はじめに

CakePHP 3 のコーディング規約では、コードのコメントブロックを、明確に書くべきとされており、コメントには phpDocumentor のタグが使えると書かれています。

コードのコメント (CakePHP 3 Cookbook)

https://book.cakephp.org/3/ja/contributing/cakephp-coding-conventions.html#id15

phpDocumentor とは、決められた書式に則ってPHPのコメントを書くことで、クラスや関数などに関するドキュメントを自動生成することが可能なツールです。

phpDocumentor

https://www.phpdoc.org/

今日は CakePHP 3 に phpDocumentor 2 を導入し、ドキュメントを自動生成する方法をご紹介します。

今回は Windows 環境を例に進めます。
前提条件として、php.exe にパスが通っているものとします。
また本記事の中でも「パスを通す」作業がありますので、分からない方は調べてください。

目次

1. composer ではインストールできず…
   (読み飛ばしてOKです)
2. phar ファイルの設置
3. graphviz「dot」のインストール
4. ドキュメント生成

1. composer ではインストールできず…

最初は composer を使ってインストールを試みたのですが、下記のようなエラーが表示されてうまくいきませんでした。

> composer require --dev phpdocumentor/phpdocumentor 2.*
  Problem 1
    - Installation request for symfony/config (locked at v4.3.6) -> satisfiable by symfony/config[v4.3.6].
    - phpdocumentor/phpdocumentor v2.0.0 requires phpdocumentor/template-zend ~1.3 -> satisfiable by phpdocumentor/template-zend[1.3.0, 1.3.1, 1.3.2].
    - phpdocumentor/phpdocumentor v2.0.1 requires phpdocumentor/template-zend ~1.3 -> satisfiable by phpdocumentor/template-zend[1.3.0, 1.3.1, 1.3.2].
    (省略)
    - phpdocumentor/template-zend 1.3.2 requires ext-xsl * -> the requested PHP extension xsl is missing from your system.
    - phpdocumentor/template-zend 1.3.1 requires ext-xsl * -> the requested PHP extension xsl is missing from your system.
    (省略)
    - phpdocumentor/phpdocumentor v2.8.3 requires phpdocumentor/fileset ~1.0 -> satisfiable by phpdocumentor/fileset[1.0.0].
    - phpdocumentor/phpdocumentor v2.8.4 requires phpdocumentor/fileset ~1.0 -> satisfiable by phpdocumentor/fileset[1.0.0].
    (省略)
    - Conclusion: don't install phpdocumentor/fileset 1.0.0
    - Installation request for phpdocumentor/phpdocumentor 2.* -> satisfiable by phpdocumentor/phpdocumentor[v2.0.0, v2.0.1, v2.1.0, v2.2.0, v2.3.0, v2.3.1, v2.3.2, v2.4.0, v2.5.0, v2.6.0, v2.6.1, v2.7.0, v2.7.1, v2.8.0, v2.8.1, v2.8.2, v2.8.3, v2.8.4, v2.8.5, v2.9.0].

  To enable extensions, verify that they are enabled in your .ini files:
    - C:\xampp\php\php.ini
  You can also run `php --ini` inside terminal to see which files are used by PHP in CLI mode.

Installation failed, reverting ./composer.json to its original content.

PHP の xsl エクステンションを有効化しても解決はできず。
仕方がないので、今回は phar で導入することにしました。

2. phar ファイルの設置

phpDocumentor のサイトから phar ファイルをダウンロードします。
コンテンツ右側の Installing にある「As a PHAR」の「All you need to do is download the phar binary.」をクリックするとダウンロードできます

設置場所ですが、僕は cakephp3 の bin フォルダの中に置きました。

3. graphviz「dot」のインストール

phpDocumentor では graphviz の 「dot」というプログラムを使用しています。これがないと、phpDocumentor 実行時に下記のようなエラーが出ます。

Unable to find the `dot` command of the GraphViz package. Is GraphViz correctly installed and present in your path?

まずはプログラムをダウンロードします。
graphviz の公式サイトにアクセスし、上部メニューの「Download」をクリックします。

遷移先の見出し「Executable Packages」の「Windows」にある「Stable 2.38 Windows install packages」をクリック。「graphviz-2.38.zip」をクリックしてダウンロードします。
(2.38はバージョン番号なので異なる場合があります)

ダウンロードした zip ファイルを適当なところに解凍し、その中の bin フォルダにパスを通します。どうすべきか分からない人は、c:\Program Files\graphviz\bin となるように展開すると良いと思います。

4. ドキュメント生成

下記コマンドで phpDocumentor を実行します。 CakePHP 3 の src フォルダの中を解析し、ドキュメントを phpdoc フォルダの中に生成します。

< cd \path\to\cakephp3
< php -d error_reporting=32765  bin\phpDocumentor.phar -d src -t phpdoc

phpdoc フォルダの中にできた index.html を開くと、生成されたドキュメントを閲覧することができます。

ところで、上記コマンドの -d error_reporting=32765 の箇所ですが、これは E_WARNING を出力しないようにしています。

phpDocumentor 2.9 には PHP7.2 以上だと 下記のような warning が出る不具合があるようです。

PHP Warning:  count(): Parameter must be an array or an object that implements Countable in phar://path/to/cakephp3/bin/phpDocumentor.phar/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1293

PHP: 定義済み定数 - Manual

https://www.php.net/manual/ja/errorfunc.constants.php