Pimcore升级到V11前的准备工作指南

Pimcore升级到V11前的准备工作指南

pimcore Open Source Data & Experience Management Platform (PIM, MDM, CDP, DAM, DXP/CMS & Digital Commerce) 项目地址: https://gitcode.com/gh_mirrors/pi/pimcore

前言

Pimcore作为一款强大的开源数字体验平台，其V11版本带来了许多重大改进和变化。在正式升级前，开发者需要完成一系列准备工作以确保系统平稳过渡。本文将详细介绍从Pimcore 10.6升级到V11所需的关键步骤和注意事项。

基础环境准备

升级到Pimcore 10.6

升级V11前，必须确保当前系统运行在Pimcore 10.6.x版本上。如果使用的是更早版本，请先完成到10.6的升级。

模板引擎迁移

PHP模板转Twig模板

Pimcore 11将不再支持PHP模板引擎，所有PHP模板必须迁移到Twig格式。这一变化适用于所有用户，包括企业版客户。

迁移建议：

1. 使用正则表达式批量替换常见模式，例如将{% extends ':Layout:default.html.twig' %}改为{% extends 'Layout/default.html.twig' %}
2. 对于复杂模板，建议在IDE中手动修改而非批量处理
3. 特别注意模板中的逻辑控制和变量输出语法差异

代码适配与改造

类型提示增强

Pimcore 11强化了类型系统，要求所有扩展Pimcore核心类的自定义类必须添加返回类型提示：

1. 检查所有继承Pimcore类或实现Pimcore接口的自定义类
2. 根据方法注释添加明确的返回类型声明
3. 可使用Symfony提供的patch-type-declarations工具辅助检查

JavaScript现代化改造

事件监听器替换插件系统：

// 旧版插件写法
pimcore.plugin.MyTestBundle = Class.create(pimcore.plugin.admin, {
    initialize: function() {
        pimcore.plugin.broker.registerPlugin(this);
    },
    preSaveObject: function(object) {
        // 业务逻辑
    }
});

// 新版事件监听写法
document.addEventListener(pimcore.events.preSaveObject, (e) => {
    // 通过e.detail访问事件数据
});

其他JS改造：

• 使用t()替代已废弃的ts()翻译函数
• 移除pimcore.helpers.addCsrfTokenToUrl调用

数据库层改造

Pimcore 11全面采用Doctrine DBAL接口：

1. 替换所有Pimcore\Db\ConnectionInterface为Doctrine\DBAL\Driver\Connection
2. 方法对应关系：
   • query() → executeQuery()
   • fetchRow() → fetchAssociative()
   • 使用Pimcore\Db\Helper类提供的新方法替代旧方法

电子商务模块调整

使用ElasticSearch的商户需要升级到ElasticSearch8兼容实现。

配置与安全更新

安全认证系统升级

1. 在security.yaml中启用新认证器：

security:
    enable_authenticator_manager: true

主要变化：

• 密码哈希工厂替代编码器工厂
• 登录限流替代暴力攻击保护
• HTTP认证器替代Guard认证器

配置存储方式变更

弃用环境变量直接配置，改为Symfony配置方式：

pimcore:
    config_location:
        image_thumbnails:
            write_target:
                type: 'symfony-config'
                options:
                    directory: '/path/to/config'

数据迁移与处理

执行数据库迁移

升级后必须运行：

bin/console doctrine:migrations:migrate

可在composer.json中添加自动执行：

"post-update-cmd": [
    "./bin/console doctrine:migrations:migrate"
]

对象属性前缀迁移

Pimcore 11将移除系统属性中的o_前缀，需要提前迁移：

1. 准备迁移脚本处理版本数据和回收站数据
2. 测试迁移过程确保数据完整性

其他重要注意事项

1. Web2Print模块：用Chrome处理器替换已废弃的HeadlessChrome
2. 配置变更：移除pimcore.assets.image.focal_point_detection配置
3. 兼容性桥接：添加pimcore/compatibility-bridge-v10包保持向后兼容
4. 类定义文件：运行特定迁移确保类定义最新：

bin/console doctrine:migration:exec 'Pimcore\Bundle\CoreBundle\Migrations\Version20230508121105'

升级检查清单

1. [ ] 确认当前版本为10.6.x
2. [ ] 完成PHP到Twig模板迁移
3. [ ] 添加所有必要的返回类型提示
4. [ ] 改造JavaScript代码
5. [ ] 更新数据库相关代码
6. [ ] 调整安全配置
7. [ ] 更新系统配置方式
8. [ ] 执行数据迁移脚本
9. [ ] 处理对象属性前缀
10. [ ] 检查所有其他注意事项

通过系统性地完成这些准备工作，可以确保Pimcore系统顺利升级到V11版本，并充分利用新版本带来的性能改进和功能增强。建议在正式升级前，在测试环境完整验证所有变更。

pimcore Open Source Data & Experience Management Platform (PIM, MDM, CDP, DAM, DXP/CMS & Digital Commerce) 项目地址: https://gitcode.com/gh_mirrors/pi/pimcore