Skip to content

4. La vista y su modelo

Hasta ahora, las acciones generaban sus propias respuestas: texto, JSON y algunas etiquetas HTML escritas como cadena. En una aplicación MVC, este es el papel de una vista: un archivo que describe el HTML de la página, con marcadores de posición para los datos que la acción le transmite: el modelo de la vista.

[Symfony] utiliza el motor de vistas [Twig], creado por el mismo equipo. Una vista [Twig] es un archivo cuyo nombre termina en [.html.twig] (el formato de salida, seguido del motor), almacenado en la carpeta [templates] de la aplicación. Es un archivo de texto (en este caso, HTML) en el que se interpretan en el servidor tres tipos de etiquetas:

  • [{{ expression }}]: el valor de una expresión, insertado en la página;
  • [{% instruction %}]: una instrucción (tag); una condición ([{% if %}]); un bucle ([{% for %}]), la herencia de plantillas ([{% extends %}], [{% block %}]), la inclusión ([{% include %}])...;
  • [{# comment #}]: un comentario, que no aparece en la página generada.

Todo lo demás se copia tal cual. Las expresiones no se escriben en [PHP], sino en el lenguaje de [Twig], que es más simple y más seguro: [model.title] se refiere a la propiedad [title] del objeto [model] (o a su método [getTitle()], o a la clave [title] de un arreglo: [Twig] la busca por sí mismo); los filtros transforman un valor ([name|upper] pone un nombre en mayúsculas); las funciones realizan cálculos ([path('home')] genera una URL). [Twig] se parece así a [Jinja2] ([Flask]), en el que se inspiró, o al motor de [Django]; se diferencia de [Blade] ([Laravel]) y de [Razor] ([ASP.NET Core]), que combinan HTML con código del lenguaje anfitrión. Una vista [Twig] no puede ejecutar código [PHP] arbitrario: solo puede mostrar los datos que se le proporcionan. Esto es deliberado: la lógica de la aplicación permanece en las clases. Una vista no se interpreta en cada solicitud: la primera vez que se usa, [Twig] la compila en una clase [PHP], almacenada en la carpeta [var/cache/dev/twig], que luego reutiliza mientras la vista no cambie. Veremos cómo es este archivo.

4.1. Ejemplo 13: una primera vista

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. La configuración: config/bundles.php y config/packages/twig.yaml

[Twig] se integra en [Symfony] mediante un bundle, TwigBundle, que debe añadirse a la lista de bundles de la aplicación (ejemplo 01):

1
2
3
4
5
6
7
<?php
// config/bundles.php: los bundles de la aplicación; el TwigBundle integra el
// motor de vistas Twig
return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
];

y configurarse:

1
2
3
4
# config/packages/twig.yaml: la configuración del TwigBundle
twig:
    # la carpeta de las vistas
    default_path: '%kernel.project_dir%/templates'

La única clave especifica la carpeta de las vistas: [templates], ubicada en la carpeta del proyecto. Este también es el valor predeterminado. En un proyecto estándar, estos dos archivos los crea [Symfony Flex] al instalar [Twig] ([composer require twig], véase la introducción).

4.1.2. El modelo de la vista: src/Model/PageModel.php

<?php
// src/Model/PageModel.php: el modelo de la vista, los datos que la acción pasa a la vista

namespace App\Model;

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

El modelo de la vista es una clase inmutable simple (véase el ejemplo 03): las tres informaciones que mostrará la vista. No es obligatorio definir el modelo de una vista como una clase: se podrían pasar tres variables separadas a la vista. Sin embargo, una clase documenta lo que espera la vista y permite que el editor verifique el código de la acción. Este es el enfoque que seguirá el caso de estudio, donde cada vista importante tiene su propia clase de modelo.

4.1.3. El controlador: src/Controller/ViewsController.php

<?php
// src/Controller/ViewsController.php: acciones que devuelven una VISTA

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: el motor Twig construye la página a partir de la plantilla de vista
    // templates/views/index.html.twig y de las variables pasadas en el arreglo (aquí
    // una sola, [model]); la página producida es el cuerpo de la respuesta
    #[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]);
    }

    // la misma vista con otro modelo; u otra vista, con el código 404
    #[Route('/hello/{name}', name: 'hello')]
    public function hello(string $name): Response
    {
        if ($name === 'unknown') {
            // el tercer parámetro de render: la respuesta por completar, aquí con el 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]);
    }
}
  • Líneas 20–23: la acción construye el modelo de la vista. La función [date], heredada de [PHP], da formato a la hora actual: [H] da formato a las horas, [i] da formato a los minutos y [s] da formato a los segundos;
  • Línea 24: el método [render] de [AbstractController] ordena a [Twig] generar la página. El primer parámetro es el nombre de la vista: la ruta del archivo, relativa a la carpeta [templates]. El segundo parámetro es un arreglo asociativo, en el que cada clave se convierte en una variable de la vista; en este caso, una sola: [model]. [render] devuelve un objeto [Response], cuyo cuerpo es la página generada (de tipo [text/html]);
  • líneas 31–35: otra vista, con otra variable ([name]). El tercer parámetro de [render] es una respuesta que se debe completar: en este caso, una respuesta 404 para una página de error personalizada. [new Response(status: ...)] pasa el código mediante un parámetro con nombre, mientras que los demás parámetros conservan sus valores predeterminados;
  • Líneas 36–40: la misma vista que la de la acción [index], pero con un modelo diferente. Esta es la ventaja de separar las acciones de las vistas: una misma vista puede ser utilizada por varias acciones.

4.1.4. La vista: templates/views/index.html.twig

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  {# {{ ... }}: el valor de una expresión, insertado en la 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>
  • línea 5: un comentario [Twig];
  • línea 6: [{{ model.title }}] inserta el valor de la propiedad [title] de la variable [model]. El punto es el operador de acceso de [Twig], donde [PHP] escribe [$model->title].

Todo lo que inserta [{{ }}] se escapa: los caracteres [<], [>], [&], ["] y ['] se reemplazan por sus entidades HTML. Este es el papel que desempeñaba la función [htmlspecialchars] en el ejemplo 09, pero esta vez es automático: por lo tanto, una vista no puede insertar por descuido en la página el HTML proporcionado por un usuario.

4.1.5. La vista: 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>

Una vista no está obligada a recibir un objeto: la variable [name] es una cadena.

4.1.6. Ejecución

Image

Image

La hora mostrada corresponde a la zona horaria configurada en [PHP] (la directiva [date.timezone] del archivo [php.ini]), que en este caso es el Tiempo Universal Coordinado (UTC); el caso de estudio mostrará cómo definirla para la aplicación. La respuesta sin procesar muestra el trabajo realizado por [Twig]: las etiquetas [{{ }}] se han reemplazado por sus valores y el comentario se ha eliminado.

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>

La página de error «home», seguida de un nombre que contiene HTML ([<b>martin], codificado en la 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>
...

La etiqueta [<b>] fue escapada, aunque ni la acción ni la vista tuvieron nada que ver (el apóstrofo también fue escapado: [&#039;]). Aquí está, por fin, la vista compilada por [Twig], tal como se encuentra en la carpeta [var/cache/dev/twig] (con un nombre generado, como [f1/f1e0ff0a8a0dc68657a0b1aa94f3ef4b.php]), reducida a lo esencial:

/* 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>
...

La vista se ha convertido en una clase llamada [PHP], cuyo método [doDisplay] genera la página pieza por pieza ([yield]). Cada [{{ model.title }}] se ha convertido en una llamada a [CoreExtension::getAttribute] (que busca la propiedad, el método o la clave [title]), pasada al método [escape] (el escape). Una vista [Twig] es, por lo tanto, simplemente una forma más segura y legible de escribir un archivo [PHP] que genera HTML.

4.2. Ejemplo 14: el lenguaje Twig

Este ejemplo combina las principales construcciones de [Twig] en una sola vista.

4.2.1. El modelo y la acción

El modelo de la vista está definido por tres clases inmutables, cada una en su propio archivo ([PHP] no exige una clase por archivo, pero el cargador de clases de [Composer] busca la clase [App\Model\Product] en el archivo [src/Model/Product.php]):

<?php
// src/Model/Product.php: un producto

namespace App\Model;

readonly class Product
{
    public function __construct(
        public string $name,
        public float $price,
        public bool $inStock,
    ) {
    }
}
<?php
// src/Model/Address.php: una dirección

namespace App\Model;

readonly class Address
{
    public function __construct(
        public string $street,
        public string $city,
    ) {
    }
}
<?php
// src/Model/BasicsModel.php: el modelo de la vista del ejemplo 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,
    ) {
    }
}

El modelo contiene valores de diversos tipos: cadenas, [null], booleanos, arreglos de objetos, arreglos vacíos y objetos que contienen otros objetos. Aquí los precios son de tipo [float], para simplificar los cálculos en la vista (el ejemplo 06 mostró por qué preferimos los centavos enteros).

<?php
// src/Controller/BasicsController.php: una vista que usa las principales construcciones de 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]);
    }
}

La acción construye el modelo mediante parámetros con nombre (véase el ejemplo 02): cada valor va precedido del nombre del parámetro al que está destinado, lo que hace legible la llamada a pesar de la cantidad de parámetros.

4.2.2. La vista: templates/basics/index.html.twig

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>{{ model.title }}</title>
</head>
<body>
  {# set: una variable de la vista; el filtro reduce suma los precios, el filtro length cuenta los productos #}
  {% set total = model.products|reduce((sum, p) => sum + p.price, 0) %}
  {% set count = model.products|length %}
  <h1>{{ model.title }}</h1>
  {# 1. mostrar un valor del modelo; null se muestra como una cadena vacía;
     el filtro default reemplaza un valor vacío. Este comentario de Twig no aparece
     en la página producida #}
  <p>1. Name: {{ model.name }} - nickname: [{{ model.nickname }}] [{{ model.nickname|default('none') }}]</p>
  {# 2. {{ }} escapa el HTML; el filtro raw lo inserta tal cual #}
  <p>2a. {{ model.html }}</p>
  <p>2b. {{ model.html|raw }}</p>
  {# 3. una condición #}
  {% if model.loggedIn %}
    <p>3. You are logged in.</p>
  {% else %}
    <p>3. You are not logged in.</p>
  {% endif %}
  {# 4. un bucle: la variable loop describe el estado del bucle #}
  <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. la lista vacía: el bloque else de un bucle for #}
  <p>5. Your cart:
    {% for p in model.cart %}<span>{{ p.name }}</span>{% else %} it is empty.{% endfor %}
  </p>
  {# 6. expresiones calculadas, las variables definidas con set y el 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. un objeto dentro de un objeto, y un filtro que convierte a mayúsculas #}
  <p>7. Address: {{ model.address.street }}, {{ model.address.city|upper }}</p>
  {# 8. verbatim: un texto que Twig copia sin interpretarlo #}
  <p>8. Braces displayed as is: {% verbatim %}{{ model.name }}{% endverbatim %}</p>
</body>
</html>
  • Líneas 9–10: la instrucción [{% set %}] crea una variable en la vista. El precio total se calcula con el filtro [reduce], que reduce un arreglo a un único valor (como [array_reduce], ejemplo 06): su función recibe el valor acumulado y el elemento actual; [(sum, p) => sum + p.price] es una función flecha de [Twig]. El filtro [length] devuelve el número de elementos de un arreglo (o de caracteres de una cadena). Estos cálculos deberían reservarse para fines de presentación: normalmente, el cálculo corresponde a la acción;
  • línea 15: un valor [null] se muestra como una cadena vacía. El filtro [default] reemplaza un valor vacío (o ausente) por un valor predeterminado;
  • líneas 17–18: [{{ }}] escapa el HTML (2a); en cambio, el filtro [raw], inserta el valor tal cual, sin escaparlo (2b). [raw] está reservado para el HTML generado por la propia aplicación, nunca para datos ingresados por el usuario;
  • Líneas 20–24: una condición: [{% if %}], [{% elseif %}], [{% else %}], [{% endif %}]. Cada bloque se cierra con una instrucción [{% end... %}];
  • Líneas 28–34: un bucle [{% for ... in ... %}] ... [{% endfor %}]. Dentro del bucle, la variable especial [loop] describe el estado del bucle: [loop.index0] (el número de iteración, a partir de 0), [loop.index] (a partir de 1), [loop.first], [loop.last] (verdadero en la primera y en la última iteración, respectivamente), [loop.length] (el número de elementos). Las variables externas al bucle ([model.name]) siguen siendo accesibles;
  • línea 30: el operador ternario [condition ? a : b] ([Twig] también acepta [condition ? a], que devuelve una cadena vacía si la condición es falsa);
  • línea 38: un bucle [for] puede tener un bloque [{% else %}], que se ejecuta si la lista está vacía. Esto es más simple que un [{% if %}] que verifique la longitud de la lista;
  • líneas 41–42: expresiones calculadas ([total / count]) y las variables de [set]. El filtro [number_format] da formato a un número: dos decimales, un punto como separador decimal y una coma como separador de miles. En el ejemplo 16 veremos una forma mucho mejor de dar formato a números e importes;
  • línea 44: el punto atraviesa objetos ([model.address.city]), y el filtro [upper] pone una cadena en mayúsculas (manejando correctamente los caracteres acentuados);
  • línea 46: la instrucción [{% verbatim %}] copia su contenido sin interpretarlo: es útil cuando una página contiene llaves destinadas a un framework de [JavaScript].

[Twig] tiene unos cincuenta filtros ([lower], [capitalize], [trim], [join], [split], [slice], [sort], [date], [json_encode], [escape]...), unas quince funciones ([range], [min], [max], [random]...) y pruebas ([is defined], [is empty], [is null], [is iterable], [is even]...); los bundles de [Symfony] añaden algunos ([path], [asset], [form_row], [is_granted]...), y la aplicación puede escribir los suyos (ejemplo 16).

4.2.3. Ejecución

Image

La página generada:

<!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>

Los comentarios y las instrucciones han desaparecido, pero dejan tras de sí sus espacios: [Twig] elimina el salto de línea que sigue a una etiqueta, pero no la sangría que la precede. Esto no tiene ningún efecto: el navegador ignora esos espacios. (Un guion dentro de una etiqueta, como [{%- ... -%}] o [{{- ... -}}], eliminaría los espacios en blanco que la rodean.) Un número [float] insertado en la página se escribe con punto decimal ([12.5]); [number_format] usa los separadores que se le pasan.

4.3. Ejemplo 15: plantillas, fragmentos y archivos estáticos

Las páginas de un sitio web suelen compartir la misma estructura: un encabezado, una barra de navegación, un pie de página y las mismas hojas de estilo. En lugar de repetir esta estructura en cada vista, se escribe una sola vez en una plantilla (layout), que las páginas extienden. Este ejemplo también usa [Bootstrap], el framework CSS más utilizado, para el diseño.

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. Archivos estáticos

Una página HTML hace referencia a otros archivos: hojas de estilo, scripts [JavaScript] e imágenes. Estos archivos, que el servidor envía tal cual, se denominan archivos estáticos. Con [Symfony], se almacenan en la carpeta [public], que el servidor web sirve tal cual (ejemplo 01): el archivo [public/css/styles.css] está disponible en la URL [/css/styles.css], sin que intervenga [Symfony] .

/* algunos ajustes adicionales a Bootstrap */
body {
  background-color: #f5f7fa;
}

/* el pie de página del layout */
.footer {
  margin-top: 2rem;
  font-size: 0.85rem;
  color: #6c757d;
}

/* los mensajes de error, al final de la página, sobre un fondo 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;
}

Algunas reglas CSS adicionales además de [Bootstrap]: un fondo gris claro, el estilo del pie de página y el estilo de un área de error que se usará en los ejemplos siguientes.

[Bootstrap] se usa en los ejemplos 15 a 28. En lugar de colocar una copia en la carpeta [public] de cada usuario, los ejemplos lo comparten: se encuentra en la carpeta [examples/common/bootstrap]. Esta carpeta no la sirve el servidor web: un controlador, compartido por todos estos ejemplos, sirve sus archivos. Este es el archivo [examples/common/BootstrapController.php]:

<?php
// common/BootstrapController.php: un controlador que sirve los archivos de Bootstrap,
// compartidos por los ejemplos 15 a 28 (la carpeta examples/common/bootstrap), bajo
// la URL /bootstrap/.... Cada uno de estos ejemplos lo declara en su
// archivo 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: la ruta absoluta del archivo solicitado, sin los . y los ..;
        // false si el archivo no existe
        $path = realpath($folder.'/'.$file);
        // un archivo que existe, y que está efectivamente DENTRO de la carpeta (sin ../ para salir de ella)
        if ($path === false || ! str_starts_with($path, $folder.DIRECTORY_SEPARATOR) || ! is_file($path)) {
            throw new NotFoundHttpException("unknown file: $file");
        }
        // una respuesta que envía el contenido de un archivo; su tipo, según su extensión
        $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;
    }
}
  • línea 7: la clase está en el espacio de nombres [Common], que el archivo [examples/composer.json] asocia con la carpeta [examples/common] (véase la introducción): el cargador de clases de [Composer] la encuentra, por lo tanto, sin importar el ejemplo;
  • Líneas 16–17: una ruta cuyo parámetro [{file}] acepta cualquier final de ruta, incluidas las barras (ejemplo 02): la URL [/bootstrap/css/bootstrap.min.css] se refiere al archivo [css/bootstrap.min.css] de la carpeta. La ruta se llama [bootstrap];
  • Líneas 20–27: servir archivos designados por una URL exige precaución: una URL como [/bootstrap/..%2F..%2F15-layout%2F.env] (donde [/] se codifica como [%2F]) no debe dar acceso a un archivo ubicado fuera de la carpeta. La función [realpath] de [PHP] calcula la ruta absoluta de un archivo, eliminando sus componentes [.] y [..], o devuelve [false] si el archivo no existe. Verificamos que la ruta resultante comience con la ruta de la carpeta ([str_starts_with]) y que designe un archivo ([is_file]); de lo contrario, se devuelve un error 404. [DIRECTORY_SEPARATOR] es el separador de rutas del sistema: [\] en [Windows], [/] en los demás sistemas;
  • líneas 29–32: un objeto [BinaryFileResponse] es una respuesta que envía el contenido de un archivo. El tipo de contenido se determina a partir de la extensión del archivo (proporcionada por [pathinfo]), de modo que una hoja de estilo se declara correctamente como [text/css]: un navegador rechazará una hoja de estilo declarada con otro tipo.

Cada ejemplo que usa [Bootstrap] declara este controlador como un servicio en su archivo [config/services.yaml]:

# config/services.yaml: los servicios de la aplicación (véase el ejemplo 06)
services:
    _defaults:
        autowire: true
        autoconfigure: true

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

    # el controlador que sirve Bootstrap, compartido por los ejemplos 15 a 28 (véase el ejemplo 15)
    Common\BootstrapController: ~
  • línea 11: el servicio [Common\BootstrapController], sin configuración específica ([~] es el valor de [null] en [YAML]): recibe la configuración de [_defaults], y [autoconfigure] lo convierte en un controlador, cuya ruta se une a las de la aplicación (ejemplo 02).

4.3.2. La plantilla: templates/layout.html.twig

<!doctype html>
{# el layout de las páginas: las páginas lo EXTIENDEN y llenan sus bloques #}
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {# block: una ranura que la página puede llenar; aquí con un contenido por defecto #}
  <title>{% block title %}Home{% endblock %} - {{ site_name }}</title>
  {# path(): la URL de la ruta llamada [bootstrap]; asset(): la URL de un archivo 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">
    {# inserción del archivo fragments/navbar.html.twig #}
    {% include 'fragments/navbar.html.twig' %}
    <main>
      {# aquí se inserta el contenido de la página solicitada por la acción #}
      {% block content %}{% endblock %}
    </main>
    {# app: la variable que Symfony entrega a todas las vistas (la solicitud actual...);
       site_name: una variable global (ver config/packages/twig.yaml) #}
    <footer class="footer">Page [{{ app.request.pathInfo }}] - © {{ 'now'|date('Y') }} {{ site_name }}</footer>
  </div>
</body>
</html>
  • línea 6: la etiqueta [viewport] indica a los navegadores móviles que muestren la página con el ancho de la pantalla, que es lo que espera [Bootstrap];
  • línea 8: la directiva [{% block %}] marca una ranura con nombre, que las páginas que extienden la plantilla pueden llenar definiendo un bloque con el mismo nombre. El contenido escrito entre [{% block title %}] y [{% endblock %}] es el contenido predeterminado del marcador de posición, usado por una página que no define este bloque. [site_name] es una variable global, presente en todas las vistas (véase [config/packages/twig.yaml], más abajo);
  • líneas 10–11: la función [path] genera la URL de una ruta con nombre (ejemplo 04), usando los valores de sus parámetros, que se proporcionan en un arreglo asociativo de [Twig] ([{file: '...'}], el equivalente de [['file' => '...']] en [PHP]). La función [asset] genera la URL a partir de un archivo de la carpeta [public]. Escribir manualmente las URL de los archivos ([/css/styles.css]) también funcionaría, pero [path] y [asset] seguirán funcionando si la aplicación se instala bajo un prefijo de URL;
  • línea 16: [{% include %}] inserta el contenido de otra vista, en este caso la barra de navegación. La vista incluida tiene acceso a las variables de la vista que la incluye;
  • línea 19: el espacio que cada página llena con su propio contenido;
  • línea 23: la variable [app] está presente en todas las vistas: [Symfony] almacena en ella la solicitud actual ([app.request]), la sesión ([app.session]), el usuario autenticado ([app.user], véase la sección sobre seguridad), el nombre de la ruta ([app.current_route])... [app.request.pathInfo] es la ruta de la URL solicitada. El filtro [date] da formato a una fecha; la cadena ['now'] designa la hora actual.

La clase [container] de [Bootstrap] centra el contenido y limita su ancho; [py-3] agrega un margen interno vertical (padding): [Bootstrap] ofrece cientos de clases de este tipo, que se combinan en el atributo [class]. La variable global [site_name] se declara en la configuración de [Twig]:

1
2
3
4
5
6
# config/packages/twig.yaml: la configuración del TwigBundle
twig:
    default_path: '%kernel.project_dir%/templates'
    # variables GLOBALES, presentes en todas las vistas
    globals:
        site_name: 'My site'

Las variables bajo la clave [globals] se agregan a todas las vistas sin necesidad de que las acciones las proporcionen. Una variable global también puede ser un servicio (['@App\Service\...']), cuyos métodos serán llamados por las vistas.

4.3.3. La barra de navegación: templates/fragments/navbar.html.twig

{# un fragmento: un trozo de página, insertado con 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(): la URL de una ruta, designada por su nombre #}
    <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>

Un fragmento: una pieza de página que no tiene sentido por sí sola. Las clases [navbar], [navbar-brand] y [nav-link] son las de la barra de navegación de [Bootstrap]. Los enlaces los genera [path], a partir de los nombres de las rutas.

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

{# MACROS: trozos de página que tienen parámetros, como las funciones #}

{# una tarjeta (card) de Bootstrap, con un nombre y un rol #}
{% 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 %}
  • Línea 4: una macro es una sección de página que tiene parámetros; es la función de [Twig]. Se declara con [{% macro name(parameters) %}] ... [{% endmacro %}]; un parámetro puede tener un valor predeterminado ([role = '']). Un archivo puede contener varias macros. La tarjeta ([card]) es un componente de [Bootstrap].

Una macro solo puede acceder a sus propios parámetros (y a las variables globales); no puede acceder a las variables de la vista que la llama. Esto es lo que la hace reutilizable. (La biblioteca [Symfony UX Twig Component] ofrece componentes con más funciones —[PHP] clases asociadas a una vista— que se usan como etiquetas HTML: [<twig:Card name="..." />]; no los necesitaremos.)

4.3.5. Las páginas

{# esta página EXTIENDE el layout: solo proporciona el contenido de sus bloques #}
{% extends 'layout.html.twig' %}
{# las macros del archivo macros.html.twig, bajo el nombre 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>
  {# la macro [card], llamada con dos parámetros escritos en el momento #}
  {{ m.card('A macro', 'called with parameters written on the spot') }}
{% endblock %}
  • línea 2: la página extiende la plantilla: [Twig] genera la página de la plantilla, reemplazando sus bloques por los que define la página. En una vista que extiende una plantilla, todo el contenido debe estar dentro de bloques: el texto escrito fuera de ellos no aparece en la página generada;
  • línea 4: [{% import %}] importa macros de un archivo con el nombre que usted elija ([m]);
  • líneas 6–12: el bloque [content], que llena la ranura del mismo nombre. La página no define el bloque [title]: la ranura conserva su contenido predeterminado, «Home»;
  • línea 11: la llamada a la macro [card], como función: [m.card(...)], dentro de [{{ }}], ya que produce texto que debe insertarse. Su resultado no se escapa por segunda vez: [Twig] sabe que ya es seguro desde el punto de vista del HTML (sus parámetros, en cambio, se escaparon dentro de la 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">
        {# los parámetros de la macro son expresiones cualesquiera #}
        {{ m.card(member.name, member.role) }}
      </div>
    {% endfor %}
  </div>
{% endblock %}
  • línea 4: el bloque [title], en una sola línea;
  • líneas 8–15: una tarjeta por cada miembro del equipo, en una cuadrícula de [Bootstrap] ([row], [col-md-4]: tres columnas en una pantalla mediana o grande, una columna en una pantalla estrecha);
  • línea 12: los parámetros de la macro son expresiones arbitrarias.

El controlador no contiene ninguna novedad:

<?php
// src/Controller/PagesController.php: tres 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 último, la tercera página no usa la plantilla:

<!doctype html>
{# esta vista no usa el layout: es una 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. Ejecución

Image

Image

Image

La página del equipo, tal como la recibe el 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>

El navegador recibió una página completa: la plantilla, el fragmento, la página y las macros se ensamblaron en el servidor. Las URL de las hojas de estilo fueron generadas por [path] y [asset]: son URL relativas al sitio. Puede verificar que las hojas de estilo se sirven correctamente (la opción [-I] de [curl] muestra solo los encabezados de la respuesta):

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

El primer archivo fue enviado por nuestro controlador ([BinaryFileResponse] agrega la fecha de modificación del archivo y permite almacenarlo en caché: [Cache-Control: public]); el segundo fue enviado directamente por el servidor de desarrollo, sin pasar por [Symfony]. Por último, un intento de salir de la carpeta:

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

(Las opciones [-s -o /dev/null -w "%{http_code}\n"] muestran solo el código de la respuesta; en [Windows], escriba [-o NUL]).

4.4. Ejemplo 16: extensiones de Twig

Una vista suele necesitar dar formato a valores: un importe con su moneda, una fecha escrita completa o un texto en mayúsculas. Este código no pertenece a la acción (que no se ocupa de la presentación), y [Twig] no permite escribirlo en la vista (que no puede ejecutar [PHP]; véase la introducción de este capítulo). Se escribe en [PHP], en una extensión de [Twig]: una clase que agrega sus propios filtros, funciones o pruebas al lenguaje de las vistas. Las bibliotecas proporcionan extensiones ya hechas, como [twig/intl-extra], instalada con los ejemplos, que da formato a fechas e importes según el idioma. Por último, las macros crean fragmentos de HTML (ejemplo 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. La extensión: src/Twig/FormatsExtension.php

<?php
// src/Twig/FormatsExtension.php: una EXTENSIÓN de Twig, que agrega dos filtros
// al lenguaje de las vistas: money y 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
{
    // la pila de solicitudes, para conocer el idioma de la solicitud actual
    public function __construct(private RequestStack $requests)
    {
    }

    // los filtros de la extensión: su nombre en las vistas, y el método que los implementa
    public function getFilters(): array
    {
        return [
            new TwigFilter('money', $this->money(...)),
            new TwigFilter('long_date', $this->longDate(...)),
        ];
    }

    // un monto en centavos, en una moneda, en el formato del idioma de la
    // solicitud: 114990 -> "€1,149.90" en inglés, "1 149,90 €" en francés.
    // La extensión intl de PHP conoce las convenciones 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);
    }

    // una fecha en palabras completas, en el idioma de la solicitud: "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';
    }
}
  • Línea 14: una extensión de [Twig] hereda de la clase [AbstractExtension]. Es un servicio, como toda clase de la carpeta [src]; [Symfony] la reconoce como una extensión ([autoconfigure]) y se la pasa a [Twig];
  • Líneas 17–19: la extensión necesita el idioma de la solicitud actual. Recibe la pila de solicitudes ([RequestStack]), un servicio de [Symfony] que conoce la solicitud actual (hay una pila porque una solicitud puede desencadenar otra internamente);
  • líneas 22–28: el método [getFilters] devuelve los filtros de la extensión: para cada uno, su nombre en las vistas y la función que lo implementa. [$this->money(...)] (con los puntos suspensivos) no llama al método: lo convierte en un valor, una función que se puede llamar más tarde (un first-class callable). Una extensión también puede proporcionar funciones ([getFunctions]) y pruebas ([getTests]);
  • líneas 33–37: formato de un importe recibido en centavos (véase el ejemplo 06). Esto depende del idioma: en francés, [1 149,90 €] (espacio para separar los miles, coma decimal, símbolo después del importe); en inglés, [€1,149.90]. La clase [NumberFormatter], parte de la extensión [intl] de [PHP], admite las convenciones de todos los países (usa datos del proyecto Unicode CLDR): se crea para un idioma y un estilo (aquí, [CURRENCY], para importes), y [formatCurrency] da formato a un importe, con la moneda designada por su código internacional ([EUR], [USD]). El primer parámetro del filtro es el valor filtrado; los parámetros siguientes son sus propiedades en la vista ([priceCents|money('USD')]);
  • líneas 40–44: formato de una fecha mediante la clase [IntlDateFormatter] de la extensión [intl]: el estilo [FULL] escribe la fecha completa, incluido el día de la semana ([Sunday, September 27, 2026]); el estilo [NONE], para la hora, no la incluye. El tipo [DateTimeInterface] acepta todas las fechas de [PHP];
  • líneas 46–49: el idioma ([fr], [en]) de la solicitud actual, o inglés si no hay solicitud (en un comando de consola, por ejemplo). Veremos quién lo establece.

4.4.2. El idioma de cada solicitud: src/EventListener/SetLanguage.php

<?php
// src/EventListener/SetLanguage.php: el idioma de cada solicitud

namespace App\EventListener;

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

// priority: el orden de los listeners del mismo evento (el más alto primero);
// 20: después del enrutamiento (32), antes de los listeners de Symfony que usan el idioma (16, 15)
#[AsEventListener(event: KernelEvents::REQUEST, priority: 20)]
class SetLanguage
{
    // el parámetro ?lang=fr de la URL, inglés en caso contrario
    public function __invoke(RequestEvent $event): void
    {
        $request = $event->getRequest();
        $request->setLocale($request->query->get('lang') === 'fr' ? 'fr' : 'en');
    }
}

Cada solicitud tiene un idioma (locale), que por defecto es el idioma [default_locale] indicado en la configuración ([en] si no se ha configurado nada). Aquí, el parámetro [?lang=fr] de la URL selecciona el francés; el inglés es el idioma predeterminado. Un listener del evento [kernel.request] (ejemplo 12) lo establece antes de cada acción mediante el método [setLocale] de la solicitud. El parámetro [priority] del atributo fija el orden de los listeners de un mismo evento: los de mayor prioridad se procesan primero (el valor predeterminado es 0). [Symfony] tiene por sí mismo varios listeners de [kernel.request]: el enrutamiento (prioridad 32), seguido de los que preparan los servicios que dependen del idioma (16 y 15). El nuestro debe ejecutarse entre ambos: 20. El comando [php bin/console debug:event-dispatcher kernel.request] muestra todos los listeners del evento, en orden. El idioma establecido de este modo solo se aplica a la solicitud actual: la siguiente volverá al idioma predeterminado. El capítulo sobre internacionalización usará este mismo idioma para traducir los textos.

4.4.3. La configuración: config/services.yaml

# config/services.yaml: los servicios de la aplicación (véase el ejemplo 06)
services:
    _defaults:
        autowire: true
        autoconfigure: true

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

    # el controlador que sirve Bootstrap, compartido por los ejemplos 15 a 28 (véase el ejemplo 15)
    Common\BootstrapController: ~

    # extensión Intl de Twig (biblioteca twig/intl-extra): los filtros
    # format_currency, format_date, format_number...
    Twig\Extra\Intl\IntlExtension: ~
  • Línea 15: los filtros de la biblioteca [twig/intl-extra] los proporciona la extensión [IntlExtension]. Su clase no está en la carpeta [src]: se declara como un servicio, y [Symfony] la reconoce como una extensión de [Twig] ([autoconfigure]). (En un proyecto estándar, el paquete [twig/extra-bundle], instalado por [Symfony Flex], se encarga de esto por sí mismo.)

4.4.4. El controlador: src/Controller/PagesController.php

<?php
// src/Controller/PagesController.php: dos 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),
        ]]);
    }
}

Las acciones pasan valores sin procesar a las vistas: una fecha ([new DateTimeImmutable('today')], la fecha de hoy a medianoche) e importes en centavos. Las vistas se encargan del formato. La clase [Product] combina un nombre, un precio (en centavos; véase el ejemplo 06) y un nivel de existencias.

4.4.5. Las vistas

{# un enlace de la barra de navegación, que recibe la clase [active] si la
   página actual está bajo la ruta [path]. app.request.pathInfo: la ruta de la
   solicitud actual; starts with: una prueba de Twig #}
{% macro link(href, path, text) %}
  <a class="nav-link{{ app.request.pathInfo starts with path ? ' active' }}" href="{{ href }}">{{ text }}</a>
{% endmacro %}

{# una insignia (badge) de Bootstrap: verde si el producto está en existencia, roja en caso contrario #}
{% macro badge(stock) %}
  <span class="badge {{ stock > 0 ? 'text-bg-success' : 'text-bg-danger' }}">{{ stock > 0 ? stock ~ ' in stock' : 'sold out' }}</span>
{% endmacro %}
  • líneas 4–6: una macro que crea un enlace para la barra de navegación. Al enlace de la página actual se le asigna la clase [active] de [Bootstrap], que lo resalta. Una macro accede a la variable global [app] (ejemplo 15): [app.request.pathInfo] es la ruta de la solicitud actual; [starts with] es un operador de [Twig], que verifica el comienzo de una cadena. El operador ternario sin cláusula «else» ([condition ? ' active']) devuelve una cadena vacía si la condición es falsa (ejemplo 14);
  • Líneas 9–11: una insignia de [Bootstrap], verde ([text-bg-success]) o roja ([text-bg-danger]) según el inventario. El operador [~] de [Twig] concatena dos cadenas (el [.] de [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. una condición escrita en la vista; app.current_route: el nombre de la ruta actual #}
    <a class="nav-link{{ app.current_route == 'home' ? ' active' }}" href="{{ path('home') }}">Home</a>
    {# 2. la macro [link] #}
    {{ m.link(path('products'), '/products', 'Products') }}
    {# 3. path() construye la URL de una ruta con nombre; un parámetro que no es
         parámetro de la ruta se agrega al final de la URL: /products?lang=fr #}
    <a class="nav-link" href="{{ path('products', {lang: 'fr'}) }}">Produits (fr)</a>
  </div>
</nav>
  • línea 1: un fragmento incluido (ejemplo 15) no hereda las importaciones de la vista que lo incluye: importa por sí mismo las macros que necesita;
  • línea 6: lo mismo que con la macro, escrito directamente en la vista, mediante el operador ternario. [app.current_route] es el nombre de la ruta de la solicitud actual. La macro evita repetir la condición en cada enlace;
  • línea 8: la llamada a la macro;
  • línea 11: un parámetro de [path] que no es un parámetro de ruta se agrega a la URL como parámetro: [/products?lang=fr].
{% extends 'layout.html.twig' %}
{% block title %}Home{% endblock %}

{% block content %}
  <h1>Home</h1>
  {# nuestro filtro long_date #}
  <p>Today is {{ today|long_date }}.</p>
  {# app.request.locale: el idioma de la solicitud, definido por el 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 %}
  • línea 7: nuestro filtro [long_date];
  • línea 9: [app.request.locale], el idioma de la solicitud, establecido por el 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>
          {# un filtro de Twig (upper), luego nuestro filtro money, sin y luego con un parámetro #}
          <td>{{ product.name|upper }}</td>
          <td>{{ product.priceCents|money }}</td>
          <td>{{ product.priceCents|money('USD') }}</td>
          {# la macro [badge] construye el HTML de la insignia #}
          <td>{{ m.badge(product.stock) }}</td>
        </tr>
      {% endfor %}
    </tbody>
  </table>
  {# el filtro format_currency de la extensión Intl: un monto (aquí en unidades), una
     moneda y el idioma de la solicitud #}
  <p>Total stock value: {{ (products|reduce((s, p) => s + p.priceCents * p.stock, 0) / 100)|format_currency('EUR', locale: app.request.locale) }}</p>
{% endblock %}
  • línea 13: un filtro de [Twig];
  • Líneas 14–15: nuestro filtro [money], primero con su moneda predeterminada, luego con un parámetro;
  • línea 17: la llamada a la macro [badge];
  • línea 24: el filtro [format_currency] de la extensión Intl: un importe (aquí en euros: el inventario total, calculado por [reduce], dividido por 100), una moneda y el idioma de la solicitud, pasado mediante un parámetro con nombre de [Twig] ([locale: ...]). Esta extensión también proporciona [format_date], [format_datetime], [format_number], [country_name], [language_name]... Nuestro filtro [money] es, por lo tanto, redundante: lo escribimos para demostrar cómo se escribe una extensión.

La plantilla [layout.html.twig] es una versión simplificada de la del ejemplo 15; su atributo [lang] recibe el idioma de la solicitud ([<html lang="{{ app.request.locale }}">]).

4.4.6. Ejecución

Image

Image

La misma página, con el parámetro [?lang=fr]. Solo cambia el formato de los números: el texto en sí está escrito directamente en las vistas. El capítulo sobre internacionalización también traducirá el texto.

Image

Un extracto del HTML produce:

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. Ejemplo 17: un formulario GET

Un formulario HTML envía sus campos al servidor de una de dos maneras, según su atributo [method]:

  • [method="get"]: los campos se agregan a la URL como parámetros ([/search?keyword=le&genre=novel]). Este es el método que usa un formulario que realiza una consulta: una búsqueda o un filtro. La URL que contiene los resultados se puede guardar como marcador, compartir o recargar sin riesgo;
  • [method="post"]: los campos se incluyen en el cuerpo de la solicitud (véase el ejemplo 11). Este es el método que usa un formulario que modifica datos: un registro, una adición o una eliminación.

Este primer formulario es una búsqueda de libros. Está escrito a mano en HTML dentro de la vista; los ejemplos siguientes usarán el componente Form de [Symfony] para los formularios.

4.5.1. El modelo: src/Model/Book.php y SearchModel.php

<?php
// src/Model/Book.php: un libro

namespace App\Model;

readonly class Book
{
    public function __construct(
        public string $title,
        public string $author,
        public string $genre,
    ) {
    }
}
<?php
// src/Model/SearchModel.php: el modelo de la vista: la entrada (para mostrarla
// de nuevo), los géneros, los 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,
    ) {
    }
}
  • Líneas 14–19: el modelo de la vista contiene los datos ingresados por el usuario, que el formulario muestra, la lista de géneros sugeridos y los resultados.

4.5.2. El controlador: src/Controller/BooksController.php

<?php
// src/Controller/BooksController.php: un formulario de búsqueda, 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 clase: los datos, escritos en el código para el ejemplo
    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 / y GET /search?keyword=...&genre=...: el formulario Y sus resultados;
    // dos rutas para la misma acción: el atributo #[Route] puede repetirse
    #[Route('/', name: 'books_home', methods: ['GET'])]
    #[Route('/search', name: 'books_search', methods: ['GET'])]
    public function search(Request $request): Response
    {
        // getString: el parámetro, en forma de cadena ('' si falta)
        $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),
        ]);
    }
}
  • Línea 16: una constante de clase privada llamada [self::GENRES] ([self] se refiere a la clase actual). Una constante no puede contener objetos: por eso los libros los proporciona un método estático (líneas 19–28). En una aplicación real, provendrían de una base de datos;
  • líneas 32–33: dos rutas para la misma acción: el atributo [#[Route]] se puede repetir. En la primera visita ([/]), no hay parámetros y se muestran todos los libros;
  • líneas 37–38: los campos del formulario se leen como parámetros de la URL (ejemplo 07). El método [getString] devuelve el parámetro como cadena, vacía si está ausente;
  • líneas 40–43: filtrado. La función [array_filter] conserva los elementos de un arreglo para los cuales la función dada devuelve [true]: se selecciona un libro si la palabra clave está vacía o aparece en su título o autor (en minúsculas en ambos lados; [mb_strtolower] maneja correctamente los caracteres acentuados), y si el género está vacío o coincide con el género del libro. [array_filter] conserva las claves de los elementos seleccionados (0, 2...): [array_values] las renumera a partir de 0;
  • líneas 44–46: el modelo de la vista.

4.5.3. La vista: templates/books/search.html.twig

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

{% block content %}
  <h1 class="h3">Book search</h1>
  {# method="get": los campos se envían en la 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: el campo vuelve a mostrar lo que se escribió (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 %}
          {# el atributo booleano selected, escrito si la condición es verdadera, omitido en caso contrario #}
          <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 %}
  • Línea 6: la etiqueta [<form>]. El atributo [action] es la URL a la que se envía el formulario; [method="get"] coloca los campos en la URL. Las clases de [Bootstrap] disponen los campos en una sola línea;
  • Línea 8: una etiqueta de campo (label). Su atributo [for] especifica el identificador ([id]) del campo que describe: al hacer clic en la etiqueta, el cursor se coloca en el campo, y los lectores de pantalla leen la etiqueta junto con el campo;
  • línea 10: un campo de entrada. Su atributo [name] es el nombre del parámetro enviado al servidor: este es el vínculo entre el formulario y la acción ([$request->query->getString('keyword')]). El atributo [value] es el valor mostrado: la entrada anterior, vuelta a mostrar (y escapada por [{{ }}], lo cual es esencial en un atributo: una entrada que contenga comillas ["] cerraría el atributo de otro modo);
  • líneas 14–20: una lista desplegable. Cada [<option>] tiene un valor ([value]), que se envía al servidor, y un texto, que se muestra. La primera opción, con un valor vacío, significa «todos los géneros»;
  • línea 18: a la opción seleccionada en la solicitud anterior se le asigna el atributo [selected]. Es un atributo booleano: basta con su presencia; no tiene valor. El operador ternario sin la parte «else» lo escribe si la condición es verdadera y no escribe nada en caso contrario. [==] es la igualdad de [Twig];
  • línea 23: el botón de envío;
  • línea 26: el número de resultados.

4.5.4. Ejecución

Image

Ingresemos [le] y seleccionemos el tipo [novel]:

Image

La URL de la página de resultados contiene los campos del formulario: [/search?keyword=le&genre=novel]. La respuesta del formulario:

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» no está seleccionada: «le» no aparece ni en el título ni en el nombre del autor.

4.6. Ejemplo 18: campos de formulario

Este ejemplo presenta todos los tipos de campos de un formulario HTML, esta vez enviado mediante POST. Muestra cómo volver a mostrar cada tipo de campo con su valor actual, cómo envía el navegador los valores de cada uno y cómo verifica el servidor que un valor recibido es realmente una de las opciones disponibles. Escribir todo esto a mano, como en el ejemplo 17, sería laborioso y repetitivo. [Symfony] delega esta tarea en su componente Form: un formulario se describe mediante una clase, su tipo; [Symfony] genera el HTML, lee los campos enviados, los convierte, los valida y vuelve a mostrar el formulario con los datos ingresados por el usuario y los errores, si los hay. Es el equivalente de [WTForms] en [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. El servicio de listas: src/Service/ListsService.php

<?php
// src/Service/ListsService.php: las listas ofrecidas por el formulario. En una
// aplicación real, provendrían de una base de datos.

namespace App\Service;

class ListsService
{
    // cada lista: un arreglo asociativo texto mostrado => 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'];
    }
}

Las listas desplegables del formulario (títulos de cortesía, países, pasatiempos, idiomas) las proporciona un servicio, siguiendo el modelo del ejemplo 06: en una aplicación real, provendrían de una base de datos. Cada lista es un arreglo asociativo: la clave es el texto mostrado y el valor es lo que se envía al servidor (este es el orden que espera el componente Form).

4.6.2. La configuración

# config/packages/framework.yaml: la configuración del FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # los mensajes (errores de los formularios) en inglés (véase el ejemplo 09)
    default_locale: en
    translator:
        default_path: '%kernel.project_dir%/translations'
    # la SESIÓN: allí se guarda el token anti-CSRF de los formularios (véase el ejemplo 20)
    session: true
    # la protección anti-CSRF de los formularios (véase más adelante)
    csrf_protection: true
  • líneas 5–7: el idioma y el traductor (ejemplo 09): los mensajes de error del componente Form, al igual que los del validador, estarán en inglés;
  • línea 9: la sesión del usuario, de la que hablaremos más en el ejemplo 20: el componente Form almacena allí el token anti-CSRF (véase más adelante);
  • línea 11: la protección anti-CSRF de los formularios.
1
2
3
4
5
# config/packages/twig.yaml: la configuración del TwigBundle
twig:
    default_path: '%kernel.project_dir%/templates'
    # el TEMA de los formularios: los campos se dibujan con las clases de Bootstrap 5
    form_themes: ['bootstrap_5_layout.html.twig']
  • Línea 5: el tema de los formularios. [Symfony] muestra cada campo mediante bloques de [Twig]; un tema proporciona la versión adecuada para un framework CSS. El tema [bootstrap_5_layout.html.twig], incluido con [Symfony], usa las clases de [Bootstrap] 5 ([form-control], [form-label], [is-invalid]...). La aplicación puede escribir sus propios temas o sobrescribir ciertos bloques de un tema existente.

4.6.3. El tipo de formulario: src/Form/FieldsType.php

<?php
// src/Form/FieldsType.php: la DESCRIPCIÓN del formulario: sus campos, su tipo, sus opciones

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
{
    // un tipo de formulario es un servicio: recibe el servicio de listas
    public function __construct(private ListsService $lists)
    {
    }

    // los campos del formulario, en el orden en que se muestran
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            // botones de opción: una lista de opciones (ChoiceType), "expanded";
            // constraints: las restricciones de validación del campo (véase el ejemplo 08)
            ->add('title', ChoiceType::class, [
                'choices' => $this->lists->titles(),
                'expanded' => true,
                'label_attr' => ['class' => 'radio-inline'],
                'constraints' => [new NotBlank(message: 'The title is required.')],
            ])
            // un campo de entrada; required => false: el campo no es obligatorio
            ->add('name', TextType::class, ['required' => false])
            // una contraseña: nunca se vuelve a mostrar en la página
            ->add('password', PasswordType::class, ['label' => 'Password', 'required' => false])
            // una fecha: un campo <input type="date">; el valor es una cadena yyyy-mm-dd
            ->add('birth_date', DateType::class, [
                'label' => 'Date of birth',
                'widget' => 'single_text',
                'input' => 'string',
                'required' => false,
            ])
            // casillas de verificación: una lista expandida de opciones, con opciones MÚLTIPLES
            ->add('hobbies', ChoiceType::class, [
                'choices' => $this->lists->hobbies(),
                'expanded' => true,
                'multiple' => true,
                'label_attr' => ['class' => 'checkbox-inline'],
                'required' => false,
            ])
            // lista desplegable: una lista de opciones que no está expandida
            ->add('country', ChoiceType::class, ['choices' => $this->lists->countries()])
            // lista de selección múltiple, mostrada en cuatro filas
            ->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]])
            // un campo oculto
            ->add('token', HiddenType::class);
    }
}
  • línea 17: un tipo de formulario hereda de la clase [AbstractType]. Es un servicio (ubicado en la carpeta [src]): puede recibir otros servicios, en este caso el servicio de listas (línea 20);
  • línea 25: el método [buildForm] describe los campos agregándolos ([add]) a un constructor de formularios: para cada campo, su nombre, tipo y opciones. El nombre del campo es también el nombre del dato que muestra; su etiqueta, por defecto, es su nombre con formato de texto ([name] se convierte en «Name»);
  • Líneas 30–35: un campo [ChoiceType] es una lista desplegable, definida por la opción [choices]. Con la opción [expanded], se convierte en un grupo de botones de opción (un campo de selección única). La opción [label_attr] asigna una clase a la etiqueta del grupo: [radio-inline] especifica botones en línea en el tema. La opción [constraints] define las restricciones de validación del campo (ejemplo 08): el título de cortesía es obligatorio;
  • línea 37: un campo [TextType] es un campo de entrada. La opción [required] es [true] por defecto: [Symfony] establece entonces el atributo HTML [required], que el navegador verifica (ejemplo 19). No envía ninguna información al servidor: es una restricción ([NotBlank]) la que hace que un campo sea obligatorio para el servidor;
  • línea 39: una contraseña ([PasswordType]), que nunca se devuelve a la página: su campo siempre está vacío al mostrarse;
  • líneas 41–46: una fecha ([DateType]), mostrada mediante un único campo [<input type="date">] (opción [widget]). Un campo de este tipo intercambia su valor con el servidor en el formato [yyyy-mm-dd], sin importar el formato en que lo muestre el navegador; la opción [input] especifica que el dato es una cadena (en lugar de un objeto [DateTime], que es el valor predeterminado);
  • líneas 48–54: una lista con elecciones múltiples ([multiple]) expandida: casillas de verificación;
  • línea 56: una lista de elección simple no expandida: una lista desplegable;
  • líneas 58–64: una lista de elección múltiple no expandida: una lista de selección múltiple, mostrada en cuatro líneas (el atributo HTML [size], especificado mediante la opción [attr]);
  • línea 65: un cuadro de texto ([TextareaType]), de dos líneas;
  • línea 67: un campo oculto ([HiddenType]).

[Symfony] proporciona unos treinta tipos de campos: [EmailType], [IntegerType], [MoneyType], [UrlType], [CheckboxType], [FileType], [CountryType], [RepeatedType] (ejemplo 19), [CollectionType] (una lista de subformularios)...

4.6.4. El controlador: src/Controller/FormController.php

<?php
// src/Controller/FormController.php: un formulario que usa todos los 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: el formulario, con valores iniciales; POST: los campos enviados
    // se leen, se validan y luego se muestran de nuevo con el mismo formulario
    #[Route('/form', name: 'form', methods: ['GET', 'POST'])]
    public function form(Request $request): Response
    {
        // los valores iniciales (uno por campo, un arreglo para un campo múltiple)
        $initial = ['title' => 'Mme', 'country' => 'fr', 'languages' => ['French'], 'token' => 'A7X2'];
        // createForm: el formulario, construido a partir de su descripción
        $form = $this->createForm(FieldsType::class, $initial);
        // handleRequest: si la solicitud es un POST, los campos recibidos se copian
        // en el formulario y luego se validan
        $form->handleRequest($request);
        $model = ['form' => $form];
        if ($form->isSubmitted()) {
            // lo que el navegador realmente envió, campo por 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): los errores de todos los campos
                'errors' => $form->getErrors(true),
                // getData(): los valores del formulario, convertidos por cada campo
                'data' => $form->getData(),
            ];
        }
        return $this->render('form/form.html.twig', $model);
    }
}
  • línea 16: una única acción para ambos métodos: GET muestra el formulario y POST lo procesa. Esta es la forma estándar de escribir una acción de formulario con [Symfony];
  • línea 20: los valores iniciales del formulario: un arreglo asociativo, con un valor por campo (un arreglo para un campo de valores múltiples);
  • línea 22: [createForm] crea el formulario (un objeto [Form]) a partir de su tipo y de los datos iniciales;
  • línea 25: [handleRequest] examina la solicitud. Con un GET, no hace nada. Con un POST que contiene los campos del formulario, los copia en el formulario: cada campo convierte su valor (la fecha, las listas, etc.), verifica que la selección esté entre las que se ofrecieron y, a continuación, el formulario valida las restricciones y el token anti-CSRF;
  • línea 27: [isSubmitted]: ¿se envió el formulario?;
  • líneas 29–34: para este ejemplo, la lista de lo que el navegador envió realmente. Los campos de un formulario de [Symfony] se nombran a partir del formulario: [fields[name]], [fields[hobbies][]]. [PHP] los organiza, por lo tanto, en un arreglo llamado [fields] (ejemplo 10), que luego se recorre. [(array) $value] convierte un valor único en un arreglo de un elemento (un arreglo sigue siendo un arreglo); [implode] combina los elementos de un arreglo en una cadena, separados por el primer parámetro;
  • líneas 35–42: el modelo de la vista recibe lo que recibió el servidor: el resultado de la validación ([isValid]), los errores ([getErrors(true)]: los de todos los campos) y los datos del formulario ([getData]), convertidos por cada campo. El operador [+=] agrega estas claves al arreglo [$model];
  • línea 44: el formulario se pasa a la vista, que lo mostrará junto con los datos ingresados por el usuario y los errores, si los hay.

4.6.5. La vista: templates/form/form.html.twig

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

{% block content %}
  <h1 class="h3">A complete form</h1>
  {# form_start: la etiqueta <form>, aquí con el método POST y la URL de la página #}
  {{ form_start(form, {attr: {style: 'max-width: 40rem'}}) }}
    {# form_row: un campo completo (etiqueta, campo de entrada, errores) #}
    {{ 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: los campos restantes (el campo oculto, el token anti-CSRF), luego </form> #}
  {{ form_end(form) }}

  {# is defined: verdadero si la variable recibida se pasó a la vista (formulario 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: el campo con error; error.message: el mensaje #}
        <li>{{ error.origin.getName() }}: {{ error.message }}</li>
      {% endfor %}
    </ul>
    {% if valid %}
      <p>The data of the form:</p>
      <ul>
        {# un bucle sobre un arreglo asociativo: la clave y el valor #}
        {% for key, value in data %}
          <li>{{ key }}: {{ value is iterable ? value|join(', ') : value }}</li>
        {% endfor %}
      </ul>
    {% endif %}
  {% endif %}
{% endblock %}
  • línea 6: la función [form_start] escribe la etiqueta [<form>]: el método POST y la URL de la página actual, por defecto; el segundo parámetro agrega atributos HTML;
  • Línea 8: la función [form_row] escribe un campo completo: su etiqueta, su campo de entrada (con su valor actual) y sus errores, usando las clases del tema. [form.title] se refiere al campo [title] del formulario. También se pueden escribir las partes por separado: [form_label], [form_widget], [form_errors];
  • líneas 9–19: los demás campos, dispuestos mediante las clases de cuadrícula de [Bootstrap];
  • línea 22: [form_end] escribe los campos que aún no se han escrito (en este caso, el campo oculto [token] y el campo oculto [_token], el token anti-CSRF), y luego cierra la etiqueta [</form>];
  • línea 25: la comprobación [is defined]: la variable [received] solo existe después de un envío;
  • líneas 30–33: los errores. Cada uno es un objeto [FormError], donde [origin] es el campo que contiene el error;
  • Líneas 39–41: un bucle [for] sobre un arreglo asociativo, que recorre tanto las claves como los valores. La prueba [is iterable] distingue entre arreglos (agrupados por el filtro [join]) y valores únicos.

Todo el formulario se podría haber escrito en una sola línea: [{{ form(form) }}]. Las funciones [form_start], [form_row], y [form_end] permiten disponer los campos como se desee.

4.6.6. Ejecución

Image

Se ven los valores predeterminados: el botón de opción «Mme», el país «France» y el idioma «French». El HTML produce lo siguiente (extractos, mostrados en varias líneas):

<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>

[Symfony] ha escrito todo: los identificadores ([fields_title_1]), las etiquetas asociadas a sus campos, los nombres terminados en [[]] para los campos múltiples (ejemplo 10), los atributos [checked] y [selected] de los valores comunes y las clases de [Bootstrap]. El último campo oculto, [fields[_token]], contiene el token anti-CSRF. Un ataque CSRF (Cross-Site Request Forgery) consiste en que un sitio malicioso engañe al navegador de su víctima para que envíe un formulario a nuestra aplicación. El navegador incluye las cookies de nuestra aplicación en la solicitud, y por lo tanto la sesión del usuario autenticado, de modo que la solicitud parece legítima. La contramedida: cada formulario de nuestra aplicación contiene un token aleatorio vinculado a la sesión del usuario, que el sitio malicioso no puede conocer. El componente Form agrega este token a todos los formularios, y [handleRequest] rechaza cualquier formulario cuyo token falte o sea incorrecto: ningún formulario puede omitirlo. (El atributo [data-controller] lo usa un script opcional de [Symfony], que refuerza la protección; aquí no tiene ningún efecto.) Completemos el formulario y enviémoslo:

Image

La página muestra lo que recibió el servidor: un parámetro por campo, con varios valores para las casillas de verificación y la lista desplegable; la contraseña se envió, pero no se vuelve a mostrar en su campo. El campo oculto [token] se devolvió tal cual: esta es la forma de enviar de ida y vuelta información que el usuario no ve (el caso de estudio lo usa para el número de versión de un registro). Sin embargo, un campo oculto no es un campo protegido: el usuario puede modificarlo con las herramientas de desarrollo de su navegador, y el servidor debe validarlo como a cualquier otro campo. El token anti-CSRF también figura entre los campos recibidos; no forma parte de los datos del formulario.

Ahora enviemos un formulario sin token, con [curl], y con un país que no figuraba entre las opciones:

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>
...

El formulario es no válido por tres razones: falta el token anti-CSRF (el error está asociado al propio formulario), no se envió ningún título de cortesía y el país [xx] no figura entre las opciones disponibles. Esta última verificación la realiza el propio campo [ChoiceType], sin que la hayamos solicitado: un usuario malicioso podría enviar cualquier cosa, no solo lo que ofrecía la página. Los mensajes están en inglés: los del componente Form los traduce [Symfony], igual que los del validador (ejemplo 09). La respuesta tiene el código de estado 422 (Unprocessable Content): [render] lo selecciona automáticamente cuando recibe un formulario enviado y no válido. Observe la diferencia con otros frameworks: [Symfony] no rechaza la solicitud antes de la acción; es el formulario el que se declara no válido, y la acción la que decide cómo proceder.

Para que el token sea aceptado, [curl] debe comportarse como un navegador: primero solicitar el formulario, conservando la cookie de sesión (opción [-c], que guarda en un archivo las cookies recibidas), y luego reenviar la cookie (opción [-b]) y el token leído de la página. La opción [--data-urlencode] codifica el propio valor del 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>
...

(el token es el de la página recibida por el primer comando). Solo quedan los dos errores de entrada.

4.7. Ejemplo 19: validación de formularios

Un formulario de registro, en el que cada campo tiene sus propias reglas de validación. Si se produce un error, el formulario se vuelve a mostrar con los datos ingresados por el usuario y un mensaje debajo de cada campo que contiene un error. Este ejemplo usa el enfoque estándar de [Symfony]: los datos del formulario son un objeto, cuya clase contiene las restricciones (ejemplo 08); el formulario llena el objeto y luego lo 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
└── ...

Los archivos [config/packages/framework.yaml] y [config/packages/twig.yaml] son los del ejemplo 18.

4.7.1. Los datos y sus restricciones: src/Model/Registration.php

<?php
// src/Model/Registration.php: los datos del formulario de registro y sus restricciones

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: una dirección válida, con un nombre de dominio completo (example.com, y no 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;
}
  • Línea 8: una clase normal cuyas propiedades son públicas y modificables; el formulario las llenará una por una. Todas se inicializan en [null]; el objeto está vacío en la primera visualización;
  • líneas 10–12: el nombre es obligatorio y no debe exceder los 20 caracteres. A cada restricción se le asigna aquí su propio mensaje, en inglés (ejemplo 09): [message] para [NotBlank], [maxMessage] para el exceso de [Length];
  • líneas 15–17: la restricción [Email] verifica que una dirección sea válida y exige un nombre de dominio completo ([example.com], no [example]);
  • líneas 19–21: la edad es un entero entre 18 y 120 ([notInRangeMessage]: el mensaje de [Range] cuando hay un mínimo y un máximo). El formulario habrá convertido la entrada en un entero;
  • líneas 23–25: la contraseña debe tener al menos 6 caracteres.

4.7.2. El formulario: src/Form/RegistrationType.php

<?php
// src/Form/RegistrationType.php: los campos del formulario de registro

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 adicionales en el campo de entrada (para la
            // validación por parte del navegador, véase más adelante)
            ->add('name', TextType::class, ['attr' => ['maxlength' => 20]])
            ->add('email', EmailType::class, ['label' => 'Email address'])
            // IntegerType: un entero; una entrada que no lo es produce
            // el error invalid_message
            ->add('age', IntegerType::class, [
                'label' => 'Age',
                'attr' => ['min' => 18, 'max' => 120],
                'invalid_message' => 'An integer is expected.',
            ])
            // RepeatedType: DOS campos que deben recibir el mismo valor (la
            // contraseña y su confirmación); un solo valor en los datos
            ->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.',
            ]);
    }

    // las opciones del formulario: sus datos son un objeto Registration
    public function configureOptions(OptionsResolver $options): void
    {
        $options->setDefaults(['data_class' => Registration::class]);
    }
}
  • línea 23: la opción [attr] agrega atributos HTML al campo de entrada: [maxlength] limita la entrada en el navegador;
  • línea 24: un campo [EmailType] genera un [<input type="email">], que el navegador puede validar;
  • líneas 27–31: un campo [IntegerType] genera un [<input type="number">] y convierte la entrada en un entero. Una entrada que no sea un entero no se puede convertir: se trata de un error de conversión (no de un error de validación; véase el ejemplo 08), cuyo mensaje de error proporciona la opción [invalid_message];
  • Líneas 34–39: un campo [RepeatedType] está formado por dos campos (aquí, dos campos [PasswordType]), que deben contener el mismo valor: la contraseña y su confirmación. Cada uno tiene sus propias opciones ([first_options], [second_options]); si las dos entradas difieren, el error es [invalid_message]. Los datos tienen un solo valor: la contraseña;
  • líneas 43–46: el método [configureOptions] define las opciones del propio formulario: [data_class] indica que sus datos son un objeto [Registration]. Cada campo lee y escribe la propiedad del mismo nombre.

[Symfony] también puede inferir el tipo de un campo a partir de las restricciones y del tipo de la propiedad: [->add('age')], que no tiene tipo, produciría un [IntegerType], con los atributos [min] y [max] inferidos de [Range]. Aquí lo hemos escrito de forma explícita para mayor claridad.

4.7.3. El controlador: src/Controller/RegistrationController.php

<?php
// src/Controller/RegistrationController.php: un formulario validado por el 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: el formulario; ?html5=true: dejamos que el navegador
    // lo valide antes de enviarlo. POST /register: el formulario 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: los campos pudieron convertirse, y el objeto Registration
        // cumple sus restricciones
        if ($form->isSubmitted() && $form->isValid()) {
            return $this->render('registration/welcome.html.twig', ['registration' => $registration]);
        }
        // la primera visualización, o un formulario inválido, mostrado de nuevo con la entrada
        // y los errores (render lo devuelve entonces con el código 422)
        return $this->render('registration/registration.html.twig',
            ['form' => $form, 'html5' => $html5]);
    }
}
  • línea 19: el parámetro [?html5=true] activa la validación del navegador (véase más adelante). [#[MapQueryParameter]] lo convierte en booleano (ejemplo 07);
  • líneas 21–23: el objeto vacío [Registration] se pasa al formulario; [handleRequest] lo llenará con los campos enviados;
  • líneas 26–28: [isValid] es verdadero si todos los campos se pudieron convertir y si el objeto [Registration] cumple sus restricciones. La página de bienvenida recibe entonces el objeto completado (el ejemplo siguiente mostrará que es mejor redirigir después de un POST exitoso);
  • líneas 31–32: de lo contrario, se muestra el formulario: vacío en la primera visualización; después de un envío no válido, muestra los datos ingresados y los errores, junto con el código 422 (ejemplo 18).

Por lo tanto, el formulario no válido lo vuelve a mostrar la propia acción POST, que conserva los datos ingresados y los errores: este es el enfoque de [Symfony]. Otros frameworks, como [Laravel], responden en cambio con una redirección a la página del formulario, conservando los datos ingresados y los errores en la sesión para la siguiente solicitud.

4.7.4. Las vistas

{% 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: el navegador ignora los atributos required, min... y envía
     el formulario tal cual; solo el servidor valida #}
  {{ form_start(form, {attr: html5 ? {} : {novalidate: 'novalidate'}}) }}
    {# form_widget: todos los campos del formulario, cada uno con su etiqueta y sus errores #}
    {{ form_widget(form) }}
    <button class="btn btn-primary" type="submit">Register</button>
  {{ form_end(form) }}
{% endblock %}

{% block page_bottom %}
  {# el error global, al final de la página, sobre un fondo rosa claro. vars: la
     información del formulario (¿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 %}
  • Línea 12: el atributo [novalidate] desactiva la validación del navegador: el formulario se envía tal cual y solo el servidor lo valida. Esto es lo que queremos observar primero. El operador ternario elige entre dos arreglos de atributos;
  • línea 14: [form_widget(form)], aplicado al formulario completo, escribe todos sus campos, cada uno con su etiqueta, su entrada y sus mensajes de error: el tema [Bootstrap] resalta en rojo un campo no válido (clase [is-invalid]) y muestra su mensaje debajo (clase [invalid-feedback]). No tuvimos que escribir ningún componente para esto;
  • líneas 19–25: el bloque [page_bottom], definido por la plantilla (véase más adelante). [form.vars] contiene los datos del formulario, calculados para la vista: [submitted] (¿enviado?), [valid] (¿válido?), [value], [errors]... Si el formulario se ha enviado y no es válido, aparece un mensaje general en un área cuyo estilo está definido en [public/css/styles.css] (ejemplo 15). El atributo [role="alert"] lo señala a los lectores de pantalla.
<!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>
    {# un bloque que las páginas pueden llenar, al final de la página #}
    {% block page_bottom %}{% endblock %}
  </div>
</body>
</html>
  • Línea 15: un segundo bloque, [page_bottom], que está vacío por defecto: una plantilla puede tener tantos bloques como sea necesario.
1
2
3
4
5
6
7
8
{% extends 'layout.html.twig' %}

{% block content %}
  {# registration: el objeto Registration, llenado por el formulario #}
  <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] es el objeto [Registration], llenado y validado: al nombre se le han quitado los espacios (véase más adelante), y la edad es un entero.

4.7.5. Ejecución

Enviemos un formulario lleno de errores: un nombre formado por espacios, una dirección sin dominio completo, una edad de 12, una contraseña demasiado corta y una confirmación diferente:

Image

Los datos ingresados se han conservado (excepto las contraseñas), y cada error se señala debajo del campo correspondiente. El nombre formado por espacios se señala como ausente: el componente Form elimina los espacios que rodean cada entrada (opción de campo [trim], con valor true por defecto). La contraseña, en cambio, tiene un solo error, que está en la confirmación: cuando las dos entradas difieren, el campo [RepeatedType] no devuelve ningún valor y no se verifica la longitud. La URL es el identificador del formulario, y [/register] indica que la página fue mostrada por la acción en respuesta a un POST. Con [curl], proporcionando el token anti-CSRF como en el ejemplo 18, también se puede enviar algo que un navegador no enviaría: una edad no 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 los datos ingresados vueltos a mostrar, junto con los atributos HTML5 ([required], [min], [max]), la clase [is-invalid], el mensaje de conversión y los atributos [aria-...], que vinculan el campo con su mensaje para los lectores de pantalla.

4.7.6. Validación del navegador

Quitemos el atributo [novalidate] siguiendo el enlace «enable it» (parámetro [?html5=true]). El navegador verifica entonces los atributos [required], [type="email"], [min], [maxlength]... antes de enviar el formulario, y muestra sus propios mensajes en un globo de ayuda debajo del primer campo con un error («Please fill in this field», «The value must be greater than or equal to 18», etc.): el formulario no se envía mientras haya un error. [Symfony] genera estos atributos automáticamente: [required] para todo campo (opción [required], p. ej., 18), [type="email"] y [type="number"] según el tipo de campo; [maxlength], [min], [max] y [minlength] provienen de nuestras opciones [attr]. Deben mantenerse coherentes con las restricciones.

Esta validación es cómoda para el usuario: es inmediata, sin idas y vueltas con el servidor. Pero no sustituye la validación del lado del servidor: un usuario puede desactivarla, y un programa como [curl] la ignora por completo. La regla es absoluta: el servidor siempre valida; la validación del lado del navegador es solo una comodidad adicional.

Por fin, una entrada correcta. El nombre, ingresado con espacios a ambos lados, fue limpiado por el formulario:

Image

4.8. Ejemplo 20: el patrón Post/Redirect/Get

Cuando una acción POST responde con una página, esa página es el resultado de un POST. Si el usuario recarga la página (presiona [F5]), el navegador reenvía la solicitud POST, tras mostrar una advertencia que pocas personas leen: el comando se envía dos veces y el mensaje se publica dos veces. El patrón Post/Redirect/Get (PRG) evita este problema: una acción POST exitosa no devuelve una página; responde con una redirección (ejemplo 04) a una página GET, que el navegador solicita de inmediato. Recargar esta página simplemente vuelve a ejecutar la acción GET.

Queda un problema: la página GET querría mostrar un mensaje (“la tarea se ha agregado”), pero es la acción POST la que conoce este mensaje, y no puede pasar una variable a una solicitud que aún no ha ocurrido. La solución: el mensaje flash, colocado en la sesión por la acción POST, se conserva hasta que se lee, se muestra y luego se descarta.

4.8.1. Configuración: config/packages/framework.yaml

# config/packages/framework.yaml: la configuración del FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # la SESIÓN: sus datos se almacenan en el servidor, un archivo por sesión,
    # en la carpeta var/sessions/dev (handler_id: null: los archivos propios de PHP)
    session:
        handler_id: null
        save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
    # los BLOQUEOS (componente Lock): archivos bloqueados (flock) de la carpeta var/lock
    lock: 'flock://%kernel.project_dir%/var/lock'
  • Líneas 6–8: la sesión del usuario (capítulo sobre los ámbitos): datos específicos de cada navegador, conservados de una solicitud a la siguiente. Se almacena en el servidor; el navegador solo guarda un identificador de ella, en una cookie. [handler_id: null] delega la tarea de almacenar estos datos en [PHP] mismo, que almacena cada sesión en un archivo; [save_path] selecciona la carpeta ([var/sessions/dev]) para que podamos examinarlas. [%kernel.environment%] es el entorno ([dev]);
  • línea 10: los bloqueos (el componente Lock, que se describe más adelante), almacenados en la carpeta [var/lock].

4.8.2. El servicio: src/Service/TasksService.php

<?php
// src/Service/TasksService.php: la lista de tareas, compartida por todos los
// usuarios. En PHP, los objetos no sobreviven a la solicitud: la lista se
// almacena en el CACHÉ de la aplicación (aquí, un archivo de la carpeta var/cache/dev/pools)

namespace App\Service;

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

class TasksService
{
    private const KEY = 'tasks';

    // el caché de la aplicación (el servicio cache.app) y la fábrica de bloqueos
    public function __construct(
        private CacheItemPoolInterface $cache,
        private LockFactory $locks,
    ) {
    }

    /** @return list<string> */
    public function list(): array
    {
        // el elemento de caché almacenado bajo la clave [tasks]; isHit: existe
        $item = $this->cache->getItem(self::KEY);
        return $item->isHit() ? $item->get() : ['Read chapter 3'];
    }

    public function add(string $label): void
    {
        // varias solicitudes pueden ejecutarse AL MISMO TIEMPO (el servidor las maneja
        // en varios procesos): un bloqueo garantiza que solo una a la
        // vez lee, modifica y reescribe la lista
        $lock = $this->locks->createLock('tasks');
        // acquire(true): esperar hasta que el bloqueo esté libre y luego tomarlo
        $lock->acquire(true);
        try {
            $tasks = $this->list();
            $tasks[] = $label;
            // el elemento de caché recibe su nuevo valor, sin límite de tiempo
            $item = $this->cache->getItem(self::KEY);
            $this->cache->save($item->set($tasks));
        } finally {
            // finally: el bloqueo se libera en todos los casos, incluso después de una excepción
            $lock->release();
        }
    }
}

La lista de tareas es compartida por todos los usuarios y debe persistir de una solicitud a la siguiente. En [Java], [C#] o [Python], se mantendría en memoria dentro de un único servicio. En [PHP], esto es imposible: como vimos en los ejemplos 01 y 06, nada sobrevive a la solicitud. Por lo tanto, la lista debe almacenarse fuera de [PHP]: en una base de datos, en un archivo... o en el caché de la aplicación, que es lo que usamos aquí.

  • Líneas 16–20: el servicio recibe dos servicios de [Symfony]. El primero es el caché de la aplicación (el servicio [cache.app], del componente Cache), un almacén de pares clave-valor, representado por la interfaz estandarizada [CacheItemPoolInterface] (el estándar PSR-6). De forma predeterminada, almacena sus valores en archivos dentro de la carpeta [var/cache/dev/pools]; en producción se prefiere un servidor dedicado, como [Redis] (una línea de configuración). El segundo es la fábrica de bloqueos del componente Lock;
  • líneas 23–28: [getItem] recupera el elemento de caché almacenado bajo una clave; [isHit] verifica si existe y [get] devuelve su valor. Se puede almacenar cualquier valor (en este caso, un arreglo de cadenas): [Symfony] lo serializa, es decir, lo convierte en texto, mediante la función [serialize] de [PHP];
  • Líneas 35–47: el servidor de desarrollo, como un servidor de producción, puede procesar varias solicitudes al mismo tiempo, en varios procesos (la variable de entorno [PHP_CLI_SERVER_WORKERS] define el número de procesos de [php -S]). Dos adiciones simultáneas podrían leer la misma lista, agregar cada una su propia tarea y luego volver a escribirla: la segunda escritura sobrescribiría la primera tarea. Un bloqueo garantiza que solo una solicitud a la vez ejecute el código que protege: [createLock('tasks')] crea un bloqueo con nombre; [acquire(true)] espera a que esté disponible y luego lo adquiere; [release()] lo libera. Aquí, el bloqueo es un archivo en la carpeta [var/lock], bloqueado por el sistema operativo (la función [flock]); como alternativa, varios servidores compartirían un bloqueo almacenado en [Redis] o en una base de datos;
  • líneas 38–47: el bloque [try] … [finally] garantiza que el bloqueo se libere en todos los casos, incluso si una excepción interrumpe el código que protege;
  • líneas 42–43: el elemento de caché recibe su nuevo valor ([set]) y luego se guarda ([save]). Sin una duración especificada, se conserva indefinidamente ([expiresAfter(3600)] lo conservaría durante una hora).

4.8.3. El controlador: src/Controller/TasksController.php

<?php
// src/Controller/TasksController.php: el patrón 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: la lista y el formulario de adición
    #[Route('/tasks', name: 'tasks', methods: ['GET'])]
    public function display(): Response
    {
        return $this->render('tasks/tasks.html.twig', ['tasks' => $this->tasks->list()]);
    }

    // POST /tasks: el patrón 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: mostramos la página de nuevo, sin redirección
            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 deja un mensaje "flash" en la sesión: sobrevivirá a la
        // redirección, para la SIGUIENTE solicitud
        $this->addFlash('success', "The task [$label] has been added.");
        // sin página: una redirección a la página GET
        return $this->redirectToRoute('tasks');
    }

    // POST /tasks/without-prg: el contraejemplo (una página como respuesta al 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]);
    }
}
  • líneas 29–35: la entrada se valida manualmente para mantener el ejemplo conciso ([trim] elimina los espacios circundantes). Una entrada no válida se vuelve a mostrar sin redirección: no hay nada que proteger contra un envío duplicado, ya que no se ha modificado nada;
  • línea 39: el método [addFlash] de [AbstractController] coloca un mensaje flash de tipo [success] en la sesión (el tipo es arbitrario: permite distinguir entre mensajes de éxito y de error, etc.);
  • línea 41: la redirección a la página GET, llamada [tasks] (ejemplo 04);
  • líneas 45–50: el contraejemplo: una página como respuesta a POST. El operador [?:] devuelve su operando izquierdo si es “verdadero” (aquí, una cadena no vacía) y el operando derecho en caso contrario.

4.8.4. Las vistas

<!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">
    {# los mensajes flash [success], en la parte superior de la página: dejados ANTES de la redirección;
       app.flashes los ELIMINA de la sesión al leerlos #}
    {% 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>
  • Líneas 13–15: [app.flashes('success')] devuelve la lista de mensajes flash de tipo [success] y los elimina de la sesión: un mensaje flash se muestra una sola vez. La clase [alert alert-success] de [Bootstrap] muestra el mensaje en un recuadro verde;
  • líneas 19–21: el mensaje de error, al final de la página, cuando la acción ha generado uno.
{% 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ón envía el MISMO formulario a otra dirección #}
    <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 %}
  • línea 11: el operador [??] de [Twig] devuelve su operando derecho si el operando izquierdo no existe (o es igual a [null]): la variable [label] solo existe después de una entrada no válida;
  • Línea 14: el atributo [formaction] de un botón envía el formulario a una dirección distinta de la especificada por su atributo [action]: así, un solo formulario puede desencadenar dos acciones distintas.

Este formulario codificado a mano carece de un token anti-CSRF: para mantener el ejemplo simple, lo agregaremos en el siguiente ejemplo.

4.8.5. ¿Dónde se almacenan los mensajes flash?

Entre la solicitud POST y la solicitud GET posterior, el mensaje debe almacenarse en alguna parte: en la sesión del usuario o en el servidor. Lo examinaremos con [curl], almacenando las cookies en un archivo (opciones [-c] y [-b], Ejemplo 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
...

La respuesta a POST es una redirección (código de estado 302, encabezado [Location]), acompañada de la cookie de sesión, [PHPSESSID] (el nombre que [PHP] asigna a esta cookie), que contiene el ID de sesión: 32 caracteres aleatorios imposibles de adivinar. Esta cookie es [httponly] (el [JavaScript] de la página no puede leerla) y [samesite=lax] (el navegador no la envía con una solicitud POST originada en otro sitio). Los encabezados [Cache-Control] y [Expires] impiden el almacenamiento en caché de una respuesta que depende de una sesión. El identificador es también el nombre del archivo de sesión en el servidor: [var/sessions/dev/sess_1e1f574eccd93268b1eb829dd714a029]. Este es ese archivo, tras la solicitud 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 es el formato de serialización de las sesiones en [PHP]: cada dato de sesión se escribe con la forma [name|serialized value]. [a:1:{...}] declara un arreglo de 1 elemento, [s:7:"success"] una cadena de 7 bytes... Contiene los mensajes flash ([_symfony_flashes]), ordenados por tipo, y metadatos de [Symfony] ([_sf2_meta]: las fechas de creación y de último uso de la sesión). Sigamos la redirección devolviendo la 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>
...

El mensaje se muestra y [app.flashes] lo elimina de la sesión. La sesión, ahora vacía, incluso ha desaparecido: [Symfony] no almacena una sesión vacía y el archivo se ha eliminado. Una nueva solicitud GET ya no mostraría el mensaje. En cambio, la lista de tareas se almacena en un archivo de caché, cuyo nombre se calcula a partir de la clave ([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";}

La primera línea es la fecha de expiración del valor (0: nunca), la segunda es la clave y la tercera es la lista serializada. En cuanto al bloqueo, es un archivo vacío, [var/lock/sf.tasks.CFFUCEx.lock], que el sistema bloquea mientras dura una modificación.

4.8.6. Ejecución

Adición de una tarea: el navegador siguió la redirección; la URL es la de la página correspondiente a GET, que puede recargarse sin riesgo.

Image

Una entrada no válida, mostrada de nuevo con su mensaje de error:

Image

El contraejemplo: la página es la respuesta a POST y su URL es [/tasks/without-prg]. Si se hace clic en [F5], el navegador pregunta si se desea reenviar el formulario; si se acepta, la tarea se agrega por segunda vez.

Image

4.9. Ejemplo 21: enlaces, botones y confirmación

Un principio del protocolo HTTP: una solicitud GET no cambia nada. Los navegadores, los motores de búsqueda y las herramientas que precargan páginas siguen libremente los enlaces sin pedir permiso al usuario. Por lo tanto, un enlace “eliminar” ([<a href="/contacts/2/delete">]) sería peligroso: un bot que rastree el sitio eliminaría todo. En una aplicación web:

  • la consulta se realiza mediante un enlace ([<a href>]), que envía una solicitud GET;
  • la modificación (guardar, duplicar, eliminar) se realiza mediante un botón colocado en un formulario, protegido por un token anti-CSRF.

Este ejemplo administra una lista de contactos y muestra una ventana de confirmación antes de cada eliminación.

4.9.1. Configuración: config/packages/framework.yaml

# config/packages/framework.yaml: la configuración del FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # un formulario POST que contiene un campo _method (DELETE, PUT...) se maneja
    # como una solicitud de ese método
    http_method_override: true
    # la sesión (mensajes flash, tokens anti-CSRF), almacenada en var/sessions (véase el ejemplo 20)
    session:
        handler_id: null
        save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
    csrf_protection: true
    lock: 'flock://%kernel.project_dir%/var/lock'
  • Línea 6: un formulario HTML solo puede enviar solicitudes GET y POST. Sin embargo, el protocolo HTTP prevé otros métodos: DELETE para eliminar, y PUT y PATCH para modificar. [Symfony] sortea esta limitación: con la opción [http_method_override], un formulario POST que contiene un campo oculto [_method] con el valor [DELETE] (o [PUT], [PATCH]) se trata como una solicitud de ese método. Esto se denomina method spoofing;
  • las demás líneas son las de los ejemplos 18 y 20: la sesión, la protección CSRF y los bloqueos.

4.9.2. El servicio: src/Service/ContactsService.php

<?php
// src/Service/ContactsService.php: los contactos, compartidos por todos, almacenados en
// el caché de la aplicación (véase el ejemplo 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,
        ];
    }

    // una modificación de los datos, bajo bloqueo: la función recibe los datos,
    // los modifica (&) y devuelve el resultado de la operación
    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'];
    }

    // el contacto, o null si no existe
    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) {
                    // un contacto es inmutable (readonly): construimos uno nuevo,
                    // que reemplaza al anterior en el arreglo
                    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 elimina el elemento i del arreglo y renumera los siguientes
                    array_splice($data['contacts'], $i, 1);
                    return $contact;
                }
            }
            return null;
        });
    }
}

Los contactos se almacenan en el caché, igual que las tareas en el Ejemplo 20. Cada contacto es un objeto inmutable [Contact] (un ID, un nombre, un número de teléfono), almacenado en un arreglo, junto con el último ID asignado. Algunos puntos sobre [PHP]:

  • líneas 37–49: todas las modificaciones siguen el mismo patrón: adquirir el bloqueo, leer los datos, modificarlos, volver a escribirlos y liberar el bloqueo. Este método escribe en el arreglo una sola vez; cada modificación le pasa una función (de tipo [callable], “invocable”), que recibe los datos y los modifica. La función debe modificar el propio arreglo, no una copia: su parámetro se declara como [array &$data], donde [&] especifica un paso por referencia (sin [&], un arreglo se copia; véase el Ejemplo 06). La palabra clave [use] en una función anónima le da acceso a las variables de la función contenedora (línea 65: [$id], [$name], [$phone]);
  • línea 44: las llamadas se encadenan una tras otra: [getItem] devuelve el elemento, [set] le asigna un valor y devuelve el propio elemento, [save] lo almacena;
  • líneas 63–75: un contacto es inmutable: se crea uno nuevo, que reemplaza al anterior en el arreglo. Una asignación es una expresión cuyo valor es el valor asignado: [return $data['contacts'][$i] = new Contact(...)] reemplaza el contacto y lo devuelve;
  • línea 80: [++] colocado antes de una variable la incrementa en 1 y devuelve el nuevo valor;
  • línea 92: [array_splice] elimina un elemento del arreglo y vuelve a numerar los elementos siguientes;
  • Los métodos devuelven [null] para un contacto inexistente: corresponde al controlador decidir la respuesta.

4.9.3. El formulario de la ficha: src/Form/ContactType.php

<?php
// src/Form/ContactType.php: el formulario de los datos de un contacto, con DOS botones de envío

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()]])
            // dos botones de envío: el formulario sabrá cuál se presionó
            ->add('save', SubmitType::class, ['attr' => ['class' => 'btn-primary']])
            ->add('duplicate', SubmitType::class, ['attr' => ['class' => 'btn-outline-primary']]);
    }
}
  • líneas 17–18: los dos campos son obligatorios;
  • líneas 20–21: dos botones de envío ([SubmitType]) forman parte del formulario. Cuando se envía el formulario, el navegador envía el nombre del botón en el que se hizo clic, y el formulario sabe cuál es. La opción [attr] les asigna sus clases de [Bootstrap].

4.9.4. El controlador: src/Controller/ContactsController.php

<?php
// src/Controller/ContactsController.php: enlaces (GET) y botones (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)
    {
    }

    // el contacto, o una respuesta 404 si no existe
    private function contactOr404(?Contact $contact): Contact
    {
        return $contact ?? throw $this->createNotFoundException('unknown contact');
    }

    // un ENLACE (<a href>): una solicitud GET, que no modifica nada
    #[Route('', name: '', methods: ['GET'])]
    public function list(): Response
    {
        return $this->render('contacts/list.html.twig', ['contacts' => $this->contacts->list()]);
    }

    // GET /contacts/2: los detalles; POST /contacts/2: uno de sus dos botones
    #[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: el botón que envió el formulario
            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]);
    }

    // una solicitud DELETE, simulada por un formulario POST (campo oculto _method)
    #[Route('/{id<\d+>}', name: '_delete', methods: ['DELETE'])]
    public function delete(Request $request, int $id): Response
    {
        // el token anti-CSRF del formulario, específico de este contacto
        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');
    }
}
  • línea 16: el prefijo de nombre [contacts]: por lo tanto, la ruta de la lista, cuyo nombre está vacío (línea 30), se llama [contacts], y la de la ficha es [contacts_details]...;
  • líneas 24–27: una función utilitaria: un contacto inexistente detiene la acción con una respuesta 404;
  • líneas 30–34: la acción GET de la lista, que no modifica nada;
  • líneas 37–58: la ficha de un contacto. En GET, muestra el formulario, completado con la información del contacto; en POST, lo procesa. Por lo tanto, la misma URL y [/contacts/2] se usan tanto para consultar como para guardar;
  • línea 45: los datos del formulario, un arreglo asociativo sin estructura: [['name' => $name, 'phone' => $phone] = ...] almacena cada elemento en una variable;
  • líneas 46–54: [get('duplicate')] devuelve el botón [duplicate] del formulario; [isClicked()] determina si fue el que envió el formulario (la prueba [instanceof SubmitButton] confirma el tipo del objeto al editor). Según el botón, la acción duplica o guarda el contacto;
  • línea 55: en ambos casos, el esquema PRG (ejemplo 20), con un mensaje flash;
  • líneas 61–71: la eliminación, gestionada por una solicitud DELETE (la misma URL, pero con un método distinto). El formulario de eliminación está codificado en la vista: la acción verifica su propio token anti-CSRF mediante el método [isCsrfTokenValid] de [AbstractController]. Un token está vinculado a un identificador (aquí, [delete-contact-2]): el token de un formulario solo es válido para ese formulario. Un token ausente o no válido detiene la acción con un error 403 (Forbidden). (El atributo [#[IsCsrfTokenValid('...')]], colocado en la acción, realizaría la misma validación.)

4.9.5. Las vistas

{% 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: un enlace simple; path() coloca el id en la ruta: /contacts/2 #}
            <a class="btn btn-sm btn-outline-primary" href="{{ path('contacts_details', {id: contact.id}) }}">View</a>
            {# delete: un formulario, cuyo envío será confirmado #}
            <form method="post" class="d-inline" action="{{ path('contacts_delete', {id: contact.id}) }}"
                  data-confirmation="Delete the contact {{ contact.name }}?">
              {# el método DELETE, que un formulario HTML no puede enviar #}
              <input type="hidden" name="_method" value="DELETE">
              {# el token anti-CSRF, específico de este contacto #}
              <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 %}
  • Línea 13: un enlace, mostrado como un botón mediante las clases de [Bootstrap] ([btn]...): la apariencia no tiene nada que ver con el método HTTP. [path('contacts_details', {id: contact.id})] coloca el ID en la ruta: [/contacts/2];
  • líneas 15–22: un formulario por cada botón “Eliminar”, sin más campos que el método y el token. La clase [d-inline] lo muestra en la misma línea que el enlace. El atributo [data-confirmation] contiene el mensaje de confirmación: los atributos [data-...] no tienen asignación predefinida y están destinados al [JavaScript] de la página;
  • línea 18: el campo oculto [_method], que convierte este POST en una solicitud DELETE;
  • línea 20: el token anti-CSRF, generado por la función [csrf_token] de [Twig], para el identificador [delete-contact-2] (el operador [~] concatena, ejemplo 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) }}
    {# dos botones de envío para el mismo formulario, uno al lado del otro #}
    <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 %}
  • líneas 10–11: los dos botones del formulario, renderizados por [form_widget], uno al lado del otro;
  • línea 12: el enlace de regreso a la lista. [form_end] generará el token anti-CSRF, que el componente Form validará por sí mismo (ejemplo 18).

4.9.6. La ventana de confirmación

El navegador puede mostrar un cuadro de diálogo de confirmación (funciones [JavaScript] y [confirm]), pero no es muy atractivo y su apariencia depende del navegador. Aquí usamos una ventana modal de [Bootstrap], mostrada con unas pocas líneas de [JavaScript]. La ventana es un fragmento incluido en la plantilla y, por lo tanto, está presente (aunque oculta) en todas las páginas:

{# una sola ventana para toda la página, oculta (d-none) al inicio #}
<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>
  • línea 2: la clase [d-none] de [Bootstrap] oculta el elemento;
  • líneas 3–4: el fondo gris, seguido de la ventana, se renderizan mediante las clases de [Bootstrap];
  • línea 11: la ubicación del mensaje;
  • líneas 14–15: los dos botones, de tipo [button] (no [submit]: no envían ningún formulario), distinguidos por su 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>
  {# la ventana de confirmación, presente en todas las páginas #}
  {% include 'fragments/confirmation.html.twig' %}
  {# el script, al final de la página: los elementos que busca ya existen #}
  <script src="{{ asset('js/app.js') }}"></script>
</body>
</html>
  • línea 19: la ventana, incluida en todas las páginas;
  • línea 21: el script, colocado al final de la página: cuando se ejecuta, los elementos que busca ya existen. Se almacena en la carpeta [public/js].

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

// confirmación de los formularios que llevan el atributo data-confirmation="..."
// Sin JavaScript, estos formularios simplemente se envían sin confirmación.
(() => {
  const modal = document.getElementById('confirmation-modal');
  const message = document.getElementById('confirmation-modal-message');
  let pending = null; // el formulario por enviar si el usuario confirma

  // 1. interceptamos el envío de los formularios por confirmar
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault(); // el envío queda suspendido
      pending = form;
      message.textContent = form.dataset.confirmation;
      modal.classList.remove('d-none'); // aparece la ventana
    });
  });

  // 2. los dos botones de la ventana
  modal.addEventListener('click', (event) => {
    const action = event.target.dataset.action;
    if (action === 'yes') {
      pending.submit(); // envío, SIN lanzar de nuevo el evento 'submit'
    } else if (action === 'no') {
      modal.classList.add('d-none');
      pending = null;
    }
  });
})();
  • línea 3: el código está encerrado en una función anónima, que se ejecuta de inmediato; sus variables no interfieren con las de los demás scripts de la página;
  • líneas 4–6: la ventana, la ubicación del mensaje y el formulario en espera de confirmación;
  • líneas 9–17: para cada formulario que tiene un atributo [data-confirmation], se intercepta el evento [submit], que se desencadena cuando se envía el formulario. [preventDefault()] suspende el envío; el formulario se pone en espera y su mensaje ([dataset.confirmation], el valor del atributo [data-confirmation]) se muestra en la ventana, que aparece;
  • líneas 20–28: un único manejador para los clics en la ventana: [event.target] es el elemento en el que se hizo clic; su atributo [data-action] especifica de qué botón se trata. “Sí” envía el formulario pendiente mediante el método [submit()], que, a diferencia de hacer clic en un botón, no desencadena el evento [submit] (de lo contrario, la ventana reaparecería); “No” oculta la ventana.

Sin [JavaScript], el formulario simplemente se envía sin confirmación: la página sigue siendo utilizable. Esto es mejora incremental: [JavaScript] aporta comodidad, pero la aplicación no depende de él.

4.9.7. Ejecución

La lista de contactos:

Image

Al hacer clic en “Eliminar” se muestra la ventana de confirmación:

Image

Tras la confirmación, la solicitud DELETE (simulada), la redirección y el mensaje emergente:

Image

La ficha de un contacto, con sus dos botones de envío:

Image

Una solicitud sin token anti-CSRF es rechazada, y un contacto inexistente devuelve un error 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
...

Las páginas de error siguen siendo las detalladas del modo de depuración de [Symfony]. El capítulo sobre el ciclo de vida de la solicitud mostrará cómo reemplazarlas por páginas personalizadas.