【実務・中級編】PhpStormの『Save Actions』でコードの品質を自動強制：フォーマットとクリーンアップの自動化 – 総合開発環境（IDE）生産性向上バイブル

PhpStormの「Save Actions」でコード品質を自動強制：フォーマットとクリーンアップの自動化

テックリードの役割とは何か。それは、コードレビューの場で「インデントが揃っていません」「使っていないuse文が残っています」「PSR-12に違反しています」といった、機械で100%防げる人間的コストをゼロにすることだ。

コードレビューは、ビジネスロジックの妥当性やアーキテクチャの美しさを議論するためにある。フォーマットのLinterやセマンティックなミスを指摘し合うために、エンジニアの貴重な時間を消費してはならない。

PHPエコシステムには、PHP_CodeSniffer、PHP-CS-Fixer、Psalm、PHPStanといった強力な静的解析ツールが存在する。しかし、これらをCIやGit Hooksだけで強制しようとすると、開発者は「コードを書く→コミットする→CIが落ちる→修正して再コミットする」という遅延ループに苦しむことになる。

この非効率をIDEのレイヤーで完全に根絶し、「Ctrl + S（または Cmd + S）を押した瞬間、すべてのコード品質が強制的に整う」世界を構築する。それがPhpStormの「Save Actions」を極限までチューニングする真の目的である。

—

1. なぜ「Save Actions」なのか？（CI/CDとPre-commitフックの限界）

多くのチームが、GitのPre-commitフック（Husky + lint-staged等）やGitHub ActionsなどのCIパイプラインでコードフォーマットを担保しようとする。しかし、これには実務上、明確なボトルネックがある。

1. フィードバックループの遅延: コミットやプッシュを行ってからエラーに気づくため、フロー状態（集中状態）が途切れる。
2. ローカル環境の差異: 開発者のローカルPHPバージョンやComposer依存のバージョン違いにより、CIとローカルでフォーマット結果が微妙にズレる現象が発生する。
3. IDEとの競合: PhpStorm自体のコード補完やリフォーマット機能と、外部のLinterが喧嘩を起こし、カーソルが勝手にジャンプするなどのストレスが生じる。

PhpStormのネイティブ機能および「Save Actions」プラグインを適切に組み合わせることで、「ファイルを保存した瞬間（＝思考が途切れる前）」にコードが整う。開発者はフォーマットの存在すら意識する必要がなくなる。これが最高開発生産性（Developer Experience）の到達点だ。

—

2. 導入すべき必須プラグインと設定の全体像

PhpStormには標準で「Reformat Code」などの保存時アクションがあるが、これだけでは不十分だ。プラグインマーケットプレイスから「Save Actions」を導入することで、詳細なトリガー制御と外部ツール連携が可能になる。

絶対に入れるべき神プラグイン

Save Actions (`dubreuia/intellij-plugin-save-actions`)
保存イベント（Shortcut, Deactivate, File Save）をトリガーにして、インスペクションの修正、未使用インポートの削除、コードフォーマットを原子的に実行する。

—

3. 実務で即採用できる！理想的な設定構成とJSONスニペット

PhpStormの設定は `.idea` ディレクトリ配下の XML ファイルとしてプロジェクト共有できる。チーム全員のIDE挙動を完全に同期させるためのベストプラクティス設定を公開する。

設定ファイル①: `project.default.xml` または `.idea/codeStyles/Project.xml`

PSR-12およびチーム固有の厳格なコーディング規約をPhpStormに強制する。

設定ファイル②: `.idea/saveactions_settings.xml`

「Save Actions」プラグインの挙動を定義する。ファイル保存時に何を実行するかを厳密に制御する心臓部だ。

—

4. チーム開発で役立つ設定の共有化ルール

個人がローカルで好き勝手な設定をしていると、Gitの差分（Diff）がフォーマット差分で埋まり、コードレビューが崩壊する。これを防ぐためのチーム運用ルールを策定する。

1. `.idea` ディレクトリのバージョニング方針

通常、`.idea` 内の多くのファイル（workspace.xmlなど）は個人依存のためGit管理から除外すべきだが、コードスタイルとSave Actionsの設定ファイルは例外である。

以下のファイルを必ずGit管理（リポジトリにコミット）に含める。

`.idea/codeStyles/` （コードスタイル設定）
`.idea/saveactions_settings.xml` （Save Actions設定）
`.idea/php.xml` （PHPインタープリター、PHPUnit、PHP Version設定）

`.gitignore` の設定例：

個人のワークスペース設定は除外
.idea/workspace.xml
.idea/tasks.xml
.idea/php-test-framework.xml

チームで共有すべき設定は許可（ネガティブパターンを使用）
!.idea/codeStyles/
!.idea/saveactions_settings.xml
!.idea/php.xml

2. インスペクションプロファイルのプロジェクト共有

PhpStormの「Settings > Editor > Inspections」で、プロジェクトで使用するPHPの静的解析ルール（未定義変数、型ミスマッチ、非推奨構文など）を設定し、それをプロジェクトルートの `.idea/inspectionProfiles/Project_Default.xml` としてエクスポートする。

これにより、開発者全員が同一のインスペクション（警告レベル）をリアルタイムで受け取れるようになる。

—

5. 開発スピードを劇的に高める「隠れたキーボードショートカット」

Save Actionsと組み合わせて使うことで、マウス操作を完全に排除し、思考のスピードでコードを操るための実戦的キーボードショートカット（macOS / Windows・Linux）を紹介する。

—

6. アーキテクトからの実践的アドバイス：導入時の「罠」と回避策

この構成を既存の大規模レガシープロジェクトに導入する際、1点だけ絶対に気をつけるべき罠がある。

それは、「数万行ある未フォーマットのレガシーコードに対して、いきなり全ファイル保存（または一括リフォーマット）をかけてはならない」ということだ。

これを行ってしまうと、Gitの `git blame` や `git log` の履歴が完全に破壊され、どの行がいつ、何の目的で変更されたのかを追うことが不可能になる。

レガシープロジェクトへの段階的導入ステップ

1. 新規作成・修正ファイルのみ対象にする:
Save Actionsは強力だが、既存の触っていないファイルまで自動フォーマットさせないよう、プロジェクト全体の強制適用は避け、`git diff` で自分が変更した行（またはファイル）だけが綺麗になるように運用する。
2. Git Hooks（Lefthook等）とPhpStormの二重防壁:
IDEの設定だけでなく、コミット時に `php-cs-fixer fix` を走らせる仕組みを併用する。これにより、万が一チームメンバーの誰かがSave Actionsを設定していなくても、CIやコミット手前で自動的にPSR-12に強制変換される。

—

結び

開発環境の整備は、単なる「お片付け」ではない。それは、チーム全体の認知負荷を劇的に下げ、エンジニアのエネルギーを「本質的な価値創造（ビジネスロジックの実装と設計）」に集中させるための最高にして最速のレバレッジ投資である。

今日からPhpStormにSave Actionsを導入し、「フォーマットのことで議論するチーム」から完全に卒業しよう。