[RFC] [Vote] Deprecate functions with overloaded signatures

On Mon, June 26, 2023, at 14:43 Nikita Popov wrote: > On Mon, Jun 26, 2023, at 20:22, Ben Ramsey wrote: > > > > I voted “no” on `array_keys()` because I do not see these as two different function signatures. To me, the single signature should look like this: > > > > function array_keys(array $array, ?mixed $filter_value = null, bool $strict = false): array {} > > > > I voted “no” on `IntlCalendar::set()` because it seems to me that `setDate()` and `setDateTime()` could share the same signature if `$hour`, `$minute`, and `$second` all default to zero, like this: > > > > public function setDate(int $year, int $month, int $dayOfMonth, int $hour = 0, int $minute = 0, int $second = 0): void {} > > > > In the same way, with `IntlGregorianCalendar::__construct()`, `createFromDate()` and `createFromDateTime()` could be combined as: > > > > public static function createFromDate(int $year, int $month, int $dayOfMonth, int $hour = 0, int $minute = 0, int $second = 0): void {} > > So commonality here is that these are all arity overloads. > > I think there's three different kinds of overloads in involved in the RFC: > > 1. static/non-static overloads. Support for this was dropped in PHP 8, but had to be retained internally just for that one usage in FII, so getting rid of that seems quite high value. > > 2. type/meaning overloads, where certain parameters change meaning entirely across overloads. These are incompatible with named parameters and result in very unclear function signatures. They only become intelligible once split into separate signatures, which is not something PHP supports. Removing these is also fairly high value. > > 3. arity overloads, where behavior depends on number of parameters, or certain parameter counts are forbidden, but the actual meaning of the parameters does not change. Equivalent to a func_num_args() check in userland code. I think these arity overloads are pretty harmless. The function signature is meaningful and compatible with named arguments. > > My overall inclination here is to vote No on all the deprecations that involve arity overloads and vote Yes on the remainder. > > Possibly I'm missing some kind of complication that the arity overloads are causing? Currently the following code returns only the array keys that loosely equal null [1]: array_keys($array, null) If the function is changed to a single signature with $filter_value defaulting to null (with an argument count check to preserve the above functionality), its behavior becomes a lot more surprising/unexpected. If a parameter defaults to null, as a user I don't expect the function to work differently when I explicitly pass the default value. To prevent confusion, the function would at least still need to be documented with two separate signatures in the PHP manual, which goes against one of the RFC goals of automatically updating signatures based on stubs. So from my perspective there is value in deprecating arity overloads: it avoids confusing behavior changes and the need to manually keep the overloaded signatures documented and in sync in the manual. Regards, Theodore [1]: https://3v4l.org/Sld4S