DateTime.createFromFormat description is misleading about doc-en HOT 8 CLOSED

I fixed this in the documentation last week: e5373bc

from doc-en.

Furthermore, I don't believe the | modifier is working at all.
IIRC, I had previously used
$date=DateTime::createFromFormat('Y-m-d|', '2021-08-12 13:14:15');
for example in order to get 2021-08-12 00:00:00, but now that seems to return false, at least in PHP 7.4 and 8.0.
I thought it was meant to reset all fields that haven't been parsed at that point.
Seem I now need to put 'Y-m-d|+' to have it ignore the H:i:s component.
DateTime::getLastErrors seems to be empty when this fails.

from doc-en.

The documentation seems flipped to me.

Yet, it behaves the other way around: with the position of ! being important and the position of | not making a difference at all. | anywhere behaves as if ! was placed at the beginning.

<?php
var_dump(DateTime::createFromFormat('!Y-m-d', '2023-08-23'));
# 2023-08-23 00:00:00.000000

var_dump(DateTime::createFromFormat('Y-!m-d', '2023-08-23'));
# 1970-08-23 00:00:00.000000

var_dump(DateTime::createFromFormat('Y-m-d!', '2023-08-23'));
# 1970-01-01 00:00:00.000000

var_dump(DateTime::createFromFormat('Y-m-d|', '2023-08-23'));
# 2023-08-23 00:00:00.000000

var_dump(DateTime::createFromFormat('|Y-m-d', '2023-08-23'));
# 2023-08-23 00:00:00.000000

Tested at https://onlinephp.io/ with php 8.2.9.

from doc-en.

@WoodrowShigeru What about it is "flipped"?

! in the string will reset the current "state" of the date to be the Unix epoch. It also means anything parsed so far is discarded, so putting this anywhere except the beginning of the string would be weird.
| resets to the epoch too, but only the parts of the date that haven't been parsed so far. Because of how it works, the effect is the same regardless of where it's placed in the format string.

They're very similar, but the main difference between the two is the "feel" of how they work: ! is suited to the beginning of the format string and conveys the intention of "start from zero instead of the current time, then...", while | is suited for the end of the format string and conveys "...and make everything else be zero".

!Y-m-d = reset everything to zero/the epoch, then parse a date
Y-m-d| = parse a date, then reset the other parts not listed here to zero

from doc-en.

The "if they have not been parsed yet" part should be written behind ! imo. What's written left of the character is parsed and will not be reset anymore. The | variant always resets all fields regardless of parsing.

from doc-en.

The "if they have not been parsed yet" part should be written behind ! imo. What's written left of the character is parsed and will not be reset anymore.

Uh, no? ! will reset everything, including fields that have been parsed. This is extremely easy to demonstrate:

// if ! resets everything then this will be 1970-01-01
// if ! resets unparsed fields then this will be 2023-08-27
DateTime::createFromFormat("Y-m-d!", "2023-08-27")

https://3v4l.org/JsFf3

The | variant always resets all fields regardless of parsing.

Also no. | only resets fields that have not been parsed. Here's a similar demonstration:

// if | resets everything then this will be 1970-01-01
// if | resets unparsed fields then this will be 2023-08-27
DateTime::createFromFormat("Y-m-d|", "2023-08-27")

https://3v4l.org/6m9F4

I'm not sure how but you definitely have those two backwards.

from doc-en.

! will reset everything

Admittedly, in post #671 (comment) I might have mixed up left and right – which does not help me convey my point.

The point is that the position of ! matters:

DateTime::createFromFormat('Y-!m-d', '2023-08-23');
# → 1970-08-23 00:00:00.000000, the "08" and "23" remain.

This only resets some fields. Some != all.

　​

The | variant always resets all fields regardless of parsing.

That is unfortunate phrasing on my part because I keep seeing "parsing" as "everything on one side of that special character". A better phrasing of what I meant would have been: the | variant always resets the same fields regardless of the position.

After reading all parts in this thread more carefully and doing more tests, I guess I can now understand the "if they have not been parsed yet" part standing in the | description.

　​

However, I would agree with the rest of the documentation only if ! at the beginning would be the only possible way to use the !. It's not. You can write it in the middle of the format string, and then it behaves differently.

It's true (but misleadingly phrased) that ! resets all fields only if you know that it first resets the fields and then parses the date – as you've described. But the documentation doesn't mention that part at all. That's, like, outside knowledge … or insider knowledge …

from doc-en.

This only resets some fields. Some != all.

No, it does reset all of them...

I think I see what you're missing: the ! happens at the moment it's encountered, not like at the end when the process is (nearly) complete and everything has been read in. Parsing the format Y-!m-d means specific actions in a specific order, read from left to right:

1. Parse the Y and skip a hyphen (Y=2023, m=current month, d=current day)
2. Reset all the fields (Y=1970, m=1, d=1)
3. Parse the m and skip a hyphen (Y=1970, m=8, d=1)
4. Parse the d (Y=1970, m=8, d=23)

The year was parsed before getting reset so that value was lost, while the month and day were parsed after getting reset so their values were kept.

So yes, while you can put | anywhere, it doesn't really make sense to have it anywhere except the beginning: why bother parsing something like a year if you're just going to reset it to 1970 anyway?
(I can imagine some unusual exceptions where it could make sense, but they really are unusual exceptions. Most people would want "reset everything because I don't want PHP using the current date/time for default values", and you do that with ! by putting it at the beginning.)

from doc-en.