升级到 v4.6.0 (#169)

Author: hex-ci

source/changelogs/index.rst

@@ -12,6 +12,8 @@
 .. toctree::
     :titlesonly:
 
+    v4.6.0
+    v4.5.8
     v4.5.7
     v4.5.6
     v4.5.5

source/changelogs/v4.4.0.rst

@@ -221,7 +221,7 @@ SiteURI 类现在比以前更严格地规范化站点 URI，并修复了一些
 - **View:** 在 ``renderSection()`` 上添加了可选的第二个参数 ``$saveData``，以防止在显示后自动清除数据。请参阅 :ref:`View Layouts <creating-a-layout>` 了解详细信息。
 - **自动路由（改进）：**
     - 现在你可以路由到模块。请参阅 :ref:`auto-routing-improved-module-routing` 了解详细信息。
-    - 如果找到与 URI 段对应的控制器，并且该控制器没有为该 URI 段定义的方法，则将执行默认方法。这样可以更灵活地处理自动路由中的 URI。请参阅 :ref:`controller-default-method-fallback` 了解详细信息。
+    - 如果找到与 URI 段对应的控制器，并且该控制器没有为该 URI 段定义的方法，则将执行默认方法。这样可以更灵活地处理自动路由中的 URI。请参阅 :ref:`auto-routing-improved-default-method-fallback` 了解详细信息。
 - **过滤器：** 现在可以在 :ref:`$filters 属性 <filters-filters-filter-arguments>` 中使用过滤器参数。
 - **请求：** 添加了 ``IncomingRequest::setValidLocales()`` 方法，用于设置有效的区域设置。
 - **Table:** 添加了 ``Table::setSyncRowsWithHeading()`` 方法，用于将行列与标题同步。请参阅 :ref:`table-sync-rows-with-headings` 了解详细信息。

source/changelogs/v4.5.0.rst

@@ -56,7 +56,7 @@
 路由
 ====
 
-- **AutoRouting 改进：** 添加了 ``$translateUriToCamelCase`` 选项，允许使用驼峰式（CamelCase）控制器和方法名称。详见 :ref:`controller-translate-uri-to-camelcase`。
+- **AutoRouting 改进：** 添加了 ``$translateUriToCamelCase`` 选项，允许使用驼峰式（CamelCase）控制器和方法名称。详见 :ref:`translate-uri-to-camelcase`。
 - **其他改进：**
     - 添加了 ``$multipleSegmentsOneParam`` 选项。启用该选项时，匹配多个段的占位符（如 ``(:any)``）将直接作为一个参数传递，即使它包含多个段。详见 :ref:`multiple-uri-segments-as-one-parameter`。
     - 现在你在 ``$override404`` 中设置的 404 控制器方法也会接收到 ``PageNotFoundException`` 消息作为第一个参数。

source/changelogs/v4.5.8.rst

@@ -0,0 +1,29 @@
+#############
+版本 4.5.8
+#############
+
+发布日期：2025 年 1 月 19 日
+
+**CodeIgniter4 的 4.5.8 版本发布**
+
+.. contents::
+    :local:
+    :depth: 3
+
+********
+安全更新
+********
+
+- **Header:** 修复了*标头名称和值的验证*问题。
+  详细信息请查阅安全通告
+  `GHSA-x5mq-jjr3-vmx6 <https://github.com/codeigniter4/CodeIgniter4/security/advisories/GHSA-x5mq-jjr3-vmx6>`_。
+
+************
+已修复的缺陷
+************
+
+- **Database:** 修复了当 ``Postgre`` 和 ``SQLSRV`` 驱动中前次查询调用失败时，``Builder::affectedRows()`` 抛出错误的缺陷。
+- **Security:** 修复了因错误格式输入导致 CSRF 令牌验证失败时直接返回通用 HTTP 500 状态码（而非优雅处理输入）的缺陷。
+
+完整缺陷修复列表请查阅仓库的
+`CHANGELOG.md <https://github.com/codeigniter4/CodeIgniter4/blob/develop/CHANGELOG.md>`_。

source/changelogs/v4.6.0.rst

@@ -0,0 +1,292 @@
+#############
+版本 4.6.0
+#############
+
+发布日期：2025 年 1 月 19 日
+
+**CodeIgniter4 的 4.6.0 版本发布**
+
+.. contents::
+    :local:
+    :depth: 3
+
+********
+重大变更
+********
+
+行为变更
+========
+
+.. _v460-behavior-changes-exceptions:
+
+异常处理
+--------
+
+异常类已重新设计。详细信息请参阅 :ref:`exception-design`。
+以下是相应的破坏性变更：
+
+- ``Validation::setRule()`` 现在抛出 ``CodeIgniter\Exceptions\InvalidArgumentException`` 而非 ``TypeError``
+- ``CriticalError`` 现在继承自 ``CodeIgniter\Exceptions\RuntimeException`` 而非 ``Error``
+- ``DatabaseException`` 现在继承自 ``CodeIgniter\Exceptions\RuntimeException`` 而非 ``Error``
+- ``ConfigException`` 现在继承自 ``CodeIgniter\Exceptions\RuntimeException`` 而非 ``CodeIgniter\Exceptions\CriticalError``
+- ``TestException`` 现在继承自 ``CodeIgniter\Exceptions\LogicException`` 而非 ``CodeIgniter\Exceptions\CriticalError``
+
+过滤器变更
+---------------
+
+``Filters`` 类已修改，允许在 before 或 after 阶段使用不同参数多次运行相同过滤器。详细信息请参阅 :ref:`Upgrading Guide <upgrade-460-filters-changes>`。
+
+注册器
+----------
+
+新增检查以防止注册器自动发现机制重复运行。若重复执行将抛出异常。详细信息请参阅 :ref:`upgrade-460-registrars-with-dirty-hack`。
+
+Time::createFromTimestamp()
+---------------------------
+
+``Time::createFromTimestamp()`` 处理时区的方式已变更。若未显式传递 ``$timezone`` 参数，实例时区将设为 UTC（此前使用系统默认时区）。详细信息请参阅 :ref:`Upgrading Guide <upgrade-460-time-create-from-timestamp>`。
+
+支持微秒的时间处理
+----------------------
+
+修复了 ``Time`` 类中部分方法丢失微秒的缺陷。详细信息请参阅 :ref:`Upgrade Guide <upgrade-460-time-keeps-microseconds>`。
+
+Time::setTimestamp()
+--------------------
+
+``Time::setTimestamp()`` 的行为已修正。详细信息请参阅 :ref:`Upgrade Guide <upgrade-460-time-set-timestamp>`。
+
+非 HTML 请求的错误报告
+------------------------------------
+
+旧版本中，当请求不接受 HTML 时，CodeIgniter 仅在 ``development`` 和 ``testing`` 环境下显示错误详情。
+
+由于在自定义环境中无法显示错误详情，现修正此行为：只要 PHP 配置中的 ``display_errors`` 启用即显示错误详情。
+
+此修正后，HTML 请求与非 HTML 请求的错误详情显示条件现已统一。
+
+会话 ID (SID)
+----------------
+
+现在 ``Session`` 类库强制使用 PHP 默认的 32 字符 SID（每字符 4 位熵值）。详细信息请参阅 :ref:`Upgrade Guide <upgrade-460-sid-change>`。
+
+.. _v460-interface-changes:
+
+响应头处理
+----------
+
+通过 ``Response`` 类设置的响应头将覆盖通过 PHP ``header()`` 函数设置的响应头。
+
+旧版本中，``Response`` 类设置的响应头会追加到现有响应头（无法修改），当存在互斥指令的同名响应头时可能导致意外行为。
+
+例如，session 会自动通过 ``header()`` 函数设置响应头：
+
+.. code-block:: none
+
+    Expires: Thu, 19 Nov 1981 08:52:00 GMT
+    Cache-Control: no-store, no-cache, must-revalidate
+    Pragma: no-cache
+
+若再次设置 **Expires** 响应头将导致重复：
+
+.. code-block:: php
+
+    $response->removeHeader('Expires'); // 无效操作
+    return $response->setHeader('Expires', 'Sun, 17 Nov 2024 14:17:37 GMT');
+
+响应头结果：
+
+.. code-block:: none
+
+    Expires: Thu, 19 Nov 1981 08:52:00 GMT
+    // ...
+    Expires: Sun, 17 Nov 2024 14:17:37 GMT
+
+此时浏览器可能无法正确识别有效响应头。本版本变更后，旧响应头将被覆盖：
+
+.. code-block:: none
+
+    Cache-Control: no-store, no-cache, must-revalidate
+    Pragma: no-cache
+    Expires: Sun, 17 Nov 2024 14:17:37 GMT
+
+接口变更
+=================
+
+.. note:: 只要你未扩展相关 CodeIgniter 核心类或实现这些接口，所有变更均向后兼容且无需调整。
+
+- **Router:** 以下方法已加入 ``RouteCollectionInterface`` 接口：
+
+    - ``getDefaultNamespace()``
+    - ``getRoutesOptions()``
+    - ``setHTTPVerb()``
+    - ``isFiltered()``
+    - ``getFiltersForRoute()``
+
+.. _v460-method-signature-changes:
+
+方法签名变更
+========================
+
+- **Router:** ``DefinedRouteCollector`` 的构造函数参数类型由 ``RouteCollection`` 改为 ``RouteCollectionInterface``
+- **View:** ``renderSection()`` 方法的返回类型改为 ``string``，且不再调用 ``echo``
+- **Time:** ``createFromTimestamp()`` 的首个参数类型由 ``int`` 改为 ``int|float``，并新增返回类型 ``static``
+- **Helpers:** 更新了 ``character_limiter()`` 的参数命名。若使用命名参数需更新函数调用
+
+移除类型定义
+------------------------
+
+- **Database:**
+    - 移除 ``BaseConnection::escapeIdentifier()`` 首个参数的 ``string`` 类型
+    - 移除 ``BaseConnection::getFieldNames()`` 和 ``SQLite3\Connection::getFieldNames()`` 首个参数的 ``string`` 类型
+    - 移除 ``BaseConnection::_listColumns()``、``MySQLi\Connection::_listColumns()``、``OCI8\Connection::_listColumns()``、``Postgre\Connection::_listColumns()``、``SQLSRV\Connection::_listColumns()``、``SQLite3\Connection::_listColumns()`` 首个参数的 ``string`` 类型
+
+.. _v460-removed-deprecated-items:
+
+移除已弃用项
+========================
+
+- **API:** 移除 ``CodeIgniter\API\ResponseTrait`` 中已弃用的 ``failValidationError()`` 方法，改用 ``failValidationErrors()``
+- **HTTP:** 移除 ``CodeIgniter\HTTP\Response`` 和 ``ResponseInterface`` 中已弃用的 ``getReason()`` 方法，改用 ``getReasonPhrase()``
+- **Logger:** 移除已弃用的 ``CodeIgniter\Log\Logger::cleanFilenames()`` 和 ``CodeIgniter\Test\TestLogger::cleanup()`` 方法，改用 ``clean_path()`` 函数
+- **Router:** 移除已弃用的 ``CodeIgniter\Router\Exceptions\RedirectException`` 异常类，改用 ``CodeIgniter\HTTP\Exceptions\RedirectException``
+- **Constants:** 移除已弃用的 ``EVENT_PRIORITY_*`` 常量，改用类常量 ``CodeIgniter\Events\Events::PRIORITY_LOW``、``CodeIgniter\Events\Events::PRIORITY_NORMAL`` 和 ``CodeIgniter\Events\Events::PRIORITY_HIGH``
+- **View:** 移除已弃用的 ``CodeIgniter\View\View::$currentSection`` 属性
+- **Config:** 移除已弃用的 ``Config\Cache::$storePath`` 属性，改用 ``Config\Cache::$file['storePath']``
+- **Formatter:** 移除已弃用的 ``Config\Format::getFormatter()`` 方法，改用 ``CodeIgniter\Format\Format::getFormatter()``
+- **Security:** 移除 ``Config\Security::$samesite`` 配置项，改用 ``Config\Cookie::$samesite``
+- **Cookie:** 移除 ``CodeIgniter\Cookie\CookieStore`` 中的 ``dispatch()``、``setRawCookie()``、``setCookie()`` 方法，这些方法已移至 ``CodeIgniter\HTTP\ResponseTrait``
+
+************
+功能增强
+************
+
+发布器
+=========
+
+- ``Publisher::discover()`` 新增第二个参数（``namespace``）用于指定搜索发布器的命名空间。详细信息请参阅 :ref:`discovery-in-a-specific-namespace`。
+
+异常处理
+==========
+
+异常类已重新设计。详细信息请参阅 :ref:`exception-design`。
+新增以下异常类：
+
+- ``CodeIgniter\Exceptions\LogicException``
+- ``CodeIgniter\Exceptions\RuntimeException``
+- ``CodeIgniter\Exceptions\BadFunctionCallException``
+- ``CodeIgniter\Exceptions\BadMethodCallException``
+- ``CodeIgniter\Exceptions\InvalidArgumentException``
+
+新增以下异常接口：
+
+- ``CodeIgniter\Files\Exceptions\ExceptionInterface``
+- ``CodeIgniter\HTTP\Exceptions\ExceptionInterface``
+- ``CodeIgniter\Router\Exceptions\ExceptionInterface``
+
+非 HTML 响应的异常显示现基于 PHP 的 ``display_errors`` 设置，而非硬编码环境判断。
+
+命令行工具
+==========
+
+- ``spark routes`` 和 ``spark filter:check`` 命令现显示过滤器参数
+- ``spark filter:check`` 命令现显示过滤器类名
+- 新增 ``spark lang:sync`` 命令用于同步翻译文件。详细信息请参阅 :ref:`sync-translations-command`
+- ``spark phpini:check`` 命令新增可选 ``opcache`` 参数，用于显示 opcache 设置信息
+
+路由
+=======
+
+- 现可在限制路由时指定多个主机名
+
+协商器
+==========
+
+- 新增特性开关 ``Feature::$strictLocaleNegotiation`` 用于启用严格区域匹配。
+  旧版本中，对于 ``Accept-language: en-US,en-GB;q=0.9`` 的请求会返回首个允许的语言 ``en``（而非精确匹配 ``en-US`` 或 ``en-GB``）。
+  设为 ``true`` 后启用基于语言代码（'en' - ISO 639-1）和区域代码（'en-US' - ISO 639-1 + ISO 3166-1 alpha）的精确匹配。
+
+分页
+==========
+
+- 新增获取当前页总条目数和范围的功能。
+  详细信息请参阅 :ref:`Displaying the Number of Items on the Page <displaying-the-number-of-items-on-the-page>`。
+
+数据库
+========
+
+其他改进
+--------
+
+- 为 MySQLi 新增 ``foundRows`` 配置项以使用 ``MYSQLI_CLIENT_FOUND_ROWS``
+- 新增 ``BaseConnection::resetTransStatus()`` 方法用于重置事务状态。详细信息请参阅 :ref:`transactions-resetting-transaction-status`
+- SQLite3 新增 ``synchronous`` 配置项，用于调整事务期间磁盘刷写策略。结合 ``WAL`` 日志模式时可有效优化性能
+
+类库
+=========
+
+- **File:** ``File`` 类新增 ``getSizeByBinaryUnit()`` 和 ``getSizeByMetricUnit()`` 方法。
+  详细信息请参阅 :ref:`File::getSizeByBinaryUnit() <file-get-size-by-binary-unit>` 和 :ref:`File::getSizeByMetricUnit() <file-get-size-by-metric-unit>`。
+- **FileCollection:** ``FileCollection`` 类新增 ``retainMultiplePatterns()`` 方法。
+  详细信息请参阅 :ref:`FileCollection::retainMultiplePatterns() <file-collections-retain-multiple-patterns>`。
+- **Validation:** ``FileRules`` 类新增 ``min_dims`` 验证规则。
+  详细信息请参阅 :ref:`Validation <rules-for-file-uploads>`。
+- **Validation:** ``is_unique`` 和 ``is_not_unique`` 规则现允许在首个参数中指定 ``dbGroup``。
+  详细信息请参阅 :ref:`Validation <rules-for-general-use>`。
+
+其他
+======
+
+- **Filters:** 现可在 before 或 after 阶段使用不同参数多次执行同一过滤器
+- **Services:** 新增 ``BaseService::resetServicesCache()`` 方法用于重置服务缓存。
+  详细信息请参阅 :ref:`resetting-services-cache`
+- **Errors:** 新增默认的 "400 Bad Request" 错误页面
+
+***************
+消息变更
+***************
+
+- 新增 ``Validation.min_dims`` 消息
+- 新增 ``Errors.badRequest`` 和 ``Errors.sorryBadRequest`` 消息
+
+********
+变更列表
+********
+
+异常处理
+==========
+
+异常类已重新设计。详细信息请参阅 :ref:`exception-design`。
+以下是相应变更：
+
+- 缓存处理器类的 ``deleteMatching()`` 方法现抛出 ``CodeIgniter\Exceptions\BadMethodCallException`` 而非 ``Exception``
+- ``Cache\ResponseCache::get()`` 现抛出 ``CodeIgniter\Exceptions\RuntimeException`` 而非 ``Exception``
+- 原抛出 ``RuntimeException`` 的类现改为抛出 ``CodeIgniter\Exceptions\RuntimeException``
+- 原抛出 ``InvalidArgumentException`` 的类现改为抛出 ``CodeIgniter\Exceptions\InvalidArgumentException``
+- 原抛出 ``LogicException`` 的类现改为抛出 ``CodeIgniter\Exceptions\LogicException``
+- 原抛出 ``BadMethodCallException`` 的类现改为抛出 ``CodeIgniter\Exceptions\BadMethodCallException``
+- 原抛出 ``BadFunctionCallException`` 的类现改为抛出 ``CodeIgniter\Exceptions\BadFunctionCallException``
+- ``RedirectException`` 现继承自 ``CodeIgniter\Exceptions\RuntimeException`` 而非 ``Exception``
+- ``PageNotFoundException`` 现继承自 ``CodeIgniter\Exceptions\RuntimeException`` 而非 ``OutOfBoundsException``
+
+************
+已弃用项
+************
+
+- **Filters:**
+    - 弃用 ``Filters`` 的 ``$arguments`` 和 ``$argumentsClass`` 属性（不再使用）
+    - 弃用 ``Filters::getArguments()`` 方法（不再使用）
+- **File:**
+    - 弃用 ``File`` 的 ``getSizeByUnit()`` 方法，改用 ``getSizeByBinaryUnit()`` 或 ``getSizeByMetricUnit()``
+
+************
+已修复的缺陷
+************
+
+- **Response:**
+    - 现在通过 ``Response`` 类设置的响应头将优先覆盖通过 PHP ``header()`` 函数手动设置的响应头
+- **View:** 为 ``View::excerpt()`` 新增多字节字符串支持
+- **Helpers:** 为 ``excerpt()`` 新增多字节字符串支持
+
+完整缺陷修复列表请查阅仓库的
+`CHANGELOG.md <https://github.com/codeigniter4/CodeIgniter4/blob/develop/CHANGELOG.md>`_。

source/cli/cli_library/017.php

@@ -21,11 +21,11 @@
         substr(
             $titles[$i] . str_repeat(' ', $maxlen + 3),
             0,
-            $maxlen + 3
+            $maxlen + 3,
         ) .
         // Wrap the descriptions in a right-hand column
         // with its left side 3 characters wider than
         // the longest item on the left.
-        CLI::wrap($descriptions[$i], 40, $maxlen + 3)
+        CLI::wrap($descriptions[$i], 40, $maxlen + 3),
     );
 }

source/concepts/services.rst

@@ -133,3 +133,16 @@ CodeIgniter 可以自动发现你可能在任何定义的命名空间中创建
 .. literalinclude:: services/012.php
 
 .. note:: 如果多个 Services 文件具有相同的方法名,则返回找到的第一个实例。
+
+.. _resetting-services-cache:
+
+重置服务缓存
+========================
+
+.. versionadded:: 4.6.0
+
+当 Services 类在框架初始化过程的早期首次被调用时，通过自动发现找到的 Services 类会被缓存到一个属性中，并且后续不会更新。
+
+如果后续动态加载了模块，且这些模块中包含 Services 类，则必须更新缓存。
+
+可以通过运行 ``Config\Services::resetServicesCache()`` 来实现。这将清除缓存，并在需要时强制重新进行服务发现。

source/conf.py

@@ -23,10 +23,10 @@
 copyright = '2019-' + str(year_now) + ' CodeIgniter 基金会'
 
 # The short X.Y version.
-version = '4.5'
+version = '4.6'
 
 # The full version, including alpha/beta/rc tags.
-release = '4.5.7'
+release = '4.6.0'
 
 # -- General configuration ---------------------------------------------------