phpDocumentor is meant as a highly configurable and extensible application. As such there are a lot of things that can be configured by the user.
An overview will be given in this chapter where you could place the configuration file and what it needs to look like.
The easiest solution would be to place the configuration file in the root of your project with the name phpdoc.dist.xml. This file can be committed to a Revision Control System and thus will the settings always be available.
When you have added a configuration file then you do not need to provide its location to phpDocumentor; the following command suffices to build your documentation:
$ phpdoc
An additional benefit is that it is possible for each developer to place a file called phpdoc.xml in their project, in addition to the phpdoc.dist.xml. This configuration file will be used instead of the phpdoc.dist.xml and when added as an ignore rule in your VCS it will give developers the ability to have settings other than the project defaults.
Hint
When present, the file ‘phpdoc.xml’ is used instead of ‘phpdoc.dist.xml’ and thus does not supplement it.
Another option is to use the -c or --config arguments to tell phpDocumentor the location of your configuration file. This can be convenient for centralized configuration management or using different settings per environment.
Note
none is a reserved word and providing -c none as option will result in any configuration file being ignored.
phpDocumentor follows the convention over configuration style and as such it is only necessary to specify the options which you want to change with regard to the defaults.
The easiest way to find out what the defaults are is to look in the configuration template, which is located in [PHPDOC FOLDER]/data/phpdoc.tpl.xml or to examine the specifications in this document.
Usually the following configuration suffices for your project:
<?xml version="1.0" encoding="UTF-8" ?>
<phpdoc>
<parser>
<target>data/output</target>
</parser>
<transformer>
<target>data/output</target>
</transformer>
<files>
<directory>.</directory>
</files>
</phpdoc>
The configuration expects you to specify for both what their output(target) folder should be.
Note
By separating the output locations into one for the parser and one for the transformation process it is possible to provide a staging location where you indefinitely store your structure file and benefit from the increased speed when doing multiple runs. This is called Incremental Processing or Incremental Parsing.
The transformer expects the source file to be at the target location of the parser so you need not specify that explicitly.
The files section allows you to specify where the source code for your project is and what files to ignore.
<files>
<file>test.php</file>
<file>bin/*</file>
<directory>src</directory>
<directory>tes??</directory>
<ignore>test/*</ignore>
</files>
It is allowed to use relative paths here; just remember that these are relative from the the location of your configuration file.
It is possible to specify specific files or a specific set of files using the file element. As with the -f parameter it supports wildcards.
In addition you can also provide entire directory trees using the element. This also supports the use of wildcards. Please note that, in contrary to the file element, the directory element is recursive and will tell phpDocumentor to process all files contained in this folder and every subfolder.
In some cases you will have to ignore certain files in your project; examples of these can be third party libraries and/or tests. In this case you can use the ignore element and provide a pattern (not a path) to ignore. Thus if you provide *test* it will ignore any file or directory containing the text test in it.
The starting point or base directory for the ignore directive is the Project Root; which is the highest folder that all files share in common. Thus if you provide a single directory and that does not contain any parseable files and only on subfolder (which does contain parseable files) then the Project Root if not the given folder but the subfolder.
The phpDocumentor configuration file contains the following top level elements which are explained in more detail in the sub-chapters.
The title is a single element used to alter the logo / text section identifying for which project the documentation is generated.
It is possible to use HTML in order, for example, include a logo in the text.
Example
<title><![CDATA[<b>My</b> Project]]></title>
The parser section contains all settings related to the conversion of your project’s source to the intermediate structure format of phpDocumentor (structure.xml).
The following fields are supported:
default-package-name, optional element which defines the name of the default package. This is the name of the package when none is provided.
target, the target location where to store the structure.xml, also used as source location for the transformer. This can be either a relative or absolute folder. Relative folders are relative to the location of the configuration file.
encoding, optional element which defines the file encoding to use.
markers, contains a listing of prefixes used in single line comments to mark a segment of code using a single word (by default FIXME and TODO are supported).
Example:
// TODO: do something
extensions, contains a list of extension’s which a file must have to be interpreted. If a file does not have the extension mentioned in this list then it is not parsed. By default these are: php, php3 and phtml.
Example
<parser>
<target>output</target>
<encoding>utf8</encoding>
<markers>
<item>TODO</item>
<item>FIXME</item>
</markers>
<extensions>
<extension>php</extension>
<extension>php3</extension>
<extension>phtml</extension>
</extensions>
</parser>
The transformer section contains most settings related to the transformation of the intermediate structure format (structure.xml) to a human-readable set of documentation. The format of this set of documentation is determined by the template choice which is present in the transformations head section.
Note
The transformer determines the location of the intermediate structure format (structure.xml) by retrieving the target element in the parser section.
The following fields are supported:
target, the target location where to store the generated documentation files.
external-class-documentation (v0.14.0), with this element you can link the documentation generated by phpDocumentor to the URL of a library based on the prefix of the class. This element may be used multiple times and each time has a prefix and uri element which specify which class to link where. The uri element supports 2 substitution variables: {CLASS} and {LOWERCASE_CLASS}.
Please note that if the class is part of a namespace that the backslashes are also copied; with exception of the ‘root’ (start of the class name).
Example
<transformer>
<target>output</target>
<external-class-documentation>
<prefix>HTML_QuickForm2</prefix>
<uri>http://pear.php.net/package/HTML_QuickForm2/docs/latest/HTML_QuickForm2/{CLASS}.html</uri>
</external-class-documentation>
</transformer>
The logging section contains all settings related to the logging of information in phpDocumentor.
Note
phpDocumentor does not ‘care’ whether the specified logging paths exist; if they do not then no log files are generated.
The following fields are supported:
Example:
<logging>
<level>warn</level>
<paths>
<default>{APP_ROOT}/data/log/{DATE}.log</default>
<errors>{APP_ROOT}/data/log/{DATE}.errors.log</errors>
</paths>
</logging>
The transformations section controls the behaviour applied in transforming the intermediate structure format to the final human-readable output.
The following fields are supported:
template, the name or path of a template to use. This element may be used multiple times to combine several templates though usually you only supply one. Example:
<template name="responsive"/>
<template name="/home/mvriel/phpDocumentor Templates/myTemplate"/>
transformation, it is also possible to execute additional transformations specifically for this project by defining your own transformations here.
Example:
<transformations>
<template name="responsive" />
</transformations>
Please see the previous sub-chapter Basic configuration for a complete description of the files section.
Example
<files>
<file>test.php</file>
<file>bin/*</file>
<directory>src</directory>
<directory>tes??</directory>
<ignore>test/*</ignore>
</files>
<?xml version="1.0" encoding="UTF-8" ?>
<phpdoc>
<parser>
<target>data/output</target>
</parser>
<transformer>
<target>data/output</target>
</transformer>
<files>
<directory>.</directory>
</files>
</phpdoc>
<?xml version="1.0" encoding="UTF-8" ?>
<phpdoc>
<title>My project</title>
<parser>
<target>output</target>
<encoding>utf8</encoding>
<markers>
<item>TODO</item>
<item>FIXME</item>
</markers>
<extensions>
<extension>php</extension>
<extension>php3</extension>
<extension>phtml</extension>
</extensions>
<visibility></visibility>
</parser>
<transformer>
<target>output</target>
</transformer>
<logging>
<level>warn</level>
<paths>
<default>{APP_ROOT}/data/log/{DATE}.log</default>
<errors>{APP_ROOT}/data/log/{DATE}.errors.log</errors>
</paths>
</logging>
<transformations>
<template name="responsive" />
</transformations>
<files>
<file>test.php</file>
<file>bin/*</file>
<directory>src</directory>
<directory>tes??</directory>
<ignore>test/*</ignore>
</files>
</phpdoc>