Skip to content

9. Arquitectura en capas y acceso a datos

Los ejemplos anteriores almacenaban sus datos en memoria o en la caché. Una aplicación real los almacena en una base de datos y se organiza en capas (véase el diagrama de la introducción):

  • la capa web (controladores, formularios, vistas): lee la solicitud, llama a la capa de negocio y selecciona la vista;
  • la capa de negocio: reglas de negocio;
  • la capa DAO (Data Access Object): consultas a la base de datos.

Cada capa conoce únicamente la capa inferior, y el menor número posible de sus detalles: la capa web no conoce SQL, y la capa de negocio no conoce HTML. Esta separación facilita la comprensión, la prueba y la evolución de cada capa. El ejemplo 28 aplica esto a la gestión de una lista de personas: es, a menor escala, la gestión de médicos y clientes del caso de estudio.

En [PHP], el acceso a bases de datos se organiza en varias capas:

  • La extensión PDO (PHP Data Objects) de [PHP] define una interfaz común para todas las extensiones de SGBD: abrir una conexión, ejecutar un comando SQL y leer filas. Cada SGBD tiene su propio controlador: [pdo_mysql] para [MySQL] (y [MariaDB]), incluido con [PHP];
  • El framework DBAL (Database Abstraction Layer) agrega la gestión de conexiones y transacciones, un generador de consultas y la conversión de tipos, y traduce los errores de cada SGBD a excepciones comunes (una violación de una restricción de unicidad se convierte en una [UniqueConstraintViolationException], sea cual sea el SGBD);
  • Doctrine ORM (Object-Relational Mapper) asigna clases (entidades) a tablas de la base de datos y transforma las filas recuperadas en objetos. Sigue el modelo llamado Data Mapper : las entidades son objetos ordinarios que no saben nada de la base de datos; otro objeto, el administrador de entidades, las lee y las guarda. Esta es la diferencia con [Eloquent] y su ORM (que proviene de [Laravel]), que sigue el modelo Active Record (cada objeto sabe cómo leerse y guardarse a sí mismo, [$person->save()]).

[Doctrine] no pertenece a [Symfony]: es un proyecto independiente, pero su ORM es el recomendado por [Symfony], y DoctrineBundle lo integra en la aplicación. Es el equivalente de [JDBC], [JPA], y [Hibernate] en [Java] (en el cual [Doctrine] se basó), de [Entity Framework Core] en [C#], o de [SQLAlchemy] en [Python]. Cabe señalar una consecuencia del funcionamiento de [PHP]: como nada sobrevive a la solicitud, cada solicitud abre su propia conexión a la base de datos (en su primer comando SQL) y la cierra al terminar. No hay grupo de conexiones como en [Java] o [Python]; abrir una conexión a [MySQL] en la misma máquina toma apenas una fracción de milisegundo.

El ejemplo requiere un servidor [MySQL] (o [MariaDB]) en ejecución: el apéndice explica cómo instalar uno con [Laragon].

9.1. Ejemplo 28: un sistema de gestión de personal de tres capas

28-layers/
├── .env
├── config/
│   ├── bundles.php
│   └── packages/
│       ├── doctrine.yaml
│       ├── framework.yaml
│       └── twig.yaml
├── database/
│   └── dbpersons.sql
├── public/
│   ├── css/
│   │   └── styles.css
│   └── js/
│       └── app.js
├── src/
│   ├── Controller/
│   │   └── PersonsController.php
│   ├── Dao/
│   │   └── PersonsDao.php
│   ├── Entity/
│   │   └── Person.php
│   ├── Form/
│   │   ├── PersonInput.php
│   │   └── PersonType.php
│   └── Business/
│       ├── PersonData.php
│       ├── BusinessException.php
│       └── PersonsBusiness.php
├── templates/
│   ├── fragments/
│   │   └── confirmation.html.twig
│   ├── layout.html.twig
│   └── persons/
│       ├── form.html.twig
│       └── list.html.twig
└── ...

9.1.1. La base de datos

La base de datos [dbpersons] se crea mediante el script SQL. Con [Laragon], se puede ejecutar, por ejemplo, en la herramienta [HeidiSQL] (menú Archivo / Ejecutar un archivo SQL), o desde la línea de comandos, en la carpeta del ejemplo:

mysql -u root < database/dbpersons.sql

El archivo [database/dbpersons.sql]:

-- base de datos del ejemplo 28: una sola tabla, [persons]
-- el script está escrito en UTF-8
SET NAMES utf8mb4;
DROP DATABASE IF EXISTS dbpersons;
CREATE DATABASE dbpersons CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbpersons;

CREATE TABLE persons (
  id INT NOT NULL AUTO_INCREMENT,
  -- la versión de la fila, incrementada en cada modificación (vea la capa DAO)
  version INT NOT NULL DEFAULT 0,
  first_name VARCHAR(30) NOT NULL,
  last_name VARCHAR(30) NOT NULL,
  age INT NOT NULL,
  PRIMARY KEY (id),
  -- dos personas no pueden tener los mismos nombre y apellido
  CONSTRAINT unq_persons_first_name_last_name UNIQUE (first_name, last_name)
) ENGINE = InnoDB;

INSERT INTO persons (first_name, last_name, age) VALUES
  ('Marie', 'Pélissier', 42),
  ('Jacques', 'Bromard', 35),
  ('Philippe', 'Jandot', 58);
  • Línea 3: el script está escrito en [UTF-8]; esto se le indica al servidor para que los acentos de los datos ([Pélissier]) permanezcan intactos;
  • Línea 5: el juego de caracteres [utf8mb4] acepta todos los caracteres (acentos, emojis, etc.). La intercalación [utf8mb4_unicode_ci] compara las cadenas sin distinguir mayúsculas ni acentos: para [MySQL], [pelissier], y [Pélissier] son iguales;
  • línea 11: un número de versión, que se incrementa cada vez que se modifica la fila (véase «bloqueo optimista», más adelante);
  • línea 17: una restricción de unicidad con nombre: la base de datos no admite dos personas con el mismo nombre y apellido.

[Doctrine] también puede crear las tablas por sí mismo, a partir de las entidades (comando [bin/console doctrine:schema:create]), o mediante migraciones: clases [PHP] que describen, paso a paso, la creación y modificación de cada tabla (biblioteca [DoctrineMigrationsBundle], comando [bin/console doctrine:migrations:migrate]). Mantenemos un script SQL, común a todas las versiones del caso de estudio, que muestra exactamente lo que contiene la base de datos.

9.1.2. Configuración

DoctrineBundle se agrega a la lista de bundles:

1
2
3
4
5
6
7
8
<?php
// config/bundles.php: los bundles de la aplicación; el DoctrineBundle integra
// Doctrine (DBAL y ORM), la biblioteca de acceso a bases de datos
return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
    Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true],
];

La conexión a la base de datos se describe en el archivo [.env] mediante una URL:

1
2
3
4
5
6
# .env: la configuración del ejemplo 28 (véase el ejemplo 01)
APP_ENV=dev
APP_SECRET=fe7d5dd3bafdb5b7ffcab097dd4e1c0c
# la conexión a la base de datos: el SGBD MySQL, en esta máquina (127.0.0.1), puerto 3306,
# la base de datos dbpersons, el usuario root sin contraseña (configuración de Laragon)
DATABASE_URL="mysql://root:@127.0.0.1:3306/dbpersons?serverVersion=8.0.32&charset=utf8mb4"

La URL [DATABASE_URL] combina todos los parámetros de conexión: el SGBD ([mysql]), el nombre de usuario y la contraseña ([root], sin nada después de [:]), el host y el puerto, y finalmente el nombre de la base de datos. Si su servidor tiene contraseña, ingrésela después de [:] ([root:secret@...]). Después de [?] siguen dos parámetros: [serverVersion], la versión del servidor ([Doctrine] adapta el SQL que genera a cada versión; para [MariaDB], por ejemplo, escribiríamos [serverVersion=10.11.2-MariaDB]), y [charset], el juego de caracteres usado para la comunicación con el servidor, que es el de la base de datos. La configuración de DoctrineBundle:

# config/packages/doctrine.yaml: la configuración del DoctrineBundle
doctrine:
    # DBAL: la conexión a la base de datos, descrita por una URL (archivo .env)
    dbal:
        url: '%env(resolve:DATABASE_URL)%'
        # las instrucciones SQL se escriben en el log (la consola) en modo de depuración
        logging: '%kernel.debug%'
    # ORM: las ENTIDADES, las clases asociadas con las tablas, son las clases de la carpeta
    # src/Entity; su mapeo a las tablas se describe mediante atributos de PHP
    orm:
        mappings:
            App:
                type: attribute
                dir: '%kernel.project_dir%/src/Entity'
                prefix: 'App\Entity'
  • línea 5: la conexión. El prefijo [resolve:] reemplaza las referencias a otros parámetros ([%...%]) en el valor de la variable, si las hay;
  • línea 7: en modo de depuración, cada comando SQL se escribe en el registro, que podemos ver en la consola (ejemplo 24). Este es también el valor por defecto;
  • líneas 10–15: las entidades son las clases de la carpeta [src/Entity], cuyo espacio de nombres comienza con [App\Entity]; su asignación a las tablas se describe mediante atributos [PHP].

Los demás archivos de configuración son los del ejemplo 21: la sesión, la protección anti-CSRF y los métodos PUT y DELETE ([framework.yaml]), así como el tema de formularios [Bootstrap] ([twig.yaml]). No hay nada más que configurar: las clases de las tres capas las crea el contenedor de [Symfony], que inyecta en cada una la capa inferior (el controlador recibe la capa de negocio, la capa de negocio recibe la capa DAO), y DoctrineBundle registra el administrador de entidades ([EntityManagerInterface]) en el contenedor.

9.1.3. La entidad Person

<?php
// src/Entity/Person.php: una fila de la tabla [persons], una ENTIDAD de Doctrine

namespace App\Entity;

use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;

// #[ORM\Entity]: la clase es una entidad; #[ORM\Table]: su tabla
#[ORM\Entity]
#[ORM\Table(name: 'persons')]
class Person
{
    // la clave primaria, generada por la base de datos (AUTO_INCREMENT); null antes de la inserción
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    // la VERSIÓN de la fila: Doctrine la incrementa en cada modificación, y solo
    // modifica la fila si su versión no ha cambiado desde que se leyó (bloqueo
    // optimista); el tipo de la columna debe indicarse explícitamente
    #[ORM\Version]
    #[ORM\Column(type: Types::INTEGER)]
    private int $version = 0;

    // las columnas: su tipo SQL se deduce del tipo de PHP (string: VARCHAR)
    #[ORM\Column(name: 'first_name', length: 30)]
    private string $firstName;

    #[ORM\Column(name: 'last_name', length: 30)]
    private string $lastName;

    #[ORM\Column]
    private int $age;

    public function __construct(string $firstName, string $lastName, int $age)
    {
        $this->edit($firstName, $lastName, $age);
    }

    public function edit(string $firstName, string $lastName, int $age): void
    {
        $this->firstName = $firstName;
        $this->lastName = $lastName;
        $this->age = $age;
    }

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getVersion(): int
    {
        return $this->version;
    }

    public function getFirstName(): string
    {
        return $this->firstName;
    }

    public function getLastName(): string
    {
        return $this->lastName;
    }

    public function getAge(): int
    {
        return $this->age;
    }
}
  • líneas 10–11: el atributo [#[ORM\Entity]] designa la clase como una entidad; [#[ORM\Table]] especifica el nombre de su tabla (de lo contrario, [Doctrine] tomaría el nombre de la clase, [person]). [ORM] es un alias del espacio de nombres [Doctrine\ORM\Mapping] (línea 7): [use ... as ORM] permite escribir los atributos de forma abreviada;
  • líneas 15–18: la clave primaria ([#[ORM\Id]]), generada por la base de datos ([#[ORM\GeneratedValue]]: derivado de [AUTO_INCREMENT], que a su vez proviene de [MySQL]). Es [null] hasta que la entidad se haya insertado;
  • líneas 23–25: la versión de la fila. El atributo [#[ORM\Version]] otorga a [Doctrine] el bloqueo optimista, descrito más adelante;
  • líneas 28–35: las columnas. Cada propiedad marcada con [#[ORM\Column]] corresponde a la columna del mismo nombre; su tipo SQL se deriva del tipo [PHP] ([string]: [VARCHAR], de longitud [length]; [int]: [INT]). A diferencia de [Eloquent], las columnas se declaran: la clase especifica exactamente lo que contiene la tabla;
  • líneas 37–72: la entidad es una clase ordinaria: un constructor, un método que modifica a la persona y los métodos de acceso. Las propiedades son privadas: una persona solo puede modificarse mediante sus métodos. [Doctrine], en cambio, lee y escribe las propiedades directamente (mediante reflexión), sin pasar por el constructor ni por los métodos.

En un proyecto estándar, el comando [bin/console make:entity] de [MakerBundle] escribe la entidad, haciendo algunas preguntas sobre sus propiedades.

9.1.4. La capa DAO

<?php
// src/Dao/PersonsDao.php: la capa DAO, consultas, sin reglas de negocio

namespace App\Dao;

use App\Entity\Person;
use Doctrine\ORM\EntityManagerInterface;

class PersonsDao
{
    // el ENTITY MANAGER de Doctrine: lee y escribe las entidades
    public function __construct(private EntityManagerInterface $em)
    {
    }

    // SELECT ... FROM persons ORDER BY last_name, first_name
    /** @return list<Person> */
    public function list(): array
    {
        return $this->em->getRepository(Person::class)->findBy([], ['lastName' => 'ASC', 'firstName' => 'ASC']);
    }

    // SELECT ... FROM persons WHERE id = ?; null si la persona no existe
    public function read(int $id): ?Person
    {
        return $this->em->find(Person::class, $id);
    }

    // una persona con los mismos nombre y apellido, distinta de [$exceptId], escrita en DQL,
    // el lenguaje de consultas de Doctrine: habla de entidades y propiedades, no
    // de tablas y columnas
    public function namesake(string $firstName, string $lastName, int $exceptId = 0): ?Person
    {
        return $this->em->createQuery(
            'SELECT p FROM App\Entity\Person p WHERE p.firstName = :firstName AND p.lastName = :lastName AND p.id <> :id')
            ->setParameters(['firstName' => $firstName, 'lastName' => $lastName, 'id' => $exceptId])
            ->setMaxResults(1)
            ->getOneOrNullResult();
    }

    // INSERT (entidad nueva) o UPDATE (entidad leída y luego modificada): persist confía
    // la entidad al manager, flush envía las instrucciones SQL necesarias a la base de datos
    public function save(Person $person): void
    {
        $this->em->persist($person);
        $this->em->flush();
    }

    // DELETE FROM persons WHERE id = ?
    public function delete(Person $person): void
    {
        $this->em->remove($person);
        $this->em->flush();
    }
}

La capa DAO contiene únicamente consultas, sin lógica de negocio. Recibe el administrador de entidades (línea 12), que utiliza la conexión de la solicitud actual y participa en la transacción abierta (si la hay) iniciada por la capa de negocio.

  • Líneas 18–21: cada entidad tiene un repositorio (repository), un objeto que la recupera de la base de datos: [getRepository]. Su método [findBy(criteria, orderBy)] devuelve la lista de entidades que cumplen los criterios (en este caso, ninguno: todas), en el orden solicitado. (Un repositorio también tiene [findAll], [findOneBy], [count]...; una aplicación puede escribir su propia clase de repositorio, con sus propias consultas: es lo que genera [make:entity].);
  • líneas 24–27: [find]: recuperación por clave primaria, o [null];
  • líneas 32–39: una consulta escrita en DQL (Doctrine Query Language), el lenguaje de consulta de [Doctrine]. Se parece a SQL, pero hace referencia a entidades y propiedades ([App\Entity\Person p], [p.firstName]), que [Doctrine] traduce a tablas y columnas. Los valores son parámetros con nombre ([:firstName]), proporcionados mediante [setParameters]: se transmiten a la base de datos por separado y nunca se copian en el texto del comando SQL, lo que hace imposible la inyección SQL. [setMaxResults(1)] limita el resultado a una fila ([LIMIT 1]); [getOneOrNullResult] devuelve la entidad encontrada, o [null];
  • Líneas 43–47: el registro. [persist] asigna una nueva entidad al administrador (una entidad leída por el administrador ya le está asignada); [flush] envía a la base de datos todos los comandos SQL necesarios: un [INSERT] para una entidad nueva, y un [UPDATE] que contiene únicamente las columnas modificadas para una entidad que fue leída y luego modificada. El administrador compara cada entidad que ha leído con su estado original: este es el seguimiento de cambios. Después de un [INSERT], [Doctrine] almacena en la entidad el identificador generado por la base de datos;
  • líneas 50–54: la eliminación: [remove], seguido de [flush], que activa [DELETE].

9.1.5. La capa de negocio

<?php
// src/Business/PersonData.php: los datos de una persona, tal como los transmite la capa web

namespace App\Business;

readonly class PersonData
{
    public function __construct(
        public string $firstName,
        public string $lastName,
        public int $age,
    ) {
    }
}

Los datos de una persona, tal como la capa web los transmite a la capa de negocio: un objeto simple, sin relación con [Symfony].

<?php
// src/Business/BusinessException.php: una regla de negocio rechaza la operación; el
// mensaje está destinado al usuario

namespace App\Business;

use RuntimeException;

class BusinessException extends RuntimeException
{
}

Una clase de excepción específica de la capa de negocio: una regla de negocio rechaza la operación, y el mensaje de la excepción está destinado al usuario. Hereda de [RuntimeException] sin añadirle nada; solo importa su nombre.

<?php
// src/Business/PersonsBusiness.php: la capa de NEGOCIO, las reglas de negocio, y solo
// ellas. Cada operación que escribe es una TRANSACCIÓN: confirmada (COMMIT) si la
// función termina normalmente, cancelada (ROLLBACK) si de ella sale una excepción

namespace App\Business;

use App\Dao\PersonsDao;
use App\Entity\Person;
use Doctrine\DBAL\Exception\UniqueConstraintViolationException;
use Doctrine\ORM\EntityManagerInterface;
use Doctrine\ORM\OptimisticLockException;

class PersonsBusiness
{
    private const NAMESAKE = 'A person already has these first and last names.';

    private const MODIFIED = 'This record has been modified meanwhile: reload it.';

    private const UNKNOWN = 'This person does not exist (anymore).';

    public function __construct(private PersonsDao $dao, private EntityManagerInterface $em)
    {
    }

    /** @return list<Person> */
    public function list(): array
    {
        return $this->dao->list();
    }

    public function read(int $id): Person
    {
        return $this->dao->read($id) ?? throw new BusinessException(self::UNKNOWN);
    }

    public function add(PersonData $data): Person
    {
        // wrapInTransaction: la función se ejecuta en una transacción
        return $this->transaction(function () use ($data) {
            // regla 1: no puede haber dos personas con los mismos nombre y apellido
            if ($this->dao->namesake($data->firstName, $data->lastName)) {
                throw new BusinessException(self::NAMESAKE);
            }
            $person = new Person($data->firstName, $data->lastName, $data->age);
            $this->dao->save($person);
            return $person;
        });
    }

    public function edit(int $id, int $version, PersonData $data): Person
    {
        return $this->transaction(function () use ($id, $version, $data) {
            $person = $this->read($id);
            // regla 2: no se modifica un registro que otra persona modificó mientras tanto
            if ($person->getVersion() !== $version) {
                throw new BusinessException(self::MODIFIED);
            }
            if ($this->dao->namesake($data->firstName, $data->lastName, $id)) {
                throw new BusinessException(self::NAMESAKE);
            }
            $person->edit($data->firstName, $data->lastName, $data->age);
            // El UPDATE "WHERE id = ... AND version = ..." de Doctrine lanza una
            // OptimisticLockException si no modificó ninguna fila (véase transaction)
            $this->dao->save($person);
            return $person;
        });
    }

    public function delete(int $id): Person
    {
        return $this->transaction(function () use ($id) {
            $person = $this->read($id);
            $this->dao->delete($person);
            return $person;
        });
    }

    // la función [$operation], ejecutada en una transacción. Dos errores de la
    // base de datos son errores de negocio: la restricción de unicidad (dos altas simultáneas),
    // y el bloqueo optimista (dos ediciones simultáneas)
    private function transaction(callable $operation): Person
    {
        try {
            return $this->em->wrapInTransaction($operation);
        } catch (UniqueConstraintViolationException $e) {
            throw new BusinessException(self::NAMESAKE, previous: $e);
        } catch (OptimisticLockException $e) {
            throw new BusinessException(self::MODIFIED, previous: $e);
        }
    }
}
  • líneas 16–20: los mensajes de las reglas de negocio;
  • líneas 32–35: una persona inexistente es un error de negocio. El operador [??] acepta una expresión [throw] en el lado derecho: si la persona es [null], se lanza la excepción;
  • líneas 37–49: regla n.º 1: no puede haber dos personas con el mismo nombre y apellido. La regla se verifica antes de escribir en la base de datos, y se lanza una excepción [BusinessException] si no se cumple. Pero esta verificación no es suficiente: dos solicitudes simultáneas podrían verificar ambas que no hay homónimos y luego proceder ambas a insertar los registros. La restricción de unicidad de la base de datos rechaza entonces el segundo [INSERT], y [Doctrine] lanza una [UniqueConstraintViolationException], que el método [transaction] transforma en la misma [BusinessException]. La base de datos es la última línea de defensa;
  • líneas 51–68: regla n.º 2: no modificar un registro que otra persona haya modificado mientras tanto. El formulario de actualización lleva la versión del registro que se leyó (en un campo oculto); si difiere de la versión actual, el registro cambió desde que se mostró. Queda el caso en que la modificación concurrente ocurre entre la lectura de la línea 54 y el guardado de la línea 65: esto lo detecta el bloqueo optimista de [Doctrine]. Para una entidad que tiene una versión, [UPDATE] verifica dos condiciones (el identificador y la versión leída) e incrementa la versión en 1; si otra consulta ha modificado la fila mientras tanto (su versión ha cambiado), el [UPDATE] no modifica ninguna fila, y [Doctrine] lanza una excepción [OptimisticLockException]. Este es el principio del bloqueo optimista: no se bloquea nada, pero se detectan las modificaciones concurrentes. ([Doctrine] lo hace por sí mismo, al igual que [Hibernate] y [SQLAlchemy]; la versión de [Laravel] de este curso tuvo que escribir la condición a mano.);
  • líneas 70–77: la eliminación marca a la persona como eliminada para el mensaje de confirmación;
  • Líneas 82–91: toda operación que escribe datos se ejecuta dentro de una transacción: [wrapInTransaction] abre la transacción, ejecuta la función, envía los cambios pendientes ([flush]), luego confirma la transacción ([COMMIT]) y devuelve el valor de la función; si la función lanza una excepción, la transacción se revierte ([ROLLBACK]): ninguno de los cambios realizados dentro de la función se conserva, y la excepción se propaga. Así, la capa de negocio determina el alcance de las transacciones: una operación de negocio, una transacción. Los dos errores de base de datos que son errores de negocio se convierten en [BusinessException]; el parámetro llamado [previous] adjunta la excepción original a la nueva para el registro. Cualquier otro error se propaga tal cual: no es un error de negocio, sino un error de programación (o una falla del sistema). Después de una excepción, [Doctrine] cierra el administrador de entidades, cuyo estado ya no es confiable: no se puede seguir usando durante la solicitud, lo que aquí no es un problema, ya que la solicitud está terminando.

El parámetro [callable] del método [transaction] hace referencia a una función arbitraria; las funciones anónimas de las líneas 40, 53 y 72 capturan, mediante [use], las variables que necesitan.

9.1.6. La capa web

La entrada del formulario se describe mediante una clase, y sus restricciones mediante atributos (ejemplo 19):

<?php
// src/Form/PersonInput.php: los campos del formulario y sus restricciones (véase el ejemplo 19)

namespace App\Form;

use App\Entity\Person;
use App\Business\PersonData;
use Symfony\Component\Validator\Constraints as Assert;

class PersonInput
{
    #[Assert\NotBlank(message: 'The first name is required.')]
    #[Assert\Length(max: 30, maxMessage: '30 characters at most.')]
    public ?string $firstName = null;

    #[Assert\NotBlank(message: 'The last name is required.')]
    #[Assert\Length(max: 30, maxMessage: '30 characters at most.')]
    public ?string $lastName = null;

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

    // la versión del registro, llevada por un campo oculto (solo en la edición)
    public ?int $version = null;

    // la entrada, rellenada previamente con una persona existente
    public static function from(Person $p): self
    {
        $input = new self();
        $input->firstName = $p->getFirstName();
        $input->lastName = $p->getLastName();
        $input->age = $p->getAge();
        $input->version = $p->getVersion();
        return $input;
    }

    // los datos validados, para la capa de negocio
    public function data(): PersonData
    {
        return new PersonData(trim($this->firstName), trim($this->lastName), $this->age);
    }
}
  • líneas 12–22: las restricciones, con mensajes en inglés;
  • línea 25: la versión del registro, transportada por un campo oculto (solo en modo de edición);
  • líneas 28–36: una entrada prellenada con una persona existente, para el formulario de actualización;
  • líneas 39–42: los datos validados, en el formato esperado por la capa de negocio.

Podríamos haber vinculado el formulario directamente a la entidad [Person] (opción [data_class], ejemplo 19) y colocar en ella las restricciones: esto es habitual con [Symfony]. Sin embargo, el formulario modificaría entonces la entidad antes de que la capa de negocio verificara sus reglas, y se pasaría una entidad no válida al administrador de entidades. Una clase de entrada separada mantiene distintas las capas: la capa web transmite a la capa de negocio únicamente datos validados.

<?php
// src/Form/PersonType.php: el formulario de una persona (véase el ejemplo 18)

namespace App\Form;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\HiddenType;
use Symfony\Component\Form\Extension\Core\Type\IntegerType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

class PersonType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('firstName', TextType::class, ['label' => 'First name', 'attr' => ['maxlength' => 30]])
            ->add('lastName', TextType::class, ['label' => 'Last name', 'attr' => ['maxlength' => 30]])
            ->add('age', IntegerType::class, ['label' => 'Age', 'attr' => ['min' => 0, 'max' => 150],
                'invalid_message' => 'The age must be an integer.']);
        // la versión: un campo oculto, solo en el formulario de edición
        if ($options['edit']) {
            $builder->add('version', HiddenType::class);
        }
    }

    // las opciones del formulario: la clase de los datos y una opción propia
    public function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->setDefaults(['data_class' => PersonInput::class, 'edit' => false]);
    }
}
  • líneas 20–21: un campo de tipo entero; [invalid_message] es el mensaje que se muestra cuando la entrada no se puede convertir en un entero;
  • líneas 23–25: el campo oculto de versión, solo en el formulario de actualización, según la opción [edit];
  • líneas 29–32: [configureOptions] declara las opciones del formulario y sus valores por defecto: la clase de datos y una opción personalizada, [edit].
<?php
// src/Controller/PersonsController.php: la capa WEB; solo conoce la capa de negocio

namespace App\Controller;

use App\Form\PersonInput;
use App\Form\PersonType;
use App\Business\BusinessException;
use App\Business\PersonsBusiness;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
use Symfony\Component\Routing\Attribute\Route;

// name: un prefijo para el nombre de todas las rutas de la clase (persons_list...)
#[Route(name: 'persons_')]
class PersonsController extends AbstractController
{
    public function __construct(private PersonsBusiness $business)
    {
    }

    #[Route('/', name: 'home', methods: ['GET'])]
    public function home(): Response
    {
        return $this->redirectToRoute('persons_list');
    }

    #[Route('/persons', name: 'list', methods: ['GET'])]
    public function list(): Response
    {
        return $this->render('persons/list.html.twig', ['persons' => $this->business->list()]);
    }

    // GET: el formulario vacío; POST: el formulario enviado
    #[Route('/persons/add', name: 'add', methods: ['GET', 'POST'])]
    public function add(Request $request): Response
    {
        $input = new PersonInput();
        $form = $this->createForm(PersonType::class, $input);
        $form->handleRequest($request);
        if ($form->isSubmitted() && $form->isValid()) {
            try {
                $p = $this->business->add($input->data());
                $this->addFlash('success', "{$p->getFirstName()} {$p->getLastName()} has been added.");
                return $this->redirectToRoute('persons_list');
            } catch (BusinessException $e) {
                // una regla de negocio lo rechaza: el formulario se muestra de nuevo, con la
                // entrada y el mensaje, al final de la página
                return $this->formPage('Add a person', $form, $e->getMessage());
            }
        }
        return $this->formPage('Add a person', $form);
    }

    // GET: el formulario de edición, rellenado previamente
    #[Route('/persons/{id<\d+>}/edit', name: 'edit_form', methods: ['GET'])]
    public function editForm(int $id): Response
    {
        try {
            $p = $this->business->read($id);
        } catch (BusinessException $e) {
            $this->addFlash('error', $e->getMessage());
            return $this->redirectToRoute('persons_list');
        }
        return $this->formPage('Edit a person', $this->editFormFor($id, PersonInput::from($p)));
    }

    // PUT: el formulario de edición enviado
    #[Route('/persons/{id<\d+>}', name: 'edit', methods: ['PUT'])]
    public function edit(Request $request, int $id): Response
    {
        $input = new PersonInput();
        $form = $this->editFormFor($id, $input);
        $form->handleRequest($request);
        if ($form->isSubmitted() && $form->isValid()) {
            try {
                $p = $this->business->edit($id, (int) $input->version, $input->data());
                $this->addFlash('success', "{$p->getFirstName()} {$p->getLastName()} has been edited.");
                return $this->redirectToRoute('persons_list');
            } catch (BusinessException $e) {
                return $this->formPage('Edit a person', $form, $e->getMessage());
            }
        }
        return $this->formPage('Edit a person', $form);
    }

    #[Route('/persons/{id<\d+>}', name: 'delete', methods: ['DELETE'])]
    public function delete(Request $request, int $id): Response
    {
        if (! $this->isCsrfTokenValid("delete-person-$id", $request->request->getString('_token'))) {
            throw new AccessDeniedHttpException('invalid anti-CSRF token');
        }
        try {
            $p = $this->business->delete($id);
            $this->addFlash('success', "{$p->getFirstName()} {$p->getLastName()} has been deleted.");
        } catch (BusinessException $e) {
            // no hay formulario que mostrar de nuevo: el error también viaja como mensaje flash
            $this->addFlash('error', $e->getMessage());
        }
        return $this->redirectToRoute('persons_list');
    }

    // el formulario de edición: enviado con el método PUT, a la URL /persons/{id}
    private function editFormFor(int $id, PersonInput $input): FormInterface
    {
        return $this->createForm(PersonType::class, $input, ['edit' => true,
            'method' => 'PUT', 'action' => $this->generateUrl('persons_edit', ['id' => $id])]);
    }

    private function formPage(string $title, FormInterface $form, ?string $error = null): Response
    {
        // un error de negocio: el código 422, igual que un formulario inválido (véase el ejemplo 19)
        return $this->render('persons/form.html.twig',
            ['title' => $title, 'form' => $form, 'error' => $error],
            new Response(status: $error ? 422 : 200));
    }
}
  • línea 18: el atributo de clase [#[Route]] antepone un prefijo solo a los nombres de ruta aquí: la ruta llamada [list] se llama en realidad [persons_list];
  • línea 21: la capa de negocio, la única capa que conoce el controlador;
  • líneas 38–56: el proceso, en tres pasos: validación del formulario (errores de entrada, ejemplo 19); la llamada a la capa de negocio (reglas de negocio); y luego el patrón PRG, con un mensaje flash de éxito (ejemplo 20). Una [BusinessException] vuelve a mostrar el formulario, junto con los datos ingresados y el mensaje de la excepción, que la plantilla mostrará en la parte inferior de la página. Los errores de entrada y los errores de lógica de negocio se gestionan así de la misma manera;
  • líneas 59–69: el formulario de edición, prellenado con la persona recuperada. Si la persona no existe, el usuario es redirigido a la lista con un mensaje flash de error;
  • líneas 72–88: la actualización, que sigue el mismo patrón que la operación de adición;
  • líneas 90–104: la eliminación, protegida por un token CSRF único para cada persona (ejemplo 21). No hay formulario que volver a mostrar: cualquier error también se transmite en un mensaje flash, [error];
  • líneas 107–111: el formulario de edición se envía con el método PUT (opción [method]: [form_start] agrega entonces el campo oculto [_method], ejemplo 21), a la URL [/persons/{id}] (opción [action]);
  • líneas 113–119: la página del formulario. Un error de negocio se devuelve con el código 422, que indica un formulario no válido.

La capa web no contiene SQL ni reglas de negocio: traduce la solicitud en una llamada a la capa de negocio y el resultado en una página.

Las vistas:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Persons</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">
    {# el mensaje de éxito (mensaje flash [success]): en la parte superior #}
    {% for message in app.flashes('success') %}
      <div class="alert alert-success" role="status">{{ message }}</div>
    {% endfor %}
    <main>
      {% block content %}{% endblock %}
    </main>
    {# los errores: en la parte inferior; un mensaje flash [error], o la variable [error] de la vista #}
    {% for message in app.flashes('error') %}
      <div class="error-area" role="alert">{{ message }}</div>
    {% endfor %}
    {% if error is defined and error %}
      <div class="error-area" role="alert">{{ error }}</div>
    {% endif %}
  </div>
  {% include 'fragments/confirmation.html.twig' %}
  <script src="{{ asset('js/app.js') }}"></script>
</body>
</html>
  • líneas 13–15: el mensaje de éxito en la parte superior de la página (ejemplo 20);
  • Líneas 20–25: los errores; en la parte inferior de la página: un mensaje flash (después de una redirección), o la variable de vista [error] (formulario vuelto a mostrar). La prueba [is defined] evita un error en las páginas que no tienen esta variable.
{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">Persons</h1>
  <table class="table align-middle">
    <thead><tr><th>First name</th><th>Last name</th><th>Age</th><th></th></tr></thead>
    <tbody>
      {% for p in persons %}
        <tr>
          <td>{{ p.firstName }}</td>
          <td>{{ p.lastName }}</td>
          <td>{{ p.age }}</td>
          <td class="text-end">
            <a class="btn btn-sm btn-outline-primary" href="{{ path('persons_edit_form', {id: p.id}) }}">Edit</a>
            <form method="post" class="d-inline" action="{{ path('persons_delete', {id: p.id}) }}"
                  data-confirmation="Delete {{ p.firstName }} {{ p.lastName }}?">
              <input type="hidden" name="_method" value="DELETE">
              <input type="hidden" name="_token" value="{{ csrf_token('delete-person-' ~ p.id) }}">
              <button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
            </form>
          </td>
        </tr>
      {% endfor %}
    </tbody>
  </table>
  <a class="btn btn-primary" href="{{ path('persons_add') }}">Add a person</a>
{% endblock %}

La lista incluye los enlaces y botones del ejemplo 21, junto con su ventana de confirmación (los archivos [fragments/confirmation.html.twig] y [public/js/app.js] son los del ejemplo 21). Las propiedades [p.firstName], [p.lastName]... se leen mediante los métodos de acceso [getFirstName()], [getLastName()]...: [Twig] los encuentra por sí solo (ejemplo 13).

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

{% block content %}
  <h1 class="h3">{{ title }}</h1>
  {# novalidate: la validación es la del servidor (ver el ejemplo 19); form_start
     también escribe el campo oculto _method de un formulario PUT #}
  {{ form_start(form, {attr: {novalidate: 'novalidate'}}) }}
    {{ form_widget(form) }}
    <button class="btn btn-primary" type="submit">Save</button>
    <a class="btn btn-link" href="{{ path('persons_list') }}">Cancel</a>
  {{ form_end(form) }}
{% endblock %}

Una vista utilizada tanto para agregar como para modificar registros. [form_widget] muestra todos los campos del formulario, incluido el campo oculto de versión y el token anti-CSRF.

9.1.7. Ejecución

La lista de personas:

Image

Un formulario de adición llenado incorrectamente: la capa web detecta los errores de entrada.

Image

Un homónimo: la entrada es correcta, pero la capa de negocio rechaza la adición. Como la comparación la realiza la base de datos, esta ignora tanto las mayúsculas como los acentos: [marie pelissier] es un homónimo de [Marie Pélissier].

Image

Una adición exitosa:

Image

Para probar la regla n.º 2, abramos el mismo registro en dos pestañas. En la primera pestaña, cambiemos la edad y guardemos. En la segunda pestaña, que todavía muestra la versión anterior, modifiquemos también el registro:

Image

La eliminación, con su confirmación:

Image

Image

9.1.8. Los comandos SQL

Sigamos en la consola los comandos SQL de una modificación (se han eliminado las fechas y las líneas del servidor de desarrollo). La visualización del formulario de modificación de la persona n.º 1:

1
2
3
[info] Connecting with parameters [array]
[debug] Executing statement: SELECT t0.id AS id_1, t0.version AS version_2, t0.first_name AS first_name_3, t0.last_name AS last_name_4, t0.age AS age_5 FROM persons t0 WHERE t0.id = ? (parameters: [array], types: [array])
[info] Disconnecting

Una conexión, una lectura por clave primaria (cuyo valor se pasa como parámetro, [?]), seguida de una desconexión al final de la solicitud. No hay transacción: una lectura aislada no la requiere. [Doctrine] asigna un alias a cada tabla ([t0]) y a cada columna ([id_1]). Los valores de los parámetros son un arreglo, que el registro mínimo de [Symfony] no muestra ([[array]]); [Monolog], o la barra de depuración de [Symfony] ([WebProfilerBundle], instalado mediante [composer require --dev profiler]), sí los mostraría. La actualización del registro maestro, con una nueva edad:

1
2
3
4
5
6
7
8
[debug] Beginning transaction
[debug] Executing statement: SELECT t0.id AS id_1, t0.version AS version_2, t0.first_name AS first_name_3, t0.last_name AS last_name_4, t0.age AS age_5 FROM persons t0 WHERE t0.id = ? (parameters: [array], types: [array])
[debug] Executing statement: SELECT p0_.id AS id_0, p0_.version AS version_1, p0_.first_name AS first_name_2, p0_.last_name AS last_name_3, p0_.age AS age_4 FROM persons p0_ WHERE p0_.first_name = ? AND p0_.last_name = ? AND p0_.id <> ? LIMIT 1 (parameters: [array], types: [array])
[debug] Executing statement: SAVEPOINT DOCTRINE_2
[debug] Executing statement: UPDATE persons SET age = ?, version = version + 1 WHERE id = ? AND version = ? (parameters: [array], types: [array])
[debug] Executing statement: SELECT version FROM persons WHERE id = ? (parameters: [array], types: [array])
[debug] Executing statement: RELEASE SAVEPOINT DOCTRINE_2
[debug] Committing transaction

En una sola transacción, vemos: la lectura del registro, la búsqueda de un homónimo (la consulta DQL, traducida a SQL), seguida de [UPDATE]. Esta transacción modifica únicamente la columna que ha cambiado ([age]), incrementa el número de versión y establece la condición del bloqueo optimista ([AND version = ?]). [Doctrine] vuelve entonces a leer la nueva versión para guardarla en la entidad. [flush] abre una transacción por sí mismo; como ya existe una (la transacción de la capa de negocio), simplemente crea un punto de guardado ([SAVEPOINT]), una transacción anidada que se confirma ([RELEASE]) al final de [flush]. Ahora enviemos el mismo formulario por segunda vez, usando todavía la versión anterior:

1
2
3
[debug] Beginning transaction
[debug] Executing statement: SELECT t0.id AS id_1, t0.version AS version_2, t0.first_name AS first_name_3, t0.last_name AS last_name_4, t0.age AS age_5 FROM persons t0 WHERE t0.id = ? (parameters: [array], types: [array])
[debug] Rolling back transaction

La versión leída no es la del formulario: la capa de negocio lanzó una [BusinessException], que revirtió la transacción ([ROLLBACK]), y la página muestra «Este registro ha sido modificado entretanto: vuelva a cargarlo». Del mismo modo, la adición de un homónimo se detiene tras la búsqueda del homónimo, sin un [INSERT].