複数人でLaravelプロジェクトを開発していると、インデントや引用符の使い方、余分な空白行など、コードスタイルの微妙な違いがコードレビューの手間を増やしてしまいます。「Laravel Pint」は、こうしたコードスタイルの指摘や修正を自動化してくれる公式ツールです。本記事では、Laravel Pintのインストール方法から基本コマンド、pint.jsonによるカスタマイズ、CIへの組み込みまで、実際にコマンドを実行して確認した内容をもとに解説します。
Laravel Pintとは
Laravel Pintは、Laravelチームが公式に提供するPHPのコードスタイル自動整形ツールです。内部的にはPHP CS Fixerを利用しており、複雑な設定をしなくても、Laravel流の意見が反映されたコーディングスタイルへ自動的に整形してくれます。ESLintやPrettierのPHP版・Laravel特化版とイメージすると分かりやすいでしょう。
Laravel Pintは「ミニマリスト向け」を掲げているとおり、設定ファイルなしでもすぐに使い始められる点が特徴です。チーム開発でのコードレビューからスタイルの指摘を減らし、レビュアーがロジックの妥当性に集中できるようになります。
インストール方法
Laravel 9以降でlaravel newコマンドから作成した新規プロジェクトには、Laravel Pintが最初からrequire-devに含まれています。実際に最新のLaravelスケルトンで確認したところ、composer.jsonにlaravel/pintが含まれ、追加のインストール作業なしでvendor/bin/pintが使える状態でした。
$ cat composer.json | grep pint
"laravel/pint": "^1.27",
$ ls vendor/bin/ | grep pint
pint
そのため、新規プロジェクトであればインストール手順は不要で、そのまま次章のコマンドを実行できます。既存の古いプロジェクトなど、laravel/pintがまだ含まれていない場合のみ、Composerで開発依存として追加します。
composer require laravel/pint --devプロジェクトの基本的なセットアップから見直したい場合は、初心者向け：Laravelでcomposer installを成功させるための完全ガイドもあわせて参考にしてください。
基本的な使い方
Pintの実行方法はシンプルです。プロジェクトルートで以下を実行すると、対象となる全PHPファイル（vendorディレクトリを除く）のコードスタイルを自動修正します。
./vendor/bin/pint特定のディレクトリやファイルだけを対象にすることもできます。
# ディレクトリ単位
./vendor/bin/pint app/Models
# ファイル単位
./vendor/bin/pint app/Models/User.php実際にコードを整形してみる
次のようなスタイルが乱れたモデルクラスを用意し、実際に./vendor/bin/pintを実行して挙動を検証しました。
整形前
<?php
namespace App\Models;
class User
{
public $name;
function __construct($name)
{
$this->name=$name;
}
public function greet() {
if($this->name == null){
return "Hello";
}
else{
return "Hello, ".$this->name;
}
}
}整形後（./vendor/bin/pint実行後）
<?php
namespace App\Models;
class User
{
public $name;
public function __construct($name)
{
$this->name = $name;
}
public function greet()
{
if ($this->name == null) {
return 'Hello';
} else {
return 'Hello, '.$this->name;
}
}
}インデントの統一、functionの可視性修飾子の補完（function → public function）、余分な空白の削除、ダブルクォートからシングルクォートへの統一、elseの位置調整などが、コマンド1回で自動的に適用されることが確認できました。
よく使うオプション
Pintには実行結果の確認やCI利用を想定したオプションが用意されています。実際に検証した動作は次のとおりです。
| オプション | 用途 |
|---|---|
--test |
ファイルを書き換えず、スタイル違反の有無だけを検査する。違反があれば終了コード1を返す |
-v |
修正した各ファイルと適用されたルール名を詳細に表示する |
--dirty |
Gitで未コミットの変更があるファイルだけを対象にする。新規追加した未追跡ファイルも対象に含まれる |
--diff=<branch> |
指定ブランチから分岐した後に変更・追加されたファイルだけを対象にする。CIでの差分チェックに有効 |
--repair |
スタイル違反を修正しつつ、修正が発生した場合は終了コード1を返す（CIで「直したが検知はしたい」場合に利用） |
--parallel |
複数プロセスで並列実行する（実験的機能）。--max-processes=4のようにプロセス数を指定可能 |
例えば、mainブランチから分岐した差分だけを検査する場合は次のように実行します。
./vendor/bin/pint --test --diff=main実際にmainブランチ作成後に1ファイルだけ追加してこのコマンドを実行したところ、追加したファイルのみが検査対象となり、それ以前から存在する未整形のファイルは対象外になることを確認しました。差分だけを見るCIのジョブや、大規模な既存プロジェクトへの段階的な導入に向いています。
pint.jsonによるカスタマイズ
Pintは設定不要で使い始められますが、プロジェクトのルートディレクトリにpint.jsonを置くことで、プリセットやルール、対象外ファイルを細かく制御できます。
{
"preset": "laravel",
"exclude": [
"storage",
"bootstrap/cache"
],
"notName": [
"*.blade.php"
],
"notPath": [
"app/Legacy/OldService.php"
],
"rules": {
"simplified_null_return": true,
"new_with_parentheses": false
}
}それぞれの項目の役割を実際に検証したところ、次のように機能しました。
- preset: ベースとなるルールセットを指定する
- rules: presetの一部ルールを個別に有効・無効化する。上書きしたルールだけがpresetの設定を上書きする
- exclude: 指定ディレクトリ配下を検査対象から除外する
- notName: 指定パターンに一致するファイル名を除外する
- notPath: 指定した個別ファイルを除外する
excludeで指定したディレクトリ配下のファイルと、notPathで指定した個別ファイルは、明らかなスタイル違反があっても検査自体がスキップされることを実際に確認しています。
プリセットの種類と選び方
Pintが現在サポートしているプリセットは次の5種類です。
| プリセット | 特徴 |
|---|---|
laravel（デフォルト） |
Laravel公式が採用しているスタイル。設定不要ならこのまま使うのが基本 |
per |
PHP-FIGが策定する「PER Coding Style」に準拠 |
psr12 |
PSR-12標準に準拠したスタイル |
symfony |
Symfonyプロジェクトのコーディングスタイルに準拠 |
empty |
ルールを一切適用しない状態から、rulesで自分だけのスタイルを組み立てる |
Laravelプロジェクトで特にこだわりがなければ、デフォルトのlaravelプリセットのままで問題ありません。他フレームワークからの移行でPSR-12やSymfony準拠のスタイルに慣れている場合は、--presetオプションやpint.jsonでプリセットを切り替えられます。
./vendor/bin/pint --preset psr12チーム全体のコーディング規約を整理する際は、Laravelコーディング規約の徹底解説：ベストプラクティスで効率的な開発を実現もあわせて確認し、Pintで自動化できる部分と、レビューで人が確認すべき部分を切り分けておくと運用がスムーズです。
CI（GitHub Actions）に組み込む
Pintはローカルでの実行だけでなく、CI上での自動チェック・自動整形にも組み込めます。GitHubの「Settings > Actions > General > Workflow permissions」で書き込み権限を許可したうえで、.github/workflows/lint.ymlを次のように作成します。
name: Fix Code Style
on: [push]
jobs:
lint:
runs-on: ubuntu-latest
strategy:
fail-fast: true
matrix:
php: [8.4]
steps:
- name: Checkout code
uses: actions/checkout@v5
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php }}
tools: pint
- name: Run Pint
run: pint
- name: Commit linted files
uses: stefanzweifel/git-auto-commit-action@v6
pushのたびにPintが自動実行され、スタイル違反があれば修正コミットが自動で追加されます。プルリクエスト単位で差分だけを検査したい場合は、前述の--diffオプションと組み合わせてpint --test --diff=mainのようにジョブを分けるとよいでしょう。
よくある質問
Laravel PintとPHP CS Fixerの違いは？
Laravel PintはPHP CS Fixerをベースに、Laravel向けの設定をあらかじめ組み込んだラッパーです。PHP CS Fixerの個別ルールもそのままpint.jsonのrulesに指定して利用できます。
Pintだけでコード品質は十分ですか？
Pintが担うのはスタイル（見た目）の統一のみで、バグの検出や型の整合性チェックは行いません。静的解析はPHPStanやLarastanなど別のツールと役割分担するのが一般的です。
Bladeファイルは対象になりますか？
Pintの検査対象は拡張子が.phpのファイルです。.blade.phpも対象に含まれるため、Blade内のPHPコードを触られたくない場合は、本記事で紹介したnotNameで除外できます。
まとめ
Laravel Pintは、新規プロジェクトであれば追加インストールなしで使い始められ、./vendor/bin/pintを実行するだけでコードスタイルを自動整形できるツールです。--testや--diff、--dirtyを使い分ければCIや大規模プロジェクトにも段階的に導入でき、pint.jsonでプリセットやルールを細かく調整することも可能です。まずはデフォルト設定のまま既存プロジェクトに--testを実行し、どの程度スタイルが揃っているかを確認するところから始めてみてください。
コメント