Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:120229
MIME-Version: 1.0
References: <CAH5C8xXtCVHaxwzmAW_eBxp_D6p7kww9svND=3AEeC9X6--YXg@mail.gmail.com>
 <ffa8138a-f1b6-3926-bc2f-558ffca344b0@gmail.com> <CAH5C8xXhCkZt7bBs7YcjMBRYM5ggu7W47huCCbVwb2-q_zFnBA@mail.gmail.com>
 <e3eba528-a015-48be-ba8e-fa71d512aa33@app.fastmail.com>
In-Reply-To: <e3eba528-a015-48be-ba8e-fa71d512aa33@app.fastmail.com>
Date: Thu, 11 May 2023 00:10:33 +0200
Message-ID: <CAH5C8xVJPXx8Mk5WViOiqBe-094zTbtSO6pkZGx2BeGKbaXVoA@mail.gmail.com>
To: Larry Garfield <larry@garfieldtech.com>
Cc: php internals <internals@lists.php.net>
Content-Type: multipart/alternative; boundary="000000000000b6827905fb5e24a3"
Subject: Re: [PHP-DEV] [RFC] [Discussion] Deprecate functions with overloaded signatures
From: kocsismate90@gmail.com (=?UTF-8?B?TcOhdMOpIEtvY3Npcw==?=)

--000000000000b6827905fb5e24a3
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

Hi Dan (and Larry and Tim who responded to the same topic),

Would leaving the current versions in place and working actually cause
> any maintenance issues?


Yes, unfortunately they cause some maintenance issues: since they don't
have a single
signature, gen_stub.php generates the wrong signature for them in the
manual. For example
https://www.php.net/manual/en/function.stream-context-set-option.php
displays two distinct
signatures, however gen_stub.php only knows one signature, so obviously
generation won't work well:

function stream_context_set_option($context, array|string
$wrapper_or_options, ?string $option_name =3D null, mixed $value =3D UNKNOW=
N):
bool {}

I use gen_stub.php for automatically detecting the outdated
function/method/class signatures which I can then
commit with minimal effort. Actually my doc-en PRs (
https://github.com/php/doc-en/pulls?page=3D1&q=3Dis%3Apr+is%3Aclosed+author=
%3Akocsismate
)
are either fixing outdated information in the manual, or ensuring that
gen_stub.php can generate the same
information that we display in the docs. Now, there are only ~50-60
function/method signatures
in master which are not in line  with the output of gen_stub.php, and most
of them are due to
overloaded signatures (the rest is due to PHP 8.3 changes which shouldn't
be documented yet).
For reference, the number of outdated function signatures used to be many
hundreds or probably 1000+
when the project started, just before PHP 8.0 came out.

If not, then we could just move really slowly on deprecating them. We
> could deprecate them at some point in the 9.x release cycle and remove
> them in 10.0.


Although I would love to get rid of as many overloaded signatures as
possible due to the above mentioned fact,
I admit that there might be some signatures which other internals would
prefer to phase out slower than me. So
thanks for the idea! Now, the individual votes in the RFC contain 2 options
for removing a signature: a shorter path (deprecation
in PHP 8.4, removal in PHP 9.0) and a longer one (deprecation in PHP 9.0
and removal in PHP 10.0).

Additionally, I wrote a very explicit and detailed list about the suggested
BC compatible alternatives for each deprecation so that
now it should be very clear how difficult it is to replace a
function/method invocation.

The RFC says:

 Impact analysis: 1 out of the 2000 most popular PHP packages rely on
> calling session_set_save_handler() with 6 or more arguments.


> I doubt analysing github is going to give a useful measure of the
> impact of this RFC. Functions like session_set_save_handler are going
> to be used in custom code written for a company than in shared
> libraries.


Yes, I'm aware of this glitch, but that's the best I could provide for
estimating the impact of the deprecations.

Cheers,
M=C3=A1t=C3=A9

--000000000000b6827905fb5e24a3--