CodeIgniter 4 从 4.2.11 升级到 4.2.12:项目文件核对、修复项解析与升级实操指南
CodeIgniter 4 从 4.2.11 升级到 4.2.12:项目文件核对、修复项解析与升级实操指南
CodeIgniter 4 的 4.2.12 是一个以修复缺陷为主的小版本(发布于 2023 年 1 月 9 日),其官方升级说明的核心结论是:该版本未改动任何项目空间(project space)中的可执行代码,因此升级动作本身非常轻量。本文围绕官方升级文档 upgrade_4212.rst 展开,完整梳理三种安装方式的升级流程、项目文件变更清单,并结合当前仓库源码逐一解析 4.2.12 修复的四个缺陷(CLI 下 getIPAddress() 报错、link_tag() 缺少 RSS type、migrate:status 文件名显示错误、useAutoIncrement 为 false 时 Model::save() 保存对象报错),让读者既能照单完成升级,也能理解每个修复的底层原理。
升级前:确认当前版本与阅读对应升级说明
在动手升级之前,请先确认你当前运行的 CodeIgniter 4 版本。官方升级总览文档 upgrading.rst 给出了两种简便的版本确认方法:
- 查看 Debug Toolbar(调试工具栏) 中显示的信息;
- 在代码中直接输出常量
\CodeIgniter\CodeIgniter::CI_VERSION,例如:
echo \CodeIgniter\CodeIgniter::CI_VERSION;
确认版本后,请阅读与当前版本对应的升级说明。如果你正从 4.2.11 升级到 4.2.12,则本文档正是你需要的升级依据;同时建议参阅 backward_compatibility_notes.rst 了解向后兼容性说明。
三种安装方式对应的升级入口
升级说明中提到了三种安装方式,每种方式都有各自对应的升级指南,请按你的实际安装方式选择入口:
| 安装方式 | 升级指南 |
|---|---|
| Composer 安装 App Starter(应用启动模板) | installing_composer.rst 中的应用启动模板升级章节 |
| Composer 安装(向已有项目添加 CodeIgniter4) | installing_composer.rst 中的向已有项目添加 CodeIgniter4 升级章节 |
| 手动安装 | installing_manual.rst 中的手动安装升级章节 |
升级操作的核心方法:对比项目空间文件
官方升级说明反复强调“项目空间(project space)”的概念。所谓项目空间,是指位于应用根目录下的 app/、public/、writable/ 等由你直接维护的目录。执行升级时,你需要将原始框架文件与你自己项目中的同名文件进行对比,把框架侧的改动同步过来。原始文件的获取途径有两个:
- Composer 安装:位于
vendor/codeigniter4/framework目录中; - 手动安装:位于官方发布的 ZIP 压缩包中。
例如,原始的应用配置 app/Config/App.php 在 Composer 安装方式下位于 vendor/codeigniter4/framework/app/Config/App.php。官方推荐的两种对比策略为:
- 逐行对比后,把框架侧的新改动手动合并进你的文件;
- 直接使用框架侧的新文件替换旧文件,然后把你此前自行添加的自定义配置行重新补回去。
4.2.12 项目文件变更清单与核对要点
升级说明明确写道:Version 4.2.12 did not alter any executable code in project files(4.2.12 未改动项目文件中任何可执行代码)。这意味着本次升级不会带来行为变化,你的项目文件理论上无需改动即可平滑升级。
以下是该版本中收到变更的全部项目空间文件清单(许多变更仅是注释或格式调整,不影响运行时行为):
app/Config/Cache.phpapp/Config/Migrations.phpapp/Controllers/BaseController.phpcomposer.json
不过,官方说明中这句“全部变更”指的是项目空间内收到改动的文件。实际上框架侧的修复代码位于 system/ 目录(详见下文第三节),升级后由框架本身提供,项目空间文件只是这次版本迭代中同样被触碰到的文件。因此,升级时依然建议按上一节的方法对这四个文件做一次差异核对,确认没有遗漏框架侧同步过来的注释、格式或默认值调整。
下面结合当前仓库中的同名文件,看看这四个项目空间文件的当前形态,作为核对基准:
app/Config/Cache.php:当前仓库中的缓存配置包含handler(默认'file')、backupHandler(默认'dummy')、prefix、ttl(默认 60 秒)、reservedCharacters、file、memcached、redis、validHandlers、cacheQueryString、cacheStatusCodes等属性。核对时重点确认你自己的自定义 handler、前缀与 TTL 设置没有被覆盖。app/Config/Migrations.php:当前仓库中的迁移配置包含enabled(默认true)、table(默认'migrations')、timestampFormat(默认'Y-m-d-His_')与lock(默认false)。其中timestampFormat支持的格式为YmdHis_、Y-m-d-His_、Y_m_d_His_三种,与本次修复的migrate:status文件名显示问题直接相关(详见下文)。app/Controllers/BaseController.php:应用控制器基类,本次变更不涉及可执行逻辑。composer.json:版本号与依赖声明文件的例行更新。
4.2.12 修复内容详解:四个缺陷的源码级解析
根据 v4.2.12.rst 与 CHANGELOG_4.2.md 的记录,4.2.12 共修复了四个缺陷。下面结合当前仓库源码逐一说明修复背景与影响。
1. 修复 CLI 环境下 Request::getIPAddress() 报错
问题背景:在 CLI(命令行)环境下,PHP 的 $_SERVER['REMOTE_ADDR'] 通常不存在,这会导致 getIPAddress() 在取 IP 时出错。
修复后的源码逻辑(见 system/HTTP/RequestTrait.php):
$this->ipAddress = $this->getServer('REMOTE_ADDR');
// If this is a CLI request, $this->ipAddress is null.
if ($this->ipAddress === null) {
return $this->ipAddress = '0.0.0.0';
}
也就是说,当请求来自 CLI 时,REMOTE_ADDR 取值为 null,修复后统一返回 '0.0.0.0' 作为占位 IP,避免抛出异常。完整方法还包含代理 IP(Config\App::$proxyIPs)解析与 valid_ip 校验,最终通过校验则返回真实 IP,否则同样回退为 '0.0.0.0'。这一修复对在 CLI 下运行定时任务、队列消费者或 Spark 命令时调用 IP 相关逻辑的场景尤为重要。
2. 修复 link_tag() 缺少 type="application/rss+xml" 属性
问题背景:link_tag() 是 HTML 辅助函数(见 system/Helpers/html_helper.php),用于生成 <link> 标签。此前生成 RSS 订阅链接时不会自动带上 type="application/rss+xml",导致部分订阅器无法正确识别。
修复思路:link_tag() 生成属性的核心逻辑是:
$attributes['rel'] = $rel;
if ($type !== '' && $rel !== 'canonical' && $hreflang === '' && ! ($rel === 'alternate' && $media !== '')) {
$attributes['type'] = $type;
}
修复后,当 rel 为 alternate 且用于 RSS 时,type 属性会被正确输出。典型用法:
echo link_tag([
'rel' => 'alternate',
'type' => 'application/rss+xml',
'href' => 'rss.xml',
]);
// 输出:<link href="..." rel="alternate" type="application/rss+xml" />
3. 修复 spark migrate:status 在 Y_m_d_His_ 时间戳格式下显示错误文件名
问题背景:app/Config/Migrations.php 中的 timestampFormat 支持 YmdHis_、Y-m-d-His_、Y_m_d_His_ 三种格式。当项目使用 Y_m_d_His_ 这种带下划线的格式时,spark migrate:status 命令此前会解析出错误的文件名。
修复逻辑:在 system/Commands/Database/MigrateStatus.php 中,对迁移文件名的提取进行了修正:
$migrations[$uid]->name = mb_substr($migration->name, (int) mb_strpos($migration->name, $uid . '_'));
该命令会输出包含命名空间(namespace)、版本(version)、文件名(filename)、分组(group)、执行时间(on)与批次(batch)的表格,文件名列正是本次修复的对象。如果你在项目中使用 Y_m_d_His_ 时间戳格式生成迁移文件,升级到 4.2.12 后 php spark migrate:status 才能正确显示迁移文件名。
4. 修复 useAutoIncrement 为 false 时 Model::save() 保存对象报错
问题背景:当模型将 $useAutoIncrement 设置为 false(即主键不是自增整数,而是由业务逻辑手动指定的字符串主键)时,Model::save() 在保存对象(object)形态的数据时会报错。
修复逻辑:核心修复位于 system/Model.php 的 shouldUpdate() 方法:
if ($this->useAutoIncrement === true) {
return true;
}
// When useAutoIncrement feature is disabled, check
// in the database if given record already exists
return $this->where($this->primaryKey, $this->getIdValue($row))->countAllResults() === 1;
当 useAutoIncrement 为 false 时,save() 需要查询数据库判断该主键是否已存在,以决定执行插入还是更新;修复确保了对对象形态数据的正确判断。同时,system/Model.php 的 doProtectFieldsForInsert() 在 useAutoIncrement === false 时会保留手动指定的主键字段,使其不会被 allowedFields 过滤掉。典型场景是使用 UUID、业务编号等非自增主键的模型,例如:
class Book extends Model
{
protected $table = 'books';
protected $primaryKey = 'isbn';
protected $useAutoIncrement = false;
protected $allowedFields = ['isbn', 'title', 'author'];
}
升级到 4.2.12 后,对这种模型调用 $bookModel->save($bookObject) 将不再报错。
升级完成后:验证与常见检查
完成升级后,建议做以下验证:
- 确认版本号:再次输出
\CodeIgniter\CodeIgniter::CI_VERSION,应返回4.2.12;或通过 Debug Toolbar 核对。 - 回归测试受影响功能:重点验证 CLI 命令中涉及 IP 的代码、RSS 订阅链接的渲染、
php spark migrate:status的文件名列显示,以及非自增主键模型的save()操作。 - 核对配置差异:如果采用“整文件替换 + 补回自定义配置”的策略,务必检查 app/Config/Cache.php 与 app/Config/Migrations.php 中的自定义项是否完整保留。
小结:一次轻量、无破坏性的升级
从 4.2.11 升级到 4.2.12 是一次典型的“缺陷修复型”小版本升级:项目空间内无任何可执行代码变更,框架侧修复集中在 Request::getIPAddress()、link_tag()、spark migrate:status 与 Model::save() 四处。升级动作本身以“对比项目文件 + 同步框架新代码”为主,不会引入破坏性变更,可放心在维护窗口内完成。若你的项目恰好命中上述四个缺陷场景(CLI 应用、RSS 订阅、Y_m_d_His_ 迁移格式、非自增主键模型),本次升级的收益将非常直接。