技術資料

複数人でPHPやLaravelのコードを書いていると、インデント、配列の書き方、空行の入れ方など、動作には影響しない部分で書き方がばらつくことがあります。

Laravel Pintを使うと、PHPコードの書式を一定のルールに合わせて自動的に修正できます。ローカルではコードを修正し、CIでは書式違反だけを検査する、という使い分けも可能です。

この記事では、Laravel Pintの基本的な使い方と、どのような場合に導入するとよいかを短く整理します。GitHub ActionsのWorkflowそのものについては、GitHub ActionsでPHP・LaravelのCIを始める記事で説明しています。

Laravel Pintとは

Laravel Pintは、Laravelの書式に沿ってPHPコードを整形するためのツールです。Laravelの公式ドキュメントでは、PintはPHP CS Fixerをベースにしたコードスタイル修正ツールと説明されています。

書式をそろえると、コードレビューでインデントや改行だけを指摘する必要が減ります。変更内容に関係する差分へ集中しやすくなることが、Pintを導入する主な効果です。

ただし、Pintが確認するのは主にコードの書式です。アプリケーションが正しく動くか、型や設計に問題がないか、仕様を満たしているかまでは確認しません。

それぞれ確認対象が異なるため、Pintが成功したからといって、テストや静的解析も十分だとは判断できません。

Pintを利用できる状態にする

新しいLaravelアプリケーションには、Pintが含まれていることがあります。まずはプロジェクトのvendor/binにPintがあるか確認します。

./vendor/bin/pint

古いLaravelアプリケーションなど、Pintが含まれていないプロジェクトでは、Composerで開発用の依存関係へ追加します。

composer require laravel/pint --dev

プロジェクトごとにPintのバージョンやPHPの要件が異なるため、実行前にcomposer.jsonやcomposer.lockの内容を確認しましょう。グローバルにインストールしたツールではなく、プロジェクトのvendor/bin/pintを使うと、開発者間やCIで同じ依存関係を使いやすくなります。

ローカルで書式を修正する

引数を付けずに実行すると、Pintが対象のPHPファイルを確認し、書式に問題があるファイルを修正します。

./vendor/bin/pint

プロジェクト全体ではなく、特定のディレクトリやファイルだけを対象にすることもできます。

./vendor/bin/pint app/Models
./vendor/bin/pint app/Models/User.php

実行後は、修正された内容をGitの差分で確認します。Pintが変更したからといって、その差分を確認せずにコミットするのではなく、意図しない変更がないかを見ておきましょう。

git diff

変更内容を詳しく表示したい場合は、-vを付けて実行します。

./vendor/bin/pint -v

CIでは書式違反だけを検査する

CIでPintを実行するときは、実行環境のファイルを書き換えるのではなく、書式違反があるかだけを検査する構成にします。

./vendor/bin/pint --test

--testを付けると、Pintはファイルを修正せずに検査します。書式違反が見つかった場合は、成功ではない終了コードを返すため、CIのステップも失敗として扱えます。

この場合、ローカルで次のコマンドを実行して書式を修正し、差分を確認してから再度--testを実行します。

./vendor/bin/pint
./vendor/bin/pint --test

GitHub Actionsでは、Workflowの一つのステップとして次のように記述できます。

- name: Check PHP code style
  run: ./vendor/bin/pint --test

CIのイベント、Runner、Composer、PHPUnitなどの説明は、プロジェクトのCI構成と合わせて考える必要があります。Pintだけを参照したい場合は、まずこのステップの意味を押さえておけば十分です。

対象範囲を絞って実行する

Pintには、対象範囲を絞るためのオプションもあります。例えば、Gitの指定ブランチとの差分にあるファイルを対象にする場合は、--diffを使います。

./vendor/bin/pint --diff=main

未コミットの変更があるファイルだけを対象にする場合は、--dirtyを使います。

./vendor/bin/pint --dirty

既存プロジェクトへPintを導入すると、これまでのコード全体が修正対象になることがあります。最初から全ファイルを修正すると大きな差分になりやすいため、場合によっては、対象ディレクトリ、変更したファイル、差分のあるファイルなどに分けて、段階的に導入する方法も検討が必要かもしれません。

--diffや--dirtyを検査用途で使う場合の組み合わせや挙動は、利用しているPintのバージョンで確認してください。オプションの意味を確認せずにCIへ組み込むと、想定より広い範囲や狭い範囲しか検査していない可能性があります。

設定を変更する

Pintは、標準のLaravelプリセットを使うだけであれば、設定ファイルを作らずに利用できます。プロジェクト固有のルールを設定したい場合は、プロジェクトのルートディレクトリへpint.jsonを作成します。

{
    "preset": "laravel",
    "rules": {
        "simplified_null_return": true
    },
    "exclude": [
        "app/Generated"
    ]
}

presetは、複数の書式ルールをまとめた設定です。rulesでは個別のルールを有効または無効にでき、excludeでは対象から外すディレクトリを指定できます。

pint.jsonの設定項目について詳しくは、Laravel Pint公式ドキュメントのConfiguring Pint、Presets、Rules、Excluding Files / Foldersを参照してください。個別のルールを探す場合は、PintのベースになっているPHP CS Fixer Configuratorも利用できます。

設定を変更すると、既存コードの修正量や、チーム内で確認する差分の内容も変わります。ルールを増やすときは、何のために変更するのかを共有し、Pintの実行結果を確認してから採用します。

Bladeファイルの扱いに注意する

Pintは、標準ではBladeテンプレートを整形しません。.blade.phpも対象にしたい場合は、現在の実行だけ--bladeを付ける方法があります。

./vendor/bin/pint --blade

--bladeによる整形では、Node.jsが必要です。Bladeも整形対象にする場合は、PHPコードだけを対象にする場合と前提が変わるため、Pintの対象バージョンの公式ドキュメントを確認します。

Bladeの整形を常に有効にする場合は、pint.jsonでルールを設定する方法もあります。ただし、既存テンプレートへ一度に適用すると大きな差分になる可能性があるため、対象を限定して結果を確認する方が安全です。

Laravel Pintを導入するか判断する

Pintは、次のようなプロジェクトで導入しやすいと思います。

• 複数人でPHPコードを変更している
• コードレビューで書式に関する指摘が繰り返し発生している
• Pull Requestごとに同じ書式を確認したい
• 新しく追加するコードの書き方をそろえたい

一方、既存コードへ導入するときは、最初に全ファイルを自動修正するかどうかを決める必要があります。書式修正だけの差分と機能変更の差分が混ざると、レビューや不具合の切り分けが難しくなるためです。

例えば、最初の段階では新しく変更するファイルだけを対象にし、Pintのルールと差分量を確認します。その後、チームで合意できた段階で対象範囲を広げる方法があります。

また、Pintはテストの代わりにはなりません。Pintで書式を整えた後も、PHPUnitなどのテスト、必要に応じた静的解析、手動での動作確認をそれぞれ行います。

まとめ

Laravel Pintは、PHPコードの書式をLaravelのルールに合わせて修正・検査するためのツールです。

ローカルで書式を修正するときは./vendor/bin/pintを使い、修正後の差分を確認します。CIやPull Requestで書式違反だけを確認するときは、./vendor/bin/pint --testを使います。

pint.jsonでルールや対象範囲を設定できますが、既存コードへ導入する場合は大きな差分にならないよう、対象を分けて進めることも大切です。Pintの対象バージョン、Bladeの扱い、使用するオプションを確認したうえで、プロジェクトの運用へ組み込みましょう。

参考資料

• Laravel Pint公式ドキュメント
• laravel/pint - GitHub
• GitHub ActionsでPHP・LaravelのCIを始める：テスト・Lint・ビルドを自動化するWorkflowの基本