Doc #76569 [Asn->Csd]: Description of ???!??? And ???|??? of DateTime::createFromFormat

Edit report at https://bugs.php.net/bug.php?id=76569&edit=1

 ID:                 76569
 Updated by:         [email protected]
 Reported by:        manabu dot matsui at gmail dot com
 Summary:            Description of “!” And “|” of
                     DateTime::createFromFormat
-Status:             Assigned
+Status:             Closed
 Type:               Documentation Problem
 Package:            Date/time related
 Operating System:   N/A
 PHP Version:        Irrelevant
 Assigned To:        derick
 Block user comment: N
 Private report:     N

 New Comment:

The fix for this bug has been committed.
If you are still experiencing this bug, try to check out latest source from https://github.com/php/php-src and re-test.
Thank you for the report, and for helping us make PHP better.

This was already correctly documented as:

Resets all fields (year, month, day, hour, minute, second, fraction and timezone information) to zero-like values ( 0 for hour, minute, second and fraction, 1 for month and day, 1970 for year and UTC for timezone information)


Previous Comments:
------------------------------------------------------------------------
[2021-10-21 18:52:37] [email protected]

I can confirm the reported behavior: <https://3v4l.org/i71Kc> and
<https://3v4l.org/TU9Pu>.  I'm not sure, though, whether it is
intentional that ! and | reset to the default timezone.  Derick,
can you please clarify?

------------------------------------------------------------------------
[2018-11-10 16:33:17] salmanarshad2000 at yahoo dot com

I have noticed the same behavior and agree that the documentation needs to be corrected. The documentation seems to suggest that including ! or | inside the format string will result in a datetime with UTC / +00:00 timezone e.g.:

object(DateTime)#1 (3) {
  ["date"]=>
  string(26) "2000-01-01 00:00:00.000000"
  ["timezone_type"]=>
  int(1)
  ["timezone"]=>
  string(6) "+00:00"
}

Or:

object(DateTime)#1 (3) {
  ["date"]=>
  string(26) "2000-01-01 00:00:00.000000"
  ["timezone_type"]=>
  int(2)
  ["timezone"]=>
  string(3) "UTC"
}

But it does not produce the result I assumed by reading the documentation.

Other: the documentation also examples of using "|" and how it differs from "!".

------------------------------------------------------------------------
[2018-07-02 22:59:27] manabu dot matsui at gmail dot com

Description:
------------
At http://php.net/manual/en/datetime.createfromformat.php, description of format character “!” And “|” are as follows:

“!”
Resets all fields (year, month, day, hour, minute, second, fraction and timezone information) to the Unix Epoch

“|”
Resets all fields (year, month, day, hour, minute, second, fraction and timezone information) to the Unix Epoch if they have not been parsed yet

And in the rest of this document, the UNIX epoch is explained as follows:

> The Unix epoch is 1970-01-01 00:00:00 UTC.

But actually, they appear to reset to 1970-01-01 00:00:00 in the resulting timezone, not UTC.

% php -d date.timezone=Asia/Tokyo -r 'var_dump(DateTime::createFromFormat("!", ""));'
object(DateTime)#1 (3) {
  ["date"]=>
  string(26) "1970-01-01 00:00:00.000000"
  ["timezone_type"]=>
  int(3)
  ["timezone"]=>
  string(10) "Asia/Tokyo"
}
% php -d date.timezone=Asia/Tokyo -r 'var_dump(DateTime::createFromFormat("!", "")->getTimestamp());'
int(-32400)
% php -r 'var_dump(DateTime::createFromFormat("!", "", new DateTimeZone("Asia/Tokyo")));'
object(DateTime)#2 (3) {
  ["date"]=>
  string(26) "1970-01-01 00:00:00.000000"
  ["timezone_type"]=>
  int(3)
  ["timezone"]=>
  string(10) "Asia/Tokyo"
}

Since the current behavior is more useful, I think this is a problem of documentation.



------------------------------------------------------------------------



--
Edit this bug report at https://bugs.php.net/bug.php?id=76569&edit=1