CodeIgniter 4.3.8 升级指南:项目文件合并与 Controller Filters `except` 语义修复详解

原创2026-10-11 10:22:17267 阅读
文章标签:后端Web框架

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 行),相关链路如下:

  1. processGlobals() 遍历 $this->config->globals['before'] / ['after'] 中的每个别名,当配置为数组且含有 except 键时,取出排除规则并调用 checkExcept()(第 686-691 行)判断当前 URI 是否命中排除列表,命中则丢弃该过滤器。
  2. checkExcept()(第 884-897 行)是本次语义修复的关键实现:
    • $paths === [] 时直接返回 false,即"空数组不匹配任何路径",因此过滤器不会被排除——对应新语义 ['except' => []] 表示排除空;
    • 字符串形式的 $paths 会被包装成单元素数组后进入 checkPseudoRegex()。
  3. 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:

  1. 检索 $globals 数组中所有 except 键(before / after 两个分组都要检查),确认没有使用 [] 或 '' 作为排除值来"禁用"某个全局过滤器;
  2. 若确实需要让某过滤器对所有请求生效,直接删除其 except 键,或显式写成 ['except' => []];
  3. 若只想放行首页(baseURL),写成 <a href="https://link.gitcode.com/i/83831c6a32e299c8d30eaf2066c6632d" target="_blank">'except' => ''] 即可;想放行特定路径段则使用通配符,例如 ['except' => ['api/*']](完整示例见官方过滤器文档 [filters.rst 中 "Except for a Few URIs" 一节,以及示例文件 filters/006.php);
  4. 利用 * 通配符匹配任意字符、用数组形式声明多个排除路径,这两类既有能力不受本次修复影响。

升级验证与回归测试

完成版本更新与 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 数据集中都有完整佐证。升级后务必对照本文的对照表审查自身过滤器配置,即可平滑完成本次版本迁移。

登录后查看全文
CodeIgniter4