IntelliJ IDEA（PhpStorm）でphpDocumentorを軽快に使いこなす方法

JetBrains製のIDEは本当にクオリティーが高いです。感動。

今回は、IntelliJ IDEA（PhpStorm）でphpDocumentorを利用する手順を説明していきます。

phpDocumentorとは

phpDocumentorは、PHPのソースコードにプログラマー向けにAPIの使用方法のドキュメントを自動生成するコマンド及びそのドキュメントの形式のことです。PHPDocとも言われていたり。Javaで言うところのjavadocと同じです。

大人数で開発する上では、各クラスやモジュールの利用方法をチーム内で明確に共有する必要があります。とはいえ、少ない開発工数の大部分をプログラマー向けのドキュメント作成に割くわけにもいきませんから、できる限りツールに任せて自動的に作成してしまおう！というものです。

ドキュメントに書ける項目は様々ありますが、最低限のものを挙げると以下のとおりです。以下のようなコメントが、ソースコードに挿入されるイメージです。

クラス

/**
 * クラスの説明
 *
 * @access public
 * @author 佐藤 太郎 <sato@example.com>
 */

メソッド

/**
 * メソッドの説明
 *
 * @access public
 * @param 型 引数名 説明
 * @return 型 説明
 */

プロパティ

/**
 * @var 型 変数名 説明
 */

他にもいろいろなタグ（@paramや@returnのようなもの）がありますが、あまり多すぎてもチーム内での共有が難しくなるので、私のチームでは最低限このタグだけで運用しています。どうしてもその他のタグが必要な場合は、都度プロジェクトごとに決定しています。

他のタグの情報はこちらに記載してありますので、参考にどうぞ。

IntelliJ IDEAの場合は、PHPプラグインを入れる

当然ですが、phpDocumentorはPHPのための機能です。IntelliJ IDEAではデフォルトでPHPプラグインが含まれていないため、インストールしてください。

[Preferences]→[Plugins]→[Install JetBrains plugin]→[PHP]で検索して[Install]。インストール完了後は、IDEAを再起動してください。

phpDocumentorを使って実装する

では、早速実際にPHPのクラスファイルを作成する手順から、IntelliJ IDEAにおけるphpDocumentorの使い方を解説していきます。今回は、以下のクラスファイルにドキュメントを記載していきます。

<?php

class Test
{
    private $dateTime;

    public function __construct($dateTime)
    {
        $this->setDateTime($dateTime);
    }

    public function getDateTime()
    {
        return $this->dateTime;
    }

    public function getDateTimeFormat($format)
    {
        return $this->dateTime->format($format);
    }

    public function setDateTime($dateTime)
    {
        $this->dateTime = $dateTime;
    }
}

コンストラクターにPHPのDateTimeクラスのインスタンスを引数として渡すと、セッターメソッドを通じて$dateTimeプロパティに格納されます。あとは、getDateTimeやgetDateTimeFormatといったメソッドで、そのプロパティの内容を取得する単純なクラスです。

実は、このクラスをIDEAに入力すると、19行目の$this->dateTime->format($format);で警告が出ます。

なぜかというと、IDEAは$this->dateTimeがDateTimeクラスのインスタンスであることを知らないため、formatメソッドを検出できないのです。

「動的型付けだから仕方ないのでは？」と思われるかもしれませんが、ここを厳密に定義し、この警告を解消してくれるのが、phpDocumentorのメリットでもあります。phpDocumentorで以下のようにコメントをつけるだけで、IDEAの警告は解消されます。

$dateTimeプロパティにDateTimeのインスタンスである記述をしただけです。これだけで、IDEAは$dateTimeプロパティがDateTimeのインスタンスであることを認識しますので、警告が出なくなるのはもちろん、メソッドの補完などもしてくれるようになります。つまり、言語上は動的型付けですが、開発上は静的型付けのメリットを享受したまま開発ができるということです。

もちろん、DateTimeのようなPHPに元から備わっているクラスだけではなく、自作したクラスでも同様に動作します。

そして、肝心のphpDocumentorを追加する手順ですが、クラスファイルを開いている画面で[command]+[N]を押します（WindowsだとCtrl+Nかな？できない場合は[エディター内を右クリック]→[Generate]）。すると、以下の画面が開くかと思います。

一番下の[PHPDoc Blocks]を選択すると、プロパティとメソッド一覧が表示されますので、phpDocumentorを追加したいプロパティかメソッドを選択すると、自動で分析し、ある程度までドキュメントを自動生成してくれます。

後は、型やクラスの名称や、説明書きを加えればOKです。IDEAは、phpDocumentorの部分に関してもクラス名称など補完してくれるので、難なく入力できるかと思います。

IDEAで自動生成し、DateTimeクラスに関する部分だけ手動で型を入力したコードが以下です。

<?php

/**
 * Class Test
 */
class Test
{
    /**
     * @var DateTime
     */
    private $dateTime;

    /**
     * Test constructor.
     * @param DateTime $dateTime
     */
    public function __construct($dateTime)
    {
        $this->setDateTime($dateTime);
    }

    /**
     * @return DateTime
     */
    public function getDateTime()
    {
        return $this->dateTime;
    }

    /**
     * @param string $format
     * @return string
     */
    public function getDateTimeFormat($format)
    {
        return $this->dateTime->format($format);
    }

    /**
     * @param DateTime $dateTime
     */
    public function setDateTime($dateTime)
    {
        $this->dateTime = $dateTime;
    }
}

ほぼ自動生成ですが、これでだいぶ読みやすくなったかと思います。後は、文章でクラスやメソッド、プロパティや引数等の説明をちょちょいと書き加えれば、完了です。ね、簡単でしょう？

人間が見てわかり易いドキュメントを残すというのも非常に大事ですが、IntelliJ IDEAを使う上では、返り値や引数の型をドキュメント上に残すことで、誤った型を指定してしまってバグを作り込んでしまうリスクを抑えることができます。単純なクラス構成であればそんなに問題にはならないと思いますが、段々複雑になってくると、動的型付けであるPHPではあやふやになりがちです。

phpDocumentorをしっかり記載する癖をつけておけば、可読性は上がるし、型に関する警告等はIntelliJ IDEAで勝手に判断して出してくれるし、いいことづくめです。是非皆さん、使いこなしていきましょう。

おまけ

先ほど出てきたこの画面で、実はコンストラクターやアクセサーメソッド（ゲッター・セッター）も自動生成できます。

IDEを使いこなせるようになると、段々コードを手で入力する機会が減ってきて痛快ですね。