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.

Screenshot of the output tab on PhpDocumentor

Comments

Hi,
please help me. After I type pear install --alldeps PhpDocumentor
Terminal gives me "No releases available for package "pear.php.net/PhpDocumentator" install failed"

Why pear cannot find PhpDocumentator??
Thank you

I am sorry. I have no problem with this yet. I used "pear install PhpDocumentator" (without --alldeps) and PhpDoc... is now installed. Thanks for good tut and sorry for spam ;)

Unfortunately, I run the same issue.
Removing --alldeps from the command line didn't resolve the issue. I tried to update almost everything (which is a good thing), but it still don't work.
If someone has some advice, it would be much appreciated.
Still, thank you for this tutorial. I love you ;)

Buen dia, quiero felicitar a Liam Green-Hughes por este excelente manual de instalacion y funcionamiento.

Add new comment

Comments are always very welcome, but please note the following:
  • Sadly due to the high number of spam comments recently all comments are now manually moderated. You comment will therefore not appear on the site instantly.
  • Comments on this web site are monitored for spam using Mollom. By posting a comment, you accept that your message and other personal details about you will be analysed and stored for anti-spam and quality monitoring purposes, in accordance with Mollom's privacy policy.
  • Please use your own name not a company or website name to submit comments. Your comment will be removed if you don't do this.
  • All links in comments will be marked with a no follow attribute. That means posting a link to your site here won't help your search engine rankings.
  • By submitting a comment you agree that your comment can be reproduced under the same licensing terms as the rest of the content on the site.
  • Comments can be removed at any time without explanation, but won't be removed just because you disagreed with something I said.