CodeIgniter 4.0 系列完整版本演进全解:从 alpha 到 v4.0.5 的核心变更、弃用与升级指南
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 中最值得注意的安全相关行为变更,直接影响所有处理上传文件的代码:
Config\Mimes::guessExtensionFromType现在仅在未给出候选扩展名时才反向搜索$mimes数组。也就是说,对于通常的上传文件场景,检测不再盲目做全表反查;UploadedFile::getExtension()的兜底值由空字符串''改为$this->getClientExtension();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 的升级路径,值得提前布局:
- 全面使用
Factories:将ModelFactory与Config的调用替换为Factories::models()/Factories::config(),这是 4.1 起的标准做法; - 关注 HTTP 层 PSR 兼容化:4.0.5 的"HTTP Layer Refactor"为 4.1 的 PSR-7 兼容层铺路,涉及
Request、Response、Message系列的接口调整; - 重检上传扩展名逻辑:如第二节所述,
getExtension()/guessExtension()的兜底语义已变化,若应用强依赖旧行为需显式处理; - 跟随官方升级文档:4.x 各版本的详细升级指南位于 user_guide_src/source/installation/upgrading.rst(对应各
upgrade_4xx.rst主题),建议升级前逐节对照。
七、如何在当前仓库中验证这些变更
本仓库为 CodeIgniter 4 框架源码仓库,可直接查看实现与测试来印证日志描述:
- Factories 机制:阅读 system/Config/Factories.php 与 system/Config/Factory.php,测试用例见
tests/system/Config/下的 Factories 相关测试; - 上传文件扩展名检测:阅读 system/HTTP/Files/UploadedFile.php 与 app/Config/Mimes.php,相关测试覆盖了
guessExtensionFromType()的候选扩展名与反向搜索分支; - 查询构造器编译行为:
getCompiledDelete()等方法的实现位于 system/Database/BaseBuilder.php,配套测试在tests/system/Database/; - 模型与软删除:阅读 system/Model.php 与 system/BaseModel.php;
- CLI 命令基础设施:
prompt校验、命令发现等位于 system/CLI/ 目录; - 后续版本对照:
changelogs/目录下的CHANGELOG_4.1.md至CHANGELOG_4.6.md记录了 4.1 之后的演进,可用来对照验证 4.0.5 弃用项的最终去向。
八、小结: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 及之后版本提供清晰的迁移地图。