Aller au contenu

Static Analysis et Code Completion avec Twig

Par Mise à jour le 9 min de lecture

Twig, Blade et les moteurs de templates compilés partagent un même talon d’Achille : l’analyse statique et l’autocomplétion du code dans les vues.

TwigStan est une super initiative et un projet ambitieux, mais il fait face à des défis techniques importants : bloqué sur les composants Symfony 7.1, migration Symfony 8 très difficile (cf. issue #277). Cela illustre la complexité inhérente à ajouter l’analyse statique par-dessus un langage de template compilé.

L’approche Splates est plus simple, si l’on accepte de mélanger HTML et PHP : en s’appuyant directement sur l’écosystème PHP natif (PHPStan, IDE), on évite cette couche de complexité supplémentaire.

Splates est un moteur de template PHP 8.4+ moderne, fork de league/plates, repensé autour de classes PHP typées. Le résultat : PHPStan max level sur les templates, autocomplétion complète dans l’IDE, et zéro magie.

Pourquoi Splates ?

  • Moins de magie : pas de langage de template compilé, pas de noms de template en string, pas de sections magiques. Juste des classes PHP.
  • PHPStan max level : chaque template est analysable statiquement. Les erreurs de typo se retrouvent à l’analyse, pas au runtime.
  • Autocomplétion IDE : les paramètres du constructeur avec #[TemplateData] fournissent l’autocomplétion partout.
  • Escaping contextuel : les value objects Text, Html, Attr, Js, Slot gèrent l’échappement selon le contexte — auto-escape par le type system.
  • Pattern Slots typé : les layouts sont des composants avec des propriétés Closure ou Slot (remplace les block/section magiques).
  • Injection de services : #[Inject] + Engine::addGlobal() pour les services globaux.

Quick Start

composer require piedweb/splates

Créer un template (style explicite, proche mentalement de Twig) :

<?php

namespace App\Templates;

use PiedWeb\Splates\Template\Attribute\TemplateData;
use PiedWeb\Splates\Template\TemplateAbstract;

class ProfileTpl extends TemplateAbstract
{
    public function __construct(
        #[TemplateData] public string $name,
        #[TemplateData] public string $email,
    ) {}

    public function __invoke(): void
    { ?>
        <div class="profile">
            <h1><?= $this->e($this->name) ?></h1>
            <p>Email: <?= $this->e($this->email) ?></p>
        </div>
    <?php }
}

Le rendre :

<?php

use PiedWeb\Splates\Engine;
use App\Templates\ProfileTpl;

$engine = new Engine();

echo $engine->render(new ProfileTpl(
    name: 'John Doe',
    email: 'john@example.com',
));

L’IDE autocomplète les paramètres name et email. PHPStan vérifie les types. Aucune surprise au runtime.

Choisir son style d’escaping

Splates propose deux approches d’échappement. Le choix est une question d’ergonomie et de migration progressive.

Style A — string + $this->e() (explicite)

#[TemplateData] public string $name,
// ...
<h1><?= $this->e($this->name) ?></h1>

La correspondance mentale avec Twig est directe : {{ name }} ≈ <?= $this->e($this->name) ?>. Idéal pour démarrer une migration depuis Twig sans changer d’habitudes.

Style B — Text value object (auto-escape)

use PiedWeb\Splates\Template\Value\Text;

#[TemplateData] public Text $name,
// ...
<h1><?= $this->name ?></h1>

Le type Text garantit l’échappement à la conversion en string. Plus court à l’usage, et le type system rend l’oubli d’escape impossible : si une propriété est typée Text, on ne peut pas la rendre non-échappée.

Recommandation : Text pour les nouveaux projets, string + $this->e() pour une migration progressive depuis Twig.

Templates fichier (sans classe)

Splates supporte aussi les templates .php classiques (comme league/plates), pas besoin de classe :

<?php
// Rendu
echo $engine->render('templates/hello.php', ['name' => 'John']);
<!-- templates/hello.php -->
<h1>Hello, <?= $e($name) ?></h1>

Les variables sont extraites automatiquement, et $e est disponible comme fonction d’échappement.

C’est idéal pour des templates simples ou une migration progressive. Pour les templates complexes, les classes offrent la sécurité des types et l’autocomplétion.

Templates en classe

La vraie force de Splates. Un template est une classe PHP avec :

  • Un constructeur avec les paramètres #[TemplateData] : les données du template
  • Une méthode __invoke() : le rendu HTML
  • Des méthodes helper via TemplateAbstract : $this->e(), $this->render(), $this->capture(), $this->slot()
<?php

class UserCardTpl extends TemplateAbstract
{
    public function __construct(
        #[TemplateData] public User $user,
        #[TemplateData] public bool $showEmail = false,
    ) {}

    public function __invoke(): void
    { ?>
        <div class="card">
            <h2><?= $this->e($this->user->name) ?></h2>
            <?php if ($this->showEmail): ?>
                <p><?= $this->e($this->user->email) ?></p>
            <?php endif ?>
        </div>
    <?php }
}

À noter : Splates propose plusieurs niveaux de création (TemplateClassInterface minimal, injection via paramètres d'__invoke(), #[Inject] sur propriétés, ou TemplateAbstract complet). Le README de Splates détaille ces options.

Value objects pour un escaping sûr

Splates fournit des value objects avec escaping contextuel :

ClasseContexteExemple
TextContenu HTML<p><?= $text ?></p>
HtmlHTML pré-échappé<?= $html ?>
AttrAttributs HTML<div class="<?= $attr ?>">
JsValeurs JavaScript<script>var x = <?= $js ?>;</script>
SlotContenu lazy (closure)<main><?= $slot ?></main>
<?php
use PiedWeb\Splates\Template\Value\{Text, Html, Attr, Js};

// Text — auto-escape pour le contenu HTML
$name = new Text('<script>bad</script>');
echo "<p>$name</p>";
// <p>&lt;script&gt;bad&lt;/script&gt;</p>

// Attr — escape pour les attributs HTML
$class = new Attr('my-class" onclick="bad');
echo "<div class=\"$class\">";
// <div class="my-class&quot; onclick=&quot;bad">

// Js — encode en JSON pour JavaScript
$data = new Js(['user' => 'John', 'count' => 42]);
echo "<script>var config = $data;</script>";
// <script>var config = {"user":"John","count":42};</script>

Layouts avec le pattern Slots

Fini les {% extends %} et {% block %} magiques. Avec Splates, un layout est un composant qui reçoit ses contenus en propriétés typées.

Variante Closure (la plus explicite)

<?php

class LayoutTpl extends TemplateAbstract
{
    public function __construct(
        #[TemplateData] public string $title,
        #[TemplateData] public Closure $content,
        #[TemplateData] public ?Closure $scripts = null,
    ) {}

    public function __invoke(): void
    { ?>
<!DOCTYPE html>
<html>
<head><title><?= $this->e($this->title) ?></title></head>
<body>
    <main><?= ($this->content)() ?></main>
    <?php if ($this->scripts): ?>
    <?= ($this->scripts)() ?>
    <?php endif ?>
</body>
</html>
    <?php }
}

Variante Slot (plus concise)

Le value object Slot évite la gymnastique ($this->content)() :

use PiedWeb\Splates\Template\Value\Slot;

class LayoutTpl extends TemplateAbstract
{
    public function __construct(
        #[TemplateData] public string $title,
        #[TemplateData] public Slot $content,
    ) {}

    public function __invoke(): void
    { ?>
<!DOCTYPE html>
<html>
<head><title><?= $this->e($this->title) ?></title></head>
<body>
    <main><?= $this->content ?></main>
</body>
</html>
    <?php }
}

La page qui utilise le layout

<?php

class ArticleTpl extends TemplateAbstract
{
    public function __construct(
        #[TemplateData] public string $title,
        #[TemplateData] public string $body,
    ) {}

    public function __invoke(): void
    {
        echo $this->render(new LayoutTpl(
            title: $this->title,
            content: $this->slot(function () { ?>

                <article>
                    <h1><?= $this->e($this->title) ?></h1>
                    <div><?= $this->e($this->body) ?></div>
                </article>

            <?php }),
        ));
    }
}

Le helper $this->slot(...) capture le contenu d’une closure et renvoie une Closure(): string (ou peut être passé à un new Slot(...) selon la variante choisie côté layout).

Comparaison avec Twig

{# Twig #}
{% extends 'layout.html.twig' %}
{% block content %}
    <h1>{{ title }}</h1>
{% endblock %}

Avec Splates, le layout est explicite : on voit exactement quels slots sont passés, avec leurs types. L’IDE peut naviguer du composant au layout en un clic.

Astuce — Heredoc pour la coloration syntaxique

Quand on mélange PHP et HTML dans une closure, la coloration de VS Code perd souvent le contexte. La syntaxe heredoc offre une meilleure coloration HTML :

private function renderSidebar(): string
{
    // Pré-calculer et échapper les valeurs
    $dashboardUrl = $this->e($this->app->url('/dashboard'));
    $usersUrl = $this->e($this->app->url('/users'));

    return <<<HTML
        <nav class="sidebar-nav">
            <h3>Quick Links</h3>
            <ul>
                <li><a href="{$dashboardUrl}">Dashboard</a></li>
                <li><a href="{$usersUrl}">All Users</a></li>
            </ul>
        </nav>
        HTML;
}

Trade-off :

  • Heredoc : coloration HTML correcte dans VS Code, mais nécessite de pré-calculer les variables.
  • Closure avec ?> : permet les expressions PHP inline (<?php if ?>), coloration parfois cassée.

Injection de services

Pour les services globaux (router, config, etc.), Splates utilise #[Inject] et Engine::addGlobal() :

<?php

// Configuration
$engine = new Engine();
$engine->addGlobal('ext', $templateExtension);
$engine->addGlobal('router', $router);
<?php

use PiedWeb\Splates\Template\Attribute\Inject;

class MyTpl extends TemplateAbstract
{
    #[Inject]
    public TemplateExtension $ext;

    #[Inject]
    public RouterInterface $router;

    public function __construct(
        #[TemplateData] public User $user,
    ) {}

    public function __invoke(): void
    { ?>
        <a href="<?= $this->e($this->ext->url('user_profile', ['id' => $this->user->getId()])) ?>">
            <?= $this->e($this->user->getName()) ?>
        </a>
    <?php }
}

Créer une classe de base pour l’application

<?php

namespace App\Templates;

use PiedWeb\Splates\Template\Attribute\Inject;
use PiedWeb\Splates\Template\TemplateAbstract;

abstract class AppTemplate extends TemplateAbstract
{
    #[Inject]
    public TemplateExtension $ext;

    protected function url(string $route, array $params = []): string
    {
        return $this->ext->url($route, $params);
    }

    protected function user(): ?User
    {
        return $this->ext->getUser();
    }
}

// Tous les templates de l'app étendent AppTemplate
class DashboardTpl extends AppTemplate
{
    public function __invoke(): void
    { ?>
        <p>Bienvenue, <?= $this->e($this->user()?->getName() ?? 'Invité') ?></p>
    <?php }
}

Intégration Symfony

Configuration du service

# config/services.yaml
services:
    PiedWeb\Splates\Engine:
        arguments:
            $templateDir: '%kernel.project_dir%'
            $cacheDir: '%kernel.cache_dir%/splates'
        calls:
            - addGlobal: ['ext', '@App\Service\TemplateExtension']

Override de AbstractController

<?php

namespace App\Controller;

use PiedWeb\Splates\Engine;
use PiedWeb\Splates\Template\TemplateClassInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController as SfAbstractController;
use Symfony\Component\HttpFoundation\Response;

abstract class AbstractController extends SfAbstractController
{
    public function __construct(
        protected readonly Engine $splates,
    ) {}

    protected function renderSplates(TemplateClassInterface $template, int $status = 200): Response
    {
        return new Response(
            $this->splates->render($template),
            $status,
        );
    }
}

Utilisation dans un contrôleur

<?php

class UserController extends AbstractController
{
    #[Route('/user/{id}', name: 'user_profile')]
    public function profile(User $user): Response
    {
        return $this->renderSplates(new ProfileTpl(user: $user));
    }
}

Formulaires Symfony

Pour les formulaires, le plus pragmatique est de déléguer le rendu à Twig via le bridge existant :

<?php

class TemplateExtension
{
    public function __construct(
        private readonly UrlGeneratorInterface $urlGenerator,
        private readonly Environment $twig,
    ) {}

    public function form(FormInterface $form): string
    {
        return $this->twig->render('form.html.twig', [
            'form' => $form->createView(),
        ]);
    }
}

Migrer de Twig vers Splates

TwigSplates
{% extends 'layout.html.twig' %}echo $this->render(new LayoutTpl(content: ...))
{% block content %}...{% endblock %}content: $this->slot(function () { ... })
{% include 'partial.html.twig' %}echo $this->render(new PartialTpl())
{% macro tooltip(text) %}Méthode PHP private ou service injecté
{{ var|default('fallback') }}$var ?? 'fallback'
{{ var|u.truncate(50, '…') }}(new UnicodeString($var))->truncate(50, '…')
{{ var|escape }} / {{ var }}$this->e($var) ou propriété typée Text
{% for item in items %}foreach ($this->items as $item):
{% if condition %}if ($condition):

Étapes de migration

  1. Créer les classes de template : un fichier .twig = une classe PHP. Les variables du template deviennent les paramètres #[TemplateData] du constructeur.
  1. Convertir les layouts : {% extends %} + {% block %} deviennent le pattern slots. Le layout reçoit des Closure (ou Slot), la page les passe via $this->slot().
  1. Remplacer les includes : {% include 'partial.html.twig' %} devient $this->render(new PartialTpl(...)).
  1. Remplacer les macros : deviennent des méthodes private sur la classe ou des services injectés via #[Inject].
  1. Adapter les filtres : les filtres Twig deviennent du PHP natif (?? pour default, UnicodeString pour les manipulations de texte, etc.).

Clin d’œil : Twig → Plates → Splates

Splates est un fork de league/plates. Si tu viens de Plates plutôt que de Twig, tes templates .php continuent de fonctionner via $engine->render('template.php', [...]). Pour passer en classes typées et profiter pleinement de PHPStan, le guide « Migrating from league/plates » du README détaille la conversion étape par étape.

Cache et Performance

En production, activer le cache de réflexion pour éviter l’introspection à chaque requête :

<?php

$engine = new Engine(cacheDir: '/path/to/cache');

// Préchauffer le cache au déploiement
$engine->getInjectResolver()->warmCache([
    ProfileTpl::class,
    LayoutTpl::class,
    ArticleTpl::class,
]);

Le compromis est d’accepter PHP dans les templates, mais avec les classes typées, les value objects et le pattern slots, le résultat est plus structuré et plus sûr que du Twig sans analyse statique.

Email • RSS • Twitter

Être notifié des nouvelles publications

Continuer sa lecture sur le développement web