CodeIgniter 4.3.8 升级指南:项目文件合并与 Controller Filters `except` 语义修复详解
CodeIgniter 4.3.8 升级指南:项目文件合并与 Controller Filters except 语义修复详解
本文是 CodeIgniter 4 从 4.3.7 升级到 4.3.8 的官方操作指南(对应仓库内 upgrade_438.rst)的完整技术解读。4.3.8 是一个以缺陷修复为主的小版本(发布于 2023 年 8 月 25 日,详见 v4.3.8 变更日志),除了常规的项目空间文件合并工作外,它还修复了一个影响面较广的 Controller Filters 全局过滤器 except 配置语义错误。读完本文,你将掌握:三种安装方式下把项目从 4.3.7 升级到 4.3.8 的具体步骤、项目空间内 composer.json 的手动合并方法,以及 except 新语义在源码与测试中的实际行为,能够据此审查并修正自己项目中的过滤器配置。
升级前必读:按安装方式选择对应说明
升级不是简单的替换文件。CodeIgniter 4 的官方升级指南要求你先根据自己项目的安装方式,阅读对应的升级说明,再执行版本更新。4.3.8 升级文档给出的三条入口分别是:
- Composer 安装(App Starter 项目):适用于通过
codeigniter4/appstarter创建的独立项目,对应 installing_composer.rst 中的 "Upgrading" 一节(该节锚点定义于第 103 行)。 - Composer 安装(为已有项目添加 CodeIgniter4):适用于把框架以 Composer 依赖方式引入现有 PHP 项目的场景,对应同一文档中的第二个升级小节(锚点位于第 263 行)。
- 手动安装:适用于直接下载框架压缩包、手动放置
system目录的场景,对应 installing_manual.rst 中的 "Upgrading" 一节(锚点位于第 38 行)。
无论采用哪种方式,官方都建议在升级前后阅读完整的 升级说明索引 与 变更日志,重点核对 Breaking Changes(破坏性变更)与 Enhancements(增强)部分,确认新版本没有引入与自身项目冲突的行为变化。
三种安装方式的升级步骤
方式一:Composer App Starter 项目升级
对于 App Starter 项目,升级非常简单——在项目根目录执行:
composer update
composer update 会把 codeigniter4/framework 更新到满足 composer.json 版本约束的最新版本。需要注意:Composer 只会更新 system(框架本体)所在的 vendor 依赖,项目空间(root、app、public、writable)内的文件不会自动被修改,因此升级后仍需按下一节内容手动检查项目文件变更。
如果你希望锁定升级到 4.3.8 这一具体版本(例如新版本 4.4.x 已发布,但你暂时不打算跟进),则需要打开项目根目录的 composer.json,把框架版本写死:
"require": {
"...": "...",
"codeigniter4/framework": "4.3.8"
}
然后再次运行 composer update。需要特别提醒:当 composer.json 中写死固定版本号(如 "4.3.8")时,后续再执行 composer update 不会自动把框架升到最新版本,版本约束的写法细节可参考 Composer 官方版本约束文档。
方式二:为已有项目添加 CodeIgniter4 的升级
如果 CodeIgniter4 是作为既有项目的 Composer 依赖引入的,升级方式与方式一相同:在项目根目录执行 composer update,或通过固定版本号 "codeigniter4/framework": "4.3.8" 锁定目标版本后更新。
该方式的优势是安装相对简单、更新便捷;代价与方式一相同——项目空间(root、app、public、writable)中的文件变更需要自己检查并合并。
方式三:手动安装升级
手动安装的项目升级方式最直接:下载一份新的框架副本,然后用新副本替换原有的 system 文件夹。替换完成后,阅读升级说明与变更日志,检查是否存在破坏性变更。
该方式"下载即运行"(Download and run),但缺点也最明显:项目空间(root、app、public、tests、writable)内的所有文件变更都需要完全手工合并,没有任何自动化辅助,建议在升级前对 app/、public/、writable/ 等目录做好版本备份或 Git 提交。
项目空间文件变更:composer.json 需手动合并
CodeIgniter 4 将框架代码区分为两个空间:system 空间(框架本体,随升级自动替换)与项目空间(root、app、public、writable,属于开发者自己的代码)。升级文档明确指出,项目空间中的文件即使收到了上游更新,也不会在你未干预的情况下被自动修改——这正是升级后最容易出现遗漏的地方。
4.3.8 升级文档列出的项目空间文件变更如下:
| 分类 | 文件 | 说明 |
|---|---|---|
| Content Changes(建议合并) | composer.json |
收到显著变更,官方推荐将更新版本合并到你的应用中 |
| All Changes(全部变更) | composer.json |
完整变更清单中的唯一文件;文档同时说明清单中许多文件变更可能只是注释或格式调整,不影响运行时行为 |
也就是说,本次 4.3.8 升级中,你需要重点关注的项目空间文件只有一个:根目录的 composer.json。合并时建议对比官方 App Starter 模板(仓库内 admin/starter/composer.json)或框架仓库根目录的 composer.json,检查依赖版本约束、autoload、scripts 等区块是否与新版保持一致。
如果项目空间文件较多、手工合并繁琐,官方文档还提到社区存在一些用于辅助合并项目空间变更的 CodeIgniter 第三方模块,可在 Packagist 上按 "codeigniter4 updates" 关键词检索(本文不展开外部站点内容,仅作提示)。
4.3.8 核心变更:Controller Filters except 语义修复
本次升级中最值得关注的实质性变更,是 Controller Filters(控制器过滤器)全局配置中 except 参数的语义修复。它属于行为层面的破坏性修复——如果你的项目恰好在全局过滤器($globals)中使用了 except,升级后某些过滤器的生效范围可能发生变化。
修复前后的行为对照
官方变更日志(v4.3.8.rst)给出的结论非常明确:
在之前的版本中,
['except' => []]或['except' => '']被理解为 "except all"(排除所有 URI,即过滤器对任何请求都不生效)。该 bug 已修复,现在:
['except' => []]表示不排除任何内容(过滤器对所有 URI 生效);['except' => '']表示仅排除 baseURL 本身(过滤器对所有非 baseURL 的 URI 生效)。
这一语义差异可以用下表直观对比(假设全局过滤器配置为 'csrf' => ['except' => $value]):
| 配置写法 | 4.3.7 及以前的行为 | 4.3.8 起的行为 |
|---|---|---|
['except' => []] |
排除所有 URI(过滤器从不生效) | 不排除任何 URI(过滤器全量生效) |
['except' => ''] |
排除所有 URI(过滤器从不生效) | 仅排除 baseURL 路径(其余 URI 均生效) |
['except' => ['api/*']] |
排除 api/* |
排除 api/*(不受影响) |
如果你的旧配置中写的是 'except' => [] 或 'except' => '',并且本意是"让过滤器对所有请求生效"或"只放行首页",那么升级到 4.3.8 后行为将符合预期;反之,如果本意是"让过滤器完全不生效",则需要在升级后主动修正配置。
源码级实现原理
要理解新语义,需要阅读框架的过滤器调度核心 system/Filters/Filters.php。全局过滤器是在 initialize() 中通过 processGlobals() 处理的(第 670-716 行),相关链路如下:
processGlobals()遍历$this->config->globals['before']/['after']中的每个别名,当配置为数组且含有except键时,取出排除规则并调用checkExcept()(第 686-691 行)判断当前 URI 是否命中排除列表,命中则丢弃该过滤器。checkExcept()(第 884-897 行)是本次语义修复的关键实现:$paths === []时直接返回false,即"空数组不匹配任何路径",因此过滤器不会被排除——对应新语义['except' => []]表示排除空;- 字符串形式的
$paths会被包装成单元素数组后进入checkPseudoRegex()。
checkPseudoRegex()(第 905-921 行)把路径模式转换为正则:先将/转义为\/,再把通配符*替换为.*,最后以#\A...\z#u全匹配当前 URI。当except为空字符串''时,模式被trim('', '/ ')清理为空串,正则为#\A\z#u,它只会匹配空 URI——而 URI 在processGlobals()入口处经过strtolower(trim($uri ?? '', '/ '))归一化,baseURL 对应的路径恰恰就是空字符串,于是"空字符串仅排除 baseURL"的语义在代码层面成立。
与之形成对照的是路径匹配(而非排除)逻辑 pathApplies()(第 861-874 行):在 $filters 的 before / after 路径匹配中,空路径('' 或 [])表示"匹配所有 URI"。匹配用空值=全匹配、排除用空值=不匹配,这两套逻辑在 4.3.8 中被明确区分开,这也是本次修复的根源所在。
测试用例验证
框架的单元测试完整覆盖了上述新语义,见 tests/system/Filters/FiltersTest.php 中 testBeforeExcept()(第 603-627 行)及其数据提供器 provideBeforeExcept()(第 632-714 行)。其中与本次修复直接相关的用例:
- empty array not exclude:URI 为
admin/foo/bar、except => [],断言foo过滤器被保留(不排除任何内容); - empty string not exclude:URI 为
admin/foo/bar、except => '',断言foo过滤器被保留(空字符串只匹配 baseURL,不影响其他路径); - empty string exclude:URI 为
''(即 baseURL 路径)、except => '',断言foo过滤器被排除(仅对 baseURL 生效)。
同时,testProcessMethodProcessGlobalsWithExcept()(第 222-253 行)验证了 except 为 ['admin/*']、['admin/*', 'foo/*']、['*']、'admin/*' 等常规写法时全局过滤器仍能正确按 URI 排除。这些测试证明:修复后 except 既支持单路径字符串,也支持多路径数组,且路径匹配仍遵循"相对 baseURL、小写、支持 * 通配符"的既有规则。
实践建议:升级后的过滤器配置审查
升级到 4.3.8 后,建议按以下步骤检查项目中的 app/Config/Filters.php:
- 检索
$globals数组中所有except键(before/after两个分组都要检查),确认没有使用[]或''作为排除值来"禁用"某个全局过滤器; - 若确实需要让某过滤器对所有请求生效,直接删除其
except键,或显式写成['except' => []]; - 若只想放行首页(baseURL),写成
<a href="https://link.gitcode.com/i/83831c6a32e299c8d30eaf2066c6632d" target="_blank">'except' => '']即可;想放行特定路径段则使用通配符,例如['except' => ['api/*']](完整示例见官方过滤器文档 [filters.rst 中 "Except for a Few URIs" 一节,以及示例文件 filters/006.php); - 利用
*通配符匹配任意字符、用数组形式声明多个排除路径,这两类既有能力不受本次修复影响。
升级验证与回归测试
完成版本更新与 composer.json 合并后,建议执行以下验证:
- 运行
composer update后确认 vendor 中框架版本已变为 4.3.8,可通过composer show codeigniter4/framework核对; - 手动安装方式则确认
system目录已整体替换为新版本,并检查system/下的关键文件(如 system/Filters/Filters.php)与本次修复对应的方法(checkExcept、checkPseudoRegex)存在; - 在开发环境对涉及全局过滤器的路由做冒烟测试,重点验证 CSRF、Honeypot、DebugToolbar 等依赖全局配置的过滤器在各类 URI 下是否按预期生效/放行;
- 若项目自建了测试套件,可参照 tests/system/Filters/FiltersTest.php 中
provideBeforeExcept的用例模式,为自身过滤器配置补充针对except语义的回归测试,防止后续版本再次回归。
小结
4.3.8 是 CodeIgniter 4 在 4.3 系列中的一个纯修复型小版本:升级动作集中在"按安装方式执行 composer update 或替换 system 目录 + 手动合并项目空间的 composer.json",真正的行为变化只有一个——全局过滤器 except 的空值语义从"排除全部"修正为"排除空 / 仅排除 baseURL"。该修复在 system/Filters/Filters.php 的 checkExcept() 实现与 tests/system/Filters/FiltersTest.php 的 provideBeforeExcept 数据集中都有完整佐证。升级后务必对照本文的对照表审查自身过滤器配置,即可平滑完成本次版本迁移。