phpdox

Display an annotated skeleton configuration XML file

$ phpdox --skel

$ phpdox

$ phpdox [[-f|--file]] [path/to/phpdox.xml]

$ phpdox [[-c|--collector]]

$ phpdox [[-g|--generator]]

phpdox [OPTIONS]

--file <file>
    Specifies an alternative XML configuration file to use, overriding the default phpdox.xml.

--source <path>
    Sets the source directory containing PHP files to be analyzed, overriding the configuration file's setting.

--output <path>
    Defines the directory where the generated documentation will be stored, overriding the configuration.

--template <path>
    Specifies a custom template directory or file to use for rendering the documentation.

--bootstrap <file>
    Includes a PHP file before the documentation generation process begins. Useful for custom autoloaders or environment setup.

--force-build
    Forces phpdox to perform a complete rebuild of the documentation, ignoring any cached data.

--config-only
    Validates the phpdox.xml configuration file and exits without generating documentation.

--skip-build
    Parses source code and generates the XML index but skips the actual documentation generation process.

--quiet
    Suppresses informational output, only showing warnings and errors.

--silent
    Suppresses all output, including warnings and errors.

--version
    Displays the phpdox version information and exits.

--help, -h
    Shows a help message detailing command-line options.

phpdox is a powerful and flexible documentation generator specifically designed for PHP projects. Unlike some other tools, it focuses on statically analyzing your PHP source code to extract API documentation without requiring external runtime execution. Its primary strength lies in generating an intermediate XML representation of your project's structure and DocBlocks, which can then be transformed into various human-readable formats like HTML, LaTeX, or Markdown using different templates or XSLT stylesheets.

It aims to provide a more streamlined and less configuration-heavy experience compared to some predecessors, making it ideal for integration into automated build processes and continuous integration/delivery (CI/CD) pipelines. By default, phpdox reads its configuration from a phpdox.xml file located in the project root, allowing for highly customizable documentation generation workflows.

phpdox relies heavily on the proper structuring of your PHP DocBlocks (e.g., PSR-5 conventions) for accurate documentation extraction. While it offers flexibility through its XML output, custom transformations require knowledge of XSLT or the chosen template engine (e.g., Twig). Complex projects will almost always require a dedicated phpdox.xml configuration file, as command-line options are primarily for overrides.

The central element for phpdox operation is the phpdox.xml configuration file, typically located in your project's root directory. This XML file defines everything from source code paths, output directories, excluded files, and custom templates to advanced settings for specific generators (e.g., HTML, XML). It allows for fine-grained control over the documentation generation process.

While phpdox can directly generate HTML documentation, its core strength lies in producing a rich XML representation of your code's API. This XML output can then be transformed using XSLT or other templating engines (like Twig) into virtually any desired format, such as custom HTML layouts, LaTeX for PDF generation, or Markdown for READMEs. This 'transform-from-XML' approach provides superior customization and integration possibilities.

phpdox is designed to be easily integrated into PHP's popular build and dependency management tools. It's commonly run as a Composer script (e.g., defined in your composer.json's scripts section) or as a task within a Phing build file. This enables automated documentation updates as part of your project's build or deployment process.

phpdox emerged as an alternative to more monolithic PHP documentation tools, aiming for simplicity, speed, and better integration into modern PHP development workflows. Its development focused on generating a machine-readable XML intermediate format, providing unparalleled flexibility for various output formats. It has become a popular choice for developers looking for a robust, configurable, and automated documentation generation solution, especially within CI/CD environments.

phpdoc(1), composer(1), git(1), xmlstarlet(1)