[wp-trac] [WordPress Trac] #40657: Deprecate current_time( 'timestamp' )

[WordPress Trac]

#40657: Deprecate current_time( 'timestamp' )
-------------------------+-----------------------------
 Reporter:  jdgrimes     |      Owner:
     Type:  enhancement  |     Status:  new
 Priority:  normal       |  Milestone:  Awaiting Review
Component:  Date/Time    |    Version:
 Severity:  normal       |   Keywords:
  Focuses:               |
-------------------------+-----------------------------
 I've just opened #40653 to address some issues with how `current_time()`
 operates internally. That ticket provides a bit of background on the age
 of the `current_time()` function and why it does what it does.

 In this ticket I'd like to specifically address the use of `current_time(
 'timestamp' )`, which 'gets the Unix timestamp of the current time in the
 site's timezone.'

 The problem is that timestamps are actually timezoneless, they are UTC,
 meaning that they are always counting the number of seconds from the Unix
 epoch, which is a certain point in time, simultaneous across all
 timezones.

 What WordPress is trying to do is [http://lists.automattic.com/pipermail
 /wp-testers/2010-April/012671.html explained by Otto here]:

 >Basically, in order to maintain consistency across older PHP 4
 installations, it was decided to have WP force the PHP environment to be
 using UTC dates for everything. [I.e., `date()` is always GMT.] Then
 WordPress itself applies the adjustments when needed.
 >
 >...
 >
 >A call to current_time( 'timestamp' ) will give you the current timestamp
 adjusted by the necessary amount to get the correct time display. So to
 get the correct date in WordPress using date(), you'd do this:
 >
 >`date('Y-m-d', current_time( 'timestamp' ));`
 >
 >How it breaks down:
 >- PHP date and time functions should always give you the info in UTC.
 >- current_time( 'timestamp' ) will give you a UTC timestamp adjusted by
 the amount necessary to show the local date.

 So this was deemed necessary for legacy reasons (PHP 4), but it is very
 confusing and tends to fool learning devs into a complete misunderstanding
 of timestamps, causing them to think that timestamps somehow have a
 timezone. In reality, this is just a quirk of legacy handling provided by
 WordPress. But it actually is no longer necessary, and probably ought to
 be deprecated, or at least discouraged.

 I say that it isn't necessary because the `current_time()` function now
 allows for any format string to be passed. This means that instead of
 this:

 `date('Y-m-d', current_time( 'timestamp' ));`

 You can skip the step of getting the "non-GMT" timestamp, and just do
 this:

 `current_time( 'Y-m-d' );`

 Also, because the timestamp does not actually carry any timezone
 information, if you do it the first way and try to format it later in a
 manner that includes timezone information, it will be UTC.
 (`current_time()` actually has this same problem right now, but it would
 be fixed by #40653.)

 In summary:
 - `current_time( 'timestamp' )` is not necessary to use, the format you
 want to convert the timestamp to can be passed directly.
 - It confuses devs into thinking that timestamps are timezone-relative,
 when they are not.
 - It won't work when ultimately converted to formats that include timezone
 information, since the timestamp does not actually include timezone info.

 It might not be worth it to actually fully deprecate the `'timestamp'` arg
 when `$gmt` is false, just because of the volume of legacy code that might
 be using this, but I thought at least I would open a ticket to raise
 awareness.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/40657>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform