« Munich
Mrs Henderson Presents »

Installing PhpDocumentor

April 2nd, 2006

Highly recommend PhpDocumentor. I won’t explain what it is, since it’s pretty self evident: it documents your PHP code. Oops–just explained it.

Their site is slightly fudged but don’t let that put you off. The easiest way to install it is through PEAR. You can either use it through the command line, or through the (again) slightly fudged web-based interface. It’s slightly awkward to get going, but once you understand how it works–it works. So first off create a PEAR directory on your server so that it has something to install to:

cd /path/to/public_html
mkdir pear

Next set it as a default data directory:

cd /path/to/php/bin
./pear config-set data_dir /path/to/public_html/pear

Next some magic:

./pear install --alldeps phpdocumentor
Failed to download pear/phpdocumentor within preferred state "stable", latest release is version 1.3.0RC5, stability "beta", use "channel://pear.php.net/phpdocumentor-1.3.0RC5" to install
Cannot initialize 'phpdocumentor', invalid or missing package file
Package "phpdocumentor" is not valid
install failed

Oops, so change it to:

./pear install --alldeps channel://pear.php.net/phpdocumentor-1.3.0RC5

Now that everything’s installed, load up your browser to “localhost” and navigate to your data directory, which should be something like “http://localhost/pear” then click on phpdocumentor. You’ll be presented with the main web-based interface. Here are some quick start steps to using it:

  1. Put some tags into your code
  2. Create a temporary directory in /tmp or something and give the directory read/write access to the user that runs PHP, in my case it’s “chown nobody docs”. You can find out who runs PHP by doing a phpinfo() and searching for “User/Group”
  3. In the web-based interface click on “Files” and enter the pathnames to the things you want docs to be generated from.
  4. Then click “Output” and enter the pathname to the temporary directory you created.
  5. Clear anything in the “Output Format” box underneath and select the style you want from the drop down box → Click “Add the converter in the help box”
  6. Move onto “Options” → type in and check the boxes as required; it’s self explanatory.
  7. Finally click “Config” → “Go”. You don’t usually need to change the default config files.
  8. Voila! Your documentation should be available in your /tmp/docs directory.

Some of the designs can look quite gnarly, so here’s what I do:

  1. Use HTML:frames:phpdoc.de as the “Output Format”.
  2. Open up “index.html” with a text editor.
  3. Change the frameset row size to “75,*”
  4. Change all the frameborders to equal “0″

Filed under: PHP by Alex at 8:16 pm | Trackback

Comments are closed.