Changeset 46154

Timestamp:

09/17/2019 11:13:25 AM (5 years ago)

Author:

SergeyBiryukov

Message:

Date/Time: Introduce get_post_datetime() to retrieve post published or modified time as a DateTimeImmutable object instance.

Introduce get_post_timestamp() to retrieve post published or modified time as a Unix timestamp.

Use get_post_datetime() in get_post_time() and get_post_modified_time() to return correct GMT time if default timezone is changed from UTC.

Props Rarst, johnregan3.
Fixes #25002.

Location:

trunk

Files:

• src/wp-includes/general-template.php (modified) (6 diffs)
• tests/phpunit/tests/date/postTime.php (added)

trunk/src/wp-includes/general-template.php

@@ -2516 +2516 @@
  *                          was written. Either 'G', 'U', or php date format defaults
  *                          to the value specified in the time_format option. Default empty.
- * @param int|WP_Post $post WP_Post object or ID. Default is global $post object.
+ * @param int|WP_Post $post WP_Post object or ID. Default is global `$post` object.
  * @return string|int|false Formatted date string or Unix timestamp if `$d` is 'U' or 'G'. False on failure.
  */
@@ -2554 +2554 @@
  *                               was written. Either 'G', 'U', or php date format. Default 'U'.
  * @param bool        $gmt       Optional. Whether to retrieve the GMT time. Default false.
- * @param int|WP_Post $post      WP_Post object or ID. Default is global $post object.
+ * @param int|WP_Post $post      WP_Post object or ID. Default is global `$post` object.
  * @param bool        $translate Whether to translate the time string. Default false.
  * @return string|int|false Formatted date string or Unix timestamp if `$d` is 'U' or 'G'. False on failure.
@@ -2565 +2565 @@
     }
 
-    if ( $gmt ) {
-        $time = $post->post_date_gmt;
+    $datetime = get_post_datetime( $post );
+
+    if ( false === $datetime ) {
+        return false;
+    }
+
+    if ( 'U' === $d || 'G' === $d ) {
+        $time = $datetime->getTimestamp();
+
+        // Returns a sum of timestamp with timezone offset. Ideally should never be used.
+        if ( ! $gmt ) {
+            $time += $datetime->getOffset();
+        }
+    } elseif ( $translate ) {
+        $time = wp_date( $d, $datetime->getTimestamp(), $gmt ? new DateTimeZone( 'UTC' ) : null );
     } else {
-        $time = $post->post_date;
-    }
-
-    $time = mysql2date( $d, $time, $translate );
+        if ( $gmt ) {
+            $datetime = $datetime->setTimezone( new DateTimeZone( 'UTC' ) );
+        }
+
+        $time = $datetime->format( $d );
+    }
 
     /**
@@ -2584 +2599 @@
      */
     return apply_filters( 'get_post_time', $time, $d, $gmt );
+}
+
+/**
+ * Retrieve post published or modified time as a `DateTimeImmutable` object instance.
+ *
+ * The object will be set to the timezone from WordPress settings.
+ *
+ * @since 5.3.0
+ *
+ * @param int|WP_Post $post  Optional. WP_Post object or ID. Default is global `$post` object.
+ * @param string      $field Optional. Post field to use. Accepts 'date' or 'modified'.
+ * @return DateTimeImmutable|false Time object on success, false on failure.
+ */
+function get_post_datetime( $post = null, $field = 'date' ) {
+    $post = get_post( $post );
+
+    if ( ! $post ) {
+        return false;
+    }
+
+    $time = ( 'modified' === $field ) ? $post->post_modified : $post->post_date;
+
+    if ( empty( $time ) || '0000-00-00 00:00:00' === $time ) {
+        return false;
+    }
+
+    return date_create_immutable_from_format( 'Y-m-d H:i:s', $time, wp_timezone() );
+}
+
+/**
+ * Retrieve post published or modified time as a Unix timestamp.
+ *
+ * Note that this function returns a true Unix timestamp, not summed with timezone offset
+ * like older WP functions.
+ *
+ * @since 5.3.0
+ *
+ * @param int|WP_Post $post  Optional. WP_Post object or ID. Default is global `$post` object.
+ * @param string      $field Optional. Post field to use. Accepts 'date' or 'modified'.
+ * @return int|false Unix timestamp on success, false on failure.
+ */
+function get_post_timestamp( $post = null, $field = 'date' ) {
+    $datetime = get_post_datetime( $post, $field );
+
+    if ( false === $datetime ) {
+        return false;
+    }
+
+    return $datetime->getTimestamp();
 }
 
@@ -2654 +2718 @@
  *                               was modified. Either 'G', 'U', or php date format. Default 'U'.
  * @param bool        $gmt       Optional. Whether to retrieve the GMT time. Default false.
- * @param int|WP_Post $post      WP_Post object or ID. Default is global $post object.
+ * @param int|WP_Post $post      WP_Post object or ID. Default is global `$post` object.
  * @param bool        $translate Whether to translate the time string. Default false.
  * @return string|int|false Formatted date string or Unix timestamp if `$d` is 'U' or 'G'. False on failure.
@@ -2665 +2729 @@
     }
 
-    if ( $gmt ) {
-        $time = $post->post_modified_gmt;
+    $datetime = get_post_datetime( $post, 'modified' );
+
+    if ( false === $datetime ) {
+        return false;
+    }
+
+    if ( 'U' === $d || 'G' === $d ) {
+        $time = $datetime->getTimestamp();
+
+        // Returns a sum of timestamp with timezone offset. Ideally should never be used.
+        if ( ! $gmt ) {
+            $time += $datetime->getOffset();
+        }
+    } elseif ( $translate ) {
+        $time = wp_date( $d, $datetime->getTimestamp(), $gmt ? new DateTimeZone( 'UTC' ) : null );
     } else {
-        $time = $post->post_modified;
-    }
-
-    $time = mysql2date( $d, $time, $translate );
+        if ( $gmt ) {
+            $datetime = $datetime->setTimezone( new DateTimeZone( 'UTC' ) );
+        }
+
+        $time = $datetime->format( $d );
+    }
 
     /**