docs: 📚 更新文档以反映 v4.6.3 版本变更及新增功能说明

Author: hex-ci

.claude/commands/translate.md

@@ -0,0 +1,3 @@
+使用 @agent-codeigniter-translator 翻译 $ARGUMENTS
+
+使用中文与我交流。

source/changelogs/index.rst

@@ -12,6 +12,8 @@
 .. toctree::
     :titlesonly:
 
+    v4.6.3
+    v4.6.2
     v4.6.1
     v4.6.0
     v4.5.8

source/changelogs/v4.6.2.rst

@@ -0,0 +1,54 @@
+#############
+版本 4.6.2
+#############
+
+发布日期：2025 年 7 月 26 日
+
+**CodeIgniter4 的 4.6.2 版本发布**
+
+.. contents::
+    :local:
+    :depth: 3
+
+********
+安全更新
+********
+
+- **ImageMagick 处理器：** 修复了 *ImageMagick 处理器中的命令注入漏洞*。
+  详情请参阅 `安全公告 GHSA-9952-gv64-x94c <https://github.com/codeigniter4/CodeIgniter4/security/advisories/GHSA-9952-gv64-x94c>`_。
+
+********
+变更内容
+********
+
+- **Security：** Security 辅助函数的 ``sanitize_filename()`` 函数现在支持第二个参数来控制是否允许相对路径。
+
+************
+废弃功能
+************
+
+- **Security：** ``Security::sanitizeFilename()`` 方法已废弃。请使用 ``sanitize_filename()`` 代替。
+- **Security：** ``SecurityInterface::sanitizeFilename()`` 方法已废弃。
+
+**********
+错误修复
+**********
+
+- **Cache：** 修复了损坏或不可读的缓存文件可能在 ``FileHandler::getItem()`` 中引发未处理异常的错误。
+- **Commands：** 修复了 ``make:test`` 在 Windows 上总是出错的错误。
+- **Commands：** 修复了 ``make:test`` 生成的测试文件不以 ``Test.php`` 结尾的错误。
+- **Commands：** 修复了 ``make:test`` 在未输入类名后输入提示会显示三次的错误。
+- **CURLRequest：** 修复了在某些情况下中间 HTTP 响应未从响应链中正确移除的错误，该错误会导致返回不正确的状态码和标头而非最终响应。
+- **Database：** 修复了 ``ConditionalTrait`` 中的 ``when()`` 和 ``whenNot()`` 错误地将某些假值（如 ``[]``、``0``、``0.0`` 和 ``'0'``）评估为真值的错误，导致回调被意外执行。这些方法现在使用 ``(bool)`` 将条件转换为布尔值，以确保与 PHP 原生真值性的一致行为。
+- **Database：** 修复了 ``BasePreparedQuery`` 在访问 ``BaseConnection::transStatus`` 受保护属性时的封装违规问题。
+- **DownloadResponse：** 修复了使用内联处置时 ``Content-Disposition`` 标头中缺少 ``filename`` 参数的错误，该错误会导致浏览器使用 URL 的最后一段作为文件名而不是预期的文件名。
+- **Email：** 修复了当 ``$_SERVER['SERVER_NAME']`` 未设置时 ``Email::getHostname()`` 无法使用 ``$_SERVER['SERVER_ADDR']`` 的错误。
+- **Security：** 修复了 Security 辅助函数的 ``sanitize_filename()`` 函数在 CLI 请求中使用时会抛出错误的问题。
+- **Session：** 修复了对不受支持的数据库驱动程序（如 ``SQLSRV``、``OCI8`` 或 ``SQLite3``）使用 ``DatabaseHandler`` 时未抛出适当错误的问题。
+- **SiteURI：** 修复了 ``SiteURIFactory::parseRequestURI()`` 中在使用 ``mod_rewrite`` 从子文件夹提供应用程序服务同时保留 ``index.php`` 文件时会导致错误路由路径检测的错误。
+- **SiteURI：** 修复了 ``SiteURIFactory::parseRequestURI()`` 中当应用程序从子文件夹提供服务时包含多字节（非 ASCII）字符的文件夹名称无法正确解析的错误。
+- **URI：** 修复了 ``URI::getAuthority()`` 中没有定义默认端口的方案（如 ``rtsp://``）由于缺少数组键处理而导致问题的错误。
+
+请参阅仓库的
+`CHANGELOG.md <https://github.com/codeigniter4/CodeIgniter4/blob/develop/CHANGELOG.md>`_
+获取已修复错误的完整列表。

source/changelogs/v4.6.3.rst

@@ -0,0 +1,22 @@
+#############
+版本 4.6.3
+#############
+
+发布日期：2025 年 8 月 2 日
+
+**CodeIgniter4 的 4.6.3 版本发布**
+
+.. contents::
+    :local:
+    :depth: 3
+
+**********
+问题修复
+**********
+
+- **Email：** 修复了在构建邮件附件时 CID 检查的问题。
+- **Email：** 修复了类析构函数中 SMTP 连接资源验证的问题。
+
+查看代码仓库的
+`CHANGELOG.md <https://github.com/codeigniter4/CodeIgniter4/blob/develop/CHANGELOG.md>`_
+获取完整的问题修复列表。

source/conf.py

@@ -26,7 +26,7 @@
 version = '4.6'
 
 # The full version, including alpha/beta/rc tags.
-release = '4.6.1'
+release = '4.6.3'
 
 # -- General configuration ---------------------------------------------------
 

source/database/query_builder.rst

@@ -1106,7 +1106,7 @@ $builder->when()
 
 .. versionadded:: 4.3.0
 
-这允许根据条件修改查询，而不会中断查询构建器链。第一个参数是条件，应评估为布尔值。第二个参数是在条件为 true 时运行的回调函数。
+这允许根据条件修改查询而不破坏查询构建器链。第一个参数是条件，它应该评估为布尔值。第二个参数是一个可调用的函数，当条件为真时将运行该函数。
 
 例如，你可能希望仅根据 HTTP 请求中发送的值应用给定的 WHERE 语句：
 

source/helpers/security_helper.rst

@@ -20,16 +20,16 @@
 
 以下函数可用:
 
-.. php:function:: sanitize_filename($filename)
+.. php:function:: sanitize_filename($filename[, $relativePath = false])
 
     :param    string    $filename: 文件名
+    :param    bool      $relativePath: 是否接受相对路径（自 v4.6.2 起可用）
     :returns:    安全的文件名
     :rtype:    string
 
     提供对目录遍历的保护。
 
-    此函数是 ``\CodeIgniter\Security::sanitizeFilename()`` 的别名。
-    更多信息,请参阅 :doc:`安全库 <../libraries/security>` 文档。
+    更多信息，请参阅 :doc:`安全 <../libraries/security>` 文档。
 
 .. php:function:: strip_image_tags($str)
 

source/incoming/routing.rst

@@ -150,7 +150,7 @@ HTTP 方法路由
 ============ ===========================================================================================================
 (:any)       匹配从该位置到 URI 末尾的所有字符，可能包含多个段
 (:segment)   匹配除斜杠（``/``）外的任意字符，限制为单个段
-(:num)       匹配任意整数
+(:num)       匹配任意正整数
 (:alpha)     匹配任意字母字符串
 (:alphanum)  匹配任意字母数字组合字符串
 (:hash)      与 ``(:segment)`` 相同，便于识别使用哈希 ID 的路由

source/installation/running.rst

@@ -452,6 +452,9 @@ default.conf
 引导应用程序
 *********************
 
-在某些情况下，你可能希望加载框架而不实际运行整个应用程序。这对于对项目进行单元测试非常有用，但也可能对使用第三方工具分析和修改代码很有用。框架提供了一个专门用于此场景的独立引导脚本：**system/Test/bootstrap.php**。
+在某些情况下，你希望加载框架但不实际运行整个应用程序。这对于你的项目的单元测试特别有用，但对于使用第三方工具分析和修改你的代码也可能很有用。框架专门为这些情况提供了两个单独的引导脚本：
 
-在引导过程中，大部分项目路径都会被定义。你可以使用预定义的常量来覆盖这些路径，但是当使用默认值时，请确保你的路径与安装方法的预期目录结构对齐。
+- **system/Test/bootstrap.php**：此脚本主要用于单元测试。
+- **system/util_bootstrap.php**：此脚本用于需要访问框架的其他脚本。建议在不属于测试的脚本中使用此脚本，因为如果抛出异常，它将不会优雅地失败。
+
+你的项目的大部分路径是在引导过程中定义的。你可以使用预定义的常量来覆盖这些路径，但在使用默认值时，请确保你的路径与你的安装方法的预期目录结构一致。

source/installation/upgrade_460.rst

@@ -178,6 +178,8 @@ Session ID (SID) 变更
     - 新增 ``Config\Feature::$strictLocaleNegotiation``
 - app/Config/Routing.php
     - ``Config\Routing::$translateUriToCamelCase`` 已变更为 ``true``
+- app/Config/Kint.php
+    - ``Config\Kint::$richSort`` 已被移除。Kint v6 不再使用 ``AbstractRenderer::SORT_FULL``。如果在你的代码中保留此属性，将因未定义常量而导致运行时错误。
 
 所有变更
 ===========