Laravel9でLarastan + Laravel Pintを使ってみる

はじめに

この記事はLarastanとLaravel Pintの設定方法や使い方について書いています。

以下を参考にしています。

対象者

Larastan、Laravel Pintについて知りたい方、Laravelプロジェクトで使用するLinter、Formatterを検討中の方を対象としています。

また、Laravel9の環境構築ができている前提で進めます。

記事の流れ

Larastanについて
larastanとは
1.インストール
2.設定ファイルを作成編集
3.静的解析を実行

Laravel Pintについて
Laravel Pintとは
1.インストール
2.Laravel Pint実行
3.ルールを追加する

環境

• Laravel：9.24.0
• PHP：8.1.13

Larastanとは

Larastanは静的解析ツールでPHPStanのラッパーです。
デフォルトでLaravel用の固有ルールが定義されていて、複雑な設定などせずに使えます。

Laravelの固有ルールについては下記に記載されています。

早速導入手順を説明していきます。

1. インストール

まずはインストールします。
Laravelは9.0以上、PHPは8.0以上である必要があります。

composer require nunomaduro/larastan:^2.0 --dev

2. 設定ファイルを作成・編集

Laravelのルートディレクトリにphpstan.neonというファイルを作成し、編集します。

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

parameters内にある各パラメータについて説明していきますが、pathsとlevel以外は頭の片隅に入れて置く程度で良いと思います。

paths

解析する範囲を指定するためのパラメータです。
app/配下のファイルを解析したい場合は下記のようにします。

phpstan.neon

paths:
    - app/

level

適用するルールを設定するためパラメータです。
設定できるlevelは0〜9まであり、数字が大きくなるほどルールが厳しくなります。
チームでコードの書き方を合わせたいくらいなら、あまり厳しくしないでも良いと思います。

各levelごとのルールについて詳しく知りたい方は下記を確認してみてください。

ignoreErrors

解析した際、特定のエラーを発生させたくない場合に使用するパラメータです。
例えばMethod Foo\Bar::baz() should return Illuminate\Http\Response but return statement is missing.のようなエラーが発生した場合には下記のように正規表現を利用してエラーを除外できます。

phpstan.neon

ignoreErrors:
    - '#Method [a-zA-Z0-9\\:()]* should return Illuminate\\Http\\Response but return statement is missing\.#'

また、パスを指定して、特定のディレクトリやファイルのみエラーを除外することもできます。

phpstan.neon

ignoreErrors:
    -
        message: '#Method [a-zA-Z0-9\\:()]* should return Illuminate\\Http\\Response but return statement is missing\.#'
        path: Foo\Bar

excludePaths

解析から除外するディレクトリ、ファイルを設定するためのパラメータです。
例えばControllers配下を除外するには下記のように指定します。

phpstan.neon

parameters:
    excludePaths:
        - app/Http/Controllers

checkMissingIterableValueType

曖昧な型宣言を許容する際に使用するパラメータです。
levelを5以下に設定している場合は型宣言のエラーは発生しないので触る必要はありません。

下記のように設定します。

phpstan.neon

parameters:
    checkMissingIterableValueType: false

ちなみに曖昧な型宣言ですが、下記の1つ目例のように配列内の値の型が宣言されていない状態のことを指します。

配列内の値の型が不明確で曖昧な型宣言になっている

function foo(array $bar) {
    //
}

配列内の値の型が明確で具体的な型宣言になっている

/**
* @param array{ num: int } $bar
*/
function foo(array $bar) {
    //
}

3. 静的解析を実行

ルートディレクトリで下記コマンドを実行します。

./vendor/bin/phpstan analyse

このままだとコマンドが長いのでエイリアスをつけるといいと思います。
設定方法ですが、composer.jsonファイルのscripts内に下記のようにコードを追加します。

composer.json

"scripts": {
    "lint": [
        "./vendor/bin/phpstan analyse"
    ]
}

下記コマンドで実行できるようになります。

composer lint

これでLarastanの設定は完了です。

Laravel Pintとは

PHP-CS-Fixerのラッパーでコードのスタイルを整えてくれるLaravel用のFormatterです。

導入がとても簡単で、インストールするだけで使えてしまいます。
また、設定ファイルを作成してルールを追加することもできるので、細かいカスタマイズも可能です。

導入手順を書いていきます。

1. インストール

まずはインストールします。

composer require laravel/pint --dev

2. Laravel Pint実行

実行します。

./vendor/bin/pint

これだけです。
拍子抜けするくらい簡単ですね。

こちらもLarastanと同様にエイリアスを付けるとスマートでいいと思います。

composer.json

"scripts": {
    "fix": [
        "./vendor/bin/pint"
    ]
}

再度実行して見てください。

composer fix

3. ルールを追加する

Laravel Pintでは専用のファイルを作成し、ルールを追加することもできます。
ルートディレクトリにpint.jsonファイルを作成し、下記のように編集します。

pint.json

{
  "rules": {
      "method_chaining_indentation": true
  }
}

上記のルールはメソッドチェーンのインデントを揃えるためのものです。

ルールが適用されているか確認するために下記のようなコードを書いてみてください。

<?php
$user = User::where('age', '>=', '18')
        ->get();

Laravel Pintを実行します。

composer fix

下記のようにインデントが入ります。

<?php
$user = User::where('age', '>=', '18')
            ->get(); // インデントが入る

他にも色々なルールがありますので気になるものを試してみてください。

最後に

ここまで見ていただき、ありがとうございました。
LarastanとLaravel Pintは導入が簡単でLaravelのためのルールが元から設定されているため、Laravelを使用するプロジェクトでは候補になりやすいのではないかと思います。

実際に私が技術選定した際も他のライブラリと比較して導入コスト低いこと、元からLaravel用のルールが設定されている点に魅力を感じて採用しました。
Laravelプロジェクトでどのライブラリを使おうか迷っている方はぜひ使ってみてください。

参考