Skip to content

4. A view e seu modelo

Até aqui, as ações geravam suas próprias respostas: texto, JSON e algumas tags HTML escritas como string. Em uma aplicação MVC, esse é o papel de uma view: um arquivo que descreve o HTML da página, com marcadores de posição para os dados que a ação lhe passa, o modelo da view.

[Symfony] usa a engine de views [Twig], criada pela mesma equipe. Uma view [Twig] é um arquivo cujo nome termina em [.html.twig] (o formato de saída, seguido da engine), armazenado na pasta [templates] da aplicação. É um arquivo de texto, neste caso HTML, no qual três tipos de tags são interpretados no servidor:

  • [{{ expression }}]: o valor de uma expressão, inserido na página;
  • [{% instruction %}]: uma instrução (tag); uma condição ([{% if %}]); um laço ([{% for %}]), a herança de templates ([{% extends %}], [{% block %}]), a inclusão ([{% include %}])...;
  • [{# comment #}]: um comentário, que não aparece na página gerada.

Todo o resto é copiado como está. As expressões não são escritas em [PHP], mas na linguagem do [Twig], que é mais simples e mais segura: [model.title] refere-se à propriedade [title] do objeto [model] (ou ao seu método [getTitle()], ou à chave [title] de um array: o [Twig] procura por conta própria); os filtros transformam um valor ([name|upper] coloca um nome em maiúsculas); as funções realizam cálculos ([path('home')] gera uma URL). [Twig] assemelha-se, assim, ao [Jinja2] ([Flask]), do qual tirou inspiração, ou à engine do [Django]; ele difere do [Blade] ([Laravel]) e do [Razor] ([ASP.NET Core]), que combinam HTML com código da linguagem hospedeira. Uma view [Twig] não pode executar código [PHP] arbitrário: ela só pode exibir os dados que lhe são fornecidos. Isso é proposital: a lógica da aplicação permanece nas classes. Uma view não é interpretada a cada requisição: no primeiro uso, o [Twig] a compila em uma classe [PHP], armazenada na pasta [var/cache/dev/twig], que ele reutiliza enquanto a view não for alterada. Veremos a aparência desse arquivo.

4.1. Exemplo 13: uma primeira view

13-first-view/
├── config/
│   ├── packages/
│   │   ├── framework.yaml
│   │   └── twig.yaml
│   └── bundles.php
├── src/
│   ├── Controller/
│   │   └── ViewsController.php
│   ├── Model/
│   │   └── PageModel.php
│   └── Kernel.php
├── templates/
│   └── views/
│       ├── unknown.html.twig
│       └── index.html.twig
└── ...

4.1.1. A configuração: config/bundles.php e config/packages/twig.yaml

O [Twig] é integrado ao [Symfony] por meio de um bundle, o TwigBundle, que deve ser adicionado à lista de bundles da aplicação (Exemplo 01):

1
2
3
4
5
6
7
<?php
// config/bundles.php: os bundles da aplicação; o TwigBundle integra a
// engine de views Twig
return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
];

e configurar:

1
2
3
4
# config/packages/twig.yaml: a configuração do TwigBundle
twig:
    # a pasta das views
    default_path: '%kernel.project_dir%/templates'

A única chave especifica a pasta das views: [templates], localizada na pasta do projeto. Esse também é o valor padrão. Em um projeto padrão, esses dois arquivos são criados pelo [Symfony Flex] quando se instala o [Twig] ([composer require twig], veja a introdução).

4.1.2. O modelo da view: src/Model/PageModel.php

<?php
// src/Model/PageModel.php: o modelo da view, os dados que a action passa para a view

namespace App\Model;

readonly class PageModel
{
    public function __construct(
        public string $title,
        public string $message,
        public string $time,
    ) {
    }
}

O modelo da view é uma classe simples e imutável (veja o Exemplo 03): as três informações que a view exibirá. Não há obrigação de definir o modelo de uma view como uma classe: três variáveis separadas poderiam ser passadas à view. No entanto, uma classe documenta o que a view espera e permite que o editor verifique o código da ação. Essa é a abordagem que o estudo de caso seguirá, em que cada view importante tem sua própria classe de modelo.

4.1.3. O controller: src/Controller/ViewsController.php

<?php
// src/Controller/ViewsController.php: actions que retornam uma VIEW

namespace App\Controller;

use App\Model\PageModel;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(methods: ['GET'])]
class ViewsController extends AbstractController
{
    // render: a engine Twig constrói a página a partir do template da view
    // templates/views/index.html.twig e das variáveis passadas no array (aqui
    // apenas uma, [model]); a página produzida é o corpo da resposta
    #[Route('/', name: 'index')]
    public function index(): Response
    {
        $model = new PageModel(
            'My first view',
            'This page was built by Twig, on the server.',
            date('H:i:s'));
        return $this->render('views/index.html.twig', ['model' => $model]);
    }

    // a mesma view com outro modelo; ou outra view, com o código 404
    #[Route('/hello/{name}', name: 'hello')]
    public function hello(string $name): Response
    {
        if ($name === 'unknown') {
            // o terceiro parâmetro de render: a resposta a completar, aqui com o código 404
            return $this->render('views/unknown.html.twig', ['name' => $name],
                new Response(status: Response::HTTP_NOT_FOUND));
        }
        $model = new PageModel(
            "Hello $name",
            'This time, the title of the page comes from the URL.',
            date('H:i:s'));
        return $this->render('views/index.html.twig', ['model' => $model]);
    }
}
  • Linhas 20–23: a ação constrói o modelo da view. A função [date], derivada do [PHP], formata a hora atual: [H] formata as horas, [i] formata os minutos e [s] formata os segundos;
  • Linha 24: o método [render] de [AbstractController] instrui o [Twig] a gerar a página. O primeiro parâmetro é o nome da view: o caminho do arquivo, relativo à pasta [templates]. O segundo parâmetro é um array associativo, em que cada chave se torna uma variável na view; neste caso, uma só: [model]. [render] retorna um objeto [Response], cujo corpo é a página gerada (do tipo [text/html]);
  • linhas 31–35: outra view, com outra variável ([name]). O terceiro parâmetro de [render] é uma resposta a ser preenchida: neste caso, uma resposta 404 para uma página de erro personalizada. [new Response(status: ...)] passa o código por meio de um parâmetro nomeado, enquanto os demais parâmetros mantêm seus valores padrão;
  • Linhas 36–40: a mesma view da ação [index], mas com um modelo diferente. Essa é a vantagem de separar ações e views: uma única view pode ser usada por várias ações.

4.1.4. A view: templates/views/index.html.twig

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  {# {{ ... }}: o valor de uma expressão, inserido na página #}
  <title>{{ model.title }}</title>
</head>
<body>
  <h1>{{ model.title }}</h1>
  <p>{{ model.message }}</p>
  <p>Page built at {{ model.time }}.</p>
</body>
</html>
  • linha 5: um comentário [Twig];
  • linha 6: [{{ model.title }}] insere o valor da propriedade [title] da variável [model]. O ponto é o operador de acesso do [Twig], onde o [PHP] escreve [$model->title].

Tudo o que é inserido por [{{ }}] é escapado: os caracteres [<], [>], [&], ["] e ['] são substituídos por suas entidades HTML. Esse é o papel que a função [htmlspecialchars] desempenhava no Exemplo 09, mas agora de forma automática: uma view, portanto, não pode inserir inadvertidamente na página o HTML fornecido por um usuário.

4.1.5. A view: templates/views/unknown.html.twig

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Unknown</title>
</head>
<body>
  <h1>Nobody is called [{{ name }}] here.</h1>
</body>
</html>

Uma view não precisa receber um objeto: a variável [name] é uma string.

4.1.6. Execução

Image

Image

A hora exibida corresponde ao fuso horário configurado no [PHP] (a diretiva [date.timezone] no arquivo [php.ini]), que neste caso é o Tempo Universal Coordenado (UTC); o estudo de caso mostrará como defini-lo para a aplicação. A resposta bruta mostra o trabalho realizado pelo [Twig]: as tags [{{ }}] foram substituídas por seus valores, e o comentário foi removido.

curl -i http://localhost:8000/
HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
    <title>My first view</title>
</head>
<body>
  <h1>My first view</h1>
  <p>This page was built by Twig, on the server.</p>
  <p>Page built at 09:31:47.</p>
</body>
</html>

A página de erro “home”, seguida de um nome que contém HTML ([<b>martin], codificado na URL):

curl -i http://localhost:8000/hello/unknown
curl http://localhost:8000/hello/%3Cb%3Emartin
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=UTF-8

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Unknown</title>
</head>
<body>
  <h1>Nobody is called [unknown] here.</h1>
</body>
</html>
...
    <title>Hello &lt;b&gt;martin</title>
...
  <h1>Hello &lt;b&gt;martin</h1>
  <p>This time, the title of the page comes from the URL.</p>
...

A tag [<b>] foi escapada, embora nem a ação nem a view tivessem qualquer relação com isso (o apóstrofo também foi escapado: [&#039;]). Eis, finalmente, a view compilada pelo [Twig], como encontrada na pasta [var/cache/dev/twig] (sob um nome gerado, como [f1/f1e0ff0a8a0dc68657a0b1aa94f3ef4b.php]), reduzida ao essencial:

/* views/index.html.twig */
class __TwigTemplate_9c9473b678a753b61e2666e1a8e3a2a4 extends Template
{
    ...
    protected function doDisplay(array $context, array $blocks = []): iterable
    {
        // line 1
        yield "<!doctype html>
<html lang=\"en\">
<head>
  <meta charset=\"utf-8\">
  ";
        // line 6
        yield "  <title>";
        yield (string) $this->escaper->escape(CoreExtension::getAttribute($this->env, $this->source,
            ... $context["model"] ..., "title", ...), "html", null, true);
        yield "</title>
...

A view se tornou uma classe chamada [PHP], cujo método [doDisplay] gera a página peça por peça ([yield]). Cada [{{ model.title }}] virou uma chamada a [CoreExtension::getAttribute] (que procura a propriedade, o método ou a chave [title]), passada ao método [escape] (escape). Uma view [Twig] é, portanto, simplesmente uma forma mais segura e mais legível de escrever um arquivo [PHP] que gera HTML.

4.2. Exemplo 14: a linguagem Twig

Este exemplo combina as principais construções do [Twig] em uma única view.

4.2.1. O modelo e a ação

O modelo da view é definido por três classes imutáveis, cada uma em seu próprio arquivo (o [PHP] não exige uma classe por arquivo, mas o class loader do [Composer] procura a classe [App\Model\Product] no arquivo [src/Model/Product.php]):

<?php
// src/Model/Product.php: um produto

namespace App\Model;

readonly class Product
{
    public function __construct(
        public string $name,
        public float $price,
        public bool $inStock,
    ) {
    }
}
<?php
// src/Model/Address.php: um endereço

namespace App\Model;

readonly class Address
{
    public function __construct(
        public string $street,
        public string $city,
    ) {
    }
}
<?php
// src/Model/BasicsModel.php: o modelo da view do exemplo 14

namespace App\Model;

readonly class BasicsModel
{
    /**
     * @param list<Product> $products
     * @param list<Product> $cart
     */
    public function __construct(
        public string $title,
        public string $name,
        public ?string $nickname,
        public string $html,
        public bool $loggedIn,
        public string $currency,
        public array $products,
        public array $cart,
        public Address $address,
    ) {
    }
}

O modelo contém valores de vários tipos: strings, [null], booleanos, arrays de objetos, arrays vazios e objetos que contêm outros objetos. Os preços aqui são do tipo [float], para simplificar os cálculos na view (o Exemplo 06 mostrou por que preferimos centavos inteiros).

<?php
// src/Controller/BasicsController.php: uma view que usa as principais construções do Twig

namespace App\Controller;

use App\Model\Address;
use App\Model\BasicsModel;
use App\Model\Product;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

class BasicsController extends AbstractController
{
    #[Route('/', name: 'index', methods: ['GET'])]
    public function index(): Response
    {
        $model = new BasicsModel(
            title: 'Twig basics',
            name: 'Martin',
            nickname: null,
            html: '<b>this is HTML</b>',
            loggedIn: true,
            currency: '€',
            products: [
                new Product('Keyboard', 25, true),
                new Product('Mouse', 12.5, false),
                new Product('Screen', 149, true),
            ],
            cart: [],
            address: new Address('12 rue des Lilas', 'Angers'));
        return $this->render('basics/index.html.twig', ['model' => $model]);
    }
}

A ação constrói o modelo usando parâmetros nomeados (veja o Exemplo 02): cada valor é precedido pelo nome do parâmetro a que se destina, o que torna a chamada legível apesar do número de parâmetros.

4.2.2. A view: templates/basics/index.html.twig

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>{{ model.title }}</title>
</head>
<body>
  {# set: uma variável da view; o filtro reduce soma os preços, o filtro length conta os produtos #}
  {% set total = model.products|reduce((sum, p) => sum + p.price, 0) %}
  {% set count = model.products|length %}
  <h1>{{ model.title }}</h1>
  {# 1. exibe um valor do modelo; null é exibido como uma string vazia;
     o filtro default substitui um valor vazio. Este comentário Twig não aparece
     na página produzida #}
  <p>1. Name: {{ model.name }} - nickname: [{{ model.nickname }}] [{{ model.nickname|default('none') }}]</p>
  {# 2. {{ }} escapa o HTML; o filtro raw o insere como está #}
  <p>2a. {{ model.html }}</p>
  <p>2b. {{ model.html|raw }}</p>
  {# 3. uma condição #}
  {% if model.loggedIn %}
    <p>3. You are logged in.</p>
  {% else %}
    <p>3. You are not logged in.</p>
  {% endif %}
  {# 4. um laço: a variável loop descreve o estado do laço #}
  <p>4. Our products:</p>
  <ul>
    {% for product in model.products %}
      <li>no. {{ loop.index0 }}: {{ product.name }}, {{ product.price }} {{ model.currency }}
        {{ product.inStock ? '(in stock)' : '(sold out)' }}
        {% if loop.first %} - the first one{% endif %}
        {% if loop.last %} - the last one, seen by {{ model.name }}{% endif %}
      </li>
    {% endfor %}
  </ul>
  {# 5. a lista vazia: o bloco else de um laço for #}
  <p>5. Your cart:
    {% for p in model.cart %}<span>{{ p.name }}</span>{% else %} it is empty.{% endfor %}
  </p>
  {# 6. expressões calculadas, as variáveis definidas por set e o filtro number_format #}
  <p>6. {{ count }} products, for a total of {{ total }} {{ model.currency }};
    average price: {{ (total / count)|number_format(2, '.', ',') }} {{ model.currency }}</p>
  {# 7. um objeto dentro de um objeto, e um filtro que converte para maiúsculas #}
  <p>7. Address: {{ model.address.street }}, {{ model.address.city|upper }}</p>
  {# 8. verbatim: um texto que o Twig copia sem interpretar #}
  <p>8. Braces displayed as is: {% verbatim %}{{ model.name }}{% endverbatim %}</p>
</body>
</html>
  • Linhas 9–10: a instrução [{% set %}] cria uma variável na view. O preço total é calculado pelo filtro [reduce], que reduz um array a um único valor (como [array_reduce], exemplo 06): sua função recebe o valor acumulado e o elemento atual; [(sum, p) => sum + p.price] é uma arrow function do [Twig]. O filtro [length] retorna o número de elementos de um array (ou de caracteres de uma string). Esses cálculos devem ser reservados à apresentação: o cálculo normalmente pertence à ação;
  • linha 15: um valor [null] é exibido como uma string vazia. O filtro [default] substitui um valor vazio (ou ausente) por um valor padrão;
  • linhas 17–18: [{{ }}] escapa o HTML (2a); o filtro [raw], por outro lado, insere o valor como está, sem escapá-lo (2b). [raw] é reservado ao HTML gerado pela própria aplicação, nunca a entradas do usuário;
  • Linhas 20–24: uma condição: [{% if %}], [{% elseif %}], [{% else %}], [{% endif %}]. Cada bloco é fechado por uma instrução [{% end... %}];
  • Linhas 28–34: um laço [{% for ... in ... %}] ... [{% endfor %}]. Dentro do laço, a variável especial [loop] descreve o estado do laço: [loop.index0] (o número da iteração, começando em 0), [loop.index] (começando em 1), [loop.first], [loop.last] (verdadeiros na primeira e na última iteração), [loop.length] (o número de elementos). As variáveis externas ao laço ([model.name]) continuam acessíveis;
  • linha 30: o operador ternário [condition ? a : b] (o [Twig] também aceita [condition ? a], que retorna uma string vazia se a condição for falsa);
  • linha 38: um laço [for] pode ter um bloco [{% else %}], que é executado se a lista estiver vazia. Isso é mais simples do que um [{% if %}] que verificasse o tamanho da lista;
  • linhas 41–42: expressões calculadas ([total / count]) e as variáveis de [set]. O filtro [number_format] formata um número: duas casas decimais, um ponto como separador decimal e uma vírgula como separador de milhares. No Exemplo 16, veremos uma forma muito melhor de formatar números e valores;
  • linha 44: o ponto percorre objetos ([model.address.city]), e o filtro [upper] coloca uma string em maiúsculas (tratando corretamente os caracteres acentuados);
  • linha 46: a instrução [{% verbatim %}] copia seu conteúdo sem interpretá-lo: isso é útil quando uma página contém chaves destinadas a um framework [JavaScript].

[Twig] tem cerca de cinquenta filtros ([lower], [capitalize], [trim], [join], [split], [slice], [sort], [date], [json_encode], [escape]...), cerca de quinze funções ([range], [min], [max], [random]...) e testes ([is defined], [is empty], [is null], [is iterable], [is even]...); os bundles do [Symfony] acrescentam alguns ([path], [asset], [form_row], [is_granted]...), e a aplicação pode escrever os seus próprios (Exemplo 16).

4.2.3. Execução

Image

A página gerada:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Twig basics</title>
</head>
<body>
        <h1>Twig basics</h1>
    <p>1. Name: Martin - nickname: [] [none]</p>
    <p>2a. &lt;b&gt;this is HTML&lt;/b&gt;</p>
  <p>2b. <b>this is HTML</b></p>
        <p>3. You are logged in.</p>
      <p>4. Our products:</p>
  <ul>
          <li>no. 0: Keyboard, 25 €
        (in stock)
         - the first one              </li>
          <li>no. 1: Mouse, 12.5 €
        (sold out)
                      </li>
          <li>no. 2: Screen, 149 €
        (in stock)
                 - the last one, seen by Martin      </li>
      </ul>
    <p>5. Your cart:
     it is empty.  </p>
    <p>6. 3 products, for a total of 186.5 €;
    average price: 62.17 €</p>
    <p>7. Address: 12 rue des Lilas, ANGERS</p>
    <p>8. Braces displayed as is: {{ model.name }}</p>
</body>
</html>

Os comentários e as instruções desapareceram, mas deixam seus espaços: o [Twig] remove a quebra de linha que segue uma tag, mas não a indentação que a precede. Isso não tem efeito: o navegador ignora esses espaços. (Um hífen dentro de uma tag, como [{%- ... -%}] ou [{{- ... -}}], removeria o espaço em branco ao redor dela.) Um número [float] inserido na página é escrito com ponto decimal ([12.5]); [number_format] usa os separadores que lhe são passados.

4.3. Exemplo 15: templates, fragmentos, arquivos estáticos

As páginas de um site geralmente compartilham a mesma estrutura: um cabeçalho, uma barra de navegação, um rodapé e as mesmas folhas de estilo. Em vez de repetir essa estrutura em cada view, ela é escrita uma só vez em um template (layout), que as páginas estendem. Este exemplo também usa o [Bootstrap], o framework CSS mais utilizado, para o layout.

15-layout/
├── config/
│   ├── packages/
│   │   └── twig.yaml
│   └── services.yaml
├── public/
│   └── css/
│       └── styles.css
├── src/
│   ├── Controller/
│   │   └── PagesController.php
│   ├── Model/
│   │   └── Member.php
│   └── Kernel.php
├── templates/
│   ├── fragments/
│   │   └── navbar.html.twig
│   ├── layout.html.twig
│   ├── macros.html.twig
│   └── pages/
│       ├── home.html.twig
│       ├── raw.html.twig
│       └── team.html.twig
└── ...

4.3.1. Arquivos estáticos

Uma página HTML referencia outros arquivos: folhas de estilo, scripts [JavaScript] e imagens. Esses arquivos, que o servidor envia como estão, são chamados de arquivos estáticos. Com o [Symfony], eles ficam na pasta [public], que o servidor web serve como estão (exemplo 01): o arquivo [public/css/styles.css] está disponível na URL [/css/styles.css], sem que o [Symfony] seja envolvido.

/* algumas configurações além do Bootstrap */
body {
  background-color: #f5f7fa;
}

/* o rodapé do layout */
.footer {
  margin-top: 2rem;
  font-size: 0.85rem;
  color: #6c757d;
}

/* as mensagens de erro, na parte inferior da página, sobre um fundo rosa claro */
.error-area {
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef;
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

Algumas regras CSS adicionais, além do [Bootstrap]: um fundo cinza-claro, o estilo do rodapé e o estilo de uma área de erro que será usada nos exemplos seguintes.

[Bootstrap] é usado nos exemplos 15 a 28. Em vez de colocar uma cópia na pasta [public] de cada usuário, os exemplos o compartilham: ele fica na pasta [examples/common/bootstrap]. Essa pasta não é servida pelo servidor web: um controller, compartilhado por todos esses exemplos, serve seus arquivos. Este é o arquivo [examples/common/BootstrapController.php]:

<?php
// common/BootstrapController.php: um controller que serve os arquivos do Bootstrap,
// compartilhados pelos exemplos 15 a 28 (a pasta examples/common/bootstrap), sob
// a URL /bootstrap/... Cada um desses exemplos o declara em seu
// arquivo config/services.yaml

namespace Common;

use Symfony\Component\HttpFoundation\BinaryFileResponse;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Routing\Requirement\Requirement;

class BootstrapController
{
    #[Route('/bootstrap/{file}', name: 'bootstrap', requirements: ['file' => Requirement::CATCH_ALL],
        methods: ['GET'])]
    public function serve(string $file): BinaryFileResponse
    {
        $folder = realpath(__DIR__.'/bootstrap');
        // realpath: o caminho absoluto do arquivo solicitado, sem o . e o ..;
        // false se o arquivo não existir
        $path = realpath($folder.'/'.$file);
        // um arquivo que existe e que está de fato DENTRO da pasta (sem ../ para sair dela)
        if ($path === false || ! str_starts_with($path, $folder.DIRECTORY_SEPARATOR) || ! is_file($path)) {
            throw new NotFoundHttpException("unknown file: $file");
        }
        // uma resposta que envia o conteúdo de um arquivo; seu tipo, de acordo com sua extensão
        $response = new BinaryFileResponse($path);
        $types = ['css' => 'text/css', 'js' => 'text/javascript', 'map' => 'application/json'];
        $response->headers->set('Content-Type', $types[pathinfo($path, PATHINFO_EXTENSION)] ?? 'application/octet-stream');
        return $response;
    }
}
  • linha 7: a classe está no namespace [Common], que o arquivo [examples/composer.json] associa à pasta [examples/common] (veja a introdução): o class loader do [Composer] a encontra, portanto, independentemente do exemplo;
  • Linhas 16–17: uma rota cujo parâmetro [{file}] aceita qualquer final de caminho, inclusive barras (exemplo 02): a URL [/bootstrap/css/bootstrap.min.css] refere-se ao arquivo [css/bootstrap.min.css] da pasta. A rota se chama [bootstrap];
  • Linhas 20–27: servir arquivos designados por uma URL exige cautela: uma URL como [/bootstrap/..%2F..%2F15-layout%2F.env] (em que [/] é codificada como [%2F]) não deve dar acesso a um arquivo localizado fora da pasta. A função [realpath] do [PHP] calcula o caminho absoluto de um arquivo, eliminando seus componentes [.] e [..], ou retorna [false] se o arquivo não existir. Verificamos que o caminho resultante começa com o caminho da pasta ([str_starts_with]) e que ele se refere a um arquivo ([is_file]); caso contrário, um erro 404 é retornado. [DIRECTORY_SEPARATOR] é o separador de caminhos do sistema: [\] no [Windows], [/] nos demais;
  • linhas 29–32: um objeto [BinaryFileResponse] é uma resposta que envia o conteúdo de um arquivo. O tipo de conteúdo é determinado com base na extensão do arquivo (fornecida por [pathinfo]), de modo que uma folha de estilo seja corretamente declarada como [text/css]: um navegador rejeita uma folha de estilo declarada com outro tipo.

Cada exemplo que usa o [Bootstrap] declara esse controller como um serviço em seu arquivo [config/services.yaml]:

# config/services.yaml: os serviços da aplicação (veja o exemplo 06)
services:
    _defaults:
        autowire: true
        autoconfigure: true

    App\:
        resource: '../src/'

    # o controller que serve o Bootstrap, compartilhado pelos exemplos 15 a 28 (veja o exemplo 15)
    Common\BootstrapController: ~
  • linha 11: o serviço [Common\BootstrapController], sem configuração específica ([~] é o valor de [null] em [YAML]): ele recebe a configuração de [_defaults], e [autoconfigure] o transforma em um controller, cuja rota se junta às da aplicação (exemplo 02).

4.3.2. O template: templates/layout.html.twig

<!doctype html>
{# o layout das páginas: as páginas o ESTENDEM e preenchem seus blocos #}
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {# block: um espaço que a página pode preencher; aqui com um conteúdo padrão #}
  <title>{% block title %}Home{% endblock %} - {{ site_name }}</title>
  {# path(): a URL da rota chamada [bootstrap]; asset(): a URL de um arquivo de public/ #}
  <link rel="stylesheet" href="{{ path('bootstrap', {file: 'css/bootstrap.min.css'}) }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3">
    {# inserção do arquivo fragments/navbar.html.twig #}
    {% include 'fragments/navbar.html.twig' %}
    <main>
      {# o conteúdo da página solicitada pela action é inserido aqui #}
      {% block content %}{% endblock %}
    </main>
    {# app: a variável que o Symfony fornece a todas as views (a requisição atual...);
       site_name: uma variável global (veja config/packages/twig.yaml) #}
    <footer class="footer">Page [{{ app.request.pathInfo }}] - © {{ 'now'|date('Y') }} {{ site_name }}</footer>
  </div>
</body>
</html>
  • linha 6: a tag [viewport] instrui os navegadores móveis a exibir a página na largura da tela, que é o que o [Bootstrap] espera;
  • linha 8: a diretiva [{% block %}] marca um slot nomeado, que as páginas que estendem o template podem preencher definindo um bloco com o mesmo nome. O conteúdo escrito entre [{% block title %}] e [{% endblock %}] é o conteúdo padrão do espaço reservado, usado por uma página que não define esse bloco. [site_name] é uma variável global, presente em todas as views (veja [config/packages/twig.yaml], abaixo);
  • linhas 10–11: a função [path] gera a URL de uma rota nomeada (exemplo 04), a partir dos valores de seus parâmetros, que são fornecidos em um array associativo do [Twig] ([{file: '...'}], o equivalente de [['file' => '...']] em [PHP]). A função [asset] gera a URL de um arquivo da pasta [public]. Escrever as URLs dos arquivos manualmente ([/css/styles.css]) também funcionaria, mas [path] e [asset] continuarão funcionando se a aplicação for instalada sob um prefixo de URL;
  • linha 16: [{% include %}] insere o conteúdo de outra view, neste caso a barra de navegação. A view incluída tem acesso às variáveis da view que a inclui;
  • linha 19: o espaço que cada página preenche com seu próprio conteúdo;
  • linha 23: a variável [app] está presente em todas as views: o [Symfony] armazena nela a requisição atual ([app.request]), a sessão ([app.session]), o usuário autenticado ([app.user], veja a seção sobre segurança), o nome da rota ([app.current_route])... [app.request.pathInfo] é o caminho da URL solicitada. O filtro [date] formata uma data; a string ['now'] designa a hora atual.

A classe [container] do [Bootstrap] centraliza o conteúdo e limita sua largura; [py-3] adiciona uma margem interna vertical (padding): o [Bootstrap] oferece centenas de classes desse tipo, que são combinadas no atributo [class]. A variável global [site_name] é declarada na configuração do [Twig]:

1
2
3
4
5
6
# config/packages/twig.yaml: a configuração do TwigBundle
twig:
    default_path: '%kernel.project_dir%/templates'
    # variáveis GLOBAIS, presentes em todas as views
    globals:
        site_name: 'My site'

As variáveis sob a chave [globals] são adicionadas a todas as views sem que as ações precisem fornecê-las. Uma variável global também pode ser um serviço (['@App\Service\...']), cujos métodos serão chamados pelas views.

4.3.3. A barra de navegação: templates/fragments/navbar.html.twig

{# um fragmento: um pedaço de página, inserido por include #}
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">{{ site_name }}</span>
  <div class="navbar-nav">
    {# path(): a URL de uma rota, designada pelo seu nome #}
    <a class="nav-link" href="{{ path('home') }}">Home</a>
    <a class="nav-link" href="{{ path('team') }}">Team</a>
    <a class="nav-link" href="{{ path('raw') }}">Page without layout</a>
  </div>
</nav>

Um fragmento: um pedaço de página que não faz sentido por si só. As classes [navbar], [navbar-brand] e [nav-link] são as da barra de navegação do [Bootstrap]. Os links são gerados por [path], com base nos nomes das rotas.

4.3.4. Uma macro: templates/macros.html.twig

{# MACROS: pedaços de página que têm parâmetros, como funções #}

{# um card do Bootstrap, com um nome e um papel #}
{% macro card(name, role = '') %}
  <div class="card">
    <div class="card-body">
      <h5 class="card-title">{{ name }}</h5>
      <p class="card-text">{{ role }}</p>
    </div>
  </div>
{% endmacro %}
  • Linha 4: uma macro é um trecho de página que tem parâmetros; essa é a função do [Twig]. Ela é declarada por [{% macro name(parameters) %}] ... [{% endmacro %}]; um parâmetro pode ter um valor padrão ([role = '']). Um arquivo pode conter várias macros. O card ([card]) é um componente do [Bootstrap].

Uma macro só pode acessar seus próprios parâmetros (e as variáveis globais); ela não pode acessar as variáveis da view que a chama. É isso que a torna reutilizável. (A biblioteca [Symfony UX Twig Component] oferece componentes mais completos, que são classes [PHP] associadas a uma view e usadas como tags HTML: [<twig:Card name="..." />]; não precisaremos deles.)

4.3.5. As páginas

{# esta página ESTENDE o layout: ela fornece apenas o conteúdo de seus blocos #}
{% extends 'layout.html.twig' %}
{# as macros do arquivo macros.html.twig, com o nome m #}
{% import 'macros.html.twig' as m %}

{% block content %}
  <h1>Welcome</h1>
  <p>This page only contains its own content: the header, the navigation
    bar and the footer come from the <code>layout.html.twig</code> layout.</p>
  {# a macro [card], chamada com dois parâmetros escritos na hora #}
  {{ m.card('A macro', 'called with parameters written on the spot') }}
{% endblock %}
  • linha 2: a página estende o template: o [Twig] gera a página do template, substituindo seus blocos pelos definidos pela página. Em uma view que estende um template, todo o conteúdo deve estar dentro de blocos: o texto escrito fora deles não aparece na página gerada;
  • linha 4: [{% import %}] importa macros de um arquivo sob um nome à sua escolha ([m]);
  • linhas 6–12: o bloco [content], que preenche o slot de mesmo nome. A página não define o bloco [title]: o slot mantém seu conteúdo padrão, “Home”;
  • linha 11: a chamada à macro [card], como função: [m.card(...)], dentro de [{{ }}], já que ela produz texto a ser inserido. Sua saída não é escapada uma segunda vez: o [Twig] sabe que ela já está protegida contra HTML (seus parâmetros, porém, foram escapados dentro da macro).
{% extends 'layout.html.twig' %}
{% import 'macros.html.twig' as m %}

{% block title %}Our team{% endblock %}

{% block content %}
  <h1>Our team</h1>
  <div class="row g-3">
    {% for member in members %}
      <div class="col-md-4">
        {# os parâmetros da macro são expressões quaisquer #}
        {{ m.card(member.name, member.role) }}
      </div>
    {% endfor %}
  </div>
{% endblock %}
  • linha 4: o bloco [title], em uma única linha;
  • linhas 8–15: um card por membro da equipe, em uma grade do [Bootstrap] ([row], [col-md-4]: três colunas em uma tela média ou grande, uma coluna em uma tela estreita);
  • linha 12: os parâmetros da macro são expressões arbitrárias.

O controller não contém nenhuma novidade:

<?php
// src/Controller/PagesController.php: três páginas

namespace App\Controller;

use App\Model\Member;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(methods: ['GET'])]
class PagesController extends AbstractController
{
    #[Route('/', name: 'home')]
    public function home(): Response
    {
        return $this->render('pages/home.html.twig');
    }

    #[Route('/team', name: 'team')]
    public function team(): Response
    {
        $members = [
            new Member('Marie Pélissier', 'Director'),
            new Member('Jacques Bromard', 'Developer'),
            new Member('Philippe Jandot', 'Graphic designer'),
        ];
        return $this->render('pages/team.html.twig', ['members' => $members]);
    }

    #[Route('/raw', name: 'raw')]
    public function raw(): Response
    {
        return $this->render('pages/raw.html.twig');
    }
}

Por fim, a terceira página não usa o template:

<!doctype html>
{# esta view não usa o layout: é uma página completa #}
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Raw page</title>
</head>
<body>
  <p>This page does not use the layout: no Bootstrap, no navigation bar.</p>
  <p><a href="{{ path('home') }}">Back to home</a></p>
</body>
</html>

4.3.6. Execução

Image

Image

Image

A página da equipe, como recebida pelo navegador:

curl http://localhost:8000/team
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Our team - My site</title>
    <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3">
        <nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">My site</span>
  <div class="navbar-nav">
        <a class="nav-link" href="/">Home</a>
    <a class="nav-link" href="/team">Team</a>
    <a class="nav-link" href="/raw">Page without layout</a>
  </div>
</nav>
    <main>
              <h1>Our team</h1>
  <div class="row g-3">
          <div class="col-md-4">
                  <div class="card">
    <div class="card-body">
      <h5 class="card-title">Marie Pélissier</h5>
      <p class="card-text">Director</p>
    </div>
  </div>

      </div>
...
      </div>
    </main>
        <footer class="footer">Page [/team] - © 2026 My site</footer>
  </div>
</body>
</html>

O navegador recebeu uma página completa: o template, o fragmento, a página e as macros foram montados no servidor. As URLs das folhas de estilo foram geradas por [path] e [asset]: são URLs relativas ao site. Você pode verificar se as folhas de estilo estão sendo servidas corretamente (a opção [-I] do [curl] exibe apenas os cabeçalhos da resposta):

curl -I http://localhost:8000/bootstrap/css/bootstrap.min.css
curl -I http://localhost:8000/css/styles.css
HTTP/1.1 200 OK
Cache-Control: public
Last-Modified: Sun, 27 Sep 2026 09:32:39 GMT
Content-Type: text/css; charset=UTF-8
Content-Length: 232111
Accept-Ranges: bytes
...
HTTP/1.1 200 OK
Content-Type: text/css; charset=UTF-8
Content-Length: 435

O primeiro arquivo foi enviado pelo nosso controller ([BinaryFileResponse] acrescenta a data de modificação do arquivo e permite que ele seja armazenado em cache: [Cache-Control: public]); o segundo foi enviado diretamente pelo servidor de desenvolvimento, sem passar pelo [Symfony]. Por fim, uma tentativa de sair da pasta:

curl -s -o /dev/null -w "%{http_code}\n" "http://localhost:8000/bootstrap/..%2F..%2F15-layout%2F.env"
404

(As opções [-s -o /dev/null -w "%{http_code}\n"] exibem apenas o código da resposta; no [Windows], digite [-o NUL]).

4.4. Exemplo 16: extensões do Twig

Uma view muitas vezes precisa formatar valores: um valor monetário com sua moeda, uma data escrita por extenso ou um texto em maiúsculas. Esse código não pertence à ação (que não cuida da apresentação), e o [Twig] não permite escrevê-lo na view (que não pode executar [PHP]; veja a introdução deste capítulo). Ele é escrito em [PHP], em uma extensão do [Twig]: uma classe que adiciona seus próprios filtros, funções ou testes à linguagem das views. Bibliotecas fornecem extensões prontas, como [twig/intl-extra], instalada com os exemplos, que formata datas e valores monetários de acordo com o idioma. Por fim, as macros criam trechos de HTML (Exemplo 15).

16-extensions/
├── config/
│   └── services.yaml
├── src/
│   ├── Controller/
│   │   └── PagesController.php
│   ├── EventListener/
│   │   └── SetLanguage.php
│   ├── Model/
│   │   └── Product.php
│   ├── Twig/
│   │   └── FormatsExtension.php
│   └── Kernel.php
├── templates/
│   ├── fragments/
│   │   └── navbar.html.twig
│   ├── layout.html.twig
│   ├── macros.html.twig
│   └── pages/
│       ├── home.html.twig
│       └── products.html.twig
└── ...

4.4.1. A extensão: src/Twig/FormatsExtension.php

<?php
// src/Twig/FormatsExtension.php: uma EXTENSION do Twig, que adiciona dois filtros
// à linguagem das views: money e long_date

namespace App\Twig;

use DateTimeInterface;
use IntlDateFormatter;
use NumberFormatter;
use Symfony\Component\HttpFoundation\RequestStack;
use Twig\Extension\AbstractExtension;
use Twig\TwigFilter;

class FormatsExtension extends AbstractExtension
{
    // a pilha de requisições, para saber o idioma da requisição atual
    public function __construct(private RequestStack $requests)
    {
    }

    // os filtros da extensão: seu nome nas views e o método que os implementa
    public function getFilters(): array
    {
        return [
            new TwigFilter('money', $this->money(...)),
            new TwigFilter('long_date', $this->longDate(...)),
        ];
    }

    // um valor em centavos, em uma moeda, no formato do idioma da
    // requisição: 114990 -> "€1,149.90" em inglês, "1 149,90 €" em francês.
    // A extensão intl do PHP conhece as convenções de cada país
    public function money(int $cents, string $currency = 'EUR'): string
    {
        $formatter = new NumberFormatter($this->language(), NumberFormatter::CURRENCY);
        return $formatter->formatCurrency($cents / 100, $currency);
    }

    // uma data por extenso, no idioma da requisição: "Sunday, September 27, 2026"
    public function longDate(DateTimeInterface $day): string
    {
        $formatter = new IntlDateFormatter($this->language(), IntlDateFormatter::FULL, IntlDateFormatter::NONE);
        return $formatter->format($day);
    }

    private function language(): string
    {
        return $this->requests->getCurrentRequest()?->getLocale() ?? 'en';
    }
}
  • Linha 14: uma extensão do [Twig] herda da classe [AbstractExtension]. Ela é um serviço, como toda classe da pasta [src]; o [Symfony] a reconhece como uma extensão ([autoconfigure]) e a repassa ao [Twig];
  • Linhas 17–19: a extensão precisa do idioma da requisição atual. Ela recebe a pilha de requisições ([RequestStack]), um serviço do [Symfony] que conhece a requisição atual (há uma pilha porque uma requisição pode disparar outra internamente);
  • linhas 22–28: o método [getFilters] retorna os filtros da extensão: para cada um, seu nome nas views e a função que o implementa. [$this->money(...)] (com as reticências) não chama o método: ela o transforma em um valor, uma função que pode ser chamada mais tarde (um first-class callable). Uma extensão também pode fornecer funções ([getFunctions]) e testes ([getTests]);
  • linhas 33–37: formatação de um valor recebido em centavos (veja o Exemplo 06). Isso depende do idioma: em francês, [1 149,90 €] (espaço para separar os milhares, vírgula decimal, símbolo depois do valor); em inglês, [€1,149.90]. A classe [NumberFormatter], parte da extensão [intl] do [PHP], oferece suporte às convenções de todos os países (ela usa dados do projeto Unicode CLDR): é criada para um idioma e um estilo (aqui, [CURRENCY], para valores monetários), e [formatCurrency] formata um valor, com a moeda designada por seu código internacional ([EUR], [USD]). O primeiro parâmetro do filtro é o valor filtrado; os parâmetros seguintes são suas propriedades na view ([priceCents|money('USD')]);
  • linhas 40–44: formatação de uma data usando a classe [IntlDateFormatter] da extensão [intl]: o estilo [FULL] escreve a data por extenso, incluindo o dia da semana ([Sunday, September 27, 2026]); o estilo [NONE], para a hora, não a inclui. O tipo [DateTimeInterface] aceita todas as datas do [PHP];
  • linhas 46–49: o idioma ([fr], [en]) da requisição atual, ou inglês se não houver requisição (em um comando de console, por exemplo). Veremos quem o define.

4.4.2. O idioma de cada requisição: src/EventListener/SetLanguage.php

<?php
// src/EventListener/SetLanguage.php: o idioma de cada requisição

namespace App\EventListener;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;

// priority: a ordem dos listeners do mesmo evento (o maior primeiro);
// 20: depois do roteamento (32), antes dos listeners do Symfony que usam o idioma (16, 15)
#[AsEventListener(event: KernelEvents::REQUEST, priority: 20)]
class SetLanguage
{
    // o parâmetro ?lang=fr da URL, inglês caso contrário
    public function __invoke(RequestEvent $event): void
    {
        $request = $event->getRequest();
        $request->setLocale($request->query->get('lang') === 'fr' ? 'fr' : 'en');
    }
}

Cada requisição tem um idioma (locale), que por padrão é o idioma [default_locale] especificado na configuração ([en] se nada estiver configurado). Aqui, o parâmetro [?lang=fr] da URL seleciona o francês; o inglês é o idioma padrão. Um listener do evento [kernel.request] (Exemplo 12) o define antes de cada ação usando o método [setLocale] da requisição. O parâmetro [priority] do atributo define a ordem dos listeners de um mesmo evento: os de maior prioridade são processados primeiro (o padrão é 0). [Symfony] tem ele próprio vários listeners de [kernel.request]: o roteamento (prioridade 32), seguido dos que preparam os serviços dependentes do idioma (16 e 15). O nosso deve ser executado entre os dois: 20. O comando [php bin/console debug:event-dispatcher kernel.request] exibe todos os listeners do evento, em ordem. O idioma definido dessa forma vale apenas para a requisição atual: a seguinte voltará ao idioma padrão. O capítulo sobre internacionalização usará esse mesmo idioma para traduzir os textos.

4.4.3. A configuração: config/services.yaml

# config/services.yaml: os serviços da aplicação (veja o exemplo 06)
services:
    _defaults:
        autowire: true
        autoconfigure: true

    App\:
        resource: '../src/'

    # o controller que serve o Bootstrap, compartilhado pelos exemplos 15 a 28 (veja o exemplo 15)
    Common\BootstrapController: ~

    # extensão Intl do Twig (biblioteca twig/intl-extra): os filtros
    # format_currency, format_date, format_number...
    Twig\Extra\Intl\IntlExtension: ~
  • Linha 15: os filtros da biblioteca [twig/intl-extra] são fornecidos pela extensão [IntlExtension]. Sua classe não está na pasta [src]: ela é declarada como um serviço, e o [Symfony] a reconhece como uma extensão do [Twig] ([autoconfigure]). (Em um projeto padrão, o pacote [twig/extra-bundle], instalado pelo [Symfony Flex], cuida disso sozinho.)

4.4.4. O controller: src/Controller/PagesController.php

<?php
// src/Controller/PagesController.php: duas páginas

namespace App\Controller;

use App\Model\Product;
use DateTimeImmutable;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(methods: ['GET'])]
class PagesController extends AbstractController
{
    #[Route('/', name: 'home')]
    public function home(): Response
    {
        return $this->render('pages/home.html.twig', ['today' => new DateTimeImmutable('today')]);
    }

    #[Route('/products', name: 'products')]
    public function products(): Response
    {
        return $this->render('pages/products.html.twig', ['products' => [
            new Product('keyboard', 2500, 12),
            new Product('mouse', 1250, 0),
            new Product('screen', 114990, 3),
        ]]);
    }
}

As ações passam valores brutos às views: uma data ([new DateTimeImmutable('today')], a data de hoje à meia-noite) e valores em centavos. A formatação fica a cargo das views. A classe [Product] combina um nome, um preço (em centavos; veja o Exemplo 06) e um nível de estoque.

4.4.5. As views

{# um link da barra de navegação, que recebe a classe [active] se a
   página atual estiver sob o caminho [path]. app.request.pathInfo: o caminho da
   requisição atual; starts with: um teste do Twig #}
{% macro link(href, path, text) %}
  <a class="nav-link{{ app.request.pathInfo starts with path ? ' active' }}" href="{{ href }}">{{ text }}</a>
{% endmacro %}

{# um badge do Bootstrap: verde se o produto estiver em estoque, vermelho caso contrário #}
{% macro badge(stock) %}
  <span class="badge {{ stock > 0 ? 'text-bg-success' : 'text-bg-danger' }}">{{ stock > 0 ? stock ~ ' in stock' : 'sold out' }}</span>
{% endmacro %}
  • linhas 4–6: uma macro que cria um link para a barra de navegação. O link da página atual recebe a classe [active] do [Bootstrap], que o destaca. Uma macro acessa a variável global [app] (Exemplo 15): [app.request.pathInfo] é o caminho da requisição atual; [starts with] é um operador do [Twig], que verifica o início de uma string. O operador ternário sem cláusula “else” ([condition ? ' active']) retorna uma string vazia se a condição for falsa (Exemplo 14);
  • Linhas 9–11: um badge do [Bootstrap], verde ([text-bg-success]) ou vermelho ([text-bg-danger]) conforme o estoque. O operador [~] do [Twig] concatena duas strings (o [.] do [PHP]).
{% import 'macros.html.twig' as m %}
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">Extensions</span>
  <div class="navbar-nav">
    {# 1. uma condição escrita na view; app.current_route: o nome da rota atual #}
    <a class="nav-link{{ app.current_route == 'home' ? ' active' }}" href="{{ path('home') }}">Home</a>
    {# 2. a macro [link] #}
    {{ m.link(path('products'), '/products', 'Products') }}
    {# 3. path() constrói a URL de uma rota nomeada; um parâmetro que não é
         parâmetro da rota é adicionado ao final da URL: /products?lang=fr #}
    <a class="nav-link" href="{{ path('products', {lang: 'fr'}) }}">Produits (fr)</a>
  </div>
</nav>
  • linha 1: um fragmento incluído (exemplo 15) não herda as importações da view que o inclui: ele importa por conta própria as macros de que precisa;
  • linha 6: o mesmo que com a macro, escrito diretamente na view, com o operador ternário. [app.current_route] é o nome da rota da requisição atual. A macro evita repetir a condição em cada link;
  • linha 8: a chamada à macro;
  • linha 11: um parâmetro de [path] que não é um parâmetro de rota é adicionado à URL como parâmetro de consulta: [/products?lang=fr].
{% extends 'layout.html.twig' %}
{% block title %}Home{% endblock %}

{% block content %}
  <h1>Home</h1>
  {# nosso filtro long_date #}
  <p>Today is {{ today|long_date }}.</p>
  {# app.request.locale: o idioma da requisição, definido pelo listener SetLanguage #}
  <p>Formatting language: {{ app.request.locale }}
    (<a href="{{ path('home', {lang: 'fr'}) }}">in French</a>, <a href="{{ path('home') }}">in English</a>)</p>
{% endblock %}
  • linha 7: nosso filtro [long_date];
  • linha 9: [app.request.locale], o idioma da requisição, definido pelo listener [SetLanguage].
{% extends 'layout.html.twig' %}
{% import 'macros.html.twig' as m %}
{% block title %}Products{% endblock %}

{% block content %}
  <h1>Products</h1>
  <table class="table table-sm w-auto">
    <thead><tr><th>Product</th><th>Price</th><th>Price in dollars</th><th>Stock</th></tr></thead>
    <tbody>
      {% for product in products %}
        <tr>
          {# um filtro do Twig (upper), depois nosso filtro money, sem e depois com um parâmetro #}
          <td>{{ product.name|upper }}</td>
          <td>{{ product.priceCents|money }}</td>
          <td>{{ product.priceCents|money('USD') }}</td>
          {# a macro [badge] constrói o HTML do badge #}
          <td>{{ m.badge(product.stock) }}</td>
        </tr>
      {% endfor %}
    </tbody>
  </table>
  {# o filtro format_currency da extensão Intl: um valor (aqui em unidades), uma
     moeda e o idioma da requisição #}
  <p>Total stock value: {{ (products|reduce((s, p) => s + p.priceCents * p.stock, 0) / 100)|format_currency('EUR', locale: app.request.locale) }}</p>
{% endblock %}
  • linha 13: um filtro do [Twig];
  • Linhas 14–15: nosso filtro [money], primeiro com sua moeda padrão, depois com um parâmetro;
  • linha 17: a chamada à macro [badge];
  • linha 24: o filtro [format_currency] da extensão Intl: um valor (aqui em euros: o estoque total, calculado por [reduce], dividido por 100), uma moeda e o idioma da requisição, passado por meio de um parâmetro nomeado do [Twig] ([locale: ...]). Essa extensão também fornece [format_date], [format_datetime], [format_number], [country_name], [language_name]... Nosso filtro [money] serve, portanto, a duplo propósito: nós o escrevemos para demonstrar como escrever uma extensão.

O template [layout.html.twig] é uma versão simplificada do template do Exemplo 15; seu atributo [lang] recebe o idioma da requisição ([<html lang="{{ app.request.locale }}">]).

4.4.6. Execução

Image

Image

A mesma página, com o parâmetro [?lang=fr]. Apenas a formatação dos números muda: o texto em si está fixo nas views. O capítulo sobre internacionalização também traduzirá o texto.

Image

Um trecho do HTML produz:

curl "http://localhost:8000/products?lang=en"
...
              <tr>
                    <td>KEYBOARD</td>
          <td>€25.00</td>
          <td>$25.00</td>
                    <td>  <span class="badge text-bg-success">12 in stock</span>
</td>
        </tr>
...
    <p>Total stock value: €3,749.70</p>
...

4.5. Exemplo 17: um formulário GET

Um formulário HTML envia seus campos ao servidor de duas maneiras, dependendo de seu atributo [method]:

  • [method="get"]: os campos são adicionados à URL como parâmetros ([/search?keyword=le&genre=novel]). É o método usado por um formulário que realiza uma consulta: uma busca ou um filtro. A URL com os resultados pode ser salva nos favoritos, compartilhada ou recarregada com segurança;
  • [method="post"]: os campos são incluídos no corpo da requisição (veja o Exemplo 11). É o método usado por um formulário que modifica dados: um cadastro, uma inclusão ou uma exclusão.

Este primeiro formulário é uma busca de livros. Ele é escrito à mão em HTML dentro da view; os exemplos seguintes usarão o componente Form do [Symfony] para os formulários.

4.5.1. O modelo: src/Model/Book.php e SearchModel.php

<?php
// src/Model/Book.php: um livro

namespace App\Model;

readonly class Book
{
    public function __construct(
        public string $title,
        public string $author,
        public string $genre,
    ) {
    }
}
<?php
// src/Model/SearchModel.php: o modelo da view: a entrada (para exibi-la
// novamente), os gêneros, os resultados

namespace App\Model;

readonly class SearchModel
{
    /**
     * @param list<string> $genres
     * @param list<Book> $results
     */
    public function __construct(
        public string $keyword,
        public string $genre,
        public array $genres,
        public array $results,
    ) {
    }
}
  • Linhas 14–19: o modelo da view contém a entrada do usuário, que o formulário exibe, a lista de gêneros sugeridos e os resultados.

4.5.2. O controller: src/Controller/BooksController.php

<?php
// src/Controller/BooksController.php: um formulário de pesquisa, enviado por GET

namespace App\Controller;

use App\Model\Book;
use App\Model\SearchModel;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

class BooksController extends AbstractController
{
    // CONSTANTES de classe: os dados, escritos no código para o exemplo
    private const GENRES = ['novel', 'poetry', 'drama'];

    /** @return list<Book> */
    private static function books(): array
    {
        return [
            new Book('Le Rouge et le Noir', 'Stendhal', 'novel'),
            new Book('Les Fleurs du mal', 'Baudelaire', 'poetry'),
            new Book('Madame Bovary', 'Flaubert', 'novel'),
            new Book('Alcools', 'Apollinaire', 'poetry'),
            new Book('Le Cid', 'Corneille', 'drama'),
        ];
    }

    // GET / e GET /search?keyword=...&genre=...: o formulário E seus resultados;
    // duas rotas para a mesma action: o atributo #[Route] pode ser repetido
    #[Route('/', name: 'books_home', methods: ['GET'])]
    #[Route('/search', name: 'books_search', methods: ['GET'])]
    public function search(Request $request): Response
    {
        // getString: o parâmetro, na forma de string ('' se estiver ausente)
        $keyword = $request->query->getString('keyword');
        $genre = $request->query->getString('genre');
        $word = mb_strtolower($keyword);
        $results = array_values(array_filter(self::books(), fn (Book $book) =>
            ($word === '' || str_contains(mb_strtolower($book->title), $word)
                || str_contains(mb_strtolower($book->author), $word))
            && ($genre === '' || $book->genre === $genre)));
        return $this->render('books/search.html.twig', [
            'model' => new SearchModel($keyword, $genre, self::GENRES, $results),
        ]);
    }
}
  • Linha 16: uma constante de classe privada, chamada [self::GENRES] ([self] refere-se à classe atual). Uma constante não pode conter objetos: os livros são, portanto, fornecidos por um método estático (linhas 19–28). Em uma aplicação real, eles viriam de um banco de dados;
  • linhas 32–33: duas rotas para a mesma ação: o atributo [#[Route]] pode ser repetido. Na primeira visita ([/]), não há parâmetros, e todos os livros são exibidos;
  • linhas 37–38: os campos do formulário são lidos como parâmetros da URL (exemplo 07). O método [getString] retorna o parâmetro como string, vazia se ele estiver ausente;
  • linhas 40–43: filtragem. A função [array_filter] mantém os elementos de um array para os quais a função dada retorna [true]: um livro é selecionado se a palavra-chave estiver vazia ou aparecer em seu título ou autor (em minúsculas dos dois lados; [mb_strtolower] trata corretamente os caracteres acentuados), e se o gênero estiver vazio ou corresponder ao gênero do livro. [array_filter] mantém as chaves dos itens selecionados (0, 2...): [array_values] as renumera a partir de 0;
  • linhas 44–46: o modelo da view.

4.5.3. A view: templates/books/search.html.twig

{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">Book search</h1>
  {# method="get": os campos são enviados na URL (?keyword=...&genre=...) #}
  <form method="get" action="{{ path('books_search') }}" class="row g-2 align-items-end mb-3">
    <div class="col-auto">
      <label class="form-label" for="keyword">Title or author</label>
      {# value: o campo exibe novamente o que foi digitado (escapado por {{ }}) #}
      <input class="form-control" id="keyword" name="keyword" value="{{ model.keyword }}">
    </div>
    <div class="col-auto">
      <label class="form-label" for="genre">Genre</label>
      <select class="form-select" id="genre" name="genre">
        <option value="">(all)</option>
        {% for genre in model.genres %}
          {# o atributo booleano selected, escrito se a condição for verdadeira, omitido caso contrário #}
          <option value="{{ genre }}"{{ genre == model.genre ? ' selected' }}>{{ genre }}</option>
        {% endfor %}
      </select>
    </div>
    <div class="col-auto">
      <button class="btn btn-primary" type="submit">Search</button>
    </div>
  </form>
  <p>{{ model.results|length }} book(s) found.</p>
  <ul>
    {% for book in model.results %}
      <li><i>{{ book.title }}</i>, {{ book.author }} ({{ book.genre }})</li>
    {% endfor %}
  </ul>
{% endblock %}
  • Linha 6: a tag [<form>]. O atributo [action] é a URL para a qual o formulário é enviado; [method="get"] coloca os campos na URL. As classes do [Bootstrap] dispõem os campos em uma única linha;
  • Linha 8: um rótulo. Seu atributo [for] especifica o identificador ([id]) do campo que ele descreve: clicar no rótulo coloca o cursor no campo, e os leitores de tela leem o rótulo junto com o campo;
  • linha 10: um campo de entrada. Seu atributo [name] é o nome do parâmetro enviado ao servidor: esse é o elo entre o formulário e a ação ([$request->query->getString('keyword')]). O atributo [value] é o valor exibido: a entrada anterior, reexibida (e escapada por [{{ }}], o que é essencial em um atributo: uma entrada contendo aspas ["] fecharia o atributo);
  • linhas 14–20: uma lista suspensa. Cada [<option>] tem um valor ([value]), enviado ao servidor, e um texto, exibido. A primeira opção, com valor vazio, significa “todos os gêneros”;
  • linha 18: a opção selecionada na requisição anterior recebe o atributo [selected]. Trata-se de um atributo booleano: sua simples presença basta; ele não tem valor. O operador ternário sem a parte “else” o escreve se a condição for verdadeira e não escreve nada caso contrário. [==] é a igualdade do [Twig];
  • linha 23: o botão de envio;
  • linha 26: o número de resultados.

4.5.4. Execução

Image

Vamos digitar [le] e selecionar o tipo [novel]:

Image

A URL da página de resultados contém os campos do formulário: [/search?keyword=le&genre=novel]. A resposta do formulário:

curl "http://localhost:8000/search?keyword=le&genre=novel"
...
    <form method="get" action="/search" class="row g-2 align-items-end mb-3">
    <div class="col-auto">
      <label class="form-label" for="keyword">Title or author</label>
            <input class="form-control" id="keyword" name="keyword" value="le">
    </div>
    <div class="col-auto">
      <label class="form-label" for="genre">Genre</label>
      <select class="form-select" id="genre" name="genre">
        <option value="">(all)</option>
                            <option value="novel" selected>novel</option>
                            <option value="poetry">poetry</option>
                            <option value="drama">drama</option>
              </select>
    </div>
...
  </form>
  <p>1 book(s) found.</p>
  <ul>
          <li><i>Le Rouge et le Noir</i>, Stendhal (novel)</li>
      </ul>
...

“Madame Bovary” não é selecionado: “le” não aparece nem no título nem no nome do autor.

4.6. Exemplo 18: campos de formulário

Este exemplo apresenta todos os tipos de campo de um formulário HTML, desta vez enviado por POST. Ele mostra como reexibir cada tipo de campo com seu valor atual, como o navegador envia os valores de cada um e como o servidor verifica se um valor recebido é de fato uma das opções disponíveis. Escrever tudo isso à mão, como no Exemplo 17, seria demorado e repetitivo. [Symfony] delega essa tarefa ao seu componente Form: um formulário é descrito por uma classe, seu tipo; o [Symfony] gera o HTML, lê os campos enviados, converte-os, valida-os e reexibe o formulário com a entrada do usuário e os eventuais erros. É o equivalente ao [WTForms] em [Python].

18-fields/
├── config/
│   └── packages/
│       ├── framework.yaml
│       └── twig.yaml
├── src/
│   ├── Controller/
│   │   └── FormController.php
│   ├── Form/
│   │   └── FieldsType.php
│   ├── Service/
│   │   └── ListsService.php
│   └── Kernel.php
├── templates/
│   ├── form/
│   │   └── form.html.twig
│   └── layout.html.twig
└── ...

4.6.1. O serviço de listas: src/Service/ListsService.php

<?php
// src/Service/ListsService.php: as listas oferecidas pelo formulário. Em uma
// aplicação real, elas viriam de um banco de dados.

namespace App\Service;

class ListsService
{
    // cada lista: um array associativo texto exibido => valor enviado
    public function titles(): array
    {
        return ['Mr' => 'Mr', 'Mme' => 'Mme', 'Melle' => 'Melle'];
    }

    public function countries(): array
    {
        return ['France' => 'fr', 'Belgium' => 'be', 'Switzerland' => 'ch', 'Canada' => 'ca'];
    }

    public function hobbies(): array
    {
        return ['reading' => 'reading', 'music' => 'music', 'sport' => 'sport', 'cinema' => 'cinema'];
    }

    public function languages(): array
    {
        return ['French' => 'French', 'English' => 'English', 'Spanish' => 'Spanish',
            'German' => 'German'];
    }
}

As listas suspensas do formulário (títulos de tratamento, países, hobbies, idiomas) são fornecidas por um serviço, seguindo o modelo do Exemplo 06: em uma aplicação real, viriam de um banco de dados. Cada lista é um array associativo: a chave é o texto exibido, e o valor é o que é enviado ao servidor (essa é a ordem esperada pelo componente Form).

4.6.2. A configuração

# config/packages/framework.yaml: a configuração do FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # as mensagens (erros dos formulários) em inglês (veja o exemplo 09)
    default_locale: en
    translator:
        default_path: '%kernel.project_dir%/translations'
    # a SESSÃO: o token anti-CSRF dos formulários é mantido ali (veja o exemplo 20)
    session: true
    # a proteção anti-CSRF dos formulários (veja mais adiante)
    csrf_protection: true
  • linhas 5–7: o idioma e o tradutor (Exemplo 09): as mensagens de erro do componente Form, assim como as do validador, estarão em inglês;
  • linha 9: a sessão do usuário, da qual falaremos mais no Exemplo 20: o componente Form armazena nela o token anti-CSRF (veja abaixo);
  • linha 11: a proteção anti-CSRF dos formulários.
1
2
3
4
5
# config/packages/twig.yaml: a configuração do TwigBundle
twig:
    default_path: '%kernel.project_dir%/templates'
    # o TEMA dos formulários: os campos são desenhados com as classes do Bootstrap 5
    form_themes: ['bootstrap_5_layout.html.twig']
  • Linha 5: o tema dos formulários. [Symfony] renderiza cada campo usando blocos do [Twig]; um tema fornece a versão adequada a um framework CSS. O tema [bootstrap_5_layout.html.twig], incluído no [Symfony], usa as classes do [Bootstrap] 5 ([form-control], [form-label], [is-invalid]...). A aplicação pode escrever seus próprios temas ou sobrescrever certos blocos de um tema existente.

4.6.3. Tipo de formulário: src/Form/FieldsType.php

<?php
// src/Form/FieldsType.php: a DESCRIÇÃO do formulário: seus campos, seu tipo, suas opções

namespace App\Form;

use App\Service\ListsService;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
use Symfony\Component\Form\Extension\Core\Type\DateType;
use Symfony\Component\Form\Extension\Core\Type\HiddenType;
use Symfony\Component\Form\Extension\Core\Type\PasswordType;
use Symfony\Component\Form\Extension\Core\Type\TextareaType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Validator\Constraints\NotBlank;

class FieldsType extends AbstractType
{
    // um tipo de formulário é um serviço: ele recebe o serviço de listas
    public function __construct(private ListsService $lists)
    {
    }

    // os campos do formulário, na ordem em que são exibidos
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            // botões de opção: uma lista de escolhas (ChoiceType), "expanded";
            // constraints: as restrições de validação do campo (veja o exemplo 08)
            ->add('title', ChoiceType::class, [
                'choices' => $this->lists->titles(),
                'expanded' => true,
                'label_attr' => ['class' => 'radio-inline'],
                'constraints' => [new NotBlank(message: 'The title is required.')],
            ])
            // um campo de entrada; required => false: o campo não é obrigatório
            ->add('name', TextType::class, ['required' => false])
            // uma senha: nunca exibida novamente na página
            ->add('password', PasswordType::class, ['label' => 'Password', 'required' => false])
            // uma data: um campo <input type="date">; o valor é uma string yyyy-mm-dd
            ->add('birth_date', DateType::class, [
                'label' => 'Date of birth',
                'widget' => 'single_text',
                'input' => 'string',
                'required' => false,
            ])
            // caixas de seleção: uma lista expandida de escolhas, com escolhas MÚLTIPLAS
            ->add('hobbies', ChoiceType::class, [
                'choices' => $this->lists->hobbies(),
                'expanded' => true,
                'multiple' => true,
                'label_attr' => ['class' => 'checkbox-inline'],
                'required' => false,
            ])
            // lista suspensa: uma lista de escolhas que não é expandida
            ->add('country', ChoiceType::class, ['choices' => $this->lists->countries()])
            // lista de seleção múltipla, exibida em quatro linhas
            ->add('languages', ChoiceType::class, [
                'label' => 'Spoken languages',
                'choices' => $this->lists->languages(),
                'multiple' => true,
                'attr' => ['size' => 4],
                'required' => false,
            ])
            ->add('comment', TextareaType::class, ['required' => false, 'attr' => ['rows' => 2]])
            // um campo oculto
            ->add('token', HiddenType::class);
    }
}
  • linha 17: um tipo de formulário herda da classe [AbstractType]. Ele é um serviço (localizado na pasta [src]): pode aceitar outros serviços, neste caso o serviço de listas (linha 20);
  • linha 25: o método [buildForm] descreve os campos adicionando-os ([add]) a um form builder: para cada campo, seu nome, tipo e opções. O nome do campo também é o nome do dado que ele exibe; seu rótulo, por padrão, é o seu nome formatado como texto ([name] torna-se “Name”);
  • Linhas 30–35: um campo [ChoiceType] é uma lista suspensa, definida pela opção [choices]. Com a opção [expanded], ele se torna um grupo de botões de opção (um campo de seleção única). A opção [label_attr] atribui uma classe ao rótulo do grupo: [radio-inline] especifica, no tema, botões lado a lado. A opção [constraints] define as restrições de validação do campo (exemplo 08): o título de tratamento é obrigatório;
  • linha 37: um campo [TextType] é um campo de entrada. A opção [required] tem como padrão [true]: o [Symfony] define então o atributo HTML [required], que o navegador verifica (Exemplo 19). Ela não envia nenhuma informação ao servidor: é uma restrição ([NotBlank]) que torna um campo obrigatório para o servidor;
  • linha 39: uma senha ([PasswordType]), que nunca é devolvida à página: seu campo está sempre vazio quando exibido;
  • linhas 41–46: uma data ([DateType]), exibida por um único campo [<input type="date">] (opção [widget]). Esse campo troca seu valor com o servidor no formato [yyyy-mm-dd], independentemente do formato em que o navegador o exibe; a opção [input] especifica que o dado é uma string (e não um objeto [DateTime], que é o padrão);
  • linhas 48–54: uma lista com escolhas múltiplas ([multiple]) expandida: caixas de seleção;
  • linha 56: uma lista de escolha única não expandida: uma lista suspensa;
  • linhas 58–64: uma lista de escolhas múltiplas não expandida: uma lista de seleção múltipla, exibida em quatro linhas (o atributo HTML [size], especificado pela opção [attr]);
  • linha 65: uma caixa de texto ([TextareaType]), com duas linhas;
  • linha 67: um campo oculto ([HiddenType]).

O [Symfony] oferece cerca de trinta tipos de campo: [EmailType], [IntegerType], [MoneyType], [UrlType], [CheckboxType], [FileType], [CountryType], [RepeatedType] (exemplo 19), [CollectionType] (uma lista de subformulários)...

4.6.4. O controller: src/Controller/FormController.php

<?php
// src/Controller/FormController.php: um formulário que usa todos os tipos de campos

namespace App\Controller;

use App\Form\FieldsType;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

class FormController extends AbstractController
{
    // GET: o formulário, com valores iniciais; POST: os campos enviados
    // são lidos, validados e depois exibidos novamente pelo mesmo formulário
    #[Route('/form', name: 'form', methods: ['GET', 'POST'])]
    public function form(Request $request): Response
    {
        // os valores iniciais (um por campo, um array para um campo múltiplo)
        $initial = ['title' => 'Mme', 'country' => 'fr', 'languages' => ['French'], 'token' => 'A7X2'];
        // createForm: o formulário, construído a partir de sua descrição
        $form = $this->createForm(FieldsType::class, $initial);
        // handleRequest: se a requisição for um POST, os campos recebidos são copiados
        // para o formulário e depois validados
        $form->handleRequest($request);
        $model = ['form' => $form];
        if ($form->isSubmitted()) {
            // o que o navegador realmente enviou, campo a campo
            $received = [];
            foreach ($request->request->all() as $name => $value) {
                foreach ((array) $value as $key => $v) {
                    $received[] = "{$name}[$key] = [".implode(', ', (array) $v).']';
                }
            }
            $model += [
                'received' => implode("\n", $received),
                'valid' => $form->isValid(),
                // getErrors(true): os erros de todos os campos
                'errors' => $form->getErrors(true),
                // getData(): os valores do formulário, convertidos por cada campo
                'data' => $form->getData(),
            ];
        }
        return $this->render('form/form.html.twig', $model);
    }
}
  • linha 16: uma única ação para os dois métodos: o GET exibe o formulário, o POST o processa. Essa é a forma padrão de escrever uma ação de formulário com o [Symfony];
  • linha 20: os valores iniciais do formulário: um array associativo, com um valor por campo (um array para um campo de vários valores);
  • linha 22: [createForm] cria o formulário, um objeto [Form], com base em seu tipo e nos dados iniciais;
  • linha 25: [handleRequest] examina a requisição. Para um GET, não faz nada. Para um POST que contenha os campos do formulário, copia-os para o formulário: cada campo converte seu valor (a data, as listas etc.), verifica se uma seleção está entre as que foram oferecidas e, em seguida, o formulário valida as restrições e o token anti-CSRF;
  • linha 27: [isSubmitted]: o formulário foi enviado?;
  • linhas 29–34: para este exemplo, a lista do que o navegador realmente enviou. Os campos de um formulário [Symfony] recebem o nome do formulário: [fields[name]], [fields[hobbies][]]. [PHP] os organiza, portanto, em um array chamado [fields] (Exemplo 10), que é então percorrido. [(array) $value] converte um valor único em um array de um elemento (um array continua sendo um array); [implode] combina os elementos de um array em uma string, separados pelo primeiro parâmetro;
  • linhas 35–42: o modelo da view recebe o que o servidor recebeu: o resultado da validação ([isValid]), os erros ([getErrors(true)]: os de todos os campos) e os dados do formulário ([getData]), convertidos por cada campo. O operador [+=] adiciona essas chaves ao array [$model];
  • linha 44: o formulário é passado à view, que o exibirá, junto com a entrada do usuário e os eventuais erros.

4.6.5. A view: templates/form/form.html.twig

{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">A complete form</h1>
  {# form_start: a tag <form>, aqui com o método POST e a URL da página #}
  {{ form_start(form, {attr: {style: 'max-width: 40rem'}}) }}
    {# form_row: um campo completo (rótulo, campo de entrada, erros) #}
    {{ form_row(form.title) }}
    <div class="row g-2">
      <div class="col">{{ form_row(form.name) }}</div>
      <div class="col">{{ form_row(form.password) }}</div>
      <div class="col">{{ form_row(form.birth_date) }}</div>
    </div>
    {{ form_row(form.hobbies) }}
    <div class="row g-2">
      <div class="col">{{ form_row(form.country) }}</div>
      <div class="col">{{ form_row(form.languages) }}</div>
    </div>
    {{ form_row(form.comment) }}
    <button class="btn btn-primary" type="submit">Send</button>
  {# form_end: os campos restantes (o campo oculto, o token anti-CSRF), depois </form> #}
  {{ form_end(form) }}

  {# is defined: true se a variável recebida foi passada para a view (formulário enviado) #}
  {% if received is defined %}
    <h2 class="h5 mt-3">What the server received</h2>
    <pre class="bg-light p-2 border">{{ received }}</pre>
    <p>Valid form: {{ valid ? 'yes' : 'no' }}</p>
    <ul>
      {% for error in errors %}
        {# error.origin: o campo com erro; error.message: a mensagem #}
        <li>{{ error.origin.getName() }}: {{ error.message }}</li>
      {% endfor %}
    </ul>
    {% if valid %}
      <p>The data of the form:</p>
      <ul>
        {# um laço sobre um array associativo: a chave e o valor #}
        {% for key, value in data %}
          <li>{{ key }}: {{ value is iterable ? value|join(', ') : value }}</li>
        {% endfor %}
      </ul>
    {% endif %}
  {% endif %}
{% endblock %}
  • linha 6: a função [form_start] escreve a tag [<form>]: por padrão, o método POST e a URL da página atual; o segundo parâmetro adiciona atributos HTML;
  • Linha 8: a função [form_row] escreve um campo completo: seu rótulo, seu campo de entrada (com seu valor atual) e seus erros, usando as classes do tema. [form.title] refere-se ao campo [title] do formulário. Também é possível escrever as partes separadamente: [form_label], [form_widget], [form_errors];
  • linhas 9–19: os demais campos, dispostos pelas classes de grade do [Bootstrap];
  • linha 22: [form_end] escreve os campos que ainda não foram escritos (neste caso, o campo oculto [token] e o campo oculto [_token], o token anti-CSRF) e depois fecha a tag [</form>];
  • linha 25: a verificação [is defined]: a variável [received] só existe após um envio;
  • linhas 30–33: os erros. Cada um é um objeto [FormError], em que [origin] é o campo que contém o erro;
  • Linhas 39–41: um laço [for] sobre um array associativo, que percorre tanto as chaves quanto os valores. O teste [is iterable] distingue os arrays (agrupados pelo filtro [join]) dos valores únicos.

O formulário inteiro poderia ter sido escrito em uma única linha: [{{ form(form) }}]. As funções [form_start], [form_row], e [form_end] permitem dispor os campos como se desejar.

4.6.6. Execução

Image

Os valores padrão estão visíveis: o botão de opção “Mme”, o país “France” e o idioma “French”. O HTML produzido é o seguinte (trechos, exibidos em várias linhas):

<form name="fields" method="post" style="max-width: 40rem">
  <fieldset class="mb-3"><legend class="col-form-label required">Title</legend>
    <div id="fields_title">
      <div class="form-check form-check-inline">
        <input type="radio" id="fields_title_0" name="fields[title]" required="required" class="form-check-input" value="Mr" />
        <label class="form-check-label required" for="fields_title_0">Mr</label></div>
      <div class="form-check form-check-inline">
        <input type="radio" id="fields_title_1" name="fields[title]" required="required" class="form-check-input" value="Mme" checked="checked" />
...
  <div class="mb-3"><label for="fields_name" class="form-label">Name</label>
    <input type="text" id="fields_name" name="fields[name]" class="form-control" /></div>
...
    <input type="checkbox" id="fields_hobbies_0" name="fields[hobbies][]" class="form-check-input" value="reading" />
...
  <select id="fields_country" name="fields[country]" class="form-select">
    <option value="fr" selected="selected">France</option><option value="be">Belgium</option>...
  <select id="fields_languages" name="fields[languages][]" size="4" class="form-select" multiple="multiple">
    <option value="French" selected="selected">French</option>...
...
  <input type="hidden" id="fields_token" name="fields[token]" value="A7X2" />
  <input type="hidden" id="fields__token" name="fields[_token]" data-controller="csrf-protection" value="9863be7bac.KU7NzSfFyCspR2sfBG_fTqNV6UuMueZ2pOsuPACnvFo.X32P9UOQm1FPIxhHUVqHGvcBmWbl36Il8KJsCVnS8A1ZJYGudJSrRmwoWw" />
</form>

O [Symfony] escreveu tudo: os identificadores ([fields_title_1]), os rótulos associados a seus campos, os nomes terminados em [[]] para os campos múltiplos (exemplo 10), os atributos [checked] e [selected] dos valores comuns e as classes do [Bootstrap]. O último campo oculto, [fields[_token]], contém o token anti-CSRF. Um ataque CSRF (Cross-Site Request Forgery) consiste em um site malicioso induzir o navegador da vítima a enviar um formulário à nossa aplicação. O navegador inclui os cookies da nossa aplicação na requisição, e portanto a sessão do usuário autenticado, fazendo a requisição parecer legítima. A contramedida: todo formulário da nossa aplicação contém um token aleatório vinculado à sessão do usuário, que o site malicioso não tem como conhecer. O componente Form adiciona esse token a todo formulário, e [handleRequest] rejeita qualquer formulário cujo token esteja ausente ou incorreto: nenhum formulário pode omiti-lo. (O atributo [data-controller] é usado por um script opcional do [Symfony], que reforça a proteção; ele não tem efeito aqui.) Vamos preencher o formulário e enviá-lo:

Image

A página mostra o que o servidor recebeu: um parâmetro por campo, com vários valores para as caixas de seleção e para a lista suspensa; a senha foi enviada, mas não é exibida novamente em seu campo. O campo oculto [token] foi devolvido como está: essa é a maneira de enviar de um lado para o outro informações que o usuário não vê (o estudo de caso usa isso para o número de versão de um registro). No entanto, um campo oculto não é um campo protegido: o usuário pode modificá-lo com as ferramentas de desenvolvedor de seu navegador, e o servidor deve validá-lo como qualquer outro campo. O token anti-CSRF também está incluído entre os campos recebidos; ele não faz parte dos dados do formulário.

Agora vamos enviar um formulário sem token, usando o [curl], e com um país que não estava listado como opção:

curl -g -d "fields[name]=Martin&fields[country]=xx" http://localhost:8000/form
...
        <h2 class="h5 mt-3">What the server received</h2>
    <pre class="bg-light p-2 border">fields[name] = [Martin]
fields[country] = [xx]</pre>
    <p>Valid form: no</p>
    <ul>
                      <li>fields: The CSRF token is invalid. Please try to resubmit the form.</li>
                      <li>title: The title is required.</li>
                      <li>country: The selected choice is invalid.</li>
          </ul>
...

O formulário é inválido por três razões: o token anti-CSRF está ausente (o erro é associado ao próprio formulário), nenhum título de tratamento foi enviado e o país [xx] não está entre as opções disponíveis. Essa última verificação é feita pelo próprio campo [ChoiceType], sem que a tenhamos solicitado: um usuário malicioso poderia enviar qualquer coisa, não apenas o que a página ofereceu. As mensagens estão em inglês: as do componente Form são traduzidas pelo [Symfony], assim como as do validador (exemplo 09). A resposta tem o código de status 422 (Unprocessable Content): [render] o seleciona automaticamente diante de um formulário enviado e inválido. Observe a diferença em relação a outros frameworks: o [Symfony] não rejeita a requisição antes da ação; é o formulário que se declara inválido, e é a ação que decide como proceder.

Para que o token seja aceito, o [curl] deve se comportar como um navegador: primeiro solicitar o formulário, guardando o cookie de sessão (opção [-c], que salva em um arquivo os cookies recebidos), depois reenviar o cookie (opção [-b]) e o token lido da página. A opção [--data-urlencode] codifica o próprio valor do token:

curl -c cookies.txt http://localhost:8000/form
curl -b cookies.txt -g --data-urlencode "fields[_token]=9863be7bac.KU7N..." -d "fields[name]=Martin&fields[country]=xx" http://localhost:8000/form
1
2
3
4
5
6
...
    <ul>
                      <li>title: The title is required.</li>
                      <li>country: The selected choice is invalid.</li>
          </ul>
...

(o token é o da página recebida pelo primeiro comando). Restam apenas os dois erros de entrada.

4.7. Exemplo 19: validação de formulário

Um formulário de cadastro, em que cada campo tem suas próprias regras de validação. Se ocorrer um erro, o formulário é reexibido com a entrada do usuário e uma mensagem abaixo de cada campo que contenha um erro. Este exemplo usa a abordagem padrão do [Symfony]: os dados do formulário são um objeto, cuja classe contém as restrições (Exemplo 08); o formulário preenche o objeto e depois o valida.

19-form-validation/
├── src/
│   ├── Controller/
│   │   └── RegistrationController.php
│   ├── Form/
│   │   └── RegistrationType.php
│   ├── Model/
│   │   └── Registration.php
│   └── Kernel.php
├── templates/
│   ├── registration/
│   │   ├── welcome.html.twig
│   │   └── registration.html.twig
│   └── layout.html.twig
└── ...

Os arquivos [config/packages/framework.yaml] e [config/packages/twig.yaml] são os do Exemplo 18.

4.7.1. Dados e suas restrições: src/Model/Registration.php

<?php
// src/Model/Registration.php: os dados do formulário de cadastro e suas restrições

namespace App\Model;

use Symfony\Component\Validator\Constraints as Assert;

class Registration
{
    #[Assert\NotBlank(message: 'The name is required.')]
    #[Assert\Length(max: 20, maxMessage: 'The name must not exceed 20 characters.')]
    public ?string $name = null;

    // Email: um endereço válido, com um nome de domínio completo (example.com, e não example)
    #[Assert\NotBlank(message: 'The email address is required.')]
    #[Assert\Email(message: 'Invalid email address.')]
    public ?string $email = null;

    #[Assert\NotBlank(message: 'The age is required.')]
    #[Assert\Range(notInRangeMessage: 'The age must be between 18 and 120 years.', min: 18, max: 120)]
    public ?int $age = null;

    #[Assert\NotBlank(message: 'The password is required.')]
    #[Assert\Length(min: 6, minMessage: 'The password must have at least 6 characters.')]
    public ?string $password = null;
}
  • Linha 8: uma classe comum cujas propriedades são públicas e editáveis; o formulário as preencherá uma a uma. Todas são inicializadas com [null]; o objeto está vazio na primeira exibição;
  • linhas 10–12: o nome é obrigatório e não deve exceder 20 caracteres. Cada restrição recebe aqui sua própria mensagem, em inglês (exemplo 09): [message] para [NotBlank], [maxMessage] para o excesso em [Length];
  • linhas 15–17: a restrição [Email] verifica se um endereço é válido e exige um nome de domínio totalmente qualificado ([example.com], não [example]);
  • linhas 19–21: a idade é um inteiro entre 18 e 120 ([notInRangeMessage]: a mensagem de [Range] quando há um mínimo e um máximo). O formulário terá convertido a entrada em um inteiro;
  • linhas 23–25: a senha deve ter pelo menos 6 caracteres.

4.7.2. O formulário: src/Form/RegistrationType.php

<?php
// src/Form/RegistrationType.php: os campos do formulário de cadastro

namespace App\Form;

use App\Model\Registration;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\EmailType;
use Symfony\Component\Form\Extension\Core\Type\IntegerType;
use Symfony\Component\Form\Extension\Core\Type\PasswordType;
use Symfony\Component\Form\Extension\Core\Type\RepeatedType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

class RegistrationType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            // attr: atributos HTML adicionais no campo de entrada (para a
            // validação pelo navegador, veja mais adiante)
            ->add('name', TextType::class, ['attr' => ['maxlength' => 20]])
            ->add('email', EmailType::class, ['label' => 'Email address'])
            // IntegerType: um inteiro; uma entrada que não seja um inteiro produz
            // o erro invalid_message
            ->add('age', IntegerType::class, [
                'label' => 'Age',
                'attr' => ['min' => 18, 'max' => 120],
                'invalid_message' => 'An integer is expected.',
            ])
            // RepeatedType: DOIS campos que devem receber o mesmo valor (a
            // senha e sua confirmação); um único valor nos dados
            ->add('password', RepeatedType::class, [
                'type' => PasswordType::class,
                'first_options' => ['label' => 'Password', 'attr' => ['minlength' => 6]],
                'second_options' => ['label' => 'Confirmation'],
                'invalid_message' => 'The confirmation does not match the password.',
            ]);
    }

    // as opções do formulário: seus dados são um objeto Registration
    public function configureOptions(OptionsResolver $options): void
    {
        $options->setDefaults(['data_class' => Registration::class]);
    }
}
  • linha 23: a opção [attr] adiciona atributos HTML ao campo de entrada: [maxlength] limita a entrada no navegador;
  • linha 24: um campo [EmailType] gera um [<input type="email">], que o navegador pode validar;
  • linhas 27–31: um campo [IntegerType] gera um [<input type="number">] e converte a entrada em um inteiro. Uma entrada que não seja um inteiro não pode ser convertida: trata-se de um erro de conversão (e não de validação; veja o exemplo 08), cuja mensagem de erro é fornecida pela opção [invalid_message];
  • Linhas 34–39: um campo [RepeatedType] é formado por dois campos (aqui, dois [PasswordType] campos), que devem conter o mesmo valor: a senha e sua confirmação. Cada um tem suas próprias opções ([first_options], [second_options]); se as duas entradas diferirem, o erro é [invalid_message]. Os dados têm apenas um valor: a senha;
  • linhas 43–46: o método [configureOptions] define as opções do próprio formulário: [data_class] indica que seus dados são um objeto [Registration]. Cada campo lê e escreve a propriedade de mesmo nome.

O [Symfony] também pode inferir o tipo de um campo com base nas restrições e no tipo da propriedade: [->add('age')], que não tem tipo, produziria um [IntegerType], com os atributos [min] e [max] inferidos de [Range]. Escrevemos isso explicitamente, para maior clareza.

4.7.3. O controller: src/Controller/RegistrationController.php

<?php
// src/Controller/RegistrationController.php: um formulário validado pelo servidor

namespace App\Controller;

use App\Form\RegistrationType;
use App\Model\Registration;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\MapQueryParameter;
use Symfony\Component\Routing\Attribute\Route;

class RegistrationController extends AbstractController
{
    // GET /register: o formulário; ?html5=true: deixamos o navegador
    // validá-lo antes do envio. POST /register: o formulário enviado
    #[Route('/register', name: 'register', methods: ['GET', 'POST'])]
    public function register(Request $request, #[MapQueryParameter] bool $html5 = false): Response
    {
        $registration = new Registration();
        $form = $this->createForm(RegistrationType::class, $registration);
        $form->handleRequest($request);
        // isValid: os campos puderam ser convertidos e o objeto Registration
        // respeita suas restrições
        if ($form->isSubmitted() && $form->isValid()) {
            return $this->render('registration/welcome.html.twig', ['registration' => $registration]);
        }
        // a primeira exibição, ou um formulário inválido, exibido novamente com a entrada
        // e os erros (render então o devolve com o código 422)
        return $this->render('registration/registration.html.twig',
            ['form' => $form, 'html5' => $html5]);
    }
}
  • linha 19: o parâmetro [?html5=true] ativa a validação do navegador (veja abaixo). [#[MapQueryParameter]] o converte em booleano (exemplo 07);
  • linhas 21–23: o objeto vazio [Registration] é passado ao formulário; [handleRequest] o preencherá com os campos enviados;
  • linhas 26–28: [isValid] é verdadeiro se todos os campos puderam ser convertidos e se o objeto [Registration] atende às suas restrições. A página de boas-vindas recebe então o objeto preenchido (o exemplo seguinte mostrará que é melhor redirecionar após um POST bem-sucedido);
  • linhas 31–32: caso contrário, o formulário é exibido: vazio na primeira exibição; após um envio inválido, ele mostra a entrada e os erros, com o código 422 (exemplo 18).

O formulário inválido é, portanto, reexibido pela própria ação do POST, que mantém a entrada e os erros: essa é a abordagem adotada pelo [Symfony]. Outros frameworks, como o [Laravel], respondem, em vez disso, redirecionando para a página do formulário, mantendo a entrada e os erros na sessão para a requisição seguinte.

4.7.4. As views

{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">Registration</h1>
  {% if html5 %}
    <p>Browser validation <b>enabled</b> - <a href="{{ path('register') }}">disable it</a></p>
  {% else %}
    <p>Browser validation <b>disabled</b> - <a href="{{ path('register', {html5: 'true'}) }}">enable it</a></p>
  {% endif %}
  {# novalidate: o navegador ignora os atributos required, min... e envia
     o formulário como está; somente o servidor valida #}
  {{ form_start(form, {attr: html5 ? {} : {novalidate: 'novalidate'}}) }}
    {# form_widget: todos os campos do formulário, cada um com seu rótulo e seus erros #}
    {{ form_widget(form) }}
    <button class="btn btn-primary" type="submit">Register</button>
  {{ form_end(form) }}
{% endblock %}

{% block page_bottom %}
  {# o erro global, no final da página, sobre um fundo rosa claro. vars: as
     informações do formulário (enviado? válido?) #}
  {% if form.vars.submitted and not form.vars.valid %}
    <div class="error-area" role="alert">The form contains errors.</div>
  {% endif %}
{% endblock %}
  • Linha 12: o atributo [novalidate] desativa a validação do navegador: o formulário é enviado como está, e somente o servidor o valida. É isso que queremos observar primeiro. O operador ternário escolhe entre dois arrays de atributos;
  • linha 14: [form_widget(form)], aplicado ao formulário inteiro, escreve todos os seus campos, cada um com seu rótulo, sua entrada e suas mensagens de erro: o tema do [Bootstrap] destaca um campo inválido em vermelho (classe [is-invalid]) e exibe sua mensagem abaixo dele (classe [invalid-feedback]). Não precisamos escrever nenhum componente para isso;
  • linhas 19–25: o bloco [page_bottom], definido pelo template (veja abaixo). [form.vars] contém os dados do formulário, calculados para a view: [submitted] (enviado?), [valid] (válido?), [value], [errors]... Se o formulário foi enviado e é inválido, uma mensagem geral aparece em uma área cujo estilo é definido por [public/css/styles.css] (exemplo 15). O atributo [role="alert"] sinaliza isso aos leitores de tela.
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Registration</title>
  <link rel="stylesheet" href="{{ path('bootstrap', {file: 'css/bootstrap.min.css'}) }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3" style="max-width: 36rem">
    <main>
      {% block content %}{% endblock %}
    </main>
    {# um bloco que as páginas podem preencher, no final da página #}
    {% block page_bottom %}{% endblock %}
  </div>
</body>
</html>
  • Linha 15: um segundo bloco, [page_bottom], que é vazio por padrão: um template pode ter quantos blocos forem necessários.
1
2
3
4
5
6
7
8
{% extends 'layout.html.twig' %}

{% block content %}
  {# registration: o objeto Registration, preenchido pelo formulário #}
  <h1 class="h3">Welcome {{ registration.name }}</h1>
  <p>Your registration is saved: address <b>{{ registration.email }}</b>,
    age <b>{{ registration.age }}</b> years.</p>
{% endblock %}

[registration] é o objeto [Registration], preenchido e validado: o nome teve seus espaços removidos (veja abaixo) e a idade é um inteiro.

4.7.5. Execução

Vamos enviar um formulário cheio de erros: um nome formado por espaços, um endereço sem domínio completo, uma idade de 12, uma senha curta demais e uma confirmação diferente:

Image

A entrada foi mantida (exceto as senhas), e cada erro é sinalizado abaixo do campo correspondente. O nome formado por espaços é sinalizado como ausente: o componente Form remove os espaços ao redor de cada entrada (opção de campo [trim], definida como true por padrão). A senha, porém, tem apenas um erro, que está na confirmação: quando as duas entradas diferem, o campo [RepeatedType] não retorna nenhum valor, e o tamanho não é verificado. A URL é a do formulário, e [/register] indica que a página foi exibida pela ação em resposta ao POST. Com o [curl], fornecendo o token anti-CSRF como no Exemplo 18, também é possível enviar algo que um navegador não enviaria, uma idade não numérica:

curl -i -b cookies.txt -g --data-urlencode "registration[_token]=..." -d "registration[name]=Martin&registration[email]=martin@example.com&registration[age]=abc&registration[password][first]=abcdef&registration[password][second]=abcdef" http://localhost:8000/register
1
2
3
4
5
HTTP/1.1 422 Unprocessable Content
...
<input type="number" id="registration_age" name="registration[age]" required="required" min="18" max="120" aria-describedby="registration_age_error1" aria-invalid="true" class="form-control is-invalid" value="abc" />
<div class="invalid-feedback d-block" id="registration_age_error1">An integer is expected.</div>
...

Vemos a entrada reexibida, junto com os atributos HTML5 ([required], [min], [max]), a classe [is-invalid], a mensagem de conversão e os atributos [aria-...], que vinculam o campo à sua mensagem para os leitores de tela.

4.7.6. Validação no navegador

Vamos remover o atributo [novalidate] seguindo o link “ativar” (parâmetro [?html5=true]). O navegador passa então a verificar os atributos [required], [type="email"], [min], [maxlength]... antes de enviar o formulário e exibe suas próprias mensagens em um balão abaixo do primeiro campo com erro (“Please fill in this field”, “The value must be greater than or equal to 18” etc.): o formulário não é enviado enquanto houver um erro. [Symfony] gera esses atributos automaticamente: [required] para qualquer campo (opção [required], por exemplo, 18), [type="email"] e [type="number"] conforme o tipo do campo; [maxlength], [min], [max] e [minlength] vêm de nossas [attr] opções. Eles devem permanecer coerentes com as restrições.

Essa validação é conveniente para o usuário: é imediata, sem idas e vindas ao servidor. Mas ela não substitui a validação no servidor: um usuário pode desativá-la, e um programa como o [curl] a ignora completamente. A regra é absoluta: o servidor sempre valida; a validação no navegador é apenas uma conveniência adicional.

Uma entrada correta, enfim. O nome, digitado com espaços de ambos os lados, foi limpo pelo formulário:

Image

4.8. Exemplo 20: O padrão Post/Redirect/Get

Quando uma ação POST responde com uma página, essa página é o resultado de um POST. Se o usuário recarrega a página (pressiona [F5]), o navegador reenvia a requisição POST, depois de exibir um aviso que poucas pessoas leem: o comando é enviado duas vezes, e a mensagem é postada duas vezes. O padrão Post/Redirect/Get (PRG) evita esse problema: uma ação POST bem-sucedida não devolve uma página; ela responde com um redirecionamento (exemplo 04) para uma página GET, que o navegador solicita imediatamente. Recarregar essa página apenas reexecuta a ação GET.

Resta um problema: a página GET gostaria de exibir uma mensagem (“a tarefa foi adicionada”), mas quem conhece essa mensagem é a ação POST, e ela não pode passar uma variável a uma requisição que ainda não ocorreu. A solução: a mensagem flash, colocada na sessão pela ação POST, é mantida até ser lida, exibida e então descartada.

4.8.1. Configuração: config/packages/framework.yaml

# config/packages/framework.yaml: a configuração do FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # a SESSÃO: seus dados são armazenados no servidor, um arquivo por sessão,
    # na pasta var/sessions/dev (handler_id: null: os arquivos próprios do PHP)
    session:
        handler_id: null
        save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
    # os LOCKS (componente Lock): arquivos bloqueados (flock) da pasta var/lock
    lock: 'flock://%kernel.project_dir%/var/lock'
  • Linhas 6–8: a sessão do usuário (capítulo sobre escopos): dados específicos de um navegador, mantidos de uma requisição para a seguinte. Ela é armazenada no servidor; o navegador guarda apenas um identificador dela, em um cookie. [handler_id: null] delega a tarefa de armazenar esses dados ao próprio [PHP], que guarda cada sessão em um arquivo; [save_path] escolhe a pasta, [var/sessions/dev], para que possamos examiná-las. [%kernel.environment%] é o ambiente ([dev]);
  • linha 10: os locks (bloqueios; o componente Lock, descrito adiante), armazenados na pasta [var/lock].

4.8.2. O serviço: src/Service/TasksService.php

<?php
// src/Service/TasksService.php: a lista de tarefas, compartilhada por todos os
// usuários. No PHP, os objetos não sobrevivem à requisição: a lista é
// armazenada no CACHE da aplicação (aqui, um arquivo da pasta var/cache/dev/pools)

namespace App\Service;

use Psr\Cache\CacheItemPoolInterface;
use Symfony\Component\Lock\LockFactory;

class TasksService
{
    private const KEY = 'tasks';

    // o cache da aplicação (o serviço cache.app) e a factory de locks
    public function __construct(
        private CacheItemPoolInterface $cache,
        private LockFactory $locks,
    ) {
    }

    /** @return list<string> */
    public function list(): array
    {
        // o item de cache armazenado sob a chave [tasks]; isHit: ele existe
        $item = $this->cache->getItem(self::KEY);
        return $item->isHit() ? $item->get() : ['Read chapter 3'];
    }

    public function add(string $label): void
    {
        // várias requisições podem ser executadas AO MESMO TEMPO (o servidor as trata
        // em vários processos): um lock garante que apenas uma por
        // vez leia, modifique e reescreva a lista
        $lock = $this->locks->createLock('tasks');
        // acquire(true): espera até que o lock esteja livre e então o obtém
        $lock->acquire(true);
        try {
            $tasks = $this->list();
            $tasks[] = $label;
            // o item de cache recebe seu novo valor, sem limite de tempo
            $item = $this->cache->getItem(self::KEY);
            $this->cache->save($item->set($tasks));
        } finally {
            // finally: o lock é liberado em todos os casos, mesmo após uma exceção
            $lock->release();
        }
    }
}

A lista de tarefas é compartilhada por todos os usuários e deve persistir de uma requisição para a seguinte. Em [Java], [C#] ou [Python], ela ficaria na memória, dentro de um único serviço. Em [PHP], isso é impossível: como vimos nos exemplos 01 e 06, nada sobrevive à requisição. A lista deve, portanto, ser armazenada fora do [PHP]: em um banco de dados, em um arquivo... ou no cache da aplicação, que usamos aqui.

  • Linhas 16–20: o serviço recebe dois serviços do [Symfony]. O primeiro é o cache da aplicação (o serviço [cache.app], do componente Cache), um repositório de pares chave-valor, representado pela interface padronizada [CacheItemPoolInterface] (o padrão PSR-6). Por padrão, ele armazena seus valores em arquivos dentro da pasta [var/cache/dev/pools]; em produção, prefere-se um servidor dedicado, como o [Redis] (uma linha de configuração). O segundo é a fábrica de locks do componente Lock;
  • linhas 23–28: [getItem] recupera o item de cache armazenado sob uma chave; [isHit] verifica se ele existe, e [get] devolve seu valor. Qualquer valor (aqui, um array de strings) pode ser armazenado: o [Symfony] o serializa, ou seja, converte-o em texto, usando a função [serialize] do [PHP];
  • Linhas 35–47: o servidor de desenvolvimento, como um servidor de produção, pode processar várias requisições ao mesmo tempo, em vários processos (a variável de ambiente [PHP_CLI_SERVER_WORKERS] define o número de processos de [php -S]). Duas adições simultâneas poderiam ler a mesma lista, cada uma acrescentar sua própria tarefa e depois gravá-la de volta: a segunda gravação sobrescreveria a primeira tarefa. Um lock garante que apenas uma requisição por vez execute o código que ele protege: [createLock('tasks')] cria um lock nomeado; [acquire(true)] espera que ele fique disponível e então o adquire; [release()] o libera. Aqui, o lock é um arquivo na pasta [var/lock], bloqueado pelo sistema operacional (a função [flock]); como alternativa, vários servidores compartilhariam um lock armazenado no [Redis] ou em um banco de dados;
  • linhas 38–47: o bloco [try] … [finally] garante que o lock seja liberado em todos os casos, mesmo que uma exceção interrompa o código que ele protege;
  • linhas 42–43: o item de cache recebe seu novo valor ([set]) e depois é salvo ([save]). Sem uma duração especificada, ele é mantido indefinidamente ([expiresAfter(3600)] o manteria por uma hora).

4.8.3. O controller: src/Controller/TasksController.php

<?php
// src/Controller/TasksController.php: o padrão Post / Redirect / Get

namespace App\Controller;

use App\Service\TasksService;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

class TasksController extends AbstractController
{
    public function __construct(private TasksService $tasks)
    {
    }

    // GET /tasks: a lista e o formulário de adição
    #[Route('/tasks', name: 'tasks', methods: ['GET'])]
    public function display(): Response
    {
        return $this->render('tasks/tasks.html.twig', ['tasks' => $this->tasks->list()]);
    }

    // POST /tasks: o padrão Post / Redirect / Get
    #[Route('/tasks', name: 'tasks_add', methods: ['POST'])]
    public function add(Request $request): Response
    {
        $label = trim($request->request->getString('label'));
        if ($label === '' || mb_strlen($label) > 40) {
            // entrada inválida: exibimos a página novamente, sem redirecionamento
            return $this->render('tasks/tasks.html.twig', ['tasks' => $this->tasks->list(),
                'label' => $label,
                'error' => 'The label must have 1 to 40 characters.']);
        }
        $this->tasks->add($label);
        // addFlash deixa uma mensagem "flash" na sessão: ela sobreviverá ao
        // redirecionamento, para a PRÓXIMA requisição
        $this->addFlash('success', "The task [$label] has been added.");
        // nenhuma página: um redirecionamento para a página GET
        return $this->redirectToRoute('tasks');
    }

    // POST /tasks/without-prg: o contraexemplo (uma página em resposta ao POST)
    #[Route('/tasks/without-prg', name: 'tasks_without_prg', methods: ['POST'])]
    public function addWithoutPrg(Request $request): Response
    {
        $this->tasks->add(trim($request->request->getString('label')) ?: '(untitled)');
        return $this->render('tasks/tasks.html.twig', ['tasks' => $this->tasks->list(), 'withoutPrg' => true]);
    }
}
  • linhas 29–35: a entrada é validada manualmente para manter o exemplo conciso ([trim] remove os espaços das extremidades). Uma entrada inválida é reexibida sem redirecionamento: não há nada a proteger contra um envio duplicado, já que nada foi modificado;
  • linha 39: o método [addFlash] de [AbstractController] coloca uma mensagem flash do tipo [success] na sessão (o tipo é arbitrário: permite distinguir mensagens de sucesso e de erro, etc.);
  • linha 41: o redirecionamento para a página GET, chamada [tasks] (exemplo 04);
  • linhas 45–50: o contraexemplo: uma página em resposta a um POST. O operador [?:] devolve seu operando da esquerda se ele for “verdadeiro” (aqui, uma string não vazia) e, caso contrário, o operando da direita.

4.8.4. As views

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Tasks</title>
  <link rel="stylesheet" href="{{ path('bootstrap', {file: 'css/bootstrap.min.css'}) }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3" style="max-width: 36rem">
    {# as mensagens flash [success], no topo da página: deixadas ANTES do redirecionamento;
       app.flashes as REMOVE da sessão ao lê-las #}
    {% for message in app.flashes('success') %}
      <div class="alert alert-success" role="status">{{ message }}</div>
    {% endfor %}
    <main>
      {% block content %}{% endblock %}
    </main>
    {% if error is defined %}
      <div class="error-area" role="alert">{{ error }}</div>
    {% endif %}
  </div>
</body>
</html>
  • Linhas 13–15: [app.flashes('success')] devolve a lista de mensagens flash do tipo [success] e as remove da sessão: uma mensagem flash é exibida uma única vez. A [alert alert-success] classe do [Bootstrap] exibe a mensagem em uma moldura verde;
  • linhas 19–21: a mensagem de erro, na parte inferior da página, quando a ação gerou uma.
{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">My tasks</h1>
  <ol>
    {% for task in tasks %}
      <li>{{ task }}</li>
    {% endfor %}
  </ol>
  <form method="post" action="{{ path('tasks_add') }}" class="d-flex gap-2">
    <input class="form-control" name="label" value="{{ label ?? '' }}" placeholder="New task">
    <button class="btn btn-primary text-nowrap" type="submit">Add</button>
    {# formaction: este botão envia o MESMO formulário para outro endereço #}
    <button class="btn btn-outline-secondary text-nowrap" type="submit" formaction="{{ path('tasks_without_prg') }}">Add without PRG</button>
  </form>
  {% if withoutPrg is defined %}
    <p class="text-danger mt-2">Page displayed in response to a POST: press F5 and the task will be added a second time.</p>
  {% endif %}
{% endblock %}
  • linha 11: o operador [??] do [Twig] devolve seu operando da direita se o operando da esquerda não existir (ou for igual a [null]): a variável [label] só existe após uma entrada inválida;
  • Linha 14: o atributo [formaction] de um botão envia o formulário para um endereço diferente do especificado pelo atributo [action] do formulário: um único formulário pode, assim, disparar duas ações diferentes.

Este formulário escrito à mão não tem um token anti-CSRF: para manter o exemplo simples, vamos adicioná-lo no próximo exemplo.

4.8.5. Onde as mensagens flash são armazenadas?

Entre a requisição POST e a requisição GET seguinte, a mensagem precisa ser armazenada em algum lugar: na sessão do usuário ou no servidor. Vamos examinar isso com o [curl], armazenando os cookies em um arquivo (opções [-c] e [-b], Exemplo 18):

curl -i -b cookies.txt -c cookies.txt -d "label=Do%20the%20exercises" http://localhost:8000/tasks
1
2
3
4
5
6
7
HTTP/1.1 302 Found
Cache-Control: max-age=0, must-revalidate, private
Location: /tasks
Content-Type: text/html; charset=utf-8
Expires: Sun, 27 Sep 2026 09:36:41 GMT
Set-Cookie: PHPSESSID=1e1f574eccd93268b1eb829dd714a029; path=/; httponly; samesite=lax
...

A resposta ao POST é um redirecionamento (código de status 302, cabeçalho [Location]), acompanhado do cookie de sessão, [PHPSESSID] (o nome que o [PHP] atribui a esse cookie), que contém o ID da sessão: 32 caracteres aleatórios impossíveis de adivinhar. Esse cookie é [httponly] (o [JavaScript] da página não consegue lê-lo) e [samesite=lax] (o navegador não o envia com uma requisição POST originada em outro site). Os cabeçalhos [Cache-Control] e [Expires] impedem o armazenamento em cache de uma resposta que depende de uma sessão. O identificador também é o nome do arquivo de sessão no servidor: [var/sessions/dev/sess_1e1f574eccd93268b1eb829dd714a029]. Eis esse arquivo, após a requisição POST:

_symfony_flashes|a:1:{s:7:"success";a:1:{i:0;s:43:"The task [Do the exercises] has been added.";}}_sf2_meta|a:3:{s:1:"u";i:1790501801;s:1:"c";i:1790501801;s:1:"l";i:0;}

Este é o formato de serialização das sessões em [PHP]: cada dado de sessão é escrito na forma [name|serialized value]. [a:1:{...}] declara um array com 1 elemento, [s:7:"success"] uma string de 7 bytes... Ele contém as mensagens flash ([_symfony_flashes]), ordenadas por tipo, e metadados do [Symfony] ([_sf2_meta]: as datas de criação e de último uso da sessão). Vamos seguir o redirecionamento reenviando o cookie:

curl -i -b cookies.txt -c cookies.txt http://localhost:8000/tasks
1
2
3
4
5
6
7
HTTP/1.1 200 OK
...
              <div class="alert alert-success" role="status">The task [Do the exercises] has been added.</div>
...
          <li>Read chapter 3</li>
          <li>Do the exercises</li>
...

A mensagem é exibida e removida da sessão por [app.flashes]. A sessão, agora vazia, chegou até a desaparecer: o [Symfony] não armazena uma sessão vazia, e o arquivo foi excluído. Uma nova requisição GET não exibiria mais a mensagem. A lista de tarefas, por outro lado, é armazenada em um arquivo de cache, cujo nome é calculado a partir da chave ([var/cache/dev/pools/app/VT2eLxVxyZ/P/W/CElt3eODhIKkushDZW1A]):

1
2
3
0
tasks
a:2:{i:0;s:14:"Read chapter 3";i:1;s:16:"Do the exercises";}

A primeira linha é a data de expiração do valor (0: nunca), a segunda é a chave e a terceira é a lista serializada. Quanto ao lock, trata-se de um arquivo vazio, [var/lock/sf.tasks.CFFUCEx.lock], que o sistema bloqueia durante uma modificação.

4.8.6. Execução

Adição de uma tarefa: o navegador seguiu o redirecionamento; a URL é a da página correspondente ao GET, que pode ser recarregada com segurança.

Image

Uma entrada inválida, reexibida com sua mensagem de erro:

Image

O contraexemplo: a página é a resposta ao POST, e sua URL é [/tasks/without-prg]. Se você clicar em [F5], o navegador pergunta se você deseja reenviar o formulário; se concordar, a tarefa é adicionada uma segunda vez.

Image

Um princípio do protocolo HTTP: uma requisição GET não altera nada. Navegadores, mecanismos de busca e ferramentas que pré-carregam páginas seguem links livremente, sem pedir permissão ao usuário. Um link de “exclusão” ([<a href="/contacts/2/delete">]) seria, portanto, perigoso: um bot que percorresse o site apagaria tudo. Em uma aplicação web:

  • a consulta é feita por meio de um link ([<a href>]), que envia uma requisição GET;
  • a edição (salvar, duplicar, excluir) é feita por meio de um botão colocado em um formulário, protegido por um token anti-CSRF.

Este exemplo gerencia uma lista de contatos e exibe uma janela de confirmação antes de cada exclusão.

4.9.1. Configuração: config/packages/framework.yaml

# config/packages/framework.yaml: a configuração do FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # um formulário POST que contém um campo _method (DELETE, PUT...) é tratado
    # como uma requisição desse método
    http_method_override: true
    # a sessão (mensagens flash, tokens anti-CSRF), armazenada em var/sessions (veja o exemplo 20)
    session:
        handler_id: null
        save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
    csrf_protection: true
    lock: 'flock://%kernel.project_dir%/var/lock'
  • Linha 6: um formulário HTML só pode enviar requisições GET e POST. No entanto, o protocolo HTTP prevê outros métodos: DELETE para exclusão, e PUT e PATCH para modificação. O [Symfony] contorna essa limitação: com a opção [http_method_override], um formulário POST que contenha um campo oculto [_method] com o valor [DELETE] (ou [PUT], [PATCH]) é tratado como uma requisição desse método. Isso é o method spoofing;
  • as demais linhas são as dos exemplos 18 e 20: a sessão, a proteção CSRF e os locks.

4.9.2. O serviço: src/Service/ContactsService.php

<?php
// src/Service/ContactsService.php: os contatos, compartilhados por todos, armazenados no
// cache da aplicação (veja o exemplo 20)

namespace App\Service;

use App\Model\Contact;
use Psr\Cache\CacheItemPoolInterface;
use Symfony\Component\Lock\LockFactory;

class ContactsService
{
    private const KEY = 'contacts';

    public function __construct(
        private CacheItemPoolInterface $cache,
        private LockFactory $locks,
    ) {
    }

    /** @return array{contacts: list<Contact>, lastId: int} */
    private function data(): array
    {
        $item = $this->cache->getItem(self::KEY);
        return $item->isHit() ? $item->get() : [
            'contacts' => [
                new Contact(1, 'Marie Durand', '01 23 45 67 89'),
                new Contact(2, 'Paul Martin', '06 12 34 56 78'),
                new Contact(3, 'Philippe Jandot', '02 98 76 54 32'),
            ],
            'lastId' => 3,
        ];
    }

    // uma modificação dos dados, sob lock: a função recebe os dados,
    // os modifica (&) e retorna o resultado da operação
    private function editData(callable $operation): mixed
    {
        $lock = $this->locks->createLock('contacts');
        $lock->acquire(true);
        try {
            $data = $this->data();
            $result = $operation($data);
            $this->cache->save($this->cache->getItem(self::KEY)->set($data));
            return $result;
        } finally {
            $lock->release();
        }
    }

    /** @return list<Contact> */
    public function list(): array
    {
        return $this->data()['contacts'];
    }

    // o contato, ou null se ele não existir
    public function read(int $id): ?Contact
    {
        return array_find($this->list(), fn (Contact $c) => $c->id === $id);
    }

    public function edit(int $id, string $name, string $phone): ?Contact
    {
        return $this->editData(function (array &$data) use ($id, $name, $phone) {
            foreach ($data['contacts'] as $i => $contact) {
                if ($contact->id === $id) {
                    // um contato é imutável (readonly): construímos um novo,
                    // que substitui o antigo no array
                    return $data['contacts'][$i] = new Contact($id, $name, $phone);
                }
            }
            return null;
        });
    }

    public function add(string $name, string $phone): Contact
    {
        return $this->editData(function (array &$data) use ($name, $phone) {
            $contact = new Contact(++$data['lastId'], $name, $phone);
            $data['contacts'][] = $contact;
            return $contact;
        });
    }

    public function delete(int $id): ?Contact
    {
        return $this->editData(function (array &$data) use ($id) {
            foreach ($data['contacts'] as $i => $contact) {
                if ($contact->id === $id) {
                    // array_splice remove o item i do array e renumera os seguintes
                    array_splice($data['contacts'], $i, 1);
                    return $contact;
                }
            }
            return null;
        });
    }
}

Os contatos são armazenados no cache, assim como as tarefas no Exemplo 20. Cada contato é um objeto imutável [Contact] (um ID, um nome, um telefone), armazenado em um array, junto com o último ID atribuído. Alguns pontos sobre o [PHP]:

  • linhas 37–49: todas as modificações seguem o mesmo padrão: adquirir o lock, ler os dados, modificá-los, gravá-los de volta e liberar o lock. Este método grava no array uma única vez; cada modificação lhe passa uma função (do tipo [callable], “chamável”), que recebe os dados e os modifica. A função deve modificar o próprio array, e não uma cópia: seu parâmetro é declarado como [array &$data], onde [&] especifica uma passagem por referência (sem o [&], um array é copiado; veja o Exemplo 06). A palavra-chave [use] em uma função anônima dá a ela acesso às variáveis da função que a contém (linha 65: [$id], [$name], [$phone]);
  • linha 44: as chamadas se encadeiam: [getItem] devolve o item, [set] atribui um valor a ele e devolve o próprio item, [save] o armazena;
  • linhas 63–75: um contato é imutável: cria-se um novo, que substitui o antigo no array. Uma atribuição é uma expressão cujo valor é o valor atribuído: [return $data['contacts'][$i] = new Contact(...)] substitui o contato e o devolve;
  • linha 80: [++] colocado antes de uma variável a incrementa em 1 e devolve o novo valor;
  • linha 92: [array_splice] remove um elemento do array e renumera os elementos seguintes;
  • Os métodos devolvem [null] para um contato inexistente: cabe ao controller decidir a resposta.

4.9.3. O formulário da ficha: src/Form/ContactType.php

<?php
// src/Form/ContactType.php: o formulário dos dados de um contato, com DOIS botões de envio

namespace App\Form;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\SubmitType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Validator\Constraints\NotBlank;

class ContactType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('name', TextType::class, ['constraints' => [new NotBlank()]])
            ->add('phone', TextType::class, ['label' => 'Phone', 'constraints' => [new NotBlank()]])
            // dois botões de envio: o formulário saberá qual deles foi clicado
            ->add('save', SubmitType::class, ['attr' => ['class' => 'btn-primary']])
            ->add('duplicate', SubmitType::class, ['attr' => ['class' => 'btn-outline-primary']]);
    }
}
  • linhas 17–18: os dois campos são obrigatórios;
  • linhas 20–21: dois botões de envio ([SubmitType]) fazem parte do formulário. Quando o formulário é enviado, o navegador envia o nome do botão que foi clicado, e o formulário sabe qual é. A opção [attr] atribui a eles suas classes do [Bootstrap].

4.9.4. O controller: src/Controller/ContactsController.php

<?php
// src/Controller/ContactsController.php: links (GET) e botões (POST, DELETE)

namespace App\Controller;

use App\Form\ContactType;
use App\Model\Contact;
use App\Service\ContactsService;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\SubmitButton;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/contacts', name: 'contacts')]
class ContactsController extends AbstractController
{
    public function __construct(private ContactsService $contacts)
    {
    }

    // o contato, ou uma resposta 404 se ele não existir
    private function contactOr404(?Contact $contact): Contact
    {
        return $contact ?? throw $this->createNotFoundException('unknown contact');
    }

    // um LINK (<a href>): uma requisição GET, que não modifica nada
    #[Route('', name: '', methods: ['GET'])]
    public function list(): Response
    {
        return $this->render('contacts/list.html.twig', ['contacts' => $this->contacts->list()]);
    }

    // GET /contacts/2: os detalhes; POST /contacts/2: um de seus dois botões
    #[Route('/{id<\d+>}', name: '_details', methods: ['GET', 'POST'])]
    public function details(Request $request, int $id): Response
    {
        $contact = $this->contactOr404($this->contacts->read($id));
        $form = $this->createForm(ContactType::class,
            ['name' => $contact->name, 'phone' => $contact->phone]);
        $form->handleRequest($request);
        if ($form->isSubmitted() && $form->isValid()) {
            ['name' => $name, 'phone' => $phone] = $form->getData();
            $duplicate = $form->get('duplicate');
            // isClicked: o botão que enviou o formulário
            if ($duplicate instanceof SubmitButton && $duplicate->isClicked()) {
                $copy = $this->contacts->add("$name (copy)", $phone);
                $this->addFlash('success', "The contact [$copy->name] has been created.");
            } else {
                $this->contacts->edit($id, $name, $phone);
                $this->addFlash('success', "The contact [$name] has been edited.");
            }
            return $this->redirectToRoute('contacts');
        }
        return $this->render('contacts/details.html.twig', ['contact' => $contact, 'form' => $form]);
    }

    // uma requisição DELETE, simulada por um formulário POST (campo oculto _method)
    #[Route('/{id<\d+>}', name: '_delete', methods: ['DELETE'])]
    public function delete(Request $request, int $id): Response
    {
        // o token anti-CSRF do formulário, específico deste contato
        if (! $this->isCsrfTokenValid("delete-contact-$id", $request->request->getString('_token'))) {
            throw new AccessDeniedHttpException('invalid anti-CSRF token');
        }
        $contact = $this->contactOr404($this->contacts->delete($id));
        $this->addFlash('success', "The contact [$contact->name] has been deleted.");
        return $this->redirectToRoute('contacts');
    }
}
  • linha 16: o prefixo de nome [contacts]: a rota da lista, cujo nome é vazio (linha 30), chama-se, portanto, [contacts], e a da ficha é [contacts_details]...;
  • linhas 24–27: uma função utilitária: um contato inexistente interrompe a ação com uma resposta 404;
  • linhas 30–34: a ação GET da lista, que não modifica nada;
  • linhas 37–58: a ficha de um contato. Em GET, ela exibe o formulário preenchido com as informações do contato; em POST, ela o processa. A mesma URL e o mesmo [/contacts/2] servem, portanto, tanto para consultar quanto para salvar;
  • linha 45: os dados do formulário, um array associativo não estruturado: [['name' => $name, 'phone' => $phone] = ...] armazena cada elemento em uma variável;
  • linhas 46–54: [get('duplicate')] devolve o botão [duplicate] do formulário; [isClicked()] determina se foi ele que enviou o formulário (o teste [instanceof SubmitButton] confirma o tipo do objeto para o editor). Dependendo do botão, a ação duplica ou salva o contato;
  • linha 55: em ambos os casos, o esquema PRG (exemplo 20), com uma mensagem flash;
  • linhas 61–71: a exclusão, tratada por uma requisição DELETE (a mesma URL, mas com um método diferente). O formulário de exclusão é escrito diretamente na view: a ação verifica seu próprio token anti-CSRF com o método [isCsrfTokenValid] de [AbstractController]. Um token está vinculado a um identificador (aqui, [delete-contact-2]): o token de um formulário só é válido para esse formulário. Um token ausente ou inválido interrompe a ação com um erro 403 (Forbidden). (O atributo [#[IsCsrfTokenValid('...')]], colocado na ação, faria a mesma validação.)

4.9.5. As views

{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">Contacts</h1>
  <table class="table align-middle">
    <tbody>
      {% for contact in contacts %}
        <tr>
          <td>{{ contact.name }}</td>
          <td>{{ contact.phone }}</td>
          <td class="text-end">
            {# view: um link simples; path() coloca o id no caminho: /contacts/2 #}
            <a class="btn btn-sm btn-outline-primary" href="{{ path('contacts_details', {id: contact.id}) }}">View</a>
            {# delete: um formulário, cujo envio será confirmado #}
            <form method="post" class="d-inline" action="{{ path('contacts_delete', {id: contact.id}) }}"
                  data-confirmation="Delete the contact {{ contact.name }}?">
              {# o método DELETE, que um formulário HTML não consegue enviar #}
              <input type="hidden" name="_method" value="DELETE">
              {# o token anti-CSRF, específico deste contato #}
              <input type="hidden" name="_token" value="{{ csrf_token('delete-contact-' ~ contact.id) }}">
              <button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
            </form>
          </td>
        </tr>
      {% endfor %}
    </tbody>
  </table>
{% endblock %}
  • Linha 13: um link, exibido como botão pelas classes do [Bootstrap] ([btn]...): a aparência nada tem a ver com o método HTTP. [path('contacts_details', {id: contact.id})] coloca o ID no caminho: [/contacts/2];
  • linhas 15–22: um formulário para cada botão “Excluir”, sem outros campos além do método e do token. A classe [d-inline] o exibe na mesma linha do link. O atributo [data-confirmation] contém a mensagem de confirmação: os atributos [data-...] não têm função própria, destinam-se ao [JavaScript] da página;
  • linha 18: o campo oculto [_method], que transforma este POST em uma requisição DELETE;
  • linha 20: o token anti-CSRF, gerado pela função [csrf_token] do [Twig], para o identificador [delete-contact-2] (o operador [~] concatena, exemplo 16).
{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">Contact no. {{ contact.id }}</h1>
  {{ form_start(form) }}
    {{ form_row(form.name) }}
    {{ form_row(form.phone) }}
    {# dois botões de envio para o mesmo formulário, lado a lado #}
    <div class="d-flex gap-2">
      {{ form_widget(form.save) }}
      {{ form_widget(form.duplicate) }}
      <a class="btn btn-link" href="{{ path('contacts') }}">Back to the list</a>
    </div>
  {{ form_end(form) }}
{% endblock %}
  • linhas 10–11: os dois botões do formulário, renderizados por [form_widget], lado a lado;
  • linha 12: o link de volta para a lista. [form_end] gerará o token anti-CSRF, que o componente Form validará por conta própria (exemplo 18).

4.9.6. A janela de confirmação

O navegador pode exibir uma caixa de diálogo de confirmação (funções [JavaScript] e [confirm]), mas ela é pouco atraente, e sua aparência depende do navegador. Aqui usamos uma janela modal do [Bootstrap], exibida com algumas linhas de [JavaScript]. A janela é um fragmento incluído no template e, portanto, está presente, embora oculta, em todas as páginas:

{# uma única janela para a página inteira, oculta (d-none) no início #}
<div id="confirmation-modal" class="d-none">
  <div class="modal-backdrop fade show"></div>
  <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true">
    <div class="modal-dialog modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-header">
          <h5 class="modal-title">Confirmation</h5>
        </div>
        <div class="modal-body">
          <p class="mb-0" id="confirmation-modal-message"></p>
        </div>
        <div class="modal-footer">
          <button type="button" class="btn btn-secondary" data-action="no">No, go back</button>
          <button type="button" class="btn btn-danger" data-action="yes">Yes, confirm</button>
        </div>
      </div>
    </div>
  </div>
</div>
  • linha 2: a classe [d-none] do [Bootstrap] oculta o elemento;
  • linhas 3–4: o fundo cinza, seguido da janela, são renderizados pelas classes do [Bootstrap];
  • linha 11: a posição da mensagem;
  • linhas 14–15: os dois botões, do tipo [button] (e não [submit]: eles não enviam nenhum formulário), distinguidos pelo atributo [data-action].
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Contacts</title>
  <link rel="stylesheet" href="{{ path('bootstrap', {file: 'css/bootstrap.min.css'}) }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3" style="max-width: 40rem">
    {% for message in app.flashes('success') %}
      <div class="alert alert-success" role="status">{{ message }}</div>
    {% endfor %}
    <main>
      {% block content %}{% endblock %}
    </main>
  </div>
  {# a janela de confirmação, presente em todas as páginas #}
  {% include 'fragments/confirmation.html.twig' %}
  {# o script, no final da página: os elementos que ele procura já existem #}
  <script src="{{ asset('js/app.js') }}"></script>
</body>
</html>
  • linha 19: a janela, incluída em todas as páginas;
  • linha 21: o script, colocado no final da página: quando ele é executado, os elementos que procura já existem. Ele fica armazenado na pasta [public/js].

O script [public/js/app.js]:

// confirmação dos formulários que possuem o atributo data-confirmation="..."
// Sem JavaScript, esses formulários são simplesmente enviados sem confirmação.
(() => {
  const modal = document.getElementById('confirmation-modal');
  const message = document.getElementById('confirmation-modal-message');
  let pending = null; // o formulário a enviar se o usuário confirmar

  // 1. interceptamos o envio dos formulários a confirmar
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault(); // o envio é suspenso
      pending = form;
      message.textContent = form.dataset.confirmation;
      modal.classList.remove('d-none'); // a janela aparece
    });
  });

  // 2. os dois botões da janela
  modal.addEventListener('click', (event) => {
    const action = event.target.dataset.action;
    if (action === 'yes') {
      pending.submit(); // envio, SEM disparar novamente o evento 'submit'
    } else if (action === 'no') {
      modal.classList.add('d-none');
      pending = null;
    }
  });
})();
  • linha 3: o código está envolvido em uma função anônima, executada imediatamente; suas variáveis não interferem nas dos demais scripts da página;
  • linhas 4–6: a janela, o local da mensagem e o formulário aguardando confirmação;
  • linhas 9–17: para cada formulário que tem um atributo [data-confirmation], o evento [submit], disparado quando o formulário é enviado, é interceptado. [preventDefault()] suspende o envio; o formulário é colocado em espera, e sua mensagem ([dataset.confirmation], o valor do atributo [data-confirmation]) é exibida na janela, que aparece;
  • linhas 20–28: um único handler para os cliques na janela: [event.target] é o elemento clicado; seu atributo [data-action] especifica de qual botão se trata. “Sim” envia o formulário pendente com o método [submit()], que, ao contrário de um clique em um botão, não dispara o evento [submit] (caso contrário, a janela reapareceria); “Não” oculta a janela.

Sem [JavaScript], o formulário é simplesmente enviado sem confirmação: a página continua utilizável. Isso é o aprimoramento progressivo: o [JavaScript] acrescenta conveniência, mas a aplicação não depende dele.

4.9.7. Execução

A lista de contatos:

Image

Clicar em “Excluir” exibe a janela de confirmação:

Image

Após a confirmação, a requisição DELETE (simulada), o redirecionamento e a mensagem pop-up:

Image

A ficha de um contato, com seus dois botões de envio:

Image

Uma requisição sem token anti-CSRF é rejeitada, e um contato inexistente devolve um erro 404:

curl -i -X POST -d "_method=DELETE" http://localhost:8000/contacts/3
curl -i http://localhost:8000/contacts/9
1
2
3
4
5
6
HTTP/1.1 403 Forbidden
X-Debug-Exception: invalid%20anti-CSRF%20token
...
HTTP/1.1 404 Not Found
X-Debug-Exception: unknown%20contact
...

As páginas de erro ainda são as detalhadas do modo de depuração do [Symfony]. O capítulo sobre o ciclo de vida da requisição mostrará como substituí-las por páginas personalizadas.