Skip to content

3. El modelo de la acción

Una acción necesita información enviada por el navegador: los parámetros de la URL ([?name=martin&age=42]), los campos de un formulario, el cuerpo JSON de la solicitud y, a veces, un encabezado HTTP de la solicitud. El curso original denomina toda esta información el modelo de la acción. Este capítulo muestra cómo una acción de [Symfony] recupera esta información, la convierte al tipo correcto y la valida. Este proceso se denomina enlace de datos (data binding).

[Symfony] proporciona acceso a la información de la solicitud mediante el objeto [Request] (ejemplo 05), en forma de cadenas de caracteres, junto con algunos métodos de conversión. También puede enlazar esta información a los parámetros de una acción mediante atributos ([#[MapQueryParameter]], [#[MapQueryString]], [#[MapRequestPayload]]) y validarla con su componente Validator: describimos los datos esperados mediante restricciones (“obligatorio”, “un entero entre 0 y 150”, etc.), escritas como atributos como en [PHP], y el validador comprueba que los datos las cumplan. Primero leeremos los parámetros manualmente (ejemplo 07) y luego dejaremos que el framework se encargue de su conversión y validación (ejemplos 08 a 12). En el próximo capítulo, las mismas restricciones validarán los formularios HTML.

Observe la terminología: en el próximo capítulo, la palabra “modelo” se referirá principalmente a los datos que una acción pasa a su vista. El modelo de una acción, tal como se usa en este capítulo, es lo que ella recibe.

Los ejemplos 07 a 12 se ejecutan de la misma manera que los del capítulo anterior: un terminal abierto en la carpeta del ejemplo, [php -S localhost:8000 -t public]; [Ctrl-C] detiene el servidor. La mayoría usa el listener [ReadableJson] del ejemplo 03, lo que da como resultado un JSON legible. Solo comentaremos sus archivos de configuración cuando introduzcan algo nuevo.

3.1. Ejemplo 07: los parámetros de la URL

Los parámetros de la URL son la porción que sigue a [?]: [?name=martin&age=42]. Esta porción se denomina cadena de consulta (query string). Cada parámetro es un par [name=value]; los pares se separan con [&]. El controlador [ParametersController]:

<?php
// src/Controller/ParametersController.php: los parámetros de la URL (la "cadena de consulta")

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\MapQueryParameter;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/parameters', name: 'parameters_', methods: ['GET'])]
class ParametersController extends AbstractController
{
    // /parameters/action01?name=martin: $request->query contiene los parámetros de
    // la URL; get devuelve el valor de un parámetro, o null si falta
    #[Route('/action01', name: 'action01')]
    public function action01(Request $request): Response
    {
        $name = $request->query->get('name');
        return new Response("name = [$name], of type ".get_debug_type($name));
    }

    // /parameters/action02?age=42: getInt CONVIERTE el valor (una cadena) en un
    // entero; un parámetro ausente da 0, un valor que no es un entero,
    // un error 400
    #[Route('/action02', name: 'action02')]
    public function action02(Request $request): Response
    {
        $age = $request->query->getInt('age');
        return new Response("age = [$age], of type ".get_debug_type($age));
    }

    // /parameters/action03?age=42: un parámetro OBLIGATORIO, convertido manualmente;
    // su ausencia, o un valor que no es un entero, produce una respuesta 400
    #[Route('/action03', name: 'action03')]
    public function action03(Request $request): Response
    {
        $text = $request->query->get('age');
        if ($text === null) {
            // una excepción HTTP: Symfony la convierte en una respuesta 400 (Bad Request)
            throw new BadRequestHttpException('the [age] parameter is required');
        }
        // filter_var devuelve el entero contenido en la cadena, o false
        $age = filter_var($text, FILTER_VALIDATE_INT);
        if ($age === false) {
            throw new BadRequestHttpException("[$text] is not an integer");
        }
        return new Response("age = [$age], of type ".get_debug_type($age));
    }

    // /parameters/action04?page=2: un valor predeterminado si falta el parámetro
    #[Route('/action04', name: 'action04')]
    public function action04(Request $request): Response
    {
        $page = $request->query->getInt('page', 1);
        return new Response("page = [$page]");
    }

    // /parameters/action05?q=symfony: el nombre del parámetro de la URL no es necesariamente
    // el de la variable de PHP
    #[Route('/action05', name: 'action05')]
    public function action05(Request $request): Response
    {
        $search = $request->query->get('q');
        return new Response("search = [$search]");
    }

    // /parameters/action06?name=martin&age=42: todos los parámetros a la vez, como un arreglo
    #[Route('/action06', name: 'action06')]
    public function action06(Request $request): JsonResponse
    {
        return $this->json($request->query->all());
    }

    // /parameters/action07?age=42&page=2: el atributo #[MapQueryParameter] ENLAZA un
    // parámetro de la URL con el parámetro de la acción del mismo nombre, y lo convierte a
    // su tipo. Un parámetro sin valor predeterminado es obligatorio
    #[Route('/action07', name: 'action07')]
    public function action07(#[MapQueryParameter] int $age, #[MapQueryParameter] int $page = 1): Response
    {
        return new Response("age = [$age], page = [$page]");
    }
}
  • línea 22: la propiedad [query] de la solicitud contiene los parámetros de la URL, en una “bolsa” de parámetros (un objeto [InputBag]), cuyo método [get] devuelve el valor de un parámetro (ya decodificado) o [null] si está ausente;
  • línea 23: la acción muestra el valor y su tipo: la función [get_debug_type] devuelve el nombre del tipo de un valor. Un valor obtenido de la URL es siempre una cadena ([string]). El operador [.] concatena la cadena interpolada y el tipo;
  • Línea 32: El método [getInt] lee el parámetro y lo convierte a entero. Un parámetro ausente devuelve 0; un valor que no es un entero ([abc]) provoca un error 400 (Bad Request). De manera similar, existe [getBoolean] ([1], [true], [on] y [yes] son verdadero), [getString], [getAlpha] (solo letras), [getDigits] (solo números), [getEnum] (una lista);
  • líneas 41–51: un parámetro obligatorio y una conversión manual que distingue entre los dos errores posibles. [throw new BadRequestHttpException(message)] termina la operación con una respuesta 400, acompañada del mensaje (véase el ejemplo 03, que también lanzó una excepción 404). La función [filter_var] de [PHP], con el filtro [FILTER_VALIDATE_INT], devuelve el entero contenido en la cadena, o [false] si la cadena no es un entero;
  • línea 58: El segundo parámetro de [getInt] es un valor predeterminado, que se usa si el parámetro está ausente. Este suele ser el caso del número de página en una lista;
  • línea 67: no es obligatorio que la variable [PHP] tenga el mismo nombre que el parámetro de la URL. Los motores de búsqueda suelen usar un parámetro corto, [q] (query);
  • línea 75: [all()] devuelve todos los parámetros de la URL en un arreglo asociativo, que la acción convierte a JSON (véase el ejemplo 03);
  • líneas 81–85: el enfoque declarativo. El atributo [#[MapQueryParameter]], colocado antes de un parámetro de la acción, vincula ese parámetro con el parámetro del mismo nombre en la URL y lo convierte al tipo declarado ([int]). Un parámetro sin valor predeterminado es obligatorio: si falta o no se puede convertir, provoca un error 404 (la URL, tal como está escrita, no corresponde a ninguna página válida). Un valor predeterminado ([$page = 1]) lo vuelve opcional. Esto es lo que hacen las líneas 41–51, en una sola línea.

Probemos cada acción con [curl]. Primero con el parámetro presente y luego ausente:

curl -i "http://localhost:8000/parameters/action01?name=martin"
curl http://localhost:8000/parameters/action01
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8

name = [martin], of type string
name = [], of type null

Las comillas alrededor de la URL son necesarias en un terminal: sin ellas, el shell interpretaría [&] (que ejecuta un comando en segundo plano en [Linux]) y [?]. El valor [null], al insertarse en una cadena, se convierte en una cadena vacía. Un valor que contiene espacios o caracteres especiales debe codificarse en la URL: un espacio se convierte en [%20], y [&] se convierte en [%26] (de lo contrario, separaría dos parámetros). El navegador lo hace automáticamente; con [curl], hay que escribirlo explícitamente. [PHP] decodifica el valor antes de que la acción lo lea:

curl "http://localhost:8000/parameters/action01?name=jean%20dupont%20%26%20fils"
name = [jean dupont & fils], of type string

Conversión mediante [getInt]: exitosa, fallida y luego sin parámetros:

1
2
3
curl "http://localhost:8000/parameters/action02?age=42"
curl -i "http://localhost:8000/parameters/action02?age=abc"
curl http://localhost:8000/parameters/action02
1
2
3
4
5
6
age = [42], of type int
HTTP/1.1 400 Bad Request
Content-Type: text/html; charset=UTF-8
X-Debug-Exception: Input%20value%20%22age%22%20cannot%20be%20converted%20to%20%22int%22.
...
age = [0], of type int

[Symfony] se niega a convertir [abc] a entero: es un error del cliente, de ahí el código 400 (“Input value 'age' cannot be converted to 'int'”). En cambio, un parámetro ausente devuelve 0 silenciosamente: la acción no puede distinguir este caso de una edad de 0 realmente ingresada. El parámetro obligatorio de la acción 03 está ausente y, por lo tanto, no es válido. Solicitamos una respuesta JSON (encabezado [Accept], véase el ejemplo 03), que contiene el mensaje de la excepción:

curl -i -H "Accept: application/json" http://localhost:8000/parameters/action03
curl -H "Accept: application/json" "http://localhost:8000/parameters/action03?age=abc"
1
2
3
4
5
HTTP/1.1 400 Bad Request
Content-Type: application/json

{"type":"https:\/\/tools.ietf.org\/html\/rfc2616#section-10","title":"An error occurred","status":400,"detail":"the [age] parameter is required","class":"Symfony\\Component\\HttpKernel\\Exception\\BadRequestHttpException","trace":[...]}
{"type":"https:\/\/tools.ietf.org\/html\/rfc2616#section-10","title":"An error occurred","status":400,"detail":"[abc] is not an integer","class":"Symfony\\Component\\HttpKernel\\Exception\\BadRequestHttpException","trace":[...]}

(Este JSON compacto no es reformateado por nuestro listener, véase el ejemplo 03). En un navegador, en modo de depuración, una respuesta 400 muestra la página de error de [Symfony], con el mensaje:

Image

El valor predeterminado y el parámetro renombrado:

1
2
3
curl http://localhost:8000/parameters/action04
curl "http://localhost:8000/parameters/action04?page=3"
curl "http://localhost:8000/parameters/action05?q=symfony"
1
2
3
page = [1]
page = [3]
search = [symfony]

Todos los parámetros a la vez. El parámetro [name] aparece dos veces:

curl "http://localhost:8000/parameters/action06?name=martin&age=42&name=durand"
1
2
3
4
{
    "name": "durand",
    "age": "42"
}

El parámetro [name] conserva solo su último valor: es una regla de [PHP], que volveremos a ver en el ejemplo 10. La edad siguió siendo una cadena (["42"], entre comillas dentro del JSON): no se solicitó ninguna conversión. En un navegador (aquí, [Chromium]), el JSON se muestra exactamente como lo formateó el servidor; la casilla “Pretty-print” lo indentaría si no estuviera ya indentado. La barra de direcciones también muestra la codificación de los caracteres acentuados en la URL ([é] se convierte en [%C3%A9], con sus dos bytes en [UTF-8]):

Image

Por último, el enlace mediante [#[MapQueryParameter]], con y sin el parámetro opcional, y luego con una edad no válida:

1
2
3
curl "http://localhost:8000/parameters/action07?age=42"
curl "http://localhost:8000/parameters/action07?age=42&page=3"
curl -i "http://localhost:8000/parameters/action07?age=abc"
1
2
3
4
5
6
age = [42], page = [1]
age = [42], page = [3]
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=UTF-8
X-Debug-Exception: Invalid%20query%20parameter%20%22age%22.
...

Sin el parámetro [age], el mensaje sería “Missing query parameter 'age'”. El código 404 puede sorprender: el atributo acepta un parámetro [validationFailedStatusCode], que permite elegir otro ([#[MapQueryParameter(validationFailedStatusCode: 400)]]).

Este primer ejemplo ilustra las limitaciones del enfoque manual: para cada parámetro, hay que escribir la lectura, la conversión y el manejo de los valores ausentes y de los errores. Con diez parámetros, el código de la acción quedaría abrumado por estas comprobaciones. [#[MapQueryParameter]] simplifica la conversión, pero no dice nada sobre las reglas (“una cadena de 2 a 20 caracteres”). Es mejor describir lo que se espera y dejar que el framework lo verifique. Ese es el propósito del siguiente ejemplo.

3.2. Ejemplo 08: un modelo de acción descrito mediante una clase

El modelo de una acción puede describirse mediante una clase: una propiedad por cada parámetro esperado, junto con su tipo y, en forma de atributos, las restricciones que debe cumplir. [Symfony] crea entonces el objeto por sí mismo a partir de la solicitud, lo valida y lo pasa a la acción. Las restricciones son clases del componente Validator: [NotBlank] (obligatorio), [Length] (una longitud), [Range] (un intervalo), [Choice] (una lista de valores), [Email], [Regex]... [Symfony] proporciona más de setenta.

3.2.1. El modelo: src/Model/PersonModel.php

<?php
// src/Model/PersonModel.php: el modelo de la acción, una clase que describe los
// parámetros esperados y sus RESTRICCIONES

namespace App\Model;

use Symfony\Component\Validator\Constraints as Assert;

readonly class PersonModel
{
    public function __construct(
        // obligatorio, luego una cadena de 2 a 20 caracteres: verifica en secuencia
        // las restricciones en orden, y se detiene en la primera que falla
        #[Assert\Sequentially([
            new Assert\NotBlank(),
            new Assert\Length(min: 2, max: 20),
        ])]
        public ?string $name = null,
        // obligatorio, un entero entre 0 y 150
        #[Assert\NotNull]
        #[Assert\Range(min: 0, max: 150)]
        public ?int $age = null,
        // obligatorio, solo uno de estos tres valores
        #[Assert\NotBlank]
        #[Assert\Choice(choices: ['Mr', 'Mme', 'Melle'])]
        public ?string $title = null,
        // opcional; si está presente, una dirección de correo válida
        #[Assert\Email]
        public ?string $email = null,
    ) {
    }
}
  • Línea 7: Importación del espacio de nombres de las restricciones, con el nombre corto [Assert]: las restricciones se escribirán como [Assert\NotBlank], [Assert\Length]... Esta es una práctica estándar en todos los proyectos [Symfony];
  • líneas 9–31: una clase inmutable cuyas propiedades son inicializadas por el constructor (ejemplo 03). Cada propiedad tiene un valor predeterminado, [null], y un tipo anulable ([?string], [?int]: una cadena, o [null]): si falta un parámetro en la URL, la propiedad toma el valor predeterminado [null], y una restricción determina si era obligatoria. Esta es la forma estándar de escribir estas clases;
  • Líneas 14–18: El nombre es obligatorio ([NotBlank] rechaza [null] y una cadena vacía) y debe tener de 2 a 20 caracteres ([Length]). La restricción [Sequentially] comprueba en orden las restricciones que contiene y se detiene en la primera que falla: un nombre vacío produce un solo error, no dos. Los parámetros de las restricciones son con nombre ([min: 2]), un requisito desde [Symfony] 8;
  • líneas 20–22: la edad es obligatoria ([NotNull]) y debe estar entre 0 y 150 ([Range]). Su tipo es [?int]: [Symfony] convertirá la cadena de la URL a un entero;
  • líneas 24–26: el tratamiento es obligatorio y debe ser uno de los tres valores listados ([Choice]);
  • líneas 28–29: la dirección de correo electrónico es opcional (sin la restricción [NotBlank]); si se incluye, debe ser válida. Con la excepción de una restricción, [NotBlank], las demás aceptan [null]: solo verifican los valores presentes.

Este modelo describe los datos esperados; no contiene instrucciones de validación. Esto se conoce como estilo declarativo.

3.2.2. La acción: src/Controller/PersonsController.php

<?php
// src/Controller/PersonsController.php: una acción cuyo modelo es una clase

namespace App\Controller;

use App\Model\PersonModel;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\Attribute\MapQueryString;
use Symfony\Component\Routing\Attribute\Route;

class PersonsController extends AbstractController
{
    // /persons/action01?name=martin&age=42&title=Mr
    // #[MapQueryString]: Symfony construye un objeto PersonModel a partir de los
    // parámetros de la URL, y lo VALIDA ANTES de la llamada a la acción. Un
    // modelo inválido lanza una excepción (véase src/EventListener/ValidationErrors.php), y
    // la acción nunca se invoca
    #[Route('/persons/action01', name: 'persons_action01', methods: ['GET'])]
    public function action01(Request $request, #[MapQueryString] PersonModel $person): JsonResponse
    {
        return $this->json([
            'received' => $request->query->all(),
            'person' => $person,
            'ageType' => get_debug_type($person->age),
        ]);
    }
}
  • Línea 21: El atributo [#[MapQueryString]] indica a [Symfony] que construya el parámetro [$person] a partir de los parámetros de la URL. Un resolvedor de argumentos (ejemplo 05) realiza esta tarea en dos pasos. Primero, convierte: mediante el Serializer, crea un objeto [PersonModel], donde cada propiedad recibe el parámetro de la URL con el mismo nombre, convertido a su tipo correspondiente. Luego, valida el objeto: comprueba cada restricción de cada propiedad. Si todo es correcto, se llama a la acción. De lo contrario, lanza una excepción (una [HttpException] con código 404, que contiene una [ValidationFailedException], que a su vez contiene la lista de todos los errores, no solo el primero), y la acción nunca se llama: por lo tanto, no tiene que preocuparse por datos no válidos;
  • líneas 23–27: la acción devuelve los parámetros recibidos tal cual, seguidos del objeto [PersonModel] y del tipo de la edad, para ilustrar la diferencia.

¿Quién maneja la excepción? De forma predeterminada, [Symfony] mismo, mediante una respuesta de error 404 (o 422, para [#[MapRequestPayload]], ejemplo 11): su página de error o, para un cliente que solicita JSON, un documento que detalla los errores. Aquí queremos una respuesta de error en JSON, en todos los casos, con un código de estado 400 y en nuestro propio formato. Ese es el papel de un listener.

3.2.3. Manejo de errores: src/EventListener/ValidationErrors.php

<?php
// src/EventListener/ValidationErrors.php: un modelo inválido produce, para TODA la
// aplicación, una respuesta 400 que detalla los errores

namespace App\EventListener;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Validator\Exception\ValidationFailedException;

// un listener del evento [kernel.exception], lanzado cuando una excepción
// sale de la acción (o de la preparación de sus parámetros)
#[AsEventListener(event: KernelEvents::EXCEPTION)]
class ValidationErrors
{
    public function __invoke(ExceptionEvent $event): void
    {
        // la excepción HTTP lanzada por #[MapQueryString] contiene la excepción de la
        // validación, que contiene la lista de los errores (las "violaciones")
        $validation = $event->getThrowable()->getPrevious();
        if (! $validation instanceof ValidationFailedException) {
            return;    // otra excepción: Symfony la maneja como de costumbre
        }
        $errors = [];
        foreach ($validation->getViolations() as $violation) {
            $errors[] = ['field' => $violation->getPropertyPath(), 'message' => $violation->getMessage()];
        }
        // la respuesta del evento reemplaza la página de error de Symfony
        $event->setResponse(new JsonResponse(['status' => 400, 'errors' => $errors], 400));
    }
}
  • Línea 15: un listener del evento [kernel.exception] (la constante [KernelEvents::EXCEPTION]). [Symfony] desencadena este evento cuando ocurre una excepción durante la acción o mientras se preparan sus parámetros, antes de que la acción genere su propia respuesta de error. Declarado de esta manera, el listener se aplica a todas las acciones de la aplicación: toda acción que valide un modelo se beneficia de él, sin tener que escribir una sola línea de código de manejo de errores;
  • Línea 22: El evento, un objeto [ExceptionEvent], transporta la excepción ([getThrowable()]). La excepción lanzada por [#[MapQueryString]] es una excepción HTTP; [getPrevious()] devuelve la excepción que la causó: la excepción de validación;
  • líneas 23–25: si no es un error de validación, el listener no hace nada: [Symfony] manejará la excepción como de costumbre. El operador [!] (no) invierte la condición;
  • líneas 26–29: [getViolations()] devuelve la lista de errores, que se denominan (de restricción) violaciones. Cada violación tiene una ruta ([getPropertyPath()], el nombre de la propiedad con error) y un mensaje. [$errors[] = ...] agrega un elemento al final del arreglo [$errors];
  • Línea 31: [setResponse] devuelve una respuesta al evento: una respuesta JSON, con código de estado 400. [Symfony] la envía en lugar de su página de error (y, como cualquier respuesta, pasa por el listener [ReadableJson]).

3.2.4. Ejecución

Un modelo válido:

curl -i "http://localhost:8000/persons/action01?name=martin&age=42&title=Mr"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "received": {
        "name": "martin",
        "age": "42",
        "title": "Mr"
    },
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mr",
        "email": null
    },
    "ageType": "int"
}

Los parámetros recibidos son cadenas; el objeto [PersonModel] contiene la edad como entero (sin comillas en el JSON), y la dirección ausente es [null]. Un nombre rodeado de espacios ([%20]) y una dirección presente:

curl "http://localhost:8000/persons/action01?name=%20%20martin%20&age=42&title=Mme&email=martin@example.com"
{
    "received": {
        "name": "  martin ",
        "age": "42",
        "title": "Mme",
        "email": "martin@example.com"
    },
    "person": {
        "name": "  martin ",
        "age": 42,
        "title": "Mme",
        "email": "martin@example.com"
    },
    "ageType": "int"
}

Los espacios que rodean el nombre se han conservado: [Symfony] no transforma los datos recibidos. Una restricción puede ignorarlos durante la validación ([new Assert\Length(min: 2, normalizer: 'trim')]), pero el valor sigue siendo el que se envió. En el próximo capítulo, el componente Form eliminará estos espacios. Sin parámetros en este punto: faltan los tres campos obligatorios.

curl -i http://localhost:8000/persons/action01
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "This value should not be blank."
        },
        {
            "field": "age",
            "message": "This value should not be null."
        },
        {
            "field": "title",
            "message": "This value should not be blank."
        }
    ]
}

Cuatro campos no válidos a la vez:

curl "http://localhost:8000/persons/action01?name=m&age=200&title=Mlle&email=xx"
{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "This value is too short. It should have 2 characters or more."
        },
        {
            "field": "age",
            "message": "This value should be between 0 and 150."
        },
        {
            "field": "title",
            "message": "The value you selected is not a valid choice."
        },
        {
            "field": "email",
            "message": "This value is not a valid email address."
        }
    ]
}

Todos los errores se informan a la vez, lo que permite al usuario corregirlo todo de una sola vez. Por último, una edad que no es un número:

curl "http://localhost:8000/persons/action01?name=m&age=abc&title=Mlle&email=xx"
1
2
3
4
5
6
7
8
9
{
    "status": 400,
    "errors": [
        {
            "field": "age",
            "message": "This value should be of type int."
        }
    ]
}

Esta vez, solo se informa un error, aunque el nombre, el tratamiento y la dirección siguen siendo no válidos. Este es el resultado del proceso de dos pasos que realiza [#[MapQueryString]]: la conversión falló ([abc] no se puede convertir a entero), por lo que no se pudo construir el objeto, y la validación, que comprueba el objeto, no tuvo lugar. Los mensajes están en inglés, el idioma predeterminado de [Symfony]. El siguiente ejemplo personaliza algunos de ellos.

3.3. Ejemplo 09: validación realizada por la acción

En el ejemplo 08, un modelo no válido interrumpe la acción, y el listener de la aplicación responde. Esto es conveniente para una API, cuyos clientes son programas que esperan una respuesta de error estandarizada. Pero una página web suele preferir volver a mostrar el formulario con mensajes de error: en ese caso, la acción debe decidir qué hacer con un modelo no válido. Ella misma llama al validador.

09-action-validation/
├── config/
│   └── packages/
│       └── framework.yaml
├── src/
│   ├── Controller/
│   │   └── PersonsController.php
│   ├── Model/
│   │   └── PersonInput.php
│   └── Kernel.php
├── translations/
│   └── validators.en.yaml
└── ...

3.3.1. El modelo: src/Model/PersonInput.php

<?php
// src/Model/PersonInput.php: la ENTRADA de una persona, tal como llega
// (cadenas), y las restricciones que debe cumplir

namespace App\Model;

use Symfony\Component\Validator\Constraints as Assert;

class PersonInput
{
    #[Assert\Sequentially([
        new Assert\NotBlank(),
        new Assert\Length(min: 2, max: 20),
    ])]
    public ?string $name = null;

    // una cadena de dígitos (digit), cuyo valor está entre 0 y 150;
    // message: un mensaje específico de esta restricción
    #[Assert\Sequentially([
        new Assert\NotBlank(),
        new Assert\Type('digit', message: 'an integer is expected'),
        new Assert\Range(min: 0, max: 150),
    ])]
    public ?string $age = null;

    #[Assert\NotBlank]
    #[Assert\Choice(choices: ['Mr', 'Mme', 'Melle'])]
    public ?string $title = null;

    #[Assert\Email]
    public ?string $email = null;
}

Esta vez, el modelo describe la entrada exactamente como se recibe: cadenas, que la acción copiará en el propio objeto. Por lo tanto, sus propiedades son ordinarias (ni promovidas ni [readonly]), y todas de tipo [?string], incluida la edad:

  • líneas 19–24: La edad es una cadena, que debe estar presente ([NotBlank]), contener solo dígitos ([Type('digit')], que verifica que una cadena contenga solo dígitos) y cuyo valor debe estar entre 0 y 150 ([Range] acepta una cadena que representa un número). Gracias a [Sequentially], una edad [abc] se informa una sola vez. El parámetro [message] reemplaza el mensaje de la restricción por el nuestro: cada restricción tiene este parámetro (o varios, cuando tiene varios tipos de errores, como [minMessage] y [maxMessage] para [Length]);
  • las demás propiedades tienen las restricciones del ejemplo 08.

3.3.2. Mensajes personalizados

Los mensajes de error del validador están escritos en inglés en su código, pero pasan por el [Symfony] traductor (el componente Translation), que los traduce al idioma de la solicitud. [Symfony] incluye traducciones de sus mensajes en unos sesenta idiomas: basta con seleccionar el idioma de la aplicación y habilitar el traductor en [config/packages/framework.yaml]:

1
2
3
4
5
6
7
8
# config/packages/framework.yaml: la configuración del FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # el idioma de la aplicación: los mensajes de validación estarán en inglés
    default_locale: en
    # el servicio de traducción; sus diccionarios están en la carpeta translations/
    translator:
        default_path: '%kernel.project_dir%/translations'
  • línea 5: el idioma predeterminado de la aplicación (locale). Este es también el idioma de cada solicitud, a menos que la aplicación lo cambie (véase el capítulo sobre internacionalización);
  • líneas 7–8: el traductor, cuyos diccionarios específicos de la aplicación se encuentran en la carpeta [translations]. [%kernel.project_dir%] es un parámetro del contenedor: la carpeta del proyecto (ejemplo 01).

Los mensajes traducidos por [Symfony] no siempre son apropiados. La aplicación puede proporcionar sus propias traducciones, que tienen prioridad. Los mensajes de validación se almacenan en el [validators] dominio; las traducciones al inglés de este dominio se almacenan en el archivo [translations/validators.en.yaml] (el nombre de un diccionario se compone del dominio, el idioma y el formato):

1
2
3
4
5
# translations/validators.en.yaml: nuestras propias traducciones de los mensajes
# de validación (dominio [validators]), que tienen precedencia sobre las de Symfony.
# La clave es el mensaje original en inglés
'This value should not be blank.': 'the field is required'
'The value you selected is not a valid choice.': 'unknown value'

Un diccionario asocia cada clave con su traducción. Para los mensajes del validador, la clave es el mensaje original en inglés: ['This value should not be blank.'] se mostrará como “el campo es obligatorio”. Las claves van entre comillas simples porque contienen caracteres (puntos, espacios) que tienen significados específicos en [YAML]. Los mensajes que este archivo no traduce conservan la traducción de [Symfony] (el archivo [vendor/symfony/validator/Resources/translations/validators.en.xlf]), y un mensaje que ningún diccionario reconoce se muestra tal cual: es el caso de nuestro mensaje “an integer is expected.”

3.3.3. La acción: src/Controller/PersonsController.php

<?php
// src/Controller/PersonsController.php: es la acción la que decide qué hacer con una entrada inválida

namespace App\Controller;

use App\Model\PersonInput;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Validator\Validator\ValidatorInterface;

class PersonsController extends AbstractController
{
    // el VALIDADOR, un servicio de Symfony, se inyecta en la acción (véase el ejemplo 06)
    #[Route('/persons/action01', name: 'persons_action01', methods: ['GET'])]
    public function action01(Request $request, ValidatorInterface $validator): Response
    {
        // la entrada: los parámetros de la URL, copiados en el objeto
        $input = new PersonInput();
        $input->name = $request->query->get('name');
        $input->age = $request->query->get('age');
        $input->title = $request->query->get('title');
        $input->email = $request->query->get('email');
        // validate verifica las restricciones del objeto y devuelve la lista de errores
        $errors = $validator->validate($input);
        if (count($errors) > 0) {
            $items = '';
            foreach ($errors as $error) {
                $items .= "<li>{$error->getPropertyPath()}: {$error->getMessage()}</li>";
            }
            return new Response("<p>The form contains errors:</p><ul>$items</ul>");
        }
        // htmlspecialchars: el nombre ingresado se inserta en HTML; sus caracteres
        // < > & " ' se reemplazan por &lt; &gt;... (de lo contrario, una entrada podría inyectar HTML)
        return new Response("<p>Welcome $input->title ".htmlspecialchars($input->name)
            ." ($input->age years old)</p>");
    }
}
  • línea 17: el validador, un servicio de [Symfony] (de tipo [ValidatorInterface]), se inyecta en la acción como un servicio de la aplicación (ejemplo 06);
  • Líneas 20–24: La acción crea el objeto y copia en él los parámetros de la URL. Podríamos haber dejado, como en el ejemplo 08, que [#[MapQueryString]] construyera el objeto; sin embargo, [#[MapQueryString]] lo valida de inmediato y termina la acción en caso de error, que es exactamente lo que queremos evitar aquí;
  • Línea 26: [validate] comprueba las restricciones del objeto y devuelve una lista de violaciones (un objeto [ConstraintViolationList], que se recorre como un arreglo y cuyo tamaño devuelve [count]). La validación no lanza ninguna excepción: la propia acción decide qué hacer a continuación;
  • líneas 27–33: los errores, campo por campo, cada uno dentro de una etiqueta [<li>]. En una cadena entre comillas, [{$error->getMessage()}] inserta el resultado de una llamada a un método (las llaves delimitan la expresión). El operador [.=] agrega una cadena al final de otra;
  • líneas 36–37: si tiene éxito, un mensaje de bienvenida. El nombre se pasa por la función [htmlspecialchars] de [PHP], que reemplaza los caracteres que tienen significado en HTML ([<], [>], [&], ["], [']) por sus entidades ([&lt;], [&gt;]...): se mostrarán tal cual en lugar de ser interpretados. Sin esta precaución, un usuario podría ingresar un “nombre” que contenga HTML, o incluso [JavaScript], que se ejecutaría en el navegador de cualquiera que viera la página. Esta es la vulnerabilidad de seguridad más común en la web: la inyección de scripts (XSS, cross-site scripting). Los campos de tratamiento y edad no requieren esta protección: sus valores han sido validados por restricciones (uno de tres valores permitidos, todos numéricos). En el próximo capítulo, el motor de vistas [Twig] realizará este escape automáticamente para cualquier valor insertado en una página.

Una entrada válida, seguida de una entrada con cuatro errores:

Image

Image

Los mensajes están en inglés: los de [Symfony] (nombre, dirección), los nuestros (edad) y el de nuestro diccionario (tratamiento). La respuesta sin procesar a la segunda consulta, la de un nombre que contiene HTML, y la respuesta a una consulta sin nombre, con una edad demasiado alta:

1
2
3
curl "http://localhost:8000/persons/action01?name=m&age=abc&title=Mx&email=xx"
curl "http://localhost:8000/persons/action01?name=%3Cb%3Emartin%3C/b%3E&age=42&title=Mr"
curl "http://localhost:8000/persons/action01?age=200&title=Mr"
1
2
3
<p>The form contains errors:</p><ul><li>name: This value is too short. It should have 2 characters or more.</li><li>age: an integer is expected</li><li>title: unknown value</li><li>email: This value is not a valid email address.</li></ul>
<p>Welcome Mr &lt;b&gt;martin&lt;/b&gt; (42 years old)</p>
<p>The form contains errors:</p><ul><li>name: the field is required</li><li>age: This value should be between 0 and 150.</li></ul>

El nombre [<b>martin</b>] (codificado como [%3Cb%3E...] en la URL) se muestra tal cual, sin negrita: sus etiquetas han sido neutralizadas. Observe que esta vez la respuesta tiene un código de estado 200: es la acción la que decidió devolver una página normal que contiene los errores.

3.4. Ejemplo 10: parámetros múltiples

El mismo parámetro puede aparecer varias veces en una URL: [?color=red&color=green]. Esto es lo que envía un navegador para un grupo de casillas de verificación con el mismo nombre o para una lista de selección múltiple (véase el próximo capítulo). [PHP] maneja este caso a su manera. El controlador [ArraysController]:

<?php
// src/Controller/ArraysController.php: un parámetro que aparece varias veces en la URL

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Validator\ValidatorInterface;

#[Route('/arrays', name: 'arrays_', methods: ['GET'])]
class ArraysController extends AbstractController
{
    // /arrays/action01?color=red&color=green: para PHP, el segundo parámetro
    // REEMPLAZA al primero: solo se conserva el ÚLTIMO valor
    #[Route('/action01', name: 'action01')]
    public function action01(Request $request): JsonResponse
    {
        return $this->json(['color' => $request->query->get('color'),
            'raw' => $request->server->get('QUERY_STRING')]);
    }

    // /arrays/action02?color[]=red&color[]=green: los corchetes piden
    // a PHP que guarde TODOS los valores en un arreglo
    #[Route('/action02', name: 'action02')]
    public function action02(Request $request): JsonResponse
    {
        // all('color'): el parámetro en forma de arreglo (vacío si falta)
        $colors = $request->query->all('color');
        return $this->json(['color' => $colors, 'count' => count($colors)]);
    }

    // /arrays/action03?color[]=red: un arreglo, validado elemento por elemento
    #[Route('/action03', name: 'action03')]
    public function action03(Request $request, ValidatorInterface $validator): JsonResponse
    {
        $colors = $request->query->all('color');
        // se puede validar cualquier valor (aquí un arreglo), proporcionando las
        // restricciones para validar
        $violations = $validator->validate($colors, [
            // una lista de al menos un elemento
            new Assert\Count(min: 1),
            // All: las restricciones se aplican a CADA elemento
            new Assert\All([new Assert\Choice(choices: ['red', 'green', 'blue'])]),
        ]);
        $errors = [];
        foreach ($violations as $violation) {
            $errors[] = "color{$violation->getPropertyPath()}: {$violation->getMessage()}";
        }
        return $this->json(['colors' => $colors, 'valid' => ! $errors, 'errors' => $errors]);
    }
}
  • Líneas 21–22: Para [PHP], los parámetros de la URL forman un arreglo asociativo, en el que cada clave tiene un solo valor: un parámetro repetido reemplaza al anterior, y solo se conserva el último valor. La acción también devuelve, a modo de comparación, la cadena de parámetros sin procesar tal como la envió el navegador: la propiedad [server] de la solicitud contiene las variables que el servidor web transmite a [PHP], entre ellas [QUERY_STRING];
  • líneas 28–33: Para recuperar todos los valores, el nombre del parámetro debe terminar con corchetes: [?color[]=red&color[]=green]. [PHP] almacena entonces los valores en un arreglo, el valor del parámetro [color]. El método [all], cuando se le da el nombre de un parámetro, devuelve ese parámetro como un arreglo, vacío si el parámetro está ausente;
  • líneas 37–53: se valida el arreglo. El método [validate] del validador acepta cualquier valor, siempre que se especifiquen sus restricciones: aquí, [Count(min: 1)] (un arreglo con al menos un elemento) y [All], que aplica las restricciones que contiene a cada elemento del arreglo: cada uno debe ser uno de los tres colores;
  • línea 50: la ruta de la violación identifica el elemento erróneo: [[1]] para el segundo elemento (los índices comienzan en 0) y una cadena vacía para el propio arreglo. Esto se agrega al nombre del parámetro;
  • línea 52: el operador [!] se evalúa como [true] para un arreglo vacío, que se evalúa como “falso” en una condición.

El archivo [translations/validators.en.yaml] del ejemplo traduce el mensaje de la restricción [Choice] (ejemplo 09). Los resultados:

1
2
3
curl "http://localhost:8000/arrays/action01?color=red&color=green"
curl -g "http://localhost:8000/arrays/action02?color[]=red&color[]=green"
curl http://localhost:8000/arrays/action02
{
    "color": "green",
    "raw": "color=red&color=green"
}
{
    "color": [
        "red",
        "green"
    ],
    "count": 2
}
{
    "color": [],
    "count": 0
}

La opción [-g] de [curl] evita que interprete por sí mismo los corchetes de la URL. Un navegador, en cambio, los codifica ([color%5B%5D=red]), lo que [PHP] también entiende. En cuanto a HTML, todo lo que hay que hacer es nombrar las casillas de verificación de un grupo [color[]] (el componente Form de [Symfony] lo hará por nosotros; véase el ejemplo 18). Esta regla se aplica específicamente a [PHP]: los frameworks de otros lenguajes ([Flask], [Spring MVC], [ASP.NET Core]) conservan todos los valores de un parámetro repetido, sin corchetes.

[Symfony] se asegura de que las dos formas no se confundan: [get] rechaza un parámetro que es un arreglo, y [all] rechaza un parámetro que no es un arreglo. En ambos casos se devuelve un error 400:

curl -i -g "http://localhost:8000/arrays/action01?color[]=red"
curl -i "http://localhost:8000/arrays/action02?color=red"
1
2
3
4
5
6
HTTP/1.1 400 Bad Request
X-Debug-Exception: Input%20value%20%22color%22%20contains%20a%20non-scalar%20value.
...
HTTP/1.1 400 Bad Request
X-Debug-Exception: Unexpected%20value%20for%20parameter%20%22color%22%3A%20expecting%20%22array%22%2C%20got%20%22string%22.
...

La validación tiene éxito, luego falla por un color desconocido y después por una lista vacía:

1
2
3
curl -g "http://localhost:8000/arrays/action03?color[]=red&color[]=blue"
curl -g "http://localhost:8000/arrays/action03?color[]=red&color[]=yellow"
curl http://localhost:8000/arrays/action03
{
    "colors": [
        "red",
        "blue"
    ],
    "valid": true,
    "errors": []
}
{
    "colors": [
        "red",
        "yellow"
    ],
    "valid": false,
    "errors": [
        "color[1]: unknown value"
    ]
}
{
    "colors": [],
    "valid": false,
    "errors": [
        "color: This collection should contain 1 element or more."
    ]
}

El error relativo al color desconocido hace referencia a [color[1]]: el parámetro y el índice del elemento problemático en el arreglo.

3.5. Ejemplo 11: los parámetros de una solicitud POST

Los ejemplos anteriores usaban solicitudes GET, cuyos parámetros están contenidos en la URL. Una solicitud POST transporta sus datos en su cuerpo, en dos formas principales:

  • campos de un formulario HTML: el cuerpo tiene la misma sintaxis que una cadena de consulta ([name=martin&age=42]), y su tipo (encabezado [Content-Type]) es [application/x-www-form-urlencoded];
  • un documento JSON, enviado por un programa ([JavaScript] en una página, cliente de una API...): el tipo es [application/json].

El controlador [PostController]:

<?php
// src/Controller/PostController.php: los parámetros de una solicitud POST

namespace App\Controller;

use App\Model\PersonModel;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Exception\JsonException;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
use Symfony\Component\HttpKernel\Exception\UnsupportedMediaTypeHttpException;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/post', name: 'post_', methods: ['POST'])]
class PostController extends AbstractController
{
    // los campos de un formulario HTML (cuerpo application/x-www-form-urlencoded):
    // $request->request contiene los parámetros del CUERPO de la solicitud
    #[Route('/action01', name: 'action01')]
    public function action01(Request $request): JsonResponse
    {
        return $this->json([
            'receivedType' => $request->headers->get('Content-Type'),
            'fields' => $request->request->all(),
        ]);
    }

    // un cuerpo JSON: toArray() lo deserializa
    #[Route('/action02', name: 'action02')]
    public function action02(Request $request): JsonResponse
    {
        // el formato del cuerpo, deducido del encabezado Content-Type: 'json', 'form'...
        if ($request->getContentTypeFormat() !== 'json') {
            throw new UnsupportedMediaTypeHttpException('the body of the request must be JSON');
        }
        try {
            $body = $request->toArray();
        } catch (JsonException $e) {
            throw new BadRequestHttpException('Malformed JSON: '.$e->getMessage());
        }
        return $this->json(['receivedType' => $request->headers->get('Content-Type'), 'body' => $body,
            'name' => $request->getPayload()->get('name')]);
    }

    // un solo campo; getPayload(): los parámetros del cuerpo, ya sea un
    // formulario o un documento JSON
    #[Route('/action03', name: 'action03')]
    public function action03(Request $request): Response
    {
        $name = $request->getPayload()->get('name');
        return new Response("name = [$name]");
    }

    // el cuerpo, formulario o JSON, enlazado a un objeto PersonModel y validado (véase
    // el ejemplo 08): #[MapRequestPayload] es la contraparte de #[MapQueryString]
    #[Route('/action04', name: 'action04')]
    public function action04(#[MapRequestPayload] PersonModel $person): JsonResponse
    {
        return $this->json(['person' => $person, 'valid' => true]);
    }
}
  • línea 17: todas las rutas del controlador aceptan únicamente el método POST;
  • Línea 26: El encabezado de solicitud [Content-Type];
  • línea 27: la propiedad [request] de la solicitud (el nombre, “history”, induce a error) contiene los parámetros del cuerpo, en el caso de un cuerpo de formulario, en una bolsa de parámetros similar a [query] (ejemplo 07): [get], [getInt], [all]... Los campos de un formulario siguen las reglas del ejemplo 10: un campo repetido debe tener un nombre que termine en [[]];
  • líneas 36–38: [getContentTypeFormat()] especifica el formato del cuerpo, derivado del encabezado [Content-Type]: [json], [form], [xml]... Un cuerpo que no está declarado como JSON se rechaza con el error 415 (Unsupported Media Type);
  • líneas 39–43: [toArray()] deserializa el cuerpo JSON: el texto JSON se convierte en un arreglo [PHP]. Un JSON mal formado lanza una excepción [JsonException] (del componente HttpFoundation, importada en la línea 7), que el bloque [try] / [catch] intercepta para responder con un error 400 que contiene nuestro mensaje. Sin este bloque, [Symfony] respondería por sí mismo con un error 400: esta excepción es una de las que reconoce como errores del cliente;
  • líneas 44–45: El método [getPayload()] devuelve los parámetros del cuerpo, ya sea un formulario o un documento JSON, en una bolsa de parámetros. Es el método más utilizado porque no depende de la forma de la solicitud;
  • línea 53: un campo de formulario, leído por [getPayload()];
  • líneas 59–63: el atributo [#[MapRequestPayload]] es el equivalente, para el cuerpo de la solicitud, de [#[MapQueryString]] (ejemplo 08): construye un objeto [PersonModel] (la clase del ejemplo 08) a partir de los campos del formulario o del documento JSON, y lo valida. Un modelo no válido lanza una excepción (con código 422, Unprocessable Content, en este caso), que el listener [ValidationErrors] del ejemplo 08 convierte en una respuesta 400. El ejemplo también usa la configuración y el diccionario del ejemplo 09: los mensajes estarán en inglés, con nuestras propias traducciones.

[Symfony] no requiere nada más para aceptar solicitudes POST: no tiene una protección anti-CSRF que se aplique a todas las solicitudes (ejemplo 02). Con [curl], la opción [-d] (data) envía un cuerpo; la solicitud pasa entonces a ser una solicitud POST, de tipo [application/x-www-form-urlencoded], a menos que la opción [-H] (header) especifique un tipo diferente. La opción [-X POST] establece explícitamente el método (aquí es opcional). Los campos de un formulario, incluido un campo repetido:

curl -i -g -X POST -d "name=martin&age=42&hobby[]=tennis&hobby[]=piano" http://localhost:8000/post/action01
HTTP/1.1 200 OK
Content-Type: application/json

{
    "receivedType": "application/x-www-form-urlencoded",
    "fields": {
        "name": "martin",
        "age": "42",
        "hobby": [
            "tennis",
            "piano"
        ]
    }
}

Un cuerpo JSON, que contiene un entero y un arreglo:

curl -i -H "Content-Type: application/json" -d "{\"name\": \"martin\", \"age\": 42, \"children\": [\"léa\", \"tom\"]}" http://localhost:8000/post/action02
HTTP/1.1 200 OK
Content-Type: application/json

{
    "receivedType": "application/json",
    "body": {
        "name": "martin",
        "age": 42,
        "children": [
            "léa",
            "tom"
        ]
    },
    "name": "martin"
}

Las comillas del JSON van precedidas de [\] para evitar que termine la cadena del comando; en [Linux] y [macOS], también se puede encerrar el JSON entre apóstrofos: [-d '{"name": "martin"}']. A diferencia de los campos de un formulario, el JSON transporta tipos de datos: la edad ya es un entero. Un cuerpo que no es JSON, seguido de un JSON mal formado (solicitando una respuesta JSON para ver el mensaje):

curl -i -H "Accept: application/json" -d "name=martin" http://localhost:8000/post/action02
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -d "{\"name\": " http://localhost:8000/post/action02
1
2
3
4
5
6
7
8
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json

{"type":"https:\/\/tools.ietf.org\/html\/rfc2616#section-10","title":"An error occurred","status":415,"detail":"the body of the request must be JSON",...}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{"type":"https:\/\/tools.ietf.org\/html\/rfc2616#section-10","title":"An error occurred","status":400,"detail":"Malformed JSON: Could not decode request body.",...}

Un solo campo y luego la misma URL solicitada mediante GET:

curl -d "name=jean%20dupont" http://localhost:8000/post/action03
curl -i "http://localhost:8000/post/action03?name=martin"
1
2
3
4
5
name = [jean dupont]
HTTP/1.1 405 Method Not Allowed
Content-Type: text/html; charset=UTF-8
Allow: POST
...

La URL existe, pero no para el método GET: [Symfony] devuelve una respuesta 405 (Method Not Allowed), y su encabezado [Allow] lista los métodos aceptados (ejemplo 02). Por último, el modelo vinculado al cuerpo de la solicitud: primero mediante un formulario válido, luego uno no válido y, finalmente, mediante un documento JSON:

1
2
3
curl -d "name=martin&age=42&title=Mr" http://localhost:8000/post/action04
curl -i -d "name=m&age=200" http://localhost:8000/post/action04
curl -H "Content-Type: application/json" -d "{\"name\": \"martin\", \"age\": \"42\", \"title\": \"Mr\"}" http://localhost:8000/post/action04
{
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mr",
        "email": null
    },
    "valid": true
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "This value is too short. It should have 2 characters or more."
        },
        {
            "field": "age",
            "message": "This value should be between 0 and 150."
        },
        {
            "field": "title",
            "message": "the field is required"
        }
    ]
}
{
    "status": 400,
    "errors": [
        {
            "field": "age",
            "message": "This value should be of type int|null."
        }
    ]
}

La última solicitud muestra una diferencia entre los dos formatos de cuerpo. Los campos de un formulario son siempre cadenas: [Symfony] convierte, por lo tanto, la cadena ["42"] a entero. Un documento JSON, en cambio, tiene tipos de datos: si el cliente envía una cadena (["42"], entre comillas) donde la clase espera un entero, se trata de un error de tipo, que [Symfony] informa sin intentar la conversión ([int|null] es el tipo [?int] de la propiedad, escrito de otra manera).

3.6. Ejemplo 12: enlace y validación personalizados

Los tipos, atributos y restricciones estándar no siempre bastan. Este ejemplo muestra tres formas de extender el enlace y la validación:

  • un resolvedor de argumentos “personalizado”: una fecha en formato francés, [23-09-2026], ubicada en la ruta de la URL, proporcionada a la acción como un objeto;
  • un listener que proporciona a la acción un parámetro que no proviene de la URL, sino de un encabezado HTTP;
  • una restricción de validación personalizada (sin espacios) y la conversión de una fecha [dd/mm/yyyy].
12-custom-binding/
├── src/
│   ├── Controller/
│   │   └── ExamplesController.php
│   ├── EventListener/
│   │   └── ErrorAsText.php
│   ├── Binding/
│   │   ├── DetectLanguage.php
│   │   ├── DayFr.php
│   │   ├── DayFrResolver.php
│   │   ├── NoSpace.php
│   │   └── NoSpaceValidator.php
│   ├── Model/
│   │   └── SearchModel.php
│   └── Kernel.php
└── ...

3.6.1. Un objeto vinculado a un parámetro de ruta: DayFr.php y DayFrResolver.php

Hemos visto que los parámetros de una acción son proporcionados por resolvedores de argumentos (ejemplo 05): uno proporciona los parámetros de ruta (ejemplo 02), otro la solicitud (ejemplo 05), otro los servicios (ejemplo 06), y otros más los parámetros de la URL ([#[MapQueryParameter]]) o un modelo ([#[MapQueryString]]). [Symfony] tiene unos quince, entre ellos uno para fechas ([#[MapDateTime]]) y otro para enumeraciones. La aplicación puede escribir los suyos. Escribiremos uno para una fecha en formato francés, representada por la clase [DayFr]:

<?php
// src/Binding/DayFr.php: una fecha francesa "23-09-2026" en la ruta de la URL

namespace App\Binding;

use DateTimeImmutable;
use Stringable;

readonly class DayFr implements Stringable
{
    public function __construct(public DateTimeImmutable $date)
    {
    }

    // texto de la ruta -> objeto DayFr; null: el texto no designa una fecha
    public static function fromUrl(string $text): ?self
    {
        // el ! de "!d-m-Y" restablece la hora a cero (de lo contrario, sería la hora actual)
        $date = DateTimeImmutable::createFromFormat('!d-m-Y', $text);
        // createFromFormat acepta "31-02-2026" (y lo convierte en el 3 de marzo): verificamos
        // que la fecha, formateada de nuevo, devuelva el texto recibido
        if ($date === false || $date->format('d-m-Y') !== $text) {
            return null;
        }
        return new self($date);
    }

    // objeto DayFr -> texto de la ruta (usado al construir la URL de una ruta)
    public function __toString(): string
    {
        return $this->date->format('d-m-Y');
    }
}
  • línea 9: una clase inmutable que implementa la interfaz [Stringable] de [PHP]: sus objetos pueden convertirse en cadena mediante su método [__toString];
  • línea 11: la fecha, un objeto [DateTimeImmutable] (la clase de fecha de [PHP]; la versión [Immutable] crea un nuevo objeto con cada modificación ([$date->modify('+1 day')] devuelve una nueva fecha) en lugar de modificar el objeto);
  • líneas 16–26: un método estático que crea un objeto [DayFr] a partir del texto de la ruta, o devuelve [null] si el texto no es válido ([?self]: un objeto de la clase actual, o [null]). [DateTimeImmutable::createFromFormat] analiza una cadena según un formato específico: [d] para el día, [m] para el mes y [Y] para el año de cuatro dígitos; el [!] inicial pone la hora en cero. [createFromFormat] es tolerante: acepta [31-02-2026] y lo interpreta como el 3 de marzo. La validación de la línea 22 rechaza este caso: la fecha, reformateada por [format], debe coincidir exactamente con el texto recibido;
  • Líneas 29–32: la operación inversa: el objeto se convierte en el texto de la ruta. [Symfony] lo usará para crear una URL a partir de un objeto [DayFr].

El resolvedor:

<?php
// src/Binding/DayFrResolver.php: un ARGUMENT RESOLVER, que proporciona a las acciones
// sus parámetros de tipo DayFr

namespace App\Binding;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\Controller\ValueResolverInterface;
use Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadata;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

class DayFrResolver implements ValueResolverInterface
{
    // invocado para cada parámetro de una acción que pide este resolver (véase el
    // controlador): devuelve el valor del parámetro, en un arreglo
    public function resolve(Request $request, ArgumentMetadata $argument): iterable
    {
        // el parámetro de ruta con el mismo nombre que el parámetro de la acción ($day)
        $text = $request->attributes->get($argument->getName());
        if (! is_string($text)) {
            return [];    // nada que proporcionar: otro resolver se encargará
        }
        // una fecha que no existe: la URL no designa nada, error 404
        return [DayFr::fromUrl($text) ?? throw new NotFoundHttpException("[$text] is not a date")];
    }
}
  • Línea 12: Un resolvedor de argumentos implementa la interfaz [ValueResolverInterface], cuyo único método es [resolve];
  • Línea 16: [resolve] recibe la solicitud y la descripción del parámetro de la acción (un objeto [ArgumentMetadata]: su nombre, tipo, valor predeterminado y atributos). Devuelve el valor del parámetro en un arreglo ([iterable]), o un arreglo vacío si no tiene nada que devolver;
  • Línea 19: Los parámetros de ruta se almacenan en los atributos de la solicitud ([$request->attributes]), un conjunto de parámetros que también contiene información calculada por [Symfony] (el nombre de la ruta, [_route], por ejemplo). Buscamos el parámetro con el mismo nombre que el de la acción;
  • línea 24: el objeto [DayFr] o, si el texto no corresponde a una fecha, un error 404: la URL no corresponde a nada. El operador [??] devuelve su operando izquierdo si no es [null], y el operando derecho en caso contrario; acepta una expresión [throw] a la derecha.

La clase es un servicio, como todas las de la carpeta [src] (ejemplo 02): [Symfony] la reconoce como un resolvedor de argumentos, gracias a su interfaz ([autoconfigure]). El controlador indicará qué parámetro debe proporcionar.

3.6.2. Un parámetro proporcionado por un listener: src/Binding/DetectLanguage.php

Para proporcionar a una acción información calculada a partir de la solicitud, también se puede hacer que un listener la calcule (ejemplo 03) y luego la incluya en la solicitud antes de la acción:

<?php
// src/Binding/DetectLanguage.php: un listener que CALCULA una información para la acción

namespace App\Binding;

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

// el evento [kernel.request]: llega la solicitud, la acción aún no se invoca
#[AsEventListener(event: KernelEvents::REQUEST)]
class DetectLanguage
{
    public function __invoke(RequestEvent $event): void
    {
        $request = $event->getRequest();
        // el encabezado "Accept-Language: fr-FR,fr;q=0.9,en;q=0.8" -> "fr": el idioma
        // preferido del navegador entre los ofrecidos (el primero por defecto)
        $language = $request->getPreferredLanguage(['fr', 'en']);
        // los ATRIBUTOS de la solicitud: información que la aplicación guarda allí
        // para las funciones que procesarán la solicitud después
        $request->attributes->set('language', $language);
    }
}
  • línea 11: un listener del evento [kernel.request], desencadenado cuando llega la solicitud, antes de llamar a la acción (el propio enrutamiento es un listener de este evento: el capítulo sobre el ciclo de vida explicará su orden);
  • línea 19: el encabezado [Accept-Language] de la solicitud especifica los idiomas del usuario, en orden de preferencia: [fr-FR,fr;q=0.9,en;q=0.8] (el coeficiente [q] mide la preferencia, en una escala de 0 a 1). [getPreferredLanguage] selecciona el idioma preferido del usuario entre los que ofrece la aplicación; si no hay ningún encabezado, toma por defecto el primer idioma de la lista;
  • línea 22: el idioma se almacena en los atributos de la solicitud con el nombre [language], junto a los parámetros de ruta.

El listener se ejecuta para todas las solicitudes. [Symfony] no tiene el equivalente del middleware de rutas que existe en otros frameworks: un listener que debe actuar solo en ciertas rutas comprueba por sí mismo el nombre de la ruta ([$request->attributes->get('_route')]). En cuanto a la acción, recibirá la información sin hacer nada especial (véase el controlador).

3.6.3. Una restricción “personalizada” y una conversión: NoSpace.php y SearchModel.php

Una restricción “personalizada” se escribe como dos clases: la restricción en sí, que la describe (sus opciones, su mensaje), y su validador, que la verifica.

<?php
// src/Binding/NoSpace.php: una restricción de validación "casera"

namespace App\Binding;

use Attribute;
use Symfony\Component\Validator\Constraint;

// #[Attribute]: la clase puede usarse como atributo (#[NoSpace]); la
// verificación en sí se confía a la clase NoSpaceValidator
#[Attribute(Attribute::TARGET_PROPERTY)]
class NoSpace extends Constraint
{
    public string $message = 'the field must not contain a space';
}
  • línea 11: el atributo [#[Attribute]] de [PHP] permite usar la clase como atributo, aquí sobre una propiedad ([TARGET_PROPERTY]);
  • línea 12: una restricción hereda de la clase [Constraint];
  • línea 14: su mensaje de error, en una propiedad pública: puede cambiarse en tiempo de ejecución ([#[NoSpace(message: '...')]]).
<?php
// src/Binding/NoSpaceValidator.php: la verificación de la restricción NoSpace

namespace App\Binding;

use Symfony\Component\Validator\Constraint;
use Symfony\Component\Validator\ConstraintValidator;

class NoSpaceValidator extends ConstraintValidator
{
    public function validate(mixed $value, Constraint $constraint): void
    {
        if ($value !== null && str_contains((string) $value, ' ')) {
            // el valor no es adecuado: se informa una "violación", con el
            // mensaje de la restricción
            $this->context->buildViolation($constraint->message)->addViolation();
        }
    }
}
  • línea 9: el validador de una restricción lleva el nombre de su clase, seguido de [Validator]: así lo localiza [Symfony] . Hereda de [ConstraintValidator];
  • Líneas 11–18: Su método [validate] recibe el valor que se va a validar y la restricción. [str_contains] comprueba la presencia de un texto en una cadena; [(string)] convierte el valor en cadena. Si el valor no es válido, se informa de una violación al contexto de validación ([$this->context]), junto con el mensaje de la restricción. El tipo [mixed] se refiere a cualquier tipo. Al igual que las restricciones de [Symfony], esta acepta [null]: la ausencia de un valor la maneja [NotBlank].

La restricción la usa el modelo de búsqueda:

<?php
// src/Model/SearchModel.php: el modelo de la búsqueda

namespace App\Model;

use App\Binding\NoSpace;
use DateTimeImmutable;
use Symfony\Component\Validator\Constraints as Assert;

readonly class SearchModel
{
    public function __construct(
        // una restricción "casera"
        #[NoSpace]
        public ?string $keyword = null,
        // DateTime: una fecha en formato dd/mm/yyyy, que existe; {{ value }}: el valor recibido
        #[Assert\DateTime(format: 'd/m/Y', message: '{{ value }} is not a valid dd/mm/yyyy date')]
        public ?string $since = null,
    ) {
    }

    // la fecha, CONVERTIDA en un objeto de fecha (null si falta)
    public function since(): ?DateTimeImmutable
    {
        return $this->since === null ? null
            : DateTimeImmutable::createFromFormat('!d/m/Y', $this->since);
    }
}
  • líneas 14–15: nuestra restricción, usada igual que cualquier otra;
  • líneas 17–18: la restricción [DateTime] verifica que el valor sea una fecha con el formato indicado ([d/m/Y]: dd/mm/aaaa) y que esa fecha exista. Nuestro mensaje reemplaza al predeterminado; el marcador [{{ value }}] será sustituido por el valor recibido (entre comillas). La fecha sigue siendo una cadena en el modelo: una propiedad de tipo [DateTimeImmutable] sería convertida por el Serializer, pero entonces una fecha no válida provocaría un error de conversión (ejemplo 08), con un mensaje de error bastante vago;
  • Líneas 23–27: la conversión de la fecha, en un método del modelo: el objeto [DateTimeImmutable] correspondiente, o [null] si falta la fecha. La acción llama a este método solo después de la validación: por lo tanto, la fecha es necesariamente válida.

Por último, la respuesta ante una validación fallida. Queremos que sea distinta de la del ejemplo 08: el primer mensaje de error, en texto sin formato, con el código 400:

<?php
// src/EventListener/ErrorAsText.php: un modelo inválido produce una respuesta 400,
// que contiene, como texto plano, el mensaje del primer error

namespace App\EventListener;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Validator\Exception\ValidationFailedException;

#[AsEventListener(event: KernelEvents::EXCEPTION)]
class ErrorAsText
{
    public function __invoke(ExceptionEvent $event): void
    {
        $validation = $event->getThrowable()->getPrevious();
        if ($validation instanceof ValidationFailedException) {
            $event->setResponse(new Response($validation->getViolations()[0]->getMessage(),
                Response::HTTP_BAD_REQUEST, ['Content-Type' => 'text/plain; charset=utf-8']));
        }
    }
}

Este es el listener del ejemplo 08, reducido a lo esencial: [getViolations()[0]] es la primera violación. Un listener de este tipo se aplica a toda la aplicación. Para ofrecer una respuesta distinta según la acción, habría que verificar el nombre de la ruta (véase más arriba).

3.6.4. El controlador: src/Controller/ExamplesController.php

<?php
// src/Controller/ExamplesController.php: enlace y validación personalizados

namespace App\Controller;

use App\Binding\DayFr;
use App\Binding\DayFrResolver;
use App\Model\SearchModel;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\MapQueryString;
use Symfony\Component\HttpKernel\Attribute\ValueResolver;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/examples', name: 'examples_', methods: ['GET'])]
class ExamplesController extends AbstractController
{
    // /examples/schedule/23-09-2026: #[ValueResolver] confía el parámetro $day al
    // resolver DayFrResolver, que lo ENLAZA con el parámetro de ruta {day}
    #[Route('/schedule/{day}', name: 'schedule', requirements: ['day' => '[0-9]{2}-[0-9]{2}-[0-9]{4}'])]
    public function schedule(#[ValueResolver(DayFrResolver::class)] DayFr $day): Response
    {
        // generateUrl construye la URL de una ruta; el objeto DayFr se convierte en el texto
        // de la ruta mediante su método __toString: "23-09-2026"
        return new Response("schedule for the day [{$day->date->format('Y-m-d')}], of type "
            .get_debug_type($day->date).', URL: '.$this->generateUrl('examples_schedule', ['day' => $day]));
    }

    // /examples/hello: un parámetro que no proviene de la URL, sino de un encabezado,
    // calculado por el listener DetectLanguage y guardado en los atributos de la solicitud
    #[Route('/hello', name: 'hello')]
    public function hello(string $language): Response
    {
        return new Response($language === 'en' ? 'Hello!' : 'Bonjour !');
    }

    // /examples/search?keyword=symfony&since=01/09/2026
    #[Route('/search', name: 'search')]
    public function search(#[MapQueryString] SearchModel $search): Response
    {
        $since = $search->since()?->format('Y-m-d');
        return new Response("search for [$search->keyword] since [$since]");
    }
}
  • Línea 20: la ruta del calendario, cuyo parámetro [{day}] está restringido por una expresión regular: [[0-9]] denota un dígito, [{2}] denota la repetición del patrón anterior: dos dígitos, un guion, dos dígitos, un guion, cuatro dígitos. Un segmento de ruta con otro formato no coincide con la ruta (404), sin que siquiera se consulte a nuestro resolvedor;
  • línea 21: el atributo [#[ValueResolver]] asigna el parámetro [$day] a un resolvedor, identificado por su clase: solo este lo proporcionará. Sin este atributo, [Symfony] probaría sus resolvedores por orden de prioridad, y el resolvedor de parámetros de ruta, que tiene precedencia sobre el nuestro, proporcionaría la cadena ["23-09-2026"] a un parámetro de tipo [DayFr]: un error;
  • líneas 25–26: la fecha se muestra en formato internacional ([Y-m-d]: [2026-09-23]). El método [generateUrl] de [AbstractController] crea la URL de una ruta con nombre, junto con sus parámetros (esto es lo que hacía [redirectToRoute] en el ejemplo 04). Se le pasa el propio objeto [DayFr]: [Symfony] lo convierte en cadena mediante su método [__toString]. La URL se refiere al sitio ([/examples/...]); un tercer parámetro exigiría una URL absoluta;
  • líneas 31–35: el parámetro [$language] no corresponde a ningún parámetro de ruta. Sin embargo, el resolvedor de parámetros de ruta suele buscar un atributo de la solicitud con el mismo nombre que el parámetro: por eso encuentra el que el listener [DetectLanguage] almacenó allí. Eso es todo: no se necesita ningún atributo en el parámetro;
  • Líneas 38–43: el modelo de búsqueda, enlazado a los parámetros de la URL y validado (ejemplo 08). La acción solo acepta modelos válidos; llama al método de conversión de la fecha. El [?->] operador (nullsafe) llama a un método si el objeto no es [null], y devuelve [null] en caso contrario.

3.6.5. Ejecución

El objeto asociado al parámetro de ruta:

curl "http://localhost:8000/examples/schedule/23-09-2026"
curl -i "http://localhost:8000/examples/schedule/31-02-2026"
1
2
3
4
5
schedule for the day [2026-09-23], of type DateTimeImmutable, URL: /examples/schedule/23-09-2026
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=UTF-8
X-Debug-Exception: %5B31-02-2026%5D%20is%20not%20a%20date
...

La fecha se muestra en formato internacional, pero la URL generada por [generateUrl] volvió al formato francés. El 31 de febrero no existe: 404, con un mensaje de nuestro resolvedor. Una fecha en formato internacional, [2026-09-23], no coincide con el patrón descrito por la expresión regular: también es un 404, pero esta vez porque ninguna ruta coincide.

El listener. La [-H] opción de [curl] establece el encabezado [Accept-Language]:

1
2
3
curl -H "Accept-Language: en-US,en;q=0.9,fr;q=0.8" http://localhost:8000/examples/hello
curl -H "Accept-Language: fr-FR,fr;q=0.9" http://localhost:8000/examples/hello
curl http://localhost:8000/examples/hello
1
2
3
Hello!
Bonjour !
Bonjour !

Sin el encabezado [Accept-Language] ([curl] no envía ninguno), se usa el primer idioma de la lista. El capítulo sobre internacionalización volverá sobre este tema, con la selección del idioma por parte del usuario.

La restricción «propia» y la conversión de la fecha:

1
2
3
4
5
curl "http://localhost:8000/examples/search?keyword=symfony&since=01/09/2026"
curl "http://localhost:8000/examples/search"
curl -i "http://localhost:8000/examples/search?keyword=symfony%20mvc"
curl "http://localhost:8000/examples/search?since=2026-09-01"
curl "http://localhost:8000/examples/search?since=31/02/2026"
1
2
3
4
5
6
7
8
search for [symfony] since [2026-09-01]
search for [] since []
HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8

the field must not contain a space
"2026-09-01" is not a valid dd/mm/yyyy date
"31/02/2026" is not a valid dd/mm/yyyy date

Sin ningún parámetro, [#[MapQueryString]] construye un modelo vacío, que es válido: sus dos propiedades son opcionales.

3.6.6. Conclusión

Resumamos los métodos de que dispone una acción para obtener su modelo:

Parámetros de ruta
los parámetros de la acción, con los mismos nombres; convertidos según su tipo ([int $id]), restringidos mediante [requirements]; enlazados a un objeto mediante un resolvedor de argumentos ([ValueResolverInterface], [#[ValueResolver]])
Parámetros de la URL
[$request->query->get(...)], [getInt], [all]...; [#[MapQueryParameter]]; un parámetro repetido se escribe como [name[]]
Campos de un formulario POST
[$request->request->get(...)], o [$request->getPayload()->get(...)], que también lee JSON
JSON del cuerpo
[$request->toArray()], [$request->getPayload()]
Modelo descrito por una clase
[#[MapQueryString]] (URL), [#[MapRequestPayload]] (el cuerpo): conversión y luego validación
Encabezados
[$request->headers->get(...)], y métodos que los analizan, como [getPreferredLanguage]
Validación
restricciones ([#[Assert\...]]), verificadas antes de la acción ([#[MapQueryString]]...) o durante la acción ([ValidatorInterface]); restricciones «personalizadas» ([Constraint] y [ConstraintValidator])
Mensajes
el idioma [default_locale], el traductor y los diccionarios [translations/validators.xx.yaml]
Errores comunes
un listener de eventos para [kernel.exception]
Parámetro calculado
un listener de eventos [kernel.request], que almacena información en los atributos de la solicitud

En cambio, los formularios HTML requieren algo más que validación: deben mostrarse, volver a mostrarse con los datos ingresados por el usuario y los errores, y protegerse contra solicitudes falsificadas. [Symfony] delega todo esto en su componente Form. Este es el tema del próximo capítulo, una vez presentadas las vistas.