调用Timber自定义子类方法后，Programme对象变为WP_Post的原因排查

我正在使用Timber框架，自定义了继承自Timber\Post的Programme类。遇到异常问题：调用该类方法后，Programme对象会降级为普通WP_Post对象。

相关代码 #

single.php代码 #

$context = Timber::context();

/** @var Programme $post */
$post = Timber::get_post();

$context['post'] = $post;

$context['header'] = [
    'title' => $post->meta('programme_page_header_title') ?: $post->post_title,
    'media' => $post->meta('programme_page_header_media'),
    'date' => $post->get_session_range(), // <-- 调用此方法后，$post变为WP_Post
];

$context['content'] = [
    'items' => $post->meta('programme_content_content'),
    'artists' => $post->meta('programme_content_artists'),
];

自定义Programme类代码 #

use Timber\Post as TimberPost;

class Programme extends TimberPost
{
    public function get_session_range()
    {
        /** @var Session[] */
        $sessions = $this->meta('programme_general_connected_sessions');

        $earliestDate = null;
        $latestDate = null;

        foreach ($sessions as $session) {
            $date = $session->general_date_object(); // <-- 疑似问题行？
            $date = null;

            if ($earliestDate === null || $date < $earliestDate) {
                $earliestDate = $date;
            }

            if ($latestDate === null || $date > $latestDate) {
                $latestDate = $date;
            }
        }

        return ['earliest' => $earliestDate, 'latest' => $latestDate];
    }
}

Session类代码 #

class Session extends Timber\Post
{
    public function general_date_object(): DateTimeImmutable
    {
        return $this->meta('session_general_date');
    }

    // 其他方法已省略...
}

调用get_session_range()方法后，上下文中原有的$post对象不再是Programme实例，而是WP_Post实例。

我的怀疑点：

• programme_general_connected_sessions字段（由ACF或类似工具返回）可能返回原始WP_Post对象或数字文章ID
• 可能未正确配置关联文章类型的类映射
• 使用的Timber版本为2.3.2

分析与解答 #

核心原因 #

问题出在Timber的meta()方法内部的对象复用机制，以及未正确配置自定义Post类型的类映射：

1. ACF关联字段的返回值处理：当通过$this->meta('programme_general_connected_sessions')获取关联的Session时，如果ACF返回原始WP_Post对象，Timber处理这些对象时会复用WordPress全局$post变量容器，导致原本的Programme实例被覆盖成当前遍历的WP_Post（Session对应的原始对象）。

2. 缺少自定义Post类型的类映射：即使ACF返回ID，Timber默认会将其转换成Timber\Post实例而非自定义的Session类。强制将这些实例当成Session调用方法时，会触发内部错误，间接导致原始Programme对象状态异常。

解决方案 #

1. 配置Timber的Post类型类映射

在主题functions.php中添加类映射，让Timber自动将指定Post类型转换为自定义类：

add_filter('timber/post/classmap', function($classmap) {
    $classmap['programme'] = 'Programme'; // 替换为Programme对应的Post类型slug
    $classmap['session'] = 'Session';     // 替换为Session对应的Post类型slug
    return $classmap;
});

2. 确保ACF关联字段返回ID而非对象

在ACF字段设置中，将programme_general_connected_sessions的返回格式设为"Post ID"，Timber会通过ID正确实例化Session类，避免直接操作原始WP_Post导致的全局变量污染。

3. 手动转换关联对象（备选方案）

若无法修改ACF设置，在get_session_range()方法中手动将返回对象转换为Session实例：

public function get_session_range()
{
    $session_items = $this->meta('programme_general_connected_sessions');
    // 统一转换为ID数组
    $session_ids = array_map(function($item) {
        return is_object($item) ? $item->ID : $item;
    }, $session_items);

    /** @var Session[] */
    $sessions = array_map(function($id) {
        return Timber::get_post($id); // 通过ID获取会自动应用类映射
    }, $session_ids);

    // 后续日期计算逻辑不变...
}

4. 临时修复：避免全局$post变量污染

遍历关联对象前保存当前$post实例，遍历结束后恢复：

public function get_session_range()
{
    global $post;
    $original_post = $post; // 保存原始Programme实例

    /** @var Session[] */
    $sessions = $this->meta('programme_general_connected_sessions');

    $earliestDate = null;
    $latestDate = null;

    foreach ($sessions as $session) {
        $date = $session->general_date_object();
        // 后续日期计算逻辑不变...
    }

    $post = $original_post; // 恢复原始Programme实例
    return ['earliest' => $earliestDate, 'latest' => $latestDate];
}

内容的提问来源于stack exchange，提问作者Joren Rothman