結論

Larastanを導入すると、Laravelプロジェクトでも静的解析ができる
コードを実行する前にバグの候補を検出できるため、開発効率が上がる
最初は level: 0 で十分。移植初期から厳しい設定にすると警告対応ばかりになるため、徐々に引き上げるのが現実的

PHPStan / Larastanとは

PHPStanとは

PHPStanはPHPの静的解析ツールです。コードを実際に実行しなくても、潜在的な問題を事前に検出できます。

たとえば、以下のようなスペルミスもエラーとして検出できます。

// name のはずが nmae になっている
$user->nmae;

PHPStanがあれば、このようなミスをコードレビューや実行前に気づけます。

Larastanとは

LarastanはPHPStanのLaravel向け拡張パッケージです。

LaravelはEloquentやFacadeなど動的な仕組みを多用しているため、素のPHPStanでは解析が難しい部分があります。Larastanを使うことで、Laravelの構文を正しく解析できるようになります。

環境

項目	内容
Laravel	10.x
実行環境	Laravel Sail（Docker）
エディタ	VSCode

導入手順

1. インストール

Sailのコンテナ内でComposerを使ってインストールします。

sail composer require --dev larastan/larastan

--dev を付けることで、開発環境専用のパッケージとしてインストールされます。

2. 設定ファイルの作成

プロジェクトルートに phpstan.neon を作成します。

touch phpstan.neon

3. 設定内容を記述

phpstan.neon に以下の内容を記述します。

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

parameters:
    paths:
        - app

    level: 0

設定内容の解説

includes

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

LarastanがLaravel用に用意した拡張設定を読み込む記述です。これにより、EloquentやFacadeなどLaravel特有の構文が正しく解析されます。

paths

paths:
    - app

解析対象のディレクトリを指定します。今回は app ディレクトリのみを対象にしています。必要に応じて tests などを追加できます。

level

level: 0

解析の厳しさを0〜9の数値で指定します。数値が大きいほど厳しくなります。

レベル	内容
0	最も緩やか。致命的な問題を中心に検出
5	型の整合性なども検査
9	最も厳格

初学者や移植初期は level: 0 から始めて、慣れてきたら少しずつ上げていくのがおすすめです。

実行方法

以下のコマンドで静的解析を実行します。

sail php ./vendor/bin/phpstan analyse

躓いたポイント

`sail vendor/bin/phpstan analyse` ではエラーになった

最初に以下のコマンドを実行したところ、エラーが発生しました。

sail vendor/bin/phpstan analyse

unknown docker command: "compose vendor/bin/phpstan"

原因

vendor/bin/phpstan はPHPスクリプトのため、実行には php を明示的に付ける必要があります。sail コマンドはDockerのコマンドとして解釈しようとするため、そのままでは動作しません。

正しい実行方法

sail php ./vendor/bin/phpstan analyse

sail php とすることで、SailのコンテナのPHPを使ってスクリプトを実行できます。

実行結果

正しく実行できると、以下のような出力が得られます。

 [OK] No errors

phpstan.neon の設定に従い、app ディレクトリ配下を静的解析できました。今回の環境では、level: 0 で問題なしという結果になりました。

Git管理

今回の変更でコミット対象になるファイルは以下の通りです。

コミットするファイル

composer.json
composer.lock
phpstan.neon

今回は自動生成されるファイルはないため、.gitignore への追加は不要です。

実際に触って感じたこと

同じLaravel開発補助ツールとして IDE Helper もありますが、役割が異なります。

ツール	役割
IDE Helper	コード補完（VSCodeなどの入力支援）
PHPStan / Larastan	静的解析（潜在的なバグの検出）

Laravelは動的な仕組みが多いため、この2つを組み合わせると開発しやすくなると感じました。

また、移植初期から厳しいlevelに設定すると警告対応ばかりになってしまうため、最初は level: 0 から始めて段階的に引き上げていくのが現実的だと感じました。