From cc80f95b27579b5d56af4d81d2bf07331b27d00c Mon Sep 17 00:00:00 2001 From: Hex Date: Thu, 11 Jul 2024 00:19:39 +0800 Subject: [PATCH] =?UTF-8?q?=E5=8D=87=E7=BA=A7=E5=88=B0=204.5.3=20(#165)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- source/_static/css/citheme.css | 5 +++ source/changelogs/index.rst | 2 + source/changelogs/v4.5.2.rst | 25 +++++++++++ source/changelogs/v4.5.3.rst | 19 ++++++++ source/cli/cli_request.rst | 2 +- source/concepts/autoloader.rst | 4 +- source/concepts/factories.rst | 6 +++ source/concepts/goals.rst | 15 +++++++ source/concepts/index.rst | 1 + source/concepts/services.rst | 14 +++--- source/concepts/services/002.php | 3 ++ source/concepts/services/012.php | 2 +- source/concepts/services/013.php | 2 +- source/concepts/services/014.php | 2 +- source/concepts/services/015.php | 4 +- source/concepts/structure.rst | 30 +++++++++---- source/conf.py | 2 +- source/database/configuration.rst | 14 +++--- source/database/examples.rst | 6 +-- source/database/helpers.rst | 2 - source/database/metadata.rst | 4 +- source/database/query_builder.rst | 9 ++-- source/database/results.rst | 2 + source/database/utilities.rst | 2 +- source/dbmgmt/forge.rst | 2 +- source/dbmgmt/index.rst | 2 +- source/dbmgmt/migration.rst | 22 ++++----- source/extending/basecontroller/003.php | 2 +- source/extending/core_classes.rst | 2 +- source/extending/events.rst | 4 +- source/general/common_functions.rst | 19 ++++---- source/general/errors.rst | 19 +++++--- source/general/errors/012.php | 9 ++-- source/general/errors/013.php | 7 +-- source/general/errors/018.php | 2 +- source/general/managing_apps.rst | 21 ++------- source/general/modules.rst | 6 +-- source/helpers/form_helper.rst | 41 +++++++++-------- source/incoming/content_negotiation/001.php | 2 +- source/incoming/filters.rst | 2 + source/incoming/incomingrequest/002.php | 2 +- source/incoming/incomingrequest/003.php | 2 +- source/incoming/routing.rst | 8 ++-- source/incoming/routing/026.php | 4 +- source/installation/deployment.rst | 2 + source/installation/upgrade_452.rst | 38 ++++++++++++++++ source/installation/upgrade_453.rst | 39 ++++++++++++++++ source/installation/upgrade_4xx.rst | 2 +- source/installation/upgrade_responses.rst | 7 +-- source/installation/upgrading.rst | 2 + source/intro/requirements.rst | 2 +- source/libraries/caching.rst | 17 ++++--- source/libraries/caching/002.php | 2 +- source/libraries/cookies.rst | 10 ++--- source/libraries/cookies/002.php | 2 +- source/libraries/cookies/003.php | 2 +- source/libraries/cookies/007.php | 4 +- source/libraries/cookies/009.php | 3 +- source/libraries/cookies/010.php | 2 +- source/libraries/cookies/013.php | 4 +- source/libraries/cookies/014.php | 1 - source/libraries/cookies/015.php | 6 +-- source/libraries/cookies/017.php | 3 +- source/libraries/curlrequest.rst | 2 +- source/libraries/curlrequest/002.php | 3 ++ source/libraries/curlrequest/003.php | 2 +- source/libraries/curlrequest/004.php | 6 ++- source/libraries/curlrequest/005.php | 2 +- source/libraries/curlrequest/008.php | 2 +- source/libraries/curlrequest/009.php | 4 +- source/libraries/curlrequest/012.php | 2 +- source/libraries/email/001.php | 2 +- source/libraries/encryption/001.php | 2 +- source/libraries/encryption/003.php | 6 ++- source/libraries/encryption/013.php | 3 +- source/libraries/file_collections.rst | 11 +++-- source/libraries/files/012.php | 2 +- source/libraries/files/014.php | 2 + source/libraries/honeypot.rst | 8 ++-- source/libraries/images.rst | 4 +- source/libraries/images/001.php | 2 +- source/libraries/images/002.php | 2 +- source/libraries/images/007.php | 2 +- source/libraries/images/008.php | 4 +- source/libraries/images/009.php | 2 +- source/libraries/images/010.php | 2 +- source/libraries/images/011.php | 4 +- source/libraries/images/012.php | 2 +- source/libraries/images/013.php | 2 +- source/libraries/images/014.php | 2 +- source/libraries/pagination/001.php | 2 +- source/libraries/pagination/002.php | 4 +- source/libraries/pagination/003.php | 4 +- source/libraries/pagination/004.php | 7 ++- source/libraries/pagination/005.php | 4 +- source/libraries/pagination/018.php | 4 +- source/libraries/security.rst | 2 + source/libraries/security/001.php | 2 +- source/libraries/sessions.rst | 34 +++++++------- source/libraries/sessions/001.php | 2 +- source/libraries/throttler/001.php | 2 +- source/libraries/throttler/002.php | 5 +-- source/libraries/time.rst | 49 +++++++++++---------- source/libraries/typography/001.php | 2 +- source/libraries/uploaded_files.rst | 34 +++++++++----- source/libraries/uri.rst | 14 +++--- source/libraries/validation.rst | 28 +++++++----- source/libraries/validation/004.php | 2 +- source/libraries/validation/008.php | 4 +- source/libraries/validation/037.php | 2 +- source/libraries/validation/044.php | 2 +- source/libraries/validation/046.php | 4 +- source/models/model.rst | 20 +++++---- source/outgoing/index.rst | 2 +- source/outgoing/localization.rst | 8 +++- source/outgoing/response.rst | 2 +- source/outgoing/table.rst | 2 +- source/outgoing/view_cells.rst | 4 ++ source/outgoing/view_cells/023.php | 13 ++++++ source/outgoing/view_decorators.rst | 16 ++++++- source/outgoing/view_decorators/002.php | 4 +- source/outgoing/view_parser.rst | 10 +++-- source/outgoing/view_parser/001.php | 2 +- source/outgoing/view_renderer/001.php | 2 +- source/outgoing/views.rst | 4 ++ source/testing/benchmark/001.php | 8 ++-- source/testing/overview.rst | 15 +++++-- 127 files changed, 590 insertions(+), 325 deletions(-) create mode 100644 source/changelogs/v4.5.2.rst create mode 100644 source/changelogs/v4.5.3.rst create mode 100644 source/concepts/goals.rst create mode 100644 source/installation/upgrade_452.rst create mode 100644 source/installation/upgrade_453.rst create mode 100644 source/outgoing/view_cells/023.php diff --git a/source/_static/css/citheme.css b/source/_static/css/citheme.css index 58de483c..7a654b54 100644 --- a/source/_static/css/citheme.css +++ b/source/_static/css/citheme.css @@ -245,6 +245,11 @@ html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not( background-color: #fffff0; } +span.std, +span.pre { + text-wrap: nowrap; +} + /* Messages ----------------------------------------------------------------- */ .rst-content .success { diff --git a/source/changelogs/index.rst b/source/changelogs/index.rst index a8a000f9..b03b6795 100644 --- a/source/changelogs/index.rst +++ b/source/changelogs/index.rst @@ -12,6 +12,8 @@ .. toctree:: :titlesonly: + v4.5.3 + v4.5.2 v4.5.1 v4.5.0 v4.4.8 diff --git a/source/changelogs/v4.5.2.rst b/source/changelogs/v4.5.2.rst new file mode 100644 index 00000000..bfdf4526 --- /dev/null +++ b/source/changelogs/v4.5.2.rst @@ -0,0 +1,25 @@ +############# +版本 4.5.2 +############# + +发布日期：2024年6月10日 + +**CodeIgniter4 的 4.5.2 版本发布** + +.. contents:: + :local: + :depth: 3 + +*************** +消息变更 +*************** + +- 添加了 ``Security.insecureCookie`` 消息。 + +********** +修复的错误 +********** + +请查看仓库的 +`CHANGELOG.md `_ +以获取修复错误的完整列表。 diff --git a/source/changelogs/v4.5.3.rst b/source/changelogs/v4.5.3.rst new file mode 100644 index 00000000..2e8c20fa --- /dev/null +++ b/source/changelogs/v4.5.3.rst @@ -0,0 +1,19 @@ +############# +版本 4.5.3 +############# + +发布日期：2024年6月25日 + +**CodeIgniter4 的 4.5.3 版本发布** + +.. contents:: + :local: + :depth: 3 + +********** +修复的错误 +********** + +请查看仓库的 +`CHANGELOG.md `_ +以获取修复错误的完整列表。 diff --git a/source/cli/cli_request.rst b/source/cli/cli_request.rst index 7c0aeff0..94a8f7c1 100644 --- a/source/cli/cli_request.rst +++ b/source/cli/cli_request.rst @@ -29,7 +29,7 @@ getOptions() .. literalinclude:: cli_request/003.php -getOption($which) +getOption($key) ----------------- 返回被视为选项的特定命令行参数的值: diff --git a/source/concepts/autoloader.rst b/source/concepts/autoloader.rst index 4d858cf1..81155944 100755 --- a/source/concepts/autoloader.rst +++ b/source/concepts/autoloader.rst @@ -45,7 +45,7 @@ CodeIgniter 提供了一个非常灵活的自动加载器，只需进行很少 每行的键是命名空间本身。这个不需要尾部反斜杠。 值是可以找到类的目录位置。 -默认情况下，命名空间 ``App`` 位于 **app** 目录中，命名空间 ``Config`` 位于 ``app/Config`` 目录中。 +默认情况下，命名空间 ``App`` 位于 **app** 目录中，命名空间 ``Config`` 位于 **app/Config** 目录中。 如果你在这些位置根据 `PSR-4`_ 创建类文件，自动加载器将自动加载它们。 @@ -72,6 +72,8 @@ Config 命名空间 配置文件位于 ``Config`` 命名空间中，而不是你可能预期的 ``App\Config`` 中。这使得核心系统文件即使在应用命名空间发生变化时也能始终找到它们。 +.. note:: 自 v4.5.3 appstarter 版本起，``Config\\`` 命名空间已被添加到 **composer.json** 的 ``autoload.psr-4`` 中。 + 更改应用命名空间 ---------------------- diff --git a/source/concepts/factories.rst b/source/concepts/factories.rst index be95a2ad..80745040 100644 --- a/source/concepts/factories.rst +++ b/source/concepts/factories.rst @@ -72,6 +72,8 @@ .. literalinclude:: factories/013.php :lines: 2- +.. _factories-passing-fully-qualified-classname: + 传递完全限定类名 -------------------------------- @@ -229,6 +231,8 @@ setOptions 方法 .. versionadded:: 4.4.0 +.. important:: 除非你已经仔细阅读了这一节并理解了这个功能是如何工作的，否则不要使用这个功能。否则，你的应用程序将无法正常工作。 + 为了提高性能，实现了配置缓存。 先决条件 @@ -242,6 +246,8 @@ setOptions 方法 工作原理 ============ +.. important:: 一旦缓存，配置值在缓存被删除之前永远不会改变，即使配置文件或 **.env** 发生了变化。 + - 如果 Factories 中的 Config 实例的状态发生变化，则在关闭之前将所有 Config 实例保存到缓存文件中。 - 如果有缓存可用，则在 CodeIgniter 初始化之前恢复缓存的 Config 实例。 diff --git a/source/concepts/goals.rst b/source/concepts/goals.rst new file mode 100644 index 00000000..8837e666 --- /dev/null +++ b/source/concepts/goals.rst @@ -0,0 +1,15 @@ +############################## +设计与架构目标 +############################## + +CodeIgniter 的目标是在最小化，最轻量级的开发包中得到最大的执行效率、功能和灵活性。 + +为了达到这个目标，我们在开发过程的每一步都致力于基准测试、重构和简化工作，拒绝加入任何对实现目标没有帮助的东西。 + +从技术和架构角度看，CodeIgniter 按照下列目标创建： + +- **动态实例化。** 在 CodeIgniter 中，组件的导入和函数的执行都是在被请求的时候才执行，而不是全局的。除核心资源外，系统不需要任何其他资源，因此系统默认是非常轻量级的。HTTP 请求所触发的事件以及你设计的控制器和视图将决定哪些资源是需要加载的。 +- **低耦合。** 耦合是指一个系统中组件之间的依赖程度。组件之间的依赖程度越低，系统的重用性和灵活性就越好。我们的目标就是打造一个低耦合的系统。 +- **组件专一性。** 专一性指的是组件对某个目标的专注程度。在 CodeIgniter 中，每一个类和方法都是高度独立的，从而可以最大程度地被复用。 + +CodeIgniter 是一个动态实例化，高度组件专一性的低耦合系统。它在小巧的基础上力求做到简单、灵活和高性能。 diff --git a/source/concepts/index.rst b/source/concepts/index.rst index 88e26fa1..ee8b1fbe 100755 --- a/source/concepts/index.rst +++ b/source/concepts/index.rst @@ -14,3 +14,4 @@ CodeIgniter4 概览 factories http security + goals diff --git a/source/concepts/services.rst b/source/concepts/services.rst index b39b7c1b..24e8c714 100755 --- a/source/concepts/services.rst +++ b/source/concepts/services.rst @@ -16,16 +16,16 @@ CodeIgniter 4 中的 **服务** 提供了创建和共享新类实例的功能。 CodeIgniter 的所有核心类都以“服务”提供。这仅仅意味着,不是硬编码一个类名进行加载,而是在一个非常简单的配置文件中定义要调用的类。这个文件充当工厂的角色,用来创建所需类的新实例。 -为什么使用服务? +为什么使用服务？ ================= -一个快速的示例可能会使事情更清楚,所以想象一下,你需要获取 Timer 类的一个实例。最简单的方法就是简单地创建该类的一个新实例: +一个快速的例子可能会让事情更清晰，所以想象一下你需要引入一个 Timer 类的实例。最简单的方法可能就是直接创建这个类的一个新的实例： .. literalinclude:: services/001.php -这工作得很好。直到你决定要使用另一个定时器类来替换它。也许这个定时器类具有默认定时器不提供的一些高级报告功能。为了做到这一点,你现在需要找到应用程序中使用了定时器类的所有位置。由于你可能已经将它们保留在那里以便持续运行性能日志,所以这可能是一个非常耗时且容易出错的处理方法。这就是服务派上用场的地方。 +这工作得很好。直到你决定用一个不同的计时器类来替代它。也许这个类有一些默认计时器不提供的高级报告功能。为了做到这一点，现在你必须找到你应用程序中使用计时器类的所有位置。由于你可能已经将它们保留下来，以持续运行应用程序的性能日志，这可能是一个耗时且容易出错的处理方式。这就是服务派上用场的地方。 -与其自己创建实例,不如让一个中心类为我们创建类的实例。这个类非常简单。它只包含每个我们希望用作服务的类的方法。该方法通常返回该类的一个共享实例,并将它可能具有的任何依赖项传递给它。然后,我们将用调用此新类的代码替换定时器创建代码: +我们不是自己创建实例，而是让一个中心类为我们创建类的实例。这个类保持非常简单。它只包含我们想要作为服务使用的每个类的方法。该方法通常返回该类的 **共享实例**，并将任何它可能具有的依赖项传递给它。然后，我们将替换我们的计时器创建代码，使用调用这个全局函数或服务类的代码： .. literalinclude:: services/002.php @@ -40,7 +40,7 @@ CodeIgniter 的所有核心类都以“服务”提供。这仅仅意味着,不 .. literalinclude:: services/013.php -``$typography`` 是一个 Typography 类的实例,如果你再次调用 ``\Config\Services::typography()``,你将会得到完全相同的实例。 +``$timer`` 是一个 Timer 类的实例，如果你再次调用 ``service('timer')``，你将会得到完全相同的实例。 服务通常返回类的共享实例。下面的代码在首次调用时创建一个 ``CURLRequest`` 实例。第二次调用返回完全相同的实例。 @@ -51,7 +51,7 @@ CodeIgniter 的所有核心类都以“服务”提供。这仅仅意味着,不 获取新实例 ====================== -如果你想获取 Typography 类的新实例,需要向参数 ``$getShared`` 传递 ``false``: +如果你想获取 Timer 类的新实例,需要向参数 ``$getShared`` 传递 ``false``: .. literalinclude:: services/014.php @@ -67,6 +67,8 @@ service() .. literalinclude:: services/003.php +.. note:: 自 v4.5.0 起，当你没有向服务传递参数时，推荐使用全局函数 ``service()``，因为性能有所提升。 + 如果创建方法需要其他参数,可以在服务名称后传入: .. literalinclude:: services/004.php diff --git a/source/concepts/services/002.php b/source/concepts/services/002.php index cb292eca..cedf5d19 100644 --- a/source/concepts/services/002.php +++ b/source/concepts/services/002.php @@ -1,3 +1,6 @@ 'http://example.com/api/v1/', 'timeout' => 3, ]; -$client1 = \Config\Services::curlrequest($options1); +$client1 = service('curlrequest', $options1); $options2 = [ 'baseURI' => 'http://another.example.com/api/v2/', 'timeout' => 10, ]; -$client2 = \Config\Services::curlrequest($options2); +$client2 = service('curlrequest', $options2); // $options2 does not work. // $client2 is the exactly same instance as $client1. diff --git a/source/concepts/structure.rst b/source/concepts/structure.rst index 3d6abef2..9d74df5b 100755 --- a/source/concepts/structure.rst +++ b/source/concepts/structure.rst @@ -11,13 +11,22 @@ 默认目录 ******************* -一个新安装有五个目录:``app/``、``public/``、``writable/``、``tests/`` 和 ``vendor/`` 或 ``system/``。 +一个全新安装有 5 个目录： + +- **app** +- **public** +- **writable** +- **tests** +- **vendor** 或 **system** + 每个目录都有非常具体的作用。 app === -``app`` 目录是所有应用程序代码的存放位置。它具有默认的目录结构,适用于许多应用程序。以下文件夹组成基本内容: +**app** 目录是所有应用程序代码的存放位置。它具有默认的目录结构，适用于许多应用程序。 + +以下文件夹组成基本内容： .. code-block:: none @@ -33,16 +42,16 @@ app ThirdParty/ 应用程序中可以使用的第三方库 Views/ 视图组成向客户端显示的 HTML -由于 ``app`` 目录已经有了命名空间,你应该随意修改此目录的结构以适应应用程序的需要。例如,你可能决定开始使用存储库模式和实体模型来处理数据。在这种情况下,你可以将 ``Models`` 目录重命名为 ``Repositories``,并添加一个新的 ``Entities`` 目录。 +由于 **app** 目录已经有了命名空间，你可以随意修改此目录的结构以适应应用程序的需要。 -.. note:: 但是,如果你重命名了 ``Controllers`` 目录,则无法使用自动将请求路由到控制器的方法,并且需要在 routes 文件中定义所有路由。 +例如，你可能决定开始使用存储库模式和实体模型来处理数据。在这种情况下，你可以将 **Models** 目录重命名为 **Repositories**，并添加一个新的 **Entities** 目录。 -此目录下的所有文件都位于 ``App`` 命名空间下,尽管你可以在 **app/Config/Constants.php** 中自由更改命名空间。 +此目录下的所有文件都位于 ``App`` 命名空间下，尽管你可以在 **app/Config/Constants.php** 中自由更改命名空间。 system ====== -.. note:: 如果使用 Composer 安装 CodeIgniter, ``system`` 位于 ``vendor/codeigniter4/framework/system``。 +.. note:: 如果使用 Composer 安装 CodeIgniter，**system** 位于 **vendor/codeigniter4/framework/system**。 此目录存储构成框架本身的文件。虽然你在如何使用应用程序目录方面有很大的灵活性,但是不应修改 system 目录中的文件。相反,你应该扩展类或创建新类以提供所需的功能。 @@ -54,6 +63,7 @@ public ====== **public** 文件夹包含 web 应用程序的面向浏览器的部分,防止直接访问源代码。 + 它包含主要的 **.htaccess** 文件、**index.php** 以及你添加的任何应用程序资源,如 CSS、JavaScript 或图片。 此文件夹旨在成为站点的“网页根目录”,你的 web 服务器会配置为指向它。 @@ -61,12 +71,16 @@ public writable ======== -此目录包含在应用程序生命周期中可能需要写入的任何目录。这包括用于缓存文件、日志和用户上传的任何目录。你应该在这里添加应用程序需要写入的任何其他目录。这使你可以保持其他主目录不可写,作为额外的安全措施。 +此目录包含在应用程序生命周期中可能需要写入的任何目录。这包括用于缓存文件、日志和用户上传的任何目录。 + +你应该在这里添加应用程序需要写入的任何其他目录。这使你可以保持其他主目录不可写,作为额外的安全措施。 tests ===== -此目录设置为保存测试文件。``_support`` 目录包含可在编写测试时使用的各种模拟类和其他实用程序。此目录不需要传输到生产服务器。 +此目录设置为保存测试文件。**_support** 目录包含可在编写测试时使用的各种模拟类和其他实用程序。 + +此目录不需要传输到生产服务器。 修改目录位置 ***************************** diff --git a/source/conf.py b/source/conf.py index c1e9dfdd..8c55f3e2 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.1' +release = '4.5.3' # -- General configuration --------------------------------------------------- diff --git a/source/database/configuration.rst b/source/database/configuration.rst index ff2ea253..9fa55227 100755 --- a/source/database/configuration.rst +++ b/source/database/configuration.rst @@ -24,12 +24,12 @@ CodeIgniter 有一个配置文件,可让你存储数据库连接值(用户名、 类属性的名称是连接名称,在连接时可以用作指定组名。 -.. note:: SQLite3 数据库的默认位置是在 **writable** 文件夹中。如果要更改位置,则必须设置新文件夹的完整路径。 +.. note:: SQLite3 数据库的默认位置是 **writable** 文件夹。如果要更改位置，则必须设置新文件夹（例如，'database' => WRITEPATH . 'db/database_name.db'）的完整路径。 DSN --- -某些数据库驱动程序(如 Postgre、OCI8)需要完整的 DSN 字符串才能连接。但是,如果你没有为需要 DSN 字符串的驱动程序指定 DSN 字符串,CodeIgniter 将尝试使用其余提供的设置来构建它。 +某些数据库驱动程序（如 Postgre、OCI8）需要完整的 DSN（Data Source Name）字符串才能连接。但是，如果你没有为需要 DSN 字符串的驱动程序指定 DSN 字符串，CodeIgniter 将尝试使用其余提供的设置来构建它。 如果指定了 DSN,你应该使用 ``'DSN'`` 配置设置,就像你正在使用驱动程序的底层原生 PHP 扩展一样,如下所示: @@ -39,7 +39,7 @@ DSN 通用方式的 DSN ^^^^^^^^^^^^^^^^^^^^^^^ -你还可以以通用方式(URL 格式)设置数据源名称。在这种情况下,DSN 必须具有以下原型: +你还可以以通用方式(URL 格式)设置 DSN。在这种情况下,DSN 必须具有以下原型: .. literalinclude:: configuration/003.php :lines: 11-14 @@ -89,7 +89,7 @@ DSN 使用 .env 文件配置 ************************** -你还可以在当前服务器的 **.env** 文件中保存配置值。你只需要输入默认组配置设置中更改的值。值的命名格式应为,其中 ``default`` 是组名称:: +你还可以在 **.env** 文件中保存你的配置值，其中包含当前服务器的数据库设置。你只需要输入与默认配置组中的设置不同的值。这些值应该遵循以下格式，其中 ``default`` 是组名:: database.default.username = 'root'; database.default.password = ''; @@ -110,7 +110,7 @@ DSN .. _database-config-explanation-of-values: ********************** -值的解释 +值的描述 ********************** ================ =========================================================================================================== @@ -129,7 +129,7 @@ DSN 支持的驱动:``MySQLi``、``Postgre``、``SQLite3``、``SQLSRV`` 和 ``OCI8``。 **DBPrefix** 可选的表前缀,在运行时会添加到表名中 :doc:`查询构造器 ` 查询。这允许多个 CodeIgniter 安装共享一个数据库。 **pConnect** true/false (布尔值)- 是否使用持久连接。 -**DBDebug** true/false (布尔值)- 数据库错误发生时是否抛出异常。 +**DBDebug** true/false (布尔值)- 当发生数据库错误时是否抛出异常。 **charset** 与数据库通信使用的字符集。 **DBCollat** （仅限 ``MySQLi``）与数据库通信时使用的字符集。 **swapPre** 一个默认的表前缀,应该与 ``DBPrefix`` 互换。这对于分布式应用程序很有用,在那里你可能运行手动编写的查询,并需要最终用户仍可自定义前缀。 @@ -187,4 +187,4 @@ MySQLi 驱动程序接受包含以下选项的数组： * ``ssl_ca`` - 证书颁发机构文件的路径 * ``ssl_capath`` - 包含以 PEM 格式存储的可信 CA 证书的目录路径 * ``ssl_cipher`` - 允许用于加密的密码列表，用冒号（``:``）分隔 -* ``ssl_verify`` - true/false; 是否验证服务器证书 +* ``ssl_verify`` - true/false (布尔值) - 是否验证服务器证书 diff --git a/source/database/examples.rst b/source/database/examples.rst index 839c63b5..240b47f3 100755 --- a/source/database/examples.rst +++ b/source/database/examples.rst @@ -1,5 +1,5 @@ ################################## -数据库快速入门:示例代码 +快速入门：使用示例 ################################## 以下页面包含显示数据库类用法的示例代码。有关完整详细信息,请阅读描述每个函数的单独页面。 @@ -19,7 +19,7 @@ 一旦加载,该类即可按照下述方式使用。 -.. note:: 如果所有页面都需要数据库访问,则可以自动连接。有关详细信息,请参阅 :doc:`连接 ` 页面。 +.. note:: 如果所有页面都需要数据库访问,则可以自动连接。有关详细信息,请参阅 :doc:`连接数据库 ` 页面。 具有多个结果的标准查询(对象版本) ===================================================== @@ -59,7 +59,7 @@ 查询构建器查询 =================== -:doc:`查询构建器模式 ` 为你提供了一种简化的检索数据方式: +:doc:`查询构建器 ` 为你提供了一种简化的检索数据方式: .. literalinclude:: examples/007.php diff --git a/source/database/helpers.rst b/source/database/helpers.rst index fd731f32..07b842b2 100755 --- a/source/database/helpers.rst +++ b/source/database/helpers.rst @@ -37,7 +37,6 @@ $db->countAll() =============== 允许你确定特定表中的行数。在第一个参数中提交表名。这是查询构建器的一部分。 -例子: .. literalinclude:: helpers/001.php @@ -45,7 +44,6 @@ $db->countAllResults() ====================== 允许你确定特定结果集中的行数。在第一个参数中提交表名。这是查询构建器的一部分。 -例子: .. literalinclude:: helpers/002.php diff --git a/source/database/metadata.rst b/source/database/metadata.rst index ce109c1e..4b6a8e10 100755 --- a/source/database/metadata.rst +++ b/source/database/metadata.rst @@ -1,5 +1,5 @@ ################# -数据库元数据 +获取元数据 ################# .. contents:: @@ -66,7 +66,7 @@ $db->fieldExists() .. literalinclude:: metadata/005.php -.. note:: 用你要查找的字段名称替换 *field_name*,并用你要查找的表格名称替换 *table_name*。 +.. note:: 将 *field_name* 和 *table_name* 替换为你要查找的列名和表名。 检索字段元数据 ======================= diff --git a/source/database/query_builder.rst b/source/database/query_builder.rst index 5027f3ad..addcc419 100755 --- a/source/database/query_builder.rst +++ b/source/database/query_builder.rst @@ -69,7 +69,9 @@ $builder->get() .. literalinclude:: query_builder/004.php -有关结果生成的完整讨论,请访问 :doc:`getResult*() 方法 ` 页面。 +有关结果生成的完整讨论,请访问 :ref:`getResult() ` 方法页面。 + +请访问 :ref:`getResult() ` 方法，以了解关于结果生成的完整讨论。 $builder->getCompiledSelect() ----------------------------- @@ -80,12 +82,11 @@ $builder->getCompiledSelect() .. literalinclude:: query_builder/005.php -第一个参数使你可以设置查询构建器查询是否将重置(默认情况下,它将重置,就像使用 ``$builder->get()`` 一样): +下面第一个查询中的参数 (false) 允许你设置查询构建器是否会被重置（因为该参数的默认值为 true，即默认情况下 ``getCompiledSelect(bool $reset = true)`` 会像使用 ``$builder->get()`` 一样被重置）： .. literalinclude:: query_builder/006.php -上例中的关键是要注意第二个查询没有利用 ``limit(10, 20)``,但生成的 SQL 查询具有 ``LIMIT 20, 10``。 -这种结果的原因是因为第一个参数设置为 ``false``。 +在上述示例中需要注意的关键点是，第二个查询并没有使用 ``limit(10, 20)``，但生成的 SQL 查询却包含 ``LIMIT 20, 10``。这种结果的原因是因为第一个查询中的参数被设置为 ``false``，因此 ``limit(10, 20)`` 在第二个查询中仍然有效。 $builder->getWhere() -------------------- diff --git a/source/database/results.rst b/source/database/results.rst index 172e713b..228cfabe 100755 --- a/source/database/results.rst +++ b/source/database/results.rst @@ -12,6 +12,8 @@ 结果数组 ************* +.. _getresult: + getResult() =========== diff --git a/source/database/utilities.rst b/source/database/utilities.rst index 8924639b..1176391a 100644 --- a/source/database/utilities.rst +++ b/source/database/utilities.rst @@ -1,5 +1,5 @@ ###################### -数据库实用工具类 +数据库实用工具 ###################### 数据库实用工具类包含了帮助你管理数据库的方法。 diff --git a/source/dbmgmt/forge.rst b/source/dbmgmt/forge.rst index f9eb1a4d..252b930b 100644 --- a/source/dbmgmt/forge.rst +++ b/source/dbmgmt/forge.rst @@ -35,7 +35,7 @@ $forge->createDatabase('db_name') .. literalinclude:: forge/003.php -可选的第二个参数设置为 true 将添加 ``IF EXISTS`` 语句或检查数据库是否存在,然后再创建它(取决于 DBMS)。 +可选的第二个参数设置为 true 将添加 ``IF EXISTS`` 语句，或者在创建数据库之前检查数据库是否存在（具体取决于 DBMS）。 .. literalinclude:: forge/004.php diff --git a/source/dbmgmt/index.rst b/source/dbmgmt/index.rst index 9c5c9f54..e2693d9a 100644 --- a/source/dbmgmt/index.rst +++ b/source/dbmgmt/index.rst @@ -7,7 +7,7 @@ CodeIgniter 用于重建或查看数据库的工具。 .. toctree:: :titlesonly: - 使用数据库 Forge 维护数据库 + 数据库 Forge 数据库迁移 数据库填充 db_commands diff --git a/source/dbmgmt/migration.rst b/source/dbmgmt/migration.rst index 1e0ebdfe..766f4811 100644 --- a/source/dbmgmt/migration.rst +++ b/source/dbmgmt/migration.rst @@ -87,7 +87,7 @@ migrate php spark migrate -你可以对 (migrate) 使用以下选项: +你可以对 ``migrate`` 使用以下选项： - ``-g`` - 用于指定数据库组。如果指定了该选项，只会运行指定数据库组的迁移。如果未指定，则会运行所有迁移。 - ``-n`` - 用于选择命名空间，否则将使用 ``App`` 命名空间。 @@ -109,8 +109,8 @@ For Windows: 当使用 ``--all`` 选项时,它将扫描所有命名空间,尝试找到任何未运行的迁移。这些迁移将一起收集,然后按创建日期排序为一组。这应该有助于最大限度地减少主应用程序和任何模块之间的潜在冲突。 -rollback -======== +migrate:rollback +================ 回滚所有迁移到空白状态,有效迁移到 0: @@ -118,13 +118,13 @@ rollback php spark migrate:rollback -你可以对 (rollback) 使用以下选项: +你可以对 ``migrate:rollback`` 使用以下选项: - ``-b`` - 选择批次:自然数指定批次。 - ``-f`` - 强制绕过确认问题,它仅在生产环境中询问。 -refresh -======= +migrate:refresh +=============== 首先回滚所有迁移,然后迁移所有来刷新数据库状态: @@ -132,15 +132,15 @@ refresh php spark migrate:refresh -你可以对 (refresh) 使用以下选项: +你可以对 ``migrate:refresh`` 使用以下选项: - ``-g`` - 用于指定数据库组。如果指定了该选项，只会运行指定数据库组的迁移。如果未指定，则会运行所有迁移。 - ``-n`` - 用于选择命名空间，否则将使用 ``App`` 命名空间。 - ``--all`` - 刷新所有命名空间。 - ``-f`` - 强制绕过确认问题,它仅在生产环境中询问。 -status -====== +migrate:status +============== 显示所有迁移的列表以及它们运行的日期和时间,如果未运行则显示 '--': @@ -158,7 +158,7 @@ status | CodeIgniter\Settings | 2021-11-14-143905 | AddContextColumn | default | 2022-04-06 01:23:08 | 1 | +----------------------+-------------------+-----------------------+---------+---------------------+-------+ -你可以对 (status) 使用以下选项: +你可以对 ``migrate:status`` 使用以下选项: - ``-g`` - 用于指定数据库组。如果指定了该选项，只会检查指定数据库组的迁移。如果未指定，则会检查所有迁移。 @@ -171,7 +171,7 @@ make:migration php spark make:migration [options] -你可以对 (``make:migration``) 使用以下选项: +你可以对 ``make:migration`` 使用以下选项: - ``--namespace`` - 设置根命名空间。默认: ``APP_NAMESPACE``。 - ``--suffix`` - 在类名后追加组件标题。 diff --git a/source/extending/basecontroller/003.php b/source/extending/basecontroller/003.php index 2f6fcb9d..b7bcab22 100644 --- a/source/extending/basecontroller/003.php +++ b/source/extending/basecontroller/003.php @@ -18,6 +18,6 @@ public function initController(/* ... */) // Do Not Edit This Line parent::initController($request, $response, $logger); - $this->session = \Config\Services::session(); + $this->session = service('session'); } } diff --git a/source/extending/core_classes.rst b/source/extending/core_classes.rst index 9c7ce85e..e519d07f 100755 --- a/source/extending/core_classes.rst +++ b/source/extending/core_classes.rst @@ -81,7 +81,7 @@ 扩展核心类 ====================== -如果你只需要为现有库添加一些功能 - 可能添加一两个方法 - 那么重新创建整个库就有点过度设计。在这种情况下,最好简单地扩展该类。扩展该类与 `替换核心类`_ 几乎相同,只有一个例外: +如果你只需要向现有的库中添加一些功能 - 可能是一两个方法 - 那么重新创建整个库就有些过度了。在这种情况下，更好的做法是简单地扩展这个类。扩展类与 `替换核心类`_ 几乎相同，只有一个例外： * 类声明必须扩展父类。 diff --git a/source/extending/events.rst b/source/extending/events.rst index fdbd4341..3e880dd8 100644 --- a/source/extending/events.rst +++ b/source/extending/events.rst @@ -1,9 +1,9 @@ 事件 ##################################### -CodeIgniter 的 Events 功能提供了一种利用内部机制而不修改核心文件的方式。CodeIgniter 运行时遵循特定的执行流程,但有时你可能希望在执行流程的特定阶段引发某些操作。例如,你可能希望在控制器加载之前或之后运行一个脚本,或者你可能希望在其他位置触发自己的脚本。 +CodeIgniter 的事件功能提供了一种方式，可以在不修改核心文件的情况下，接入并修改框架的内部工作流程。当 CodeIgniter 运行时，它会遵循一个特定的执行过程。但是，在某些情况下，你可能会希望在某些特定的执行阶段执行某些操作。例如，你可能想在控制器加载之前或之后运行一个脚本，或者你可能想在其他位置触发自己的脚本。 -事件遵循 *发布/订阅* 模式,即在脚本执行的某个时刻触发一个事件。其他脚本可以通过在 Events 类中注册来“订阅”该事件,以表明它们希望在触发该事件时执行操作。 +事件基于 *发布/订阅* 模式工作，在脚本执行期间的某个点触发一个事件。其他脚本可以通过注册到事件类来“订阅”该事件，让事件类知道它们希望在触发该事件时执行一个动作。 .. contents:: :local: diff --git a/source/general/common_functions.rst b/source/general/common_functions.rst index 7f492937..68e40710 100755 --- a/source/general/common_functions.rst +++ b/source/general/common_functions.rst @@ -97,14 +97,15 @@ CodeIgniter 提供了一些全局定义的函数和变量,在任何时候都可 .. php:function:: lang($line[, $args[, $locale]]) - :param string $line: 要检索的文本行 - :param array $args: 要替换占位符的数据数组 - :param string $locale: 指定使用的区域设置,而不是默认区域设置 - :returns: 基于别名字符串的特定区域设置的文件 + :param string $line: 需要检索的语言文件名和文本 key。 + :param array $args: 用于替换占位符的数据数组。 + :param string $locale: 指定使用当前区域设置之外的区域设置。 + :returns: 语言文件中的文本 + :rtype: list|string - 根据别名字符串检索特定区域设置的文件。 + 从语言文件中检索文本。 - 有关更多信息,请参阅 :doc:`本地化 ` 页面。 + 更多信息，请参见 :ref:`language-localization`。 .. php:function:: model($name[, $getShared = true[, &$conn = null]]) @@ -164,7 +165,7 @@ CodeIgniter 提供了一些全局定义的函数和变量,在任何时候都可 :returns: 来自视图的输出 :rtype: string - 获取当前与 RendererInterface 兼容的类,并告诉它渲染指定的视图。只是在控制器、库和路由闭包中使用的方便方法。 + 获取当前的 RendererInterface 兼容类（默认为 :doc:`视图 <../outgoing/view_renderer>` 类），并告诉它渲染指定的视图。这仅仅提供了一个方便的方法，可以在控制器、库以及在路由闭包中使用。 当前,这些选项可用于 ``$options`` 数组中: @@ -335,7 +336,7 @@ CodeIgniter 提供了一些全局定义的函数和变量,在任何时候都可 :returns: 共享的 Request 对象 :rtype: IncomingRequest|CLIRequest - 此函数是 ``Services::request()`` 的包装器。 + 此函数是 ``Services::request()`` 和 ``service('request')`` 的包装器。 .. php:function:: response() @@ -344,7 +345,7 @@ CodeIgniter 提供了一些全局定义的函数和变量,在任何时候都可 :returns: 共享的 Response 对象 :rtype: Response - 此函数是 ``Services::response()`` 的包装器。 + 此函数是 ``Services::response()`` 和 ``service('response')`` 的包装器。 .. php:function:: route_to($method[, ...$params]) diff --git a/source/general/errors.rst b/source/general/errors.rst index 958d97e4..a8ab7cc8 100755 --- a/source/general/errors.rst +++ b/source/general/errors.rst @@ -75,14 +75,23 @@ CodeIgniter 通过“异常（Exception）”在你的系统中内置了错误 .. _logging_deprecation_warnings: -弃用警告日志 ------------- +记录弃用警告 +---------------------------- .. versionadded:: 4.3.0 -默认情况下，所有由 ``error_reporting()`` 报告的错误都会作为 ``ErrorException`` 对象抛出。这包括 ``E_DEPRECATED`` 和 ``E_USER_DEPRECATED`` 错误。随着 PHP 8.1+ 的使用激增，许多用户可能会看到由于 `passing null to non-nullable arguments of internal functions `_ 抛出的异常。为了简化向 PHP 8.1 的迁移，你可以指示 CodeIgniter 记录这些弃用警告，而不是抛出它们。 +在 v4.3.0 之前，所有通过 ``error_reporting()`` 报告的错误都会被抛出为一个 ``ErrorException`` 对象。 -首先，确保你的 ``Config\Exceptions`` 副本已更新了两个新属性并设置如下： +但随着 PHP 8.1+ 的广泛使用，许多用户可能会遇到因为 `passing null to non-nullable arguments of internal functions `_ 而抛出的异常。 + +为了更顺利地迁移到 PHP 8.1，从 v4.3.0 开始，CodeIgniter 增加了仅记录弃用错误（``E_DEPRECATED`` 和 ``E_USER_DEPRECATED``）而不将其作为异常抛出的功能。 + +默认情况下，CodeIgniter 在开发环境中仅记录弃用警告而不抛出异常。在生产环境中，则不进行记录且不抛出异常。 + +配置 +^^^^^^^^^^^^^ + +此功能的设置如下。首先，确保你的 ``Config\Exceptions`` 副本更新了两个新属性，并按以下方式设置： .. literalinclude:: errors/012.php @@ -90,7 +99,7 @@ CodeIgniter 通过“异常（Exception）”在你的系统中内置了错误 .. literalinclude:: errors/013.php -之后，后续的弃用警告将会被记录而不是抛出。 +之后，后续的弃用警告将按照配置进行记录，而不会作为异常抛出。 此功能也适用于用户弃用警告： diff --git a/source/general/errors/012.php b/source/general/errors/012.php index 1b773613..2c81e878 100644 --- a/source/general/errors/012.php +++ b/source/general/errors/012.php @@ -7,8 +7,9 @@ class Exceptions extends BaseConfig { - // ... other properties - - public bool $logDeprecations = true; - public string $deprecationLogLevel = LogLevel::WARNING; // this should be one of the log levels supported by PSR-3 + // ... + public bool $logDeprecations = true; // If set to false, an exception will be thrown. + // ... + public string $deprecationLogLevel = LogLevel::WARNING; // This should be one of the log levels supported by PSR-3. + // ... } diff --git a/source/general/errors/013.php b/source/general/errors/013.php index 23352f0e..b099c6d1 100644 --- a/source/general/errors/013.php +++ b/source/general/errors/013.php @@ -6,7 +6,8 @@ class Logger extends BaseConfig { - // .. other properties - - public $threshold = 5; // originally 4 but changed to 5 to log the warnings from the deprecations + // ... + // This must contain the log level (5 for LogLevel::WARNING) corresponding to $deprecationLogLevel. + public $threshold = (ENVIRONMENT === 'production') ? 4 : 9; + // ... } diff --git a/source/general/errors/018.php b/source/general/errors/018.php index 3cba0995..9546e4a6 100644 --- a/source/general/errors/018.php +++ b/source/general/errors/018.php @@ -1,6 +1,6 @@ redirect('https://example.com/path') ->setHeader('Some', 'header') ->setCookie('and', 'cookie'); diff --git a/source/general/managing_apps.rst b/source/general/managing_apps.rst index 4429c5ab..b676301d 100755 --- a/source/general/managing_apps.rst +++ b/source/general/managing_apps.rst @@ -4,21 +4,6 @@ 默认情况下,假设你只打算在 **app** 目录中使用 CodeIgniter 来管理一个应用程序。但是,可以拥有多个共享单个 CodeIgniter 安装的应用程序集,或者重命名或重新定位你的应用程序目录。 -.. important:: 如果你安装了 CodeIgniter v4.1.9 或更早版本,并且在 ``/composer.json`` 的 ``autoload.psr-4`` 中有像下面这样的 ``App\\`` 和 ``Config\\`` 命名空间,你需要删除这些行并运行 ``composer dump-autoload``。 - - .. code-block:: text - - { - ... - "autoload": { - "psr-4": { - "App\\": "app", <-- 移除这行 - "Config\\": "app/Config" <-- 移除这行 - } - }, - ... - } - .. contents:: :local: :depth: 2 @@ -34,13 +19,15 @@ 你需要修改项目根目录中的另外两个文件,以便它们可以找到 **Paths** 配置文件: -- **/spark** 运行命令行应用程序。 +- **spark** 运行命令行应用程序。 .. literalinclude:: managing_apps/002.php + :lines: 2- -- **/public/index.php** 是你的 Web 应用程序的前端控制器。 +- **public/index.php** 是你的 Web 应用程序的前端控制器。 .. literalinclude:: managing_apps/003.php + :lines: 2- .. _running-multiple-app: diff --git a/source/general/modules.rst b/source/general/modules.rst index b6c481c2..0b6a1c7b 100755 --- a/source/general/modules.rst +++ b/source/general/modules.rst @@ -210,7 +210,7 @@ For Windows: 语言文件 ============== -只要文件遵循与主应用程序目录相同的目录结构,在使用 ``lang()`` 方法时就会从定义的命名空间自动定位语言文件。 +只要文件遵循与主应用程序目录相同的目录结构，在使用 :php:func:`lang()` 函数时就会从定义的命名空间自动定位语言文件。 库 ========= @@ -230,11 +230,11 @@ For Windows: .. note:: 我们不建议在模块中使用相同的短类名。 -.. note:: 当有一个相同短名称的类时,即使你指定了完全限定的类名(如 ``model(\Acme\Blog\Model\PostModel::class)``), ``model()`` 也会在 **app/Models/** 中找到该文件。这是因为 ``model()`` 是 ``Factories`` 类的包装器,默认使用 ``preferApp``。有关更多信息,请参阅 :ref:`factories-loading-class`。 +.. note:: 在 v4.4.0 之前，即使你指定了一个完全限定的类名，如 ``model(\Acme\Blog\Model\PostModel::class)``，``model()`` 也会在 **app/Models/** 中查找具有相同短名称的类的文件。有关更多信息，请参阅 :ref:`factories-passing-fully-qualified-classname` 中的注释。 视图 ===== -如 :doc:`视图 ` 文档中所述,可以使用类命名空间加载视图: +如 :ref:`视图 ` 文档中所述，可以使用类命名空间加载视图： .. literalinclude:: modules/012.php diff --git a/source/helpers/form_helper.rst b/source/helpers/form_helper.rst index 181138bd..810cd179 100755 --- a/source/helpers/form_helper.rst +++ b/source/helpers/form_helper.rst @@ -54,7 +54,7 @@ :returns: 一个 HTML 表单开启标签 :rtype: string - 使用从 **Config\App::$baseURL** 构建的站点 URL 创建一个开启的表单标签。它将可选地允许你添加表单属性和隐藏的输入字段,并将始终根据配置文件中的 charset 值添加 `accept-charset` 属性。 + 创建一个开启的 form 标签，其 action 的 base 使用你的 ``Config\App::$baseURL`` 值。它将可选地允许你添加表单属性和隐藏输入字段，并且将始终根据你的 **app/Config/App.php** 配置文件中的 ``$charset`` 属性添加 `accept-charset` 属性。 与硬编码你自己的 HTML 相比,使用此标签的主要好处在于,如果你的 URL 改变,它允许你的站点更便携。 @@ -88,16 +88,21 @@