In this guide we are going to explain how to generate documentation for your application and how to tune it to your liking. phpDocumentor supports a wide range of options related to the generation of documentation that can help you.
Let's start with the minimum that you need in order to run phpDocumentor. In the next few chapters we will be adding more and more options but you can safely ignore those and just use what we describe in this chapter.
When running phpDocumentor there are three command-line options that are essential:
- specifies the directory, or directories, of your project that you want to document.
- specifies a specific file, or files, in your project that you want to document.
- specifies the location where your documentation will be written (also called 'target folder').
The above options are all you need to generate your documentation as demonstrated in this example:
$ phpdoc -d path/to/my/project -f path/to/an/additional/file -t path/to/my/output/folder
For phpDocumentor to work you must specify at least a directory or file to scan, or have this information in a :doc:`configuration<../references/configuration>` file. phpDocumentor won't assume that you want to document the directory from where you run the command.
The target folder is optional but if you omit it then your documentation will be generated in a subfolder, of
your current working directory, called
Before we continue to discuss the other options that phpDocumentor offers we would like to mention that phpDocumentor
supports the use of a Configuration file. All you need to do is add a file called
'phpdoc.dist.xml' to the root of your project, add your options to it and then invoke the
phpdoc command without
phpDocumentor will look in the current working directory for the configuration file and use its contents to determine options such as where your project files are and where to output your documentation.
You can override the settings in the configuration on a per user basis using another file called 'phpdoc.xml'. It is
recommended to prevent committing that file to your code repository using, for example, a
When present, the file 'phpdoc.xml' is used instead of 'phpdoc.dist.xml' and thus does not supplement it.
- You can even specify an alternate location for your 'phpdoc.xml' using the '--config' command-line option.
For more information on the options and format supported by the configuration it is best to consult the Configuration.
Influencing the List of Project Files
- As mentioned in the Quickstart above you can select which directories and files to document using the
-d(for directories and their files) or the
-f(for just single files). You can even provide those options multiple times if you need multiple files or directories.
Sometimes you may want to exclude entire directories, or files from your documentation build because they contain unwanted third-party documentation, or because you just don't need to transform documentation content for certain files in your project. The
--ignoreoption lets you specify what directories and files to exclude from your project.
A basic example of the
--ignoreoption is excluding one or more directories from your project. If you have a 'vendor' directory that is not relevant to your project documentation, you can exclude it by specifying
--ignore "vendor/". Repeat the
--ignoreoption to exclude multiple directories.
If you have a single file in the 'tests' directory that you want to exclude from the documentation build, you can declare it explicitly by specifying
--ignore "tests/excludeme.php". This command will transform all PHP files in the 'tests' directory except for 'excludeme.php'.
--ignoreoption also supports glob patterns to exclude files and directories using wildcards. To ignore all files ending with
test.phpyou can use
Enclose any value for an option that provides a wildcard with double quotes to prevent your command line from interpreting them.
When you want to provide a relative path, keep in mind that this is relative to the Project Root Folder. The project's root folder is the first folder that the provided folders have in common, so for ``-d "src/phpDocumentor,src/SomethingElse" this is the directory "src" and not the current working directory. When in doubt, check the output of phpDocumentor, it mentions the project's root folder after all files are collected.
- By default phpDocumentor will ignore hidden files and will not follow symlinks. This will prevent unwanted documentables and loops in paths. Should you want to document hidden files you can do so by supplying the option
--hidden=off, for traversing symlinks you can provide the option
Customizing the Look and Feel
phpDocumentor offers a wide range of options for changing the look and feel of your documentation but almost all of
them are captured in a template (believe me, you do not want to configure this on the command-line). So, the easiest way
is to pick a template using the option
It is possible to generate output using two templates at once. This can be convenient for generating HTML documentation and Checkstyle XML output at the same time. Generating output for two templates can be accomplished by providing the
--templateoption twice or by using a comma-separated list:
.. code-block:: shell-session
$ phpdoc --template="clean" --template="checkstyle" -d . $ phpdoc --template="clean,checkstyle" -d .
In addition to the options offered by the templates themselves, there are two command-line options to influence the output of your documentation:
- This option changes the name of your 'default', or nameless, package to that of your preference. This way you can, for example, change the default package name to the name of your application.
- This option will change the title in your browser's titlebar and, for some templates, the title text of the template itself. This is a small convenience to personalize the template for your application.
Using a configuration file you can apply more customization to the look and feel of the documentation, please see the chapter on templates for more information on this subject.
- phpDocumentor assumes that your project's files are encoded using UTF-8. If your encoding differs you can use the
--encodingcommand line option to instruct phpDocumentor to expect that.
phpDocumentor is mostly about DocBlocks and processing inline documentation. However it will also collect markers.
In short, a Marker is a single-line inline comment that starts with a single, identifying, word and has a description. Let's take a look at an example to make this less abstract:
// TODO: Move this code to another location
As you can see here, we indicate that a specific piece of code on the following line should be moved. phpDocumentor
collects these markers and generates a report that shows which and where these markers are placed. In the example above
you may notice that there is a colon (
:) after the marker text; this is optional and will be ignored when present.
- By default, phpDocumentor only collects markers that start with TODO or FIXME, as these are the most common, but you can provide an alternative list using the
--markerscommand line option.
TODO markers also get a special treatment; phpDocumentor generates a report detailing which todo items are in your code and uses both the :doc:`../references/phpdoc/tags/todo` tag and the TODO marker to compile this list.