From 7a44b18d91bbd191e6b1311cf09774d237b159ee Mon Sep 17 00:00:00 2001 From: Hex Date: Fri, 6 Sep 2024 17:45:50 +0800 Subject: [PATCH] =?UTF-8?q?=E5=8D=87=E7=BA=A7=E5=88=B0=204.5.4=20(#166)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- source/changelogs/index.rst | 1 + source/changelogs/v4.5.4.rst | 22 ++++ source/conf.py | 2 +- source/database/query_builder.rst | 8 +- source/general/configuration.rst | 2 + source/incoming/filters.rst | 26 +++-- source/incoming/routing.rst | 11 +- source/installation/upgrade_420.rst | 2 + source/installation/upgrade_454.rst | 30 +++++ source/installation/upgrading.rst | 1 + source/libraries/email.rst | 173 ++++++++++++++-------------- source/libraries/files.rst | 24 +++- source/libraries/user_agent/005.php | 2 +- source/libraries/validation.rst | 51 ++++---- 14 files changed, 222 insertions(+), 133 deletions(-) create mode 100644 source/changelogs/v4.5.4.rst create mode 100644 source/installation/upgrade_454.rst diff --git a/source/changelogs/index.rst b/source/changelogs/index.rst index b03b6795..5a68623e 100644 --- a/source/changelogs/index.rst +++ b/source/changelogs/index.rst @@ -12,6 +12,7 @@ .. toctree:: :titlesonly: + v4.5.4 v4.5.3 v4.5.2 v4.5.1 diff --git a/source/changelogs/v4.5.4.rst b/source/changelogs/v4.5.4.rst new file mode 100644 index 00000000..a57430d4 --- /dev/null +++ b/source/changelogs/v4.5.4.rst @@ -0,0 +1,22 @@ +############# +版本 4.5.4 +############# + +发布日期：2024 年 7 月 27 日 + +**CodeIgniter4 的 4.5.4 版本发布** + +.. contents:: + :local: + :depth: 3 + +********** +修复的错误 +********** + +- **路由：** 修复了一个错误，即传递给 ``$routes->group()`` 的过滤器没有合并到传递给内部路由的过滤器中。 +- **CURLRequest：** 修复了一个错误，即在进行请求时，配置数组中的 ``version`` 字符串无法使用。 + +请参阅仓库的 +`CHANGELOG.md `_ +以获取修复错误的完整列表。 diff --git a/source/conf.py b/source/conf.py index 8c55f3e2..da89b8e9 100755 --- a/source/conf.py +++ b/source/conf.py @@ -26,7 +26,7 @@ version = '4.5' # The full version, including alpha/beta/rc tags. -release = '4.5.3' +release = '4.5.4' # -- General configuration --------------------------------------------------- diff --git a/source/database/query_builder.rst b/source/database/query_builder.rst index addcc419..a90480f7 100755 --- a/source/database/query_builder.rst +++ b/source/database/query_builder.rst @@ -206,6 +206,8 @@ $builder->fromSubquery() Join ==== +.. _query-builder-join: + $builder->join() ---------------- @@ -226,7 +228,7 @@ RawSql .. versionadded:: 4.2.0 -从 v4.2.0 开始, ``$builder->join()`` 接受一个 ``CodeIgniter\Database\RawSql`` 实例,它表示原始 SQL 字符串。 +自 v4.2.0 起，``$builder->join()`` 接受一个 ``CodeIgniter\Database\RawSql`` 实例作为 JOIN ON 条件，该实例用于表示原始 SQL 字符串。 .. literalinclude:: query_builder/102.php @@ -1329,13 +1331,13 @@ $builder->resetQuery() .. php:method:: join($table, $cond[, $type = ''[, $escape = null]]) :param string $table: 要连接的表名 - :param string $cond: JOIN ON 条件 + :param string|RawSql $cond: JOIN ON 条件 :param string $type: JOIN 类型 :param bool $escape: 是否转义值和标识符 :returns: ``BaseBuilder`` 实例(方法链) :rtype: ``BaseBuilder`` - 向查询添加 ``JOIN`` 子句。 + 向查询添加 ``JOIN`` 子句。自 v4.2.0 起，``RawSql`` 可以用作 JOIN ON 条件。另见 :ref:`query-builder-join`。 .. php:method:: where($key[, $value = null[, $escape = null]]) diff --git a/source/general/configuration.rst b/source/general/configuration.rst index d9dda252..fa2d8e40 100755 --- a/source/general/configuration.rst +++ b/source/general/configuration.rst @@ -261,6 +261,8 @@ CodeIgniter 期望 **.env** 文件与 **app** 目录一起位于项目的根目 如果在 :doc:`模块 ` 中启用了 :ref:`auto-discovery`，则注册器可以在命名空间和文件之间在运行时更改配置属性。 +.. note:: 此功能在 ``CodeIgniter\Config\BaseConfig`` 类中实现。因此，它不适用于 **app/Config** 文件夹中未继承该类的某些文件。 + 有两种实现注册器的方法: **隐式** 和 **显式**。 .. note:: 来自 **.env** 的值始终优先于注册器。 diff --git a/source/incoming/filters.rst b/source/incoming/filters.rst index 2e77468d..6cfbad6a 100644 --- a/source/incoming/filters.rst +++ b/source/incoming/filters.rst @@ -62,29 +62,33 @@ 配置过滤器 ******************* -配置过滤器运行时有两种方法。一种是在 **app/Config/Filters.php** 中进行配置，另一种是在 **app/Config/Routes.php** 中进行配置。 +配置过滤器的运行方式有两种。一种是在 **app/Config/Filters.php** 中进行配置，另一种是在 **app/Config/Routes.php** 中进行配置。 -如果你想为特定的路由指定过滤器，请使用 **app/Config/Routes.php** 并参考 :ref:`URI Routing `。 +如果你想为定义的路由指定过滤器，请使用 **app/Config/Routes.php** 并参考 :ref:`URI 路由 `。 -.. note:: 最安全的应用过滤器方法是 :ref:`禁用自动路由 `,并 :ref:`设置过滤器到路由 `。 +.. note:: 应用过滤器最安全的方法是 :ref:`禁用自动路由 `，并 :ref:`将过滤器设置到路由 `。 app/Config/Filters.php ====================== **app/Config/Filters.php** 文件包含四个属性，允许你精确配置过滤器的运行时机。 -.. warning:: 建议你在过滤器设置中的 URI 末尾始终添加 ``*``。因为控制器方法可能比你想象的通过不同的 URL 访问。例如,当启用 :ref:`auto-routing-legacy` 时,如果你有 ``Blog::index``,它可以通过 ``blog``、``blog/index`` 和 ``blog/index/1`` 等方式访问。 +.. warning:: 建议你在过滤器设置中的 URI 末尾始终添加 ``*``。因为控制器方法可能比你想象的通过不同的 URL 访问。例如,当启用 :ref:`auto-routing-legacy` 时,如果你有 ``Blog::index()``,它可以通过 ``blog``、``blog/index`` 和 ``blog/index/1`` 等方式访问。 + +.. _filters-aliases: $aliases -------- -``$aliases`` 数组用于将简单名称与一个或多个完全限定的类名相关联,这些类名是要运行的过滤器: +``$aliases`` 数组用于将一个简单的名称与一个或多个完全限定类名关联起来，这些类名是要运行的过滤器： .. literalinclude:: filters/003.php -别名是强制性的,如果你稍后尝试使用完整的类名,系统将抛出错误。以这种方式定义使得切换使用的类变得简单。非常适合当你决定需要更改到不同的身份验证系统时,因为你只需要更改过滤器的类即可完成。 +别名是强制性的，如果你尝试稍后使用完整的类名，系统会抛出错误。 + +以这种方式定义它们可以简化类的切换。当你决定需要更换不同的认证系统时，这种方式非常有用，因为你只需更改过滤器的类即可。 -你可以将多个过滤器组合成一个别名,使复杂的过滤器组非常简单: +你可以将多个过滤器组合成一个别名，使得应用复杂的过滤器集变得简单： .. literalinclude:: filters/004.php @@ -131,7 +135,7 @@ $globals .. warning:: 在 v4.4.7 之前，由于一个漏洞，被过滤器处理的 URI 路径没有进行 URL 解码。换句话说，路由中指定的 URI 路径和过滤器中指定的 URI 路径可能会不同。详细信息请参见 :ref:`upgrade-447-filter-paths`。 -在过滤器设置中可以使用 URI 路径（相对于 BaseURL）的任何位置,你都可以使用正则表达式,或者像在这个例子中使用星号 (``*``) 作为通配符,匹配之后的所有字符。在这个例子中,任何以 ``api/`` 开头的 URI 路径都将被免于 CSRF 保护,但网站的表单将全部受保护。 +在过滤器设置中，任何可以使用 URI 路径（相对于 BaseURL）的地方，你都可以使用正则表达式，或者像上面的例子中那样，使用星号 (``*``) 作为通配符来匹配其后的所有字符。在这个例子中，任何以 ``api/`` 开头的 URI 路径都将被排除在 CSRF 保护之外，但网站的表单将全部受到保护。 如果你需要指定多个 URI,可以使用 URI 路径模式数组: @@ -142,13 +146,15 @@ $methods .. warning:: 如果使用 ``$methods`` 过滤器,你应该 :ref:`禁用自动路由(传统) `,因为 :ref:`auto-routing-legacy` 允许任何 HTTP 方法访问控制器。以你不期望的方法访问控制器可能会绕过过滤器。 -你可以将过滤器应用于所有某种 HTTP 方法的请求,如 POST、GET、PUT 等。在此数组中,你需要以 **全小写** 指定方法名称。它的值将是要运行的过滤器数组: +你可以对某个 HTTP 方法（如 ``POST``、``GET``、``PUT`` 等）的所有请求应用过滤器。其值将是一个要运行的过滤器数组： .. literalinclude:: filters/008.php .. note:: 与 ``$globals`` 或 ``$filters`` 属性不同,这些只能作为前置过滤器运行。 -除了标准的 HTTP 方法外,这也支持一个特殊情况:``cli``。``cli`` 方法将应用于所有从命令行运行的请求。 +除了标准的 HTTP 方法外，这里还支持一个特殊情况：``CLI``。``CLI`` 方法将应用于所有从命令行运行的请求。 + +.. note:: 在 v4.5.0 之前，由于一个错误，你需要以 **小写** 指定 HTTP 方法名称。 $filters -------- diff --git a/source/incoming/routing.rst b/source/incoming/routing.rst index 1764e3e8..27ec5773 100755 --- a/source/incoming/routing.rst +++ b/source/incoming/routing.rst @@ -350,12 +350,13 @@ HTTP 动词路由 ================ 你可以通过在控制器之前或之后提供要运行的过滤器来更改特定路由的行为。这在认证或 API 日志记录时特别方便。 + 过滤器的值可以是字符串或字符串数组: * 与 **app/Config/Filters.php** 中定义的别名匹配。 * 过滤器类名 -有关设置过滤器的更多信息,请参阅 :doc:`控制器过滤器 `。 +请参阅 :ref:`控制器过滤器 ` 了解更多关于定义别名的信息。 .. warning:: 如果你在 **app/Config/Routes.php** 中为路由设置过滤器(而不是在 **app/Config/Filters.php** 中) 建议禁用 Auto Routing(传统)。当启用 :ref:`auto-routing-legacy` 时,控制器可能可以通过与配置路由不同的 URL 访问, @@ -364,7 +365,7 @@ HTTP 动词路由 别名过滤器 ------------ -你为过滤器值指定在 **app/Config/Filters.php** 中定义的别名: +你可以为过滤器值指定一个 :ref:`在 app/Config/Filters.php 中定义 ` 的别名。 .. literalinclude:: routing/034.php @@ -377,7 +378,7 @@ HTTP 动词路由 .. versionadded:: 4.1.5 -你可以为过滤器值指定过滤器类名: +你可以为过滤器值指定一个过滤器类名： .. literalinclude:: routing/036.php @@ -394,7 +395,7 @@ HTTP 动词路由 :ref:`从 4.1.4 升级到 4.1.5 ` 了解详情。 -你可以为过滤器值指定一个数组: +你可以为过滤器值指定一个数组： .. literalinclude:: routing/037.php @@ -509,6 +510,8 @@ HTTP 动词路由 过滤器的值必须与 **app/Config/Filters.php** 内定义的别名之一匹配。 +.. note:: 在 v4.5.4 之前，由于一个 bug，传递给 ``group()`` 的过滤器没有合并到传递给内部路由的过滤器中。 + 设置其他选项 ===================== diff --git a/source/installation/upgrade_420.rst b/source/installation/upgrade_420.rst index eaf17c38..69647a48 100644 --- a/source/installation/upgrade_420.rst +++ b/source/installation/upgrade_420.rst @@ -42,6 +42,8 @@ Config/Constants.php composer.json ============= +.. note:: 此步骤在 v4.5.0 或更高版本中不再需要。 + 如果你使用 Composer,在安装 CodeIgniter v4.1.9 或更早版本时,如果 ``/composer.json`` 的 ``autoload.psr-4`` 中存在类似下面的 ``App\\`` 和 ``Config\\`` 命名空间,你需要删除这些行并运行 ``composer dump-autoload``。 .. code-block:: text diff --git a/source/installation/upgrade_454.rst b/source/installation/upgrade_454.rst new file mode 100644 index 00000000..c4a2149c --- /dev/null +++ b/source/installation/upgrade_454.rst @@ -0,0 +1,30 @@ +############################# +从 4.5.3 升级到 4.5.4 +############################# + +请参考与你的安装方法相对应的升级说明。 + +- :ref:`Composer 安装 App Starter 升级 ` +- :ref:`Composer 安装 将 CodeIgniter4 添加到现有项目 升级 ` +- :ref:`手动安装 升级 ` + +.. contents:: + :local: + :depth: 2 + +************* +项目文件 +************* + +**项目空间** （root、app、public、writable）中的一些文件收到了更新。由于这些文件位于 **system** 范围之外，因此不会在没有你干预的情况下更改。 + +.. note:: 有一些第三方的 CodeIgniter 模块可以帮助合并项目空间的更改： + `在 Packagist 上探索 `_。 + +所有更改 +=========== + +这是 **项目空间** 中所有收到更改的文件列表；许多只是简单的注释或格式调整，对运行时没有影响： + +- app/Config/Events.php +- composer.json diff --git a/source/installation/upgrading.rst b/source/installation/upgrading.rst index 5b86966a..993bddf5 100755 --- a/source/installation/upgrading.rst +++ b/source/installation/upgrading.rst @@ -14,6 +14,7 @@ backward_compatibility_notes + upgrade_454 upgrade_453 upgrade_452 upgrade_451 diff --git a/source/libraries/email.rst b/source/libraries/email.rst index 51860900..40131b9b 100644 --- a/source/libraries/email.rst +++ b/source/libraries/email.rst @@ -80,39 +80,40 @@ SMTP 协议的 SSL 与 TLS 电子邮件首选项 ================= -以下是可以在发送电子邮件时设置的所有首选项列表。 +以下是发送电子邮件时可以设置的所有首选项列表。 =================== =================== ============================ ======================================================================= 首选项 默认值 选项 描述 =================== =================== ============================ ======================================================================= -**userAgent** CodeIgniter 无 "用户代理"。 -**protocol** mail ``mail``, ``sendmail``, 邮件发送协议。 +**fromEmail** 在 "from" 标头中设置的电子邮件地址。 +**fromName** 在 "from" 标头中设置的名称。 +**userAgent** CodeIgniter "user agent"。 +**protocol** mail ``mail``，``sendmail``， 邮件发送协议。 或 ``smtp`` -**mailPath** /usr/sbin/sendmail 无 到 Sendmail 的服务器路径。 -**SMTPHost** 无默认值 无 SMTP 服务器主机名。 -**SMTPUser** 无默认值 无 SMTP 用户名。 -**SMTPPass** 无默认值 无 SMTP 密码。 -**SMTPPort** 25 无 SMTP 端口。（如果设置为 ``465``，无论 ``SMTPCrypto`` 设置如何， - 都将使用 TLS 连接。） -**SMTPTimeout** 5 无 SMTP 超时时间（以秒为单位）。 -**SMTPKeepAlive** false ``true``/``false`` (布尔值) 启用持久化的 SMTP 连接。 -**SMTPCrypto** tls ``tls``, ``ssl``, 或 SMTP 加密。将此设置为 ``ssl`` 将使用 SSL 创建一个安全 - 空字符串 (``''``) 通道到服务器，``tls`` 将向服务器发出 - ``STARTTLS`` 命令。在端口 ``465`` 的连接应 - 将此设置为空字符串 (``''``)。请参见 - :ref:`email-ssl-tls-for-smtp`。 -**wordWrap** true ``true``/``false`` (布尔值) 启用自动换行。 -**wrapChars** 76 换行字符数。 -**mailType** text ``text`` 或 ``html`` 邮件类型。如果你发送 HTML 邮件，你必须将其作为一个完整的网页发送。 - 确保你没有任何相对链接或相对图像路径，否则它们将无法工作。 -**charset** utf-8 字符集（``utf-8``, ``iso-8859-1``, 等等）。 -**validate** true ``true``/``false`` (布尔值) 是否验证电子邮件地址。 +**mailPath** /usr/sbin/sendmail Sendmail 的服务器路径。 +**SMTPHost** SMTP 服务器主机名。 +**SMTPUser** SMTP 用户名。 +**SMTPPass** SMTP 密码。 +**SMTPPort** 25 SMTP 端口。（如果设置为 ``465``，则无论 ``SMTPCrypto`` 设置如何， + 都会使用 TLS 进行连接。） +**SMTPTimeout** 5 SMTP 超时时间（以秒为单位）。 +**SMTPKeepAlive** false ``true``/``false`` 启用持久的 SMTP 连接。 +**SMTPCrypto** tls ``tls``，``ssl``，或 SMTP 加密。将此设置为 ``ssl`` 将使用 SSL 创建到服务器的安全通道， + 而 ``tls`` 将向服务器发出 + 空字符串（``''``） ``STARTTLS`` 命令。在端口 ``465`` 上连接应将此设置为空字符串 (``''``)。 + 另请参见 :ref:`email-ssl-tls-for-smtp`。 +**wordWrap** true ``true``/``false`` 启用自动换行。 +**wrapChars** 76 换行的字符数。 +**mailType** text ``text`` 或 ``html`` 邮件类型。如果发送 HTML 邮件，必须将其作为完整的网页发送。 + 确保没有任何相对链接或相对图像路径，否则它们将无法工作。 +**charset** UTF-8 字符集 (``utf-8``，``iso-8859-1`` 等)。 +**validate** true ``true``/``false`` 是否验证电子邮件地址。 **priority** 3 1, 2, 3, 4, 5 邮件优先级。``1`` = 最高。``5`` = 最低。``3`` = 正常。 -**CRLF** \\n ``\r\n`` 或 ``\n`` 或 ``\r`` 换行字符。（使用 ``\r\n`` 以符合 RFC 822）。 -**newline** \\n ``\r\n`` 或 ``\n`` 或 ``\r`` 换行字符。（使用 ``\r\n`` 以符合 RFC 822）。 -**BCCBatchMode** false ``true``/``false`` (布尔值) 启用 BCC 批处理模式。 -**BCCBatchSize** 200 无 每个 BCC 批次的电子邮件数量。 -**DSN** false ``true``/``false`` (布尔值) 启用来自服务器的通知消息。 +**CRLF** \\r\\n ``\r\n``，``\n`` 或 ``\r`` 换行符。（使用 ``\r\n`` 以符合 RFC 822）。 +**newline** \\r\\n ``\r\n``，``\n`` 或 ``\r`` 换行符。（使用 ``\r\n`` 以符合 RFC 822）。 +**BCCBatchMode** false ``true``/``false`` 启用 BCC 批处理模式。 +**BCCBatchSize** 200 每个 BCC 批次中的电子邮件数量。 +**DSN** false ``true``/``false`` 启用来自服务器的通知消息。 =================== =================== ============================ ======================================================================= 覆盖文字换行 @@ -139,40 +140,40 @@ CodeIgniter 允许你在消息的一部分手动覆盖文字换行,如下所示: .. php:method:: setFrom($from[, $name = ''[, $returnPath = null]]) - :param string $from: “From” 电子邮件地址 - :param string $name: “From” 显示名称 - :param string $returnPath: 可选的电子邮件地址,用于重定向未送达的电子邮件 - :returns: CodeIgniter\\Email\\Email 实例(方法链式调用) + :param string $from: "From" 电子邮件地址 + :param string $name: "From" 显示名称 + :param string $returnPath: 可选的电子邮件地址，用于重定向未送达的邮件 + :returns: CodeIgniter\\Email\\Email 实例（方法链） :rtype: CodeIgniter\\Email\\Email - 设置发送电子邮件的电子邮件地址和名称: + 设置发送电子邮件的人的电子邮件地址和名称： .. literalinclude:: email/003.php - 你还可以设置 Return-Path 来帮助重定向未送达的邮件: + 你还可以设置 Return-Path，以帮助重定向未送达的邮件： .. literalinclude:: email/004.php - .. note:: 如果你已将协议配置为 'smtp',则无法使用 Return-Path。 + .. note:: 如果你将协议配置为 'smtp'，则不能使用 Return-Path。 .. php:method:: setReplyTo($replyto[, $name = '']) - :param string $replyto: 回复电子邮件地址 + :param string $replyto: 回复的电子邮件地址 :param string $name: 回复电子邮件地址的显示名称 - :returns: CodeIgniter\\Email\\Email 实例(方法链式调用) + :returns: CodeIgniter\\Email\\Email 实例（方法链） :rtype: CodeIgniter\\Email\\Email - 设置回复地址。如果没有提供信息,将使用 `setFrom <#setFrom>`_ 方法中的信息。例如: + 设置回复地址。如果未提供信息，则使用 `setFrom <#setFrom>`_ 方法中的信息。示例： .. literalinclude:: email/005.php .. php:method:: setTo($to) - :param mixed $to: 逗号分隔的电子邮件地址字符串或电子邮件地址数组 - :returns: CodeIgniter\\Email\\Email 实例(方法链式调用) + :param mixed $to: 逗号分隔的字符串或电子邮件地址数组 + :returns: CodeIgniter\\Email\\Email 实例（方法链） :rtype: CodeIgniter\\Email\\Email - 设置收件人的电子邮件地址。可以是单个电子邮件,用逗号分隔的列表或数组: + 设置收件人的电子邮件地址。可以是单个电子邮件、逗号分隔的列表或数组： .. literalinclude:: email/006.php @@ -182,138 +183,138 @@ CodeIgniter 允许你在消息的一部分手动覆盖文字换行,如下所示: .. php:method:: setCC($cc) - :param mixed $cc: 逗号分隔的电子邮件地址字符串或电子邮件地址数组 - :returns: CodeIgniter\\Email\\Email 实例(方法链式调用) + :param mixed $cc: 逗号分隔的字符串或电子邮件地址数组 + :returns: CodeIgniter\\Email\\Email 实例（方法链） :rtype: CodeIgniter\\Email\\Email - 设置抄送电子邮件地址。就像“to”,可以是单个电子邮件、用逗号分隔的列表或数组。 + 设置 CC 电子邮件地址。就像 "to" 一样，可以是单个电子邮件、逗号分隔的列表或数组。 .. php:method:: setBCC($bcc[, $limit = '']) - :param mixed $bcc: 逗号分隔的电子邮件地址字符串或电子邮件地址数组 - :param int $limit: 每批发送的最大电子邮件数 - :returns: CodeIgniter\\Email\\Email 实例(方法链式调用) + :param mixed $bcc: 逗号分隔的字符串或电子邮件地址数组 + :param int $limit: 每批发送的最大电子邮件数量 + :returns: CodeIgniter\\Email\\Email 实例（方法链） :rtype: CodeIgniter\\Email\\Email - 设置密送电子邮件地址。就像 ``setTo()`` 方法一样,可以是单个电子邮件、用逗号分隔的列表或数组。 + 设置 BCC 电子邮件地址。就像 ``setTo()`` 方法一样，可以是单个电子邮件、逗号分隔的列表或数组。 - 如果设置了 ``$limit``,将启用“批量模式”,它将以不超过指定的 ``$limit`` 为一批发送电子邮件。 + 如果设置了 ``$limit``，将启用“批处理模式”，这将按批次发送电子邮件，每批次不超过指定的 ``$limit``。 .. php:method:: setSubject($subject) :param string $subject: 电子邮件主题 - :returns: CodeIgniter\\Email\\Email 实例(方法链式调用) + :returns: CodeIgniter\\Email\\Email 实例（方法链） :rtype: CodeIgniter\\Email\\Email - 设置电子邮件主题: + 设置电子邮件主题： .. literalinclude:: email/009.php .. php:method:: setMessage($body) - :param string $body: 电子邮件消息体 - :returns: CodeIgniter\\Email\\Email 实例(方法链式调用) + :param string $body: 电子邮件正文 + :returns: CodeIgniter\\Email\\Email 实例（方法链） :rtype: CodeIgniter\\Email\\Email - 设置电子邮件消息体: + 设置电子邮件正文： .. literalinclude:: email/010.php .. php:method:: setAltMessage($str) - :param string $str: 备用电子邮件消息体 - :returns: CodeIgniter\\Email\\Email 实例(方法链式调用) + :param string $str: 替代电子邮件正文 + :returns: CodeIgniter\\Email\\Email 实例（方法链） :rtype: CodeIgniter\\Email\\Email - 设置备用电子邮件消息体: + 设置替代电子邮件正文： .. literalinclude:: email/011.php - 如果你发送 HTML 格式的电子邮件,这是一个可选的消息字符串,可以使用它。它允许你指定一个不含 HTML 格式的备用消息,该消息将添加到头字符串中,供不接受 HTML 电子邮件的人使用。如果你没有设置自己的消息,CodeIgniter 将从你的 HTML 电子邮件中提取消息并剥离标签。 + 这是一个可选的消息字符串，可以在你发送 HTML 格式的电子邮件时使用。它允许你指定一个没有 HTML 格式的替代消息，该消息将添加到头字符串中，以便那些不接受 HTML 电子邮件的人使用。如果你没有设置自己的消息，CodeIgniter 将从你的 HTML 电子邮件中提取消息并去除标签。 .. php:method:: setHeader($header, $value) - :param string $header: 标题名称 - :param string $value: 标题值 - :returns: CodeIgniter\\Email\\Email 实例(方法链式调用) + :param string $header: 头名称 + :param string $value: 头值 + :returns: CodeIgniter\\Email\\Email 实例（方法链） :rtype: CodeIgniter\\Email\\Email - 追加其他标题到电子邮件: + 向电子邮件添加附加头： .. literalinclude:: email/012.php .. php:method:: clear($clearAttachments = false) :param bool $clearAttachments: 是否清除附件 - :returns: CodeIgniter\\Email\\Email 实例(方法链式调用) - :rtype: CodeIgniter\\Email\\Email + :returns: CodeIgniter\\Email\\Email 实例（方法链） + :rtype: CodeIgniter\\Email\\Email - 将所有电子邮件变量初始化为空状态。如果你在循环中运行电子邮件发送方法,这种方法很有用,它允许在循环之间重置数据。 + 将所有电子邮件变量初始化为空状态。此方法旨在用于在循环中运行电子邮件发送方法，允许在循环之间重置数据。 .. literalinclude:: email/013.php - 如果你将参数设置为 true,任何附件也将被清除: + 如果将参数设置为 true，任何附件也将被清除： .. literalinclude:: email/014.php .. php:method:: send($autoClear = true) :param bool $autoClear: 是否自动清除消息数据 - :returns: 成功为 true,失败为 false + :returns: 成功时返回 true，失败时返回 false :rtype: bool - 电子邮件发送方法。根据成功或失败返回布尔值 true 或 false,使其可用于条件语句: + 电子邮件发送方法。根据成功或失败返回布尔值 true 或 false，使其可以有条件地使用： .. literalinclude:: email/015.php - 如果请求成功,此方法将自动清除所有参数。要停止此行为,请传递 false: + 如果请求成功，此方法将自动清除所有参数。要停止此行为，请传递 false： .. literalinclude:: email/016.php - .. note:: 为了使用 ``printDebugger()`` 方法,你需要避免清除电子邮件参数。 + .. note:: 为了使用 ``printDebugger()`` 方法，你需要避免清除电子邮件参数。 - .. note:: 如果启用了 ``BCCBatchMode``,收件人多于 ``BCCBatchSize``,此方法将始终返回布尔值 ``true``。 + .. note:: 如果启用了 ``BCCBatchMode``，并且收件人超过 ``BCCBatchSize``，此方法将始终返回布尔值 ``true``。 .. php:method:: attach($filename[, $disposition = ''[, $newname = null[, $mime = '']]]) :param string $filename: 文件名 - :param string $disposition: 附件的 'disposition'。大多数电子邮件客户端会忽略这里使用的 MIME 规范并自行决定。https://www.iana.org/assignments/cont-disp/cont-disp.xhtml - :param string $newname: 要在电子邮件中使用的自定义文件名 - :param string $mime: 要使用的 MIME 类型(对缓冲数据有用) - :returns: CodeIgniter\\Email\\Email 实例(方法链式调用) + :param string $disposition: 附件的 'disposition'。大多数电子邮件客户端会根据此处使用的 MIME 规范自行决定。https://www.iana.org/assignments/cont-disp/cont-disp.xhtml + :param string $newname: 在电子邮件中使用的自定义文件名 + :param string $mime: 要使用的 MIME 类型（对缓冲数据有用） + :returns: CodeIgniter\\Email\\Email 实例（方法链） :rtype: CodeIgniter\\Email\\Email - 启用你发送一个附件。在第一个参数中放置文件路径/名称。对于多个附件,多次使用该方法。例如: + 允许你发送附件。将文件路径/名称放在第一个参数中。对于多个附件，请多次使用该方法。例如： .. literalinclude:: email/017.php - 要使用默认 disposition(attachment),请将第二个参数留空,否则使用自定义 disposition: + 要使用默认的 disposition（附件），请将第二个参数留空，否则使用自定义 disposition： .. literalinclude:: email/018.php - 你也可以使用 URL: + 你还可以使用 URL： .. literalinclude:: email/019.php - 如果你想使用自定义文件名,可以使用第三个参数: + 如果你想使用自定义文件名，可以使用第三个参数： .. literalinclude:: email/020.php - 如果你需要使用缓冲字符串而不是真实的物理文件,可以使用第一个参数作为缓冲区,第三个参数作为文件名,第四个参数为 MIME 类型: + 如果你需要使用缓冲字符串而不是实际的物理文件，可以将第一个参数用作缓冲区，第三个参数用作文件名，第四个参数用作 MIME 类型： .. literalinclude:: email/021.php .. php:method:: setAttachmentCID($filename) :param string $filename: 已存在的附件文件名 - :returns: 附件内容 ID,如果未找到则为 false + :returns: 附件内容 ID 或未找到时返回 false :rtype: string - 设置并返回附件的内容 ID,这使你可以将内嵌(图片)附件嵌入 HTML 中。第一个参数必须已附加的文件名。 + 设置并返回附件的内容 ID，这使你能够将内嵌（图片）附件嵌入 HTML 中。第一个参数必须是已附加的文件名。 .. literalinclude:: email/022.php - .. note:: 为了使内容 ID 在每封电子邮件中都是唯一的,必须对其进行重新创建。 + .. note:: 每封电子邮件的内容 ID 必须重新创建以确保其唯一性。 .. php:method:: printDebugger($include = ['headers', 'subject', 'body']) @@ -321,12 +322,12 @@ CodeIgniter 允许你在消息的一部分手动覆盖文字换行,如下所示: :returns: 格式化的调试数据 :rtype: string - 返回包含任何服务器消息、电子邮件标头和电子邮件消息的字符串。用于调试。 + 返回包含任何服务器消息、电子邮件头和电子邮件消息的字符串。对调试很有用。 - 你可以选择只打印指定的消息部分。有效选项为:**headers**、**subject**、**body**。 + 你可以选择性地指定应打印消息的哪些部分。有效选项是：**headers**、**subject**、**body**。 - 例如: + 示例： .. literalinclude:: email/023.php - .. note:: 默认情况下,所有原始数据都将被打印。 + .. note:: 默认情况下，将打印所有原始数据。 diff --git a/source/libraries/files.rst b/source/libraries/files.rst index 75cf7119..a26f07f3 100755 --- a/source/libraries/files.rst +++ b/source/libraries/files.rst @@ -12,9 +12,12 @@ CodeIgniter 提供了一个 File 类,它封装了 `SplFileInfo isReferral()) { - echo $agent->referrer(); + echo $agent->getReferrer(); } diff --git a/source/libraries/validation.rst b/source/libraries/validation.rst index b27c0d6a..0381d3e6 100755 --- a/source/libraries/validation.rst +++ b/source/libraries/validation.rst @@ -759,11 +759,9 @@ PHP 请求之间不共享任何内容。所以在验证失败时重定向,重定 规则 参数 描述 示例 ======================= ========== ================================================================= =================================================== alpha 无 如果字段包含除 ASCII 字母字符之外的任何内容,则失败。 -alpha_space 无 如果字段包含 ASCII 空格和字母字符之外的任何内容,则失败。 alpha_dash 无 如果字段包含除 ASCII 字母数字字符、下划线或破折号之外的任何内容, 则失败。 alpha_numeric 无 如果字段包含除 ASCII 字母数字字符之外的任何内容,则失败。 -alpha_numeric_space 无 如果字段包含除 ASCII 字母数字和空格字符之外的任何内容,则失败。 alpha_numeric_punct 无 如果字段包含除字母数字、空格和这组有限标点之外的任何内容, 则失败:``~`` (波浪号)、 ``!`` (感叹号)、``#`` (数字)、 @@ -772,6 +770,8 @@ alpha_numeric_punct 无 如果字段包含除字母数字、空格 ``_`` (下划线), ``+`` (加号), ``=`` (等号), ``|`` (竖线), ``:`` (冒号), ``.`` (句点)。 +alpha_numeric_space 无 如果字段包含除 ASCII 字母数字和空格字符之外的任何内容,则失败。 +alpha_space 无 如果字段包含 ASCII 空格和字母字符之外的任何内容,则失败。 decimal 无 如果字段包含除十进制数字外的任何内容,则失败。 也接受数字前的 ``+`` 或 ``-`` 号。 differs 是 如果字段与参数中字段的值不不同,则失败。 ``differs[field_name]`` @@ -784,8 +784,10 @@ hex 无 如果字段包含除十六进制字符之 if_exist 无 如果存在此规则,验证将仅在要验证的数据中存在字段键时检查该字段。 in_list 是 如果字段不在预定列表中,则失败。 ``in_list[red,blue,green]`` integer 无 如果字段包含除整数之外的任何内容,则失败。 -is_natural 无 如果字段包含除自然数之外的任何内容,则失败:0, 1, 2, 3等。 -is_natural_no_zero 无 如果字段包含除自然数和零之外的任何内容,则失败:1, 2, 3等。 +is_natural 无 如果字段包含除自然数之外的任何内容,则失败: ``0``, ``1``, ``2``, + ``3`` 等。 +is_natural_no_zero 无 如果字段包含除自然数和零之外的任何内容,则失败: ``1``, ``2``, + ``3`` 等。 is_not_unique 是 检查数据库中是否存在给定的值。 可以通过字段/值过滤器忽略记录(当前只接受一个过滤器)。 is_unique 是 检查字段值是否存在于数据库中。可以可选地设置要忽略的列和值, @@ -797,30 +799,14 @@ max_length 是 如果字段长于参数值,则失败。 min_length 是 如果字段短于参数值,则失败。 ``min_length[3]`` not_in_list 是 如果字段在预定列表中,则失败。 ``not_in_list[red,blue,green]`` numeric 无 如果字段包含除数字外的任何内容,则失败。 -regex_match 是 如果字段不匹配正则表达式,则失败。 ``regex_match[/regex/]`` permit_empty 无 允许字段接收空数组、空字符串、null 或 false。 +regex_match 是 如果字段不匹配正则表达式,则失败。 ``regex_match[/regex/]`` required 无 如果字段为空数组、空字符串、null 或 false,则失败。 required_with 是 当数据中任何其他字段不为空时,该字段是必需的。 ``required_with[field1,field2]`` required_without 是 当数据中任何其他字段为空时,该字段是必需的。 ``required_without[field1,field2]`` -string 无 alpha* 规则的通用替代,确认元素是一个字符串。 +string 无 **alpha** 规则的通用替代,确认元素是一个字符串。 timezone 无 如果字段不匹配 `timezone_identifiers_list()`_ 中的时区,则失败。 valid_base64 无 如果字段包含除有效的 Base64 字符之外的任何内容,则失败。 -valid_json 无 如果字段不包含有效的 JSON 字符串,则失败。 -valid_email 无 如果字段不包含有效的电子邮件地址,则失败。 -valid_emails 无 如果任何以逗号分隔提供的值不是有效的电子邮件,则失败。 -valid_ip 是 如果提供的 IP 无效,则失败。 - 可选参数为 ``ipv4`` 或 ``valid_ip[ipv6]`` - ``ipv6`` 以指定 IP 格式。 -valid_url 无 如果字段不包含(宽松的)URL,则失败。 - 包括可能是主机名的简单字符串, - 如“codeigniter”。**通常,应使用** ``valid_url_strict``。 -valid_url_strict 是 如果字段不包含有效的 URL,则失败。你可以可选地指定 ``valid_url_strict[https]`` - 有效 schema 的列表。如果未指定, ``http,https`` - 有效。此规则使用 PHP 的 ``FILTER_VALIDATE_URL``。 -valid_date 是 如果字段不包含有效日期，则验证失败。 ``valid_date[d/m/Y]`` - 任何 `strtotime()`_ 接受的字符串都是有效的， - 前提是你没有指定一个匹配日期格式的可选参数。 - **因此，通常有必要指定该参数。** valid_cc_number 是 验证信用卡号是否与指定提供程序使用的格式匹配。 ``valid_cc_number[amex]`` 当前支持的提供程序有: 美国运通 (``amex``)、 @@ -840,10 +826,27 @@ valid_cc_number 是 验证信用卡号是否与指定提供程 Scotiabank 圣哥伦布卡 (``scotia``)、 BMO 自动柜员机卡 (``bmoabm``)、 HSBC 加拿大卡 (``hsbc``) +valid_json 无 如果字段不包含有效的 JSON 字符串,则失败。 +valid_email 无 如果字段不包含有效的电子邮件地址,则失败。 +valid_emails 无 如果任何以逗号分隔提供的值不是有效的电子邮件,则失败。 +valid_ip 是 如果提供的 IP 无效,则失败。 + 可选参数为 ``ipv4`` 或 ``valid_ip[ipv6]`` + ``ipv6`` 以指定 IP 格式。 +valid_url 无 如果字段不包含(宽松的)URL,则失败。 + 包括可能是主机名的简单字符串, + 如“codeigniter”。**通常,应使用** ``valid_url_strict``。 +valid_url_strict 是 如果字段不包含有效的 URL,则失败。你可以可选地指定 ``valid_url_strict[https]`` + 有效 schema 的列表。如果未指定, ``http,https`` + 有效。此规则使用 PHP 的 ``FILTER_VALIDATE_URL``。 +valid_date 是 如果字段不包含有效日期，则验证失败。 ``valid_date[d/m/Y]`` + 任何 `strtotime()`_ 接受的字符串都是有效的， + 前提是你没有指定一个匹配日期格式的可选参数。 + **因此，通常有必要指定该参数。** ======================= ========== ================================================================= =================================================== -.. note:: 你也可以使用任何返回布尔值且至少接受一个要验证的数据的参数的原生 PHP 函数。 - 验证库 **从不改变** 要验证的数据。 +.. note:: 你也可以使用任何返回布尔值并且至少允许一个参数（要验证的字段数据）的原生 PHP 函数。 + +.. important:: 验证库 **从不更改** 要验证的数据。 .. _timezone_identifiers_list(): https://www.php.net/manual/en/function.timezone-identifiers-list.php .. _strtotime(): https://www.php.net/manual/en/function.strtotime.php