# [RFC] [Discussion] Deprecate functions with overloaded signatures

- Thread: https://externals.io/message/120146
- Original archive: https://news-web.php.net/php.internals/120146
- Started by kocsismate90@gmail.com on 2023-04-27T21:28:36+00:00
- Messages: 81
- RFC: Remove functions with overloaded signatures (Accepted) — https://externals.io/rfc/deprecate_functions_with_overloaded_signatures.md
- Page 1 of 4: messages 1 to 25 (25 per page, add `?page=N` to the URL)
- Next page: https://externals.io/message/120146.md?page=2
- Reply by email to internals@lists.php.net
- More for agents: search with https://externals.io/search.md?q={query} · RFCs at https://externals.io/rfc.md · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

---

## #120146 — kocsismate90@gmail.com — 2023-04-27T21:28:36+00:00

URL: https://externals.io/message/120146#120146

Hi Internals,

As you have possibly already experienced, overloaded signatures cause
various smaller and bigger issues, while the concept is not natively
supported by PHP. That's why I drafted an RFC which intends to phase out
the majority of overloaded function/method signatures and also forbid
the introduction of such functions in the future:
https://wiki.php.net/rfc/deprecate_functions_with_overloaded_signatures

I'm not sure at all what the best solution would be to get rid of the
overloaded FFI methods, so I hope that someone comes up with a better idea.
Currently, the RFC suggests deprecating and then removing the static
methods in question, but I hope that we can find a more elegant approach.
So this section is incomplete and it's just for starting the discussion.

Regards,
Máté

---

## #120147 — Kamil Tekiela — 2023-04-27T22:48:57+00:00

URL: https://externals.io/message/120146#120147 · In reply to: #120146

Hi Máté,

I agree with this proposal, and I will be voting yes. The function
overloads are not a big issue for PHP developers, and some are very
much in use, but the reasons you listed are convincing and the manner
in which you propose to do it should create an easy upgrade path.

I think one year of deprecation is not enough. I believe the functions
that get replacements should be deprecated immediately in PHP 8.3 to
give people two years of deprecation notice. It doesn't make sense to
me to add a replacement but not deprecate the old variant.

`($rm = new ReflectionMethod(explode(“::”, $string));) ` I think you
forgot a splat operator here.

ReflectionProperty::setValue could have an alternative called
ReflectionProperty::setStaticValue. Then there would be no need for
the unused parameter anymore.

The overload of array_keys should be replaced with a new function
array_search_all. This overload is little known and very confusing.

The overload of ldap_exop should just be deprecated. An alternative
already exists and is the preferred way.

I wasn't aware that pg_execute has an overload apart from the default
connection one. Could you explain what that overload is?

stream_context_set_option should get alternative
stream_context_set_option_array.

What is the last item in Future scope supposed to be, because I think
ReflectionProperty is a typo.

Why is `implode()` not mentioned in this RFC?

Regards,
Kamil

---

## #120150 — Rowan Tommins — 2023-04-28T08:16:56+00:00

URL: https://externals.io/message/120146#120150 · In reply to: #120146

> As you have possibly already experienced, overloaded signatures cause
> various smaller and bigger issues, while the concept is not natively
> supported by PHP. That's why I drafted an RFC which intends to phase out
> the majority of overloaded function/method signatures and also forbid
> the introduction of such functions in the future:
> https://wiki.php.net/rfc/deprecate_functions_with_overloaded_signatures


Hi Máté,

While I broadly agree with the sentiment behind this, I think the 
upgrade path needs to be examined a bit more closely.

As Kamil says, a potential 1-year deprecation is probably not enough, 
and we need to keep in mind that many libraries and applications need to 
support multiple versions of PHP at once. If they are to become errors 
in 9.0, there should be some way to write code that will run on both 8.0 
and 9.0.

The only ones in this list I can see that being easy for are 
assert_options (you can write a polyfill for the new assert_set_option, 
and switch all code to use that), and `get_class()` / `get_parent_class()` 
(you can start passing $this right away).

A lot of the others introduce new methods, which can't easily 
polyfilled, or directly change the signature. For all of those, users 
would have to write an additional wrapper, with explicit detection of 
the PHP version to make the call in one form or the other.


I have particular concerns about session_set_save_handler. The impact is 
hard to estimate, because it will be used directly in applications more 
often than in libraries. The multiple parameter signature is much older, 
dating back to PHP 4, with the object form added only in PHP 5.4. That 
may seem a long time ago, but there is currently no incentive to change 
existing code between the styles, and doing so requires a reasonable 
amount of work.


On a different point, I think "assert_options" is a peculiar name for 
either setting or getting a single option, and would suggest it be 
replaced with two new functions, assert_get_option and 
assert_set_option. Replacing both variants also makes it easier for 
users to find everywhere they've used it, and polyfill both variants, 
rather than having to examine each.


Regards,

-- 
Rowan Tommins
[IMSoP]

---

## #120174 — kocsismate90@gmail.com — 2023-05-02T08:18:31+00:00

URL: https://externals.io/message/120146#120174 · In reply to: #120147

Hi Kamil,

Thank you for your reply, it is pretty much appreciated!

I think one year of deprecation is not enough. I believe the functions
> that get replacements should be deprecated immediately in PHP 8.3 to
> give people two years of deprecation notice. It doesn't make sense to
> me to add a replacement but not deprecate the old variant.
>

Yes, this upgrade path also makes sense to me, and I'm happy to go with
it if others don't disagree! Probably my approach would be advantageous
if we were earlier in the 8.x lifecycle.


> `($rm = new ReflectionMethod(explode(“::”, $string));) ` I think you
> forgot a splat operator here.
>

Fixed!


> ReflectionProperty::setValue could have an alternative called
> ReflectionProperty::setStaticValue. Then there would be no need for
> the unused parameter anymore.
>

Originally, my proposal had this method, but at last I removed it based on
Nicolas' suggestions. I think both ways make sense, a single setValue() is
probably much easier from the migration point of view, since the suggested
alternative is already there in older PHP versions. And it doesn't mean
we cannot have a ReflectionProperty::setStaticValue() later on. :)


> The overload of array_keys should be replaced with a new function
> array_search_all. This overload is little known and very confusing.
>

Thanks for pointing this out, I'll look into this soon!


>
> The overload of ldap_exop should just be deprecated. An alternative
> already exists and is the preferred way.
>

I've just included ldap_exop() in the RFC, albeit slightly differently to
your
suggestion: since this function performs the extended operation
synchronously
or asynchronously based on whether the $response_data parameter is provided,
we cannot simply deprecate and remove the latter one, because as far as I
can understand, synchronous communication is also a valid use-case. So I
went
with adding an ldap_exop_sync() function.


> I wasn't aware that pg_execute has an overload apart from the default
> connection one. Could you explain what that overload is?
>

You are right, as it turned out for me, there is no other overload indeed,
so I removed
it from the RFC.


> stream_context_set_option should get alternative
> stream_context_set_option_array.
>

Thanks for the suggestion! I incorporated this suggestion into the RFC
(using
the stream_context_set_options name though).

What is the last item in Future scope supposed to be, because I think
> ReflectionProperty is a typo.
>

Right, it's now removed.


> Why is `implode()` not mentioned in this RFC?
>

Because it's not overloaded anymore. :) Even though the manual lists
multiple signatures
for it, its exact signature is the following:

function implode(string|array $separator, ?array $array = null): string {}

I'm not sure how much people would miss the possibility to use implode with
a
single argument ("implode($array)"), but if that's the case, we can add it
to the
usual PHP 8.3 or PHP 8.4 Deprecations RFC. I wouldn't like to add it to
mine,
because it's already way too long.

Regards:
Máté

---

## #120175 — Rowan Tommins — 2023-05-02T11:32:23+00:00

URL: https://externals.io/message/120146#120175 · In reply to: #120150

> On a different point, I think "assert_options" is a peculiar name for
> either setting or getting a single option, and would suggest it be
> replaced with two new functions, assert_get_option and
> assert_set_option.
>


Further to this, I've realised that the manual is currently a bit confusing
regarding the interaction of ini_set('zend.assertions', ...),
ini_set('assert.active', ...), and assert_options(ASSERT_ACTIVE, ...)

Either way, all the options to assert_options are documented as having an
equivalent ini setting, so is this function actually needed at all, or
should users be encouraged to use ini_get / ini_set directly?

https://www.php.net/assert_options

Regards,
-- 
Rowan Tommins
[IMSoP]

---

## #120176 — Dan Ackroyd — 2023-05-02T11:37:42+00:00

URL: https://externals.io/message/120146#120176 · In reply to: #120174

Kamil Tekiela wrote:
> > […]

Máté Kocsis <kocsismate90@gmail.com> wrote:
> Yes, this upgrade path also makes sense to me, and I'm happy to go with
> it if others don't disagree!


For the functions that are having new separate methods added, not
deprecating them immediately makes upgrading easier. When upgrading
from one version of PHP to the next, it is best if you can run the
same code on both versions, without any deprecation notices going off.

Would leaving the current versions in place and working actually cause
any maintenance issues?

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.

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.

cheers
Dan
Ack

---

## #120177 — Dan Ackroyd — 2023-05-02T11:56:31+00:00

URL: https://externals.io/message/120146#120177 · In reply to: #120146

From the RFC:
>
> Code which invokes `get_class()` without parameters should be modified to
> use __CLASS__ or get_class($this) instead,

I don't think the first option is equivalent:

class C {
    function printType() {
        echo "__CLASS__ is " . __CLASS__ . "\n";
        echo "get_class is " . get_class($this) . "\n";
    }
}

class D extends C {
    function printTypeInChild() {
        echo "__CLASS__ is " . __CLASS__ . "\n";
        echo "get_class is " . get_class($this) . "\n";
    }
}

(new D)->printType();
(new D)->printTypeInChild();

// Output is:
__CLASS__ is C
get_class is D
__CLASS__ is D
get_class is D

And unless I'm missing something, the second option doesn't appear
usable with static methods, which is also a problem with
 `get_parent_class()`

> while code which invokes
> `get_parent_class()` without parameters should be modified to use
> get_parent_class($this) instead.

What would the equivalent code `get_parent_class()` for static methods? e.g.

class A {}

class B extends A {
    public static function foo() {
        echo `get_parent_class()` . " \n";
    }
}
b::foo();

cheers
Dan
Ack

---

## #120178 — Aleksander Machniak — 2023-05-02T12:00:59+00:00

URL: https://externals.io/message/120146#120178 · In reply to: #120146

> https://wiki.php.net/rfc/deprecate_functions_with_overloaded_signatures

 `stream_context_set_option()` should be removed from the Future Scope as 
it already is being changed by the RFC.

-- 
Aleksander Machniak
Kolab Groupware Developer        [https://kolab.org]
Roundcube Webmail Developer  [https://roundcube.net]
----------------------------------------------------
PGP: 19359DC1 # Blog: https://kolabian.wordpress.com

---

## #120179 — tim@bastelstu.be — 2023-05-02T12:04:45+00:00

URL: https://externals.io/message/120146#120179 · In reply to: #120177

Hi


> And unless I'm missing something, the second option doesn't appear
> usable with static methods, which is also a problem with
> `get_parent_class()`

static::class or self::class appear to do the right thing depending on 
what exactly you want to retrieve.

> > […]
> 
> What would the equivalent code `get_parent_class()` for static methods? e.g.
> 

parent::class appears to do the right thing.

Best regards
Tim Düsterhus

---

## #120180 — kocsismate90@gmail.com — 2023-05-02T12:20:21+00:00

URL: https://externals.io/message/120146#120180 · In reply to: #120150

Hi Rowan,

As Kamil says, a potential 1-year deprecation is probably not enough,
> and we need to keep in mind that many libraries and applications need to
> support multiple versions of PHP at once. If they are to become errors
> in 9.0, there should be some way to write code that will run on both 8.0
> and 9.0.
>

Yes, I agree that we should make the upgrade path of libraries as easy as
possible,
and I also agree that probably a 1-year deprecation is not enough.. although
the suggested alternatives would be available 2 years in advance of the
removal
so this would allow a 2 year window for fixing code using the deprecated
functionality.


> The only ones in this list I can see that being easy for are
> assert_options (you can write a polyfill for the new assert_set_option,
> and switch all code to use that), and `get_class()` / `get_parent_class()`
> (you can start passing $this right away).
>

As far as I see there are more deprecations which are easy to fix. In order
to see the whole picture
better, let's group the functions based on how a possible upgrade path
would look like:

- With existing suggested alternative:
    - `get_class()` and `get_parent_class()`
    - pg_fetch_result(), pg_field_prtlen(), and pg_field_is_null()
    - Phar::setStub()
    - ReflectionMethod::__construct()
    - ReflectionProperty::setValue()
    - `session_set_save_handler()` (because the OO and procedural style are
interchangeable)
    - `stream_context_set_option()`
- Polyfillable:
    - `assert_options()`
    - ldap_connect()
    - ldap_exop()
- Requires conditional version check:
    - DatePeriod::__construct()
    - IntlCalendar::set()
    - IntlGregorianCalendar::__construct()

(I intentionally did not include the FFI related methods, since this
section is TBD)

As it can be seen, most deprecations have an existing alternative. The 2nd
category (polyfillable ones)
mostly contains very little used functions, especially because the
deprecation of ldap_connect() only
affects PHP compiled with OracleLDAP.

The category which requires conditional PHP version checks is indeed the
most problematic one.
Probably it's not a surprise that it only includes methods because it's not
possible to polyfill methods
according to my knowledge. The good news is that IntlCalendar::set() and
IntlGregorianCalendar::__construct()
seem to be very little used functionality. So in my opinion,
DatePeriod::__construct() has the worst upgrade path,
the rest are either easy or shouldn't cause much issues. Since the
constructor is set to be removed completely
based on Derick's preference, we should discuss with him whether it's worth
to leave the
public function __construct(DateTimeInterface $start, DateInterval
$interval, DateTimeInterface $end, int $options = 0) {}
signature alive so that people can change their code to use this instead of
the other two signatures.

I have particular concerns about session_set_save_handler. The impact is
> hard to estimate, because it will be used directly in applications more
> often than in libraries. The multiple parameter signature is much older,
> dating back to PHP 4, with the object form added only in PHP 5.4. That
> may seem a long time ago, but there is currently no incentive to change
> existing code between the styles, and doing so requires a reasonable
> amount of work.
>

Yes, but changing `session_set_save_handler()` to session_set_save_handlers()
should be a reasonably small effort, isn't it? I understand that it's going
to affect
lots of codebases, however other PHP 8.x deprecations are much more
difficult
to fix than this one would be.


> On a different point, I think "assert_options" is a peculiar name for
> either setting or getting a single option, and would suggest it be
> replaced with two new functions, assert_get_option and
> assert_set_option. Replacing both variants also makes it easier for
> users to find everywhere they've used it, and polyfill both variants,
> rather than having to examine each.
>

Yes, I agree that the `assert_options()` name is at least weird but I
wouldn't like to
include changes into this RFC which are not strictly related to overloaded
signatures. Just like in case of `implode()`, the 1-parameter version of
 `assert_options()`
could be added to the PHP 8.3/8.4 deprecations RFC though.

Regards,
Máté

---

## #120181 — Rowan Tommins — 2023-05-02T13:07:21+00:00

URL: https://externals.io/message/120146#120181 · In reply to: #120180

> Yes, but changing `session_set_save_handler()` to session_set_save_handlers()
> should be a reasonably small effort, isn't it? I understand that it's
> going to affect
> lots of codebases, however other PHP 8.x deprecations are much more
> difficult
> to fix than this one would be.
>


Oh, did that proposal change, or did I just misread it?

Maybe because the function names are so similar? In general, I hate
variable and function names that differ only by an "s", it's far too easy
to misread or mistype them. Maybe "session_set_save_handler_functions"?

For the same reason, I much prefer Kamil's suggestion of "
stream_context_set_option_array" over " stream_context_set_options".


As an aside, I don't think "other deprecations are already more difficult"
is a good argument - it's like saying "yes, I punched him, but not as hard
as someone else already had". I think the change can be defended from other
angles, but wanted to call that out.




> Yes, I agree that the `assert_options()` name is at least weird but I
> wouldn't like to
> include changes into this RFC which are not strictly related to overloaded
> signatures. Just like in case of `implode()`, the 1-parameter version of
> `assert_options()`
> could be added to the PHP 8.3/8.4 deprecations RFC though.
>


It *is* strictly related, though: the current function has two purposes:
get an option, and set an option; the RFC proposes to split that into two
functions, and there are three ways we can do that:

1) Keep the current name for get, come up with a new name for set
2) Come up with a new name for get, keep the current name for set
3) Come up with new names for both get and set

I then looked further, and suggested:

4) Deprecate the existing function, but do not create any new functions;
instead, recommend ini_get for get, and ini_set for set

All four options are direct remedies to the overloaded signature, and I
think due to the current unclear naming, options 3 and 4 are superior to
options 1 and 2. Do you have a specific reason to prefer option 1?


Regards,
-- 
Rowan Tommins
[IMSoP]

---

## #120182 — Larry Garfield — 2023-05-02T16:13:10+00:00

URL: https://externals.io/message/120146#120182 · In reply to: #120180

> As far as I see there are more deprecations which are easy to fix. In order
> to see the whole picture
> better, let's group the functions based on how a possible upgrade path
> would look like:
>
> - With existing suggested alternative:
>     - `get_class()` and `get_parent_class()`
>     - pg_fetch_result(), pg_field_prtlen(), and pg_field_is_null()
>     - Phar::setStub()
>     - ReflectionMethod::__construct()
>     - ReflectionProperty::setValue()
>     - `session_set_save_handler()` (because the OO and procedural style are
> interchangeable)
>     - `stream_context_set_option()`
> - Polyfillable:
>     - `assert_options()`
>     - ldap_connect()
>     - ldap_exop()
> - Requires conditional version check:
>     - DatePeriod::__construct()
>     - IntlCalendar::set()
>     - IntlGregorianCalendar::__construct()
>
> (I intentionally did not include the FFI related methods, since this
> section is TBD)
>
> As it can be seen, most deprecations have an existing alternative. The 2nd
> category (polyfillable ones)
> mostly contains very little used functions, especially because the
> deprecation of ldap_connect() only
> affects PHP compiled with OracleLDAP.

Thanks for the breakdown.  I am also generally in favor of the changes here, but am concerned about the migration path.  The key factor, IMO, is that it should be possible to run code without version checks across as wide a range of versions as feasible.  Needing version checks to run from 8.2 to 9.0 is going to be problematic.  Were we earlier in the 8.x cycle it would be less of an issue, but assuming we stick to the usual schedule it feels too tight on those.

As Rowan asked, how much would it hurt to leave the date-related methods available but deprecated until 10.x?

I'm also not entirely clear how you'd polyfill functions that exist, but change behavior.

--Larry Garfield

---

## #120183 — tim@bastelstu.be — 2023-05-02T17:05:43+00:00

URL: https://externals.io/message/120146#120183 · In reply to: #120176

Hi


> For the functions that are having new separate methods added, not
> deprecating them immediately makes upgrading easier. When upgrading
> from one version of PHP to the next, it is best if you can run the
> same code on both versions, without any deprecation notices going off.

Agree here, I consider it a good thing if there's at least one version 
where both alternatives exist and are fully supported (i.e. without 
emitting a deprecation notice).

As an example, with PHP 8.3's addition of Randomizer::getFloat() and 
Randomizer::getBytesFromString() there are useful replacements for 
 `lcg_value()` and `uniqid()` [1] respectively, but I'm intentionally not 
proposing deprecating either of them before whatever comes after PHP 8.3.

[1] The latter of which is likely one of the most misused functions in PHP.

> Would leaving the current versions in place and working actually cause
> any maintenance issues?
> 
> 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.

Does it necessarily follow that a function that is deprecated in major X 
must be removed in major X+1? Otherwise deprecating with 8.3 and 
removing in 10 would be an option that could be evaluated when it's time 
for 9 and the migration did not yet "sufficiently" happen in userland code.

I can also see how that would be useful for the planned deprecation of 
 `rand()` and `mt_rand()`. Both of them have overloaded signatures, but will 
be part of the other deprecation RFC, as they also have a myriad of 
other issues that I consider to be worse than the signature. 
Unfortunately they are pretty ubiquitous, but luckily do not cause 
"internal" maintenance problems. So it would likely be feasible to keep 
them until 10, as long as they emit the deprecation notice to slowly nag 
developers away from them towards better alternatives.

Best regards
Tim Düsterhus

---

## #120184 — Larry Garfield — 2023-05-02T19:06:44+00:00

URL: https://externals.io/message/120146#120184 · In reply to: #120183

> Hi
>
> 
> > […]
>
> Agree here, I consider it a good thing if there's at least one version 
> where both alternatives exist and are fully supported (i.e. without 
> emitting a deprecation notice).
>
> As an example, with PHP 8.3's addition of Randomizer::getFloat() and 
> Randomizer::getBytesFromString() there are useful replacements for 
> `lcg_value()` and `uniqid()` [1] respectively, but I'm intentionally not 
> proposing deprecating either of them before whatever comes after PHP 8.3.
>
> [1] The latter of which is likely one of the most misused functions in PHP.
>
> > […]
>
> Does it necessarily follow that a function that is deprecated in major X 
> must be removed in major X+1? Otherwise deprecating with 8.3 and 
> removing in 10 would be an option that could be evaluated when it's time 
> for 9 and the migration did not yet "sufficiently" happen in userland code.
>
> I can also see how that would be useful for the planned deprecation of 
> `rand()` and `mt_rand()`. Both of them have overloaded signatures, but will 
> be part of the other deprecation RFC, as they also have a myriad of 
> other issues that I consider to be worse than the signature. 
> Unfortunately they are pretty ubiquitous, but luckily do not cause 
> "internal" maintenance problems. So it would likely be feasible to keep 
> them until 10, as long as they emit the deprecation notice to slowly nag 
> developers away from them towards better alternatives.
>
> Best regards
> Tim Düsterhus

Given past pushback on changes that we've gotten, a low-cost/no-cost long deprecation period seems like it would be very appreciated.

I've actually been considering proposing an RFC to mandate a minimum time length between deprecation and actual removal/change for that reason.

--Larry Garfield

---

## #120197 — Derick Rethans — 2023-05-05T16:12:48+00:00

URL: https://externals.io/message/120146#120197 · In reply to: #120146

> As you have possibly already experienced, overloaded signatures cause 
> various smaller and bigger issues, while the concept is not natively 
> supported by PHP. That's why I drafted an RFC which intends to phase 
> out the majority of overloaded function/method signatures and also 
> forbid the introduction of such functions in the future: 
> https://wiki.php.net/rfc/deprecate_functions_with_overloaded_signatures

I'm going to nitpick on the newly suggested names and argument order for the
DatePeriod factory methods — althoughI do agree that they need to get created:

createFromInterval(DateTimeInterface $start, DateInterval $interval, DateTimeInterface $end, int $options = 0)
→ createWithRange(DateTimeInterface $begin, DateTimeInterface $end, DateTimeInterface $int, int $options = 0)

createFromRecurrences(DateTimeInterface $start, DateInterval $interval, int $recurrences, int $options = 0)
→ createWithRecurrences(DateInterval $begin, int $recurrences, DateInterval $interval, int $options = 0)

We also should fix the argument names. Either $start/$finish, or $begin/$end. I
prefer the latter.

createFromIso8601(string $specification, int $options = 0)
-> createFromISO8601String

I am open to bike shedding about this :-)

cheers,
Derick

---

## #120199 — tim@bastelstu.be — 2023-05-05T19:59:40+00:00

URL: https://externals.io/message/120146#120199 · In reply to: #120197

Hi


> createFromIso8601(string $specification, int $options = 0)
> -> createFromISO8601String
> 
> I am open to bike shedding about this :-)

Okay, I'd like a different color of my bikeshed:

Please no consecutive uppercase letters in the function name. I find 
createFromIso8601 (or createFromIso8601String if find the 'String' 
suffix useful) much more readable than createFromISO8601String. 
Uppercase acronyms are especially bad if followed by another ucfirst 
word, because the word boundary is not immediately visible there. Not 
the case here (it's digits), but still bad.

Best regards
Tim Düsterhus

---

## #120228 — kocsismate90@gmail.com — 2023-05-10T21:28:16+00:00

URL: https://externals.io/message/120146#120228 · In reply to: #120181

Hi Rowan,


> As an aside, I don't think "other deprecations are already more difficult"
> is a good argument - it's like saying "yes, I punched him, but not as hard
> as someone else already had". I think the change can be defended from other
> angles, but wanted to call that out.
>

I admit that my argument was not a good one, but I intended to mean that
most of
the suggested alternatives are not too difficult to implement: since
numerous other proposals
were accepted in the past with a much more difficult upgrade path, I think
this aspect
of my RFC shouldn't be a deal breaker considering the benefits.

Maybe because the function names are so similar? In general, I hate
> variable and function names that differ only by an "s", it's far too easy
> to misread or mistype them. Maybe "session_set_save_handler_functions"?


To be honest, I'm not a fan of using the longer names
(session_set_save_handler_functions
and stream_context_set_option_array), especially the latter one looks weird
to me, and it
doesn't go well with `stream_context_get_options()`.

Besides, a most interesting development is that I've just discovered the
 `stream_context_get_params()`
and `stream_context_set_params()` functions which do nearly the same what the
stream_context_*et_option
functions do: the only difference between them is that the latter functions
wrap the options inside the
"options" key and also has an additional "notification" key.

It *is* strictly related, though: the current function has two purposes:
> get an option, and set an option; the RFC proposes to split that into two
> functions, and there are three ways we can do that:


Thanks for the idea, your explanation made sense to me, so finally, I
removed `assert_options()` from
my proposal and the deprecation of `assert_options()` relies on the PHP 8.3
deprecations RFC.

Regards:
Máté

---

## #120229 — kocsismate90@gmail.com — 2023-05-10T22:10:33+00:00

URL: https://externals.io/message/120146#120229 · In reply to: #120182

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 = null, mixed $value = UNKNOWN):
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=1&q=is%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áté

---

## #120230 — kocsismate90@gmail.com — 2023-05-10T22:28:33+00:00

URL: https://externals.io/message/120146#120230 · In reply to: #120197

Hi Derick and Tim,

Derick, I incorporated most of your suggestions into the RFC with the sole
exception of the argument
names ($start/$finish,$begi/$end): it would feel odd if these parameters
and their related properties
were called differently:
https://www.php.net/manual/en/class.dateperiod.php#dateperiod.props.start

Actually, when we renamed the majority of parameters together with Nikita,
this was one of few rules that we had:
parameters should be called the same way as the property they initialize.


> Please no consecutive uppercase letters in the function name. I find
> createFromIso8601 (or createFromIso8601String if find the 'String'
> suffix useful) much more readable than createFromISO8601String.
> Uppercase acronyms are especially bad if followed by another ucfirst
> word, because the word boundary is not immediately visible there. Not
> the case here (it's digits), but still bad.


Yes, generally, I wholeheartedly agree, but unfortunately I still "had to"
go
with Derick's suggestion of using consecutive uppercase letters because
there
is already a DateTime::setISODate() method with the same casing and I want
to
follow the established naming convention of ext/date. Personally, I like
the "String"
suffix, probably it makes the name better, but since I don't really care
about this
problem too much, I'd leave it for Derick to decide about it.

Máté

---

## #120231 — tim@bastelstu.be — 2023-05-11T09:36:37+00:00

URL: https://externals.io/message/120146#120231 · In reply to: #120229

Hi


> If not, then we could just move really slowly on deprecating them. We
> > […]
> 
> 
> 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).
> 

I believe this vote format ("three options") is not really compatible 
with the voting rules (https://wiki.php.net/rfc/voting).

For example it's not entirely clear what would happen here:

5 votes to deprecate in 8.3 / remove 9.0
4 votes to deprecate in 9.0 / remove 10.0
4 votes to not deprecate.

Neither option has a 2/3 majority over any other option. The two 
deprecation options together have a 2/3 majority over not deprecating, 
which might indicate that a deprecation should happen. But in which 
version? This would likely require ranked choice voting which feels 
complex for something that should be a simple vote.

I've had a similar issue with my "Improve `unserialize()` error handling 
RFC" (https://externals.io/message/118566) and opted to make an 
executive decision as the RFC author and not offer one of the possible 
version targets to avoid that problem entirely.

----------------------

Repeating my previous question:

> Does it necessarily follow that a function that is deprecated in major X 
> must be removed in major X+1? Otherwise deprecating with 8.3 and 
> removing in 10 would be an option that could be evaluated when it's time 
> for 9 and the migration did not yet "sufficiently" happen in userland code.

Would it be an option to just deprecate everything in PHP 8.3 and defer 
the vote for the removal target version to a later date? This would give 
users the deprecation notice as early as possible and also gives them 
appropriate time to migrate if migration for a specific set of functions 
is (much) slower than others. It doesn't really feel right to decide on 
a deprecation for 9.0 / removal for 10.0 at the current time, but 
deprecation in 8.3 + removal when it's ready seems to be okay.

Best regards
Tim Düsterhus

---

## #120234 — Dan Ackroyd — 2023-05-11T16:58:26+00:00

URL: https://externals.io/message/120146#120234 · In reply to: #120231

>
> Would it be an option to just deprecate everything in PHP 8.3

As I said before, having at least one version where the new versions
of the functions are available, and the old versions aren't giving
deprecation notices, is the 'cleanest' way of refactoring functions.

Deprecation notices only deliver their value when the old versions of
the functions are removed, and before then are a cost.

> It doesn't really feel right to decide on
> a deprecation for 9.0 / removal for 10.0 at the current time, but
> deprecation in 8.3 + removal when it's ready seems to be okay.

I think I don't understand your concern.

If a problem is discovered with a planned removal of something, people
on this project are mostly reasonable*, and a small RFC to adjust to
the new circumstances would be very likely to pass.

cheers
Dan
Ack

* though sometimes they base their decisions on experiences/value
different from my own, which makes it not feel like that.

---

## #120235 — tim@bastelstu.be — 2023-05-11T17:06:44+00:00

URL: https://externals.io/message/120146#120235 · In reply to: #120234

Hi


> 
> > […]
> 
> As I said before, having at least one version where the new versions
> of the functions are available, and the old versions aren't giving
> deprecation notices, is the 'cleanest' way of refactoring functions.

Right. Replace "8.3" by "the first version after the replacement is 
available" in my previous email. My main question was …

> Deprecation notices only deliver their value when the old versions of
> the functions are removed, and before then are a cost.
> 
> > […]
> 
> I think I don't understand your concern.
> 
> If a problem is discovered with a planned removal of something, people
> on this project are mostly reasonable*, and a small RFC to adjust to
> the new circumstances would be very likely to pass.

… the following: I wanted to know if

"Deprecate in 8.x + not remove in 9.0, but only remove in 10.x or 11.x"

would be an option, because I feel that it is more useful than

"If we deprecate in 8.x then we MUST remove in 9.0, that's why we're 
already making deprecation plans for 9.x, so we are able to remove in 10.0"

All the discussion so far had "Deprecate in x.y and remove in x+1.0", 
but not "Deprecate in x.y and remove in x+n.0 with n > 1".

Best regards
Tim Düsterhus

---

## #120236 — Dan Ackroyd — 2023-05-11T17:06:44+00:00

URL: https://externals.io/message/120146#120236 · In reply to: #120231

>
> I believe this vote format ("three options") is not really compatible
> with the voting rules (https://wiki.php.net/rfc/voting).
>
> For example it's not entirely clear what would happen here:
>
> 5 votes to deprecate in 8.3 / remove 9.0
> 4 votes to deprecate in 9.0 / remove 10.0
> 4 votes to not deprecate.

The RFC author could just say that yes votes for deprecation and
eventual removal will be added together, with the timescale being a
preference vote.

I think the only people who would object to that are people who would
vote yes to "deprecate and remove" but only if it matches their
preferred timescale, and would otherwise vote no. Which probably isn't
a thing.

cheers
Dan
Ack

---

## #120237 — kocsismate90@gmail.com — 2023-05-11T22:16:38+00:00

URL: https://externals.io/message/120146#120237 · In reply to: #120236

Hi Dan and Tim,


> The RFC author could just say that yes votes for deprecation and
> eventual removal will be added together, with the timescale being a
> preference vote.
>

Thank you, Dan, for the  clarification, that was indeed what I meant. I'll
also
make this clear in the RFC, unfortunately I forgot it so far.

… the following: I wanted to know if


> "Deprecate in 8.x + not remove in 9.0, but only remove in 10.x or 11.x"


Yes, this is also a possible choice. Actually, I'm sure there were multiple
things deprecated in 5.x,
which only got removed in PHP 8.0. At least this is what I remember. :)

The reason why I still opted for the possibility of "deprecate in 9.0 and
remove in 10.0",
because in my opinion this choice would suit better some of the most
widespread functionalities.
Not deprecating them formally straightaway in 8.x versions, but only
providing a suggested
alternative instead of them, would first of all buy some time for people
who don't yet want to deal with this problem at all, but still allow them
to voluntarily migrate
when they are ready without nagging them. Then they had a relatively long
time period when we would
warn them a bit louder. A full major release cycle should be more than
enough time to perform the migration.

With all that said, personally I don't think any of the affected
functionalities (maybe with the exception
of only one of them) warrant such a long phasing out period.

Regards,
Máté

---

## #120238 — Rowan Tommins — 2023-05-12T06:52:21+00:00

URL: https://externals.io/message/120146#120238 · In reply to: #120236

>
> > […]
>
>The RFC author could just say that yes votes for deprecation and
>eventual removal will be added together, with the timescale being a
>preference vote.
>
>I think the only people who would object to that are people who would
>vote yes to "deprecate and remove" but only if it matches their
>preferred timescale, and would otherwise vote no. Which probably isn't
>a thing.


I think it's actually very likely that voters would want to express "deprecate, but do not remove before 10.0". Treating those votes as "generally in favour, so enough to approve removal in 9.0" doesn't seem appropriate.

The other way around - "deprecate, but do not remove later than 9.0" - seems less likely. I also don't see any reason to delay the deprecation - the whole point of the longer period is to give people more notice.

So I would suggest rewording the options slightly:

a) Deprecate in 8.3, remove in either 9.0 or 10.0
b) Deprecate in 8.3, remove in 10.0
c) Do not deprecate

Now if the votes are a:5, b:4, c:4, we can say:

- 9 people voted for deprecation in 8.3, vs 4 against
- only 5 voted for removal in 9.0, vs 8 against
- 9 voted for removal in 10.0, vs 4 against

So we conclude that we should deprecate in 8.3, and remove in 10.0


The suggestion to narrow it down to a yes/no proposal in the discussion phase is probably even better, though.

Regards,

-- 
Rowan Tommins
[IMSoP]

---

Next page: https://externals.io/message/120146.md?page=2
