Merge pull request #6431 from kenjis/feat-Time-toDatabase

feat: add Time::toDatabase()

Author: kenjis

system/I18n/Time.php

@@ -895,7 +895,7 @@ public function toTimeString()
      *
      * @throws Exception
      *
-     * @return bool|string
+     * @return false|string
      */
     public function toLocalizedString(?string $format = null)
     {
@@ -1179,4 +1179,12 @@ public function __wakeup(): void
         $this->timezone = new DateTimeZone($timezone);
         parent::__construct($this->date, $this->timezone);
     }
+
+    /**
+     * Returns the datetime string ('Y-m-d H:i:s') that is safe to databases regardless of locale.
+     */
+    public function toDatabase(): string
+    {
+        return $this->format('Y-m-d H:i:s');
+    }
 }

tests/system/I18n/TimeTest.php

@@ -1128,4 +1128,17 @@ public function testSetTestNowWithFaLocale()
 
         Locale::setDefault($currentLocale);
     }
+
+    public function testToDatabase()
+    {
+        $currentLocale = Locale::getDefault();
+        Locale::setDefault('fa');
+
+        $time = Time::parse('2017-01-12 00:00', 'America/Chicago');
+
+        $this->assertSame('۲۰۱۷-۰۱-۱۲ ۰۰:۰۰:۰۰', (string) $time);
+        $this->assertSame('2017-01-12 00:00:00', $time->toDatabase());
+
+        Locale::setDefault($currentLocale);
+    }
 }

user_guide_src/source/changelogs/v4.3.0.rst

@@ -70,6 +70,7 @@ Others
 - Added new Form helper function :php:func:`validation_errors()`, :php:func:`validation_list_errors()` and :php:func:`validation_show_error()` to display Validation Errors.
 - Now you can autoload helpers by **app/Config/Autoload.php**.
 - ``BaseConnection::escape()`` now excludes the ``RawSql`` data type. This allows passing SQL strings into data.
+- Added :ref:`Time::toDatabase() <time-todatabase>` to get a datetime string that can be used with databases regardless of locale.
 
 Changes
 *******

user_guide_src/source/libraries/time.rst

@@ -171,6 +171,17 @@ Displays just the localized version of time portion of the value:
 
 .. literalinclude:: time/018.php
 
+.. _time-todatabase:
+
+toDatabase()
+============
+
+.. versionadded:: 4.3.0
+
+This method returns a string that can be used with databases regardless of locale.
+
+.. literalinclude:: time/042.php
+
 humanize()
 ==========
 

user_guide_src/source/libraries/time/042.php

@@ -0,0 +1,9 @@
+<?php
+
+// Locale: en
+$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
+echo $time->toDatabase(); // '2016-03-09 12:00:00'
+
+// Locale: fa
+$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
+echo $time->toDatabase(); // '2016-03-09 12:00:00'