phpDocumentorの使い方(簡易版)・日本語訳

phpdoc --help で表示されるヘルプをベースに、phpDocumentorの使い方を日本語に翻訳しました。インストール方法など、いくつかの補足情報を追加しています。

---

phpDocumentorとは

phpDocumentorは、PHPソースコードからドキュメントを自動生成するツールです。

• 目的: ドキュメント生成を自動化。PHPで構成されたシステムの理解を促す。
• 使い方:
  1. ソースコード内に特別なコメントブロック（/** */で括られる）を設置し、DocBlockタグをコメントとして記述する。
  2. クラスやメソッドの詳細情報を記述する。
  3. phpDocumentorを実行すると、ドキュメントが自動生成される。

phpDocumentorは、クリーンで明確なコードベースを目指す開発者にとって欠かせないツールです。

インストール方法

PHARファイルをコピーする方法

公式サイト末尾に書いてあるとおり、composerによるインストールは可能ですが推奨されません。PHARファイルを以下の手順によりインストールします。

$ wget https://phpdoc.org/phpDocumentor.phar
$ mv phpDocumentor.phar phpdoc
$ chmod +x phpdoc

PHPが古くて最新版のphpDocumentorを動作させることができない場合は、Packagistで対応バージョンを確認し、該当するPHARファイルをGitHubで選んで取得してください。とはいえあまり古いと芋づる的な困難もありますので、最新のPHP環境が動作するコンテナを立ててビルドするのがよいかと思います。

• phpdocumentor/phpdocumentor - Packagist
• phpDocumentor/releases - GitHub

Dockerコンテナを利用する方法

$ docker run --rm -v ${PWD}:/data phpdoc/phpdoc:3

Dockerを利用している場合はこちらのほうが手軽です。

基本的な使い方

$ ./phpdoc run -d 解析するディレクトリ -t 出力ディレクトリ

<解析するディレクトリ>内のすべての.php、.php3、.phtmlファイルを解析し、<出力ディレクトリ>にドキュメントをHTMLサイトとして出力します。

runはproject:runの省略形です。

phpDocumentorは現在の作業ディレクトリでphpdoc.dist.xmlまたはphpdoc.xmlファイルを探し、存在する場合は設定ファイルとして読み込み、デフォルト設定を上書きします。設定ファイルではコマンドラインと同様の設定（およびそれ以上の設定）を指定できます。

$ ./phpdoc run -d src -t doc -i vendor -i node_modules

srcディレクトリを解析対象とし、docディレクトリにドキュメントを生成します。上記の例では2つのディレクトリを解析対象外としています。

runコマンドのオプション一覧

よく使うオプション

• -d, --directory[=DIRECTORY]：解析するディレクトリのカンマ区切りリスト。
• -t, --target[=TARGET]：生成された出力を保存するパス。
• -i, --ignore[=IGNORE]：ソースコードディレクトリに対して相対的な無視するファイルおよびディレクトリのカンマ区切りリスト。ワイルドカード * と ? がサポートされています。
• --title[=TITLE]：このプロジェクトのタイトルを設定します。デフォルトは「phpDocumentor」です。
• --force：キャッシュを無視し文書を完全にビルドし直します。

その他のオプション

• --cache-folder[=CACHE-FOLDER]：キャッシュファイルを保存するパス。
• -f, --filename[=FILENAME]：解析するファイルのカンマ区切りリスト。ワイルドカード ? と * がサポートされています。
• --ignore-tags[=IGNORE-TAGS]：無視するタグのカンマ区切りリスト、デフォルトはなし。package・subpackage・ignoreは無視できません。。
• --encoding[=ENCODING]：解析対象のソースファイルのエンコード。
• --extensions[=EXTENSIONS]：解析するファイルの拡張子のカンマ区切りリスト、デフォルトは php, php3, phtml。
• --hidden：このオプションを使用すると、phpDocumentorはピリオド(.)で始まるファイルとディレクトリを解析します（デフォルトでは無視されます）。
• --ignore-symlinks：他のファイルやディレクトリへのシンボリックリンクを無視します、デフォルトはオンです。
• -m, --markers[=MARKERS]：フィルターするマーカー/タグのカンマ区切りリスト。
• --validate：PHP Lintを使用して処理された各ファイルを検証します、パフォーマンスに大きく影響します。
• --visibility[=VISIBILITY]：ドキュメントに表示されるべき解析の可視性を指定します（カンマ区切り例："public,protected")。
• --defaultpackagename[=DEFAULTPACKAGENAME]：デフォルトパッケージに使用する名前。[デフォルト: "Default"]。
• --sourcecode：構文がハイライトされたソースコードを含めるかどうか。
• --template[=TEMPLATE]：使用するテンプレートの名前（オプション）（複数指定できます）。
• --parseprivate：@internalタグでマークされたDocBlockタグを解析するかどうか。
• -h, --help：このヘルプメッセージを表示します。
• -q, --quiet：メッセージを出力しません。
• -V, --version：このアプリケーションのバージョンを表示します。
• --ansi：ANSI出力を強制します。
• --no-ansi：ANSI出力を無効にします。
• -n, --no-interaction：どのインタラクティブな質問もしません。
• -c, --config[=CONFIG]：カスタム設定ファイルの場所。
• --log[=LOG]：書き込むログファイル。
• -e, --env=ENV：環境名。[デフォルト: "prod"]。
• --no-debug：デバッグモードをオフにします。
• -v|vv|vvv, --verbose：メッセージの詳細度を増加します：1は通常の出力、2はより詳細な出力、3はデバッグ。

その他のコマンド

前述のrunコマンド以外に、以下のコマンドが実装されています。

• project
  • project:run 省略形は run
  • project:parse 省略形は parse
  • project:transform 省略形は transform
• template
  • template:list 省略形は list
  • template:generate
  • template:package
• help

詳細なコマンドリストを表示するには、listコマンドを使用してください。また、特定のコマンドの詳細な説明を表示したい場合は、コマンド名の前に help という単語を付け加えて実行します。

$ ./phpdoc help project:run
Description:
  Parses and transforms the given files to a specified location

Usage:
  project:run [options]
  run

上記では、project:run コマンドがソースファイルを解析し（parses）、指定された場所にドキュメンテーションを生成する（transforms）ことを行うと説明しています。

[options] はこのコマンドに与えることができるオプションがあることを表しています。また、単に run という記述があるのは、project:run の短縮形として run コマンドも同様の機能を提供することを意味しています。