phpDocumentor

Node templates

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

Once you have a directive and a node, the final step is telling phpDocumentor how to render that node. phpDocumentor uses Twig templates for this, one template per node class (and per output format).

First we write a Twig template for our HelloNode . Inside the template, node refers to the node instance, so any public getter on the node (like getName() ) is available as node.name :

<p class="hello-directive">Hello, {{ node.name }}!</p>

Register the template

Templates are registered in your extension's Extension class rather than through services.php , because two container parameters need to be updated: the list of directories Twig should look for templates in (phpdoc.guides.base_template_paths ), and the mapping from node class to template file (phpdoc.guides.node_templates ):

<?php

declare(strict_types=1);

namespace phpDocumentor\Example;

use phpDocumentor\Example\Nodes\HelloNode;
use Symfony\Component\Config\FileLocator;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Loader\PhpFileLoader;

use function phpDocumentor\Guides\DependencyInjection\template;

class Extension extends \phpDocumentor\Extension\Extension
{
    public function getAlias(): string
    {
        return 'phpdoc:example';
    }

    public function load(array $configs, ContainerBuilder $container)
    {
        $loader = new PhpFileLoader($container, new FileLocator(__DIR__ . '/Resources/config'));
        $loader->load('services.php');

        // Make our own templates directory known to the Twig loader
        $baseDirs = $container->getParameter('phpdoc.guides.base_template_paths');
        $baseDirs[] = __DIR__ . '/Resources/templates/html';
        $container->setParameter('phpdoc.guides.base_template_paths', $baseDirs);

        // Tell the renderer which template belongs to our node
        $templates = $container->getParameter('phpdoc.guides.node_templates');
        $templates[] = template(HelloNode::class, 'hello.html.twig');
        $container->setParameter('phpdoc.guides.node_templates', $templates);
    }
}

The template() helper builds the array structure phpDocumentor expects for a template mapping: which node class it applies to, which template file to use, and, optionally, for which output format (html by default).

With the template registered, .. hello:: World will render as Hello, World! wherever it is used in your documentation.

Search results