楽をするためのPHPDocと 配列型の落とし穴 2020.8.21 @PHP LT Fes

自己紹介 ● 名前 ○ 荒巻 拓哉 ● 所属 ○ 株式会社ラクス ■ 配配メール というサービスの開発をしてます

PHPDoc、書いてますか？

https://github.com/symfony/symfony/blob/03155addd7c96a9455660b7d51d993cf4f8eb201/src/Symfony/Component/ HttpFoundation/InputBag.php

● コードを読む際に理解しやすい ● ドキュメントを生成できる → phpDocumentor ● IDEの補完が効きやすくなる → PhpStorm ● 静的解析ができる → PHPStan, Phan など 何のために書くの？

ドキュメント生成 https://github.com/PHPMailer/PHPMailer/blob/e7acd3d92fa02728c51bf64b90615bffc84815f0/src/PHPMailer.php

ドキュメント生成 http://phpmailer.github.io/PHPMailer/classes/PHPMailer.PHPMailer.PHPMailer.html#method_html2text

IDEで補完

静的解析 引数の型が違う、プロパティ・メソッドが存在しない、などを検出 DateTimeクラスにないメ ソッド 引数の型が違う

静的解析 PHPStan

静的解析 Phan

PHPDocの仕様？ 各ツールでサポートする記法が少しずつ異なる PSR-5, PSR-19として標準化する動きはあるが、現時点ではまだ提案段階

PHPDocを書いてみる 題材：Userクラス 　 ORマッパーのEntityクラスのイメージ

No content

PHPDocを書いてみる PHPDocをちゃんと書いてるからヨシ！ ……？ → 全ユーザのユーザ名を表示する関数を書いてみる

補完が効かない

補完が効かない

静的解析でエラー検知できない PHPStan Phan

なんで？ array型は中の要素の型はわからない → 補完も静的解析もできない

なんとかならないの？ User[] と書きましょう プリミティブの配列でもOK ● int[] ● string[] ● (User|string)[]※PhpStorm 2020.2時点で未対応

→

No content

PHPStan Phan

その他の配列型の書き方 @return array @return array @return array{id: int, name: string} 上記3つはPhpStorm 2020.2では未対応
 （ただのarray扱いになる）


まとめ ● PHPDocを書くと楽できる ○ 自動でドキュメントを作ってくれる ○ IDEで補完できる ○ 静的解析ができる ● 配列は要素の型も書く ○ int[]形式 ○ 連想配列はarray か array{id: int}形式 ■ ただしPhpStormは未対応 ● PHPDocはしっかり書きましょう！！！

参考資料 ● 2018年のPHPDoc事情とPSR-5 - Qiita https://qiita.com/tadsan/items/72b02339d12120ca37d7 ● array shapes記法(Object-like arrays)と旧PSR-5記法で型をつける - Qiita https://qiita.com/tadsan/items/bfa9465166c351da37e5 ● PSR-19: PHPDoc tagsを予習してみよう - BASE開発チームブログ https://devblog.thebase.in/entry/2019/12/14/110000