Extensions

This feature is still under development and only available in the nightly docker builds.

Not sure what extensions are or how to install one? Read the extensions feature overview first.

Write your own extension

To write your own extension you need to create a folder in the extensions folder with the name of your extension. In our example we use Example as the name of our extension. The namespace of your extension is free to choose.

First you need to create a manifest file called manifest.xml . This file contains the extension information:

<?xml version="1.0" encoding="utf-8" ?>
<phar xmlns="https://phar.io/xml/manifest/1.0">
    <contains name="phpDocumentor\Example" version="1.0" type="extension">
        <extension for="phpdocumentor/phpdocumentor" compatible="^3.5"/>
    </contains>

    <copyright>
        <author name="You" email="[email protected]"/>
        <license type="MIT" url="https://github.com/phpdocumentor/phpdocumentor-example-extension/blob/1.0.0/LICENSE"/>
    </copyright>

    <requires>
        <php version="^8.1"/>
    </requires>

    <bundles>
        <component name="phpDocumentor\Example\Extension" version="1.0" />
    </bundles>
</phar>

The bundles section contains the class that should be loaded when the extension is loaded. This class must extend Extension . And should not contain any other logic rather than registering services.

Under the hood PhpDocumentor uses the Symfony Dependency Injection component. You can find more information about this component in the Symfony Dependency Injection documentation. This also shows how to register services. We are using the DI extensions of Symfony to register services. Like bundles do in a Symfony application.

Autoloading

The directory of the extension is added to the autoloader. So you can use the autoloader to load classes in your extension. Please note that the autoloader is not accessible by the extension itself. So you cannot add classes yourself to the autoloader. This is done by phpDocumentor following the PSR-4 standard. The root namespace is the name of the extension. So in the example above the root namespace is phpDocumentor\Example .

By using the same autoloader as the application itself you have access to all classes that are loaded by the application. Services that are registered in the application can be used in the extension.

Extension points

phpDocumentor is still under active development, so extension points might change without warning. The following extension points are currently available and documented:

Twig extensions, to customize the rendering of output.
Custom directives, to add new RestructuredText directives, together with custom nodes and node templates to render them.

Common use-cases