phpDocumentorとは
今回はPHPの話ですが、PHPでの開発に限らずシステム開発をしていると様々な設計ドキュメントを作成する機会がありますが、
小規模なWebシステムの開発程度であれば、別にドキュメントはなくても事足りることが多いです。ただドキュメントがあるとプロジェクト引継ぎだったり新人メンバ追加だったりという時に、簡易でもドキュメントがあると説明が楽になるというメリットもあります。しかし、そのためにドキュメントを作成・更新していく手間というのは惜しく、そんなときにソースコードから自動でドキュメント生成できるといいなという考えに至るわけですが、PHPでは、「phpDocumentor」というものがソースコードを自動生成してくれるツールになります。
ドキュメントを生成すると、クラスとメソッドの説明をHTML形式で見られるようにしたものと、簡単なクラス図のようなものが見られるようになります。
この簡易クラス図が個人的には分かりやすくていいなと感じています。
phpDocumetor導入手順
1.phpDocumentorのダウンロード
composerを使う方法もあるようですが、調べたところphpDocumentor単体では上手くいかないようで、自分は若干はまりそうだったので、
pharファイルをダウンロードして実行するという方法をとることにしました。
以下の公式サイトからダウンロードできます。
記事執筆（2020/9月）時点では、右側の「Installing」欄の「As a PHAR」リンクをクリックすると表示される「All you need to do is download the phar binary.」をクリックすれば「phpDocumentor.phar」がダウンロードできました。
2.phpDocumentor.pharファイルの設置
実行するときにパスを指定すればよいので、好きな位置に配置をすればOK。パスを通しておいてもよいでしょう。
私はCakePHPプロジェクトで使うので「vendor/bin/」の下に配置しました。
3.Graphvizのインストール
クラス図の生成に使われる「Graphviz」というソフトがあるようで、そちらをインストールしておきます。
Linuxの場合はyumでインストールできます。
sudo yum install graphvizWindowsの場合は、以下からインストールできます。
https://graphviz.org/download/
4.ドキュメントの生成
以下のコマンドで実行します。
php -d 【ドキュメント化したいクラスが配置されているディレクトリ】 -t 【ドキュメントを生成するディレクトリ】私はPHP7.4で実行していましたが、
「PHP Warning: count(): Parameter must be an array or an object that implements Countable～」というエラーが大量に出てきます。
これはPHPの7.2からcountメソッドの引数がcountableでない場合に発生するwarningですが、問題なく生成はされます。
もしWarningを出力させたくない場合は、
php -d error_reporting=E_ERROR -d 【ドキュメント化したいクラスが配置されているディレクトリ】 -t 【ドキュメントを生成するディレクトリ】という感じでphpの実行オプションでエラー出力レベルを変更すると出力されなくなります。
PHPファイルへのコメントの書き方
phpDocumentorはクラスやメソッドの直前にコメントを記述することで、そのコメントを基にドキュメントを生成します。
コメントをどのように記載すると、その内容がドキュメントに反映されるかを見ておきます。
例えば以下のようになります。
/**
* Sample File ←ファイルの説明
*/
/**
* Samples Class ←クラスの説明
*/
class Samples
{
/**
*
* test method ←メソッドの説明
*
* @param int $a ←メソッドの引数
* @return int ←メソッドの戻り値
*/
public function test($a){
return $a * 2;
}
}細かいルールは沢山あるようなので、詳細は以下の公式ページなどを参考にしてください。
参考
Glossary
参考
Inside DocBlocks
ちなみにCakePHPのbakeや、LaravelのartisanでControllerやModelを生成すると、自分で記述しなくてもある程度自動的にコメントが付けてくれるのでだいぶ楽になります。
