Laravelプロジェクトに静的解析ツール(Larastan)を導入

## 1. はじめに

Laravelプロジェクトにおいて、コードの品質管理は何をしていますか？
大抵のプロジェクトではコードレビューで品質の担保をしていると思いますが、
設計・コーディングに集中できるように、少しでもレビュー時間を減らしたいですよね。

また、型の定義やPHPDocなどのミスは指摘しやすい分、
ほかのエラーハンドリングなど保守性の観点を見逃してしまうこともあると思います。

静的解析ツールを導入することで、そういった機械的な観点を事前に検出し、
レビュー時にはプロジェクトにおいて必要な観点のチェックに集中することができるようになるはずです。

本記事では、Laravelの静的解析ツールである**Larastan**についてご紹介します。

## 2. 対象読者

- Laravelを用いた開発経験がある方
- 静的解析ツールについて学びたい方

## 3. 目次
- [1. はじめに](#1-はじめに)
- [2. 対象読者](#2-対象読者)
- [3. 目次](#3-目次)
- [4. 環境](#4-環境)
- [5. 本編](#5-本編)
  - [5.1 Larastanとは](#51-larastanとは)
  - [5.2 Larastanのインストール](#52-larastanのインストール)
  - [5.3 設定ファイルの作成](#53-設定ファイルの作成)
  - [5.4 静的解析の実行](#54-静的解析の実行)
  - [5.5 設定のカスタマイズ](#55-設定のカスタマイズ)
  - [5.6 Github Actionsでの利用](#56-github-actionsでの利用)
- [6. さいごに](#6-さいごに)
- [7. 参考サイト](#7-参考サイト)

## 4. 環境

- PHP 8.2
- Laravel 9.19
- Larastan 2.6

## 5. 本編

### 5.1 Larastanとは

**Larastan**とは、Laravelに特化した静的解析ツールです。
LarastanはPHPの静的解析ツールである**PHPStan**をベースにしており、Laravelのコードに特化したルールを追加しています。

Larastanではコード内のエラー検出に重点を置いており、コードの品質を向上させるためのツールとして活用することができます。

### 5.2 Larastanのインストール

まずLarastanをプロジェクトにインストールします。Composerを使用して、以下のコマンドを実行します。

```bash
$ composer require --dev "larastan/larastan:^2.0"
```

**※2025.3.13追記**
`$ composer require nunomaduro/larastan:^2.0 --dev`は非推奨になりました。
[こちら](https://qiita.com/Zucky2022/items/861dabe5e3c8e372b234)の記事を参照ください。

※Larastan2.xを使用する場合、下記条件を満たしている必要があります。
- PHP 8.0以上
- Laravel 9.0以上

### 5.3 設定ファイルの作成

次に、プロジェクトルートに`phpstan.neon`ファイルを作成します。

```conf:phpstan.neon
includes:
    - ./vendor/nunomaduro/larastan/extension.neon

parameters:

    paths:
        - app/

    # Level 9 is the highest level
    level: 5

#    ignoreErrors:
#        - '#PHPDoc tag @var#'
#
#    excludePaths:
#        - ./*/*/FileToBeExcluded.php
#
#    checkMissingIterableValueType: false
```

利用可能なオプションについては、PHPStanのドキュメントを参照してください。

 https://phpstan.org/config-reference

### 5.4 静的解析の実行

最後に、phpstanコマンドを実行します。
Larastanはプロジェクトのコードを解析し、コード内のエラーや問題点を探し出します。解析結果はターミナルに出力され、具体的な問題点とその存在するファイル・行数が示されます。

```bash
$ ./vendor/bin/phpstan analyse

Note: Using configuration file /var/www/api/phpstan.neon.
 50/50 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

 [OK] No errors
```

エラーがなければこのような表示になります。


例えば、Userモデルに未定義のプロパティを参照している場合は下記のようなエラーが表示されます。

```bash
$ ./vendor/bin/phpstan analyse

Note: Using configuration file /var/www/api/phpstan.neon.
 50/50 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

 ------ --------------------------------------------------------------------------
  Line   Services/AuthService.php
 ------ --------------------------------------------------------------------------
  34     Access to an undefined property App\Models\User::$foge.
         💡 Learn more:
            https://phpstan.org/blog/solving-phpstan-access-to-undefined-property
 ------ --------------------------------------------------------------------------

  [ERROR] Found 1 error
```

### 5.5 設定のカスタマイズ

`phpstan.neon`を編集することで、様々な設定をカスタマイズすることができます。

ここでは、設定項目の１つである、解析の厳しさを設定するレベル(`level: x`)について説明します。

レベルは0から9まであり、数値が大きいほど厳しく解析を行います。レベルは累積的であり、例えば、レベル5を設定すると、レベル0からレベル5までのルールが適用されます。各レベルについての詳細は、次のサイトを参照してください。

https://phpstan.org/user-guide/rule-levels


### 5.6 Github Actionsでの利用

ここまでは、コマンドラインでの実行を紹介しましたが、最後にGithub Actionsでの利用方法を紹介します。

プロジェクトのルートに`.github/workflows/phpstan.yml`を作成します。

下記では、**push**イベントが発生した場合に、Larastanを実行するジョブを定義しています。そうすることで、コードをpushするたびにLarastanが実行され、コード内の問題点を検出することができ、未然にバグを防ぐことができます。

```yml:phpstan.yml
name: larastan job

on:
  push:

jobs:
  larastan:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout code
      uses: actions/checkout@v2

    - name: Set up PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: 8.2
        tools: composer:v2

    - name: Get Composer Cache Directory
      id: composer-cache
      run: echo "::set-output name=dir::$(composer config cache-files-dir)"

    - name: Cache Composer dependencies
      uses: actions/cache@v2
      with:
        path: ${{ steps.composer-cache.outputs.dir }}
        key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
        restore-keys: |
          ${{ runner.os }}-composer-

    - name: Install dependencies
      run: composer install --prefer-dist --no-progress

    - name: Run Larastan
      run: ./vendor/bin/phpstan analyse
```

## 6. さいごに

**Larastan**は、Laravelの開発において、コードの品質を向上させるための強力なツールです。コードの問題を早期に発見し、バグの予防やコードレビューの効率化に役立ててください！

## 7. 参考サイト

- [Larastan GitHub](https://github.com/nunomaduro/larastan)
- [LarastanでLaravelプロジェクトを静的解析しよう！ - Qiita](https://qiita.com/MasaKu/items/7ed6636a57fae12231e0)