PhpStorm Custom Inspectionの極意：プロジェクト固有ルールをIDEとCI/CDの血肉にする方法
開発現場において、コードレビューは最大のボトルネックであり、同時に最も消耗するプロセスだ。「命名規則の揺れ」「レガシーなヘルパー関数の直叩き」「特定のドメイン層における直接的なクエリ実行」——これらは本来、人間の脳みそではなく、機械が片手間に検知し、エディタ上でリアルタイムにねじ伏せるべき性質のものだ。
JetBrains PhpStormには、標準のInspection（静的解析）機能の枠を超え、チーム固有のアンチパターンをカスタムルールとして定義する「Custom Inspection (Structural Search and Replace: SSR)」という強力な機構が備わっている。
本稿では、このカスタムインスペクションを単なる「IDEの便利機能」で終わらせず、Dockerコンテナ環境での完全自動構成、PhpStorm CLI（Qodana / Inspections CLI）を用いたCI/CDパイプラインへの統合、そしてIDEのメモリ消費を最適化しながら限界まで自動化を突き詰める、生粋のアーキテクトのための実践知見を解説する。
—
1. 内部アーキテクチャの理解：InspectionはIDE内でどう動いているか
まず、PhpStormの静的解析エンジンが内部で何をしているのかを把握しておこう。
PhpStormは、ソースコードを開き、あるいはバックグラウンドで走査した際、テキストを字句解析（Lexer）し、構文解析（Parser）を行ってAST（抽象構文木：Abstract Syntax Tree）をメモリ上に構築する。
標準のInspectionやCustom Inspection（SSR）は、このASTノード群に対し、パターンマッチングをリアルタイムで実行している。
[Source Code]
↓ (Lexer / Parser)
[AST (Abstract Syntax Tree)]
↓ (SSR Pattern Matcher)
[Real-time Inspection Highlight & Quick Fix]
このメカニズムを理解していれば、単なる正規表現による文字列置換の限界（インデントや改行、コメントの有無に左右される問題）を超え、「コードの構造（構文木の形状）」を完全に捉えた精密なバリデーションが構築できることがわかるだろう。
—
2. 現場で即採用すべき「Custom Inspection」の実装シナリオ
ここでは、実際の現場で頻発する「絶対にやらせたくないアンチパターン」を例に、Structural Search and Replace (SSR) を用いたカスタムインスペクションの定義方法を解説する。
実装ターゲット：レガシーな `dd()` や `var_dump()` の本番混入防止
あるいは、ドメイン駆動設計（DDD）を採用しているプロジェクトで、アプリケーション層（Application Service）から直接データベースファサード（例: `DB::table()`）を叩くことを禁止するルールを考えてみよう。
ステップ1: 構造検索テンプレートの作成
1. PhpStormのメニューから `Edit` > `Find` > `Search Structurally…` を開く。
2. テンプレート（Template）に、検知したいコードの抽象構造を記述する。変数部分は `$variable$` のようにプレースホルダー化できる。
例えば、「インフラ層を介さずに、アプリケーション層で直接Eloquentモデルの静的メソッド（例: `User::all()`）を呼び出す行為」を禁止するカスタムルールの場合：
// 検索テンプレート（Search template）
$Class$::query()->$method$($args$)
ここで、変数 `$Class$` に制約（Constraints）をかける。
- `$Class$` の Script や Text filter で、`User` や `Order` など特定のドメインモデルを指定、あるいは特定名前空間以外からの呼び出しをフックする。
ステップ2: Custom Inspectionへの昇格
作成した検索パターンと、それに合致した場合の置換パターン（または警告メッセージ）を定義し、プロジェクト設定として保存する。
1. `Settings` > `Editor` > `Inspections` を開く。
2. `PHP` > `General` もしくは新規グループに `Structural Search` からカスタムインスペクションを追加。
3. 警告メッセージ（Problem descriptor）に、開発者への具体的な修正指示を記述する。
> 「警告: ドメインモデルの直接静的呼び出しは禁止されています。Repository層を介してアクセスしてください。」
—
3. チーム全員のIDEへ完全自動同期（Shared Settings）
作成したCustom Inspectionを、チームメンバー全員のPhpStormに手動で設定させるなどというナンセンスな運用をしてはならない。すべてのIDE設定はコードとしてバージョン管理されなければならない。
PhpStormのインスペクション設定は、プロジェクトルートの `.idea/inspectionProfiles/` ディレクトリ配下にXML形式で保存される。これをGitで管理することで、リポジトリをクローンした瞬間から全員の環境で同一のルールが強制される。
`.idea/inspectionProfiles/Project_Default.xml` の実例と解説
- `level=”ERROR”`: この設定により、エディタ上での波線表示だけでなく、後述するCI/CDパイプラインでのビルド失敗（exit code 1）に直結させることができる。
—
4. Dockerコンテナ環境 & CI/CD（Qodana）との完全統合
IDEの中だけでルールが動いていても、開発者が警告を無視してコミット・プッシュしてしまっては意味がない。ここで、PhpStormのエンジンをヘッドレスモードで実行するJetBrains公式の静的解析ツール「Qodana (PHP向け)」をCI/CDパイプラインに組み込む。
Qodanaは、PhpStormと完全に同一のインスペクションエンジン（ASTパーサおよびSSRルール）をヘッドレスで動作させるため、「IDEで警告が出たのにCIで検知されない」という不整合が絶対に起きない。
GitHub Actions / GitLab CI での実行設定 (`qodana.yaml`)
プロジェクトのルートに `qodana.yaml` を配置し、IDEでエクスポートしたプロファイルを参照させる。
version: “1.0”
使用するQodanaのリンターイメージ（PHP用）
linter: jetbrains/qodana-php:latest
プロジェクト固有のインスペクションプロファイルを指定
profile:
name: “Project Default”
解析対象外にするディレクトリ
exclude:
- build/
- var/
- vendor/
失敗条件の厳格化（ERRORレベルが1件でもあればCIを落とす）
failure-conditions:
severity:
error: 1
GitHub Actions Workflow の実装 (`.github/workflows/qodana.yml`)
name: Qodana Code Quality Inspection
on:
push:
branches: [ “main”, “develop” ]
pull_request:
branches: [ “” ]
jobs:
qodana:
name: PhpStorm Engine Static Analysis
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
checks: write
steps:
# 1. リポジトリのチェックアウト（LFSやサブモジュールがある場合は深さも指定）
- name: Checkout Code
uses: actions/checkout@v4
with:
fetch-depth: 0
# 2. Qodana CLIによる静的解析の実行（Dockerベース）
- name: Run Qodana Linting
uses: JetBrains/qodana-action@v2023.3
env:
QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }} # Qodana Cloud連携用（任意）
# 3. プルリクエストへのアノテーション自動投稿
- name: Add Inspection Results to PR
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: ${{ runner.temp }}/qodana/results/qodana.sarif.json
このパイプラインにより、開発者がプルリクエストを作成した瞬間、PhpStormの脳みそがクラウド上でコードを走査し、違反箇所にピンポイントでコメントを自動付与する。
—
5. パフォーマンス最適化ハック：大規模プロジェクトにおけるPhpStormのメモリ・負荷チューニング
カスタムインスペクションを増やしすぎたり、複雑すぎるASTパターン（深すぎるネストや曖昧なワイルドカード）を定義したりすると、PhpStormのバックグラウンド解析（Daemon）が重くなり、タイピング中にラグが生じたり、ファンスピードが跳ね上がったりする。
大規模なPHPモノリス（数万ファイル規模）を扱うDevOpsエンジニアとして、IDEのパフォーマンスを限界まで引き出すためのチューニング設定を共有する。
1. ヒープサイズの拡張 (`phpstorm.vmoptions`)
デフォルトのヒープサイズ（通常2GB程度）では、巨大なASTキャッシュを保持しきれず、ガーベッジコレクション（GC）が頻発してエディタがカクつく。
`Help` > `Edit Custom VM Options…` から以下のように最適化値を設定する。
最大ヒープサイズを4GBに拡張（マシンの物理メモリが16GB以上ある場合）
-Xmx4096m
初期ヒープサイズ
-Xms1024m
コードキャッシュの割り当て拡大
-XX:ReservedCodeCacheSize=512m
G1GC（Garbage-First Garbage Collector）の積極的活用によるSTW（Stop-The-World）時間の最小化
-XX:+UseG1GC
-XX:InitiatingHeapOccupancyPercent=45
-XX:G1ReservePercent=15
2. 不要なインスペクションの無効化
プロジェクトで使用していないフレームワーク（例：Symfonyを使っているのにLaravel用のインスペクションが走るなど）のインスペクションや、極端にコストの高いカスタムインスペクションは、対象スコープ（Inspection Scope）を限定するか、明示的に無効化する。
特に、巨大な `vendor/` ディレクトリや自動生成ファイル（`var/cache/` 等）がインスペクション対象に含まれていないか、`.idea/` のスコープ設定を厳しく監査すること。
—
総合アーキテクトからの提言
コードレビューは、人間が「どう書くべきか」という哲学を議論する場であって、「セミコロンが抜けている」「禁止されたメソッドが使われている」といった機械的な不備を指摘し合う場ではない。
PhpStormの Custom Inspection をコード化し、 `.idea` で共有し、QodanaによってCI/CDパイプラインの門番として常駐させる。このエコシステムを完成させた瞬間から、チームのコードベースは人間の注意力に依存しない、自律的な品質維持機構を手に入れる。
真の自動化とは、開発者の自由を奪うことではなく、クリエイティブな思考を阻害するノイズを極限まで排除することなのだ。今すぐプロジェクトにカスタムインスペクションを組み込み、静寂で美しいコードベースを手に入れてほしい。