こんにちは！開発現場の裏側で、チーム全体の生産性を引き上げる仕組みづくりに奔走しているシニアエンジニアです。
日々のプルリクエストレビューで、こんな消耗をしたことはありませんか？
「あ、またこのレガシーな書き方をしている……」「ドキュメントに禁止って書いたのに、新メンバーがまた同じアンチパターンを踏んでいる……」
人間の目によるコードレビューには限界があります。そして、それを指摘する時間も、指摘される側のモチベーションも、プロジェクトにとっては貴重なコストの無駄遣いです。
今回は、世界最高峰のPHP向けIDEである PhpStorm の奥底に眠る機能――「Custom Inspection（カスタムインスペクション）」 を完全攻略します。チーム特有の「禁止したい書き方」をIDE自身に学習させ、コードを書いているまさにその瞬間に警告を出させる仕組みを構築しましょう。
これをマスターすれば、機械的な指摘はすべてIDEに任せられるようになり、あなたのチームのレビュー工数は劇的に削減されます。さあ、一緒に「自動で品質が担保される開発環境」を作っていきましょう！
—
1. なぜ「Custom Inspection」なのか？（ツールの役割と本質）
世の中には、PHPStanやPsalm、PHP_CodeSnifferといった優れた静的解析ツールが存在します。これらも素晴らしいものですが、「CI（継続的インテグレーション）が回ってエラーが出るまで、開発者が間違いに気づきにくい」というタイムラグがあります。
PhpStormのCustom Inspectionの本質は、「開発者のキーストロークの直後（リアルタイム）にフィードバックを与える」点にあります。
チーム開発における圧倒的なメリット
1. レビューの手間が消滅する: 「ここに `new` を直接書かないで、ファクトリーを使ってください」といった属人的な指摘を、マージ前に人間がやる必要がなくなります。
2. オンボードコストの激減: 新しくチームに参加したエンジニアが、初日から「IDEに怒られる通りに書くだけ」で、自然とプロジェクト独自のアーキテクチャルールを体得できます。
3. 「知らなかった」を防ぐ: ドキュメントの奥底に埋もれたコーディング規約は誰も読みませんが、目の前で赤く波線が引かれる警告は、嫌でも開発者の目に入ります。
—
2. 基礎セットアップ：PhpStormの「Structural Search and Replace」を理解する
PhpStormで独自のカスタムインスペクションを作る際、最も強力な武器となるのが 「Structural Search and Replace (SSR：構造的検索と置換)」 です。
通常の正規表現（Regex）は「文字列の並び」しか見ませんが、SSRは「PHPの構文木（AST：抽象構文木）」を理解します。つまり、変数名や空白、改行がどうなっていようと、コードの「構造」が一致していれば正確に検知できるのです。
最も重要な基本設定ステップ
まずは、独自のルールを定義するための画面を開いてみましょう。
1. PhpStormの設定画面を開きます。
- macOS: `Cmd + ,`
- Windows/Linux: `Ctrl + Alt + S`
2. 左メニューから [Editor] > [Inspections] に移動します。
3. 右上の検索窓に `Structural search` と入力します。
4. [General] > [Structural search] にチェックが入っていることを確認し、その下にある [Add Structural Search Inspection] をクリックします。
これで、独自の構文ルールを追加する準備が整いました。
—
3. 実践：プロジェクト固有のルールを「Custom Inspection」として実装する
今回は、実務で本当によくある要件を例に取ります。
> 【プロジェクトの要件】
> 「我がプロジェクトでは、DB接続を直接 `new PDO()` で生成することを厳禁とする。必ずDIコンテナ経由、または指定の `DatabaseManager::connect()` を経由しなければならない。直接 `new PDO` を書いている箇所はすべて警告を出したい」
このルールをPhpStormに覚え込ませましょう。
手順1: SSRテンプレートの作成
1. 先ほど追加したカスタムインスペクションの設定画面（または `Edit Inspection Profile Settings`）を開きます。
2. [Search template] に、検知したいコードの「パターン（雛形）」を記述します。変数には `$variable$ `$ のようなプレースホルダーが使えます。
以下の検索パターンを入力してください。
// 検索パターン：引数の数や中身に関わらず、new PDO(…) と書かれている構造すべてをキャッチする
new PDO($args$)
手順2: フィルタ（変数制約）の設定（高度なテクニック）
もし「特定の引数の場合だけ許可したい」といった例外がある場合は、変数をクリックして制約（Constraints）をかけられますが、今回は「すべて禁止」なのでそのままで進みます。
手順3: 警告メッセージの設定
インスペクションの設定項目で、以下のように設定します。
- Message: `プロジェクト規約により、直接の new PDO() の使用は禁止されています。DatabaseManager::connect() を使用してください。`
- Severity: `Warning` （または厳しくしたい場合は `Error`）
—
4. 動作確認：これが「生きたドキュメント」の威力だ！
設定を保存したら、実際にプロジェクト内のPHPファイルを開いて動作確認をしてみましょう。
テストコードの用意
以下のようなコードを適当なPHPファイルに書いてみます。
期待される挙動
コードエディタ上の `new PDO(…)` の部分に、シュッと鮮やかな赤い波線（または黄色い警告線）が走り、マウスオーバーすると先ほど設定したメッセージがポップアップします。
[警告] プロジェクト規約により、直接の new PDO() の使用は禁止されています。DatabaseManager::connect() を使用してください。
さらに強力なのは、PhpStormの Quick Fix（Alt + Enter / Option + Enter） を組み合わせることで、警告箇所を一瞬で正しいコードに置換（Replace）する機能まで持たせられる点です（※置換テンプレートも同時に設定した場合）。
—
5. チーム全員へ共有する（超重要：設定のGit管理）
「俺のPCのPhpStormでは警告が出るけど、後輩のPCでは出ない」となっては、チーム開発の意味がありません。PhpStormのインスペクション設定は、プロジェクトの資産としてGitで共有する必要があります。
1. 設定画面で作成したカスタムインスペクションを選択し、プロファイル名をデフォルトのままでなく、プロジェクト固有の名前（例: `MyProject Custom Rules`）に変更します。
2. プロジェクトのエディタ設定（`.idea/inspectionProfiles/` ディレクトリ配下）に、この設定ファイルがXML形式で書き出されていることを確認します。
3. この `.idea/` の中にあるインスペクション設定ファイルを、`.gitignore` から外し、Gitの管理下に置きます。
これで、チームメンバー全員が同じリポジトリをクローンした瞬間から、全く同じ高度なコーディングルールがIDEに標準装備されるようになります。
—
おわりに：開発体験（DX）を極限まで高めよう
今回は、PhpStormのCustom Inspectionを使ってプロジェクト固有のルールを強制する方法を解説しました。
ルールをドキュメントに書き残す時代は終わりました。「ルールはIDEに語らせる」。これが、モダンで洗練された開発チームの共通認識です。
人間が疲弊するレビューを減らし、コードの品質はマシンに担保させ、私たちは「本当にクリエイティブな設計やビジネスロジックの構築」に集中する――。この環境を手に入れたあなたのチームは、明日から見違えるほどスピードと品質を上げていくはずです。
毎日のコーディングが、もっと心地よく、もっと楽しくなりますように。それでは、次の開発現場でお会いしましょう！