phpDocumentor v3: caching your PHP structure before it writes a single HTML page

The structure cache is the product, not the HTML

phpDocumentor does not parse your code and write a website in one pass. It generates a cache with the application structure first, and rendering reads from that cache. The README calls this the two-step process and notes the cache can power your own tools or formatters. That design choice has consequences worth understanding before you install anything.

The README also lists low memory usage: peak memory is given as under 20MB for small projects, 40MB for medium ones and 100MB for large frameworks. The second payoff is incremental parsing: if you keep the Structure file from a previous run, the README claims an additional performance boost of up to 80 percent on top of the base processing speed gain. Both numbers come from the project's own documentation rather than from an outside benchmark.

Because the cache is a file you keep, deleting it between runs throws away the incremental path. In CI that usually happens anyway, so the incremental claim applies most to a local documentation workflow or a pipeline that caches artifacts between jobs.

DocBlocks as the only input, and generics phpdoc could read first

The API documentation is generated from PHP source and DocBlock comments. Whatever a class or function says about itself in a DocBlock is what ends up on the page, and whatever it omits is absent.

Three details change what that means in practice. Docblock over types means a docblock can express a type that PHP itself cannot parse natively, and phpDocumentor renders it rather than discarding it. Shows any tag means unrecognised tags survive into the output, and some tags add behaviour, with @link given as the example. Generics support means that as static analysis pushes PHP types toward more complex shapes, the tool treats generic types as first class types instead of flattening them to strings.

Namespaces, closures and the rest of PHP 7 syntax are covered.

Three installation routes, and the one the maintainers argue against

There are four documented routes. Phive is the recommended one and pins a GPG key:

$ phive install phpDocumentor --trust-gpg-keys 6DA3ACC4991FFAE5

That installs the tool as an isolated phar dependency, and you run it from the tools directory:

$ php tools/phpDocumentor

The manual route is to download the phar file from the releases page and run it directly:

$ php phpDocumentor.phar

Docker is the third option, and the published image is a real multi-stage build rather than a wrapper. The base stage is php:8.4-trixie with openjdk-21-jre-headless, and the phpdoc_base stage writes memory_limit=-1 into a phpdoc.ini before setting /opt/phpdoc/bin/phpdoc as the entrypoint.

$ docker pull phpdoc/phpdoc
$ docker run --rm -v $(pwd):/data phpdoc/phpdoc

That last point is the one to notice. phpDocumentor requires PHP 8.1 or higher to run, while source from earlier PHP versions can still be analysed. The image runs PHP 8.4 against the /data volume you mount.

Composer is available and officially not endorsed

A phpDocumentor package exists on Packagist, and the README tells you so directly before telling you not to use it. The reasoning is dependency conflicts. phpDocumentor's own libraries are consumed by countless other libraries and applications, with two of them past 150 million downloads each, so the odds that one of its dependencies collides with yours are described as high.

For a tool that runs in CI to generate documentation, that reasoning holds. Pulling phpDocumentor into your project runtime means your library now inherits a large transitive tree it does not need at request time, and any conflict surfaces as a version resolution problem in your own composer.json rather than as a documentation problem.

Use the phar. If your organisation requires everything through Composer, that is a policy conflict you have to resolve deliberately, not a default worth inheriting.

Running it: source directory in, HTML out

The basic invocation takes a source directory and a target directory:

$ phpdoc run -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY>

The option surface is large enough that the README points you at the built-in help rather than reproducing it:

$ phpdoc run -h

For anything beyond a one-off run, configuration files matter. phpDocumentor reads phpdoc.xml or phpdoc.dist.xml by default, and the repository ships its own phpdoc.dist.xml at the root, so you have a working example to copy rather than an empty file to fill in.

Class diagrams are opt-in. All bundled templates can render class diagrams from the read code base, but that needs PlantUML installed on the machine running the tool. Without it the run still succeeds: warnings about missing PlantUML can be ignored, though the resulting documentation will contain dead links where the diagrams were meant to be. The flag that turns diagrams on is:

$ phpdoc run --setting=graphs.enabled=true

RestructuredText and Markdown in, but only one language for the guides themselves

The parser handles RestructuredText and Markdown. The README frames this as a choice of markup per project.

The sharper feature is cross-inclusion. phpDocumentor can pull parts of the generated API documentation into your RestructuredText guides, so a signature table in a hand-written page can track the code instead of drifting from it. That is the mechanism aimed at projects with a real guides site.

The README describes this inclusion for RestructuredText documentation.

What to check before you commit, and what the alternatives do instead

Two things decide whether this tool earns its place. First, class diagrams silently degrade to dead links if PlantUML is missing, and the README treats that as ignorable, which means a pipeline can pass while publishing broken pages. Check your generated output for dead links rather than trusting the exit code. Second, there are no nightly releases: bleeding-edge testing means downloading a phar artifact from the Actions tab of a successful QA workflow, which is a manual step outside a normal dependency update path.

Alternatives approach the job differently. Doxygen is language-agnostic and configured by a single file with a comment convention rather than requiring DocBlocks on PHP objects; it also needs a separate rendering tool for its own diagram output. A general documentation platform such as Read the Docs hosts and builds your docs, including Sphinx-based ones, but it produces prose sites rather than an object-by-object API reference derived from source.

phpDocumentor is built for source-derived API reference and also parses RestructuredText and Markdown guides; if you need per-class and per-method pages generated from the code itself, phpDocumentor is the direct fit.

Editorial conclusion

Adopt phpDocumentor if you publish a PHP library or framework and want HTML API docs generated from DocBlocks, and install it with phive or the phar so its dependency tree stays away from yours. If your documentation is mostly prose that borrows a few API signatures, its RestructuredText inclusion mode is built for that. The last push was on 2026-11-02 and v3.10.0 shipped on 2026-05-13 under the MIT licence. The Dockerfile for the published image sets memory_limit=-1.

Frequently asked questions

Official sources

1. License: MIT
2. phpDocumentor/phpDocumentor on GitHub
3. Project website
4. README
5. Releases