phpDox – The PHP Documentation Generator

Getting Started

In this tutorial you will learn how to download, configure, and run phpDox.

Download

We distribute a PHP Archive (PHAR) that contains everything you need in order to use phpdox. Simply download it from here and put it into your $PATH, for instance:

➜ wget http://phpdox.de/releases/phpdox.phar

➜ chmod +x phpdox.phar

➜ mv phpdox.phar /usr/local/bin/phpdox

➜ phpdox --version
phpDox 0.8.0 - Copyright (C) 2010 - 2015 by Arne Blankerts

You can also immediately use the PHAR after you have downloaded it, of course:

➜ wget http://phpdox.de/releases/phpdox.phar

➜ php phpdox.phar --version
phpDox 0.8.0 - Copyright (C) 2010 - 2015 by Arne Blankerts

Alternatively, you may use Composer or the PEAR Installer to download and install phpDox as well as its dependencies.

Configure

You need to write an XML configuration file (commonly named phpdox.xml) for your project in order to use phpDox. The phpdox --skel command helps with this task by generating a skeleton configuration file.

For the purpose of this tutorial we use the following minimal example:

<?xml version="1.0" encoding="utf-8" ?>
<phpdox xmlns="http://xml.phpdox.net/config">
  <project name="Example" source="${basedir}/src" workdir="${basedir}/build/api/xml">
    <collector backend="parser" />
    <generator output="${basedir}/build/api">
      <build engine="html" output="html"/>
    </generator>
  </project>
</phpdox>

In the configuration file shown above we configure the following:

  • This is the phpDox configuration for project "Example"
  • The sources are in the ${basedir}/src directory
  • The workdir (where the XML representation of the sourcecode is cached) is ${basedir}/build/api/xml
  • We want to use the parser (for PHP-Parser) backend as our collector
  • We want to render output using the html generator and have the result put into the ${basedir}/build/api/html directory

The ${basedir} variable is resolved to the directory that contains the configuration file.

Run

When you invoke phpDox in a directory that has a file named phpdox.xml it will automatically be used:

➜ phpdox
phpDox 0.8.0 - Copyright (C) 2010 - 2015 by Arne Blankerts

[06.04.2015 - 10:00:02] Using config file './phpdox.xml.dist'
[06.04.2015 - 10:00:02] Registered collector backend 'parser'
[06.04.2015 - 10:00:02] Registered enricher 'build'
[06.04.2015 - 10:00:02] Registered enricher 'git'
[06.04.2015 - 10:00:02] Registered enricher 'checkstyle'
[06.04.2015 - 10:00:02] Registered enricher 'phpcs'
[06.04.2015 - 10:00:02] Registered enricher 'pmd'
[06.04.2015 - 10:00:02] Registered enricher 'phpunit'
[06.04.2015 - 10:00:02] Registered enricher 'phploc'
[06.04.2015 - 10:00:02] Registered output engine 'xml'
[06.04.2015 - 10:00:02] Registered output engine 'html'
[06.04.2015 - 10:00:02] Starting to process project 'phpDox'
[06.04.2015 - 10:00:02] Starting collector
[06.04.2015 - 10:00:02] Scanning directory '/usr/local/src/example/src' for files to process

{....}

[06.04.2015 - 10:00:03] Saving results to directory '/usr/local/src/example/build/api/xml'
[06.04.2015 - 10:00:04] Resolving inheritance

{....}

[06.04.2015 - 10:00:04] The following unit(s) had missing dependencies during inheritance resolution:
[06.04.2015 - 10:00:04] Collector process completed

[06.04.2015 - 10:00:04] Starting generator
[06.04.2015 - 10:00:04] Loading enrichers
[06.04.2015 - 10:00:04] Enricher Build Information initialized successfully
[06.04.2015 - 10:00:04] Enricher GIT information initialized successfully
[06.04.2015 - 10:00:04] Enricher CheckStyle XML initialized successfully
[06.04.2015 - 10:00:04] Enricher PHPMessDetector XML initialized successfully
[06.04.2015 - 10:00:04] Enricher PHPLoc xml initialized successfully
[06.04.2015 - 10:00:04] Enricher PHPUnit Coverage XML initialized successfully
[06.04.2015 - 10:00:04] Starting event loop.

{....}

[06.04.2015 - 10:00:12] Generator process completed
[06.04.2015 - 10:00:12] Processing project 'phpDox' completed.


Time: 10.8 seconds, Memory: 11.25Mb

You have learned how to download, configure, and run phpDox.