Merge pull request #8525 from kenjis/feat-db-config-dateFormat

feat: add DB config `dateFormat` to provide default date/time formats

Author: kenjis

app/Config/Database.php

@@ -43,6 +43,11 @@ class Database extends Config
         'failover'     => [],
         'port'         => 3306,
         'numberNative' => false,
+        'dateFormat'   => [
+            'date'     => 'Y-m-d',
+            'datetime' => 'Y-m-d H:i:s',
+            'time'     => 'H:i:s',
+        ],
     ];
 
     /**
@@ -69,6 +74,11 @@ class Database extends Config
         'port'        => 3306,
         'foreignKeys' => true,
         'busyTimeout' => 1000,
+        'dateFormat'  => [
+            'date'     => 'Y-m-d',
+            'datetime' => 'Y-m-d H:i:s',
+            'time'     => 'H:i:s',
+        ],
     ];
 
     public function __construct()

system/Database/BaseConnection.php

@@ -26,6 +26,7 @@
  * @property-read float      $connectDuration
  * @property-read float      $connectTime
  * @property-read string     $database
+ * @property-read array      $dateFormat
  * @property-read string     $DBCollat
  * @property-read bool       $DBDebug
  * @property-read string     $DBDriver
@@ -347,6 +348,19 @@ abstract class BaseConnection implements ConnectionInterface
      */
     protected $queryClass = Query::class;
 
+    /**
+     * Default Date/Time formats
+     *
+     * @var array<string, string>
+     */
+    protected array $dateFormat = [
+        'date'        => 'Y-m-d',
+        'datetime'    => 'Y-m-d H:i:s',
+        'datetime-ms' => 'Y-m-d H:i:s.v',
+        'datetime-us' => 'Y-m-d H:i:s.u',
+        'time'        => 'H:i:s',
+    ];
+
     /**
      * Saves our connection settings.
      */
@@ -358,6 +372,10 @@ public function __construct(array $params)
             }
         }
 
+        if (isset($params['dateFormat'])) {
+            $this->dateFormat = array_merge($this->dateFormat, $params['dateFormat']);
+        }
+
         $queryClass = str_replace('Connection', 'Query', static::class);
 
         if (class_exists($queryClass)) {

tests/system/Database/BaseConnectionTest.php

@@ -80,6 +80,13 @@ public function testSavesConfigOptions(): void
         $this->assertFalse($db->compress);
         $this->assertTrue($db->strictOn);
         $this->assertSame([], $db->failover);
+        $this->assertSame([
+            'date'        => 'Y-m-d',
+            'datetime'    => 'Y-m-d H:i:s',
+            'datetime-ms' => 'Y-m-d H:i:s.v',
+            'datetime-us' => 'Y-m-d H:i:s.u',
+            'time'        => 'H:i:s',
+        ], $db->dateFormat);
     }
 
     public function testConnectionThrowExceptionWhenCannotConnect(): void

user_guide_src/source/database/configuration.rst

@@ -184,8 +184,18 @@ Explanation of Values:
                      To enforce Foreign Key constraint, set this config item to true.
 **busyTimeout**  milliseconds (int) - Sleeps for a specified amount of time when a table is locked (``SQLite3`` only).
 **numberNative** true/false (boolean) - Whether or not to enable MYSQLI_OPT_INT_AND_FLOAT_NATIVE (``MySQLi`` only).
+**dateFormat**   The default date/time formats as PHP's `DateTime format`_.
+                 * ``date``        - date format
+                 * ``datetime``    - date and time format
+                 * ``datetime-ms`` - date and time with millisecond format
+                 * ``datetime-us`` - date and time with microsecond format
+                 * ``time``        - time format
+                 This can be used since v4.5.0, and you can get the value, e.g., ``$db->dateFormat['datetime']``.
+                 Currently, the database drivers do not use these values directly, but just provide the values.
 ================ ===========================================================================================================
 
+.. _DateTime format: https://www.php.net/manual/en/datetime.format.php
+
 .. note:: Depending on what database driver you are using (``MySQLi``, ``Postgre``,
     etc.) not all values will be needed. For example, when using ``SQLite3`` you
     will not need to supply a username or password, and the database name