phpDocumentorでドキュメント自動生成してみた

こんにちは、エンジニアの榎本です。

チーム開発において、ファイル数やクラスが増えてくると、新しいメンバーに説明をする際など、ドキュメントがないと説明が難しくなってくることがあります

しかし実際のところ、ドキュメントを作成する工数を確保できず、せっかく作ったドキュメントがあってもどんどん陳腐化している現場も多いのではないでしょうか

そのため、今回は phpDocumentor を用いて PHP のコードから自動でドキュメントを生成する方法を紹介したいと思います

作業環境

• CentOS 7.2
• PHP 7.0.12
• Composer 1.2.2

phpDocumentor のインストール

まずは新規にディレクトリを作成し、Composer で phpDocumentor をインストールします

$ mkdir dev
$ cd dev
$ composer require --dev phpdocumentor/phpdocumentor
Using version ^2.9 for phpdocumentor/phpdocumentor
./composer.json has been created
Loading composer repositories with package information
Updating dependencies (including require-dev)
...（略）
Writing lock file
Generating autoload files

これでインストールが完了です

Composer でインストールすることができるのでとても簡単ですね（開発環境でのみ使用すると思いますので --dev オプションを忘れないように気をつけてください）

それでは、インストールが完了したのでバージョンを確認してみます

$ composer show | grep phpdocumentor/phpdocumentor
phpdocumentor/phpdocumentor         v2.9.0  Documentation Generator for PHP

Composer で phpDocumentor が問題なくインストールされたことが確認できたので、ドキュメントの生成元のコードを簡単に書いてみたいと思います

• app/util/tax.php

<?php

namespace App\Util;

class Tax
{
    /**
     * 税率
     *
     * @var float
     */
    const RATE = 0.08;

    /**
     * 税込金額を返す
     *
     * @param  int $price
     * @return int
     */
    public static function getIncluded(int $price)
    {
        return floor($price * (1 + self::RATE));
    }

    /**
     * 税抜金額を返す
     *
     * @param  int $price
     * @return int
     */
    public static function getExcluded(int $price)
    {
        return ceil($price / (1 + self::RATE));
    }
}

• app/controllers/product.php

<?php

namespace App\Controllers;

use App\Util;

class Product
{
    /**
     * 商品詳細ページ
     *
     * @param  int $id
     * @param  int $price
     * @return void
     */
    public function showAction(int $id, int $price)
    {
        $product = $this->getProduct($id, $price);

        $this->view->product = $product;
    }

    /**
     * 商品情報を返す
     *
     * @param  int $id
     * @param  int $price
     * @return array
     */
    private function getProduct(int $id, int $price): array
    {
        return [
            'id' => $id,
            'price' => Util::getIncluded($price),
        ];
    }
}

たった2ファイルの簡単な PHP のコードですが、上記のコードから早速ドキュメントを自動生成してみたいと思います

ドキュメントの自動生成

ドキュメントの生成には phpdoc run コマンドを使用します（今回は phpdoc コマンドは Composer でインストールしたものを使用しているので注意してください）

$ vendor/bin/phpdoc run -d app -t public/doc
Collecting files .. OK
Initializing parser .. OK
Parsing files
...（略）
Analyze results and write report to log                            ..    0.000s

phpdoc run コマンドのオプションですが、d オプションでコードが置かれているディレクトリを指定し、t オプションでドキュメントの生成先ディレクトリを指定します。

今回は public/doc に自動生成されたドキュメントを配置するように指定しました。

それではドキュメントが生成されたのでブラウザで確認してみます。

たった2ファイルしかなかったので、中身が少ないですが、このようにクラスのメソッドの一覧や、メソッドの引数の一覧などがブラウザ上から確認できるようになりました

クラスの階層構造を可視化する

phpDocumentor はドキュメントの自動生成時にクラスの階層構造を図式で可視化することもできるので、どのような図式ができるのか試してみます

まずは、必要なライブラリを yum でインストールします。

$ sudo yum install graphviz graphviz-gd

インストールが完了したら、もう一度 phpdoc run コマンドでドキュメントを作成してみます。

このような図が表示されたら OK です！

まとめ

phpDocumentor を使用して、PHP のコードから自動でドキュメントを生成してみました

クラスの階層構造を可視化することもできるので、新しいメンバーがプロジェクトの全体像を把握することもブラウザ上で簡単に行うことができ、プロジェクトの説明を行う際などにも役立つと思います

Composer でとても簡単にインストールすることができ、導入への障壁がかなり低いので、ぜひ皆さんのプロジェクトにも導入してみてはいかがでしょうか