Getting Started With PHP DocBlox

DocBlox is the new defacto PHP class documentation generator. It was developed as an alternative to PHPDocumentor, but it looks as though it will replace it and become the new PHPDocumentor2. As a result I thought I would put together a quick tutorial on getting started.

This post assumes that you know what PHPDoc comments are and that you have a project that you want to generate API documentation for. To get started on PHPDoc take a look at the Wikipedia page on PHPDoc.

Whereas PHPDocumentor would scan and generate all of the code in one go, DocBlox will scan the source code and generate a series of XML files based on the code it finds. It will then use these files to generate the API documentation in a number of different formats, although HTML is probably the most common.

Before you do anything with DocBlox you should first make sure you have the following packages installed:

• PHP-XSL - This is required to convert the XML files into the different formats.
• Graphviz - DocBlox can additionally create an inheritance diagram, which uses the Graphviz package.
• PEAR - The PHP Extension and Application Repository, which is used to package and install DocBlox itself.

All of these packages can be installed easily through apt-get on Linux or even Synaptic package manager on Ubuntu. Windows users will have to install each component manually, but it is still doable.

Installing

To install DocBlox run the following PEAR commands.

pear channel-discover pear.docblox-project.org
pear install DocBlox/DocBlox

You can now see if it is installed by running the command docblox. You should see a help message appear on screen. One thing to watch for is that Docblox will always print out the help message if it had an error, but the error will be printed first before the help output. This caught me out as I was using a small terminal window to run the commands.

Usage

The default action of DocBlox is to scan your code and generate a bunch of XML files that contain the output of the PHPDoc elements found within. These files will also contain any referential data like class ancestry that are used to create class hierarchy diagrams. Docblox takes two default flags, -d is the directory that contains your code and -t is the output directory. The following will parse all of the code found within the current directory and write the output to a directory called output. Docblox will error if it doesn't have access to this directory so it is best to create it and set the permissions before you start.

docblox -d . -t output

You can just parse individual files by doing the following, although this is less helpful as class ancestry is not fully generated.

docblox -f File.php -t output

Once the XML files are generated DocBlox will not need to regenerate them unless the files have changed. This means that any subsequent runs of the docblox command will be much quicker as the XML files have already been generated.

Templates

Now that we have our XML files we can generate the HTML documentation. This requires that we have a HTML template installed. To see what templates are available on your system run the following command.

docblox template:list

For a fresh install there will be a theme called new_black and nothing else. If you want to install a new template then you can grab one from the DocBlox templates page. Run the following to install a new template, taking the template name from the template page.

sudo docblox template:install <template name>

You are now ready to generate the HTML documentation for the project. You can do this by running the following command, adding the --template flag.

docblox --template <template name (eg. abstract)> -d . -t output

Configuration as XML

I have only outlined a few of the command line options in this post, but there are plenty more available. It is also possible to embed these configuration options within an XML file. If you create a file called docblox.dist.xml and place it into your project directory then Docblox will automatically pick up this file and use it.

The following is the default configuration file for Docblox. This is the minimum amount of information needed to get things running with similar results to the above commands.

<?xml version="1.0" encoding="UTF-8" ?>
<docblox>
  <parser>
    <target>data/output</target>
  </parser>
  <transformer>
    <target>data/output</target>
  </transformer>
  <files>
    <directory>.</directory>
  </files>
</docblox>

You can select the configuration file by using the -c or --configuration flag.

Further Information

This is just an initial (and basic) look into Docblox as there is plenty more to look into. If you are interested then further information can be found at the Docblox site, the Docblox documentation and the Docblox templates site.