php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #77719 Behavior of strtotime() and new DateTime() documentation utterly insufficient
Submitted: 2019-03-10 17:19 UTC Modified: 2019-03-10 17:59 UTC
From: teo8976 at gmail dot com Assigned:
Status: Open Package: Documentation problem
PHP Version: Irrelevant OS: all
Private report: No CVE-ID: None
Have you experienced this issue?
Rate the importance of this bug to you:

 [2019-03-10 17:19 UTC] teo8976 at gmail dot com
Description:
------------
http://php.net/manual/en/function.strtotime.php
http://php.net/manual/en/datetime.construct.php
http://php.net/manual/en/datetime.formats.php

In either of the above pages I expect to find the answer to the question:
1 - What will be the result of new DateTime("Mon 00:01")?
2 - What will be the result of new DateTime("March 1 00:01")?

1 is not obvious because: is it next monday from now, or is it the monday of the current week?
2 is not obvious because: is it next March 1 from now (i.e. March 1 of next year if we are past March 1, and March 1 of this year if we are before March 1)?

They are ESPECIALLY not obvious given that the answer is different in the two cases. For week days, it's always in the future; for a given month and day, instead, it is always in the current year, which may be in the past or in the future.


Actually I now see that the answer to 1 is at http://php.net/manual/en/datetime.formats.relative.php but I don't see the answer to 2 anywhere.
Also I'm not sure why (1) would be considered a "relative" format while (2) wouldn't (they both depend on the current time), so why woundn't the answer to 2 be found at http://php.net/manual/en/datetime.formats.relative.php too?

One way of seeing this is that (1) is "relative" by definition, while (2) is an "absolute" time string where a part (the year) is missing, and in that case the missing part is taken from the current time. If this is the explanation, I'd expect to find it in the documentation. It's a lot to guess.

The only way I could figure this out was by trying a few values.


Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2019-03-10 17:29 UTC] teo8976 at gmail dot com
Oh my.

The information at http://php.net/manual/en/datetime.formats.relative.php is not even correct, or at least not unambiguous, in providing an answer to my question number 1.

It says:
> dayname	Moves to the next day of this name.

If you write "Sun 13:00" and today is Sunday, it's completely unclear whether it's going to "move" to next sunday, or if the result is today. Actually, "move" strongly suggests that it will move to next sunday, but the actual behavior is that it will result in today (and that's regardless of whether the hour (if included in the time string) has already passed or not).
 [2019-03-10 17:59 UTC] derick@php.net
To answer your last comment, this is explained in the manual at the URL that you gave in the second "note".
 
PHP Copyright © 2001-2019 The PHP Group
All rights reserved.
Last updated: Thu Oct 17 20:01:28 2019 UTC