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 PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher 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 APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. 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 coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress..

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 localeLocale A locale is a combination of language and regional dialect. Usually locales correspond to countries, as is the case with Portuguese (Portugal) and Portuguese (Brazil). Other examples of locales include Canadian English and U.S. English.. 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 invalidinvalid A resolution on the bug tracker (and generally common in software development, sometimes also notabug) that indicates the ticket is not a bug, is a support request, or is generally invalid. inline documentation;
• offer new API using real Unix timestamps.

Not recommended

• don’t retrieve time as WP timestamp:
  • current_time( 'timestamp' )
  • get_post_time( 'U' )
• 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;
• don’t change PHP time zone with date_default_timezone_set() (this one is hard requirement for correct core operation!)

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;
• use DateTimeZone and DateTimeImmutable objects (with wp_date() for localization), if you need to operate with different time zones.

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