CodeIgniter 4 从 4.5.1 升级到 4.5.2:项目空间文件变更清单与三种安装方式实操指南

原创2026-10-11 20:04:511,978 阅读
文章标签:后端Web框架

CodeIgniter 4 从 4.5.1 升级到 4.5.2:项目空间文件变更清单与三种安装方式实操指南

本篇指南以 CodeIgniter 4 官方升级文档 upgrade_452.rst 为主体,完整梳理从 4.5.1 升级到 4.5.2 的全部要点:三种安装方式各自的升级命令、项目空间(Project Space)中需要人工合并的 10 个变更文件及其真实作用,以及 4.5.2 版本修复的关键缺陷(依据 CHANGELOG_4.5.md)。读完后,你可以根据自己的安装方式完成一次无遗漏、可验证的 4.5.2 升级。

一、升级前:先确认当前版本号

在进行任何升级操作之前,需要确认项目当前运行的框架版本。官方升级总览 upgrading.rst 给出了两种方法:

  1. 在浏览器中打开 Debug Toolbar(调试工具栏),查看框架版本信息;
  2. 在代码中直接输出框架版本常量:
echo \CodeIgniter\CodeIgniter::CI_VERSION;

确认当前版本为 4.5.1 后,即可按下文对应你安装方式的操作步骤进行升级。

二、按安装方式执行升级

官方文档 upgrade_452.rst 明确指出:请参考与你的安装方式相对应的升级说明。CodeIgniter 官方维护三种安装方式,升级路径各不相同。

1. Composer App Starter 安装(推荐方式)

如果你是通过官方 App Starter 模板(composer create-project codeigniter4/appstarter)创建的项目,升级步骤如下。

在项目根目录执行:

composer update

执行完毕后,阅读 升级指南 与 更新日志,重点检查 Breaking Changes 与 Enhancements 是否影响你的代码。

升级到指定版本(锁定版本号)

如果你希望从 4.5.1 精确升级到 4.5.2(例如 4.5.3 已经发布,但你暂时不想跟进),可以打开项目根目录的 composer.json,在 require 中固定框架版本:

"require": {
    ...
    "codeigniter4/framework": "4.5.2"
}

然后运行 composer update。

注意:一旦在 composer.json 中使用固定版本号(如 "codeigniter4/framework": "4.5.2"),composer update 将不会把框架升级到最新版本,除非你修改版本约束。这是官方文档明确提醒的要点。

优点:安装简单、易于更新。 代价:更新后仍需检查项目空间(root、app、public、writable)中的文件变更并手动合并。

2. 通过 Composer 向现有项目添加 CodeIgniter 4

如果你是在已有项目中引入 CodeIgniter 4(而非使用 App Starter),升级方式同样基于 Composer:

composer update

初次接入时使用:

composer require codeigniter4/framework

并需要完成三步初始化:

  1. 将 vendor/codeigniter4/framework 中的 app、public、tests、writable 文件夹复制到项目根目录;
  2. 复制 env、phpunit.dist.xml、spark 文件到项目根目录;
  3. 修改 app/Config/Paths.php 中的 $systemDirectory 属性指向 vendor 目录,例如 __DIR__ . '/../../vendor/codeigniter4/framework/system'。

重要:生产环境部署时,务必执行 composer install --no-dev,移除仅开发所需的 Composer 包,可显著减小 vendor 目录体积。

3. 手动安装(不使用 Composer)

手动安装方式下,升级方法最为直接:下载框架新副本,然后替换 system 文件夹。

官方明确警告:应用代码写在 app 文件夹中,public 文件夹是公开的文档根目录,绝对不要修改 system 文件夹内的任何内容。替换时只动 system,项目空间(root、app、public、tests、writable)中的变更需要你自己逐个检查并合并。

三、核心章节:项目空间(Project Space)文件变更清单

这是 upgrade_452.rst 中最关键的内容,也是升级时最容易遗漏的部分。

什么是"项目空间"? CodeIgniter 将项目目录划分为两类作用域:

  • system 作用域:框架核心代码,位于 system/ 或 vendor/codeigniter4/framework/system,升级时会被自动替换;
  • 项目空间:项目根目录下的 root、app、public、writable 目录,这些文件不在 system 作用域内,升级时不会自动变更,必须人工干预。

官方文档强调,Packagist 上存在一些第三方 CodeIgniter 模块(搜索关键词 codeigniter4 updates)可以辅助合并项目空间的变更,但默认情况下,这些变更需要你自行处理。

4.5.1 → 4.5.2 版本中,项目空间收到更新的完整文件清单如下(其中许多是注释或格式调整,不影响运行时行为,但建议逐一核对):

- app/Config/DocTypes.php
- app/Config/Exceptions.php
- preload.php
- spark
- writable/.htaccess
- writable/cache/index.html
- writable/debugbar/index.html
- writable/index.html
- writable/logs/index.html
- writable/session/index.html

下面结合当前仓库中的真实源码,逐个说明这些文件的用途与升级时的关注点。

1. app/Config/DocTypes.php —— 文档类型(DOCTYPE)配置

该文件定义了框架在生成 HTML 时可以使用的全部文档类型声明,供视图层引用。当前仓库中的实现见 app/Config/DocTypes.php,核心结构为:

<?php

namespace Config;

class DocTypes
{
    /**
     * List of valid document types.
     *
     * @var array<string, string>
     */
    public array $list = [
        'xhtml11'           => '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">',
        'xhtml1-strict'     => '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">',
        // ... 其余 XHTML / HTML / MathML / SVG 文档类型声明
        'html5'             => '<!DOCTYPE html>',
        'xhtml-rdfa-2'      => '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.1//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-2.dtd">',
    ];

    /**
     * Whether to remove the solidus (`/`) character for void HTML elements (e.g. `<input>`)
     * for HTML5 compatibility.
     *
     * Set to:
     *    `true` - to be HTML5 compatible
     *    `false` - to be XHTML compatible
     */
    public bool $html5 = true;
}

该文件共注册了 19 种文档类型(xhtml11、xhtml1-strict、html5、mathml1、svg11 等),并包含一个布尔配置 $html5:设为 true 时按 HTML5 规范移除空元素(void element)的结尾斜杠(如 <input>),设为 false 时保持 XHTML 兼容。如果你从未自定义过此文件,可以直接用新版本覆盖;如果有自定义条目,请合并保留。

2. app/Config/Exceptions.php —— 异常处理配置

该文件控制框架的异常处理行为,是升级时需要重点核对的文件之一。当前仓库中的实现见 app/Config/Exceptions.php,继承自 CodeIgniter\Config\BaseConfig,包含以下关键配置项:

配置项 类型 默认值 作用
$log bool true 是否通过 Services::Log 记录异常
$ignoreCodes array [404] 无需记录日志的 HTTP 状态码,默认仅忽略 404
$errorViewPath string APPPATH.'Views/errors' 存放 cli 与 html 两个错误视图目录的路径
$sensitiveDataInTrace array [] 调试堆栈中需要隐藏的敏感数据,可用 / 表示两级路径,如 ['server', 'setup/password', 'secret_token']
$logDeprecations bool true 为 true 时,DEPRECATED 错误仅记录日志而不抛出异常
$deprecationLogLevel string LogLevel::WARNING 废弃警告写入的 PSR-3 日志级别,需同步调整 Config\Logger::$threshold
handler() 方法 默认处理器 根据 HTTP 状态码返回对应的异常处理器

其中 handler() 方法允许你为特定状态码注入自定义异常处理器,官方注释给出了示例:

public function handler(int $statusCode, Throwable $exception): ExceptionHandlerInterface
{
    // 默认行为:使用 CodeIgniter 默认处理器
    // 按 is_cli() 与响应格式决定 CLI / HTTP / AJAX 的展示方式
    return new ExceptionHandler($this);

    // 自定义示例:拦截特定状态码
    // if (in_array($statusCode, [400, 404, 500])) {
    //     return new \App\Libraries\MyExceptionHandler();
    // }
    // if ($exception instanceof PageNotFoundException) {
    //     return new \App\Libraries\MyExceptionHandler();
    // }
}

升级时若你未对异常处理做过自定义,可直接采用新版文件;若有自定义(如 $sensitiveDataInTrace、handler() 定制),请对照新版本合并差异。

3. preload.php —— OPcache 预加载示例

preload.php 是 4.5.2 中明确有修复的文件(changelog 记录为 fix: update preload.php for 4.5)。当前仓库根目录下的 preload.php 是一个可复制的 OPcache 预加载示例,其用途与配置方式为:

  1. 将文件复制到项目根目录;
  2. 设置类中的 $paths 属性;
  3. 在 php.ini 中配置:
opcache.preload=/path/to/preload.php

文件的核心逻辑(见 preload.php):

  • 通过 require __DIR__ . '/app/Config/Paths.php' 加载路径配置,并定义 FCPATH(指向 public 目录);
  • 定义 preload 类,其中 $paths 数组声明了要预加载的目录(include,默认指向 vendor/codeigniter4/framework/system,手动安装时需修改)以及排除清单(exclude);
  • 排除清单默认跳过不常用的数据库驱动(OCI8、Postgre、SQLite3、SQLSRV)、CLI/命令相关类、system/Test/、system/Language/、视图文件等;
  • 构造函数调用 Boot::preload($paths) 完成引导;load() 方法通过 RecursiveDirectoryIterator + RegexIterator 遍历 PHP 文件,跳过以 Test 结尾的文件后逐个 require_once。

需要注意:preload.php 中的调试输出代码(如 echo 'Loaded: ...')仅供调试时临时取消注释,生产环境严禁启用——预加载脚本绝不能产生任何输出。

4. spark —— CLI 命令入口

spark 是项目根目录下的命令行入口脚本(位于仓库根目录 spark),用于执行诸如 spark serve、spark migrate、spark routes 等 CLI 命令。4.5.2 的 changelog 中记录了与之相关的修复([ErrorException] Undefined array key in spark phpini:check),因此升级时建议使用新版本替换该脚本。

5. writable/ 目录下的占位与保护文件

writable 目录用于存放运行时生成的数据(日志、缓存、会话、上传文件等),其中的文件变更虽然多是占位符(index.html)或保护性文件(.htaccess),但升级时也应一并同步:

  • writable/.htaccess —— 保护目录不被直接列举访问;
  • writable/cache/index.html、writable/logs/index.html、writable/session/index.html、writable/debugbar/index.html、writable/index.html —— 各子目录的占位页面,用于阻止 Web 服务器对空目录的目录列举。

这些占位文件与当前仓库中的 writable/index.html、writable/debugbar/index.html、writable/session/index.html 属于同类文件,直接覆盖即可,一般不存在冲突。

四、为什么升级:4.5.2 版本修复内容一览

根据 CHANGELOG_4.5.md(第 163 行起),v4.5.2 发布于 2024-06-10,是一个以缺陷修复为主的补丁版本,包含 15 项 Bug 修复与 1 项重构:

与模型数据转换(casting)相关的修复(本次升级重点收益):

  • 修复 Model casting 可能抛出 InvalidArgumentException: Invalid parameter: nullable 的问题;
  • 修复 Model casting 在未找到记录时触发 TypeError 的问题;
  • 修复 Model::find() 在开启 casting 时返回错误数据的问题。

查询构造器与数据库驱动修复:

  • 修复 QueryBuilder 的 join() 在使用 BETWEEN 时抛出 TypeError 的问题;
  • 修复 SQLSRV 驱动下 Query Builder 总是把 "<database>"."<schema>". 附加到表名的问题;
  • 修复 Postgres 下缺失错误信息显示的问题。

其他关键修复:

  • 更新 preload.php 以适配 4.5 系列(即本文第三节第 3 项);
  • 修复 spark phpini:check 命令中未定义数组键导致的 ErrorException;
  • 修复不正确的 Security 异常消息;
  • 修复 FileCollection 伪正则匹配问题;
  • 修正 Email 中属性的默认值;
  • 修复 CLI::promptByMultipleKeys() 与 prompt();
  • 修复 number_to_amount() 中的 TypeError;
  • 移除 MockCache::save() 中未使用的 $raw 参数;
  • 修复 App Starter 的 phpunit.xml.dist。

另外有一项重构:移除 PhpStreamWrapper::stream_open() 中未使用的路径参数。

如果你的项目使用 Model 字段类型转换(casting)、QueryBuilder 的 join() 或 Postgres/SQLSRV 驱动,4.5.2 的这些修复直接关系到线上稳定性,应尽快升级。

五、合并项目空间变更的最佳实践

升级完成后,项目空间文件的合并是决定升级成败的最后一步。官方升级总览 upgrading.rst 给出了明确方法:

  1. 对比原始文件:从 vendor/codeigniter4/framework(Composer 安装)或框架 ZIP 压缩包中取出原始文件,与你的项目文件逐一对比。例如原始 app/Config/App.php 位于 vendor/codeigniter4/framework/app/Config/App.php;
  2. 合并差异:保留你自定义的配置行,同时纳入新版本新增的配置项;
  3. 或整体替换后重加自定义:直接用新版文件覆盖,再把此前自定义的行重新加入。

对于本次 4.5.2 升级,建议合并顺序为:先处理 app/Config/DocTypes.php 与 app/Config/Exceptions.php(这两个文件可能有你的自定义项,合并时注意保留),再直接覆盖 preload.php、spark 及 writable/ 下的占位文件。

六、升级后的验证清单

完成上述步骤后,建议按以下顺序验证升级结果:

  1. 确认版本号:运行 composer show codeigniter4/framework,或通过 Debug Toolbar / \CodeIgniter\CodeIgniter::CI_VERSION 确认版本为 4.5.2;
  2. 运行测试:在项目根目录执行 phpunit(或 vendor/bin/phpunit),确认既有测试全部通过,重点覆盖 Model casting、查询构造器等 4.5.2 修复涉及的场景;
  3. 验证 CLI:执行 php spark list,确认 spark 脚本可正常列出命令,无 PHP 报错;
  4. 冒烟测试:启动开发服务器(php spark serve),访问首页与关键业务路由,确认异常处理、DOCTYPE 输出与调试工具栏正常;
  5. 生产部署提醒:如果使用 Composer 安装方式,部署时执行 composer install --no-dev 以移除开发依赖。

至此,你的项目已完成从 CodeIgniter 4.5.1 到 4.5.2 的完整升级,既享受了 15 项 Bug 修复带来的稳定性提升,也确保了项目空间文件的同步。如需了解后续版本(4.5.3 及更高版本)的升级要点,可继续查阅 upgrade_453.rst 等对应版本的官方升级文档。

登录后查看全文
CodeIgniter4