Hi,
DateTimeImmutable::modify() is documented as returning
DateTimeImmutable, but it seems to actually be more specifically
returning static:
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
instead, though that's probably a considerable BC break.
If you agree that it's a doc bug, I'll submit a PR.
Regards,
Philip
Hi,
DateTimeImmutable::modify()is documented as returning
DateTimeImmutable, but it seems to actually be more specifically
returningstatic:Now I'm wondering whether this is a documentation issue (where it
should returnstatic|falseand 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 returningDateTimeImmutable
instead, though that's probably a considerable BC break.If you agree that it's a doc bug, I'll submit a PR.
Regards,
Philip
That sounds like a doc bug to me. It's likely the doc page hasn't been updated since before the static return was added. The code looks like it's doing the right thing.
Doc PR, please and thank you!
--Larry Garfield
DateTimeImmutable::modify()is documented as returning
DateTimeImmutable, but it seems to actually be more specifically
returningstatic:Now I'm wondering whether this is a documentation issue (where it
should returnstatic|falseand 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 returningDateTimeImmutable
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
DateTimeImmutable::modify()is documented as returning
DateTimeImmutable, but it seems to actually be more specifically
returningstatic:Now I'm wondering whether this is a documentation issue (where it
should returnstatic|falseand 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 returningDateTimeImmutable
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).
But interestingly __clone() is called: https://3v4l.org/A7Gd2
I agree that extending should not be the way to go. However, there are some
well known libraries that do it, like Carbon.
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--
To unsubscribe, visit: https://www.php.net/unsub.php