この記事は?

Laravelプロジェクトの品質向上の一環で、静的解析ツールを導入しました。
PHPStanとLarastanの導入経験と手順を共有します。

前提

PHPStan/Larastanについて

PHPStanとLarastanは、PHPコードの品質向上と開発効率化を支援する効果的な静的解析ツールです。

  • PHPStan: 一般的なPHPプロジェクトで使用可能です。コード内の潜在的な問題や型の不一致を検出します。
  • Larastan: PHPStanの拡張機能です。Laravel専用に調整され、フレームワークの独特な仕組みを理解します。

これらのツールは日々の開発をサポートするだけでなく、PHPやLaravelのバージョンアップ時にも非常に役立ちます。
新しいバージョンで問題が発生する可能性のある箇所や、非推奨となった古い機能を事前に検出してくれるため、アップデート作業がよりスムーズになります。

これにより、開発者はより確実に高品質なコードを書けるようになり、長期的なプロジェクト管理の負担も軽くなります。
PHPStanとLarastanは、高品質なコードを目指す開発者にとって非常に有用なツールです。

導入手順

前提

今回は以下の条件で導入を行いました。

  • スキャン対象のバージョン
    • PHP:v8.2
    • Laravel:v11
  • 解析ツールのバージョン
    • PHPStan:2.1.8
    • Larastan:v3.1.0

プロジェクトの構成は以下の通りです。

/project_root/
    └ app/  # スキャン対象
    └ vendor/ 
    └ composer.json
    └ phpstan.neon # 今回追加する設定ファイル
    └...

今回は、app ディレクトリ以下のソースコードをスキャン対象とします。

次の章では、解析ツールの導入手順を説明します。
まずPHPStanを導入し、その後Larastanで機能を拡張していきます。

PHPStanの導入

PHPStanのインストール

Composerを使用して、開発環境にPHPStanとLarastanをインストールする。
プロジェクトのルートディレクトリに移動し、インストールコマンドを実行する。

cd {略}/project_root/
composer require --dev phpstan/phpstan

インストールが成功することを確認する。

phpstan.neon (設定ファイル)の作成

プロジェクトのルートディレクトリに phpstan.neon (設定ファイル)を作成する。
以下、ファイルの中身

parameters:
    level: 5
    paths:
        - app

読み方:

  • level:
    • PHPStanの解析レベルを設定します。レベルは0から9まであり、数字が大きいほど厳密な解析を行います。
      • 多くのプロジェクトでは、レベル5から8が適していることが多いです。
        • レベル5: 基本的な型チェックと一般的なエラーの検出を行います。
        • レベル8: より高度な解析と厳密な型チェックを行います。
  • path:
    • 解析対象のディレクトリを指定します。
      • 今回の場合、app ディレクトリとその中のすべてのサブディレクトリが解析対象となります。
      • プロジェクトのルートディレクトリからの相対パスを記載します。

※その他のオプション

  • excludePaths:
    • 解析対象外とするディレクトリを指定します。
    • 例）以下の場合、app/hoge ディレクトリとその中のすべてのサブディレクトリが解析対象外となります。
parameters:
    paths:
        - app
    excludePaths:
        - app/hoge
  • ignoreErrors:
    • エラーの中で、無視するエラーを指定できます。
    • 正規表現で指定可能です。
    • 例）PHPDocと記載のあるエラーを無視する場合：
parameters:
    ignoreErrors:
        - '#PHPDoc*#'

スキャンの実行

以下コマンドでスキャンを実行します。

php ./vendor/bin/phpstan analyse
# 実行結果を出力したい場合
# php ./vendor/bin/phpstan analyse > phpstan_results.txt

成功した場合、エラーの詳細と件数が表示されます。

 [ERROR] Found XXX errors

前回保存時のスキャン結果がキャッシュに残ってしまう場合があります。
必要に応じて、以下のコマンドでキャッシュをクリアすることを推奨します。

php ./vendor/bin/phpstan clear-result-cache

Larastanの導入

Larastanのインストール

まず、Composerを使ってLarastanをインストールします。

composer require --dev larastan/larastan

※nunomaduro/larastanは廃止されました。もし誤ってインストールしてしまった場合は、以下のコマンドで削除してください。

composer remove nunomaduro/larastan

phpstan.neonを修正

phpstan.neonを以下のように修正します。

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

parameters:
    level: 5
    paths:
        - app
  • includes:
    • larastanの設定ファイルを取り込んでいます。
    • プロジェクトルートからの相対パスを記載します。

スキャンの実行

PHPStanのスキャンを実行します。
※LarastanはPHPStanの拡張機能なので、PHPStanのスキャンを実行すると同時に実行されます。

以下コマンドを実行します。

# キャッシュクリア
php ./vendor/bin/phpstan clear-result-cache
# スキャンの実行
php ./vendor/bin/phpstan analyse
# 実行結果を出力したい場合
# php ./vendor/bin/phpstan analyse > phpstan_results.txt

以下の点から、Larastanが実行されていることを確認できます:

  • ERRORの件数が増えること
  • エラーの詳細の出力に「larastan/larastan」の文言が含まれること

備考

  • 当初、vendorディレクトリをexcludePathsに指定していましたが、これによりOSSを参照する処理で’unknown class’エラーが発生し、スキャンが正常に行えませんでした。
    vendorディレクトリをexcludePathsから除外することで、この問題が解決しました。
parameters:
    excludePaths:
        - vendor

まとめ

PHPStanとLarastanは、コードの品質向上と潜在的な問題の早期発見に大きく貢献します。
ぜひプロジェクトへの導入を検討し、その効果を体感してみてください。

今後、運用を続ける中で新たな知見や改善点が見つかれば、随時共有していきます。

参考