Problem with interpretation of U and G formats in dates as WP timestamps

[Rarst]

WordPress mostly follows upstream date() for date formatting. However there is a significant deviation with U and G.

The PHP manual's definition for these are:

• U Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)
• G 24-hour format of an hour without leading zeros

WordPress has quite a different interpretation. First, it calls both of these Unix timestamp formats. However what it tends to return for them are "WordPress timestamps", effectively a sum of Unix timestamp with timezone offset, produced either explicitly (by adding gmt_offset to a Unix timestamp) or implicitly (by parsing stored non-GMT time as GMT input).

The only time when WordPress timestamp is equal to Unix timestamp is when it is produced with zero offset or parsed from GMT time.

This creates incredible challenge in correct operation, interoperability with PHP, and developer experience. It isn’t humanly possible to be constantly aware is the chunk of numbers has meaning as Unix timestamp or WP timestamp, especially since inline documentation constantly mis–names latter as former.

Since some API functions expect WP timestamps at this point backwards compatibility makes it impossible to just change these formats to actual Unix timestamps in existing functions.

So far I see the only way to salvage this:

1. Deprecate every API function that returns or consumes WP timestamps in response to G/U formats (date_i18n() and mysql2date() are huge chunk of that).
2. For functions that can produce correct Unix timestamps for G/U formats, deprecate combinations of arguments that lead to WP timestamps, such as get_post_time() with $gmt = false.

Yes, this pretty much obliterates existing Date/Time API. However under current backwards compatibility commitments it would be impossible to keep WP timestamps and move towards meaningful and reliable operation in it.

[Rarst]

#43269 was marked as a duplicate.

[Rarst]

Ok, we can't really obliterate the API. That was unrealistic.

I am writing the new API parts to work with real proper timestamps and adding inline comments about local timestamps in old stuff.

Once I have new API in place I will probably suggest sniffs discouraging WP timestamps in WPCS.

Closing the issue since this isn't really contained or going to be "done" at any clear point.