こんにちは、Nakaです。

本記事では、LaravelにおけるIDE補完を効かせるためのツールと、その仕組みについて解説します。対象読者はLaravelを普段から使っている中級者以上です。

はじめに

補完は開発スピードや効率に直結する重要な機能です。IDEやエディタがメソッドやプロパティの候補を正確に提示してくれることで、タイプミスや入力ミスを減らし、意図したコードを正確に書きやすくなります。言語やフレームワークを問わず、補完は開発体験の質を大きく左右する重要な要素です。

しかし、動的な仕組みを多用するフレームワークでは、補完は自然には効きません。Laravelもそのひとつで、Eloquentモデルの属性やQuery Builderのメソッド、Macro、Facadeの静的呼び出しなど、多くの便利機能はマジックメソッドによって提供されているため、PHPだけではIDEが補完候補を正確に推測できません。

そこでLaravelでは、PHPDocによる型注釈や、Laravel IDE Helper、Laravel Ideaのような補助ツールを用いて、動的なコードを「静的に見える形」に変換します。この仕組みによって、IDEは補完候補を正確に提示できるようになります。

本記事では、補完のベースとなるPHPDocの仕組み、Eloquentモデル / Macro / Facadeの補完を効かせる方法及びその仕組みを整理することで、IDEに頼るだけでなく、Laravelの内部構造や設計思想をより深く理解できるようになります。

PHPDocの仕組み

PHPDocはPHPの実行時には影響しませんが、IDEや静的解析ツールが型情報やメソッド情報を理解するための重要な手がかりとして活用されます。これにより、動的に生成されるプロパティやメソッドもIDEで補完できるようになります。

PHPは動的型付け言語で、型やメソッド情報が実行時まで確定しないことが多いです。そこで IDE は PHPDoc を「静的に見える型情報」として解釈し、補完候補を推測します。

例えば、 __getや __setによって 動的に生成されるプロパティをIDEに認識させる場合は @property を使います。

/**
 * @property string $name
 * @property int $age
 */
class User {}

このように書くことで、クラスに実際のプロパティがなくても、IDEは補完候補を提示できるようになります。

動的に処理されるメソッド（__call や __callStatic）も、PHPDocの @method を使って仮想的に定義できます。

/**
 * @method static User find(int $id)
 * @method static array<User> where(string $field, mixed $value)
 */
class User {}