これは CakePHP Advent Calendar 2018 の22日目の記事です。
他人の土俵で相撲を取る記事で恐縮ですが、空いてたので許してください。

さて、僕は、CakePHP3のアプリケーションを書く際に、PhpStormを使っています。
namespace とかいちいち書かなくていいし、deprecated のコードとかも見つけやすいし最高だと思っています。

ただ、めんどくさいこともあります。
それは、静的解析がうまく動いてくれない場合があることです。

文字で説明するよりコードを見ていただいたほうが早いと思うので、例を上げます。
ここでは、例として新しいコンポーネントを作る際のことを考えます。

<?php

namespace App\Controller\Component;

use Cake\Controller\Component;

class ReadRequestComponent extends Component
{
    public function isGet()
    {
        return $this->request->is('get');
    }
}

まあ、こんなメソッド / コンポーネントを作る人は実際はいないとは思いますが、あくまで例です。
こんなコンポーネントが作られたということは、どこかしらコントローラーから呼び出されることになるでしょう。

今回は、これまた例として、UsersController::index() から呼ばれたときのことを考えてみましょう。
繰り返しになりますが、こんなコンポーネントいらないですからね！本当は！

<?php
namespace App\Controller;

use App\Controller\AppController;

/**
 * Users Controller
 *
 * @property \App\Model\Table\UsersTable $Users
 *
 * @method \App\Model\Entity\User[]|\Cake\Datasource\ResultSetInterface paginate($object = null, array $settings = [])
 */
    public function initialize()
    {
        parent::initialize();
        $this->loadComponent('ReadRequest');
    }
    /**
     * Index method
     *
     * @return \Cake\Http\Response|void
     */
    public function index()
    {
        $users = $this->paginate($this->Users);
        $g = $this->ReadRequest->isGet();
        $this->set(compact('users', 'g'));
    }
?>

このとき、UsersController には大きな問題が生じているわけです。
そう。 ReadRequestって何？という。
残念ながら、PhpStorm は、 ReadRequest というコンポーネントの存在を知りません。
なので、isGet() なんてメソッドないけど？と怒られてしまいます。

これはまあ当然といえば当然ですし、融通がきかないといえばそれまでです。
が、現実はそうなっています。

では、このねじれ現象を解消する方法はないのでしょうか？

いえ、あります。
それは、PHPDoc を書いてあげること。
クラスの説明のところに以下を追記してあげます。

/**
 * @property \App\Controller\Component\ReadRequestComponent $ReadRequest
*/

すると、あらビックリ！
PhpStormが、そのメソッドの存在を認識してくれました。
めでたしめでたし。

なのですが、これを全ファイルに対して毎度行うのがめんどくさい。
というのが今回のテーマです。

ということで、前振りが長くなってしまいましたが、今回ご紹介するのがこちら(注1)。
https://github.com/dereuromark/cakephp-ide-helper
CakePHP コアメンバーの、 @dereuromark さんが作成されています。

使い方はいたってシンプルです。
Composer 経由でインストールし、いくつかの設定を追加したあと、

bin/cake annotations all # 注2

というコマンドを叩けば終わりです。

何ということでしょう！今までノーガード戦法だったコードにアノテーションがついて、
静的解析できるようになっているではありませんか。
git commit の prehook とかに仕込んでおけば、もうPhpStormに怒られることもありません。

ということで、めっちゃ便利なプラグインのご紹介でした。

一応、念の為、全然必要ないとは思いますが、どんな感じで動くのかイメージを掴んでもらうために、
レポジトリを作りました。
僕の文章力が足りず、イメージが湧きづらかったらご活用ください。
では皆さん、メリークリスマス！

注1. "cakephp/cakephp": "^3.6"
注2. all の部分は、 model とか template とかいろいろオプションがあるのですが、詳細はReadme を読んでみてください。 --help でもいろいろ出てきます。便利です。