CodeIgniter 4.0 系列完整版本演进全解:从 alpha 到 v4.0.5 的核心变更、弃用与升级指南

原创2026-10-09 16:21:461,954 阅读
文章标签:后端Web框架

CodeIgniter 4.0 系列完整版本演进全解:从 alpha 到 v4.0.5 的核心变更、弃用与升级指南

导读

本文以 CodeIgniter 4.0 官方变更日志(changelogs/CHANGELOG_4.0.md)为骨架,系统梳理该框架 4.0 大版本从 v4.0.0-alpha.1(2018-09)到 v4.0.5(2021-01)的完整演进脉络。你将掌握:v4.0.5 引入的关键弃用与 HTTP 层 PSR 重构方向、上传文件 MIME 类型检测的安全收紧策略、PHP 8 支持与主要缺陷修复清单,以及贯穿 4.0 系列的模型、路由、验证、查询构造器、会话、迁移等核心子系统的演进细节。文末结合仓库源码给出可验证的升级与迁移建议,帮助你快速定位 4.0 时代(以及向后续版本过渡时)需要注意的兼容性要点。

一、变更日志的定位与整体结构

1.1 什么是 CHANGELOG_4.0.md

changelogs/CHANGELOG_4.0.md 是 CodeIgniter 4 大版本(4.0.x)的官方逐版本变更记录,记录了从 2018 年首个 alpha 到 2021 年最后一次补丁发布的全部变更。仓库中与之并列的还有 changelogs/CHANGELOG_4.1.md 至 changelogs/CHANGELOG_4.6.md,按主版本号分文件存放,方便按版本检索。

该文件按"版本倒序"组织:最新版本 v4.0.5(2021-01-31)在最前,随后依次是 v4.0.4、v4.0.3、v4.0.2、v4.0.1、v4.0.0,以及 4.0 正式发布前的候选版与预览版:v4.0.0-rc.4、v4.0.0-rc.3、v4.0.0-rc.2b、v4.0.0-rc.2.1、v4.0.0-rc.2、v4.0.0-rc.1、v4.0.0-beta.4、v4.0.0-beta.3、v4.0.0-beta.1、v4.0.0.0-alpha.5、v4.0.0-alpha.5、v4.0.0-alpha.4、v4.0.0-alpha.3、v4.0.0-alpha.2、v4.0.0-alpha.1。

每个版本条目内部按 Implemented enhancements(增强)→ Fixed bugs(缺陷修复)→ Closed issues(关闭议题)→ Merged pull requests(合并的 PR) 的分类结构展开,每条记录均附带 GitHub issue/PR 编号与贡献者。

1.2 如何阅读这份日志

  • 关注带 "Deprecations:" 标注的区块:v4.0.5 单独用醒目区块列出弃用项,这些是升级到后续版本时最先需要处理的点;
  • 区分"修复"与"行为变更":例如 MIME 类型检测的改动虽被列为修复,但其返回值语义发生了变化,可能影响既有上传逻辑;
  • 结合 PR 编号定位代码:例如 BaseBuilder::getCompiledDelete() 的修复对应 PR #4181,可在仓库 system/Database/BaseBuilder.php 中验证其行为。

二、v4.0.5:4.0 系列的收尾与向 PSR 兼容层的过渡

v4.0.5 发布于 2021-01-31,是 4.0 系列的最后一个补丁版本。它一方面大幅修复稳定性问题,另一方面为 4.1 的 HTTP 层重构埋下伏笔。

2.1 三大弃用项:工厂模式收敛

v4.0.5 明确弃用了两处旧的工厂入口,统一收敛到 CodeIgniter\Config\Factories:

弃用对象 替代方案
CodeIgniter\Database\ModelFactory CodeIgniter\Config\Factories::models()
CodeIgniter\Config\Config CodeIgniter\Config\Factories::config()
旧 HTTP 层接口 向 PSR 兼容 HTTP 层过渡(详见 升级指南)

从当前仓库源码可以验证 Factories 的设计意图。在 system/Config/Factories.php 中,Factories 是一个 final class,通过 __callStatic() 魔术方法实现 Factories::models()、Factories::config() 等静态调用(system/Config/Factories.php#L135-L177),并维护了 $aliases(别名→FQCN 映射)、$instances(共享实例缓存)、$options(组件级配置)三张静态表:

  • 共享实例(getShared):默认复用已创建的实例,避免重复实例化开销;
  • preferApp 优先:定位类时优先在 App\ 命名空间下查找(Config 组件则特殊处理为 Config\ 命名空间,见 system/Config/Factories.php#L291-L303);
  • instanceOf 校验:可限制组件实例必须属于某一类层次,见 verifyInstanceOf()(system/Config/Factories.php#L376-L384)。

因此从 4.0.5 起,新代码应统一使用 Factories::models('UserModel') 与 Factories::config('App'),而不是继续依赖旧入口。此外,v4.0.5 中 ModelFactory 被弃用,意味着模型中实例化其他模型的方式正在向工厂收敛。

提示:变更日志内链指向 user_guide_src/source/installation/upgrade_405.rst,在仓库中该文件实际位于 user_guide_src/source/installation/upgrading.rst(由 upgrade_405 主题锚点对应),可按此路径查阅 4.0.5 的详细升级说明。

2.2 MIME 类型检测安全收紧:上传文件扩展名判定行为变更

这是 v4.0.5 中最值得注意的安全相关行为变更,直接影响所有处理上传文件的代码:

  1. Config\Mimes::guessExtensionFromType 现在仅在未给出候选扩展名时才反向搜索 $mimes 数组。也就是说,对于通常的上传文件场景,检测不再盲目做全表反查;
  2. UploadedFile::getExtension() 的兜底值由空字符串 '' 改为 $this->getClientExtension();
  3. UploadedFile::guessExtension() 的兜底值由 $this->getClientExtension() 改为空字符串 ''。

为什么是安全修复:此前 guessExtension() 在无法匹配时会回退到客户端上报的扩展名,而客户端可以通过伪造 Content-Type 强迫应用接受错误(甚至危险)的文件扩展名。调整后:

  • guessExtension() 更加保守,宁可返回 '' 也不信任客户端;
  • getExtension() 则保证总是返回一个"有用"的扩展名,但文档明确其可能不安全,建议安全敏感场景使用 guessExtension()。

从当前源码可见该语义已被固化:system/HTTP/Files/UploadedFile.php#L302-L328 中:

public function getExtension(): string
{
    $guessExtension = $this->guessExtension();

    return $guessExtension !== '' ? $guessExtension : $this->getClientExtension();
}

public function guessExtension(): string
{
    return Mimes::guessExtensionFromType($this->getMimeType(), $this->getClientExtension()) ?? '';
}

public function getClientExtension(): string
{
    return pathinfo($this->originalName, PATHINFO_EXTENSION);
}

对应地,app/Config/Mimes.php#L509-L533 中的 guessExtensionFromType() 实现验证了"先校验候选扩展名、匹配失败才反向搜索"的顺序逻辑:

public static function guessExtensionFromType(string $type, ?string $proposedExtension = null)
{
    $type = trim(strtolower($type), '. ');
    $proposedExtension = trim(strtolower($proposedExtension ?? ''));

    if (
        $proposedExtension !== ''
        && array_key_exists($proposedExtension, static::$mimes)
        && in_array($type, (array) static::$mimes[$proposedExtension], true)
    ) {
        // 检测到的 MIME 与候选扩展名匹配,直接采用
        return $proposedExtension;
    }

    // 未提供候选扩展名时才做反向搜索(该搜索对顺序敏感)
    foreach (static::$mimes as $ext => $types) {
        if (in_array($type, (array) $types, true)) {
            return $ext;
        }
    }

    return null;
}

升级注意事项:变更日志明确警告——"这些改动可能影响你的应用对文件扩展名的检测方式"。如果你的代码此前依赖 getExtension() 返回 '' 来判断未知类型,或依赖 guessExtension() 回退到客户端扩展名,升级 v4.0.5 后必须显式处理新的返回值语义。

2.3 v4.0.5 的增强与修复亮点

已实现增强(Implemented enhancements):

  • 修复模块(Modules)中的控制器路由不生效的问题(#3927);
  • CLI 的 prompt 方法支持数组形式的校验规则(#3766);
  • 校验规则支持 permit_empty、optional 参数(#3670);
  • PHP 8 支持(#3498),并配套修复了大量 PHP 8 下的兼容性问题;
  • getRoutesOptions() 在可用时返回控制器与方法信息(#3445);
  • FilterInterface 的 before() 方法补充了缺失的 response 参数(#2085);
  • 提供了集中式的 loggedInUser 方案(#2055)。

主要缺陷修复(摘录):

  • UploadedFile::store() 无法返回 null(#4183)——修复见 PR #4187,统一了返回值类型;
  • BaseBuilder::getCompiledDelete() 会真正执行查询(#4180)——PR #4181 修复,此前"编译删除语句"会误触发真实删除操作;
  • PHP 8 下"可选参数后跟必选参数"(Required parameter follows optional parameter)系列弃用告警(#4172、#4148、#4076),通过调整 IncomingRequest、DownloadResponse 等方法签名解决;
  • delete_cookie() 辅助函数失效(#4149、#3939、#3433)——与 Cookie Helper 在 4.0.4 期间的回归有关;
  • insertBatch() 未生成 createdField(#3838);
  • 视图渲染时 extract() 提取的变量覆盖了既有变量(#4108),PR #4113 将 extract 调用包裹进 IIFE 修复;
  • View 的 Parser 在模板包含 # 字符时触发 preg_replace_callback 异常(#3824)等。

三、4.0 系列的稳定性演进:v4.0.1 → v4.0.4

正式版 v4.0.0 于 2020-02-24 发布,随后 4.0.x 补丁持续修复社区反馈的问题。

3.1 v4.0.4(2020-07-15)

v4.0.4 主要修复类型系统与配置相关的缺陷:

  • CI_DEBUG 类型不正确且在严格模式下校验失败(#2975);
  • Honeypot 的 $container 未加入 env 文件(#3318);
  • DOMParser::see() 增加多字节支持(#3324);
  • 强制 HTTPS 时重定向错误(#3260);
  • 图片验证规则 is_image 存在漏洞(#3184);
  • Redis 会话处理器在 sessionExpiration 为 0 时失效(#3111);
  • Feature 测试中过滤器状态未重置(#3085、#3237)。

同时,PR #3238 为框架增加了"以编程方式调用命令"的能力,这是后续 Commands API 演进的基础。

3.2 v4.0.3(2020-05-01)

v4.0.3 是 4.0 早期一次重要的稳定性与体验修复,亮点包括:

  • 分页(Pagination)大改:新增 getTotalResults()、分组分页、makeLinks() 可选组名支持,并修复分页链接双重编码、perPage=1 时损坏等问题(PR #2899、#2901);
  • Model::delete($id) 支持字符串主键删除(PR #2894);
  • saveData 选项在视图渲染中真正生效(PR #2861);
  • 验证规则的本地化标签支持(PR #2868);
  • force_https() 修复:在输出前正确发送头部(PR #2871、#3292);
  • 语言系统增加嵌套语言定义支持(PR #2833)、模块语言合并修复(#1433);
  • 过滤器别名支持多个过滤器类(PR #2857);
  • 控制器子目录路由问题得到系统性修复。

3.3 v4.0.2 / v4.0.1(2020-02-24 / 2020-02-25)

这两个版本是正式版前后的应急修复,规模较小:

  • v4.0.2 修复 composer 依赖解析失败问题(#2613),并移除导致 appstarter 从 CLI 运行失败的多余测试类(PR #2614);
  • v4.0.1 修复文档与升级指引中的 rc 参数残留(PR #2604)、架构描述问题(#2602)。

四、v4.0.0 正式版与 RC/Beta/Alpha 阶段的关键能力定型

4.1 v4.0.0(2020-02-24)正式版

正式版聚焦收尾修复,重要条目包括:

  • $forge->dropColumn 支持数组形式的列名(#2576、PR #2578);
  • CodeIgniter\Files\File::getSize() 返回类型错误(#2476);
  • 过滤器通配符忽略默认方法的问题(#2455);
  • 尾斜杠导致重定向到根目录(#2445);
  • 新增 alpha_numeric_punct 校验规则(PR #2562);
  • 新增 is_not_unique 校验函数(PR #2392);
  • 数据库 insertIgnore 能力(PR #2446);
  • 图片库新增 convert() 与 fit() 新逻辑(PR #2113、#2150);
  • DotEnv::parse() 方法(PR #2588);
  • 调试工具栏支持深浅色主题(PR #2478)。

4.2 RC 阶段(2019-08 至 2020-02):核心架构定型

RC 阶段是 4.0 架构决策最密集的时期:

  • Entity 数据类体系(PR #2002、#1283、#1311):引入"原始值栈(original values)"以支持 hasChanged() 比较(PR #2004、#1311);
  • 模型回调(Model callbacks):PR #3252 实现模型事件回调覆盖;
  • 软删除改为 deleted_at 时间戳(PR #2051、#2053):从布尔标记迁移到时间戳/日期字段,规避多表 JOIN 时的字段歧义(#1881);
  • 会话数组处理器(PR #2014):新增 Session/ArrayHandler 用于测试环境;
  • Migrations 重构:支持按命名空间发现、数据库组追踪(PR #2137、#2065、#2303);
  • 查询构造器:新增 testMode()(PR #2269)、groupStart() 重构(PR #2270)、子查询支持(PR #2001)、HAVING 子句完善(PR #2257)、getCompiledSelect() 返回完整编译语句(PR #1640);
  • 视图:布局(Layout)渲染器引入(PR #1729)、saveData 支持(PR #181)、View Cells 缓存修复(#2821);
  • 路由:支持 {locale} 占位符、Unicode 正则路由(PR #3172)、ajax 路由选项(#2310)、HTTP 动词路由优先级修复(PR #1285)。

4.3 Beta 阶段(2019-03 至 2019-07):基础能力补全

Beta 阶段完成了大量基础设施:

  • HTML Table 类(PR #1978)、CLI::print() 同行输出(PR #1910);
  • 缓存未命中时 get() 返回 null(PR #1895、#1870);
  • WebP 图片格式支持(PR #3176、#3084);
  • 路由过滤器参数传递到 before()/after()(PR #3316);
  • 模型 findColumn() 方法(PR #1861);
  • 校验规则 equals/not_equals(PR #1952)、valid_json(PR #1187);
  • 会话 push() 方法(PR #1151);
  • 日志级别对齐 RFC 5424(PR #1178)。

4.4 Alpha 阶段(2018-09 至 2019-01):从零到一

Alpha 阶段奠定了 4.0 的整体形态,值得注意的方向性决策:

  • 自动发现(Auto-discovery)系统(PR #1215、#1665):Composer PSR-4 命名空间纳入模块自动发现,为后续模块化能力奠基;
  • 视图解析器(View Parser):支持带引号短语、非成对指令插件(#537、#547);
  • 方法伪装(Method Spoofing)(#432):表单通过隐藏字段伪装 PUT/DELETE;
  • 响应下载:DownloadResponse 与 setFileName()(PR #2129、#208);
  • 表单 CSRF 令牌:csrf_field() 与隐藏字段集成(PR #1633)、JSON POST 的 CSRF 处理(PR #2240);
  • Content Security Policy(CSP) 实现(#6)及其与调试工具栏的兼容修复(PR #1129);
  • 反向路由(Reverse Routing)(#3)与 route_to() 辅助函数;
  • 多值同名 HTTP 头支持(#16)。

五、4.0 时代的高频主题:从日志看子系统演化

5.1 模型(Model)与实体(Entity)

日志显示 4.0 系列对模型子系统投入了大量修复,常见问题集中在:

  • 验证与 save() 交互:模型插入/更新时必须尊重全部校验规则(PR #2433、#1689);
  • 时间戳字段:created_at/updated_at 自动填充的边界问题(#4038、#2737、#3469);
  • 软删除:deleted_at 时间戳、countAllResults() 尊重软删除(#1617)、JOIN 歧义(#1881);
  • 主键类型:字符串主键、非自增主键、无主键表的支持(#2835、#1602、#3134);
  • 批量操作:insertBatch/updateBatch 的转义与 createdField(#3838、#1667)。

5.2 路由与过滤器

  • 过滤器(Filters)的匹配语义从"宽松匹配"收紧为"精确匹配"(PR #2039,修复 #2038),避免意外拦截;
  • 路由组内过滤器的嵌套与多方法问题(#2390、#3733);
  • 控制器子目录、模块路由、{locale} 处理在多个版本间反复打磨(#3927、#3347、#2701)。

5.3 验证(Validation)

  • permit_empty 与 required_with/required_without 的组合行为(#2953、#1837);
  • 验证占位符(Placeholder)在错误消息中的替换(PR #2897、#2817);
  • 多文件上传验证(#2175、#2265、#3018);
  • matches 规则支持嵌套参数与标签(#946、#3492)。

5.4 数据库与查询构造器(Query Builder)

  • 绑定(binds)机制在多语句、whereIn、:= 运算符下的正确性(#2762、#1663、#2773);
  • DBPrefix 与多列 WHERE、countAllResults + groupBy 的组合(#3651、#2533);
  • getCompiledDelete() 不真正执行(PR #4181);
  • SQLite3 的 escapeChar、外键删除、表缓存问题(#3219、#1982、#3752);
  • PostgreSQL 驱动在 insertID、increment/decrement 上的修复(#2382、#1733)。

5.5 会话(Session)

  • PHP 8 下 flash 数据未能删除(#3974、PR #4053);
  • Redis 处理器对 sessionExpiration=0 的支持(#3111);
  • get('key') 在值为整数 0 时错误返回 null(PR #2339);
  • 数据库/文件/Redis 各处理器在垃圾回收与 ID 重建上的修复(#942、#318)。

5.6 安全与工具

  • CSRF:JSON POST 处理(PR #2240)、X-CSRF-TOKEN 头支持(PR #2272)、token 刷新(PR #2027);
  • 加密服务:密钥 hex2bin 前缀处理(PR #3307)、digest 参数可配置(#3404);
  • 调试工具栏:<head> 内渲染(PR #2494)、CSP 兼容(PR #1129)、历史文件清理(PR #1155);
  • 图像库:WebP 透明通道保留(#3690)、EXIF 重定向(#3006)。

六、从 4.0 升级到后续版本:官方给出的迁移方向

虽然本文聚焦 4.0 系列,但 v4.0.5 的弃用项直接指向了 4.1 的升级路径,值得提前布局:

  1. 全面使用 Factories:将 ModelFactory 与 Config 的调用替换为 Factories::models() / Factories::config(),这是 4.1 起的标准做法;
  2. 关注 HTTP 层 PSR 兼容化:4.0.5 的"HTTP Layer Refactor"为 4.1 的 PSR-7 兼容层铺路,涉及 Request、Response、Message 系列的接口调整;
  3. 重检上传扩展名逻辑:如第二节所述,getExtension()/guessExtension() 的兜底语义已变化,若应用强依赖旧行为需显式处理;
  4. 跟随官方升级文档:4.x 各版本的详细升级指南位于 user_guide_src/source/installation/upgrading.rst(对应各 upgrade_4xx.rst 主题),建议升级前逐节对照。

七、如何在当前仓库中验证这些变更

本仓库为 CodeIgniter 4 框架源码仓库,可直接查看实现与测试来印证日志描述:

八、小结:4.0 系列给开发者留下的关键清单

主题 关键结论 出处
工厂模式 从 v4.0.5 起统一使用 Factories::models() / Factories::config() system/Config/Factories.php
上传安全 guessExtension() 不再信任客户端扩展名,失败返回空串 system/HTTP/Files/UploadedFile.php
PHP 8 v4.0.5 起完整支持,修复大量"可选参数后跟必选参数"告警 changelogs/CHANGELOG_4.0.md
软删除 从布尔标记演进为 deleted_at 时间戳 system/Model.php
查询构造器 getCompiledDelete() 只编译不执行;绑定与 DBPrefix 细节被反复加固 system/Database/BaseBuilder.php
升级路径 4.0.5 的弃用项直接导向 4.1 的 HTTP PSR 兼容层 user_guide_src/source/installation/upgrading.rst

CodeIgniter 4.0 系列用 28 个月、15 个预发布版本和 6 个正式补丁完成了从重写到稳定的全过程。理解这份变更日志,不仅有助于排查 4.0 时代的遗留问题,更能为你升级到 4.1 及之后版本提供清晰的迁移地图。

登录后查看全文
CodeIgniter4