Re: DateTimeImmutable::modify() return type: doc or language bug?
| From: | Christoph M. Becker | Date: | Tue, 03 Jan 2023 15:43:49 +0000 |
| Subject: | Re: DateTimeImmutable::modify() return type: doc or language bug? | ||
| References: | 1 | Groups: | php.internals |
| Request: | Send a blank email to internals+get-119225@lists.php.net to get a copy of this message | ||
On 03.01.2023 at 10:48, Philip Hofstetter wrote:
>
DateTimeImmutable::modify() is documented as returning
> DateTimeImmutable, but it seems to actually be more
> specifically
> returning static:
>
> https://3v4l.org/j9ZSo
>
> Now I'm wondering whether this is a documentation issue (where it
> should return static|false and has not been updated to account
> for
> that return type's availability yet) or whether this is a language
> issue and the method is supposed to be returning DateTimeImmutable¬ÞÕ¾•wXæR´
> öºýÒ
> instead, though that's probably a considerable BC break.
It is not recommendable to extend DateTime(Immutable); these classes
have not been designed for that; for instance (and that may actually be
the only issue), __construct() is not called (<https://3v4l.org/4Y7jU>).
Of course, we cannot easily make them final, but I don't think we
should encourage users to subclass by documenting return types as static
– besides that the current return type is not wrong (it's just not as
specific as it could be).
> If you agree that it's a doc bug, I'll submit a PR.
As of PHP 8.0.0, the single-source-of-truth regarding the signatures are
the stub files[1]. The signatures in the PHP manual can be
automatically generated from these. Therefore the stubs would need to
be changed (first).
[1] <https://github.com/php/php-src/blob/master/ext/date/php_date.stub.php>
--
Christoph M. Becker