Merge remote-tracking branch 'upstream/develop' into 4.6

system/CLI/GeneratorTrait.php

@@ -96,13 +96,15 @@ trait GeneratorTrait
      *
      * @internal
      *
-     * @var array
+     * @var array<int|string, string|null>
      */
     private $params = [];
 
     /**
      * Execute the command.
      *
+     * @param array<int|string, string|null> $params
+     *
      * @deprecated use generateClass() instead
      */
     protected function execute(array $params): void
@@ -112,6 +114,8 @@ protected function execute(array $params): void
 
     /**
      * Generates a class file from an existing template.
+     *
+     * @param array<int|string, string|null> $params
      */
     protected function generateClass(array $params): void
     {
@@ -134,7 +138,8 @@ protected function generateClass(array $params): void
     /**
      * Generate a view file from an existing template.
      *
-     * @param string $view namespaced view name that is generated
+     * @param string                         $view   namespaced view name that is generated
+     * @param array<int|string, string|null> $params
      */
     protected function generateView(string $view, array $params): void
     {
@@ -331,6 +336,8 @@ private function normalizeInputClassName(): string
     /**
      * Gets the generator view as defined in the `Config\Generators::$views`,
      * with fallback to `$template` when the defined view does not exist.
+     *
+     * @param array<string, mixed> $data
      */
     protected function renderTemplate(array $data = []): string
     {
@@ -352,7 +359,10 @@ protected function renderTemplate(array $data = []): string
     /**
      * Performs pseudo-variables contained within view file.
      *
-     * @param string $class namespaced classname or namespaced view.
+     * @param string                          $class   namespaced classname or namespaced view.
+     * @param list<string>                    $search
+     * @param list<string>                    $replace
+     * @param array<string, bool|string|null> $data
      *
      * @return string generated file content
      */

system/Commands/Encryption/GenerateKey.php

@@ -124,6 +124,8 @@ protected function generateRandomKey(string $prefix, int $length): string
 
     /**
      * Sets the new encryption key in your .env file.
+     *
+     * @param array<int|string, string|null> $params
      */
     protected function setNewEncryptionKey(string $key, array $params): bool
     {
@@ -139,6 +141,8 @@ protected function setNewEncryptionKey(string $key, array $params): bool
 
     /**
      * Checks whether to overwrite existing encryption key.
+     *
+     * @param array<int|string, string|null> $params
      */
     protected function confirmOverwrite(array $params): bool
     {

system/Database/BaseBuilder.php

@@ -654,6 +654,7 @@ public function join(string $table, $cond, string $type = '', ?bool $escape = nu
             $cond = ' ON ' . $cond;
         } else {
             // Split multiple conditions
+            // @TODO This does not parse `BETWEEN a AND b` correctly.
             if (preg_match_all('/\sAND\s|\sOR\s/i', $cond, $joints, PREG_OFFSET_CAPTURE)) {
                 $conditions = [];
                 $joints     = $joints[0];
@@ -676,6 +677,13 @@ public function join(string $table, $cond, string $type = '', ?bool $escape = nu
             foreach ($conditions as $i => $condition) {
                 $operator = $this->getOperator($condition);
 
+                // Workaround for BETWEEN
+                if ($operator === false) {
+                    $cond .= $joints[$i] . $condition;
+
+                    continue;
+                }
+
                 $cond .= $joints[$i];
                 $cond .= preg_match('/(\(*)?([\[\]\w\.\'-]+)' . preg_quote($operator, '/') . '(.*)/i', $condition, $match) ? $match[1] . $this->db->protectIdentifiers($match[2]) . $operator . $this->db->protectIdentifiers($match[3]) : $condition;
             }

system/Database/SQLSRV/Builder.php

@@ -145,6 +145,13 @@ public function join(string $table, $cond, string $type = '', ?bool $escape = nu
             foreach ($conditions as $i => $condition) {
                 $operator = $this->getOperator($condition);
 
+                // Workaround for BETWEEN
+                if ($operator === false) {
+                    $cond .= $joints[$i] . $condition;
+
+                    continue;
+                }
+
                 $cond .= $joints[$i];
                 $cond .= preg_match('/(\(*)?([\[\]\w\.\'-]+)' . preg_quote($operator, '/') . '(.*)/i', $condition, $match) ? $match[1] . $this->db->protectIdentifiers($match[2]) . $operator . $this->db->protectIdentifiers($match[3]) : $condition;
             }

tests/system/Database/Builder/JoinTest.php

@@ -80,6 +80,25 @@ public function testJoinMultipleConditions(): void
         $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
     }
 
+    /**
+     * @see https://github.com/codeigniter4/CodeIgniter4/issues/8791
+     */
+    public function testJoinMultipleConditionsBetween(): void
+    {
+        $builder = new BaseBuilder('table1', $this->db);
+
+        $builder->join(
+            'leases',
+            'units.unit_id = leases.unit_id AND CURDATE() BETWEEN lease_start_date AND lease_exp_date',
+            'LEFT'
+        );
+
+        // @TODO Should be `... CURDATE() BETWEEN "lease_start_date" AND "lease_exp_date"`
+        $expectedSQL = 'SELECT * FROM "table1" LEFT JOIN "leases" ON "units"."unit_id" = "leases"."unit_id" AND CURDATE() BETWEEN lease_start_date AND lease_exp_date';
+
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+    }
+
     /**
      * @see https://github.com/codeigniter4/CodeIgniter4/issues/3832
      */

user_guide_src/source/database/configuration.rst

@@ -29,13 +29,13 @@ prototype:
 The name of the class property is the connection name, and can be used
 while connecting to specify a group name.
 
-.. note:: The default location of the SQLite3 database is in the **writable** folder.
-    If you want to change the location, you must set the full path to the new folder.
+.. note:: The default location of the SQLite3 database is the **writable** folder.
+    If you want to change the location, you must set the full path to the new folder (e.g., 'database' => WRITEPATH . 'db/database_name.db').
 
 DSN
 ---
 
-Some database drivers (such as Postgre, OCI8) requires a full DSN string to connect.
+Some database drivers (such as Postgre, OCI8) requires a full DSN (Data Source Name) string to connect.
 But if you do not specify a DSN string for a driver that requires it, CodeIgniter
 will try to build it with the rest of the provided settings.
 
@@ -48,7 +48,7 @@ you're using the driver's underlying native PHP extension, like this:
 DSN in Universal Manner
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-You can also set a Data Source Name in universal manner (URL like). In that case DSNs must have this prototype:
+You can also set a DSN in universal manner (URL like). In that case DSNs must have this prototype:
 
 .. literalinclude:: configuration/003.php
     :lines: 11-14
@@ -113,7 +113,7 @@ Configuring with .env File
 
 You can also save your configuration values within a **.env** file with the current server's
 database settings. You only need to enter the values that change from what is in the
-default group's configuration settings. The values should be name following this format, where
+default group's configuration settings. The values should follow this format, where
 ``default`` is the group name::
 
     database.default.username = 'root';
@@ -137,11 +137,11 @@ and decode it in the constructor in the Config class:
 .. _database-config-explanation-of-values:
 
 *********************
-Explanation of Values
+Description of Values
 *********************
 
 ================ ===========================================================================================================
- Name Config     Description
+ Config Name     Description
 ================ ===========================================================================================================
 **DSN**          The DSN connect string (an all-in-one configuration sequence).
 **hostname**     The hostname of your database server. Often this is 'localhost'.
@@ -154,31 +154,31 @@ Explanation of Values
 **DBDriver**     The database driver name. The case must match the driver name.
                  You can set a fully qualified classname to use your custom driver.
                  Supported drivers: ``MySQLi``, ``Postgre``, ``SQLite3``, ``SQLSRV``, and ``OCI8``.
-**DBPrefix**     An optional table prefix which will added to the table name when running
+**DBPrefix**     An optional table prefix which will be added to the table name when running
                  :doc:`Query Builder <query_builder>` queries. This permits multiple CodeIgniter
                  installations to share one database.
 **pConnect**     true/false (boolean) - Whether to use a persistent connection.
-**DBDebug**      true/false (boolean) - Whether to throw exceptions or not when database errors occur.
+**DBDebug**      true/false (boolean) - Whether to throw exceptions when database errors occur.
 **charset**      The character set used in communicating with the database.
 **DBCollat**     (``MySQLi`` only) The character collation used in communicating with the database.
 **swapPre**      A default table prefix that should be swapped with ``DBPrefix``. This is useful for distributed
                  applications where you might run manually written queries, and need the prefix to still be
                  customizable by the end user.
 **schema**       (``Postgre`` and ``SQLSRV`` only) The database schema, default value varies by driver.
-**encrypt**      (``MySQLi`` and ``SQLSRV`` only) Whether or not to use an encrypted connection.
+**encrypt**      (``MySQLi`` and ``SQLSRV`` only) Whether to use an encrypted connection.
                  See :ref:`MySQLi encrypt <mysqli-encrypt>` for ``MySQLi`` settings.
                  ``SQLSRV`` driver accepts true/false.
-**compress**     (``MySQLi`` only) Whether or not to use client compression.
+**compress**     (``MySQLi`` only) Whether to use client compression.
 **strictOn**     (``MySQLi`` only) true/false (boolean) - Whether to force "Strict Mode" connections, good for ensuring
                  strict SQL while developing an application.
 **port**         The database port number - Empty string ``''`` for default port (or dynamic port with ``SQLSRV``).
-**foreignKeys**  (``SQLite3`` only) true/false (boolean) - Whether or not to enable Foreign Key constraint.
+**foreignKeys**  (``SQLite3`` only) true/false (boolean) - Whether to enable Foreign Key constraint.
 
                  .. important:: SQLite3 Foreign Key constraint is disabled by default.
                      See `SQLite documentation <https://www.sqlite.org/pragma.html#pragma_foreign_keys>`_.
                      To enforce Foreign Key constraint, set this config item to true.
 **busyTimeout**  (``SQLite3`` only) milliseconds (int) - Sleeps for a specified amount of time when a table is locked.
-**numberNative** (``MySQLi`` only) true/false (boolean) - Whether or not to enable MYSQLI_OPT_INT_AND_FLOAT_NATIVE.
+**numberNative** (``MySQLi`` only) true/false (boolean) - Whether to enable MYSQLI_OPT_INT_AND_FLOAT_NATIVE.
 **dateFormat**   The default date/time formats as PHP's `DateTime format`_.
                  * ``date``        - date format
                  * ``datetime``    - date and time format
@@ -225,4 +225,4 @@ MySQLi driver accepts an array with the following options:
 * ``ssl_ca``     - Path to the certificate authority file
 * ``ssl_capath`` - Path to a directory containing trusted CA certificates in PEM format
 * ``ssl_cipher`` - List of *allowed* ciphers to be used for the encryption, separated by colons (``:``)
-* ``ssl_verify`` - true/false; Whether to verify the server certificate or not
+* ``ssl_verify`` - true/false (boolean) - Whether to verify the server certificate or not

user_guide_src/source/database/helpers.rst

@@ -42,7 +42,6 @@ $db->countAll()
 
 Permits you to determine the number of rows in a particular table.
 Submit the table name in the first parameter. This is part of Query Builder.
-Example:
 
 .. literalinclude:: helpers/001.php
 
@@ -51,7 +50,6 @@ $db->countAllResults()
 
 Permits you to determine the number of rows in a particular result set.
 Submit the table name in the first parameter. This is part of Query Builder.
-Example:
 
 .. literalinclude:: helpers/002.php
 

user_guide_src/source/database/index.rst

@@ -14,7 +14,7 @@ patterns. The database functions offer clear, simple syntax.
     Connecting to a Database <connecting>
     Running Queries <queries>
     Generating Query Results <results>
-    Query Helper Functions <helpers>
+    Query Helper Methods <helpers>
     Query Builder Class <query_builder>
     Transactions <transactions>
     Getting MetaData <metadata>

user_guide_src/source/database/query_builder.rst

@@ -88,7 +88,7 @@ $query, which can be used to show the results:
 
 .. literalinclude:: query_builder/004.php
 
-Please visit the :doc:`getResult*() method <results>` page for a full
+Please visit the :ref:`getResult() <getresult>` method for a full
 discussion regarding result generation.
 
 $builder->getCompiledSelect()
@@ -101,14 +101,14 @@ Example:
 
 .. literalinclude:: query_builder/005.php
 
-The first parameter enables you to set whether or not the query builder query
-will be reset (by default it will be reset, just like when using ``$builder->get()``):
+The parameter (false) in the first query below enables you to set whether or not the query builder
+will be reset (because the default value of the parameter is true, ``getCompiledSelect(bool $reset = true)``, by default it will be reset just like when using ``$builder->get()``):
 
 .. literalinclude:: query_builder/006.php
 
 The key thing to notice in the above example is that the second query did not
 utilize ``limit(10, 20)`` but the generated SQL query has ``LIMIT 20, 10``.
-The reason for this outcome is because the first parameter is set to ``false``.
+The reason for this outcome is because the parameter in the first query is set to ``false``, ``limit(10, 20)`` remained in the second query.
 
 $builder->getWhere()
 --------------------
@@ -169,7 +169,7 @@ $builder->selectMin()
 ---------------------
 
 Writes a **SELECT MIN(field)** portion for your query. As with
-``selectMax()``, You can optionally include a second parameter to rename
+``selectMax()``, you can optionally include a second parameter to rename
 the resulting field.
 
 .. literalinclude:: query_builder/011.php
@@ -178,7 +178,7 @@ $builder->selectAvg()
 ---------------------
 
 Writes a **SELECT AVG(field)** portion for your query. As with
-``selectMax()``, You can optionally include a second parameter to rename
+``selectMax()``, you can optionally include a second parameter to rename
 the resulting field.
 
 .. literalinclude:: query_builder/012.php
@@ -187,7 +187,7 @@ $builder->selectSum()
 ---------------------
 
 Writes a **SELECT SUM(field)** portion for your query. As with
-``selectMax()``, You can optionally include a second parameter to rename
+``selectMax()``, you can optionally include a second parameter to rename
 the resulting field.
 
 .. literalinclude:: query_builder/013.php
@@ -196,7 +196,7 @@ $builder->selectCount()
 -----------------------
 
 Writes a **SELECT COUNT(field)** portion for your query. As with
-``selectMax()``, You can optionally include a second parameter to rename
+``selectMax()``, you can optionally include a second parameter to rename
 the resulting field.
 
 .. note:: This method is particularly helpful when used with ``groupBy()``. For

user_guide_src/source/database/results.rst

@@ -12,6 +12,8 @@ There are several ways to generate query results:
 Result Arrays
 *************
 
+.. _getresult:
+
 getResult()
 ===========
 
@@ -93,7 +95,7 @@ digit in the first parameter:
 
 .. literalinclude:: results/009.php
 
-In addition, you can walk forward/backwards/first/last through your
+In addition, you can walk forward/backward/first/last through your
 results using these variations:
 
     | ``$row = $query->getFirstRow()``

user_guide_src/source/database/utilities.rst

@@ -1,6 +1,6 @@
-######################
-Database Utility Class
-######################
+##################
+Database Utilities
+##################
 
 The Database Utility Class contains methods that help you manage your database.
 

user_guide_src/source/general/common_functions.rst

@@ -106,13 +106,15 @@ Service Accessors
 
 .. php:function:: lang($line[, $args[, $locale]])
 
-    :param string $line: The line of text to retrieve
+    :param string $line: The language filename and the key of the text to retrieve.
     :param array  $args: An array of data to substitute for placeholders.
-    :param string $locale: Specify a different locale to be used instead of default one.
+    :param string $locale: Specify a different locale to be used instead of the current locale.
+    :returns: The text in the language file
+    :rtype: list<string>|string
 
-    Retrieves a locale-specific file based on an alias string.
+    Retrieves text from the language files.
 
-    For more information, see the :doc:`Localization </outgoing/localization>` page.
+    For more information, see the :ref:`language-localization`.
 
 .. php:function:: model($name[, $getShared = true[, &$conn = null]])
 

user_guide_src/source/installation/upgrade_4xx.rst

@@ -254,8 +254,8 @@ Upgrading Libraries
     upgrade_images
     upgrade_localization
     upgrade_migrations
-    upgrade_pagination
     upgrade_responses
+    upgrade_pagination
     upgrade_routing
     upgrade_security
     upgrade_sessions

user_guide_src/source/installation/upgrade_responses.rst

@@ -1,5 +1,5 @@
-Upgrade HTTP Responses
-######################
+Upgrade Output Class
+####################
 
 .. contents::
     :local:
@@ -12,11 +12,12 @@ Documentations
 
 What has been changed
 =====================
-- The methods have been renamed
+- The Output class has been changed to the Response class.
+- The methods have been renamed.
 
 Upgrade Guide
 =============
-1. The methods in the HTTP Responses class are named slightly different. The most important change in the naming is the switch from underscored method names to camelCase. The method ``set_content_type()`` from version 3 is now named ``setContentType()`` and so on.
+1. The methods in the HTTP Response class are named slightly different. The most important change in the naming is the switch from underscored method names to camelCase. The method ``set_content_type()`` from version 3 is now named ``setContentType()`` and so on.
 2. In the most cases you have to change ``$this->output`` to ``$this->response`` followed by the method. You can find all methods in :doc:`../outgoing/response`.
 
 Code Example