array shapes記法(Object-like arrays)と旧PSR-5記法で型をつける

この数年でPHPでの開発でもCI(継続的インテグレーション)はかなり活発に行われるようになり、PHPUnitなどのテスティングフレームワークのほか、PHPStanやPhanなどのツールによる静的解析も浸透しつつあります。

関数／メソッドの引数と返り値、そしてオブジェクトのプロパティは比較的に型がつけやすいところですが、現状で無法地帯な箇所があります。そうです、配列の内部構造です。実際のところ、PHPDocに `@param array` や `@return array` と書くことは `mixed` と書くのとあまり大きな違いはありません。

ご存じの通り、PHPの配列は、[動的配列(可変長配列)](https://ja.wikipedia.org/wiki/%E9%85%8D%E5%88%97#%E5%8B%95%E7%9A%84%E9%85%8D%E5%88%97)と[連想配列(ハッシュテーブル、マップ)](https://ja.wikipedia.org/wiki/%E9%80%A3%E6%83%B3%E9%85%8D%E5%88%97)の特徴を併せ持ったデータ構造であり、配列は変数と同じくあらゆる値を格納することができるからです。

近年の開発が活発なPHPの静的解析ツール(*PhpStormを除く*)では配列の内容に型をつけることができるようになっています。この記事ではPHPに静的解析で立ち向かうための一大地雷原である配列に鉈を入れるためのテクニックについて説明します。

*(この記事は2019年8月頃に書いてQiitaの下書きと社内のesaに書きかけのまま放置されていたものに加筆したものです。同様の趣旨の雑なまとめはPHP勉強会＠東京のLTスライド([arrayの型と向き合う #phpstudy](https://www.pixiv.net/fanbox/creator/105589/post/854598))にも書きましたが、本記事の方がちょっとだけ詳しいです。)*

## これまでのあらすじ

 * [2018年のPHPDoc事情とPSR-5](https://qiita.com/tadsan/items/72b02339d12120ca37d7) (読んでも読まなくてもいいです)

~~この記事を読む前にJetBrainsアカウントを持ってるPhpStormユーザーは[Support for array shape definitions / object-like arrays : WI-47052](https://youtrack.jetbrains.com/issue/WI-47052)に投票しておいてください。~~

<ins> **[2021年8月2日追記]**
[PhpStorm 2021.2でarray-shapesが実装された](https://blog.jetbrains.com/phpstorm/2021/07/phpstorm-2021-2-release/)ので、PhpStormを使っている方はすぐにアップデートしてください。deep-assocプラグインなどがなくても補完などがきくようになります。</ins>

## 例題

例として検索エンジンにクエリを投げる関数があったとします。この関数は検索ワードのほかに、オプショナルな要素として期間が指定できるとします。

```php
function search(string $word, array $options): array
{
    $begin = null;
    if (isset($options['begin'])) {
        $begin = $options['begin']->getTimestamp();
    }

    $end = null;
    if (isset($options['end'])) {
        $end = $options['end']->getTimestamp();
    }

    $query = compile_query('search_book', $word, $begin, $end);

    return request_search_engine($query);
}
```

この実装には現状ドキュメントもなく、`$options`には何を渡せばよいのかわからない状態です。

引数リストを `(string $word, ?DateTimeInterface $begin = null, ?DateTimeInterface $end = null)` と変形すれば問題は解決するでしょうか。いいえ、検索期間の指定はあくまでオプションなので、別個の引数を指定できるようにするのはあまり望ましい解決策ではありません。

## クラスを使った解法

いきなり解を出してしまいますが、このような用途には専用のクラスを作ってしまうのが、静的解析を妨げない「正攻法」な手段の一つです。

```php
class SearchOptions
{
    /** @var ?DateTimeInterface 検索期間の始点 */
    public $begin;
    /** @var ?DateTimeInterface 検索期間の終点 */
    public $end;
}

function search2(string $word, SearchOptions $options): array
{
    $timestamp = ['begin' => null, 'end' => null];

    $begin = $options->begin;
    if ($begin !== null) {
        $timestamp['begin'] = $options->begin->getTimestamp();
    }

    $end = $options->end;
    if ($end !== null) {
        $timestamp['end'] = $options->end->getTimestamp();
    }

    $query = compile_query('search_book', $word, $timestamp['begin'], $timestamp['end']);

    return request_search_engine($query);
}
```

ここではコードを短くするために`public`プロパティを使ってますが、実際にはセッター/ゲッターメソッドを定義するとかマジックメソッドを定義してやるとか好きなようにしてやってください。この定義でも、開発メンバーが全員PhpStormを使って注意深くコーディングするなら、あまり大きな問題はないかもしれません。PHP 7.4になれば[Typed properties](https://wiki.php.net/rfc/typed_properties_v2)が入りますし、言語標準の機能だけで堅く書けるようになりますしね。

ただし、この解法にはちょっとしたデメリットがあります。

ひとつはステートメントをまたいだボイラープレートを要求する、つまり `;` と改行区切りで書かないといけなくなることです。

```php
// Before
$books = search('ネコソギラジカル', [
    'begin' => new DateTimeImmutable('2002-11-01'),
]);

// After
$search_option = new SearchOption();
$search_option->begin = new DateTimeImmutable('2002-11-01');
$books = search('ネコソギラジカル', $search_option);
```

BeforeとAfterのどちらが良いかは、好みによるところがあります。行数こそ同じですが、不思議なことにコード量は増えてしまいましたね。では、クラスを利用することと、ボイラープレートのステートメントを増やさないことは両立するでしょうか。その方法もいちおうあります。

```SearchOptions.php
class SearchOptions
{
    /** @var ?DateTimeInterface 検索期間の始点 */
    public $begin;
    /** @var ?DateTimeInterface 検索期間の終点 */
    public $end;

    public static function fromArray(array $array): self
    {
        $option = new self();
        $option->begin = $array['begin'] ?? null;
        $option->end = $array['end'] ?? null;

        return $option;
    }
}
```

```php
$books = search('ネコソギラジカル', SearchOptions::fromArray([
    'begin' => new DateTimeImmutable('2002-11-01'),
]));
```

`SearchOptions::fromArray()`のぶんだけちょっと長くはなりましたが、悪くはないんじゃないでしょうか。静的メソッドを公開するかコンストラクタを公開するかも好みの問題ですね。ただ、問題が「`SearchOptions::fromArray()`に何を渡せばよいのかわからなくなった」ことにすりかわってますね。ううむ。

## 旧PSR-5ジェネリクス記法による配列の型付け

phpDocumentorやPhpStormを含めた複数の処理系がサポートするPHPDocのデファクトな仕様では `Book[]` のように記述することで `[new Book("a"), new Book("b"), new Book("c")]` のような**Bookクラスのオブジェクトだけが並んだ配列**を表現することができます。

この記法のメリットはいくつかあります。わかりやすく言うと、`foreach`の中でも型がついていることです。

```php
$books = getBooks();

foreach ($books as $book) {
    $book-> // Bookオブジェクトのメソッドの補完が効く
}
```

この`getBooks()`は以下のように型をつけることができます。

```php
/**
 * @return Books[]
 */
function getBook(): array
{
    // ...
}
```

この記法には弱点があります。PHPには複数のイテレータがありますが、`[]`は飽くまで配列を表すので、ジェネレータや`ArrayIterator`、あるいはその他のコレクションクラスなどは表現できないのです。

そこで、PHPDocを解釈するツールの多くは以下のようなジェネリクス記法をサポートします。

```php
/**
 * @return ArrayObject<Book>
 */
function getBook(): array
{
    // ...
}
```

従来記法では値の型のみを指定できましたが、ジェネリクス記法はキーと値の型を同時に指定できます。

```php
/**
 * @return ArrayObject<int, Book>
 */
function getBook(): array
{
    // ...
}
```

さて、ここまで「旧PSR-5」とわざわざ銘打っているということは、現在の策定作業中のPSR-5 Draftにはこの仕様が含まれていません。議論の長期化により、[remove references to generics by ashnazg · Pull Request #1102 · php-fig/fig-standards](https://github.com/php-fig/fig-standards/pull/1102)で一旦取り除かれました。ただし、これは将来的な議論を妨げるものではないことを明言されています。実際にはPhan, Psalm, PHPStan, [phpDocumentor/TypeResolver](https://github.com/phpDocumentor/TypeResolver), [Phpactor](https://github.com/phpactor/phpactor)など数多くのツールでこの形式をサポートしているので、使えるものと見てよいでしょう。

## array-shapes(Object-like arrays)を使った型付け

array-shapes記法は[Phanでは0.10.4](https://github.com/phan/phan/pull/1377)で導入された記法で、Psalmでは**Object-like arrays**と呼ばれています。簡素ですが、仕様はPsalmのドキュメントに掲載されています。

 * [Array types - Psalm Documentation](https://psalm.dev/docs/annotating_code/type_syntax/array_types/#object-like-arrays)

連想配列を返す関数は以下のように型付けできます。

```php
/**
 * @return array{name: string, birthday?: DateTimeImmutable, age: int}
 */
$f = function ():  {
    return [
        'name' => 'Miku',
        'age' => 16,
    ];
}
```

`birthday?`はキーの最後に`?`がついているのではなく、`birthday`というキーが省略可能だということです。

また、[PHPのlist()はタプル展開のための機能](https://qiita.com/tadsan/items/0beaf61747397c1e3db8)に書いたようにタプル風のリストで値を返す場合は以下のように型付けできます。

```php
/**
 * @return array{0: string, 1: ?DateTimeImmutable, 2: int}
 */
$f = function ():  {
    return ['Miku', null, 16];
}

[$name, $birthday, $age] = $f();
```

PHPではキーを明示的に指定しない値は0からの連番の数字が振られています。先程は`birthday`のキーそのものを省略可能にしていますが、こちらは文字列でキーを指定していたときと意図的に構造を変えていて、キーを省略可能にするのではなく、要素の型を`?DateTimeImmutable`にして明示的に`null`を返しています。

キーを省略するのか値の型をnullableにするのか、あるいはどちらでも良いように許容するのか、何が適しているは各自の考えかたによるので、各自よく考えて決めてください。

ということで、今回の問題提起のきっかけになった関数は`SearchOptions`クラスを定義することでも解決できますし、配列を受け取るようにもできます。

```php
/**
 * @param array{begin?: ?DateTimeInterface, end?: ?DateTimeInterface} $options
 */
function search(string $word, array $options): array
{
    $begin = null;
    if (isset($options['begin'])) {
        $begin = $options['begin']->getTimestamp();
    }

    $end = null;
    if (isset($options['end'])) {
        $end = $options['end']->getTimestamp();
    }

    $query = compile_query('search_book', $word, $begin, $end);

    return request_search_engine($query);
}
```

PHPの`isset($array['key'])`は「`$array['key']`が未定義だったとき」と「`$array['key']`の要素が`null`だったとき」の両方で`true`になります。そのため`begin?: ?DateTimeInterface`と書くことで両方に対応しています。

また、`SearchOptions`に渡す引数の方に型を付けても構いません。

```SearchOptions.php
<?php

class SearchOptions
{
    /** @var ?DateTimeInterface 検索期間の始点 */
    public $begin;
    /** @var ?DateTimeInterface 検索期間の終点 */
    public $end;

    /**
     * @param array{begin?: ?DateTimeInterface, end?: ?DateTimeInterface} $options
     */
    public static function fromArray(array $array): self
    {
        $option = new self();
        $option->begin = $array['begin'] ?? null;
        $option->end = $array['end'] ?? null;

        return $option;
    }
}
```

## 互換性の問題

ここまで紹介してきた**旧PSR-5形式のジェネリクス記法**と**array shapes記法(Object-like arrays)**ですが、PhpStormは2020年現在(2020.1 EAP)でも、依然としてサポートしていません([PhpStormに実装されてない未来のPHPDocとPSR-5ジェネリクス記法 - Qiita](https://qiita.com/tadsan/items/c9685be8e8297bd74cb6))。

ただし、[deep-assoc-completion - for IntelliJ IDEA, PhpStorm | JetBrains](https://plugins.jetbrains.com/plugin/9927-deep-assoc-completion)プラグインをインストールすることでPhpStormにこれらの基本の入力補完を追加することができます。インストールしましょう。

また、[LSP Support - plugin for IntelliJ IDEs | JetBrains](https://plugins.jetbrains.com/plugin/10209-lsp-support)プラグインでPsalmをLSPサーバとして登録することでもPsalmの静的解析を組み込むこともできますが、(私の感想では)やや不安定な感があります。

## まとめ

PhpStormの互換性をある程度に妥協できればarray shapes記法(Object-like arrays)と旧PSR-5記法は実用的に使えるので、使い始めましょう。

より発展的な機能として[PHPDocを使ったPHPのジェネリクス](https://www.phper.ninja/entry/2020/03/01/054833)というものもあります。

## おまけ: WordPressの`@type`タグ

WordPressでは連想配列の内部構造に型をつける記法として`@type`が用いられています。この記法は内部構造のドキュメント化ができるという点で優れていますが、多くの静的解析ツールには実装されておらず、WordPress文化圏での独自仕様に留まっています。このタグについての仕様はWordPress Coreの開発マニュアル([PHP Documentation Standards – Make WordPress Core](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#1-1-parameters-that-are-arrays))にまとめられています。WordPress本体やプラグイン以外では多用しないのが無難でしょう。この記法はほかのタグの記法と矛盾はしませんが、2020年2月現在の多くのツールでは利用されないため、この記事では紹介しません。