Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:119225
Message-ID: <42306d40-5e47-b571-5898-6d7739302ab3@gmx.de>
Date: Tue, 3 Jan 2023 16:43:49 +0100
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101
 Thunderbird/102.6.1
To: Philip Hofstetter <phofstetter@sensational.ch>,
 PHP internals <internals@lists.php.net>
References: <CAGKNXQGOjS_--5-XcXyShufisWVnvxaxy-P+_hjsU8iVHWKKwQ@mail.gmail.com>
In-Reply-To: <CAGKNXQGOjS_--5-XcXyShufisWVnvxaxy-P+_hjsU8iVHWKKwQ@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
UI-OutboundReport: notjunk:1;M01:P0:PYt35bpa+Vc=;11rG9YdjJrfloPwtKCmCc3xQSJK
 yavyNwhdC9E9DQ6PQZb9Tiu7L7berRJM4dTCB2VW6lvT19i79fpgd1YXBqpFQKMM2QiiRfnN0
 0HX867/NCwHeWqbRJkkzaTQV0hbipea8grgpNlVtgJn6VEspg9gDE4q7w2/h8u38fE5VJijaV
 CPkg1Pnu2JVoY5afL0LfnaJjbQqIyupAJEp1EneA/oIFocfHO+as/VXMWx11EIxeu/lV/JkPL
 kbWi5hgkTz8ONbB5Cr3TEkFljRjftMrLtO4bqV6rt6GR+vQjhKo6RUA4MCDobH+CXhuC3KwdC
 NG9Jxt6NHeh3j+G1flV/BHGSOVU6xFs7lKVN9wwpzuh750w+awkiao/4iNno7d2SN0tYKMl0+
 Z7xdwB9FWq859sdUT7W1RCYyNHtXCHbfY+kIKISTrKd2dkfuZDqwkfgSGcH05YFc/NUjuItbq
 ocMs5UNQ6u+qP4Adgx8vO7ty0cn0KCxXFInMcpXKergxve9HmjqTB5IyGf2H02/FC1/AkQ7Jx
 mbGW+k+OeV88O/MY3EGkh0rRz6BAfKp0sGbYWVz23dniOd0NID2FN7r8HnRBQCvg6t2hAedbQ
 av8Rf3fEeR7QT35tv6R7JNtULOnBHzdejx157BKSd17nkyFtzNnlqSEOMXOYS7hxEg4nESuH2
 DXpG6Gsh9+lLO5HGVTDeG23IYIWvoIZJ/AUTSJTxjZb5E4NyjgxRwSe3VeqFbmfGNFJtjU3CF
 zzwqf8CyWrzIzGCIaRmypVLkwKJnz/zRrA8iBLw9HgsaJ4ZBR63Q/pnKDv2JD+9wQODlJj8/7
 TfqStT88kCJlgF+jSFD5ovFApZRn4HLMZGSWJkCFULwDYE/BbAEqncmdTb4ArvJwiRIlL2waX
 qcvpW8R8IbXHDHjWxtwYQvDoV9eYVz1jz4KYBCIBD1iE4nfQHBI4tUbQKH8/+FU9c5vpVN2Ab
 ZyKzEA==
Subject: Re: DateTimeImmutable::modify() return type: doc or language bug?
From: cmbecker69@gmx.de ("Christoph M. Becker")

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`
> 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
=E2=80=93 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=
>

=2D-
Christoph M. Becker