Date/Time in WordPress

The Date/Time component includes all operations of input, output, and storage of information about time and dates in WordPress.

The WP code for working with time and a bunch of related functions were written a long time ago, back to PHP 4 version. There were a lot of shortcomings and bugs in the work of such functions, many of which were fixed in the WordPress 5.3 version. It is very difficult to fix everything due to backward compatibility.

Over a year of work was done on the code related to working with time in WP, which was released in version 5.3. Let's consider how Date/Time works now and what was done in WordPress 5.3. In short, the following was done:

1. Stable and correct operation of all existing code related to dates and times. Errors were fixed, modular tests were added, and built-in documentation for many functions was corrected.

2. New Date API functions appeared with WP 5.3+ for convenience and compatibility with PHP.

3. The code was improved thanks to the new capabilities of PHP 5.6. Just a reminder, this is now the minimum version for WP.

New API Functions

Unified Way of Getting Timezone

• wp_timezone_string() - a unified way to get the site's timezone, regardless of settings (options timezone_string/gmt_offset).

  The function will return the string Region/Location, for example Asia/Tashkent or the string ±NN:NN, for example +02:00. Both options are valid for PHP versions.

• wp_timezone() extracts the site's timezone as a DateTimeZone object.

New Date Localization

• wp_date() - the main function is a complete overhaul of date localization in WordPress. It works with Unix timestamps and PHP time zone objects, for example DateTimeZone.

Interaction with PHP

• current_datetime() - retrieves the current moment in time as a DateTimeImmutable object.

• get_post_datetime() - gets the post time as a DateTimeImmutable object.

• get_post_timestamp() - gets the post time as a Unix timestamp - 1270995315.

Moving Away from WP Timestamps

The WP Date/Time API relied on the so-called "WordPress timestamp" - WP timestamps - this is a Unix timestamp plus the site's timezone offset. This caused many errors and lack of compatibility with previous PHP versions or any external systems. The documentation erroneously mentioned Unix timestamps, when in fact "WP timestamps" were used.

It is impossible to remove WP timestamps without breaking backward compatibility. But developers have made significant progress to:

• reduce their usage in the core.
• correct incorrect documentation.
• propose a new API using real Unix timestamps.

Thus, since WP version 5.3:

Not recommended:

• DO NOT retrieve time as a "WP timestamps" (timestamp + site time offset):

  • current_time( 'timestamp' ) or current_time( 'U' )
  • get_post_time( 'U' )

• DO NOT localize time/date using the function:

  • date_i18n( DATE_RFC3339, $timestamp + $offset )

• DO NOT persistently store "WP timestamps".

• DO NOT compare "WP timestamps".

• DO NOT change the PHP time zone via date_default_timezone_set() - this is an important requirement for the core to work correctly. By default, WP sets date_default_timezone_set( 'UTC' ) and this setting should never be changed!

Recommended:

Below are the DATE_RFC3339 formats.

• Retrieve time as a "Unix timestamp" (Unix timestamp without offset) or as a DateTimeImmutable object:

  • time()
  • current_datetime().
  • get_post_datetime().
  • get_post_timestamp().

• Localize time/date based on Unix timestamp:

  • wp_date( DATE_RFC3339 ) - this is the same as wp_date( DATE_RFC3339, time() ).

• Store "Unix timestamps" or formats that accurately specify the moment of time, such as DATE_RFC3339.

• Compare Unix timestamps, DateTimeImmutable objects, or string dates in a single time zone.

• Use objects: DateTimeZone and DateTimeImmutable with the wp_date() function when processing time in a different time zone from the site's zone.

--

Source: https://make.wordpress.org/core/2019/09/23/date-time-improvements-wp-5-3/