phpDocumentor is a tool written in PHP to create complete documentation directly from both PHP code and external documentation. Well-written PHP source code practically serves as its own documentation. phpDocumentor taps into this by examining code for all kinds of structural hints, such as files, classes, functions, constant definitions, global variables, and class variables/methods. From this, it creates basic documentation in a traditional manual format. Note that you will need at least version 1.3.0 of phpDocumentor to include source code elements introduced in PHP 5 (class constants, interfaces, and others).

Output from phpDocumentor can be created for remote web browsing, print, and integration into IDE help systems through converters for HTML, and PDF.

In addition to the intrinsic structure of PHP code, phpDocumentor generates manual-format documentation from special PHP comments called DocBlocks. These comments contain additional information in a well-defined format to help describe code elements e.g. what the parameters required by a function are for.

Start by downloading phpDocumentor from source forge. Extract the archive somewhere suitable such as your home directory, then set the phpdoc script to executable. You may also need to convert the line endings in this file to Unix, which you should be able to do by opening it in gedit. Alternatively, there is a web interface supplied in the archive, which you can use if you have a PHP web server available and you are the sort of girl who can't cope with the command line e.g. you use phpMyAdmin rather than the MySQL CLI client.

Real men, however, can run the script by typing /path/to/phpdoc/phpdoc at the command line. You need to set certain options in order to tell phpdoc where to find the code you're generating documentation for, and where you want the output documentation to be placed: There are a couple of things to be aware of when using this program, which I've described below.

FAILED: Bad environment variable $PHP (set to "/usr/bin/php")

In the event that the PHP interpreter dies during the documenting process, phpdoc clumsily assumes that the interpreter was not found, and will issue the above error. This can be very misleading if you aren't expecting it, as the environment variable is often not the problem.

A much more common reason that phpdoc will die during a run is that it has run out of memory. phpdoc generates the full tree from all source files before it starts creating output documentation, and so as you can imagine this makes it rather memory hungry.

To increase the memory limit used by phpdoc, you can either increase the global limit defined in php.ini, or you can change phpdoc's config file. In most cases the latter is the preferable option, and you'll find the config file in phpdoc's root directory with the name phpDocumentor.ini.

Open this file and find the line that sets the value for memory_limit, and set it to something large. I used 2048M.

Ignoring Files and Folders

You can tell phpdoc to ignore certain files using the -i option. You can specify multiple files this way by separating them with a comma. Note that you must specify a RELATIVE path with respect to the top-most directory in your "directory" value, and to specify a folder to ignore (as opposed to a file) you MUST use a trailing slash. You can also use * and ? wildcards. Not only does this option let you avoid your documentation including 3rd party code you may have in a project, but it also means phpdoc uses less memory during a run.

So for instance, say your project code is at /path/to/source, but you want to ignore the tree below /path/to/source/ignore/this/folder, you would use the following (note the absence of a leading forward slash at the start of the ignore path and the presence of a trailing one at the end):

More phpdoc Options

By default, the HTML documentation is given a title of 'Generated Documentation'. You can change this with the -ti [title] option.

The -ue option will generate warnings as it parses the source code for each undocumented element it finds ie those that are missing a DocBlock, which is useful for checking compliance.

Finally the -q option (for quiet) suppresses progress messages as phpdoc does its thing. This does include warnings and errors too though - look in the errors.html file for information about those.

phpdoc Themes and Templates

phpdoc can generate documentation based on different templates, and you can even find some of these on the web if you want something different from the default. Try the ones mentioned on this guy's page.

PHP Static Analysis

There are an increasing number of tools available for performing static analysis of an existing PHP codebase, in order to help appraise the code and help locate maintenance and performance bottlenecks. Here are the ones I've used.

Do note the slightly different syntax for ignoring directories - pdepend uses --ignore=path1,path2 (with an equals sign), while the others use --exclude path1,path2 (no equals sign).

PHPMD - PHP Project Mess Detection

Best way to install this is through PEAR, by following the instructions at this page. This program produces reports in plain text, XML or HTML format based on metrics such as cyclometric complexity, NPath complexity, code length (class / method size), and so on.

PHPCPD - PHP Copy/Paste Detection

Another piece of kit from Dereck Rethans, most famous for XDebug. Install thru PEAR thusly: This program analyses the code you point it at, and generates a report detailing all instances of duplicate code it found:

pDepend

PHPMD above is actually just a front-end for this program, and if you want access to the raw metrics it produces you can run it directly. The report it produces is a rather opaque XML file - perhaps there's a good XSL stylesheet somewhere to convert it to HTML, but I've not found one as yet. If you've installed PHPMD as above, this will already be available, and all you need to do is run it: As well as the XML report created at the location given by --summary-xml, there will also be a couple of groovy looking SVG charts generated. Check out the PHPDepend site for what the stats all mean.