Date/Time component improvements in WordPress 5.3

Date/Time component encompasses all input, output, and storage of time and date information. Its code dates back to PHP 4 implementation in an early version and went through partial PHP 5 retrofit.

For over a year and several WP releases, we ran a project dubbed “wp_date” to fix and improve the component. Final parts of this effort will ship with WordPress 5.3.

  1. All existing code will have more correct and reliable operation. We fixed bugs, added unit tests, and corrected inline documentation for many functions.
  2. WP 5.3+ code will get access to the new API functions, for convenience and PHP interoperability.

New API functions

We improved the component’s API, made possible by raising the required PHP version to 5.6 in the core.

Unified time zone retrieval

  • wp_timezone_string() a single way to retrieve site time zone, regardless of settings (timezone_string/gmt_offset options). Might return Region/Location string or ±NN:NN offset. Both are now valid inputs for PHP versions supported by core.
  • wp_timezone() retrieves site time zone as DateTimeZone object.

New date localization

  • titular wp_date() is a ground–up rewrite of date localization with WordPress locale. It works with Unix timestamps and PHP time zone objects.
    • date_i18n() function is now a legacy wrapper around wp_date().

PHP interoperability

  • current_datetime() retrieves current moment of time as DateTimeImmutable object.
  • get_post_datetime() retrieves post time as DateTimeImmutable object.
  • get_post_timestamp() retrieves post time as Unix timestamp.

Phasing out WP timestamps

Date/Time component relied on so–called “WordPress timestamp” — a sum of Unix timestamp with a time zone offset. This was causing many bugs and lack of interoperability with upstream PHP or any external systems. Inline documentation erroneously referred to these as Unix timestamps.

It is impossible to remove WP timestamps without backwards compatibility break. But we made significant progress to:

  • cut their use in core;
  • correct invalid inline documentation;
  • offer new API using real Unix timestamps.

Not recommended

  • don’t retrieve time as WP timestamp:
  • don’t localize time based on WP timestamp:
    • date_i18n( DATE_RFC3339, $timestamp + $offset )
  • don’t store WP timestamps persistently;
  • don’t compare WP timestamps.

Recommended

  • retrieve time as Unix timestamp or DateTimeImmutable object:
    • time()
    • current_datetime()
    • get_post_datetime()
    • get_post_timestamp()
  • localize time based on Unix timestamp:
    • wp_date( DATE_RFC3339, $timestamp )
  • store Unix timestamps or formats that are precise moment in time, such as DATE_RFC3339;
  • compare Unix timestamps, DateTimeInterface objects, or string–comparable dates in same time zone.

Summary

Date/Time core component had received much–needed fixes and a set of improvements. Code on WordPress platform will be more convenient and reliable with times and dates.

If you have questions about the improvements or component in general feel free to drop by #core-datetime channel in WordPress Slack.

#5-3, #dev-notes