Jeroen Moors


Documenting your php extension
Written on 18 June 2013

If you’re working on Open Source, documentation is king! However the process of creating documentation for a PHP C or C++ extension itself is not very well documented.

You’ve got some official source like a howto, some specific info for pecl. The official docs are or outdated or pointing in different directions. A found a good blog post by Kristina Chodorow, but it’s a bit out dated and still leaves out some steps. So here it is, an (other) attempt to a step-by-step guide for documenting your PHP extension written in C or C++.

Create a working environment

Create a working directory and move in to it.

mkdir ~/phpdoc
cd ~/phpdoc

Checkout the existing php documentation and its tools.

svn checkout phpdoc

Install required software

Mare sure you’ve installed the sqlite3 extension, required for PhD to work. On Debian or Ubuntu, use:

apt-get install php5-sqlite

Install PhD, the PHP Document generator:

pear install --alldeps

Generate a docbook skeleton

Make sure your PHP extension is loaded. If it’s loaded the provided docgen.php script will use reflection to create a basic docbook files.

Replace my_extension with your extension name.

php ~/phpdoc/phpdoc/doc-base/scripts/docgen/docgen.php --output ~/phpdoc/phpdoc/en/reference/my_extension --extension my_extension

Update the main index

Add your extension to the master docbook file used to identify all available chapters.

Edit ~/phpdoc/phpdoc/doc-base/manual.xml.

nano ~/phpdoc/phpdoc/doc-base/manual.xml

Search for a section that matches the type of your extension. For example if it’s a database extension, move below the following tag:


Add a line in this section:


Prepare the docbook files

Prepare the xml files you’ve generated and modified in the previous steps.

php ~/phpdoc/phpdoc/doc-base/configure.php --with-partial=my_extension.rados

If configure.php generates any errors, fix them. It could be as easy as commenting out some lines with references to non-existing files.

Generate HTML

Generate an HTML file from the XML-files.

phd -d ~/phpdoc/phpdoc/doc-base/ -o ~/phpdoc/docs/

Pimping your HTML

By default no CSS is used in the html-output. You can easily create a look and feel by downloading a style sheet from the site and include it in your html file.

cd ~/phpdoc
phd --css ~/phpdoc/site.css -d ~/phpdoc/phpdoc/doc-base/ -o ~/phpdoc/docs/