How to install PhpDocumentor on Ubuntu

We all know that it is important to write documentation for our code. It is not the most exciting aspect of programming but sadly it is needed for those times when we have to fix or change something six months after writing it and have no recollection of how the code works or maybe of writing it at all. Fortunately there is help at hand, you can document a lot of your PHP code semi-automatically with a handy tool called PhpDocumentor. If you have programmed in Java before and used Javadoc this will be very familiar to you. It is not readily available pre-packaged through apt, but fortunately it is reasonable straightforward to install.

The idea of PHPDocumentor is to use tags in specially formatted comments in your code to document what is going on, for example you might document a what a function does, its parameters and what sort of variable it returns. PHPDocumentor will then read through your code and extract this information to build an HTML or PDF file containing this information in an easy to use format meaning that you can find this information again without having to look through lots of code. Your code might look something like this with the extra information added:


/**
* Check stock level for an item number
* @param int $item_number Six digit stock number as used by stores dept
* @return int Number of items currently in stock
*/
function get_stock_level($item_number) {
// some code
return $stock_level;
}


Note the double asterisk (this tells PhpDocumentor it should extract information from this block) in the comment block and the @param and @return tags describing what is expected by our function and what is going to come out. There are lots of tags available and you can generate quite detailed documentation for your code. For a complete list and a tutorial have a look at the PhpDocumentor manual at: http://manual.phpdoc.org/.

PhpDocumentor is written in PHP and is designed to be used through a browser to configure its many options. It will also need a location writeable by the web server where it can put the files it generates for your project. The first step is to make sure you have PHP and the Apache web server already installed on your development machine. If you are writing PHP code it is very likely you have already done this! If not enter this in a terminal (Apache is a dependency of the libapache2-mod-php5 package so it will be installed automatically):

sudo apt-get install libapache2-mod-php5

Restart Apache to make sure that it picks up the PHP installation (otherwise you might find your browser will prompt you to download the PHP file rather than it being run on the server!):

sudo /etc/init.d/apache2 restart

Rather than doing a manual download and install we will get PhpDocumentor through PEAR, which is a repository of PHP extensions. We will need to install the php-pear package first to make this possible:

sudo apt-get install php-pear

By default Apache will look at the /var/www directory for web content so before installation we should tell PEAR that this is where we want PhpDocumentor to go:

sudo pear config-set data_dir /var/www

Now we can install PhpDocumentor and also any dependencies it needs:

sudo pear install --alldeps PhpDocumentor

Before using PhpDocumentor we need to make an output directory. You can also put this under the /var/www directory, I am going to use a name of “PhpDocumentor-output”:

sudo mkdir /var/www/PhpDocumentor-output

We also need to change the owner of this directory to www-data as this is the user name Apache runs under and thus PhpDocumentor can only output to directories where this user has write permission:

sudo chown www-data /var/www/PhpDocumentor-output

If you navigate to http://localhost/PhpDocumentor/ (note that the URL is case sensitive) you will find the installation ready to run. In the Files tab enter the files you want to generate documentation for. In the Output tab's target box put /var/www/PhpDocumentor-output/ and then add on the name of your project, e.g. /var/www/PhpDocumentor-output/myproject. You can add output formats you want to generate by selecting them in the drop down box and clicking on Add the converter in the helpbox. If you click on the Create button your documentation should get generated and you be able to navigate to the result by going to: http://localhost/PhpDocumentor-output/ . You can of course copy the resulting files from the output directory and publish them wherever you wish.