Twig para PHP: Guia completo do template engine do Symfony

Twig é um template engine moderno, rápido e seguro para a linguagem PHP, desenvolvido pela equipe do Symfony. Ele oferece aos desenvolvedores uma sintaxe poderosa e intuitiva para separar a lógica de apresentação (templates) da lógica de negócios da aplicação. O Twig resolve um problema crucial no desenvolvimento web: a mistura de código PHP com HTML, que gera "código espaguete" e reduz a legibilidade e a manutenibilidade do projeto.

O principal objetivo do Twig é tornar os templates limpos, seguros e fáceis de ler. Diferente do PHP puro, o Twig limita o desenvolvedor a executar código arbitrário dentro do template, prevenindo vulnerabilidades comuns como ataques XSS (Cross-Site Scripting) por meio de escape automático de saída. Em vez de construções complexas como <?php foreach(...): ?>, você usa blocos concisos como {% for item in items %}, e em vez de <?= $var ?>, usa {{ var }}. Isso torna os templates acessíveis para designers e desenvolvedores front-end que não conhecem PHP.

Twig é o padrão de facto para o framework Symfony, mas também se integra perfeitamente com Laravel (através do pacote twigbridge), Drupal, WordPress e pode ser usado como uma biblioteca independente em qualquer projeto PHP. Graças a recursos como herança de templates, macros, sandbox e escape automático, o Twig é um dos template engines mais populares do ecossistema PHP.

Instalação

A instalação do Twig é feita através do gerenciador de dependências Composer. Certifique-se de que o Composer está instalado globalmente.

composer require twig/twig:^3.0

Após executar o comando, seu projeto terá uma pasta vendor/ e um arquivo composer.json com a dependência adicionada. Para o autoload das classes, use o arquivo padrão vendor/autoload.php.

Início rápido: Exemplo mínimo funcional

Vamos criar um template simples e exibi-lo. Estrutura do projeto:

project/
├── templates/
│   └── hello.html.twig
├── vendor/
└── index.php

Template: templates/hello.html.twig

<!DOCTYPE html>
<html>
<head>
    <title>Saudação</title>
</head>
<body>
    <h1>Olá, {{ name }}!</h1>
    <p>Hoje é {{ "now"|date("d/m/Y") }}.</p>
</body>
</html>

Script PHP: index.php

<?php
require_once 'vendor/autoload.php';

use Twig\Environment;
use Twig\Loader\FilesystemLoader;

// 1. Cria o carregador que aponta para a pasta de templates
$loader = new FilesystemLoader('templates');

// 2. Cria o ambiente Twig
$twig = new Environment($loader, [
    'cache' => 'cache', // Caminho para cache (recomendado)
    'auto_reload' => true, // Recarregar automaticamente em alterações (para desenvolvimento)
]);

// 3. Renderiza o template, passando as variáveis
echo $twig->render('hello.html.twig', ['name' => 'Mundo']);
?>

Abra o arquivo index.php no navegador. Você verá uma página com o título "Olá, Mundo!" e a data atual.

Principais métodos e funções do Twig

Abaixo estão os principais métodos e construções que formam a base do trabalho com Twig.

1. Environment::render() — Renderização de template

Assinatura: public function render(string $name, array $context = []): string

Descrição: Método principal para exibir um template. Recebe o nome do arquivo do template (relativo à raiz do carregador) e um array associativo de variáveis (contexto) que estarão disponíveis dentro do template.

<?php
// Dentro do template 'profile.html.twig', as variáveis $us