Changeset 45901

Timestamp:

08/28/2019 12:51:16 AM (5 years ago)

Author:

SergeyBiryukov

Message:

Date/Time: Introduce wp_date() to retrieve the date in localized format.

Convert date_i18n() into a wrapper for wp_date().

wp_date() is intended as a replacement for date_i18n() without legacy quirks in it. It accepts a true Unix timestamp (not summed with timezone offset) and an arbitrary timezone.

Props Rarst, mboynes, MikeHansenMe, rmccue, nacin.
Fixes #28636.

Location:

trunk/src/wp-includes

Files:

• default-filters.php (modified) (1 diff)
• functions.php (modified) (5 diffs)

trunk/src/wp-includes/default-filters.php

@@ -209 +209 @@
 add_filter( 'widget_text_content', 'shortcode_unautop' );
 add_filter( 'widget_text_content', 'do_shortcode', 11 ); // Runs after wpautop(); note that $post global will be null when shortcodes run.
-
-add_filter( 'date_i18n', 'wp_maybe_decline_date' );
 
 // RSS filters

trunk/src/wp-includes/functions.php

@@ -92 +92 @@
 
 /**
- * Retrieves the timezone from current settings as a string.
+ * Retrieves the timezone from site settings as a string.
  *
  * Uses the `timezone_string` option to get a proper timezone if available,
@@ -121 +121 @@
 
 /**
- * Retrieves the timezone from current settings as a `DateTimeZone` object.
+ * Retrieves the timezone from site settings as a `DateTimeZone` object.
  *
  * Timezone can be based on a PHP timezone string or a ±HH:MM offset.
@@ -147 +147 @@
  *
  * @since 0.71
+ * @since 5.3.0 Converted into a wrapper for wp_date().
  *
  * @global WP_Locale $wp_locale WordPress date and time locale object.
  *
- * @param string   $dateformatstring      Format to display the date.
+ * @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.
- *
  * @return string The date, translated if locale specifies it.
  */
-function date_i18n( $dateformatstring, $timestamp_with_offset = false, $gmt = false ) {
-    global $wp_locale;
-
-    $i = $timestamp_with_offset;
-
-    if ( ! is_numeric( $i ) ) {
-        $i = current_time( 'timestamp', $gmt );
-    }
-
-    /*
-     * Store original value for language with untypical grammars.
-     * See https://core.trac.wordpress.org/ticket/9396
-     */
-    $req_format = $dateformatstring;
-    $new_format = '';
-
-    // We need to unpack shorthand `r` format because it has parts that might be localized.
-    $dateformatstring = preg_replace( '/(?<!\\\\)r/', DATE_RFC2822, $dateformatstring );
-
-    /*
-     * Timestamp with offset is typically produced by a UTC `strtotime()` call on an input without timezone.
-     * This is the best attempt to reverse that operation into a local time to use.
-     */
-    $local_time = gmdate( 'Y-m-d H:i:s', $i );
-    $gmt_mode   = $gmt && ( false === $timestamp_with_offset );
-    $timezone   = $gmt_mode ? new DateTimeZone( 'UTC' ) : wp_timezone();
-    $datetime   = date_create( $local_time, $timezone );
+function date_i18n( $format, $timestamp_with_offset = false, $gmt = false ) {
+    // If timestamp is omitted it should be current time (summed with offset, unless `$gmt` is true).
+    $timestamp = $timestamp_with_offset ? $timestamp_with_offset : current_time( 'timestamp', $gmt );
 
     /*
@@ -190 +166 @@
      * Ideally this function should never be used to produce a timestamp.
      */
-    $timestamp_mode = ( 'U' === $dateformatstring );
-
-    if ( $timestamp_mode ) {
-        $new_format = $i;
-    }
-
-    if ( ! $timestamp_mode && ! empty( $wp_locale->month ) && ! empty( $wp_locale->weekday ) ) {
-        $month   = $wp_locale->get_month( $datetime->format( 'm' ) );
-        $weekday = $wp_locale->get_weekday( $datetime->format( 'w' ) );
-
-        $format_length = strlen( $dateformatstring );
+    if ( 'U' === $format ) {
+        $date = $timestamp;
+    } elseif ( $gmt && ! $timestamp_with_offset ) { // Current time in UTC.
+        $date = wp_date( $format, null, new DateTimeZone( 'UTC' ) );
+    } elseif ( ! $timestamp_with_offset ) { // Current time in site's timezone.
+        $date = wp_date( $format );
+    } else {
+        /*
+         * Timestamp with offset is typically produced by a UTC `strtotime()` call on an input without timezone.
+         * This is the best attempt to reverse that operation into a local time to use.
+         */
+        $local_time = gmdate( 'Y-m-d H:i:s', $timestamp );
+        $timezone   = wp_timezone();
+        $datetime   = date_create( $local_time, $timezone );
+        $date       = wp_date( $format, $datetime->getTimestamp(), $timezone );
+    }
+
+    /**
+     * Filters the date formatted based on the locale.
+     *
+     * @since 2.8.0
+     *
+     * @param string $date      Formatted date string.
+     * @param string $format    Format to display the date.
+     * @param int    $timestamp A sum of Unix timestamp and timezone offset in seconds.
+     *                          Might be without offset if input omitted timestamp but requested GMT.
+     * @param bool   $gmt       Whether to use GMT timezone. Only applies if timestamp was not provided.
+     *                          Default false.
+     */
+    $date = apply_filters( 'date_i18n', $date, $format, $timestamp, $gmt );
+
+    return $date;
+}
+
+/**
+ * Retrieves the date, in localized format.
+ *
+ * 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.
+ *
+ * @since 5.3.0
+ *
+ * @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.
+ *
+ * @return string The date, translated if locale specifies it.
+ */
+function wp_date( $format, $timestamp = null, $timezone = null ) {
+    global $wp_locale;
+
+    if ( ! $timestamp ) {
+        $timestamp = time();
+    }
+
+    if ( ! $timezone ) {
+        $timezone = wp_timezone();
+    }
+
+    $datetime = date_create( '@' . $timestamp );
+    $datetime->setTimezone( $timezone );
+
+    if ( empty( $wp_locale->month ) || empty( $wp_locale->weekday ) ) {
+        $date = $datetime->format( $format );
+    } else {
+        // We need to unpack shorthand `r` format because it has parts that might be localized.
+        $format = preg_replace( '/(?<!\\\\)r/', DATE_RFC2822, $format );
+
+        $new_format    = '';
+        $format_length = strlen( $format );
+        $month         = $wp_locale->get_month( $datetime->format( 'm' ) );
+        $weekday       = $wp_locale->get_weekday( $datetime->format( 'w' ) );
 
         for ( $i = 0; $i < $format_length; $i ++ ) {
-            switch ( $dateformatstring[ $i ] ) {
+            switch ( $format[ $i ] ) {
                 case 'D':
                     $new_format .= backslashit( $wp_locale->get_weekday_abbrev( $weekday ) );
@@ -223 +261 @@
                     break;
                 case '\\':
-                    $new_format .= $dateformatstring[ $i ];
+                    $new_format .= $format[ $i ];
 
                     // If character follows a slash, we add it without translating.
                     if ( $i < $format_length ) {
-                        $new_format .= $dateformatstring[ ++$i ];
+                        $new_format .= $format[ ++$i ];
                     }
                     break;
                 default:
-                    $new_format .= $dateformatstring[ $i ];
+                    $new_format .= $format[ $i ];
                     break;
             }
         }
-    }
-
-    $j = $datetime->format( $new_format );
+
+        $date = $datetime->format( $new_format );
+        $date = wp_maybe_decline_date( $date );
+    }
 
     /**
      * Filters the date formatted based on the locale.
      *
-     * @since 2.8.0
-     *
-     * @param string $j          Formatted date string.
-     * @param string $req_format Format to display the date.
-     * @param int    $i          A sum of Unix timestamp and timezone offset in seconds.
-     * @param bool   $gmt        Whether to use GMT timezone. Only applies if timestamp was
-     *                           not provided. Default false.
+     * @since 5.3.0
+     *
+     * @param string       $date      Formatted date string.
+     * @param string       $format    Format to display the date.
+     * @param int          $timestamp Unix timestamp.
+     * @param DateTimeZone $timezone  Timezone.
+     *
      */
-    $j = apply_filters( 'date_i18n', $j, $req_format, $i, $gmt );
-
-    return $j;
+    $date = apply_filters( 'wp_date', $date, $format, $timestamp, $timezone );
+
+    return $date;
 }