[wp-trac] [WordPress Trac] #38771: date_i18n() arguments are misleading in function and documentation

[WordPress Trac]

#38771: date_i18n() arguments are misleading in function and documentation
-------------------------+-----------------------------
 Reporter:  Rarst        |      Owner:
     Type:  enhancement  |     Status:  new
 Priority:  normal       |  Milestone:  Awaiting Review
Component:  Date/Time    |    Version:  trunk
 Severity:  normal       |   Keywords:
  Focuses:               |
-------------------------+-----------------------------
 `date_i18n()` is documented as following:

 {{{
 date_i18n( $dateformatstring, $unixtimestamp = false, $gmt = false )

 @param string   $dateformatstring Format to display the date.
 @param bool|int $unixtimestamp    Optional. Unix timestamp. Default false.
 @param bool     $gmt              Optional. Whether to use GMT timezone.
 Default false.
 }}}

 Second and third arguments are highly problematic.

 Let's look at this case:

 {{{#!php
 var_dump( date_default_timezone_get() );     // string(3) "UTC" < WP core
 resets to this during boot
 var_dump( get_option( 'timezone_string' ) ); // string(11) "Europe/Kiev" <
 site's setting
 var_dump( get_option( 'gmt_offset' ) );      // float(2) < numeric offset

 $now = strtotime( 'now' );
 var_dump( $now ); // int(1478987901)

 var_dump( date( DATE_W3C, $now ) );           // string(25)
 "2016-11-12T21:58:21+00:00" < PHP native UTC time, so far so good

 var_dump( date_i18n( DATE_W3C, $now ) );      // string(25)
 "2016-11-12T21:58:21+02:00" < this is UTC time w/ timezone replaced (!!!)
 var_dump( date_i18n( DATE_W3C, $now, true) ); // string(25)
 "2016-11-12T21:58:21+02:00" < still same, $gmt is meaningless

 $now = $now + get_option( 'gmt_offset' ) * HOUR_IN_SECONDS; // "WordPress
 timestamp"
 var_dump( date_i18n( DATE_W3C, $now, true) ); // string(25)
 "2016-11-12T23:58:21+02:00"  < actually "correct" time
 }}}

 Observations:

 1. Function does not output correct "local" site time
 2. Actual output consists of GMT time with site's timezone simply
 replacing real UTC timezone
 3. `$gmt` argument has no effect since WP always resets timezone to GMT,
 it's never ''not'' GMT under normal operation
 4. For correct output `$unixtimestamp` needs to be adjusted by timezone
 offset, making it anything but Unix timestamp.

 This is probably way too grown in for any kind of a code change. But at
 the very least:

 1. `$unixtimestamp` '''needs''' to be thoroughly documented/renamed as
 WP's own take on timestamp, '''incompatible''' with actual Unix
 timestamps.
 2. `$gmt` could as well be deprecated since it does nothing and when it
 does something  (timezone changed by third party code) it just further
 confuses the results.

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