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,Slotgè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
ClosureouSlot(remplace lesblock/sectionmagiques). - 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 :
| Classe | Contexte | Exemple |
|---|---|---|
Text | Contenu HTML | <p><?= $text ?></p> |
Html | HTML pré-échappé | <?= $html ?> |
Attr | Attributs HTML | <div class="<?= $attr ?>"> |
Js | Valeurs JavaScript | <script>var x = <?= $js ?>;</script> |
Slot | Contenu 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><script>bad</script></p>
// Attr — escape pour les attributs HTML
$class = new Attr('my-class" onclick="bad');
echo "<div class=\"$class\">";
// <div class="my-class" onclick="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
| Twig | Splates |
|---|---|
{% 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
- Créer les classes de template : un fichier
.twig= une classe PHP. Les variables du template deviennent les paramètres#[TemplateData]du constructeur.
- Convertir les layouts :
{% extends %}+{% block %}deviennent le pattern slots. Le layout reçoit desClosure(ouSlot), la page les passe via$this->slot().
- Remplacer les includes :
{% include 'partial.html.twig' %}devient$this->render(new PartialTpl(...)).
- Remplacer les macros : deviennent des méthodes
privatesur la classe ou des services injectés via#[Inject].
- Adapter les filtres : les filtres Twig deviennent du PHP natif (
??pourdefault,UnicodeStringpour 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.
Continuer sa lecture sur le développement web
quel plugin de traduction WordPress choisir ?