pblo

ぴーぶろ : webデベロッパーの勉強メモとか

phpDocumentorをインストールしたときのメモ

お仕事で、開発環境にphpDocumentorを入れようとしたのですが、苦戦したのでメモメモ。

phpDocumentorとは？

簡単に言うと、phpソースを読み込んでクラスや関数をドキュメント化したhtmlを生成してくれるツール

phpdoc.org : phpDocumentor

インストール

まずはこちらから最新版（09/02/02現在　phpDocumentor 1.4.2）を取得

sourceforge.net:PhpDocumentor

いつものように展開するのですが、その前に、ここでポイント。

用意されているドキュメント生成方法は３つ（phpdoc.org:インストール方法より）あります。

  • pear

  • コマンドライン

  • ブラウザ

私の場合、pearは、開発環境が外部と通信できないためNG。ブラウザは、分かりやすいけど、毎回手動で更新になるというのであまりよろしくない。そこで、クーロンで自動実行できるコマンドラインを選択しました。

コマンドラインによるインストール

まずはtarファイルを展開して、リネームします。あ、リネームは個人的に気になるからするだけですｗ

$tar xvzf PhpDocumentor-1.4.2.tgz

$mv PhpDocumentor-1.4.2 PhpDocumentor

$cd PhpDocumentor

PhpDocumentorディレクトリ内にphpdocファイルがあるので、それに実行権限を加えます。

$chmod 755 phpdoc

で、あとはこいつを実行するだけなのですが、こいつがくせものでした。

まず、いくつかオプションがあります。

$./phpdoc -t (targetDir) -d (parseDir)

オプションの説明ですが、

  • -t : ターゲットディレクトリ。ドキュメントを生成するディレクトリを指定

  • -d : パースディレクトリ。解析をするディレクトリを指定

例えばこんな感じ

$./phpdoc -t /target/phpdoc -d /parse/inc

で、いざ実行してみると、どうやら途中エラーで止まっているようです。

・・・って言いたかったのですが、いざこのエントリーを書きながら実行してみると、通りました。（うはっ

なんじゃそりゃ・・・

まー、でもこのphpdoc自体の作りが面白いので簡単に解説しておきます。

phpdocの動き

一言で言うと、phpdoc は『shとphpが一つになったファイル』 です。（こんなの初めて＞＜

上半分がshで下半分がphpという構成です。

ではどうやって動作するのか？

まずは、以下のように実行しているので、shとして動作します。

$./phpdoc -t /target/phpdoc -d /parse/inc

そしてちょうどshの終わりにexitしているため、エラーにはなりません。そこで終了するので、phpを描いてようが、秘め事を書いていようが、関係ないのですね。

そして、shの途中で、execコマンドで phpで自分自身ををたたきます。

記述はこんな感じ

exec $PHP -C -q -d output_buffering=1 "$0" "$@"

$PHPにphpコマンドの絶対パスが入ってます。$0 は自分自身のスクリプトの名前。 $@は全引数リストということで、execコマンドを約すとこんな感じ

/usr/local/bin/php -C -q -d output_buffer=1 ./phpdoc -t /target/phpdoc -d /parse/inc

これが実行されています。いろんなオプションがあって分かりにくいですが、今度はphpdocファイルがphpスクリプトとして動作しているわけです。

では、phpとして実行した場合に、上半分で書かれたshソースはphpによってどう処理されるのか？

それを、こいつが一発で解決しています。

ob_end_clean();

ぎゃー、こんなの使ったことねぇ＞＜

phpマニュアル : ob_end_clean

関数自体はなんとなく知ってたけど、こんな使い方があったなんて。。。

いやー、書き方が良いか悪いかは別として、こんなテクニックもあるんですね。。。。

どういう利点があるんでしょうか？使いこなすのが難しそうです。

–09/02/03 追記–

生成されたhtmlの文字コードの問題があったので追記。

生成されたhtmlの文字コードがiso-8859-1なので環境に合わせて修正が必要です。今回は利用しているテンプレートがデフォルトであったため、PhpDocumentor/phpDocumentor/Converters/HTML/frames/templates/default/templates ディレクトリにある以下のファイルを修正します。

blank.tpl
header.tpl
index.tpl
top_frame.tpl

これらのcharsetを「iso-8859-1」→「Shift-JIS」に変更し、再度phpdocを実行すると、文字コードが修正されたhtmlが生成されます。

また、毎回あの長いコマンドをたたくのは面倒なので、一つのshファイルにまとめておきました。

ファイル名を updatePHPDoc.sh として

#!/bin/sh
phpdoc -t /target/phpdoc -d /parse/inc

とします。これでコマンドが

$sh updatePHPDoc.sh

となりスッキリしました。

–09/02/03 追記おわり–

当初のお話

実は、当初エラーが出ていた部分は、sh側で

FAILED: Bad environment variable $PHP (set to “/usr/local/bin/php”)

というエラーがでていたので、上記でも書きましたexecを約したコマンド

/usr/local/bin/php -C -q -d output_buffer=1 ./phpdoc -t /target/phpdoc -d /parse/inc

をソース内に加えて強引に実行してましたｗ

で、この話をしようかと思ったら、エラー出ないでやがる！w

まー、shのお勉強にはなったので、よしとするかー

							Tags: [php](/tag/php), [phpDocumentor](/tag/phpdocumentor), [sh](/tag/sh)　

		« [「しりとる」微妙にバージョンアップ](/161/shiritoru_ajax)

		[オレオレライフログを作る](/189/orelifelog_requirement) »

	[画像未復旧: similar.png](http://blog.playispeace.com/img/similar.png) 関連ありそうなエントリー