CodeIgniter 4 从 4.5.1 升级到 4.5.2:项目空间文件变更清单与三种安装方式实操指南
CodeIgniter 4 从 4.5.1 升级到 4.5.2:项目空间文件变更清单与三种安装方式实操指南
本篇指南以 CodeIgniter 4 官方升级文档 upgrade_452.rst 为主体,完整梳理从 4.5.1 升级到 4.5.2 的全部要点:三种安装方式各自的升级命令、项目空间(Project Space)中需要人工合并的 10 个变更文件及其真实作用,以及 4.5.2 版本修复的关键缺陷(依据 CHANGELOG_4.5.md)。读完后,你可以根据自己的安装方式完成一次无遗漏、可验证的 4.5.2 升级。
一、升级前:先确认当前版本号
在进行任何升级操作之前,需要确认项目当前运行的框架版本。官方升级总览 upgrading.rst 给出了两种方法:
- 在浏览器中打开 Debug Toolbar(调试工具栏),查看框架版本信息;
- 在代码中直接输出框架版本常量:
echo \CodeIgniter\CodeIgniter::CI_VERSION;
确认当前版本为 4.5.1 后,即可按下文对应你安装方式的操作步骤进行升级。
二、按安装方式执行升级
官方文档 upgrade_452.rst 明确指出:请参考与你的安装方式相对应的升级说明。CodeIgniter 官方维护三种安装方式,升级路径各不相同。
1. Composer App Starter 安装(推荐方式)
如果你是通过官方 App Starter 模板(composer create-project codeigniter4/appstarter)创建的项目,升级步骤如下。
在项目根目录执行:
composer update
执行完毕后,阅读 升级指南 与 更新日志,重点检查 Breaking Changes 与 Enhancements 是否影响你的代码。
升级到指定版本(锁定版本号)
如果你希望从 4.5.1 精确升级到 4.5.2(例如 4.5.3 已经发布,但你暂时不想跟进),可以打开项目根目录的 composer.json,在 require 中固定框架版本:
"require": {
...
"codeigniter4/framework": "4.5.2"
}
然后运行 composer update。
注意:一旦在
composer.json中使用固定版本号(如"codeigniter4/framework": "4.5.2"),composer update将不会把框架升级到最新版本,除非你修改版本约束。这是官方文档明确提醒的要点。
优点:安装简单、易于更新。 代价:更新后仍需检查项目空间(root、app、public、writable)中的文件变更并手动合并。
2. 通过 Composer 向现有项目添加 CodeIgniter 4
如果你是在已有项目中引入 CodeIgniter 4(而非使用 App Starter),升级方式同样基于 Composer:
composer update
初次接入时使用:
composer require codeigniter4/framework
并需要完成三步初始化:
- 将
vendor/codeigniter4/framework中的app、public、tests、writable文件夹复制到项目根目录; - 复制
env、phpunit.dist.xml、spark文件到项目根目录; - 修改
app/Config/Paths.php中的$systemDirectory属性指向 vendor 目录,例如__DIR__ . '/../../vendor/codeigniter4/framework/system'。
重要:生产环境部署时,务必执行
composer install --no-dev,移除仅开发所需的 Composer 包,可显著减小 vendor 目录体积。
3. 手动安装(不使用 Composer)
手动安装方式下,升级方法最为直接:下载框架新副本,然后替换 system 文件夹。
官方明确警告:应用代码写在 app 文件夹中,public 文件夹是公开的文档根目录,绝对不要修改 system 文件夹内的任何内容。替换时只动 system,项目空间(root、app、public、tests、writable)中的变更需要你自己逐个检查并合并。
三、核心章节:项目空间(Project Space)文件变更清单
这是 upgrade_452.rst 中最关键的内容,也是升级时最容易遗漏的部分。
什么是"项目空间"? CodeIgniter 将项目目录划分为两类作用域:
- system 作用域:框架核心代码,位于
system/或vendor/codeigniter4/framework/system,升级时会被自动替换; - 项目空间:项目根目录下的
root、app、public、writable目录,这些文件不在 system 作用域内,升级时不会自动变更,必须人工干预。
官方文档强调,Packagist 上存在一些第三方 CodeIgniter 模块(搜索关键词 codeigniter4 updates)可以辅助合并项目空间的变更,但默认情况下,这些变更需要你自行处理。
4.5.1 → 4.5.2 版本中,项目空间收到更新的完整文件清单如下(其中许多是注释或格式调整,不影响运行时行为,但建议逐一核对):
- app/Config/DocTypes.php
- app/Config/Exceptions.php
- preload.php
- spark
- writable/.htaccess
- writable/cache/index.html
- writable/debugbar/index.html
- writable/index.html
- writable/logs/index.html
- writable/session/index.html
下面结合当前仓库中的真实源码,逐个说明这些文件的用途与升级时的关注点。
1. app/Config/DocTypes.php —— 文档类型(DOCTYPE)配置
该文件定义了框架在生成 HTML 时可以使用的全部文档类型声明,供视图层引用。当前仓库中的实现见 app/Config/DocTypes.php,核心结构为:
<?php
namespace Config;
class DocTypes
{
/**
* List of valid document types.
*
* @var array<string, string>
*/
public array $list = [
'xhtml11' => '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">',
'xhtml1-strict' => '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">',
// ... 其余 XHTML / HTML / MathML / SVG 文档类型声明
'html5' => '<!DOCTYPE html>',
'xhtml-rdfa-2' => '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.1//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-2.dtd">',
];
/**
* Whether to remove the solidus (`/`) character for void HTML elements (e.g. `<input>`)
* for HTML5 compatibility.
*
* Set to:
* `true` - to be HTML5 compatible
* `false` - to be XHTML compatible
*/
public bool $html5 = true;
}
该文件共注册了 19 种文档类型(xhtml11、xhtml1-strict、html5、mathml1、svg11 等),并包含一个布尔配置 $html5:设为 true 时按 HTML5 规范移除空元素(void element)的结尾斜杠(如 <input>),设为 false 时保持 XHTML 兼容。如果你从未自定义过此文件,可以直接用新版本覆盖;如果有自定义条目,请合并保留。
2. app/Config/Exceptions.php —— 异常处理配置
该文件控制框架的异常处理行为,是升级时需要重点核对的文件之一。当前仓库中的实现见 app/Config/Exceptions.php,继承自 CodeIgniter\Config\BaseConfig,包含以下关键配置项:
| 配置项 | 类型 | 默认值 | 作用 |
|---|---|---|---|
$log |
bool |
true |
是否通过 Services::Log 记录异常 |
$ignoreCodes |
array |
[404] |
无需记录日志的 HTTP 状态码,默认仅忽略 404 |
$errorViewPath |
string |
APPPATH.'Views/errors' |
存放 cli 与 html 两个错误视图目录的路径 |
$sensitiveDataInTrace |
array |
[] |
调试堆栈中需要隐藏的敏感数据,可用 / 表示两级路径,如 ['server', 'setup/password', 'secret_token'] |
$logDeprecations |
bool |
true |
为 true 时,DEPRECATED 错误仅记录日志而不抛出异常 |
$deprecationLogLevel |
string |
LogLevel::WARNING |
废弃警告写入的 PSR-3 日志级别,需同步调整 Config\Logger::$threshold |
handler() |
方法 | 默认处理器 | 根据 HTTP 状态码返回对应的异常处理器 |
其中 handler() 方法允许你为特定状态码注入自定义异常处理器,官方注释给出了示例:
public function handler(int $statusCode, Throwable $exception): ExceptionHandlerInterface
{
// 默认行为:使用 CodeIgniter 默认处理器
// 按 is_cli() 与响应格式决定 CLI / HTTP / AJAX 的展示方式
return new ExceptionHandler($this);
// 自定义示例:拦截特定状态码
// if (in_array($statusCode, [400, 404, 500])) {
// return new \App\Libraries\MyExceptionHandler();
// }
// if ($exception instanceof PageNotFoundException) {
// return new \App\Libraries\MyExceptionHandler();
// }
}
升级时若你未对异常处理做过自定义,可直接采用新版文件;若有自定义(如 $sensitiveDataInTrace、handler() 定制),请对照新版本合并差异。
3. preload.php —— OPcache 预加载示例
preload.php 是 4.5.2 中明确有修复的文件(changelog 记录为 fix: update preload.php for 4.5)。当前仓库根目录下的 preload.php 是一个可复制的 OPcache 预加载示例,其用途与配置方式为:
- 将文件复制到项目根目录;
- 设置类中的
$paths属性; - 在
php.ini中配置:
opcache.preload=/path/to/preload.php
文件的核心逻辑(见 preload.php):
- 通过
require __DIR__ . '/app/Config/Paths.php'加载路径配置,并定义FCPATH(指向public目录); - 定义
preload类,其中$paths数组声明了要预加载的目录(include,默认指向vendor/codeigniter4/framework/system,手动安装时需修改)以及排除清单(exclude); - 排除清单默认跳过不常用的数据库驱动(OCI8、Postgre、SQLite3、SQLSRV)、CLI/命令相关类、
system/Test/、system/Language/、视图文件等; - 构造函数调用
Boot::preload($paths)完成引导;load()方法通过RecursiveDirectoryIterator+RegexIterator遍历 PHP 文件,跳过以Test结尾的文件后逐个require_once。
需要注意:preload.php 中的调试输出代码(如 echo 'Loaded: ...')仅供调试时临时取消注释,生产环境严禁启用——预加载脚本绝不能产生任何输出。
4. spark —— CLI 命令入口
spark 是项目根目录下的命令行入口脚本(位于仓库根目录 spark),用于执行诸如 spark serve、spark migrate、spark routes 等 CLI 命令。4.5.2 的 changelog 中记录了与之相关的修复([ErrorException] Undefined array key in spark phpini:check),因此升级时建议使用新版本替换该脚本。
5. writable/ 目录下的占位与保护文件
writable 目录用于存放运行时生成的数据(日志、缓存、会话、上传文件等),其中的文件变更虽然多是占位符(index.html)或保护性文件(.htaccess),但升级时也应一并同步:
writable/.htaccess—— 保护目录不被直接列举访问;writable/cache/index.html、writable/logs/index.html、writable/session/index.html、writable/debugbar/index.html、writable/index.html—— 各子目录的占位页面,用于阻止 Web 服务器对空目录的目录列举。
这些占位文件与当前仓库中的 writable/index.html、writable/debugbar/index.html、writable/session/index.html 属于同类文件,直接覆盖即可,一般不存在冲突。
四、为什么升级:4.5.2 版本修复内容一览
根据 CHANGELOG_4.5.md(第 163 行起),v4.5.2 发布于 2024-06-10,是一个以缺陷修复为主的补丁版本,包含 15 项 Bug 修复与 1 项重构:
与模型数据转换(casting)相关的修复(本次升级重点收益):
- 修复 Model casting 可能抛出
InvalidArgumentException: Invalid parameter: nullable的问题; - 修复 Model casting 在未找到记录时触发
TypeError的问题; - 修复
Model::find()在开启 casting 时返回错误数据的问题。
查询构造器与数据库驱动修复:
- 修复 QueryBuilder 的
join()在使用BETWEEN时抛出TypeError的问题; - 修复 SQLSRV 驱动下 Query Builder 总是把
"<database>"."<schema>".附加到表名的问题; - 修复 Postgres 下缺失错误信息显示的问题。
其他关键修复:
- 更新
preload.php以适配 4.5 系列(即本文第三节第 3 项); - 修复
spark phpini:check命令中未定义数组键导致的ErrorException; - 修复不正确的 Security 异常消息;
- 修复
FileCollection伪正则匹配问题; - 修正 Email 中属性的默认值;
- 修复
CLI::promptByMultipleKeys()与prompt(); - 修复
number_to_amount()中的TypeError; - 移除
MockCache::save()中未使用的$raw参数; - 修复 App Starter 的
phpunit.xml.dist。
另外有一项重构:移除 PhpStreamWrapper::stream_open() 中未使用的路径参数。
如果你的项目使用 Model 字段类型转换(casting)、QueryBuilder 的 join() 或 Postgres/SQLSRV 驱动,4.5.2 的这些修复直接关系到线上稳定性,应尽快升级。
五、合并项目空间变更的最佳实践
升级完成后,项目空间文件的合并是决定升级成败的最后一步。官方升级总览 upgrading.rst 给出了明确方法:
- 对比原始文件:从
vendor/codeigniter4/framework(Composer 安装)或框架 ZIP 压缩包中取出原始文件,与你的项目文件逐一对比。例如原始app/Config/App.php位于vendor/codeigniter4/framework/app/Config/App.php; - 合并差异:保留你自定义的配置行,同时纳入新版本新增的配置项;
- 或整体替换后重加自定义:直接用新版文件覆盖,再把此前自定义的行重新加入。
对于本次 4.5.2 升级,建议合并顺序为:先处理 app/Config/DocTypes.php 与 app/Config/Exceptions.php(这两个文件可能有你的自定义项,合并时注意保留),再直接覆盖 preload.php、spark 及 writable/ 下的占位文件。
六、升级后的验证清单
完成上述步骤后,建议按以下顺序验证升级结果:
- 确认版本号:运行
composer show codeigniter4/framework,或通过 Debug Toolbar /\CodeIgniter\CodeIgniter::CI_VERSION确认版本为 4.5.2; - 运行测试:在项目根目录执行
phpunit(或vendor/bin/phpunit),确认既有测试全部通过,重点覆盖 Model casting、查询构造器等 4.5.2 修复涉及的场景; - 验证 CLI:执行
php spark list,确认spark脚本可正常列出命令,无 PHP 报错; - 冒烟测试:启动开发服务器(
php spark serve),访问首页与关键业务路由,确认异常处理、DOCTYPE 输出与调试工具栏正常; - 生产部署提醒:如果使用 Composer 安装方式,部署时执行
composer install --no-dev以移除开发依赖。
至此,你的项目已完成从 CodeIgniter 4.5.1 到 4.5.2 的完整升级,既享受了 15 项 Bug 修复带来的稳定性提升,也确保了项目空间文件的同步。如需了解后续版本(4.5.3 及更高版本)的升级要点,可继续查阅 upgrade_453.rst 等对应版本的官方升级文档。