Changeset 45908

Timestamp:

08/29/2019 05:06:15 AM (5 years ago)

Author:

SergeyBiryukov

Message:

Date/Time: Revamp mysql2date() to use wp_date() and handle invalid input in a consistent manner.

Add unit tests, improve documentation.

Props Rarst, pbearne.
Fixes #28992.

Location:

trunk

Files:

• src/wp-includes/functions.php (modified) (7 diffs)
• tests/phpunit/tests/date/mysql2date.php (added)

trunk/src/wp-includes/functions.php

@@ -9 +9 @@
 
 /**
- * Convert given date string into a different format.
- *
- * $format should be either a PHP date format string, e.g. 'U' for a Unix
- * timestamp, or 'G' for a Unix timestamp assuming that $date is GMT.
- *
- * If $translate is true then the given date and format string will
- * be passed to date_i18n() for translation.
+ * Convert given MySQL date string into a different format.
+ *
+ * `$format` should be a PHP date format string.
+ * 'U' and 'G' formats will return a sum of timestamp with timezone offset.
+ * `$date` is expected to be local time in MySQL format (`Y-m-d H:i:s`).
+ *
+ * Historically UTC time could be passed to the function to produce Unix timestamp.
+ *
+ * If `$translate` is true then the given date and format string will
+ * be passed to `wp_date()` for translation.
  *
  * @since 0.71
@@ -22 +25 @@
  * @param string $date      Date string to convert.
  * @param bool   $translate Whether the return date should be translated. Default true.
- * @return string|int|bool Formatted date string or Unix timestamp. False if $date is empty.
+ * @return string|int|false Formatted date string or sum of Unix timestamp and timezone offset.
+ *                          False on failure.
  */
 function mysql2date( $format, $date, $translate = true ) {
@@ -29 +33 @@
     }
 
-    if ( 'G' == $format ) {
-        return strtotime( $date . ' +0000' );
-    }
-
-    $i = strtotime( $date );
-
-    if ( 'U' == $format ) {
-        return $i;
+    $datetime = date_create( $date, wp_timezone() );
+
+    if ( false === $datetime ) {
+        return false;
+    }
+
+    // Returns a sum of timestamp with timezone offset. Ideally should never be used.
+    if ( 'G' === $format || 'U' === $format ) {
+        return $datetime->getTimestamp() + $datetime->getOffset();
     }
 
     if ( $translate ) {
-        return date_i18n( $format, $i );
-    } else {
-        return gmdate( $format, $i );
-    }
+        return wp_date( $format, $datetime->getTimestamp() );
+    }
+
+    return $datetime->format( $format );
 }
 
@@ -59 +64 @@
  * @since 1.0.0
  *
- * @param string   $type Type of time to retrieve. Accepts 'mysql', 'timestamp', or PHP date
- *                       format string (e.g. 'Y-m-d').
+ * @param string   $type Type of time to retrieve. Accepts 'mysql', 'timestamp',
+ *                       or PHP date format string (e.g. 'Y-m-d').
  * @param int|bool $gmt  Optional. Whether to use GMT timezone. Default false.
  * @return int|string Integer if $type is 'timestamp', string otherwise.
@@ -152 +157 @@
  *
  * @param string   $format                Format to display the date.
- * @param int|bool $timestamp_with_offset Optional. A sum of Unix timestamp and timezone offset in seconds.
- *                                        Default false.
- * @param bool     $gmt                   Optional. Whether to use GMT timezone. Only applies if timestamp is
- *                                        not provided. Default false.
+ * @param int|bool $timestamp_with_offset Optional. A sum of Unix timestamp and timezone offset
+ *                                        in seconds. Default false.
+ * @param bool     $gmt                   Optional. Whether to use GMT timezone. Only applies
+ *                                        if timestamp is not provided. Default false.
  * @return string The date, translated if locale specifies it.
  */
@@ -205 +210 @@
  * This is a newer function, intended to replace `date_i18n()` without legacy quirks in it.
  *
- * Note that, unlike `date_i18n()`, this function accepts a true Unix timestamp, not summed with timezone offset.
+ * Note that, unlike `date_i18n()`, this function accepts a true Unix timestamp, not summed
+ * with timezone offset.
  *
  * @since 5.3.0
@@ -211 +217 @@
  * @param string       $format    PHP date format.
  * @param int          $timestamp Optional. Unix timestamp. Defaults to current time.
- * @param DateTimeZone $timezone  Optional. Timezone to output result in. Defaults to timezone from site settings.
- *
+ * @param DateTimeZone $timezone  Optional. Timezone to output result in. Defaults to timezone
+ *                                from site settings.
  * @return string The date, translated if locale specifies it.
  */