こんにちは！日々の開発、本当にお疲れ様です。
新しいチームに入ったとき、あるいは大規模なレガシーコードを改修しているとき、こんなストレスを感じたことはありませんか？
「また古い書き方のメソッドが使われている……」
「PSRやチーム固有の規約に反したコードが、なぜかプルリクエスト（PR）まで素通りしてくる……」
「レビューアーの指摘コストが高すぎて、本来の設計議論に集中できない……」
コードレビューの度に「ここ、こう直してください」と指摘するのも、指摘されるのも、正直お互いにエネルギーを使いますよね。
実は、JetBrains社が誇る最強のIDE「PhpStorm」には、チームのコーディング規約を自動で検知し、その場で修正案まで提示してくれる「ガードレール」を自作する機能が備わっています。それが今回解説する 「Structural Search and Replace（構造的検索と置換）」 です。
これをマスターすれば、あなたのチームから「属人的な規約チェック」を完全に排除し、毎日のコーディングが劇的に楽になりますよ。さあ、一緒に次世代の自動レビュー環境を作っていきましょう！
—
1. なぜ「正規表現」ではダメなのか？PhpStormの「構造的検索」の本質
コードのパターンマッチングといえば「正規表現（Regex）」を思い浮かべる方が多いでしょう。しかし、ソースコードの解析において、正規表現はあまりにも無力です。
例えば、「非推奨である `legacy_db_query()` という関数が使われていたら警告したい」という要件を考えてみます。
- 改行やスペースの入り方、インデントがバラバラ
- 文字列の中にある `legacy_db_query` という単語（コメントやログ出力）までヒットしてしまう
正規表現でこれらを完璧にハンドリングしようとすると、破綻するか、メンテナンス不可能な複雑怪奇なパターンを書くことになります。
抽象構文木（AST）をハックする
PhpStormの「Structural Search」は、テキストの文字列としてではなく、プログラムの「抽象構文木（AST: Abstract Syntax Tree）」としてコードを理解して検索します。
つまり、PhpStormは「あ、これは文字列の中のゴミだな」「あ、これは関数呼び出しのノードだな」という構造を完璧に理解した上でパターンマッチを行います。だからこそ、ホワイトスペースや改行に惑わされず、正確にターゲットを撃ち抜けるのです。
—
2. 基礎セットアップ：あなた専用の「自動ガードレール」を作る
それでは実際に、PhpStormで構造的検索のテンプレートを作り、それをインスペクション（リアルタイム静的解析）に組み込んでいきましょう。
今回は、実務で非常によくあるユースケースとして、「特定の非推奨メソッド（例：`User::getActiveData()`）の呼び出しを検知し、新しいメソッド（`User::fetchActiveProfile()`）への自動置換を促すルール」を作ります。
ステップ1：構造的検索ダイアログを開く
PhpStormのメニューバーから、以下のパスをたどります。
- `Edit` -> `Find` -> `Search Structurally…` （ショートカット: `Ctrl + Shift + S` / `Cmd + Shift + S`）
ステップ2：検索テンプレートの定義
ダイアログが開いたら、上部の「Search template」ボックスに、抽象的なコードのひな形を入力します。
// 検索パターン（$user$ や $method$ は任意の変数＝ワイルドカードです）
$user$->$method$($args$)
これだけだとすべてのメソッド呼び出しにヒットしてしまうので、変数の制約（Constraints）を設定します。
`$method$` を右クリックし、`Edit Variables…` を選択します。
- Text filter: `^getActiveData$` （正規表現で特定のメソッド名に限定）
これで、「任意のオブジェクト経由で `getActiveData` というメソッドが呼ばれている箇所」を完璧に捕捉するテンプレートが完成しました。
ステップ3：インスペクション（リアルタイム警告）への昇格
ここからが本番です。作った検索パターンを、単発の検索で終わらせず、「エディタが開いているだけで常に警告してくれるルール（インスペクション）」に登録します。
1. 検索ダイアログの下部にある `Save as Template…` をクリックします。
2. テンプレート名にわかりやすい名前（例: `TeamStandard: Deprecated getActiveData`）をつけます。
3. PhpStormの設定画面を開きます（`Settings` / `Preferences` -> `Editor` -> `Inspections`）。
4. 検索窓に `Structural search` と打ち込みます。
5. PHPの項目にある `Structural search` にチェックを入れ、先ほど保存したテンプレートを探して有効化します。
6. 重大度（Severity）を `Warning` や `Error` に設定します。
これでセットアップは完了です！
—
3. 精度高い「HelloWorld」的動作確認
正しく設定が機能しているか、実際にコード書いて確かめてみましょう。プロジェクト内の適当なPHPファイルに、以下のコードを記述してみてください。
テストコード
getActiveData();
// 比較用：これはヒットしてはいけない安全なメソッド
$profile = $user->fetchActiveProfile();
return json_encode($userData);
}
}
期待される挙動
エディタ上に波線（インスペクションの警告）が表示されれば成功です！
`$user->getActiveData();` の部分にカーソルを合わせると、あなたが設定した警告文言や、場合によっては自動修正（Quick Fix）のメニューがポップアップします。
開発者はコードを書いているリアルタイムで規約違反に気づくことができ、CI/CDパイプラインに載せる前にローカル環境でクリーンな状態を保つことができます。
—
4. 現場の戦闘力を爆発させる応用テクニック：チーム共有の極意
ここまでの設定でも十分強力ですが、これを「自分だけのローカル設定」で終わらせては、チーム開発の効率化とは言えません。全員が同じガードレールを持つ仕組みに昇華させましょう。
`.phpstorm.inspection.profile` の共有
PhpStormのインスペクション設定は、プロジェクトルートにある `.idea/inspectionProfiles/` ディレクトリ配下にXMLとして保存されます。
この設定ファイルをGitなどのバージョン管理システムに含めてチームメンバーと共有することで、「メンバーがRepositoryをクローンした瞬間から、チーム共通の厳格なコーディング規約ガードレールが自動で稼働する」という理想郷が完成します。
事故を防ぐための実践的なパターン例
実務で即座に使える、構造的検索のパターンをいくつかシェアします。
1. 生SQL（Query Builderの生クエリ）の禁止
- 検索パターン: `$db->query($sql)`
- 意図: セキュリティ脆弱性（SQLインジェクション）の温床になる生クエリの直書きを検知し、ORMやプリペアドステートメントへの移行を強制する。
2. 本番環境での `var_dump` や `dd()` の混入防止
- 検索パターン: `dd($val$)` または `var_dump($val$)`
- 意図: デバッグコードのコミット漏れをCIに到達する前に100%ブロックする。
—
まとめ：ツールに任せられるものは、すべてツールに任せよう
今回は、PhpStormの「Structural Search and Replace」を使った自動レビュー・ガードレール構築法を解説しました。
- 正規表現の限界を超え、コードの「構造（AST）」を正確に解析する
- 独自の検索パターンをインスペクションに登録し、リアルタイムで警告を出す
- `.idea` 設定をGitで共有し、チーム全体のコード品質を底上げする
人間がやるべき仕事は、よりクリエイティブな「アーキテクチャの設計」や「ビジネスロジックの追求」です。機械的にチェックできる規約違反の検知は、すべてPhpStormの優秀なエンジンに肩代わりさせましょう。
これをマスターすれば、毎日のコーディングが劇的にストレスフリーになり、チーム全体の開発生産性が一段上のステージへと駆け上がります。ぜひ、今日の業務から試してみてくださいね！