Laravel Pintの使い方｜インストールから設定・CI連携まで

複数人でLaravelプロジェクトを開発していると、インデントの乱れや引用符（シングル/ダブル）の使い方、余分な空行など、コードスタイルの微妙な違いがコードレビューの手間を増やしてしまいます。「Laravel Pint」は、こうしたコードスタイルの指摘や修正を自動化してくれるLaravel公式のコードスタイル修正ツールです。本記事では、Laravel Pintの導入方法から基本コマンド、よく使う実行オプション、pint.jsonによるカスタマイズ、GitHub ActionsによるCI連携、エディタ連携や実務導入時のTipsまで、実機検証を交えて詳しく解説します。

Laravel Pintとは？特徴とツールの位置づけ
1. PHP-CS-Fixerとの関係とゼロ構成の思想
2. 静的解析ツール（Larastan/PHPStan）との役割分担
Laravel Pintの導入と対応バージョン
基本的な使い方とコード整形の実行例
1. プロジェクト全体の整形とパス指定
2. 実際のビフォー・アフター検証
実務で役立つコマンドラインオプション
pint.jsonによるカスタマイズ設定
プリセットの種類と選択指針
1. 利用可能な5つのプリセット比較
2. プリセットの切り替え方法
CI（GitHub Actions）への組み込み実践
1. パターン1: プルリクエスト時のコードスタイル検証（マージブロック）
2. パターン2: push時の自動整形とコミット
ローカル開発をさらに快適にする便利テクニック
実務導入時の注意点とTips
よくある質問（FAQ）
まとめ
関連記事

Laravel Pintとは？特徴とツールの位置づけ

Laravel Pint（ピント）は、Laravelチームが公式に提供しているPHP向けのコードスタイル自動整形ツール（フォーマッター）です。内部的には実績のあるPHP CS Fixerをベースに構築されており、複雑な設定ファイルを用意しなくても、Laravel公式のコーディング規約に沿ったスタイルへコマンド一発で自動整形してくれます。

PHP-CS-Fixerとの関係とゼロ構成の思想

従来のPHP CS Fixerでは、詳細な設定を行うために.php-cs-fixer.phpという複雑なPHPスクリプトを書く必要がありました。これに対しLaravel Pintは「ゼロ構成（Zero-configuration）」を掲げており、デフォルトのままでLaravelプロジェクトに最適なルールセットが適用されます。チーム全員が同じコマンドを実行するだけで、コードスタイルの議論やレビューの指摘にかかる時間を大幅に削減できます。

静的解析ツール（Larastan/PHPStan）との役割分担

Laravel Pintを導入する際によく混同されるのが、PHPStanやLarastanといった静的解析ツールとの違いです。両者は役割が明確に異なります。

ツール	主な役割	実行内容の例
Laravel Pint	コードスタイル（見た目・構文）の統一・自動整形	インデント調整、不要な空白削除、配列構文の統一、クォートの統一など
Larastan / PHPStan	静的解析（バグ検知・型チェック）	未定義変数の参照、型不整合、呼び出し不可なメソッドの検知など

Pintは「見た目を整えるツール」であり、ロジックのバグや型の誤りを検知する機能はありません。そのため、Pintによるコード整形とLarastanによる静的解析を組み合わせてCIパイプラインを構築するのが、現代のLaravel開発におけるベストプラクティスです。

Laravel Pintの導入と対応バージョン

Laravel Pintを利用するための動作環境と導入手順について確認します。

Laravel 9以降は標準搭載（新規インストール不要）

Laravel 9以降（Laravel 10、Laravel 11、Laravel 12を含む）でlaravel newコマンドまたはcomposer create-projectから作成した新規プロジェクトには、Laravel Pintが最初からrequire-devに含まれています。

プロジェクトのcomposer.jsonを確認すると、最初から以下のように記述されています。

"require-dev": {
    "laravel/pint": "^1.20"
}

このため、最新のLaravel環境であれば追加のインストール作業は不要で、そのまま./vendor/bin/pintを実行できます。

既存プロジェクトやLaravel 8以前へのインストール手順

既存のプロジェクトや、Pintが含まれていない環境に導入する場合は、Composerを使って開発依存（--dev）としてインストールします。

composer require laravel/pint --dev

※ Laravel Pintを実行するには、PHP 8.1以上が必要です。古いPHP環境を使用している場合は、PHP自体のバージョンアップを行ってください。

プロジェクトの基本的な依存関係セットアップについては、初心者向け：Laravelでcomposer installを成功させるための完全ガイドも参考にしてください。

Laravel Sail環境での実行方法

Docker開発環境であるLaravel Sailを利用している場合は、Sail経由でPintを実行します。

# Sail経由での実行
./vendor/bin/sail bin pint

# またはエイリアスを設定している場合
sail bin pint

Sailの導入手順や便利コマンドについては、Laravel Sailとは？インストールから開発環境構築・便利コマンドまで徹底解説で詳しく解説しています。

基本的な使い方とコード整形の実行例

Laravel Pintの実行は非常にシンプルです。

プロジェクト全体の整形とパス指定

プロジェクトルートで次のコマンドを実行すると、vendorディレクトリを除くプロジェクト配下の全PHPファイルが検査され、スタイル違反が自動修正されます。

./vendor/bin/pint

特定のディレクトリやファイルだけをピンポイントで整形したい場合は、引数に対象パスを指定します。

# 特定のディレクトリ配下のみ整形
./vendor/bin/pint app/Http/Controllers

# 単一ファイルのみ整形
./vendor/bin/pint app/Models/User.php

実際のビフォー・アフター検証

実際にインデントや記法が崩れたPHPコードを用意し、Pintを実行した際の変化を確認してみましょう。

【整形前（Before）】

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
  public $name;
  function __construct(array $attributes = [])
  {
      parent::__construct($attributes);
      $this->name=$attributes['name'] ?? null;
  }

    public function  greet() {
        if($this->name == null){
            return "Guest";
        }
        else{
        return "Hello, ".$this->name;
        }
    }
}

【整形後（After）】

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    public $name;

    public function __construct(array $attributes = [])
    {
        parent::__construct($attributes);
        $this->name = $attributes['name'] ?? null;
    }

    public function greet()
    {
        if ($this->name == null) {
            return 'Guest';
        } else {
            return 'Hello, '.$this->name;
        }
    }
}

Pintを実行するだけで、以下の修正が一瞬で自動適用されました。

インデント（スペース4個）の統一
functionへのアクセス修飾子（public）の自動補完
代入演算子（=）周辺の適切なスペース挿入
波括弧（{）の配置位置（PSR-12/Laravel準拠の改行）
elseのインデントと空白の整合性調整
単純な文字列リテラルのシングルクォートへの統一

実務で役立つコマンドラインオプション

Laravel Pintには、日々の開発やCIパイプラインで重宝する強力なコマンドラインオプションが揃っています。

オプション一覧表

オプション	説明	主なユースケース
`--test`	ファイルを変更せず、規約違反があるか検査のみ行う（違反があれば終了ステータス1）	CIパイプラインでのマージ前チェック
`-v` / `-vv` / `-vvv`	詳細ログを出力（修正されたファイル名や適用ルール、差分を表示）	何がどう修正されたかを細かく確認したい時
`--dirty`	Gitで未コミットの変更・新規追加ファイルのみを対象にする	ローカル作業中の素早いコミット前チェック
`--diff=<branch>`	指定ブランチ（例: `main`）との差分ファイルのみを対象にする	プルリクエスト対象の差分ファイルのみ検査するCI
`--repair`	ファイルを自動修正しつつ、修正が発生した場合は終了ステータス1を返す	CI上で自動修正と通知を兼ねる場合
`--parallel`	複数プロセスで並列実行し、処理時間を大幅に短縮する	大規模コードベースでの高速化
`--config <file>`	指定した設定ファイル（JSON）を読み込んで実行する	環境別に設定を分けたい場合

–test（CIや事前チェック用）

--testオプションを付けると、ファイルの書き換えを行わずにスタイル違反の有無を検査します。スタイル違反が1件でもあれば非ゼロ（終了コード1）で終了するため、CIでの合否判定に最適です。

./vendor/bin/pint --test

–dirty（未コミットの変更ファイルのみ対象）

--dirtyオプションを使用すると、Gitで追跡されている未コミットの変更ファイル（staged/unstaged）および新規作成ファイルのみが整形対象になります。プロジェクト全体をスキャンしないため、作業中のコードだけを素早く整形したい場合に非常に便利です。

./vendor/bin/pint --dirty

–diff（特定ブランチとの差分のみ対象）

--diffオプションは、指定したブランチ（例: mainやorigin/main）から分岐した後に変更されたファイルだけを対象にします。

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

既存のレガシーコードに未整形の箇所が大量に残っている場合でも、自分が新しく作成・変更したファイルだけをCIで厳密にチェックできるため、段階的なPint導入に欠かせないオプションです。

–repair と –parallel（高速化・並列実行）

大規模なプロジェクトで数十万行以上のコードがある場合、--parallelオプションを指定することで、CPUコアをフル活用して並列処理し、実行時間を劇的に短縮できます。

./vendor/bin/pint --parallel --max-processes=4

pint.jsonによるカスタマイズ設定

Pintは設定なしでも動作しますが、プロジェクトのルートディレクトリにpint.jsonを作成することで、チーム固有のコーディング規約に合わせた細かいルール調整が可能です。

基本構造と主要設定キー

pint.jsonはシンプルなJSON形式で記述します。主に以下のキーを指定できます。

{
    "preset": "laravel",
    "exclude": [
        "storage",
        "bootstrap/cache",
        "nova"
    ],
    "notName": [
        "*.blade.php"
    ],
    "notPath": [
        "app/Legacy/OldService.php"
    ],
    "rules": {
        "declare_strict_types": true,
        "blank_line_before_statement": {
            "statements": ["return", "throw", "try"]
        },
        "no_unused_imports": true
    }
}

実務でよく使われるルールのカスタマイズ例

rulesオブジェクトには、PHP CS Fixerで定義されている数百種類のルールを指定できます。実務で特によく使われるカスタマイズ例をいくつか紹介します。

1. 厳格な型宣言（declare(strict_types=1);）を強制する

{
    "rules": {
        "declare_strict_types": true
    }
}

すべてのPHPファイルの先頭に<?php declare(strict_types=1);が自動挿入されます。型の安全性を高めたい現代的なプロジェクトにおすすめです。

2. return文の前に空行を空ける

{
    "rules": {
        "blank_line_before_statement": {
            "statements": ["return", "try", "throw"]
        }
    }
}

処理の終了や例外スローの直前に空行を挟むことで、コードの視認性が向上します。

3. 配列構文を短縮形（[]）に統一する

{
    "rules": {
        "array_syntax": {
            "syntax": "short"
        }
    }
}

ディレクトリやファイルを除外する方法（exclude / notName / notPath）

外部パッケージのソースコードや自動生成ファイルなど、整形対象から除外したい対象がある場合は除外設定を使用します。

exclude: 特定のディレクトリ配下を丸ごと除外（例: "storage", "database/migrations"）
notName: 特定のファイル名パターンを除外（例: "*.blade.php", "*Custom.php"）
notPath: 特定のファイルパスを除外（例: "app/Legacy/Unformatted.php"）

プリセットの種類と選択指針

Laravel Pintには、ベースとなるコーディング標準を定めたプリセットが用意されています。

利用可能な5つのプリセット比較

プリセット名	準拠している標準・特徴	推奨ケース
`laravel`（デフォルト）	Laravel公式が採用しているスタイル。一般的なLaravelアプリに最適	通常のLaravelプロジェクト全般
`per`	PHP-FIGが策定した最新のコーディング規約「PER Coding Style」に準拠	最新のPHP標準スタイルに合わせたい場合
`psr12`	PHP-FIG策定の「PSR-12」標準規約に準拠	他フレームワークからの移行や汎用PHPライブラリ
`symfony`	Symfonyプロジェクトの公式スタイルに準拠	Symfonyベースのコンポーネントを多く扱う場合
`empty`	全ルールが無効な白紙状態。`rules`で1つずつ指定して独自の規約を構築	社内独自の完全カスタムルールを作成したい場合

プリセットの切り替え方法

プリセットを切り替えるには、pint.jsonの"preset"フィールドに指定するか、実行時に--presetオプションを渡します。

# コマンドラインで一時的にPSR-12を適用
./vendor/bin/pint --preset psr12

プロジェクト全体のコーディング規約の考え方については、Laravelコーディング規約の徹底解説：ベストプラクティスで効率的な開発を実現もあわせてご覧ください。

CI（GitHub Actions）への組み込み実践

チーム開発でコードスタイルの品質を維持するには、CI（継続的インテグレーション）での自動チェックが不可欠です。GitHub Actionsを使った2つの実践パターンを紹介します。

パターン1: プルリクエスト時のコードスタイル検証（マージブロック）

最も推奨される構成です。プルリクエストが作成された際にpint --testを実行し、未整形のファイルが含まれている場合はCIを失敗させてマージをブロックします。

.github/workflows/pint.yml を以下のように作成します。

name: Code Style Check

on:
  pull_request:
    branches: [ "main", "develop" ]
  push:
    branches: [ "main" ]

jobs:
  pint:
    name: Run Laravel Pint
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
          tools: pint

      - name: Run Pint Check
        run: pint --test

パターン2: push時の自動整形とコミット

開発者が手動でPintを実行し忘れてpushした場合でも、GitHub Actions側でPintを実行して自動で修正コミットをpushさせる構成です。

name: Auto Fix Code Style

on:
  push:
    branches-ignore: [ "main" ]

jobs:
  pint-fix:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
          tools: pint

      - name: Run Pint Auto-Fix
        run: pint

      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "style: fix code style with Laravel Pint"

テスト自動化やCI構築全体の流れについては、Laravelテストの基礎から実践的な自動化までを徹底解説も参考にしてください。

ローカル開発をさらに快適にする便利テクニック

Pintを日常の開発フローに無理なく組み込むための3つのテクニックを紹介します。

Composer scriptsへのコマンド登録

composer.jsonのscriptsセクションにPintのコマンドを登録しておくと、長いパスを入力せずにcomposer lintやcomposer formatなどの短いコマンドで実行できるようになります。

{
    "scripts": {
        "format": "pint",
        "lint": "pint --test",
        "test:all": [
            "@php artisan test",
            "@php vendor/bin/phpstan analyse",
            "@php vendor/bin/pint --test"
        ]
    }
}

これで、composer formatを実行するだけでコード整形が実行されます。

Git Pre-commit Hookによるコミット前自動整形

Gitのpre-commitフックを設定しておけば、コミットを実行した瞬間にステージングされた差分ファイル（--dirty）に対してPintが自動実行され、未整形のコードがコミットされるのを防ぐことができます。

.git/hooks/pre-commit に以下を記述して実行権限を付与します（chmod +x .git/hooks/pre-commit）。

#!/bin/sh
./vendor/bin/pint --dirty --test
if [ $? -ne 0 ]; then
    echo "❌ コードスタイル違反があります。'./vendor/bin/pint --dirty' を実行して修正してください。"
    exit 1
fi

エディタ連携（VS Code / PhpStorm）での保存時自動整形

ファイルの保存時（Ctrl+S / Cmd+S）に自動でPintを実行するようにエディタを設定しておくと、コマンドを手動で叩く必要すらなくなります。

VS Code: 拡張機能「Laravel Pint」（オープンソース）をインストールし、settings.jsonで以下を指定します。
```
"[php]": {
    "editor.defaultFormatter": "open-southeners.laravel-pint",
    "editor.formatOnSave": true
}
```
PhpStorm: 「Settings > PHP > Quality Tools > Pint」でPintの実行可能ファイル（vendor/bin/pint）を指定し、「Actions on Save」で「Reformat code」を有効にします。

実務導入時の注意点とTips

大規模既存コードへの一括適用と.git-blame-ignore-revsの活用

稼働中のプロジェクトに初めてPintを導入して全ファイルを一括整形すると、すべての行の変更履歴がPintのコミットに置き換わってしまい、git blameで過去の修正者やコミット理由が追えなくなるという深刻な問題が生じます。

これを回避するために、Gitの.git-blame-ignore-revs機能を使用します。

Pintでプロジェクト全体を一括整形し、専用のコミットを作成します。
```
git commit -m "style: apply Laravel Pint to whole project"
```
そのコミットのハッシュ値（例: abc123456...）を取得し、プロジェクトルートの.git-blame-ignore-revsファイルに追記します。
```
# Laravel Pint一括フォーマットコミットを除外
abc1234567890abcdef1234567890abcdef123456
```
ローカルでこのファイルを無視リストとして認識させます。
```
git config blame.ignoreRevsFile .git-blame-ignore-revs
```

GitHubなどの主要なリポジトリサービスも.git-blame-ignore-revsに標準対応しているため、Web上のBlame表示でもフォーマットコミットを自動的にスキップして本来のコミット履歴を確認できます。

チーム開発でのバージョン固定（composer.lock）

Pintのマイナーアップデートによって新しい整形ルールが追加されると、メンバー間でPintのバージョン差が生じた際に整形結果の競合が発生することがあります。必ずcomposer.lockをバージョン管理に含め、チーム全員が同一バージョンのPintを使用するようにしてください。

Bladeテンプレート（.blade.php）の扱い

Laravel Pintは.phpで終わるファイルを対象とするため、デフォルトで.blade.phpファイルも検査対象に含まれます。ただし、Bladeの独自ディレクティブ（@ifや@foreachなど）が混在していると意図しない改行やインデント崩れが起こるケースがあります。

BladeファイルをPintの対象外にしたい場合は、pint.jsonに以下を追加します。

{
    "notName": [
        "*.blade.php"
    ]
}

よくある質問（FAQ）

Q: Laravel Pintを実行しても整形されないファイルがあるのはなぜ？

pint.jsonのexcludeやnotPath、notNameで除外設定されていないか確認してください。また、.blade.php以外の非PHPファイル（JavaScriptやCSS）はPintの対象外です。

Q: PHP CS Fixerのカスタムルールをすべて指定できますか？

はい。PHP CS Fixerで提供されている標準ルールは、pint.jsonのrulesにルール名とパラメータを指定することでそのまま使用できます。

Q: Pintを実行するとCIで差分が発生して失敗する場合は？

開発者のローカル環境でcomposer installが実行されておらず、古いバージョンのPintで整形した状態でpushされている可能性があります。最新の依存関係をインストールしてから再度./vendor/bin/pintを実行してください。

まとめ

Laravel Pintは、インストールから実行まで余計な設定を必要とせず、誰でも手軽に高品質なコードスタイルを維持できる強力な公式ツールです。

ゼロ構成: Laravel 9以降なら導入作業なしですぐに利用可能
柔軟な実行オプション: --test（CI用）、--dirty（ローカル用）、--diff（PR差分用）で段階的導入もスムーズ
pint.jsonによるカスタマイズ: プリセット選択や除外設定、厳格な型宣言の強制などを柔軟に制御
自動化の推進: GitHub Actions、Composer scripts、エディタ保存時自動整形と組み合わせることで開発効率を最大化

コードスタイルの議論やレビューの手間をゼロにし、本来のビジネスロジックの実装に集中するために、ぜひプロジェクトへLaravel Pintを取り入れてみてください。