Date/Time component encompasses all input, output, and storage of time and date information. Its code dates back to PHP 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.
- All existing code will have more correct and reliable operation. We fixed bugs, added unit tests, and corrected inline documentation for many functions.
- WP 5.3+ code will get access to the new API 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 core 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 locale 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
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 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:
- 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: - 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