mktime error documentation

[anthonyeden]

From manual page: https://php.net/function.mktime

---

In a similar vein to #1558, the mtkime docs states "If the arguments are invalid, the function returns false." Under "Errors/Exceptions" it says "Every call to a date/time function will generate a E_WARNING if the time zone is not valid"

However, in PHP 8 it throws a E_ERROR / TypeError if you supply invalid parameters.

I know invalid params in PHP 8 throw TypeErrors and ValueErrors, but I think the docs need a big re-think if it's okay for pages to state certain error conditions but not all of them. PHP docs used to be quite helpful in showing all fatal error states, but since the move to PHP 8 they haven't really kept up.

[Girgias]

TypeErrors are a standard error so documenting this on every page makes little to no sense.
ValueErrors it's less clear, but it's a huge effort, I tried to automate the list somewhat in #163 but still this cannot be done by one person.

Moreover, most docs that I'm aware of were lacking in return types, diagnostic and exceptions completeness behaviour. And this coverage got increased with the usage of stubs in PHP 8.0.

In any case PRs are accepted and appreciated.

[anthonyeden]

Fair enough, thanks @Girgias.

I just feel like documentation should somehow cover all possible return values, exceptions, etc. that can be generated by that function. Especially given PHP has traditionally been very relaxed about which types it accepts, and tended to fail silently (just return a fall/null, and log an error).

Is there any merit in automatically inserting notes into the "Return values" section warning about possible TypeErrors and ValueErrors?

I recognise I'm likely alone in this view, and I'm also not the one writing or updating documentation. I have a lot of respect for you and others on the team who have taken this on.

[cmb69]

From the docs (emphasis mine):

If the parameters given to a function are not what it expects, such as passing an array where a string is expected, the return value of the function is undefined. In this case it will likely return null but this is just a convention, and cannot be relied upon. As of PHP 8.0.0, a TypeError exception is supposed to be thrown in this case.

So these return values should never have been documented; they are of no concern to userland developers, who simply need to make sure to pass arguments of supported types.