【PHP8.3】標準関数のオーバーロードを削除してシグネチャをひとつにするよ

言語によっては、同じ名前のメソッドを複数定義できるものがあります。
一般的にオーバーロードと呼ばれる機能で、Javaなど型が厳格な言語ではよく見ます。

```java:Java
public class Foo {
    public static void bar(int val) {
        System.out.println("int型の" + val);
    }
    public static void bar(String val) {
        System.out.println("String型の" + val);
    }
}

Foo::bar(1);   // int型の1
Foo::bar("1"); // String型の1
```

引数の型によって別のメソッドが実行されます。

翻ってPHPは、同名のメソッド・関数を定義することができません。
昔のPHPは引数に型を書くことができず、区別をつけることができなかったからです。
今は引数の型を書くことができるようになりましたが、別に書かなくても動くので今でも区別できません。

ところがPHPの組込関数には、そんな制限をぶっ飛ばしたかのような関数が存在します。
たとえば[DatePeriod::__construct()](https://www.php.net/manual/ja/dateperiod.construct.php)にはシグネチャが3種類もあります。

```php
class DatePeriod
{
    public function __construct(DateTimeInterface $start, DateInterval $interval, DateTimeInterface $end, int $options = 0) {}
    public function __construct(DateTimeInterface $start, DateInterval $interval, int $recurrences, int $options = 0) {}
    public function __construct(string $isostr, int $options = 0) {}
}
```

まあ[実際存在するメソッドはひとつだけ](https://github.com/php/php-src/blob/php-8.2.8/ext/date/php_date.c#L4713)で、関数の中でがんばって引数の型をチェックしているだけなんですけどね。

ということで組込関数において関数のオーバーロードをやめようというRFCが提出されました。
既に投票は終わっていて、今後PHP8.3以降のバージョンで順次非推奨となり、PHP9以降で削除されます。

以下は該当のRFC、[Deprecate functions with overloaded signatures](https://wiki.php.net/rfc/deprecate_functions_with_overloaded_signatures)の紹介です。

# PHP RFC: Deprecate functions with overloaded signatures

## Introduction

[メソッドのオーバーロード](https://www.mygreatlearning.com/blog/method-overloading-in-java/)は、Java開発者にはお馴染みですが、PHPはサポートしていません。
しかしながら、いくらかのPHP内部関数やメソッドには、複数のシグネチャが存在するように見えるものがあります。
すなわち、オーバーロードが存在します。


ここしばらく、PHPは内部コードとユーザランドコード間の不整合を減らす方向に進化しています。
この取り組みを継続するためには、PHPネイティブにオーバーロードをサポートするか、内部関数のオーバーロードを廃止していく必要があるでしょう。
前者の解決策は[効率的な解決が不可能である](https://github.com/Danack/RfcCodex/blob/master/method_overloading.md)ことが知られているため、後者が望ましい選択肢です。

さらに、一貫性を維持することだけが本RFCの目的ではありません。

PHP8.0より前のバージョンでは、オーバーロードが大きな害をもたらすことはありませんでした。
PHP8.0以降では、以下のような理由によってオーバーロードは大きな問題になりつつあります。

・ReflectionParameterでデフォルト値を取ってこれるようになった。
・シグネチャによって処理が全く異なるため、[名前付き引数](https://wiki.php.net/rfc/named_params)に適切な引数名が設定できない。
・2年以上前から、[オンラインマニュアル](https://php.net/)のシグネチャはソースコードに基いて[半自動更新されている](https://externals.io/message/105970)が、オーバーロードされた関数は自動更新できないため、シグネチャが古くなったり誤ったりする可能性がある。

名前付き引数のRFCが受理されたのち、PHP8.0では何十何百もの関数が修正され、正確な引数処理セマンティクスに従って動作するようになりました。
影響のない関数についてはずっと修正され続けています。

このRFCでは、後方互換性に影響を与えるケースを取り上げます。

## Proposal

本RFCでは、以下に取り上げるオーバーロード関数のシグネチャを、PHP8.3以降のどこかの段階で廃止します。
PHP8.3では段階的移行を容易にするため、代替の関数が必要なものについては追加します。
次のマイナーバージョンでは、影響を受けるシグネチャを非推奨にします。
最後に、次のメジャーバージョンであるPHP9.0、もしくはさらに次のPHP10.0において、非推奨としていたシグネチャを実際に削除します。


### DatePeriod::__construct()

**受理。1つめのシグネチャ以外はPHP8.4で非推奨、PHP9.0で削除される。**

[DatePeriod::__construct()](https://www.php.net/manual/ja/dateperiod.construct.php)には3つのシグネチャが存在します。

```php
class DatePeriod
{
    public function __construct(DateTimeInterface $start, DateInterval $interval, DateTimeInterface $end, int $options = 0) {}
    public function __construct(DateTimeInterface $start, DateInterval $interval, int $recurrences, int $options = 0) {}
    public function __construct(string $isostr, int $options = 0) {}
}
```

1つめを残し、3番目についてはファクトリーメソッドを用意します。

```php:PHP8.4
class DatePeriod
{

    public function __construct(DateTimeInterface $start, DateInterval $interval, DateTimeInterface|int $end, int $options = 0) {}
 
    public static function createFromISO8601String(string $specification, int $options = 0): static {}
}
```

上位2000パッケージのうち、3番目の使い方をしているものは存在しませんでした。


### dba_fetch()

**受理。1つめのシグネチャ以外はPHP8.3で非推奨、PHP9.0で削除される。**

[dba_fetch()](https://www.php.net/manual/ja/function.dba-fetch)はBerkeley DBからデータをフェッチする関数であり、現在2つのシグネチャをサポートしています。

```php
function dba_fetch(string|array $key, resource $dba, int $skip = 0): string|false {}

function dba_fetch(string|array $key, int $skip, resource $dba): string|false {}
```

引数`$dba`と`$skip`は、どちらの順番でも受け付けてしまいます。
このRFCでは、後者の使い方をPHP8.3で非推奨とし、PHP9.0で削除します。

```php:PHP8.3
function dba_fetch(string|array $key, resource $dba, int $skip = 0): string|false {}
```

上位2000パッケージのうち、後者の使い方をしているものは存在しませんでした。


### FFI::cast(), FFI::new(), and FFI::type()

**受理。1つめのシグネチャ以外はPHP8.3で非推奨、PHP9.0で削除される。**

[FFI::cast()](https://www.php.net/manual/ja/ffi.cast.php)・[FFI::new()](https://www.php.net/manual/ja/ffi.new.php)・[FFI::type()](https://www.php.net/manual/ja/ffi.type.php)には、現在2つのシグネチャが存在します。

```php
class FFI
{
    public static function cast(FFI\CType|string $type, FFI\CData|int|float|bool|null &$ptr): ?FFI\CData {}
    public function cast(FFI\CType|string $type, FFI\CData|int|float|bool|null &$ptr): ?FFI\CData {}

    public static function new(FFI\CType|string $type, bool $owned = true, bool $persistent = false): ?FFI\CData {}
    public function new(FFI\CType|string $type, bool $owned = true, bool $persistent = false): ?FFI\CData {}

    public static function type(string $type): ?FFI\CType {}
    public function type(string $type): ?FFI\CType {}
}
```

静的メソッドは定義済の型のみですが、インスタンスメソッドはcdef型もサポートしています。

インスタンスメソッドとして呼び出す方が一般的なので、このRFCでは静的メソッドのほうを廃止します。
PHP9もしくは10で削除され、以下のようになります。

```php:PHP9.0
class FFI
{
    public function cast(FFI\CType|string $type, FFI\CData|int|float|bool|null &$ptr): ?FFI\CData {}

    public function new(FFI\CType|string $type, bool $owned = true, bool $persistent = false): ?FFI\CData {}

    public function type(string $type): ?FFI\CType {}
}
```

上位2000パッケージのうち、該当のメソッドを静的に呼び出しているものは[1パッケージだけ](https://gist.github.com/kocsismate/4592eecdd7ad82e0d00e49e5514d32eb)でした。


### get_class() and get_parent_class()

**受理。1つめのシグネチャ以外はPHP8.3で非推奨、PHP9.0で削除される。**

[get_class()](https://www.php.net/manual/ja/function.get-class)と[get_parent_class()](https://www.php.net/manual/ja/function.get-parent-class)には、現在2つのシグネチャが存在します。

```php
function get_class(object $object): string {}

function get_class(): string {}
```

引数があればそのオブジェクトのクラス名を取得し、なければ現在のコンテキストのクラス名を取得します。

PHP7.2で受理された[get_class() disallow null parameter](https://wiki.php.net/rfc/get_class_disallow_null_parameter)の影響により、get_classの引数にはデフォルト値が存在しません。

このRFCでは、引数のない呼び出しをPHP8.3で非推奨とし、PHP9で削除します。

```php:PHP9.0
function get_class(object $object): string {}

function get_parent_class(object|string $object_or_string): string {}
```

現在`get_class()`を引数なしで呼んでいるコードは、`get_class(self::class)`もしくは`get_class($this)`と修正する必要があります。
また`get_parent_class()`を引数なしで呼んでいるコードは、`get_class(parent::class)`もしくは`ReflectionClass::getParentClass()`を使うように修正する必要があります。

上位2000パッケージのうち、該当のメソッドを引数なしで呼び出しているものは[10パッケージ](https://gist.github.com/kocsismate/cc41145f6cf96854608de042f8a3048b)でした。


### IntlCalendar::set()

**受理。1つめのシグネチャ以外はPHP8.4で非推奨、PHP9.0で削除される。**

[IntlCalendar::set()](https://www.php.net/manual/ja/intlcalendar.set.php)には、現在4つのシグネチャが存在します。

```php
class IntlCalendar
{

    public function set(int $field, int $value): true {}
    public function set(int $year, int $month, int $dayOfMonth): true {}
    public function set(int $year, int $month, int $dayOfMonth, int $hour, int $minute): true {}
    public function set(int $year, int $month, int $dayOfMonth, int $hour, int $minute, int $second): true {}
}
```

最初のひとつはフィールドを指定して直接書き換えるもので、それ以外は複数のフィールドをそれぞれ書き替えるものです。
そして、4つの引数を持つ`IntlCalendar::set()`は呼び出すことができません。

本RFCでは、まずPHP8.3において後ろ3つの`set`を代替するメソッドを新しく追加します。
そして後ろ3つの`set`はPHP8.4で非推奨とし、PHP9で削除します。

```php:PHP9.0
class IntlCalendar
{
    public function set(int $field, int $value): true {}

    public function setDate(int $year, int $month, int $dayOfMonth): void {}
    public function setDateTime(int $year, int $month, int $dayOfMonth, int $hour, int $minute, ?int $second = null): void {}
}
```

追加されたメソッドの返り値は`void`です。

また、手続き型として存在する[intlcal_set()](https://www.php.net/manual/ja/intlcalendar.set.php)関数はこのエイリアスであるため、同じく非推奨化されます。
というよりそもそも手続き型自体がレガシーなので、`intlcal_set()`関数自体の削除を提案します。

3つ以上の引数を持つ`IntlCalendar::set()`は、2引数のメソッドに変更するか、PHP8.3で新設されるメソッドに変更する必要があります。

上位2000パッケージのうち、`IntlCalendar::set()`を3つ以上の引数で呼び出しているものは存在しませんでした。


### IntlGregorianCalendar::__construct()

**受理。1つめのシグネチャ以外はPHP8.4で非推奨、PHP9.0で削除される。**

[IntlGregorianCalendar::__construct()](https://www.php.net/manual/ja/intlgregoriancalendar.construct.php)には、現在3つのシグネチャが存在します。

```php
class IntlGregorianCalendar
{

    public function __construct(IntlTimeZone|DateTimeZone|string|null $timezone = null, ?string $locale = null) {}
    public function __construct(int $year, int $month, int $dayOfMonth) {}
    public function __construct(int $year, int $month, int $dayOfMonth, int $hour, int $minute, ?int second = null) {}
}
```

`IntlGregorianCalendar::__construct()`も4引数で呼び出すことはできません。

本RFCでは、まずPHP8.3において後ろ2つのコンストラクタを代替するメソッドを新しく追加します。
そして後ろ2つのコンストラクタはPHP8.4で非推奨とし、PHP9で削除します。

```php:PHP9.0
class IntlGregorianCalendar
{
    public function __construct(IntlTimeZone|DateTimeZone|string|null $timezone = null, ?string $locale = null) {}

    public static function createFromDate(int $year, int $month, int $dayOfMonth): static {}
    public static function createFromDateTime(int $year, int $month, int $dayOfMonth, int $hour, int $minute, ?int second = null): static {}
}
```

手続き型として存在する[intlgregcal_create_instance()](https://www.php.net/manual/ja/intlgregoriancalendar.construct.php)関数はこのエイリアスであり、同じ影響を受けます。
こちらも[レガシー](https://externals.io/message/114473#114673)なので、`intlgregcal_create_instance()`関数自体の削除を提案します。


3つ以上の引数を持つ`IntlGregorianCalendar::__construct()`は、2引数のメソッドに変更するか、PHP8.3で新設される静的メソッドに変更する必要があります。

上位2000パッケージのうち、`IntlGregorianCalendar::__construct()`を3つ以上の引数で呼び出しているものは存在しませんでした。


### ldap_connect()

**受理。1つめのシグネチャ以外はPHP8.4で非推奨、PHP9.0で削除される。**

[ldap_connect()](https://www.php.net/manual/ja/function.ldap-connect.php)には、現在2つのシグネチャが存在します。

```php
function ldap_connect(?string $uri = null, int $port = 389): LDAP\Connection|false {}
 
function ldap_connect(
    ?string $uri,
    int $port,
    string $wallet,
    string $password,
    int $auth_mode
): LDAP\Connection|false {}
```

本RFCでは、まずPHP8.3において2つ目のシグネチャを使用する関数を追加します。
そして2つ目のシグネチャをPHP8.4で非推奨とし、PHP9で削除します。

```php:PHP9.0
function ldap_connect(?string $uri = null, int $port = 389): LDAP\Connection|false {}

function ldap_connect_wallet(?string $uri, string $wallet, string $password, int $auth_mode): LDAP\Connection|false {}
```

新しい関数の引数に`$port`はありません。
これは別途[Deprecations for PHP 8.3](https://wiki.php.net/rfc/deprecations_php_8_3#deprecate_calling_ldap_connect_with_2_parameters)のRFCで廃止されるためです。

後者の引数を持つ`ldap_connect()`は、`ldap_connect_wallet()`に変更する必要があります。

上位2000パッケージのうち、`ldap_connect()`を後者の引数で呼び出しているものは存在しませんでした。


### ldap_exop()

**受理。1つめのシグネチャ以外はPHP8.4で非推奨、PHP9.0で削除される。**

[ldap_exop()](https://www.php.net/manual/ja/function.ldap-exop.php)には、現在2つのシグネチャが存在します。

```php
function ldap_exop(
    LDAP\Connection $ldap,
    string $request_oid,
    ?string $request_data = null,
    ?array $controls = null
): LDAP\Result|false {}
 
/**
 * @param string $response_data
 * @param string $response_oid
 */
function ldap_exop(
    LDAP\Connection $ldap,
    string $request_oid,
    ?string $request_data = null,
    ?array $controls = null,
    &$response_data,
    &$response_oid
): bool {}

```

前者は非同期に実行され、後者は同期で実行されます。

本RFCでは、まずPHP8.3において2つ目のシグネチャを使用する関数を追加します。
そして2つ目のシグネチャをPHP8.4で非推奨とし、PHP9で削除します。

```php:PHP9.0
function ldap_exop(
    LDAP\Connection $ldap,
    string $request_oid,
    ?string $request_data = null,
    ?array $controls = null
): LDAP\Result|false {}

/**
 * @param string $response_data
 * @param string $response_oid
 */
function ldap_exop_sync(
    LDAP\Connection $ldap,
    string $request_oid,
    ?string $request_data = null,
    ?array $controls = null,
    &$response_data = null,
    &$response_oid = null
): bool {}
```

後者の引数を持つ`ldap_exop()`は、`ldap_exop_sync()`に変更する必要があります。

上位2000パッケージのうち、`ldap_exop()`を後者の引数で呼び出しているものは存在しませんでした。


### pg_fetch_result(), pg_field_prtlen(), and pg_field_is_null()

**受理。1つめのシグネチャ以外はPHP8.4で非推奨、PHP9.0で削除される。**

[pg_fetch_result()](https://www.php.net/manual/ja/function.pg-fetch-result)・[pg_field_prtlen](https://www.php.net/manual/ja/function.pg-field-prtlen.php)・[pg_field_is_null](https://www.php.net/manual/ja/function.pg-field-is-null.php)には、現在2つのシグネチャが存在します。

```php
function pg_fetch_result(PgSql\Result $result, mixed $field): string|false|null {}
function pg_fetch_result(PgSql\Result $result, int $row, mixed $field): string|false|null {}

function pg_field_prtlen(PgSql\Result $result, string|int $field): int|false {}
function pg_field_prtlen(PgSql\Result $result, int $row, string|int $field): int|false {}

function pg_field_is_null(PgSql\Result $result, string|int $field): int|false {}
function pg_field_is_null(PgSql\Result $result, int $row, string|int $field): int|false {}
```

本RFCでは、PHP8.3で引数`$row`をnullableとし、前者をPHP8.4で非推奨とし、PHP9で削除します。

```php:PHP9.0
function pg_fetch_result(PgSql\Result $result, ?int $row, mixed $field): string|false|null {}

function pg_field_prtlen(PgSql\Result $result, ?int $row, string|int $field): int|false {}

function pg_field_is_null(PgSql\Result $result, ?int $row, string|int $field): int|false {}
```

前者の引数を持つ`ldap_exop()`は、引数にnullを追加する必要があります。

上位2000パッケージのうち、前者の使い方をしているものは[1パッケージ](https://gist.github.com/kocsismate/1fa5f1c6a83fdbdfb016eeade5ae4128)でした。


### Phar::setStub()

**受理。1つめのシグネチャ以外はPHP8.3で非推奨、PHP9.0で削除される。**

[Phar::setStub()](https://www.php.net/manual/ja/phar.setstub.php)には、現在2つのシグネチャが存在します。

```php
class Phar
{
    public function setStub(string $string) {}
    public function setStub(resource $resource, int $length) {}
}
```

本RFCでは、後者をPHP8.3で非推奨とし、PHP9で削除します。

```php:PHP9.0
class Phar
{
    public function setStub(string $string) {}
}
```

後者を`$phar->setStub(stream_get_contents($resource));`と書き替えるのは簡単です。

上位2000パッケージのうち、後者の使い方をしているものは存在しませんでした。


### ReflectionMethod::__construct()

**受理。1つめのシグネチャ以外はPHP8.4で非推奨、PHP9.0で削除される。**

[ReflectionMethod::__construct()](https://www.php.net/manual/ja/reflectionmethod.construct.php)には、現在2つのシグネチャが存在します。

```php
class ReflectionMethod
{
    public function __construct(object|string $objectOrClass, string $method) {}
    public function __construct(string $classMethod) {}
}
```

本RFCでは、まずPHP8.3において後者を代替する静的メソッドを追加します。
そして後者のシグネチャをPHP8.4で非推奨とし、PHP9で削除します。

```php:PHP9.0
class ReflectionMethod
{
    public function __construct(object|string $objectOrClass, string $method) {}
    public static function createFromMethodName(string $method): static {}
}
```

1引数の`ReflectionMethod::__construct()`は書き替える必要があります。

上位2000パッケージのうち、後者の使い方をしているものは[10パッケージ](https://gist.github.com/kocsismate/b457f8fef074039b58fbee9121d05e92)でした。


### ReflectionProperty::setValue()

**受理。1つめのシグネチャ以外はPHP8.3で非推奨、PHP9.0で削除される。**


[ReflectionProperty::setValue()](https://www.php.net/manual/ja/reflectionproperty.setvalue.php)には、現在3つのシグネチャが存在します。

```php
class ReflectionProperty
{
    public function setValue(object $object, mixed $value): void {}
    public function setValue(mixed $unused, mixed $value): void {}
    public function setValue(mixed $value): void {}
}
```

後ろ2つのシグネチャは、静的プロパティにのみ使用可能です。
引数`$unused`は完全に無視されます。

本RFCでは、後者をPHP8.3で引数`$object`をnullableとし、後ろ2つのシグネチャを非推奨とします。
後ろ2つのシグネチャはPHP9で削除します。

```php:PHP9.0
class ReflectionProperty
{
    public function setValue(?object $object, mixed $value): void {}
}
```

インスタンスの場合、引数`$object`はオブジェクトでなければなりません。
静的プロパティの場合はオブジェクトもしくはnullとなります。

提案されている代替案は、PHP5.2以降で既に利用可能です。


### session_set_save_handler()


**受理。1つめのシグネチャ以外はPHP8.4で非推奨、PHP9.0で削除される。**

[session_set_save_handler()](https://www.php.net/manual/ja/function.session-set-save-handler.php)には、現在2つのシグネチャが存在します。

```php
function session_set_save_handler(SessionHandlerInterface $session_handler, bool $register_shutdown = true): bool {}

function session_set_save_handler(
    callable $open,
    callable $close,
    callable $read,
    callable $write,
    callable $destroy,
    callable $gc,
    ?callable $create_sid = null,
    ?callable $validate_sid = null,
    ?callable $update_timestamp = null): bool {}
```

本RFCでは、後者をPHP8.4で非推奨とし、PHP9で削除します。

```php:PHP9.0
function session_set_save_handler(SessionHandlerInterface $session_handler, bool $register_shutdown = true): bool {}
```

後者の書き方をしている場合は、SessionHandlerInterfaceに書き替える必要があります。

上位2000パッケージのうち、後者の使い方をしているものは[1パッケージ](https://gist.github.com/kocsismate/6ea902ada1eb959b5642e274844b26c0)でした。


### stream_context_set_option()

**受理。1つめのシグネチャ以外はPHP8.4で非推奨、PHP9.0で削除される。**

[stream_context_set_option()](https://www.php.net/manual/ja/function.stream-context-set-option)には、現在2つのシグネチャが存在します。

```php
/** @param resource $context */
function stream_context_set_option(
    $context,
    string $wrapper,
    string $option_name,
    mixed $value
): true {}
 
/** @param resource $context */
function stream_context_set_option($context, array $options): bool {}
```

本RFCでは、まずPHP8.3において後者を代替する関数を追加します。
そして後者のシグネチャをPHP8.4で非推奨とし、PHP9で削除します。

```php:PHP9.0
function stream_context_set_option(
    $context,
    string $wrapper,
    string $option_name,
    mixed $value
): true {}
 
/** @param resource $context */
function stream_context_set_options($context, array $options): bool {}
```

後者の書き方をしている場合は、関数名を書き替える必要があります。

上位2000パッケージのうち、後者の使い方をしているものは[1パッケージ](https://gist.github.com/kocsismate/2e0625f9a95ad1e3e29a8660461de425)でした。


### Policy about new functions

**受理。**

今後新しく追加される関数やメソッドは、複数のシグネチャを持ってはいけません。
既存の関数やメソッドに、追加のシグネチャを持たせてはいけません。


### array_keys()

**却下。変更されない。**

[array_keys()](https://www.php.net/manual/ja/function.array-keys.php)にはふたつのシグネチャが存在します。
ひとつめは全てのキーを返し、ふたつめは`$filter_value`にマッチする項目のキーを返します。

```php
function array_keys(array $array): array {}

function array_keys(array $array, mixed $filter_value, bool $strict = false): array {}
```

本RFCでは、まずPHP8.3において後者を代替する関数を追加します。
そして後者のシグネチャをPHP8.4で非推奨とし、PHP9で削除します。

```php
function array_keys(array $array): array {}

function array_keys_filter(array $array, mixed $filter_value, bool $strict = false): array {}
```


## Backwards incompatible changes

後方互換性のない変更点。

PHP8.3および8.4で、非推奨の通知が発生することがあります。
これらはPHP9.0もしくはPHP10.0において使用できなくなります。


# 感想

ということで、今後はシグネチャがひとつになり、どちらの書き方をすれば？となることもなくなります。
また[名前付き引数](https://qiita.com/rana_kualu/items/13bc0c30192ee22c1396)とも相性がいいですね。


ただひとつだけ却下されたarray_keysですが、これは[メーリングリストで異議が入った](https://externals.io/message/120677#120683)からだと思われます。
他に比べて影響も大きそうですしね。

ほとんどの変更は、2000パッケージ中で数パッケージ、あるいは皆無といった使用率だとか、そもそも関数自体ほぼ使われてないとかであり、実質的にほぼ影響がないレベルですね。
実際私がこれまで書いてきたコードでも、影響を受ける可能性のある変更って`DatePeriod::__construct()`だけだと思います。
一般的には、ほぼ気にするレベルではないと思われます。