Custom nodes

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

A directive does not render anything by itself: it only describes what should end up in the document, as a . Rendering that node into HTML (or any other output format) is a separate step, handled by a Twig template as described in Node templates.

This separation keeps parsing and rendering independent from each other, so the same node can be rendered differently per output format without having to touch the directive at all.

read first how to setup an phpDocumentor extension, and Custom directives before you continue this guide.

Continuing the .. hello:: example from Custom directives, our node simply needs to carry the name that was passed to the directive so that a template can use it later:

<?php

declare(strict_types=1);

namespace phpDocumentor\Example\Nodes;

use phpDocumentor\Guides\Nodes\AbstractNode;

/** @extends AbstractNode<string> */
final class HelloNode extends AbstractNode
{
    public function __construct(string $name)
    {
        $this->value = $name;
    }

    public function getName(): string
    {
        return $this->value;
    }
}

Nodes extend , which already takes care of common concerns such as options (:option: value on the directive) and CSS classes. The only thing our HelloNode adds is a convenient getName() accessor around the value that is stored by the base class.

If your directive needs access to information gathered elsewhere in the project, for example data from the parsed API documentation, look at . It is a more advanced base node that gives you access to a Descriptor , and is outside the scope of this guide.

With a node in place, the last step is telling phpDocumentor how to render it, which is what Node templates covers.