PHP を書く方ならご存知の静的解析ツール PHPStan ですが、コードの品質を比較的低コストで維持するものとしてはもはや欠かせないツールですね。
PHPStan を使う上では、以下のようなフローを何度も繰り返すと思います。
- コードを書く
- ローカルや CI などで PHPStan を実行
- 出力を見てコード箇所を特定して修正
このフローの 3 の部分で、PHPStan の標準だとエラーが出た際に「ファイルパス」と「行数」しか出力されないので、すぐにはエラーの箇所がわかりません。
というわけで、出力からぱっと見でエラー箇所が分かるようなフォーマッターを作りました。
これが
こうなります
エラー箇所の周辺のコードが表示されるようになります。
パッケージについて
パッケージとしての機能はこれだけですが、周辺コードが表示されているだけでも、出力を見てすぐに「あ〜ここか」とわかるので僅かに効率的になるかと思います。
なお、もし GitHub Action などを使っているなら reviewdog と組み合わせて PR 上に表示できたりもするので、むしろそちらをおすすめします。あくまでローカルで実行する場合やCI環境の整備が難しい場合に使っていただければと思います。
そして、勘のいい方はお気づきかと思いますが Collision というパッケージに出力を寄せています。
またネーミングは eslint-friendly-formatter から来ています。機能的には phpstan-codeframe-formatter 的な名前でも良かったのですが、将来的に eslint-friendly-formatter のようなエラーのグルーピングの出力機能も追加したいのでこの名前にしています。
使い方
Composer を使って簡単にインストールできます。
$ composer require --dev yamadashy/phpstan-friendly-formatter
インストール後、 phpstan.neon に以下の設定を追加してください。
includes:
- ./vendor/yamadashy/phpstan-friendly-formatter/extension.neon
そして、PHPStanの実行で --error-format friendly をつけて実行すると使えます。
$ ./vendor/bin/phpstan analyze --error-format friendly
サンプル
GitHub Actions で使用すると、以下のように出力されます。
https://github.com/yamadashy/laravel-blade-minify-directive/actions/runs/4714024802/jobs/8360104870
パッケージの開発について
コードを表示しているだけなので語ることも多くないですが、PHPStan のフォーマッターの作り方としてはこちらが参考になります。
標準のフォーマッターがいくつかあるので、GitHub でコードを参考にするのが手っ取り早いです。
大きくは以下の手順でコードを書いていきます。
-
ErrorFormatterを継承 - 他のフォーマッターを参考に
formatErrorsを定義 -
$analysisResultから Error や Warning の情報が取得できるので、そちらを元に$outputで出力
そして extension.neon など、パッケージ使用者に使ってほしいフォーマッターの設定ファイルを作成したらもう完成です。
コードの表示に関しては PHP-Console-Highlighter を使っています。
今後
eslint-friendly-formatter には以下のようなエラーのグルーピング機能がありまして、PHPStan の エラーの識別子をつけよう という議論が進めば PHPStan の出力でも同様のことができそうだなと思っています。
全体を見渡すサマリーとして有用なので是非入れたい機能です。公式で入りそうでもありますね。
さいごに
PHPStan は活発に改善されていて日々感謝していますが、こういった細かい部分がより便利に使いやすくなると良いなと思います。
何か PHPStan がより快適に使えるライブラリなどあれば紹介いただけると助かります！