結論
Laravel開発でVSCodeの補完が弱いと感じたら、barryvdh/laravel-ide-helperを導入する。
ただし、Modelの補完には専用コマンドが別途必要であり、補完が出ない原因がIDE側にある場合もある。
概要
IDE Helperとは
barryvdh/laravel-ide-helperは、LaravelプロジェクトにIDEが読める補完用ファイルを自動生成するパッケージ。
なぜ必要か
Laravelはファサードやマジックメソッドを多用するため、VSCodeなどのIDEが静的解析でクラスの構造を追いにくい。
たとえばAuth::user()の戻り値や、Eloquent Modelのカラム名などは、そのままでは補完が効かないことが多い。
IDE Helperを使うと、IDEが読めるかたちの定義ファイルが生成され、補完・型ヒント・定義ジャンプが機能するようになる。
環境
| 項目 | バージョン・ツール |
|---|---|
| Laravel | 10.x |
| 実行環境 | Laravel Sail（Docker） |
| エディタ | VSCode |
| VSCode拡張 | PHP Intelephense |
導入手順
1. パッケージのインストール
開発環境のみで使用するため、--devオプションをつけてインストールする。
sail composer require --dev barryvdh/laravel-ide-helper
2. 基本の補完ファイルを生成する
ファサード（Auth、DB、Cacheなど）の補完ファイルを生成する。
sail artisan ide-helper:generate
実行後、プロジェクトルートに_ide_helper.phpが生成される。
3. Model補完ファイルを生成する（重要）
Eloquent Modelのプロパティ（カラム名など）の補完には、別コマンドが必要。
sail artisan ide-helper:models
実行すると以下のようなプロンプトが表示される。
Do you want to overwrite the existing model files? Choose no to write to _ide_helper_models.php instead (Modelを直接書き換えますか？)
既存のModelファイルを直接変更したくない場合は no を選択する。
今回は補完確認が目的のため、 no を選択して_ide_helper_models.phpに出力した。
yesを選ぶと既存のModelファイルにPHPDocが直接書き込まれる運用も可能だが、チームの方針に合わせて判断すること。
動作確認
以下のようなコードを書いたとき、->の後にカラム名やメソッドの補完が表示されれば成功。
$user = new \App\Models\User();
$user-> /* ここで補完が出るか確認 */
Auth::user()経由の場合は、PHPDocで型を明示するとより確実に補完が効く。
/** @var \App\Models\User $user */
$user = Auth::user();
$user-> /* ここで補完が出るか確認 */
躓いたポイント
補完がまったく出ない
IDE Helper導入後も補完が出ない場合、Intelephenseのインデックスが古いままになっていることがある。
解決手順
- VSCodeを再起動する
- それでも解消しない場合は、コマンドパレット（
Ctrl + Shift + P）を開いてIntelephense: Index workspaceを実行する
インデックスが更新されると、補完が効くようになる場合がほとんど。
ide-helperだけでは補完が出ないケース
ide-helper:generateだけ実行してModelの補完を期待していた場合、補完は出ない。
Modelのプロパティ補完にはide-helper:modelsが別途必要。
この2つは生成対象が異なる。
| コマンド | 生成対象 |
|---|---|
ide-helper:generate |
ファサード・サービスコンテナなど |
ide-helper:models |
Eloquent Modelのプロパティ・リレーション |
use Illuminate\...などの未完成コードでエラーになる
PHPファイルにuse Illuminate\のような不完全なuse宣言が残っていると、Intelephenseがそのファイルを解析できずエラーになることがある。
補完確認のコードは、構文として成立した状態で記述すること。
Git管理の注意点
IDE Helperが生成するファイルは自動生成物のため、Gitで管理するファイルとしないファイルを分ける必要がある。
コミットするファイル
composer.json
composer.lock
パッケージの依存情報はチームで共有するためコミットする。
コミットしないファイル（.gitignoreに追加）
_ide_helper.php
_ide_helper_models.php
.phpstorm.meta.php（生成された場合）
.gitignoreへの追記例：
# IDE Helper
_ide_helper.php
_ide_helper_models.php
.phpstorm.meta.php
自動生成ファイルをコミットしておくと、Modelを変更するたびに差分が発生してレビューの妨げになる。
まとめ
-
barryvdh/laravel-ide-helperはLaravelのIDE補完を強化するパッケージ - ファサードの補完には
ide-helper:generate、Modelの補完にはide-helper:modelsが必要 - 補完確認が目的なら、
ide-helper:modelsの実行時はnoを選択すると既存Modelを直接変更せずに済む - 補完が出ない原因はIDE（Intelephense）側のインデックス問題であることも多い
- 生成ファイルは
.gitignoreに追加し、Gitの管理対象から外す -
ide-helper:modelsの再実行が必要なのはModelを変更したときのみで、毎回実行する必要はない
実際に試してみて
最初はAuth::や$user->で補完がまったく出ず、原因がわからず詰まりました。
調べてみると、ide-helper:generateだけではModelのカラム補完まではカバーできないとわかりました。
ide-helper:modelsを実行したことで、nameやemailなどのプロパティが補完候補に表示されるようになりました。