[Laravel5]PHPDocを書いてLaravelとIDEをもっと便利に使う
こんにちは、中榮です。
もうIDEの補完がないと生きていけない体になって久しいです。
マジックメソッドや返り値がmixedなメソッドを多用するフレームワーク、ライブラリを利用してコードを書いているとIDEの補完が効きにくいことがよくあります。
PHPDocを書くことである程度この辛さを軽減することができます。
この記事では、マジックメソッドが比較的多く登場するLaravelを例に２つのおすすめを挙げます。
※利用しているIDEはPHPStormです。
ローカル変数に@varでmixed対策
クラスに存在するプロパティの他に、ローカル変数もDocコメントで補完できます。 変数に代入するメソッドや関数の返り値がmixedもしくはPHPDocがない場合に有効です。
例えば、LaravelのIoCコンテナをサービスロケーターとして利用する場合に呼び出したオブジェクトを補完できます。
（コンストラクタやセッタで依存注入した方が素直だと思いますが）
/**
* @var \Illuminate\Contracts\Guard $auth
*/
$auth = \App::make('auth');
$user = $auth->user();
個人的にはEloquentのBuilderクラスの補完によく使います。
マジックプロパティに@property
クラスに実在せずマジックメソッドの__get()で実装されているプロパティを補完できます。
Laravelの場合はModelクラスに一通り書いておくとリレーションやプロパティ、アクセサを補完できるので便利です。
<?php namespace App\Models;
use App\Models\User;
use App\Models\Comment;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Collection;
/**
* Class Article
* @property int $id ID
* @property int $user_id ユーザーID
* @property string $title タイトル
* @property string $body 本文
* @property array $content 物件
* @property User $user ユーザー
* @property Collection|Comment[] $comments コメント
*/
class Article extends Model {
※PHPには今の所ジェネリクスがないため、Colection
他に@methodもマジックメソッドの対抗策として役に立ちます。
最後に
元のフレームワークやライブラリが補完されにくい場合でも、PHPDocを書くことである程度まで補完することができます。もちろん、元のソースにPHPDocが書かれていないのでなんともならない、というケースもありますが。
フレームワークやライブラリを選ぶ際には、素直でPHPらしい補完の効きやすいコードで実装されているかどうか、というのも１つの良い目安だと思います。
自分で実装するコードにはPHPDocをしっかり書き、また、戻り値がmixedになるようなメソッド・関数を生み出さないことでIDEの恩恵を受けやすくなります。
ただし、PHPDocだけでは型の保証までは行えません。PHPDocを間違うと間違った補完が行われうるので注意が必要です。PHPDocの前にタイプヒントを書くのが良い習慣でしょう。
