PHPStanの導入と使い方をやさしく解説

新卒ブログとは？

2024年4月に新卒入社したLIGメンバーが、日々の学びや気づきを綴るブログです。彼らがふだんどんなことを学んでいるのか、気軽にのぞいてみてください。

こんにちは、テクニカルディレクターのチェです！

今回は、私が入社してから今までアサインされてきた案件で使っている「PHPStan」について紹介します。

PHPStanは、PHPコードを検査できる便利なツールで、プロジェクトに導入することで多くのメリットがあります。

今日はPHPStanの導入方法や使い方などをまとめましたので、これから使ってみたいという方にぜひ参考にしてもらえればと思います。

PHPStanとは？

PHPStanとは、PHPコードを実行する前に、実行時にエラーを起こしそうなコードを見つけて指摘してくれるツールです。開発段階で問題を発見できるため、本番環境でのエラーを未然に防ぐことができます。

また、コードの最低限のレビューもしてくれるため、レビューの手間を減らすことができます。

PHPStanのインストール方法

まずはPHPStanをインストールしましょう。インストールする際は、以下のコマンドを実行してください。

composer require --dev phpstan/phpstan

 
※Dockerでのインストール方法など、詳しい情報については、PHPStanの公式ドキュメントを参考にしてください。

Laravelプロジェクトの場合

PHPStanは純粋なPHPコードに対して静的解析を行うツールのため、Laravel特有の記述には対応していません。そのため、Laravelプロジェクトで静的解析を行いたい場合は、Larastanを使用する必要があります。

Larastanを導入すれば、内部的にPHPStanも自動でインストールされるため、個別にPHPStanをインストールする必要はありません。

導入手順や設定方法については、Larastan公式リポジトリを参考にしてください。

設定ファイル phpstan.neon の書き方

PHPStanのインストールが完了したら、設定を行いましょう。PHPStanの設定は、’phpstan.neon’というファイルで行えます。

まず、プロジェクトのルートディレクトリにphpstan.neonファイルを作成し、以下例のコードを書いてみてください。

　includes:
　　- ./vendor/larastan/larastan/extension.neon
　　- phpstan-baseline.neon

　parameters:
　　level: 5
　　paths:
　　　- app

includes:

includesは外部の設定ファイルを読み込むためのセクションです。

Larastanやbaseline（のちほど詳しく説明します）ファイルを登録することで、設定ファイルを使えるようになります。

parameters:

parametersセクションでは、PHPStanに渡すパラメータを定義します。PHPStanはチェックのレベルを0〜10まで指定でき、レベルが高いほど厳しいチェックが行われます。

今回は5に設定しますが、最大レベルに設定したい場合はmaxを指定することもできます。maxを使うと、PHPStanのバージョンに応じた最新の厳しさを自動で適用できるため、便利です。

各レベルごとの詳しい内容については公式ドキュメントを参考にしてください。

baseline機能の使い方

現在修正が難しかったりなどの理由でPHPStanで発生しているエラーを無視したい場合があると思います。そんなときは、baselineファイルを作成し、エラーをbaselineファイルに追加することで、チェック対象から除外できます。

baselineファイルの作成には、PHPStanコマンドの–generate-baselineオプションを利用します。

./vendor/bin/phpstan analyse --generate-baseline

上記のコマンドを実行すると、baselineファイルを作成し、現在検出しているエラーが追加され、追加されたエラーが今後発生しないようになります。一時的に無視されるだけで、実際に修正されたわけではありませんので、最終的には修正するようにしましょう。

PHPStanの実行方法

PHPStanの設定が完了したら、コードの解析を実行してみましょう。基本的な実行方法は以下のコマンドになります。

./vendor/bin/phpstan analyse

コマンドの後ろにはさまざまなオプションを指定することができますが、オプションについては公式ドキュメントを参考にしてください。

設定ファイルなしで実行する方法

phpstan.neonファイルを作成せずに、コマンド実行時に直接オプションを指定してPHPStanを実行することも可能です。

たとえば、「チェックレベルは5に設定」、「Larstanを使う」、「検査したいファイルを指定」するコマンドは以下になります。

./vendor/bin/phpstan analyse --level=5 --configuration=./vendor/larastan/larastan/extension.neon app/Http/Controllers/SampleController.php

このように、特定のファイルやディレクトリだけを対象に解析したい場合は、コマンドで個別に指定できるので便利です。

ただし、毎回オプションを付ける必要があるため、コマンドが長くなりがちです。 そのため、基本的にはphpstan.neonファイルに設定をまとめておくほうがおすすめです。

まとめ

ここまで、PHPStanの基本的な導入手順や設定方法を解説してきました。

PHP言語を導入したプロジェクトでは、PHPStanを使用することで作業の手間が減り、効率がかなり向上しますので、ぜひ覚えておきましょう。

今回は最小限の設定方法を説明しましたが、PHPStanにはさまざまなオプションや設定項目がありますので、さらに詳細を知りたい方は公式ドキュメントを確認してみてください。