Timber 2.0 升级指南：全面解析重大变更与迁移方案

Timber 2.0 升级指南：全面解析重大变更与迁移方案

timber Create WordPress themes with beautiful OOP code and the Twig Template Engine 项目地址: https://gitcode.com/gh_mirrors/timb/timber

前言

作为 WordPress 生态中广受欢迎的模板引擎，Timber 2.0 版本带来了多项重大改进。本文将深入剖析这些变更，帮助开发者顺利完成升级迁移工作。

核心要求变更

Timber 2.0 对运行环境提出了更高要求：

• PHP 版本：必须 ≥ 7.4
• WordPress 版本：必须 ≥ 5.3（因使用了 WP 5.3 的日期时间改进特性）
• Twig 版本：必须 ≥ 2.15.3

安装方式调整

Timber 2.0 起不再提供插件形式的安装包，必须通过 Composer 进行依赖管理。这一变化使得版本管理更加规范，也便于与其他 PHP 项目集成。

初始化方式变更

旧版通过实例化 Timber\Timber 类来初始化，现在改为静态方法调用：

// 旧方式（已废弃）
new Timber\Timber();

// 新方式
Timber\Timber::init();

特别提醒：初始化方法不再返回任何值，请避免使用全局变量接收返回值。

废弃功能移除

路由系统

路由功能已完全移除，建议开发者：

1. 使用 WordPress 原生路由功能
2. 或集成专业路由库如 upstatement/routes

Twig 缓存扩展

原 twig/cache-extension 已被废弃，推荐迁移至 twig/cache-extra。临时解决方案：

composer require twig/cache-extension

并在配置中启用：

add_filter('timber/cache/enable_extension', '__return_true');

Request 类

Timber\Request 类被移除，如需请求处理功能，可集成专业库如：

• Nyholm/psr7
• guzzle/psr7
• laminas/laminas-diactoros

示例集成代码：

add_filter('timber/context', function($context) {
    $psr17Factory = new \Nyholm\Psr7\Factory\Psr17Factory();
    $creator = new \Nyholm\Psr7Server\ServerRequestCreator(
        $psr17Factory, $psr17Factory, $psr17Factory, $psr17Factory
    );
    $context['request'] = $creator->fromGlobals();
    return $context;
});

类命名空间规范

所有类必须使用完整命名空间：

| 旧类名 | 新类名 | |--------|--------| | TimberImage | Timber\Image | | TimberMenu | Timber\Menu | | TimberPost | Timber\Post |

唯一例外是 Timber 类别名仍保留，便于直接调用静态方法。

对象获取 API 重构

Timber 2.0 引入了工厂模式，统一了对象获取方式：

文章相关

• 获取单篇文章：Timber::get_post()
• 获取文章集合：Timber::get_posts()

变更要点：

1. 不再支持 new Timber\Post()
2. 查询参数必须使用数组形式
3. 未找到文章时返回 null 而非 false

分类项相关

• 获取单个分类项：Timber::get_term()
• 获取分类项集合：Timber::get_terms()

同样不再支持直接实例化 Timber\Term。

性能优化特性

延迟加载机制

文章集合现在采用延迟加载策略，只有实际访问时才会从数据库获取数据，这对大型站点性能有显著提升。

序列化支持

增强了文章数据的 JSON 序列化能力，便于前端 JavaScript 使用：

$post_data = json_encode(Timber::get_post(123));

插件兼容性改进

通过重构 setup() 和 teardown() 方法，Timber 2.0 更好地兼容了各类 WordPress 插件，特别是在循环处理方面。

升级检查清单

1. 确认环境满足新版本要求
2. 将插件安装方式切换为 Composer
3. 更新所有类引用为命名空间形式
4. 替换所有直接实例化为工厂方法调用
5. 检查并替换废弃的功能调用
6. 测试关键功能点是否正常

结语

Timber 2.0 通过架构重构带来了更好的性能、稳定性和扩展性。虽然升级需要一定工作量，但这些改进将为项目长期发展奠定坚实基础。建议开发者在测试环境中充分验证后再部署到生产环境。

timber Create WordPress themes with beautiful OOP code and the Twig Template Engine 项目地址: https://gitcode.com/gh_mirrors/timb/timber