如何将CakePHP 1.x版本项目升级到CakePHP 4.x版本？

升级前准备 #

• 对现有1.x项目做全量代码备份，同时导出所有生产环境数据库冷备文件，避免升级失败导致数据丢失
• 搭建独立的本地升级测试环境，禁止直接在生产/正式测试环境修改代码
• 梳理现有1.x项目的所有自定义逻辑：包括自研组件、插件、第三方依赖、业务规则配置、自定义路由、权限逻辑、定时任务，逐一统计避免遗漏
• 执行现有项目的所有自动化测试用例（如有），记录正常运行的功能基准；无自动化测试的需整理核心功能测试用例清单

提示：跨3个大版本升级禁止直接跳转，必须分阶段逐版本升级，每阶段升级完成都要做完整的功能验证后再进入下一阶段

阶段1：1.x 升级到 2.x #

• 调整目录结构：将app/目录下的配置文件、控制器、模型、视图层级对应调整到2.x的规范
• 替换所有废弃API：例如1.x中Model::find()的废弃参数、Helper调用方式、Component加载逻辑都要对应调整为2.x支持的写法
• 调整数据库操作逻辑：替换1.x中废弃的SQL拼接方法，改为2.x支持的参数绑定写法
• 完成后跑通所有核心功能测试，确认2.x版本运行无异常

阶段2：2.x 升级到 3.x #

• 新增命名空间声明：3.x开始引入PHP命名空间规范，所有控制器、模型、组件都需要加上对应命名空间
• 重构ORM层：3.x的ORM做了完全重构，原2.x的Model类要拆分为Table和Entity两层结构，原有关联查询、回调方法都要对应调整
• 替换路由配置：3.x的路由语法完全变更，原Router::connect()写法要替换为新的路由定义规则
• 调整视图层：3.x的视图模板语法、Helper调用方式有明显调整，所有.ctp模板文件需要逐一排查修改
• 升级所有插件：将兼容2.x的第三方插件替换为对应3.x的兼容版本，自研插件同步重构适配3.x规范
• 完成后跑通全量功能测试，确认3.x版本稳定运行

阶段3：3.x 升级到 4.x #

• 先升级基础环境：4.x最低要求PHP 7.2，推荐升级到PHP 7.4及以上版本
• 补全类型声明：4.x要求所有方法的参数、返回值都加上对应类型声明，不符合规范的代码需要逐一修改
• 替换4.x废弃API：例如3.x的$request->param()方法替换为$request->getParam()，$response->body()替换为对应新方法，所有废弃的组件、Helper也要同步替换
• 调整配置文件：4.x的配置文件从原PHP数组返回格式，调整为使用Configure::write()或者.env环境变量配置的规范，对应修改app.php等核心配置文件
• 重构认证授权逻辑：4.x弃用了原AuthComponent，改为独立的Authentication和Authorization插件，原有权限逻辑需要对应重构适配
• 升级所有依赖到4.x兼容版本，排查自研代码的PHP 7/8兼容问题，移除所有PHP废弃语法
• 完成后跑通全量功能测试，确认4.x版本所有功能正常运行

升级后验证上线 #

• 执行全量功能测试，覆盖接口、前端页面、定时任务、第三方对接功能的全链路
• 做性能压测，对比升级前后的接口响应速度、内存占用情况，排查优化性能瓶颈
• 小流量灰度上线，先切10%流量到新版本，观察运行日志、错误率，确认无异常后逐步全量上线
• 上线后持续监控至少72小时，收集报错信息及时修复

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