Architecture

Rendering a Twig template requires several things: First, the template needs to be found by a loader, that knows where to look for the template based on the given name. Then, the template’s source code is put through a parsing and compilation stage, which translates it to PHP code. Finally, the resulting PHP document is executed with the given parameters as context.

For a more detailed description of the Twig internals, head over to the official Twig docs. In this article, we are focusing on the various Contao-specific changes and extensions, that take place in every of these steps:

1. How does our own loader, the ContaoFilesystemLoader, work?
2. Where to put templates and how to name and structure them?
3. What does encoding mean and what is special in this regard with Contao?
4. What about interoperability with legacy templates?
5. Can I use modern templates in a 4.13/5.* extension?

Contao Filesystem Loader

The core of Twig is the Twig\Environment class. You get an instance of it, when using the @twig service in Symfony and you typically use it to render a certain template, identified by a distinct name, together with an array of parameters:

$twig->render("@Foo/bar/baz.html.twig", $params);
                        ↑                 ↑
                   Logical name       Parameters

The environment class itself does not know anything about your template files. Instead, it delegates retrieving the template source to a loader. Looking closer, you find, that there is a special loader, called a chain loader in Symfony, which holds a list of multiple loaders and asks one after another until the request can be answered. Contao makes use of this and adds its own ContaoFilesystemLoader to the chain, that reads template files from Contao specific locations on the filesystem.

Templates are identified by the logical name (the fully qualified template name, you could say). In order to make them unique across different vendors, namespaces are used. Namespaces are denoted by an @ sign and form the first part of the logical name.

$twig->render("@Foo/bar/baz.html.twig", $params);
                ↑        ↑         ↑  
           Namespace Identifier Extension

Default Symfony behavior

The default filesystem loader in a typical Symfony application looks at the root templates directory and groups all files found there under an app-specific @__main__ namespace. Also, the contents of directories inside templates/bundles will each be put under a @<directory> namespace. And finally, templates from bundles are also each put under a @<bundle-name> namespace.

There is a specific order and the loader will only use the first template that fits the requested logical name. That is why you can overwrite templates of the FooBundle by putting them in the templates/bundles/FooBundle directory: you made the loader return early when finding your template instead of the original one in said namespace.

You might have noticed, that bundle templates also get put under a second @!<bundle-name> namespace (prefixed with an exclamation mark). In Symfony, this is used to allow overwriting a template while also extending the original one. Think about how you would reference the original template: Without the second namespace, the loader would always return the replacement, as it wins over the original one. But now, what happens if two extensions (or an extension and the application) use this trick without knowing each other? Spoiler alert: it’s an issue and the reason why we invented the managed namespace concept.

Managed namespace

Symfony’s standard way has a big drawback for us: If multiple parties (e.g. extensions and/or the application) want to adjust the same template, they must know each other and explicitly target their namespaces. Otherwise, when overwriting, only the first party would win. Contao’s answer to that is called the “managed namespace” or @Contao namespace, where this problem does not occur.

Our ContaoFilesystemLoader puts every template from a Contao template directory under the following namespaces (don’t worry, you don’t have to remember this):

Optionally, you can return the path to your bundle from getPath() method in your bundle class. Starting from Symfony 6.1, this is done automatically if your bundle class extends AbstractBundle. Otherwise, you need to implement it yourself. See Symfony docs for more details.

# /vendor/foo/bar/src/FooBarBundle.php

// Symfony "<=6.0"
class FooBarBundle extends Bundle
{
    public function getPath(): string
    {
        return dirname(__DIR__);
    }
}

// Symfony "^6.1"
use Symfony\Component\HttpKernel\Bundle\AbstractBundle;

class FooBarBundle extends AbstractBundle
{
}

This allows your template namespaces to be discovered by Contao and Symfony from directories relative to the bundle path your method returns:

But, you guessed it, there is yet another namespace called @Contao, and that is the one primarily used in Contao. The loader also puts every template from the above Contao namespace directories into this namespace but this is mainly for better static analysis. The real magic happens at compile time: We replace each usage of the @Contao namespace inside any extends, include, embed or use tag with a more specific namespace from the above table. This happens automatically — you don’t have to do anything for it.

 {% extends "@Contao/content_element/text.html.twig" %}
                 ↓
 {% extends "@Contao_ContaoCoreBundle/content_element/text.html.twig" %}

Instead of one single unique template per logical name, you now get a hierarchy of templates. First come the app’s global and main template directory (see above), then those of all bundles in inverse loading order (if you are loaded later, you’re first). The replacement logic uses the hierarchy to always choose the next logical representation that exists (potentially skipping over levels).

By the way: Theme templates, though considered the most specific, are somewhat special in that regard. For more details, please refer to their own section further down.

<h1>Some simple text</h1>
{% block content %}
    <p>{{ text }}</p>
{% endblock %}

{% extends "@Contao/simple_text.html.twig" %}

{% block text %}
  {{ parent() }}
  <p class="footer">Here is a footer.</p>
{% endblock %}

{% extends "@Contao/simple_text.html.twig" %}

{% block text %}
<div style="border: 1px solid black">
  {{ parent() }}
</div>
{% endblock %}

$this->render('@Contao/simple_text.html.twig', ['text' => 'Hello world!']);

<h1>Some simple text</h1>
<div style="border: 1px solid black">
    <p>Hello world!</p>
    <p>Here is a footer.</p>
</div>

Themes

In Contao, there is the option to create theme-specific representations of templates. The A theme and B theme could both contain a content_element/text.html.twig template. They can also both extend from any existing base template. Whether the A, B or global version of the template gets rendered, is a runtime decision, though. And this makes them behave a bit differently than the other templates.

If a page object is available in the current request, the theme can be derived from the (inherited) page layout setting. In case a theme was identified and contains a more specific version of a template, the ContaoFilesystemLoader will use it instead. From a template hierarchy perspective, these theme templates do not exist. This is a design decision to keep the template hierarchy static, render calls stable (and yourself sane).

These are the implications that follow from this setup:

1. Theme templates can only be theme-specific representations of otherwise existing templates. They will, for instance, never show up in any template selection dropdown.

2. As a matter of fact, you cannot create a variant template in a theme directory and make it show up in the template selection. You can, however, create a theme-specific representation of an existing variant template. By creating a selectable non-theme variant template as a basis, you also make sure that, there will always be an available template when rendering.

3. When debugging templates via the debug:contao-twig command, you need to explicitly pass a theme (slug) to make the respective theme templates show up in the result.

Naming and structure

In this section we’re talking about how templates should be named and structured and why it might be more important than in the typical Symfony ecosystem.

Won’t using the @Contao namespace lead to naming collisions if every vendor is using it?

This is a good point and intuitively kind of works against the idea of namespaces. But Contao has proven, it isn’t that big of a problem, either: In the old days, Contao’s templating engine did neither use any namespaces nor subdirectories^*) to structure templates. We instead added vendor or type prefixes to the template names based on a naming convention. This worked surprisingly well, but lead to a lot of files in one place. With Twig templates, the path, i.e. the directories and subdirectories the template files are placed in, is now part of the template name. This means we can structure by category or vendor by creating a filesystem structure.

^{*) Well, there could be subdirectories on the filesystem, but they did not affect the template name.}

Let’s do exactly that:

 templates ← Twig root
 │
 ├─content_element
 │  ├─text.html.twig
 │  └─image.html.twig 
 ├─foo
 │  └─bar
 │     └─baz.json.twig
 …

We call the topmost directory in the above example our Twig root, because all subdirectories in there contribute to the template name: There is a content_element/text template and a foo/bar/baz template. As you can tell, you can also introduce more subdirectory layers if needed.

Above, we referred to @Contao/content_element/text.html.twig by just writing content_element/text. In fact, in the @Contao namespace, these two things both uniquely identify the same template. When using the identifier, we imply the namespace and find the right file extension. The latter is guaranteed to be unique per identifier by our loader — if there would for instance also be a text.xml.twig (note the different file extension) in a content_element directory, an exception would be thrown when the filesystem gets scanned.

Twig Root

Because we made it possible to overwrite existing legacy PHP templates with Twig templates, and because the old template system does handle directories differently, the loader cannot always safely determine if your template directory (or maybe a subdirectory) should be treated as the Twig root. In Contao 6, all the Contao template directories will implicitly be Twig roots — until then only the global template directory and the theme directories are.

For any other place, such as the main template directory (contao/templates) and inside bundles, you need to add a special marker file .twig-root to denote that this directory should be used as the naming root.

 vendor/…/FooBundle/contao/templates
 ├─bar
 │  └─baz.html.twig
 └─my_root
    ├─.twig-root 
    └─content_element
       └─foobar.html.twig

Variant templates

One of Contao’s features is the ability to provide variants to an existing template and let editors choose which one to use in the back end on a per-element basis. You could for instance have a bunch of specialized templates for the text content element — maybe one that can be used, when something should stand out in the design and one that wraps lengthy side notes in an expandable section.

{% extends "@Contao/content_element/text.html.twig" %}

{% block text %}
    <div style="border: 5px red; padding: 1em;">{{ parent() }}</div>
{% endblock %}

{% extends "@Contao/simple_text.html.twig" %}

{% block content %}
<details>
  <summary>Here is an interesting side note…</summary>
  {{ parent() }}
</details>  
{% endblock %}

Finder

If, in your own code, you need to compile a list of templates, it can get quite cumbersome to loop through and filter the template hierarchy. For your convenience, there is a contao.twig.finder_factory service, that makes this process easy.

// Inject the factory service, then create a new template finder instance.
$finder = $this->finderFactory->create();

// Configure it using its fluent interface; here we only want to find templates
// named "foo/bar.json.twig" including related variants, like "foo/bar/baz.json.twig":
$finder = $finder
    ->identifier('foo/bar')
    ->extension('json.twig')
    ->withVariants()
;

// Then, iterate over the results…
foreach ($finder as $identifier => $extension) {
    // …
}

// …or directly generate template options with labels, that can be returned in
// a DCA options listener. 
$options = $finder->asTemplateOptions();

Encoding

For historic reasons Contao uses input encoding, but Twig embraces the more sane output encoding. You can read more about the topic (and why you should favor output encoding) in this OWASP article about preventing Cross Site Scripting (XSS) attacks. We outline further down, how we want to achieve the switch in Contao 6 and how you can already write modern template code.

Why you should care

The gist: You, as the template designer, have to decide how things should be output, because only you know the context in which content can be trusted or not. The exact same data can be dangerous in one context and harmless in another!

<style>
  .box { background: <?= $this->color ?> }
</style>

[…]

<div class="box"><?= $this->color ?></div>

red; } { body: display:none;

<style>
  .box { background: red; } body { display: none; }
</style>

<script>alert(1)</script>

<div class="box"><script>alert(1)</script></div>

<style>
  .box { background: {{ color|e('css') }} }
</style>

[…]

<div class="box">{{ color|e('html') }}</div>

.box { background: red\3B \20 \7D \20 \7B \20 body\3A \20 display\3A none\3B  }

<div class="box">&lt;script&gt;alert(1)&lt;/script&gt;</div>

{# The following terms will not be escaped! #}
{{ "Twig<br>" }}
{{ foo ? "Twig<br>" : "<br>Twig" }}

Trusted raw data

If you intentionally do want to output a variable without encoding, such as some raw HTML (<b>nice</b>) in a .html.twig template, you need to add the |raw filter to your variable {{ my_content|raw }}. This tells Twig to skip the escaper filters for this value. Otherwise, here, the encoded form <b>nice</b> would be output and the browser would display a text saying <b>nice</b> instead of the boldly written word nice.

You typically have this situation with text from the back end’s tinyMCE rich text editor. Here, Contao already sanitizes the HTML with the aim to remove unwanted or potentially dangerous HTML. This depends on your contao.sanitizer settings including the allowed tags and attributes, though. With a too lax configuration, you are open to XSS injections if this data is output in an unencoded form!

Double encoding prevention

Our Twig implementation makes sure you can use Twig templates as you would with output encoding (only). The intention hereby is, that your templates can stay the same and are already safe, when we’re removing the input encoding part in Contao 6.

In case you’re wondering, how we achieve this: Under the hood, we added our own contao_html and contao_html_attr escaper variants for the HTML context. These work very similar to the original versions (html and html_attr), except they prevent double encoding using htmlspecialchars(double_encode: false). At template compile time, we then exchange escaper calls to point to ours instead.

In order to not cause unwanted output for any other Symfony bundle or your app’s custom templates, we only do this for the @Contao and @Contao_* namespaces. If you want this behavior for other templates as well, you can add your own escaper rule. A rule is a regular expression — if it matches the template’s logical name, the Contao escapers will be enabled.

// Do this in your kernel or in a compiler pass 
$contaoExtension = $twig->getExtension(ContaoExtension::class);
$contaoExtension->addContaoEscaperRule('%^@MyNamespace/%');

Legacy interoperability

To make the transition to Twig as easy as possible, we build the ability to overwrite and extend existing PHP templates with Twig counterparts. There are a lot of things happening in the background to make this work, and we are going to drop this complexity together with the whole legacy template engine in the future. You should not use this feature as an excuse to create new PHP templates if there is a modern alternative.

To overwrite a PHP template with a Twig template, name it exactly like the PHP template, but use .html.twig as the file extension. To adjust the fe_page.html5 template, you would create a fe_page.html.twig template in a Contao template directory. If there are both versions, the legacy template will be ignored.

{% extends "@Contao/fe_page.html5" %}

{% block head %}
    {{ parent() }}
    <style>
        .thing { color: orange; }
    </style>
{% endblock %}

Context transformation

The data passed to the legacy templates gets transformed and passed to the environment’s render() function as an array. In most cases you would not note a difference, but there is a small caveat if callables like anonymous functions or closures were used.

Every element in Twig’s context needs to be a literal or an object, so when transforming, we’re wrapping functions in anonymous objects, that implement a __toString() function. In case you need to supply arguments, or you need anything else than string output, you’ll need to utilize the object’s invoke() function.

$this->Template->setData([
    'normalValue' => 'foo',
    'lazyValue' => static function(): string {
        return 'foo';
    },
    'fooFunction' => static function(string $value): string {
        return "foo-$value";
    },
     'lazyArray' => static function(): array {
        return [1, 2, 3, 4, 5];
    },
]);

<?= $this->normalValue ?>
<?= $this->lazyValue ?>
<?= $this->fooFunction('bar') ?>
<?= implode(', ', $this->lazyArray) ?>

{{ normalValue }}
{{ lazyValue }}
{{ fooFunction.invoke('bar') }}
{{ lazyArray.invoke()|join(', ') }}

Version compatibility

🟢 As an extension developer you might ask yourself which Contao versions your extension can be compatible with. As a rule of thumb, we suggest to stick to Contao 5 only for new extensions, if you can.

🟡 Alternatively, you might want to support Contao 5 and Contao 4.13 LTS at the same time. In general, this should be doable without maintaining a completely different branch but there are some pitfalls. Read more about that in the following section.

🔴 From a Twig support perspective, supporting Contao 4.9 LTS is not feasible, as native support for it was only added to the core in Contao 4.12. Also note, that Contao 4.9 is in the security-only phase as of mid february 2023 and will not be maintained anymore a year after that.

Considerations when also supporting Contao 4.13

In Contao 5.0, a new structure for content elements was introduced, that features directories (content_element), instead of prefixes (ce_). Since then, several changes have been back ported to Contao 4.13. In the latest release, you can now do the following things (Twig only):

• Use directories as part of template names.
• Use arbitrary file extensions (e.g. foo.json.twig).
• Use the template Finder via the contao.twig.finder_factory service.

Depending on where you make your templates available, you might need to curate the template options yourself. Using the Finder, this should be straight-forward, though.

#[AsContentElement(category: 'bar', template: 'content_element/foo')]
class FooController extends AbstractContentElement
{
    …
}

You might need to get a bit creative when you want to use templates, that were only added in Contao 5. One way of working around that issue, is, to provide the missing template(s) yourself and make the usage forward compatible.

1. Put the template in the compat directory. Templates inside this directory are never meant to be extended by others, so the structure is not important. You might want to copy the structure you are missing, though. For example, create a compat/content_element/code.html.twig template as a replacement for the content_element/code.html.twig template, that is available in Contao 5.

2. Use dynamic inheritance to tell Twig, that it should use your compat template if the original one isn’t available. When referencing the compat template, use the extension-specific namespace, so that your template is targeted, even if another extension used the same name:

   {# Twig will use the first available template, when providing an array of options #}
   {% extends [
       "@Contao/content_element/_base.html.twig",
       "@Contao_FooBarBundle/compat/content_element/_base.html.twig"
   ] %}