こんにちは。開発現場でコードレビューのたびに「なんでここで型エラーに気づけないんだ……」と頭を抱えた経験はないだろうか。
PhpStormは、PHPエコシステムにおいて最強のIDEであり、その標準インスペクション（静的解析）だけでも一般的なタイポや未定義メソッドの検出には十分すぎるほどの能力を発揮する。しかし、大規模なドメインモデル、複雑なジェネリクス、サードパーティ製ライブラリのファントムメソッド、あるいはマジックメソッドが飛び交うレガシーとモダンが混在したコードベースにおいて、PhpStorm単体の型推論には限界がある。
「CI（GitHub Actionsなど）のパイプラインが回って、数分後にPHPStanやPsalmのエラー通知がSlackに飛んできてから修正する」――このタイムラグこそが、開発者のフロー状態を破壊し、生産性をドブに捨てる最大の要因だ。
本稿では、PhpStormにPHPStan（またはPsalm）をネイティブレベルで統合し、「コードを書いたその瞬間に、エディタ上でミリ秒単位のフィードバックを受け取る」ための最強の静的解析ワークフローを構築する。単なる導入手順ではない。チーム全体の生産性を極限まで引き上げるための実践知を伝授しよう。
—
1. 内部挙動の理解：なぜPhpStorm標準＋外部解析器なのか？
まず、ツールのデータフローを正しく把握しよう。
[ PhpStorm Editor ]
│ (リアルタイム入力)
▼
[ PhpStorm Internal Parser ] ──> 基本的な構文・型チェック (Instant)
│
▼ (ファイル保存 / バックグラウンドプロセス)
[ External Tool (PHPStan / Psalm) ] ──> AST解析 / 高度な型推論・レベル最大チェック
│
▼ (JSON / Inspections Output)
[ PhpStorm Inspection Results / Editor Highlighter ]
PhpStormのインスペクションは、高速性を最優先するため、ファイル単位かつ限定的なスコープで型を推論する。一方、PHPStanやPsalmは、アプリケーション全体の依存関係グラフ（AST：抽象構文木）を構築し、ジェネリクスの変性（variance）や条件付き型の評価、更には `@phpstan-taint-spec` によるセキュリティ脆弱性の追跡まで行う。
この2つをIDE内で同居させることで、「入力中はPhpStormが軽快にタイポを防ぎ、ファイル保存時（あるいはオンザフライ）に外部解析器が深い論理矛盾を赤波線で暴く」という、死角のない開発環境が完成する。
—
2. 絶対に入れるべき神プラグインと環境構築
PhpStormで外部静的解析を統合するためには、公式プラグインをただ入れるだけではなく、裏側のプロセス実行を最適化する必要がある。
必須プラグイン
1. PHPStan Support または Psalm plugin
- 外部ツールの実行結果をPhpStormの「Inspection（インスペクション）」ウィンドウにシームレスに統合し、エディタ上のインラインハイライト（赤・黄の波線）として描画する。
2. ide-helper (barryvdh/laravel-ide-helper 等のプロジェクト連携)
- フレームワーク特有のマジックメソッドを静認解析器に正しく認識させるための前提として、IDE側にもファサードの型を正しく教え込む。
実行バイナリのパス解決の鉄則
グローバル（`composer global`）のバイナリを指すのはアンチパターンである。プロジェクトごとにバージョンが異なるため、必ずプロジェクトローカルのベンダー配下（`vendor/bin/phpstan`）を指すように設定せよ。
Settings (Cmd+, / Ctrl+Alt+S) > PHP > Quality Tools > PHPStan
- Path to PHPStan: `[プロジェクトルート]/vendor/bin/phpstan`
- Configuration file: `[プロジェクトルート]/phpstan.neon`
- Timeout: 30〜60秒（大規模プロジェクトではタイムアウトに注意）
—
3. 実践的設定ファイル：`phpstan.neon` のベストプラクティス
チーム開発において、解析レベルを日和って下げては意味がない。しかし、いきなりLevel 9（最高レベル）を導入すると数千件のエラーが出て開発が止まる。現実解として、以下の構成をベースライン（Baseline）機能と共に導入せよ。
以下は、厳格かつ実用的な `phpstan.neon` の模範解答である。
parameters:
# 解析の厳格度レベル（最高は9だが、新規導入時は5〜7から段階的に上げるのが定石）
level: 7
# 解析対象とするソースコードのディレクトリパス
paths:
- src
- tests
# 除外したいファイルやディレクトリがある場合はここに記述
excludePaths:
- src/Legacy/OldModule/
# LaravelやSymfonyなど、マジックメソッドを多用するフレームワーク用の拡張
# 例: Larastanを使用する場合のパラメータ
# larastan:
# analyseModelProperties: true
# 既存の膨大なエラーを一旦「なかったこと」にして、新規エラーの発生を防ぐ仕組み
# 導入初期は必ず phpstan-baseline.neon を生成してコミットすること
# 実行コマンド: vendor/bin/phpstan analyze –generate-baseline
# baseline: phpstan-baseline.neon
# 未使用のプライベートプロパティやメソッドに対する挙動の制御
reportUnmatchedIgnoredErrors: true
ignoreErrors:
# サードパーティライブラリの型定義漏れなど、どうしようもない部分のみここに抑制を記述
–
message: ‘#Call to an undefined method [a-zA-Z0-9\\:]+::legacyMethod\(\)#’
path: src/Services/LegacyAdapter.php
> アーキテクトの知見:
> `–generate-baseline` を使って既存エラーを逃げることは敗北ではない。「今日から書くコードは一滴も型矛盾を許さない」というチームの意思決定を守るための防壁である。ベースラインの数値を毎スプリントで減らしていくタスクをバックログに入れろ。
—
4. 開発スピードを劇的に高める隠れたキーボードショートカット
静的解析エラーを「後から直す」のではなく「書きながら直す」ために、以下のショートカットを身体に叩き込め。
| アクション | macOS ショートカット | Windows/Linux ショートカット | プロの活用法 |
| :— | :— | :— | :— |
| 次のエラーへジャンプ | `F2` | `F2` | エディタ上でエラー箇所を迷わず渡り歩く。 |
| 前のエラーへジャンプ | `Shift + F2` | `Shift + F2` | 修正漏れを確認しながら戻る。 |
| クイックフィックス（意図の実行） | `Option + Enter` | `Alt + Enter` | これが最重要。 型のキャスト、PHPDocの自動生成、未定義メソッドのスタブ作成を一瞬で行う。 |
| 外部ツールの手動再解析 | `Ctrl + Shift + Alt + I` (Inspect Code) | `Ctrl + Alt + Shift + I` | バックグラウンド解析を待たずに強制的に最新の状態に同期。 |
| ターミナルでのPHPStan即座実行 | 自作ダクトテープ（後述） | 自作ダクトテープ | エディタから指を離さずに実行。 |
神ショートカット連打のユースケース
メソッドの引数に間違った型を渡したとする。
1. エディタ上にPHPStanによる赤波線が表示される。
2. カーソルを合わせ、`Option + Enter` (Alt + Enter) を叩く。
3. クイックメニューから「PHPStan: Type mismatchを解決する修正案（またはキャストの追加）」を選択。
4. 一瞬でコードが補正され、エラーが消える。
この一連の動作に、マウス操作は1ミリも必要ない。
—
5. チーム開発で役立つ設定の共有化ルール
個人個人のPhpStormの設定がバラバラだと、「俺の環境ではエラーが出ないのに、CIで落ちる」という悪夢のような不整合が発生する。これを防ぐため、プロジェクト固有の設定をGit管理に含める必要がある。
1. `.idea` ディレクトリの適切な管理
PhpStormはプロジェクト設定を `.idea` フォルダ内のXMLファイル群として保存する。すべてをGit管理する必要はないが、静的解析に関するインスペクション設定は共有すべきである。
以下のファイルをバージョン管理（Git）に含め、チーム全員で同一の解析ルールを強制せよ。
- `.idea/php.xml` (PHPのバージョン、インタープリター設定)
- `.idea/phpstan.xml` (PHPStanプラグインのパス・設定)
- `.idea/inspectionProfiles/` (インスペクションの有効/無効プロファイル)
逆に、個人のウィンドウ位置やタブの状態が保存される `.idea/workspace.xml` や `.idea/tasks.xml` は `.gitignore` に必ず追加すること。
`.gitignore` のベストプラクティス例
PhpStorm 固有のローカルワークスペース設定
.idea/workspace.xml
.idea/tasks.xml
.idea/usage.statistics.xml
.idea/dictionaries
.idea/shelf
ただし、インスペクションプロファイルとPHP設定は共有する
!.idea/inspectionProfiles/
!.idea/php.xml
!.idea/phpstan.xml
2. Composer ScriptsによるCI/IDEの完全同期
開発者のローカル環境で走るPHPStanと、GitHub Actions等のCIで走るPHPStanのバージョンや設定がズレてはならない。`composer.json` にカスタムスクリプトを定義し、IDEからもこのスクリプトを叩けるように紐付ける。
{
“scripts”: {
“stan”: “vendor/bin/phpstan analyze –memory-limit=2G”,
“stan:baseline”: “vendor/bin/phpstan analyze –generate-baseline”,
“ci:check”: [
“@composer stan”,
“vendor/bin/phpunit”
]
}
}
PhpStormの「Run Anything」機能（`Cmd` を2回連続押し / `Ctrl` を2回連続押し）から `composer stan` と打ち込むだけで、ローカルのインスペクション結果と完全に一致したログをIDE内のターミナルで確認できる。
—
6. まとめ：静的解析を「苦行」から「快感」へ
多くの開発現場において、静的解析ツールは「怒られ発生装置」として嫌煙されがちだ。CIで赤色に染まったビルド結果を見て溜息をつく、そんなワークフローは今日で終わりにしよう。
PhpStormにPHPStanを深く根付かせ、コードを書く「その瞬間」にフィードバックを得る仕組みを作れば、エラー修正は「手戻り」ではなく「リアルタイムなパズルゲーム」に変わる。強固な型安全は、リファクタリングの恐怖を消し去り、ビジネスロジックの実装スピードを何倍にも加速させる最強の武器となる。
あなたのプロジェクトの `vendor/bin/phpstan` は、今日も出番を待っている。さっそく今日のコミットから、エディタを赤波線のない美しい緑の境地へと導いてほしい。