11. Caso de estudio: la aplicación RdvMedecins
11.1. El problema
La aplicación RdvMedecins gestiona las citas de un consultorio médico. Cada médico tiene franjas horarias (por ejemplo, de 8:00 a 12:00 en intervalos de 20 minutos); una cita consiste en un día, una franja horaria y un cliente (un paciente). Este es el port exacto a [Symfony] de la aplicación [Laravel] de la lección anterior (que a su vez se portó desde las versiones [Flask], [Spring MVC] y [ASP.NET Core MVC]): la misma base de datos, las mismas reglas de negocio, las mismas páginas, las mismas URL, los mismos textos. Las páginas HTML las genera el servidor mediante vistas [Twig]; el acceso a la base de datos lo gestiona [Doctrine].
Tres roles de usuario comparten la aplicación:
ADMIN | el administrador ([admin]) | ver las agendas, reservar y cancelar citas para cualquier paciente; gestionar (listar, agregar, editar, eliminar) médicos y clientes |
DOCTOR | Médicos | Ver las agendas, reservar citas y cancelar citas para cualquier paciente |
USER | clientes (pacientes) | ver las agendas sin ver los nombres de los demás pacientes; reservar una cita para sí mismos; cancelar su cita; gestionar su cuenta; crear una cuenta |
Principales reglas de gestión:
- no se admiten citas en el pasado;
- una franja horaria se reserva una sola vez por día;
- un paciente solo puede tener una cita próxima a la vez;
- dos médicos (o dos clientes) no pueden tener el mismo nombre y apellido, y un inicio de sesión pertenece a una sola cuenta;
- un médico con citas no puede ser eliminado; un cliente se elimina junto con sus citas;
- la página de inicio de sesión está protegida contra bots (CAPTCHA, intentos limitados), y la creación de una cuenta de paciente requiere resolver primero el CAPTCHA de esa página.
11.2. Uso de la aplicación
11.2.1. La página de inicio de sesión

La página presenta dos botones: Iniciar sesión y Crear una cuenta de paciente. Ambos requieren ingresar los caracteres que se muestran en la imagen. Los botones FR / EN cambian el idioma:

Un error (en este caso, un CAPTCHA ingresado incorrectamente) se muestra en la parte inferior de la página sobre un fondo rosa claro:

11.2.2. El calendario, tal como lo ven el administrador y los médicos
Una vez iniciada la sesión, el administrador es dirigido a la página del calendario. Selecciona un médico y un día:


Cada franja horaria está disponible (botón Reservar) u ocupada (nombre del paciente, botón Cancelar). Al hacer clic en Reservar se abre una ventana que solicita los datos del paciente. Esta ventana la genera el servidor, al igual que el resto de la página: la URL contiene ahora el parámetro [book=4], que es el número de la franja horaria seleccionada:

Después de la reserva, un mensaje confirma la cita:

Al hacer clic en «Cancelar» se solicita una confirmación (aquí por parte de la Dra. Pélissier, cuya barra de navegación no incluye los menús de administración):

11.2.3. El portal del paciente
Un paciente (rol USER) llega a «Mi espacio»: su próxima cita, que puede cancelar, y enlaces para gestionar su cuenta y ver su calendario. Aquí todavía no tiene una cita:

En el calendario no ve los nombres de los demás pacientes; estos se reemplazan por «Reservado»: este nombre ni siquiera aparece en el código fuente de la página. Puede reservar una franja horaria disponible:

La ventana de reserva no le pide seleccionar un paciente: reserva la cita para sí mismo.


Su panel muestra ahora su próxima cita, que puede cancelar:

Como tiene una cita próxima, no puede programar otra: el botón «Reservar» no se muestra, y en el calendario de otro día o de otro médico, un mensaje explica el motivo:

Gestión de la cuenta: editar sus datos, cambiar su contraseña o eliminar su cuenta (y sus citas). Se requiere la contraseña actual para cualquier cambio:

Un paciente que intenta abrir una página reservada al administrador (aquí, [/doctors], escrita manualmente) recibe una página de error:

11.2.4. Gestión de médicos y pacientes
El administrador tiene dos menús adicionales, Médicos y Pacientes:


El formulario para agregar un médico, enviado con errores:

Un nombre igual al de un médico existente es rechazado, incluso si se escribe en minúsculas y con acento (la propia base de datos compara los nombres sin distinguir entre mayúsculas y minúsculas ni acentos; véase el ejemplo 28):

La eliminación de un paciente requiere confirmación:

11.2.5. Creación de una cuenta de paciente
Desde la página de inicio de sesión, el botón «Crear una cuenta de paciente» solo abre el formulario si el CAPTCHA se ha ingresado correctamente:

Una vez creada la cuenta, el usuario es redirigido a la página de inicio de sesión con su nombre de usuario ya completado:

11.2.6. Cierre de sesión
El token de inicio de sesión es válido durante dos horas. Transcurrido ese tiempo (o si el token ha sido manipulado), la página solicitada redirige a la página de inicio de sesión con el siguiente mensaje:

11.3. Instalación y ejecución
La aplicación se encuentra en la carpeta [rdvmedecins2-symfony], junto a la carpeta [examples]. Es un proyecto independiente, con sus propios archivos [composer.json] y [.env] , y su propia carpeta [vendor]. El archivo [README.md] de la carpeta contiene todo lo que sigue. La introducción de este documento ya describió la instalación de [PHP] y de [Composer]; aquí la ampliaremos.
11.3.1. Software necesario
Solo se necesitan tres programas:
- [PHP] 8.4 o posterior, con las extensiones [pdo_mysql] y [intl] ([Symfony] 8 requiere [PHP] 8.4, y la aplicación utiliza características introducidas en esa versión, como [array_find]). Verifique la instalación en una terminal:
El segundo comando enumera las extensiones: [pdo_mysql] e [intl] deben aparecer en la lista;
- [Composer], el administrador de bibliotecas de [PHP] (véanse los apéndices);
- un servidor [MySQL] 8 , por ejemplo, el de [Laragon] en [Windows] (véanse los apéndices). [MariaDB] también es adecuado.
El editor recomendado es [Visual Studio Code], con las extensiones [PHP Intelephense] y [Twig Language 2] (véanse los apéndices); sin embargo, todo se puede hacer desde la línea de comandos.
11.3.2. Instalación de las bibliotecas
La carpeta [vendor] no se proporciona: créela de una vez por todas en una ventana de terminal abierta en la carpeta [rdvmedecins2-symfony] (debe estar conectado a Internet):
[Composer] lee el archivo [composer.json] (que se comenta más adelante), descarga [Symfony], [Doctrine], [Twig], [firebase/php-jwt] y las bibliotecas de las que dependen, y genera el cargador de clases [vendor/autoload.php], así como el archivo [vendor/autoload_runtime.php] para el componente [Runtime] (que se comenta más adelante).
11.3.3. Creación de la base de datos
La base de datos [dbrdvmedecins2] se crea mediante el script [database/dbrdvmedecins2.sql]. Con [Laragon], abra la herramienta [HeidiSQL] (botón Base de datos) y luego ejecute el script desde el menú Archivo / Ejecutar SQL. En la línea de comandos, en la carpeta de la aplicación:
| mysql -u root -p < database/dbrdvmedecins2.sql
|
La opción [-p] solicita la contraseña de [root]; omítala si la cuenta no tiene contraseña (como ocurre con [Laragon]). Es la misma base de datos que en las demás versiones de la aplicación: si ya existe, este paso es opcional. El script puede ejecutarse en cualquier momento para volver a los datos originales.
11.3.4. Configuración del acceso a la base de datos
Toda la configuración de la instalación está contenida en el archivo [.env] (que se comenta más adelante). Por defecto, la aplicación se conecta a [MySQL] en [127.0.0.1], puerto 3306, con el usuario [root] sin contraseña: esta es la configuración por defecto de [Laragon]. Si su cuenta [root] tiene contraseña, ingrésela en este archivo, en la línea de la URL [DATABASE_URL], después de [root:]. Una variable de entorno del sistema tiene prioridad sobre el archivo (ejemplo 25): esto permite indicar la URL de la base de datos sin escribirla en un archivo del proyecto.
11.3.5. Inicio de la aplicación
En una ventana de terminal abierta en la carpeta [rdvmedecins2-symfony]:
| php -S localhost:8081 -t public
|
| [Sun Sep 27 18:40:12 2026] PHP 8.4.21 Development Server (http://localhost:8081) started
|
A continuación, abra la URL [http://localhost:8081] en un navegador y detenga la aplicación con [Ctrl-C]. El puerto 8081 permite ejecutar al mismo tiempo un ejemplo del curso (puerto 8000). La herramienta de línea de comandos [symfony] (véanse los apéndices) ofrece un servidor más completo que también puede servir la aplicación en HTTPS: [symfony server:start --port=8081].
11.3.6. Cuentas de demostración
La contraseña de cada cuenta es su nombre de usuario; también debe ingresar los caracteres de la imagen, en mayúsculas o minúsculas:
[admin] | ADMIN (el administrador) |
[pelissier], [tatou], [dupont] | DOCTOR (los médicos) |
[martin], [durand], [bistrou], [german] | USER (los pacientes) |
Una guía para explorar la aplicación:
- [admin]: agenda, de la Sra. Marie PELISSIER; hoy: una franja horaria ya está reservada por la Sra. Brigitte BISTROU. Reservar una franja para el Sr. Jean MARTIN y luego intentar reservarle una segunda cita (rechazada). Menús Médicos y Pacientes: agregar, editar, eliminar (la Dra. PELISSIER, que tiene citas, no puede ser eliminada);
- [pelissier]: su agenda del día se muestra directamente; la dirección [/doctors], ingresada manualmente, devuelve una página de error 403;
- [martin]: Mi espacio, su cita, el calendario donde los demás pacientes aparecen como «Reservado»; Gestionar mi cuenta;
- página de inicio de sesión: Crear una cuenta de paciente y luego iniciar sesión con la nueva cuenta;
- Botones FR / EN: toda la interfaz cambia de idioma, incluidas las fechas.
11.3.7. Modo de desarrollo
El archivo [.env] proporcionado configura la aplicación para desarrollo ([APP_ENV=dev]):
- La consola del servidor muestra el registro de [Symfony] (ejemplo 24): la ruta seleccionada, los pasos de seguridad y cada comando SQL enviado a la base de datos (ejemplo 28). Por ejemplo, para mostrar un calendario (líneas abreviadas):
| [info] Matched route "schedule".
[debug] Checking for authenticator support.
[debug] Checking support on authenticator.
[info] Authenticator successful!
[debug] Authenticator set no success response: request continues.
[info] Connecting with parameters [array]
[debug] Executing statement: SELECT d0_.id AS id_0, ..., u1_.login AS login_7, ... FROM doctors d0_ INNER JOIN users u1_ ON d0_.`user` = u1_.`id` WHERE d0_.id = ? (parameters: [array], types: [array])
[debug] Executing statement: SELECT a0_.id AS id_0, ... FROM appointments a0_ INNER JOIN clients c1_ ON a0_.client_id = c1_.id INNER JOIN slots s2_ ON a0_.slot_id = s2_.id WHERE a0_.day = ? AND s2_.doctor_id = ? (parameters: [array], types: [array])
[debug] Executing statement: SELECT s0_.id AS id_0, ... FROM slots s0_ WHERE s0_.doctor_id = ? ORDER BY s0_.start_hour ASC, s0_.start_minute ASC (parameters: [array], types: [array])
127.0.0.1:55220 [200]: GET /schedule?doctorId=1&day=2026-09-27
[info] Disconnecting
|
Aquí vemos el enrutamiento, el autenticador y luego tres consultas: el médico y su cuenta, las citas del día y sus pacientes, y las franjas horarias disponibles del médico. En cambio, la lista de médicos del menú desplegable no se lee; proviene de la caché (que se comenta más adelante);
- una excepción inesperada muestra la [Symfony] página de depuración (ejemplo 03), con el mensaje de la excepción y la pila de llamadas. En producción, la aplicación muestra en su lugar su propia página de error 500;
- no hay nada que reiniciar después de un cambio: cada solicitud vuelve a leer los archivos [PHP] (ejemplo 01), y, en modo [dev], [Symfony] reconstruye su propia caché (el contenedor, las rutas y las vistas compiladas) cuando un archivo ha cambiado.
El [Xdebug] depurador también permite recorrer la aplicación paso a paso desde [Visual Studio Code] (extensión [PHP Debug]): es una extensión de [PHP], que debe instalarse por separado (véase xdebug.org). La barra de depuración de [Symfony] ([WebProfilerBundle], [composer require --dev symfony/web-profiler-bundle]) muestra los detalles de la solicitud en la parte inferior de cada página: la ruta, el usuario, los comandos SQL y sus parámetros, las traducciones, los tiempos de ejecución...
11.3.8. Un servidor de producción
El servidor de desarrollo de [PHP] no está pensado para producción. En producción, la aplicación la sirve un servidor web ([nginx], [Apache]), que reenvía las solicitudes a [PHP-FPM], un administrador de procesos ([PHP]). La raíz del sitio es la carpeta [public]: solo sus archivos son accesibles desde el navegador; la carpeta [var] debe tener permisos de escritura para el servidor. En el archivo [.env] se debe especificar el modo de producción, cambiar las claves secretas y declarar que el sitio se sirve desde HTTPS:
| APP_ENV=prod
APP_SECRET=<a long random string>
JWT_SECRET=<another long random string>
COOKIE_SECURE=1
|
Se puede obtener una cadena aleatoria adecuada con [PHP] mismo: [php -r "echo bin2hex(random_bytes(32));"]. Luego, la aplicación se prepara con dos comandos:
| composer install --no-dev --optimize-autoloader
php bin/console cache:clear
|
El segundo comando genera la caché de producción (el contenedor compilado, las rutas, las vistas compiladas, etc.): en modo [prod], [Symfony] ya no verifica si los archivos han cambiado, lo que es más rápido; por lo tanto, debe volver a ejecutarse después de cada modificación. El comando [composer dump-env prod] también convierte el archivo [.env] en un archivo [PHP] ([.env.local.php]), que se lee más rápidamente.
11.3.9. Problemas comunes
Una aplicación [PHP] no «arranca»: cada solicitud reconstruye la aplicación (ejemplo 01). Por lo tanto, una base de datos inaccesible no impide que el servidor arranque: el error aparece en la primera página que consulta la base de datos (la página de inicio de sesión no consulta la base de datos; el proceso de conexión sí). En modo [dev], el error se muestra en la página de depuración de [Symfony]; en todos los casos, se registra en el archivo de registro, que el servidor de desarrollo muestra en la consola. Por ejemplo, con una base de datos que no existe:
| [critical] Uncaught PHP Exception Doctrine\DBAL\Exception\ConnectionException: "An exception occurred in the driver: SQLSTATE[HY000] [1049] Unknown database 'dbunknown'" at ExceptionConverter.php line 91
|
Los mensajes más comunes:
[Failed opening required '.../vendor/autoload_runtime.php'] | El comando [composer install] no se ejecutó |
[Your Composer dependencies require a PHP version ">= 8.4.0"] | La versión de [PHP] es anterior a la 8.4 |
[could not find driver] | La extensión [pdo_mysql] de [PHP] no está habilitada (archivo [php.ini], o menú PHP / Extensiones en [Laragon]) |
[SQLSTATE[HY000] [2002] Connection refused] | [MySQL] no se ha iniciado, o no está escuchando en [127.0.0.1:3306] |
[SQLSTATE[HY000] [1045] Access denied for user 'root'@'localhost'] | La contraseña de [MySQL] debe ingresarse en [DATABASE_URL] (véase «Configuración del acceso a la base de datos») |
[SQLSTATE[HY000] [1049] Unknown database 'dbrdvmedecins2'] | El script [database/dbrdvmedecins2.sql] no se ejecutó |
[JWT_SECRET must be at least 32 characters long (see .env).] | La clave secreta de los tokens es demasiado corta en [.env] |
[Failed to listen on localhost:8081 (reason: Address already in use)] | El puerto 8081 ya está en uso (¿se está ejecutando otra versión de la aplicación?): deténgala o elija otro puerto |
11.4. Arquitectura de la aplicación

- El navegador envía sus solicitudes al servidor ([php -S], o [nginx] + [PHP-FPM]), que las reenvía a [Symfony] mediante el archivo [public/index.php]. El núcleo de [Symfony] publica eventos relacionados con el procesamiento de la solicitud (véase el capítulo sobre el ciclo de vida), a los que responden los listeners: el idioma de la solicitud ([SetLanguage]), el enrutamiento, la sesión y luego el firewall del componente de seguridad: el usuario se identifica a partir del token JWT de su cookie ([TokenAuthenticator]), y las reglas de [access_control] deniegan el acceso a las páginas protegidas a los visitantes no autorizados. Los errores dan lugar a páginas HTML ([ErrorPage]);
- [Controller]: los controladores de la capa web. Todos pasan por un único objeto, [ApplicationModel] (carpeta [Web]), que almacena en caché las listas de médicos y clientes y reenvía las demás solicitudes a la capa de negocio; [Form]: los formularios y sus restricciones; [Views]: las plantillas de vista;
- [Security]: los tokens, JWT, el autenticador, el CAPTCHA, el límite de intentos y el pase de creación de cuenta;
- [Web]: lo que tienen en común los controladores: la caché y la fachada [ApplicationModel], la clase padre de los controladores, los mensajes flash y algunas utilidades;
- [Business]: las reglas de negocio y las transacciones;
- [Dao]: la capa DAO, una clase por tabla;
- [Entity]: las entidades [Doctrine], que la capa DAO lee y escribe en la base de datos; [Domain]: los objetos del calendario, calculados por la capa de negocio;
- [templates]: las vistas [Twig], que generan las páginas HTML; [translations]: los diccionarios; [public]: la hoja de estilos, el script de la página y [Bootstrap];
- la carpeta [config] y el archivo [.env]: la configuración, que lo une todo.
La carpeta de la aplicación (sin [vendor] ni [var]):
| rdvmedecins2-symfony/
├── bin/
│ └── console
├── composer.json
├── config/
│ ├── bundles.php
│ ├── packages/
│ │ ├── doctrine.yaml
│ │ ├── framework.yaml
│ │ ├── security.yaml
│ │ └── twig.yaml
│ ├── routes.yaml
│ └── services.yaml
├── database/
│ ├── dbrdvmedecins2.sql
│ └── README.md
├── .env
├── public/
│ ├── css/
│ │ └── styles.css
│ ├── index.php
│ ├── js/
│ │ └── app.js
│ └── lib/
│ └── bootstrap/
├── README.md
├── src/
│ ├── Controller/
│ │ ├── ScheduleController.php
│ │ ├── AuthController.php
│ │ ├── ClientsController.php
│ │ ├── PatientAreaController.php
│ │ ├── RegistrationController.php
│ │ ├── LanguageController.php
│ │ ├── DoctorsController.php
│ │ ├── PersonsController.php
│ │ └── README.md
│ ├── Dao/
│ │ ├── ClientDao.php
│ │ ├── SlotDao.php
│ │ ├── DoctorDao.php
│ │ ├── PersonDao.php
│ │ ├── README.md
│ │ ├── AppointmentDao.php
│ │ └── UserDao.php
│ ├── Domain/
│ │ ├── DoctorDaySchedule.php
│ │ ├── DoctorDaySlot.php
│ │ └── README.md
│ ├── Entity/
│ │ ├── Client.php
│ │ ├── Slot.php
│ │ ├── Doctor.php
│ │ ├── Person.php
│ │ ├── README.md
│ │ ├── Role.php
│ │ ├── Appointment.php
│ │ └── User.php
│ ├── EventListener/
│ │ ├── SetLanguage.php
│ │ ├── ErrorPage.php
│ │ ├── README.md
│ │ └── CheckRegistrationPass.php
│ ├── Form/
│ │ ├── PersonFieldsType.php
│ │ ├── RegistrationType.php
│ │ ├── MyAccountType.php
│ │ ├── PersonType.php
│ │ └── README.md
│ ├── Kernel.php
│ ├── Business/
│ │ ├── Dates.php
│ │ ├── Descriptor.php
│ │ ├── PersonData.php
│ │ ├── Business.php
│ │ ├── BusinessException.php
│ │ ├── BusinessService.php
│ │ └── README.md
│ ├── Security/
│ │ ├── AuthService.php
│ │ ├── Captcha.php
│ │ ├── CaptchaService.php
│ │ ├── CaptchaDrawing.php
│ │ ├── TokenAuthenticator.php
│ │ ├── AttemptLimiter.php
│ │ ├── RegistrationPass.php
│ │ ├── RegistrationPassRequired.php
│ │ ├── README.md
│ │ ├── InvalidSession.php
│ │ └── ConnectedUser.php
│ ├── Twig/
│ │ └── ViewsExtension.php
│ ├── Views/
│ │ ├── ScheduleView.php
│ │ ├── PersonKeys.php
│ │ ├── ScheduleRow.php
│ │ ├── OptionView.php
│ │ ├── README.md
│ │ ├── AppointmentView.php
│ │ └── BookingView.php
│ └── Web/
│ ├── ApplicationModel.php
│ ├── BaseController.php
│ ├── Flash.php
│ ├── Message.php
│ ├── Utils.php
│ └── README.md
├── templates/
│ ├── schedule.html.twig
│ ├── account.html.twig
│ ├── error.html.twig
│ ├── area.html.twig
│ ├── fragments/
│ │ ├── captcha.html.twig
│ │ ├── confirmation.html.twig
│ │ ├── errors.html.twig
│ │ ├── navbar.html.twig
│ │ ├── booking.html.twig
│ │ └── success.html.twig
│ ├── registration.html.twig
│ ├── layout.html.twig
│ ├── login.html.twig
│ ├── macros.html.twig
│ ├── persons/
│ │ ├── form.html.twig
│ │ └── list.html.twig
│ └── README.md
└── translations/
├── messages+intl-icu.en.yaml
└── messages+intl-icu.fr.yaml
|
Esta es la estructura de una aplicación [Symfony] estándar, la creada por el comando [composer create-project symfony/skeleton] (Ejemplo 01), complementada con los bundles que la aplicación requiere. Hay dos diferencias con respecto a los ejemplos: la aplicación tiene su propia carpeta [vendor] (los ejemplos compartían la de la carpeta [examples]) y su punto de entrada usa el componente [Runtime] de [Symfony] (que se verá más adelante). Las clases de la aplicación se organizan en la carpeta [src] según la regla PSR-4 (ejemplo 01): la clase [App\Business\BusinessService] está en el archivo [src/Business/BusinessService.php]. [Symfony] no exige ninguno de estos archivos: [Controller], [Entity], [EventListener], [Form] y [Twig] son los que se usan (los que utiliza [MakerBundle]), mientras que los demás ([Dao], [Business], [Security]...) forman parte de la arquitectura en capas del Ejemplo 28. [Bootstrap] forma parte de la aplicación esta vez (carpeta [public/lib/bootstrap]): el caso de estudio es autónomo.
11.5. La base de datos
La base de datos [dbrdvmedecins2] tiene cinco tablas:
- [users]: los usuarios autorizados a iniciar sesión;
- [doctors] y [clients]: los médicos y los pacientes, cada uno vinculado a su cuenta de usuario;
- [slots]: las franjas horarias disponibles de cada médico;
- [appointments]: las citas, un cliente por franja horaria en un día determinado.
11.5.1. database/dbrdvmedecins2.sql
| -- =========================================================================
-- Base de datos [dbrdvmedecins2] - MySQL 8
--
-- Evolución de [dbrdvmedecins]:
-- 1. las tablas [doctors] y [clients] reciben una columna [user],
-- clave externa a users(id): cada médico y cada cliente es
-- ahora también un usuario que puede iniciar sesión;
-- 2. aparece un tercer rol: DOCTOR (además de ADMIN y USER);
-- 3. el script crea una fila en [users] para cada médico (rol DOCTOR)
-- y para cada cliente (rol USER):
-- - login = apellido en minúsculas
-- - password = apellido en minúsculas, con hash bcrypt (10 rondas)
-- - display name = nombre + apellido
--
-- 4. restricciones de unicidad, todas con NOMBRE (la aplicación reconoce
-- el nombre de la restricción violada en el mensaje de error de MySQL):
-- - unq_users_login : un login pertenece a una sola cuenta;
-- - unq_doctors_first_name_last_name : dos médicos no pueden tener el
-- mismo nombre y apellido;
-- - unq_clients_first_name_last_name : lo mismo para los clientes.
-- Atención: la collation utf8mb4_unicode_ci compara sin distinguir
-- mayúsculas ni acentos - "Hélène DUPONT" y "helene dupont"
-- se consideran, por lo tanto, idénticos.
--
-- La tabla [users] ahora debe crearse ANTES que [doctors] y [clients]
-- (las referencian), y eliminarse DESPUÉS de ellas.
-- =========================================================================
-- el script está escrito en UTF-8
SET NAMES utf8mb4;
-- se parte de nuevo de una base de datos vacía en cada ejecución del script (práctico en desarrollo)
CREATE DATABASE IF NOT EXISTS dbrdvmedecins2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbrdvmedecins2;
-- orden de eliminación: de las tablas "hijas" a las tablas "padres"
DROP TABLE IF EXISTS appointments;
DROP TABLE IF EXISTS slots;
DROP TABLE IF EXISTS clients;
DROP TABLE IF EXISTS doctors;
DROP TABLE IF EXISTS users;
-- -------------------------------------------------------------------------
-- tabla [users]: los usuarios autorizados a iniciar sesión en la aplicación
-- -------------------------------------------------------------------------
CREATE TABLE users (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
login VARCHAR(30) NOT NULL, -- login identifier
password VARCHAR(100) NOT NULL, -- HASHED password (bcrypt) - never in clear
name VARCHAR(40) NOT NULL, -- name displayed once logged in
role VARCHAR(10) NOT NULL, -- 'ADMIN', 'DOCTOR' or 'USER'
-- un login puede pertenecer a una sola cuenta
CONSTRAINT unq_users_login UNIQUE (login)
);
-- -------------------------------------------------------------------------
-- tabla [doctors]: los médicos del consultorio
-- -------------------------------------------------------------------------
CREATE TABLE doctors (
id INT AUTO_INCREMENT PRIMARY KEY, -- primary key (technical identifier)
version INT NOT NULL DEFAULT 0, -- row version number (optimistic lock)
title VARCHAR(5) NOT NULL, -- Melle, Mme, Mr
last_name VARCHAR(20) NOT NULL,
first_name VARCHAR(20) NOT NULL,
`user` INT NOT NULL, -- foreign key -> users(id)
CONSTRAINT fk_doctors_user FOREIGN KEY (`user`) REFERENCES users(id),
-- una cuenta por médico, y un médico por cuenta
CONSTRAINT unq_doctors_user UNIQUE (`user`),
-- dos médicos no pueden tener el mismo nombre y apellido
CONSTRAINT unq_doctors_first_name_last_name UNIQUE (first_name, last_name)
);
-- -------------------------------------------------------------------------
-- tabla [clients]: los pacientes de los médicos
-- -------------------------------------------------------------------------
CREATE TABLE clients (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
title VARCHAR(5) NOT NULL,
last_name VARCHAR(20) NOT NULL,
first_name VARCHAR(20) NOT NULL,
`user` INT NOT NULL, -- foreign key -> users(id)
CONSTRAINT fk_clients_user FOREIGN KEY (`user`) REFERENCES users(id),
-- una cuenta por cliente, y un cliente por cuenta
CONSTRAINT unq_clients_user UNIQUE (`user`),
-- dos clientes no pueden tener el mismo nombre y apellido
CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);
-- -------------------------------------------------------------------------
-- tabla [slots]: los horarios disponibles de cada médico
-- -------------------------------------------------------------------------
CREATE TABLE slots (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
doctor_id INT NOT NULL, -- foreign key -> doctors(id)
start_hour INT NOT NULL, -- start hour of the slot
start_minute INT NOT NULL, -- start minute of the slot
end_hour INT NOT NULL, -- end hour of the slot
end_minute INT NOT NULL, -- end minute of the slot
CONSTRAINT fk_slots_doctor FOREIGN KEY (doctor_id) REFERENCES doctors(id)
);
-- -------------------------------------------------------------------------
-- tabla [appointments]: las citas reservadas por los clientes
-- -------------------------------------------------------------------------
CREATE TABLE appointments (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
day DATE NOT NULL, -- day of the appointment
slot_id INT NOT NULL, -- foreign key -> slots(id)
client_id INT NOT NULL, -- foreign key -> clients(id)
CONSTRAINT fk_appointments_slot FOREIGN KEY (slot_id) REFERENCES slots(id),
CONSTRAINT fk_appointments_client FOREIGN KEY (client_id) REFERENCES clients(id),
-- un mismo horario, en un mismo día, solo puede reservarse una vez
CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
);
-- =========================================================================
-- Datos de demostración
-- =========================================================================
-- los usuarios: contraseñas con hash bcrypt (10 rondas de salt)
-- admin/admin (ADMIN)
-- una cuenta DOCTOR por médico, una cuenta USER por cliente
-- (la cuenta de demostración user/user ya no existe: una cuenta USER es
-- ahora SIEMPRE la cuenta de un cliente, que puede reservar y gestionar la cuenta)
-- (login = contraseña = apellido en minúsculas)
INSERT INTO users (login, password, name, role) VALUES
('admin', '$2b$10$YSNBJXXHX9mp13nPZb6YGu8M1jR6uvPwO1s2X73z0QAqBR7TOQjoq', 'Administrator', 'ADMIN'),
-- doctors
('pelissier', '$2b$10$DnSDOK5ONrdMxTTr1NKCHOphR3WSp5QAyG9S9ueruw9HwlxI.16ba', 'Marie PELISSIER', 'DOCTOR'),
('tatou', '$2b$10$PeovBO.gmJUKP4PglI/fwu4xtWOYSxoM5VTWjTj7uQ4wcd9P9.htS', 'Paul TATOU', 'DOCTOR'),
('dupont', '$2b$10$az7wvPKC1h0EiAxXwu/PU.vYjzmB04rd5B7QnK0mvxp4niYIHVoc.', 'Sophie DUPONT', 'DOCTOR'),
-- clients
('martin', '$2b$10$GT6S5pp.WdGapFw/UmocXesbC6LEjJfZzgatCUyG9Sf4o1iBNlqZW', 'Jean MARTIN', 'USER'),
('durand', '$2b$10$l2gl/zCder8E7Nh4VxGRX.0.SsO3FDiXt6YwqYq3v9nFzgC/jQCy6', 'Alice DURAND', 'USER'),
('bistrou', '$2b$10$naeRp2YUU6c.QDl5itJMAum3Y5aHdUV6jwIcsbp0D.64jPG4F6E9m', 'Brigitte BISTROU', 'USER'),
('german', '$2b$10$tTWxh3ROWF7NjhZOMnWDMOsZcnSWUiwwfy5C3G0.xhccTXALKyLeW', 'Luc GERMAN', 'USER');
-- los médicos: la columna [user] se busca a partir del login,
-- en lugar de suponer los valores de las claves primarias de [users]
INSERT INTO doctors (title, last_name, first_name, `user`) VALUES
('Mme', 'PELISSIER', 'Marie', (SELECT id FROM users WHERE login = 'pelissier')),
('Mr', 'TATOU', 'Paul', (SELECT id FROM users WHERE login = 'tatou')),
('Melle','DUPONT', 'Sophie', (SELECT id FROM users WHERE login = 'dupont'));
INSERT INTO clients (title, last_name, first_name, `user`) VALUES
('Mr', 'MARTIN', 'Jean', (SELECT id FROM users WHERE login = 'martin')),
('Mme', 'DURAND', 'Alice', (SELECT id FROM users WHERE login = 'durand')),
('Melle','BISTROU', 'Brigitte', (SELECT id FROM users WHERE login = 'bistrou')),
('Mr', 'GERMAN', 'Luc', (SELECT id FROM users WHERE login = 'german'));
-- horarios del médico PELISSIER (doctor_id = 1): de 8:00 a 12:00 en intervalos de 20 minutos
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
(1, 8, 0, 8, 20), (1, 8, 20, 8, 40), (1, 8, 40, 9, 0),
(1, 9, 0, 9, 20), (1, 9, 20, 9, 40), (1, 9, 40, 10, 0),
(1, 10, 0, 10, 20), (1, 10, 20, 10, 40), (1, 10, 40, 11, 0),
(1, 11, 0, 11, 20), (1, 11, 20, 11, 40), (1, 11, 40, 12, 0);
-- horarios del médico TATOU (doctor_id = 2): de 14:00 a 18:00 en intervalos de 20 minutos
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
(2, 14, 0, 14, 20), (2, 14, 20, 14, 40), (2, 14, 40, 15, 0),
(2, 15, 0, 15, 20), (2, 15, 20, 15, 40), (2, 15, 40, 16, 0),
(2, 16, 0, 16, 20), (2, 16, 20, 16, 40), (2, 16, 40, 17, 0),
(2, 17, 0, 17, 20), (2, 17, 20, 17, 40), (2, 17, 40, 18, 0);
-- una cita ya reservada, para ver de inmediato un horario ocupado en la agenda
INSERT INTO appointments (day, slot_id, client_id) VALUES
(CURDATE(), 2, 3);
|
- línea 33: la base de datos se crea si no existe, con el juego de caracteres [utf8mb4] y la cotejación [utf8mb4_unicode_ci], que compara las cadenas sin distinguir mayúsculas ni acentos (ejemplo 28);
- líneas 37–41: las tablas se eliminan y luego se vuelven a crear; el script devuelve la base de datos a su estado inicial. El orden importa: no se puede eliminar una tabla mientras otra la referencie mediante una clave externa;
- Líneas 46–55: usuarios: un nombre de usuario y una contraseña con hash de [bcrypt] (ejemplo 25), el nombre para mostrar después de iniciar sesión y el rol ([ADMIN], [DOCTOR], o [USER]). La restricción [unq_users_login] garantiza que un nombre de usuario pertenezca a una sola cuenta;
- Líneas 60–72: cada tabla tiene una clave primaria [id], generada por la base de datos, y una columna [version], que es el bloqueo optimista (Ejemplo 28). La columna [user] es una clave externa que referencia a [users(id)]: la base de datos rechaza cualquier valor que no sea el ID de un usuario existente. Como [user] es una palabra reservada del lenguaje SQL, se escribe entre acentos graves. Tres restricciones: [fk_doctors_user] (la clave externa), [unq_doctors_user] (una cuenta por médico y un médico por cuenta) y [unq_doctors_first_name_last_name] (sin homónimos). Todas las restricciones tienen nombre: la aplicación reconoce una restricción violada por su nombre;
- líneas 77–89: la tabla [clients] tiene exactamente las mismas columnas;
- líneas 94–103: una franja horaria pertenece a un médico; sus horas de inicio y de fin se almacenan en horas y minutos;
- líneas 108–118: una cita consta de un día (tipo [DATE], sin hora), una franja horaria y un cliente. La restricción [unq1_appointments] impide que la misma franja horaria se reserve dos veces el mismo día: la base de datos hace cumplir esta regla, incluso si dos usuarios intentan reservarla al mismo tiempo;
- líneas 130–140: usuarios de demostración, cuya contraseña es su nombre de usuario. Los hashes comienzan con [$2b$10$]: el algoritmo ([bcrypt], variante [2b]) y el costo (10). Luego vienen la sal y el hash. Estos hashes fueron calculados por la versión [Flask] de la aplicación; [PHP] genera los suyos con el prefijo [$2y$], pero verifica ambos igual de bien;
- líneas 144–147: la columna [user] de cada médico se obtiene mediante una subconsulta basada en el nombre de usuario, en lugar de suponer los valores de las claves primarias;
- líneas 170–171: una cita ya programada para hoy ([CURDATE()]) en la segunda franja horaria del Dr. PELISSIER para la Sra. BISTROU: así, el calendario muestra de inmediato una franja horaria reservada.
A diferencia del caso de [Symfony], la base de datos no la crea [Doctrine] a partir de las entidades, ni mediante migraciones (ejemplo 28): se comparte con las demás versiones de la aplicación y el script SQL es común a todas. El comando [php bin/console doctrine:schema:validate] verifica que las descripciones de las entidades sean coherentes y que correspondan a las tablas de la base de datos.
11.6. La configuración del proyecto
11.6.1. composer.json
| {
"name": "rdvmedecins/rdvmedecins2-symfony",
"description": "RdvMedecins: booking medical appointments, HTML pages built by the server (Symfony + Twig + Doctrine)",
"type": "project",
"license": "MIT",
"require": {
"php": ">=8.4",
"ext-intl": "*",
"ext-pdo_mysql": "*",
"doctrine/doctrine-bundle": "^3.3",
"doctrine/orm": "^3.7",
"firebase/php-jwt": "^7.2",
"symfony/asset": "^8.1",
"symfony/console": "^8.1",
"symfony/dotenv": "^8.1",
"symfony/form": "^8.1",
"symfony/framework-bundle": "^8.1",
"symfony/lock": "^8.1",
"symfony/rate-limiter": "^8.1",
"symfony/runtime": "^8.1",
"symfony/security-bundle": "^8.1",
"symfony/translation": "^8.1",
"symfony/twig-bundle": "^8.1",
"symfony/validator": "^8.1",
"symfony/yaml": "^8.1",
"twig/twig": "^3.30"
},
"autoload": {
"psr-4": {
"App\\": "src/"
}
},
"config": {
"allow-plugins": {
"symfony/runtime": true
},
"optimize-autoloader": true,
"sort-packages": true
},
"minimum-stability": "stable",
"prefer-stable": true
}
|
- Líneas 6–27: las bibliotecas que requiere la aplicación y las restricciones que deben cumplir. [^8.1] se lee «versión 8.1 o una versión más reciente de la misma versión mayor 8»: [Composer] acepta versiones que corrigen errores o añaden funcionalidades, pero no las que podrían romper la aplicación (versión 9). Las líneas [php], [ext-intl] y [ext-pdo_mysql] no se refieren a bibliotecas, sino a requisitos del entorno: [Composer] rechazará la instalación si la versión de [PHP] o de sus extensiones es incompatible, en lugar de permitir que la aplicación falle más adelante. [Symfony] no es una biblioteca única: cada uno de sus componentes (enrutamiento, formularios, seguridad, etc.) es una biblioteca, y la aplicación solicita solo los que necesita; [Composer] instala además las bibliotecas de las que estos dependen;
- Líneas 28–32: la regla PSR-4 de la aplicación: las clases del espacio de nombres [App] se encuentran en la carpeta [src] (Ejemplo 01: en los ejemplos, el archivo [public/index.php] declaraba por sí mismo esta regla al cargador de clases mediante [addPsr4]);
- Líneas 34–36: el componente [Runtime] es un complemento (plugin) de [Composer]; se ejecuta durante la instalación para escribir el archivo [vendor/autoload_runtime.php]. [Composer] solicita permiso para ejecutar el código de un complemento; aquí se concede ese permiso.
[composer install] instala las versiones que cumplen estas restricciones y registra las versiones exactas instaladas en un archivo llamado [composer.lock]. Las instalaciones posteriores (por ejemplo, en otra máquina) usan este archivo: instalan exactamente las mismas versiones. [composer update], en cambio, busca las versiones más recientes permitidas por [composer.json] y actualiza [composer.lock]. El comando [composer show] enumera lo que está instalado en la carpeta [vendor]. En un proyecto típico, este archivo es complementado por [Symfony Flex] con cada [composer require] (ejemplo 01).
11.6.2. .env
| # =========================================================================
# .env: los ajustes específicos de ESTA instalación, leídos al inicio de cada
# solicitud por el componente Dotenv (véase public/index.php). Se convierten en
# variables de entorno, que la configuración (carpeta config) lee mediante
# %env(NAME)%. Una variable de entorno real del sistema tiene precedencia sobre este archivo.
# =========================================================================
# dev: desarrollo; prod: producción (véase README.md)
APP_ENV=dev
# La clave secreta de Symfony (tokens anti-CSRF, firmas...). En producción:
# otro valor, largo y aleatorio
APP_SECRET=34b2364cc4c93df6e4ee35251a048088
# — la base de datos MySQL [dbrdvmedecins2] (script: database/dbrdvmedecins2.sql):
# el SGBD, el usuario y su contraseña (los de Laragon: root, sin
# contraseña), el servidor, su puerto, la base de datos, luego la versión del servidor (para MariaDB:
# serverVersion=10.11.2-MariaDB, por ejemplo) y el conjunto de caracteres
DATABASE_URL="mysql://root:@127.0.0.1:3306/dbrdvmedecins2?serverVersion=8.0.32&charset=utf8mb4"
# — autenticación (véase src/Security/AuthService.php)
# clave secreta de los tokens JWT: al menos 32 caracteres (HMAC-SHA256)
JWT_SECRET=ef1cfc9709f10b5b5d183b4deb6d5dbbe69518629c3b12a8
# duración de validez de un token, en minutos (120 min = 2 h)
JWT_DURATION_MINUTES=120
# 1 en producción (sitio servido por HTTPS): las cookies nunca viajan sin cifrar
COOKIE_SECURE=0
# — protección contra robots (véase src/Security/AttemptLimiter.php)
# fallos de inicio de sesión permitidos para un mismo login desde la misma dirección IP, luego
# bloqueo durante esta duración (en minutos); una dirección IP también se bloquea si
# acumula LOGIN_MAX_FAILURES_IP fallos, todos los logins juntos (un robot que prueba
# miles de logins distintos)
LOGIN_MAX_FAILURES=5
LOGIN_MAX_FAILURES_IP=25
LOGIN_BLOCK_MINUTES=15
# cuentas de cliente creadas como máximo por hora y por dirección IP. En un salón de clases, todas
# las computadoras suelen salir por la misma dirección: aumentar si es necesario
REGISTRATION_MAX_PER_HOUR=10
|
El archivo que contiene los parámetros específicos de esta instalación (ejemplo 25): estos varían de una máquina a otra (la base de datos, sus credenciales) o son confidenciales (las claves). En un proyecto real, los secretos de producción no se incluyen aquí: se proporcionan mediante variables de entorno reales, mediante un archivo [.env.local] que nunca se publica, o mediante la bóveda de secretos de [Symfony] (ejemplo 25).
- línea 9: el modo de la aplicación: [dev] (desarrollo: modo de depuración, página de depuración, caché reconstruida con cada cambio) o [prod];
- línea 12: la clave secreta de [Symfony], que se usa en particular para los tokens anti-CSRF (ejemplo 21);
- línea 18: la conexión a la base de datos (ejemplo 28);
- líneas 20–38: los parámetros específicos de la aplicación: los tokens JWT (ejemplo 25) y la protección contra bots (ejemplo 27).
11.6.3. config/bundles.php y config/packages/framework.yaml
| <?php
// config/bundles.php: los bundles de la aplicación (véase el ejemplo 01): el núcleo de
// Symfony, las vistas Twig, la seguridad y Doctrine (acceso a bases de datos)
return [
Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true],
Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true],
];
|
Los cuatro bundles de la aplicación: el núcleo de [Symfony], [Twig] (Ejemplo 13), la seguridad (Ejemplo 25) y [Doctrine] (Ejemplo 28).
| # =========================================================================
# config/packages/framework.yaml: la configuración del FrameworkBundle
# =========================================================================
framework:
secret: '%env(APP_SECRET)%'
# — los idiomas (véase el ejemplo 22): inglés por defecto, francés; el
# servicio de traducción y sus diccionarios (carpeta translations)
default_locale: en
enabled_locales: ['en', 'fr']
translator:
default_path: '%kernel.project_dir%/translations'
fallbacks: ['en']
# — validación de formularios: sus mensajes son CLAVES de nuestros
# diccionarios (ERRORS.FIRSTNAME_REQUIRED...), traducidas en el dominio
# [messages], el mismo que el de las vistas (por defecto: el dominio [validators])
validation:
translation_domain: messages
# — la SESIÓN (mensajes flash, tokens anti-CSRF): archivos de la carpeta
# var/sessions. La cookie de sesión nunca es legible por el JavaScript de
# la página (httponly), ni se envía con una solicitud POST proveniente de otro sitio
# (samesite lax), ni, en producción, se envía sin cifrar (secure)
session:
handler_id: null
save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
name: rdvmedecins_session
cookie_httponly: true
cookie_samesite: lax
cookie_secure: '%env(bool:COOKIE_SECURE)%'
csrf_protection: true
# — los bloqueos (véase el ejemplo 20), para los limitadores de intentos
lock: 'flock://%kernel.project_dir%/var/lock'
# — los LIMITADORES de intentos (véase el ejemplo 27 y src/Security/AttemptLimiter.php).
# fixed_window: como máximo [limit] intentos por período [interval], contados
# desde el primer intento
rate_limiter:
# los fallos de inicio de sesión de un login, desde una dirección IP
login:
policy: fixed_window
limit: '%env(int:LOGIN_MAX_FAILURES)%'
interval: '%env(LOGIN_BLOCK_MINUTES)% minutes'
# los fallos de inicio de sesión de una dirección IP, todos los logins juntos
login_ip:
policy: fixed_window
limit: '%env(int:LOGIN_MAX_FAILURES_IP)%'
interval: '%env(LOGIN_BLOCK_MINUTES)% minutes'
# las cuentas creadas desde una dirección IP, por hora
registration:
policy: fixed_window
limit: '%env(int:REGISTRATION_MAX_PER_HOUR)%'
interval: '1 hour'
|
- líneas 9–13: los idiomas y el traductor (Ejemplo 22);
- líneas 18–19: el componente de validación traduce sus mensajes en el dominio [validators] (ejemplo 09); nuestras restricciones usan como claves de mensaje las claves de nuestros diccionarios ([ERRORS.FIRSTNAME_REQUIRED]...), que están en el dominio [messages]: se lo indicamos al componente de validación. Así, basta un único diccionario por idioma para toda la aplicación;
- líneas 25–32: la sesión (ejemplo 20): archivos en la carpeta [var/sessions]. La aplicación almacena muy poco allí: mensajes flash y tokens anti-CSRF. La cookie de sesión se llama [rdvmedecins_session]; nunca es legible por el [JavaScript] de la página, ni se envía con una solicitud POST desde otro sitio, ni, en producción, se envía en texto plano (el prefijo [bool:] convierte la variable en un booleano, ejemplo 25);
- línea 35: los bloqueos (ejemplo 20), usados por los limitadores de intentos y el servicio de CAPTCHA;
- líneas 40–55: los tres limitadores antibots (ejemplo 27), cuyos parámetros provienen del archivo [.env]. Un valor puede combinar texto y una variable: ['%env(LOGIN_BLOCK_MINUTES)% minutes'].
La caché de la aplicación (el servicio [cache.app], Ejemplo 20) no necesita configuración: se almacena en archivos dentro de la carpeta [var/cache/dev/pools] (o [prod]). La aplicación almacena allí las listas de médicos y clientes, los CAPTCHA, los contadores de intentos y los pases, todo lo cual debe compartirse entre todas las solicitudes. Con varios servidores, se elegiría una caché compartida, como [Redis] ([framework.cache.app: cache.adapter.redis]).
11.6.4. config/packages/security.yaml
| # =========================================================================
# config/packages/security.yaml: seguridad (véanse los ejemplos 25 y 26)
# =========================================================================
security:
# el hash de las contraseñas de las cuentas: bcrypt, 10 rondas, como los
# hashes del script SQL. PHP también verifica los hashes $2b$ (Python) y $2a$
# (Java) de las otras versiones de la aplicación, que comparten la misma base de datos
password_hashers:
App\Entity\User:
algorithm: bcrypt
cost: 10
# el proveedor de usuarios: irrelevante aquí, el usuario conectado está
# descrito por su token (véase src/Security/TokenAuthenticator.php); Symfony
# exige uno de todos modos: una lista vacía
providers:
none:
memory: ~
firewalls:
# UN solo firewall para toda la aplicación, STATELESS: el usuario no se
# almacena en la sesión, se vuelve a encontrar en cada solicitud a partir del
# token JWT de su cookie
main:
stateless: true
provider: none
custom_authenticators:
- App\Security\TokenAuthenticator
# ---------------------------------------------------------------------
# LA REGLA DE ACCESO: las reglas se examinan en orden, se aplica la primera cuyo
# patrón (ruta) coincide con la ruta de la URL:
# - algunas URL PÚBLICAS (PUBLIC_ACCESS): la página de inicio, el inicio de sesión, la
# elección del idioma, la creación de una cuenta;
# - URL reservadas a ciertos roles (una lista de roles: basta CON UNO);
# - todas las DEMÁS requieren un usuario autenticado (última regla).
# Es la regla "todo está prohibido excepto lo permitido": una URL agregada
# más tarde, y que se olvidara proteger, queda protegida por defecto.
# Un visitante anónimo rechazado es enviado a la página de inicio de sesión (el punto
# de entrada del firewall); un usuario autenticado sin el rol solicitado
# recibe una página de error 403.
# ---------------------------------------------------------------------
access_control:
- { path: ^/$, roles: PUBLIC_ACCESS }
- { path: ^/(login|logout)$, roles: PUBLIC_ACCESS }
- { path: ^/language/, roles: PUBLIC_ACCESS }
- { path: ^/register, roles: PUBLIC_ACCESS }
# un paciente cancela SU cita desde "Mi espacio", no desde la agenda
- { path: ^/schedule/cancel$, roles: [ROLE_ADMIN, ROLE_DOCTOR] }
- { path: ^/(doctors|clients), roles: ROLE_ADMIN }
- { path: ^/my-, roles: ROLE_USER }
- { path: ^/, roles: IS_AUTHENTICATED }
|
Configuración de seguridad (ejemplos 25 y 26):
- Líneas 8–11: hash de contraseñas: [bcrypt], 10 rondas, como los hashes del script SQL. Para verificar una contraseña, [PHP] lee el algoritmo y el costo del propio hash: los hashes de la base de datos, escritos por [Python] ([$2b$]) o por [Java] ([$2a$]), se verifican igual que los de [PHP] ([$2y$]);
- líneas 16–18: el proveedor de usuarios. El autenticador de la aplicación no necesita uno: el usuario conectado se identifica por su token, sin leer la base de datos (ejemplo 25). Pero el componente de seguridad exige uno: un proveedor [memory], sin usuarios;
- líneas 24–28: un único cortafuegos [stateless] (sin estado) para toda la aplicación, con nuestro autenticador. Sin patrón ([pattern]): cubre todas las URL. Los archivos de la carpeta [public] ([Bootstrap], la hoja de estilos, el script) no pasan por [Symfony]: el servidor web los sirve directamente;
- Líneas 43–52: las reglas de acceso de la aplicación. Las reglas [access_control] se evalúan en orden y se aplica la primera cuyo patrón coincide con la ruta de la URL. [PUBLIC_ACCESS] concede acceso a la URL a todos, incluidos los visitantes anónimos: la página de inicio, el inicio de sesión, la selección de idioma y la creación de cuenta. A continuación vienen las reglas de URL reservadas a ciertos roles: una lista de roles (línea 49) significa que basta con cualquiera de ellos. La última regla, [^/], se aplica a todas las demás URL y exige un usuario autenticado. Esta es la regla de «todo está prohibido salvo lo permitido»: una URL agregada más adelante, aunque se olvide protegerla, queda protegida automáticamente. El error inverso, una URL pública que quedó accidentalmente sin protección, se nota de inmediato; el error de una página protegida que se olvidó es mucho menos evidente.
Los roles se verifican aquí, en un único archivo, mediante patrones de URL, en lugar de atributos [#[IsGranted]] en las acciones (ejemplo 26): ambas opciones son posibles y pueden combinarse.
11.6.5. config/packages/doctrine.yaml, twig.yaml, config/routes.yaml
| # config/packages/doctrine.yaml: Doctrine, acceso a la base de datos (véase el ejemplo 28)
doctrine:
# la conexión: el DATABASE_URL del archivo .env. En modo de depuración, cada instrucción
# SQL se escribe en el log, que muestra el servidor de desarrollo
dbal:
url: '%env(resolve:DATABASE_URL)%'
# las ENTIDADES: las clases de la carpeta src/Entity, descritas mediante atributos de PHP
orm:
mappings:
App:
type: attribute
dir: '%kernel.project_dir%/src/Entity'
prefix: 'App\Entity'
|
La configuración de [Doctrine] es la que se muestra en el Ejemplo 28.
| # config/packages/twig.yaml: las vistas Twig (carpeta templates)
twig:
default_path: '%kernel.project_dir%/templates'
# los formularios se dibujan con las clases de Bootstrap 5 (véase el ejemplo 18)
form_themes: ['bootstrap_5_layout.html.twig']
|
Los campos de los formularios se dibujan con las clases de [Bootstrap] 5 (Ejemplo 18).
| # config/routes.yaml: las rutas se describen mediante los atributos #[Route] de los
# controladores de la carpeta src/Controller (véase el ejemplo 01)
controllers:
resource: routing.controllers
|
Las rutas se describen mediante los atributos [#[Route]] de los controladores (Ejemplo 01). El comando [php bin/console debug:router] las enumera todas (véase más adelante, la capa web).
11.7. Para iniciar la aplicación
11.7.1. public/index.php y bin/console
| <?php
// public/index.php: el punto de entrada de TODAS las solicitudes HTTP. La carpeta
// [public] es la raíz del sitio: solo sus archivos son accesibles desde el
// navegador (Bootstrap, hoja de estilos, script), nunca el código de la aplicación.
//
// El archivo vendor/autoload_runtime.php lo escribe el componente Runtime de Symfony
// (la biblioteca symfony/runtime): carga las clases, lee el archivo
// .env, activa el modo de depuración y luego invoca la función siguiente, que devuelve el
// kernel de la aplicación; por último le hace procesar la solicitud actual, envía la
// respuesta y termina la solicitud (véase el archivo index.php de los ejemplos)
use App\Kernel;
require_once dirname(__DIR__).'/vendor/autoload_runtime.php';
return function (array $context) {
return new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
};
|
El punto de entrada de los ejemplos (Ejemplo 01) cargaba las clases, leía el archivo [.env], activaba el modo de depuración, creaba el núcleo, le hacía procesar la solicitud, enviaba la respuesta y finalizaba la solicitud. Aquí todo esto lo gestiona el componente [Runtime] de [Symfony] (línea 14): esta es la forma del archivo [public/index.php] en una aplicación [Symfony] estándar.
- Línea 14: el archivo [vendor/autoload_runtime.php], escrito por [Composer] (véase [composer.json]), carga el cargador de clases y luego ejecuta el script que lo incluyó, en este caso [public/index.php], para obtener su valor de retorno: un archivo [PHP] incluido puede devolver un valor ([return]), al igual que una función;
- Líneas 16–18: este valor es una función anónima que recibe el contexto de la aplicación (las variables de entorno, leídas de [.env] por el componente [Runtime]) y devuelve el núcleo. El componente [Runtime] se encarga del resto: los objetos [Request], [handle], [send] y [terminate] .
La ventaja de este enfoque es que el mismo [index.php] funciona con servidores distintos de [PHP-FPM]. Con el modo worker de [FrankenPHP] (véase la sección sobre los ámbitos), por ejemplo, un «runtime» diferente mantiene el núcleo en memoria y le hace procesar las solicitudes de forma secuencial, sin que este archivo cambie. El archivo [bin/console] tiene la misma estructura: su función se encarga de ejecutar los comandos, construidos alrededor del núcleo.
11.7.2. src/Kernel.php y config/services.yaml
| <?php
// src/Kernel.php: el kernel de la aplicación (véase el ejemplo 01)
namespace App;
use Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait;
use Symfony\Component\HttpKernel\Kernel as BaseKernel;
class Kernel extends BaseKernel
{
use MicroKernelTrait;
public function boot(): void
{
parent::boot();
// la zona horaria: la del consultorio médico. Establece la fecha de hoy (no hay
// citas en el pasado, véase src/Business/Dates.php)
date_default_timezone_set('Europe/Paris');
}
}
|
El núcleo de los ejemplos (Ejemplo 01), con un método adicional:
- líneas 13–19: [boot] se llama cuando arranca el núcleo, en cada solicitud. Establece la zona horaria de [PHP]. De forma predeterminada, [PHP] opera en la zona horaria indicada en su configuración ([date.timezone], en el archivo [php.ini]), que suele ser el Tiempo Universal Coordinado (UTC); sin embargo, la fecha actual se usa en una regla de negocio: no se permiten citas en el pasado. En París, entre la medianoche y las 2:00 a. m. en verano, el día UTC todavía es el día anterior: prevalece la zona horaria del consultorio.
| # =========================================================================
# config/services.yaml: los SERVICIOS de la aplicación (véase el ejemplo 06). Todas las
# las clases de la carpeta src/ se declaran en el contenedor, que las crea bajo demanda y
# da a cada una los objetos que necesita (inyección de dependencias): un
# controlador recibe el ApplicationModel, que recibe la capa de negocio, que recibe los
# DAO, que reciben el entity manager de Doctrine...
# Solo un objeto de cada clase durante una solicitud.
# =========================================================================
services:
_defaults:
autowire: true
autoconfigure: true
App\:
resource: '../src/'
# Objetos de DATOS, creados por el código (o por Doctrine), nunca por el
# contenedor: no son servicios
exclude:
- '../src/Entity/'
- '../src/Domain/'
- '../src/Views/'
- '../src/Kernel.php'
|
- Líneas 10–15: todas las clases de la carpeta [src] son servicios creados por el contenedor, que le proporciona a cada una los objetos que solicita en su constructor (ejemplo 06). Los servicios son compartidos: un único [ApplicationModel], un único [BusinessService]... para toda la solicitud (véase el capítulo sobre los ámbitos);
- líneas 16–22: excepto las clases de datos: entidades creadas por [Doctrine] o por la capa de negocio, objetos de calendario calculados y modelos de vista creados por las acciones. Estas se excluyen: no son servicios. (Otras clases de datos, como [PersonData] o [Message], están declaradas, pero como nadie las solicita al contenedor, este las descarta por sí mismo.)
No hay nada más que declarar: los escuchas ([#[AsEventListener]]), los controladores ([#[Route]]), las extensiones [Twig], los tipos de formulario y el autenticador son reconocidos por el contenedor según sus atributos o su clase padre ([autoconfigure]) y se configuran en consecuencia. El comando [php bin/console debug:container App] enumera los servicios de la aplicación.
11.8. Las entidades
Las entidades [Doctrine] (Ejemplo 28): una clase por tabla, en la carpeta [src/Entity].
11.8.1. src/Entity/Role.php
| <?php
// src/Entity/Role.php: los tres roles de un usuario (columna users.role):
// - ADMIN : el administrador - citas + gestión de médicos y clientes;
// - DOCTOR: un médico - reserva y cancela citas;
// - USER : un cliente (paciente) - reserva para sí mismo, gestiona su cuenta.
// Una enumeración "respaldada" (backed enum): cada caso tiene un valor, la cadena
// almacenada tal cual en la base de datos; Role::from('ADMIN') hace el camino inverso.
namespace App\Entity;
enum Role: string
{
case ADMIN = 'ADMIN';
case DOCTOR = 'DOCTOR';
case USER = 'USER';
// el rol en el sentido de Symfony (véase config/packages/security.yaml): ROLE_ADMIN...
public function symfonyRole(): string
{
return 'ROLE_'.$this->value;
}
}
|
Los tres roles, enumerados de la siguiente manera ([enum], [PHP] 8.1): un tipo cuyos únicos valores posibles son sus casos: [Role::ADMIN], [Role::DOCTOR], y [Role::USER]. Una variable de tipo [Role] no puede contener ['ADMINN']: el error tipográfico se detecta. [enum Role: string] declara una enumeración con valores asociados: cada caso tiene un valor, en este caso la cadena base. [Role::ADMIN->value] es igual a ['ADMIN']; [Role::from('ADMIN')] devuelve el caso correspondiente (y lanza una excepción si el valor es desconocido); [Role::tryFrom(...)] devuelve [null] en ese caso. Una enumeración puede tener métodos: [symfonyRole()] (líneas 18–21) devuelve el rol tal como lo define [Symfony], [ROLE_ADMIN], [ROLE_DOCTOR] o [ROLE_USER] (ejemplo 25), el que verifican las reglas [access_control]. [$this] designa aquí el caso.
11.8.2. src/Entity/User.php
| <?php
// =========================================================================
// src/Entity/User.php: un usuario autorizado a iniciar sesión (tabla [users]).
// Cada médico y cada cliente tiene SU cuenta (columna [user] de las tablas
// [doctors] y [clients], véase Person.php).
//
// restricción de unicidad SQL: unq_users_login (un login pertenece a una sola
// cuenta). La crea el script database/dbrdvmedecins2.sql; la capa de negocio
// la reconoce por su NOMBRE (véase src/Business/BusinessService.php).
//
// PasswordAuthenticatedUserInterface: un usuario que tiene una contraseña (con hash);
// es lo que espera el servicio de hash de Symfony (véase AuthService).
// =========================================================================
namespace App\Entity;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
#[ORM\Entity]
#[ORM\Table(name: 'users')]
class User implements PasswordAuthenticatedUserInterface
{
#[ORM\Id]
#[ORM\GeneratedValue]
#[ORM\Column]
private ?int $id = null;
// el número de versión de la fila: el bloqueo optimista (véase el ejemplo 28)
#[ORM\Version]
#[ORM\Column(type: Types::INTEGER)]
private int $version = 0;
public function __construct(
#[ORM\Column(length: 30)]
private string $login,
// la contraseña con HASH (bcrypt), nunca la contraseña misma
#[ORM\Column(length: 100)]
private string $password,
// el nombre que se muestra una vez iniciada la sesión: "Marie PELISSIER"
#[ORM\Column(length: 40)]
private string $name,
// enumType: la columna (un texto) se convierte en un Role, y viceversa
#[ORM\Column(length: 10, enumType: Role::class)]
private Role $role,
) {
}
public function getId(): ?int
{
return $this->id;
}
public function getVersion(): int
{
return $this->version;
}
public function getLogin(): string
{
return $this->login;
}
public function getPassword(): string
{
return $this->password;
}
public function getName(): string
{
return $this->name;
}
public function getRole(): Role
{
return $this->role;
}
public function setLogin(string $login): void
{
$this->login = $login;
}
public function setPassword(string $hash): void
{
$this->password = $hash;
}
public function setName(string $name): void
{
$this->name = $name;
}
}
|
- líneas 21–23: la entidad de la tabla [users]. Implementa la interfaz [PasswordAuthenticatedUserInterface] del componente de seguridad (Ejemplo 25): es lo que espera el servicio de hash de contraseñas;
- líneas 25–33: la clave primaria y la versión, el bloqueo optimista (Ejemplo 28);
- líneas 35–48: las demás columnas se declaran en el constructor mediante la promoción de propiedades del constructor (Ejemplo 03): los atributos [#[ORM\Column]] pueden aplicarse tanto a un parámetro promovido como a una propiedad. [length] especifica la longitud de las columnas [VARCHAR]. Línea 45: la opción [enumType] convierte la columna [role] (texto) en [Role] durante las operaciones de lectura, y viceversa durante las de escritura: [$user->getRole()] devuelve un [Role], nunca una cadena;
- Líneas 50–93: los getters y tres métodos setter. La clave primaria y la versión no tienen métodos setter: [Doctrine] las mantiene actualizadas.
11.8.3. src/Entity/Person.php
| <?php
// =========================================================================
// src/Entity/Person.php: lo que tienen en común los médicos (tabla [doctors]) y los clientes
// (tabla [clients]): un título, un apellido, un nombre - y la
// cuenta de usuario asociada (columna [user]).
//
// Las dos tablas tienen exactamente las mismas columnas: se describen UNA SOLA VEZ
// en esta clase ABSTRACTA (nunca se crea una "Person"), de la cual
// heredan Doctor y Client; cada una solo especifica el nombre de su tabla.
// #[ORM\MappedSuperclass]: una clase padre cuyas columnas son las de las
// entidades que heredan de ella, pero que no tiene tabla propia.
//
// ¡Atención: [Client] aquí significa un PACIENTE del consultorio médico, no un cliente
// HTTP! Es el vocabulario del dominio de negocio original, conservado tal cual.
// =========================================================================
namespace App\Entity;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;
#[ORM\MappedSuperclass]
abstract class Person
{
#[ORM\Id]
#[ORM\GeneratedValue]
#[ORM\Column]
protected ?int $id = null;
// bloqueo optimista (véase el ejemplo 28)
#[ORM\Version]
#[ORM\Column(type: Types::INTEGER)]
protected int $version = 0;
public function __construct(
// Mr, Mme, Melle
#[ORM\Column(length: 5)]
protected string $title,
#[ORM\Column(name: 'last_name', length: 20)]
protected string $lastName,
#[ORM\Column(name: 'first_name', length: 20)]
protected string $firstName,
// -------------------------------------------------------------------
// La RELACIÓN con la cuenta de usuario: una persona tiene UNA cuenta,
// designada por la clave externa [user]. #[ORM\OneToOne]: una cuenta por
// persona, una persona por cuenta; #[ORM\JoinColumn]: la columna de la
// clave externa (rodeada de comillas invertidas: `user` es una palabra del
// lenguaje SQL de MySQL). $doctor->getAccount() devuelve un objeto User, leído de la base de datos en el
// primer acceso, o de inmediato mediante la consulta, si así lo pide (véase src/Dao)
// -------------------------------------------------------------------
#[ORM\OneToOne]
#[ORM\JoinColumn(name: '`user`', nullable: false)]
protected User $account,
) {
}
public function getId(): ?int
{
return $this->id;
}
public function getVersion(): int
{
return $this->version;
}
public function getTitle(): string
{
return $this->title;
}
public function getLastName(): string
{
return $this->lastName;
}
public function getFirstName(): string
{
return $this->firstName;
}
public function getAccount(): User
{
return $this->account;
}
public function edit(string $title, string $lastName, string $firstName): void
{
$this->title = $title;
$this->lastName = $lastName;
$this->firstName = $firstName;
}
// "Mme Alice DURAND"
public function label(): string
{
return "{$this->title} {$this->firstName} {$this->lastName}";
}
}
|
Las tablas [doctors] y [clients] tienen las mismas columnas. Su descripción compartida se escribe una sola vez, en una clase abstracta ([abstract class]): una clase de la que nunca se crean objetos y que sirve solo como clase base para la herencia. Las clases [Doctor] y [Client] heredan de ella.
- Línea 22: el atributo [#[ORM\MappedSuperclass]] convierte la clase en una superclase: sus columnas son las de cada una de las entidades que heredan de ella, pero no tiene tabla propia. ([Doctrine] también admite verdaderas jerarquías de entidades, organizadas en una sola tabla o en una tabla por clase: no es el caso aquí, donde las dos tablas son independientes.) Las propiedades son [protected]: visibles para las clases hijas;
- Líneas 51–53: la relación con la cuenta. [#[ORM\OneToOne]]: una persona tiene una cuenta y una cuenta pertenece como máximo a una persona. [#[ORM\JoinColumn]] hace referencia a la columna de la clave externa, [user], y garantiza que no esté vacía ([nullable: false]). El nombre de la columna se escribe entre acentos graves: [user] es una palabra reservada del lenguaje SQL de [MySQL], y [Doctrine] la encerrará de esta manera en los comandos SQL que escribe (véase la salida de la consola más arriba). La propiedad [account] es un objeto [User], no un número: ese es el propósito de un ORM. Cuando [Doctrine] lee una persona, también lee su cuenta si la solicitud lo requiere (carga diferida o «lazy»; véase la capa DAO); de lo contrario, coloca en la propiedad un objeto diferido [User] (lazy), que solo se leerá de la base de datos en el primer acceso a una de sus propiedades, excepto su ID, que ya conoce;
- líneas 87–92: modificación de las tres columnas de identidad;
- líneas 95–98: el nombre de una persona, «Sra. Alice DURAND», utilizado por todas las páginas. En una cadena entre comillas, [{$this->title}] inserta el valor de una propiedad.
11.8.4. src/Entity/Doctor.php y Client.php
| <?php
// src/Entity/Doctor.php: un médico (tabla [doctors]).
// Restricción de unicidad SQL: unq_doctors_first_name_last_name (dos médicos no pueden
// tener el mismo nombre y apellido).
namespace App\Entity;
use Doctrine\ORM\Mapping as ORM;
#[ORM\Entity]
#[ORM\Table(name: 'doctors')]
class Doctor extends Person
{
}
|
| <?php
// src/Entity/Client.php: un cliente, es decir, un PACIENTE (tabla [clients]).
// Restricción de unicidad SQL: unq_clients_first_name_last_name.
namespace App\Entity;
use Doctrine\ORM\Mapping as ORM;
#[ORM\Entity]
#[ORM\Table(name: 'clients')]
class Client extends Person
{
}
|
Dos entidades que especifican únicamente su tabla: todo lo demás se hereda. Un [Client] es un paciente del consultorio, no un cliente HTTP: este es el vocabulario original del dominio de negocio, conservado en todas las versiones de la aplicación.
11.8.5. src/Entity/Slot.php
| <?php
// src/Entity/Slot.php: una franja horaria de un médico (tabla [slots]):
// 8:00 - 8:20, etc. Las franjas las crea el script SQL: la aplicación
// solo las lee.
namespace App\Entity;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;
#[ORM\Entity]
#[ORM\Table(name: 'slots')]
class Slot
{
#[ORM\Id]
#[ORM\GeneratedValue]
#[ORM\Column]
private ?int $id = null;
#[ORM\Version]
#[ORM\Column(type: Types::INTEGER)]
private int $version = 0;
// varias franjas para el mismo médico: #[ORM\ManyToOne], mediante la clave
// externa [doctor_id]
#[ORM\ManyToOne]
#[ORM\JoinColumn(name: 'doctor_id', nullable: false)]
private Doctor $doctor;
#[ORM\Column(name: 'start_hour')]
private int $startHour;
#[ORM\Column(name: 'start_minute')]
private int $startMinute;
#[ORM\Column(name: 'end_hour')]
private int $endHour;
#[ORM\Column(name: 'end_minute')]
private int $endMinute;
public function getId(): ?int
{
return $this->id;
}
public function getDoctor(): Doctor
{
return $this->doctor;
}
// "8:00 - 8:20"; sprintf('%02d'): "8:05" en lugar de "8:5"
public function time(): string
{
return sprintf('%d:%02d - %d:%02d', $this->startHour, $this->startMinute, $this->endHour, $this->endMinute);
}
}
|
- líneas 26–28: la relación de la franja horaria con el médico. [#[ORM\ManyToOne]]: varias franjas horarias para el mismo médico, mediante la clave externa [doctor_id];
- líneas 30–40: las horas y los minutos de inicio y de fin. Las franjas horarias las crea el script SQL: la clase no tiene constructor y [Doctrine] rellena sus propiedades por sí mismo;
- líneas 53–56: el intervalo de tiempo, «8:00 – 8:20». El formato [%02d] de [sprintf] escribe un entero de dos dígitos, rellenado con ceros: [8:05] en lugar de [8:5].
11.8.6. src/Entity/Appointment.php
| <?php
// src/Entity/Appointment.php: una cita (tabla [appointments]): un cliente, en una franja,
// en un día dado.
// Restricción de unicidad SQL: unq1_appointments (day, slot_id) - una franja se reserva
// solo una vez por día. Creada por el script SQL, reconocida por su nombre en la capa
// de negocio.
namespace App\Entity;
use DateTimeImmutable;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;
#[ORM\Entity]
#[ORM\Table(name: 'appointments')]
class Appointment
{
#[ORM\Id]
#[ORM\GeneratedValue]
#[ORM\Column]
private ?int $id = null;
#[ORM\Version]
#[ORM\Column(type: Types::INTEGER)]
private int $version = 0;
public function __construct(
// el tipo date_immutable: la columna [day] (tipo SQL DATE) se convierte en una fecha
// DateTimeImmutable, a medianoche; se escribe en la base de datos en formato yyyy-mm-dd
#[ORM\Column(type: Types::DATE_IMMUTABLE)]
private DateTimeImmutable $day,
#[ORM\ManyToOne]
#[ORM\JoinColumn(name: 'slot_id', nullable: false)]
private Slot $slot,
#[ORM\ManyToOne]
#[ORM\JoinColumn(name: 'client_id', nullable: false)]
private Client $client,
) {
}
public function getId(): ?int
{
return $this->id;
}
public function getDay(): DateTimeImmutable
{
return $this->day;
}
public function getSlot(): Slot
{
return $this->slot;
}
public function getClient(): Client
{
return $this->client;
}
}
|
- líneas 30–31: la columna [day] (tipo SQL [DATE]) se convierte en [DateTimeImmutable] a medianoche (tipo [Doctrine] [date_immutable]). Inmutable: sus métodos nunca modifican el objeto; devuelven uno nuevo ([$day->modify('+1 day')] devuelve el día siguiente, [$day] permanece sin cambios). Toda la aplicación trabaja con fechas inmutables: una fecha compartida entre varios objetos no puede ser modificada por uno de ellos sin que los demás lo sepan;
- líneas 32–37: dos relaciones, una con la franja horaria y otra con el cliente de la cita.
11.9. El dominio: el calendario
11.9.1. src/Domain/DoctorDaySlot.php y DoctorDaySchedule.php
| <?php
// src/Domain/DoctorDaySlot.php: una franja horaria, y la cita eventualmente
// reservada en esa franja en un día dado (null si la franja está libre).
// Un objeto de "negocio" calculado, que no corresponde a ninguna tabla.
//
// readonly: las propiedades las establece el constructor de una vez por todas -
// justo lo que se necesita para un objeto calculado, que nadie modifica después.
namespace App\Domain;
use App\Entity\Slot;
use App\Entity\Appointment;
readonly class DoctorDaySlot
{
public function __construct(
public Slot $slot,
public ?Appointment $appointment,
) {
}
}
|
| <?php
// src/Domain/DoctorDaySchedule.php: la agenda completa de un médico para un día
// dado, la lista de sus franjas, cada una libre u ocupada. Calculada por
// BusinessService::getDoctorDaySchedule, convertida en una tabla HTML por
// ScheduleController.
namespace App\Domain;
use App\Entity\Doctor;
use DateTimeImmutable;
readonly class DoctorDaySchedule
{
/** @param list<DoctorDaySlot> $doctorDaySlots */
public function __construct(
public Doctor $doctor,
public DateTimeImmutable $day,
public array $doctorDaySlots,
) {
}
}
|
Dos objetos calculados que no corresponden a ninguna tabla: una franja horaria y su posible cita en un día determinado; el calendario de un médico para un solo día, con la lista de sus franjas horarias disponibles. Son clases [readonly] (ejemplo 03), cuyas propiedades se declaran en el constructor. El comentario [/** @param list<DoctorDaySlot> ... */] especifica el contenido del arreglo: [PHP] no puede determinar el tipo del contenido de un arreglo, pero los editores ([PHP Intelephense]) y las herramientas de análisis leen estos comentarios, conocidos como [PHPDoc].
11.10. La capa DAO
La capa DAO (Ejemplo 28) agrupa las consultas: una clase por tabla, sin lógica de negocio. Sus métodos no inician una transacción; la capa de negocio los llama dentro de sus propias transacciones. Están escritos en DQL (Ejemplo 28) o mediante el constructor de consultas de [Doctrine], que genera una consulta DQL mediante llamadas a métodos; los valores son parámetros de la consulta: la inyección SQL no es posible.
11.10.1. src/Dao/PersonDao.php
| <?php
// =========================================================================
// src/Dao/PersonDao.php: la capa DAO común a los médicos y los clientes.
//
// Los DAO de los médicos y de los clientes serían idénticos: esta clase ABSTRACTA
// los escribe una sola vez. $this->entityClass es la clase de la entidad en cuestión
// (Doctor::class o Client::class): las consultas DQL se refieren a SU tabla.
//
// Las consultas se escriben en DQL, el lenguaje de consultas de Doctrine (véase el
// ejemplo 28), que Doctrine traduce a SQL. Los valores (nombre, apellido...) son
// PARÁMETROS de la consulta (:firstName): sin concatenación de cadenas, por lo tanto sin
// inyección SQL. Estos métodos no abren ninguna transacción: es la capa de negocio
// la que los invoca, dentro de la suya.
// =========================================================================
namespace App\Dao;
use App\Entity\Person;
use Doctrine\ORM\EntityManagerInterface;
use Doctrine\ORM\QueryBuilder;
abstract class PersonDao
{
/** @param class-string<Person> $entityClass */
public function __construct(protected EntityManagerInterface $em, protected string $entityClass)
{
}
// -----------------------------------------------------------------------
// una consulta sobre la tabla de la clase, cuenta de usuario incluida. El
// QUERY BUILDER de Doctrine (createQueryBuilder) construye la consulta DQL
// mediante llamadas a métodos:
// SELECT p, a FROM App\Entity\Doctor p JOIN p.account a
// JOIN p.account a: la unión SQL con la tabla [users]; SELECT p, a: las
// cuentas se cargan EN LA MISMA consulta. Sin esto, cada acceso a
// $person->getAccount() desencadenaría su propia consulta
// -----------------------------------------------------------------------
protected function query(): QueryBuilder
{
return $this->em->createQueryBuilder()
->select('p', 'a')
->from($this->entityClass, 'p')
->join('p.account', 'a');
}
// lista ordenada por apellido y luego por nombre
/** @return list<Person> */
public function list(): array
{
return $this->query()->orderBy('p.lastName')->addOrderBy('p.firstName')->getQuery()->getResult();
}
// una persona y su cuenta; null si no existen
public function read(int $id): ?Person
{
return $this->query()->where('p.id = :id')->setParameter('id', $id)
->getQuery()->getOneOrNullResult();
}
// la persona cuya cuenta de usuario es [$userId]
public function readByUser(int $userId): ?Person
{
return $this->query()->where('a.id = :userId')->setParameter('userId', $userId)
->getQuery()->getOneOrNullResult();
}
// la persona que tiene este nombre y apellido, si existe. La comparación la
// hace MySQL, por lo tanto con la intercalación de la base de datos (utf8mb4_unicode_ci: sin
// distinguir mayúsculas ni acentos) - exactamente la misma regla que
// la de la restricción de unicidad SQL
public function namesake(string $firstName, string $lastName): ?Person
{
return $this->query()->where('p.firstName = :firstName')->andWhere('p.lastName = :lastName')
->setParameter('firstName', $firstName)->setParameter('lastName', $lastName)
->setMaxResults(1)->getQuery()->getOneOrNullResult();
}
// la persona será insertada por el siguiente flush (el de la transacción de
// la capa de negocio); la base de datos generará su id, que Doctrine guardará en el objeto
public function add(Person $person): void
{
$this->em->persist($person);
}
// la persona será eliminada por el siguiente flush
public function remove(Person $person): void
{
$this->em->remove($person);
}
}
|
La capa DAO común a médicos y clientes, implementada una sola vez en una clase abstracta.
- Línea 25: el constructor recibe el administrador de entidades (Ejemplo 28) y la clase correspondiente, [Doctor::class] o [Client::class] (una cadena que representa el nombre completo de la clase). El comentario [@param class-string<Person>] lo aclara para los desarrolladores. El contenedor de servicios no sabe qué cadena proporcionar: son las clases hijas las que llaman a este constructor;
- líneas 38–44: una consulta que también carga las cuentas de los usuarios leídos. [createQueryBuilder] crea un constructor de consultas; [select('p', 'a')], [from($this->entityClass, 'p')], y [join('p.account', 'a')] escriben la consulta DQL [SELECT p, a FROM App\Entity\Doctor p JOIN p.account a]. La unión ([JOIN]) sigue la relación [account] de la entidad: [Doctrine] deduce la condición SQL ([ON d0_.user = u1_.id]). El [SELECT] de ambos alias exige la carga anticipada de las cuentas: una sola consulta recupera a las personas y sus cuentas. Sin ella, la lista de médicos que muestra el administrador provocaría una consulta por médico en el primer acceso a [$doctor->getAccount()->getLogin()]: es el llamado problema de las «N + 1 consultas». Otro motivo: las listas de médicos y clientes se almacenan en la caché ([ApplicationModel], que se verá más adelante); los objetos que se agregan a la caché deben estar completos;
- líneas 48–51: la lista, ordenada por apellido y luego por nombre ([orderBy], luego [addOrderBy]: un segundo criterio; un segundo [orderBy] reemplazaría al primero). [getQuery()] devuelve la consulta DQL; [getResult()] la ejecuta y devuelve el arreglo de entidades;
- líneas 54–58: [where] agrega una condición con un parámetro con nombre ([:id]), cuyo valor lo proporciona [setParameter]. [getOneOrNullResult] devuelve la única entidad encontrada, o [null];
- líneas 61–65: la persona cuya cuenta es [$userId], condición basada en el ID de la cuenta vinculada;
- líneas 71–76: la persona con el mismo nombre y apellido. [andWhere] agrega una segunda condición (un segundo [where] reemplazaría al primero). La comparación la realiza [MySQL], con la cotejación de la base de datos: sin distinguir mayúsculas e ignorando los acentos, exactamente como la restricción de unicidad (Ejemplo 28);
- líneas 80–89: la inserción y la eliminación, que [flush] enviará a la base de datos como parte de la transacción de la capa de negocio (Ejemplo 28).
No hay método de actualización: la capa de negocio modifica la entidad leída y [Doctrine] enviará [UPDATE] en [flush] (seguimiento de cambios, Ejemplo 28), con un bloqueo optimista.
11.10.2. src/Dao/DoctorDao.php y ClientDao.php
| <?php
// src/Dao/DoctorDao.php: el DAO de los médicos - todo se hereda de PersonDao.
namespace App\Dao;
use App\Entity\Doctor;
use Doctrine\ORM\EntityManagerInterface;
class DoctorDao extends PersonDao
{
public function __construct(EntityManagerInterface $em)
{
parent::__construct($em, Doctor::class);
}
}
|
Todo se hereda: el constructor recibe el administrador de entidades del contenedor y lo pasa a [PersonDao] junto con la clase de la entidad ([parent::__construct] llama al constructor de la clase padre).
| <?php
// src/Dao/ClientDao.php: el DAO de los clientes - el de las personas, más un
// método de bloqueo.
namespace App\Dao;
use App\Entity\Client;
use Doctrine\DBAL\LockMode;
use Doctrine\ORM\EntityManagerInterface;
class ClientDao extends PersonDao
{
public function __construct(EntityManagerInterface $em)
{
parent::__construct($em, Client::class);
}
// -----------------------------------------------------------------------
// pone un BLOQUEO en la fila de un cliente hasta el final de la transacción actual
// (SELECT ... FOR UPDATE), y devuelve su id (null si el cliente no
// existe). Una segunda transacción que pida el mismo bloqueo ESPERA a que la
// primera termine. LockMode::PESSIMISTIC_WRITE: el bloqueo "pesimista" de Doctrine,
// que requiere una transacción abierta.
// Usado para la reserva (véase BusinessService::addAppointment): dos
// reservas simultáneas para el mismo paciente se procesan así una
// DESPUÉS de la otra, y la segunda ve la cita creada por la primera.
// -----------------------------------------------------------------------
public function lock(int $id): ?int
{
$row = $this->em->createQuery('SELECT c.id FROM App\Entity\Client c WHERE c.id = :id')
->setParameter('id', $id)
->setLockMode(LockMode::PESSIMISTIC_WRITE)
->getOneOrNullResult();
return $row['id'] ?? null;
}
}
|
- Líneas 28–35: un bloqueo pesimista, el otro tipo de bloqueo. [setLockMode(LockMode::PESSIMISTIC_WRITE)] agrega [FOR UPDATE] a la consulta: [SELECT c0_.id AS id_0 FROM clients c0_ WHERE c0_.id = ? FOR UPDATE]. La fila que se lee queda bloqueada hasta el final de la transacción en curso: otra transacción que solicite el mismo bloqueo espera a que termine la primera. [Doctrine] rechaza este bloqueo fuera de una transacción. La consulta lee solo el ID ([SELECT c.id]): su resultado no es una entidad, sino un arreglo asociativo ([['id' => 3]]), o [null]. Veremos, en la capa de negocio, para qué sirve este bloqueo.
11.10.3. src/Dao/SlotDao.php
| <?php
// src/Dao/SlotDao.php: capa DAO de las franjas horarias.
namespace App\Dao;
use App\Entity\Slot;
use Doctrine\ORM\EntityManagerInterface;
class SlotDao
{
public function __construct(private EntityManagerInterface $em)
{
}
// una franja y su médico
public function read(int $id): ?Slot
{
return $this->em->createQuery(
'SELECT s, d FROM App\Entity\Slot s JOIN s.doctor d WHERE s.id = :id')
->setParameter('id', $id)->getOneOrNullResult();
}
// las franjas de un médico, en orden cronológico. s.doctor = :doctorId:
// una asociación comparada con un id, el de la clave externa
/** @return list<Slot> */
public function listByDoctor(int $doctorId): array
{
return $this->em->createQuery(
'SELECT s FROM App\Entity\Slot s WHERE s.doctor = :doctorId ORDER BY s.startHour, s.startMinute')
->setParameter('doctorId', $doctorId)->getResult();
}
// elimina todas las franjas de un médico (eliminación de un médico): una
// consulta DQL DELETE, ejecutada de inmediato:
// DELETE FROM slots WHERE doctor_id = ?
public function deleteByDoctor(int $doctorId): void
{
$this->em->createQuery('DELETE FROM App\Entity\Slot s WHERE s.doctor = :doctorId')
->setParameter('doctorId', $doctorId)->execute();
}
}
|
Una franja horaria y su médico (precargado); las franjas horarias de un médico, en orden cronológico: [s.doctor = :doctorId] compara una relación con un ID, el de la clave externa; y un [DELETE] escrito en DQL, ejecutado de inmediato ([execute()]), sin leer antes las filas.
11.10.4. src/Dao/AppointmentDao.php
| <?php
// =========================================================================
// src/Dao/AppointmentDao.php: capa DAO de las citas.
//
// La tabla [appointments] no hace referencia directa al médico: pasamos por la franja
// (JOIN a.slot s ... WHERE s.doctor = ...).
// Las fechas se pasan con su tipo (Types::DATE_IMMUTABLE): Doctrine
// las escribe en el formato de la base de datos, yyyy-mm-dd.
// =========================================================================
namespace App\Dao;
use App\Entity\Appointment;
use DateTimeImmutable;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\EntityManagerInterface;
class AppointmentDao
{
public function __construct(private EntityManagerInterface $em)
{
}
// una cita, su cliente y su franja
public function read(int $id): ?Appointment
{
return $this->em->createQuery(
'SELECT a, c, s FROM App\Entity\Appointment a JOIN a.client c JOIN a.slot s WHERE a.id = :id')
->setParameter('id', $id)->getOneOrNullResult();
}
// las citas de un médico en un día dado, con su cliente
/** @return list<Appointment> */
public function doctorDayAppointments(int $doctorId, DateTimeImmutable $day): array
{
return $this->em->createQuery(
'SELECT a, c FROM App\Entity\Appointment a JOIN a.client c JOIN a.slot s
WHERE a.day = :day AND s.doctor = :doctorId')
->setParameter('day', $day, Types::DATE_IMMUTABLE)
->setParameter('doctorId', $doctorId)
->getResult();
}
// -----------------------------------------------------------------------
// las citas de un cliente a partir del día [$since] (incluido), en orden
// cronológico, con la franja Y el médico de esa franja (dos uniones:
// JOIN a.slot s JOIN s.doctor d, y SELECT a, s, d)
// -----------------------------------------------------------------------
/** @return list<Appointment> */
public function clientUpcomingAppointments(int $clientId, DateTimeImmutable $since): array
{
return $this->em->createQuery(
'SELECT a, s, d FROM App\Entity\Appointment a JOIN a.slot s JOIN s.doctor d
WHERE a.client = :clientId AND a.day >= :since
ORDER BY a.day, s.startHour, s.startMinute')
->setParameter('clientId', $clientId)
->setParameter('since', $since, Types::DATE_IMMUTABLE)
->getResult();
}
// número de citas de un cliente a partir del día [$since] (incluido);
// getSingleScalarResult: el único valor de la única fila del resultado
public function countClientUpcoming(int $clientId, DateTimeImmutable $since): int
{
return (int) $this->em->createQuery(
'SELECT COUNT(a.id) FROM App\Entity\Appointment a WHERE a.client = :clientId AND a.day >= :since')
->setParameter('clientId', $clientId)
->setParameter('since', $since, Types::DATE_IMMUTABLE)
->getSingleScalarResult();
}
// número de citas (pasadas o futuras) de un médico
public function countByDoctor(int $doctorId): int
{
return (int) $this->em->createQuery(
'SELECT COUNT(a.id) FROM App\Entity\Appointment a JOIN a.slot s WHERE s.doctor = :doctorId')
->setParameter('doctorId', $doctorId)
->getSingleScalarResult();
}
// la cita se insertará en el próximo flush
public function add(Appointment $appointment): void
{
$this->em->persist($appointment);
}
public function remove(Appointment $appointment): void
{
$this->em->remove($appointment);
}
// elimina TODAS las citas (pasadas y futuras) de un cliente, de inmediato
public function deleteByClient(int $clientId): void
{
$this->em->createQuery('DELETE FROM App\Entity\Appointment a WHERE a.client = :clientId')
->setParameter('clientId', $clientId)->execute();
}
}
|
La tabla [appointments] no hace referencia directa al médico: pasa por la franja horaria.
- Líneas 34–42: las citas de un médico en un día determinado y sus clientes. Dos uniones: una ([a.client c]) para cargar los clientes ([SELECT a, c]), y la otra ([a.slot s]) para el filtro por médico. El tercer parámetro de [setParameter] especifica el tipo del valor para [Doctrine]: un [DateTimeImmutable] se escribe entonces en el formato de la columna [DATE], [yyyy-mm-dd];
- líneas 50–59: las próximas citas de un paciente, con su franja horaria y el médico asignado a esa franja: [JOIN s.doctor d] sigue una relación a partir de la relación. El ordenamiento también se realiza según la franja horaria, una columna de otra tabla: la unión lo hace posible;
- líneas 63–79: los conteos. [COUNT(a.id)] cuenta las citas; [getSingleScalarResult] devuelve el único valor de la única fila del resultado (una cadena, convertida en entero por [(int)]);
- líneas 93–97: eliminación de todas las citas de un cliente, mediante DQL.
11.10.5. src/Dao/UserDao.php
| <?php
// src/Dao/UserDao.php: capa DAO de las cuentas de usuario. Crear (o eliminar)
// un médico o un cliente también crea (o elimina) su cuenta - véase src/Business.
// Una cuenta modificada se modifica mediante sus métodos (setLogin...): Doctrine enviará
// el UPDATE en el próximo flush (seguimiento de cambios, véase el ejemplo 28).
namespace App\Dao;
use App\Entity\User;
use Doctrine\ORM\EntityManagerInterface;
class UserDao
{
public function __construct(private EntityManagerInterface $em)
{
}
// null si ningún usuario tiene este login; findOneBy: el repositorio de la entidad
// busca la fila cuyas columnas tienen estos valores
public function readByLogin(string $login): ?User
{
return $this->em->getRepository(User::class)->findOneBy(['login' => $login]);
}
public function add(User $user): void
{
$this->em->persist($user);
}
public function remove(User $user): void
{
$this->em->remove($user);
}
}
|
Cuentas: recuperación por nombre de usuario, con almacenamiento de entidades (ejemplo 28): [findOneBy(criteria)] devuelve la única entidad que cumple los criterios, o [null]; adición y eliminación.
11.11. La capa de negocio
La capa de negocio reúne las reglas de negocio y las transacciones (Ejemplo 28). Está descrita por una interfaz, implementada por dos clases: [BusinessService], la capa de negocio propiamente dicha, y [ApplicationModel], la caché de la capa web (que se verá más adelante).
11.11.1. src/Business/Dates.php
| <?php
// src/Business/Dates.php: la fecha de hoy. La usan las REGLAS DE NEGOCIO (no
// reservar en el pasado, una sola cita PRÓXIMA por paciente): por lo tanto
// pertenece a la capa de negocio. La capa web la reutiliza.
namespace App\Business;
use DateTimeImmutable;
class Dates
{
// hoy a medianoche, en la zona horaria de la aplicación (véase src/Kernel.php)
public static function today(): DateTimeImmutable
{
return new DateTimeImmutable('today');
}
}
|
La fecha actual a medianoche (['today']), en la zona horaria de la aplicación (véase [src/Kernel.php]). Se usa para las reglas de negocio (no se permiten reservas en el pasado, solo una cita próxima): reside en la capa de negocio. Un método estático ([static]) se llama sin crear un objeto: [Dates::today()].
11.11.2. src/Business/BusinessException.php
| <?php
// =========================================================================
// src/Business/BusinessException.php: la excepción que lanza la capa de negocio cuando se
// infringe una REGLA DE NEGOCIO (login ya en uso, médico que aún tiene
// citas, horario ya reservado...). No lleva un texto, sino una
// CLAVE de traducción (p. ej. "ERRORS.LOGIN_TAKEN"): es la capa web la que
// la traducirá al francés o al inglés al mostrar la página (véase translations).
//
// Una BusinessException no es una anomalía: es una respuesta normal ("este login
// ya está en uso"), que se muestra al usuario. Cualquier otra excepción es una
// verdadera anomalía, que termina en la página de error 500.
// =========================================================================
namespace App\Business;
use RuntimeException;
use Throwable;
class BusinessException extends RuntimeException
{
public function __construct(
// clave de traducción del mensaje
public readonly string $key,
// posibles parámetros del mensaje ({minutes}...)
public readonly array $params = [],
?Throwable $previous = null,
) {
parent::__construct($key, 0, $previous);
}
}
|
La excepción que se lanza cuando se viola una regla de negocio. No lleva texto, sino una clave de traducción ([ERRORS.LOGIN_TAKEN]) y sus parámetros: la capa web la traducirá al idioma de la página (Ejemplo 22). La capa de negocio no sabe nada de los idiomas de la interfaz. [RuntimeException] es una subclase de [PHP]. Las propiedades del constructor [public readonly] se declaran e inicializan mediante la promoción de propiedades del constructor (Ejemplo 03); [parent::__construct($key, 0, $previous)] llama al constructor de [RuntimeException], pasándole el mensaje, el código y la excepción anterior (la que causó esta, por ejemplo un error de la base de datos: aparece en el registro junto con la nueva).
11.11.3. src/Business/PersonData.php
| <?php
// src/Business/PersonData.php: los datos ingresados en un formulario de "médico" o "cliente",
// tal como la capa web los pasa a la capa de negocio.
namespace App\Business;
readonly class PersonData
{
public function __construct(
public string $title, // Mr, Mme, Melle
public string $lastName,
public string $firstName,
// creación: opcional (null), por defecto el apellido en minúsculas
// modificación: opcional, el login no cambia si está ausente
public ?string $login = null,
// creación: opcional, por defecto el login
// modificación: opcional, la contraseña no cambia si está ausente
public ?string $password = null,
// modificación: la versión del registro cuando se mostró el
// formulario (bloqueo optimista)
public ?int $version = null,
) {
}
}
|
Los datos de un formulario de «persona», tal como los transmite la capa web a la capa de negocio: una clase [readonly]. El nombre de usuario, la contraseña y la versión son opcionales ([?string], [?int], valor predeterminado [null]); los comentarios explican qué significa su ausencia.
11.11.4. src/Business/Business.php
| <?php
// =========================================================================
// src/Business/Business.php: el CONTRATO de la capa de negocio: lecturas, agenda,
// citas, gestión de médicos y clientes.
//
// Una INTERFAZ describe los métodos que debe tener una clase, sin decir cómo
// se escriben. BusinessService (la capa de negocio) y ApplicationModel (el caché
// de la capa web) la implementan ambos; PHP verifica, al cargar
// la clase, que no falte ningún método.
//
// ?Type: un resultado que puede estar ausente (null: un médico que no existe...).
// list<Doctor> (en un comentario /** */): un arreglo de médicos, indexado 0, 1, 2...
// =========================================================================
namespace App\Business;
use App\Domain\DoctorDaySchedule;
use App\Entity\Client;
use App\Entity\Slot;
use App\Entity\Doctor;
use App\Entity\Appointment;
use DateTimeImmutable;
interface Business
{
// ------------------------------------------------ lecturas
/** @return list<Client> */
public function getAllClients(): array;
/** @return list<Doctor> */
public function getAllDoctors(): array;
/** @return list<Slot> */
public function getAllSlots(int $doctorId): array;
/** @return list<Appointment> */
public function getDoctorDayAppointments(int $doctorId, DateTimeImmutable $day): array;
public function getClientById(int $id): ?Client;
public function getDoctorById(int $id): ?Doctor;
public function getAppointmentById(int $id): ?Appointment;
public function getSlotById(int $id): ?Slot;
public function getDoctorDaySchedule(int $doctorId, DateTimeImmutable $day): ?DoctorDaySchedule;
// el cliente (paciente) cuya cuenta de usuario es [$userId]
public function getClientByUserId(int $userId): ?Client;
// las citas de un cliente, de hoy o futuras, con horario y médico
/** @return list<Appointment> */
public function getClientUpcomingAppointments(int $clientId): array;
// ------------------------------------------------ citas (ADMIN, DOCTOR, USER)
// lanza una BusinessException si:
// - el día ya pasó ("ERRORS.PAST_DATE");
// - el paciente ya tiene una cita próxima ("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
// - el horario ya está ocupado ese día ("ERRORS.SLOT_ALREADY_BOOKED").
public function addAppointment(DateTimeImmutable $day, Slot $slot, Client $client): Appointment;
public function deleteAppointment(Appointment $appointment): void;
// ------------------------------------------------ médicos (ADMIN)
// crea el médico Y su cuenta de usuario (rol DOCTOR)
public function addDoctor(PersonData $data): Doctor;
// modifica el médico Y su cuenta de usuario
public function editDoctor(int $id, PersonData $data): Doctor;
// elimina el médico, sus horarios Y su cuenta - se rechaza si tiene citas
public function deleteDoctor(int $id): void;
// ------------------------------------------------ clientes
// (el ADMIN; addClient también se usa para el registro de un paciente,
// editClient y deleteClient los usa el paciente para su propia cuenta)
// crea el cliente Y su cuenta de usuario (rol USER)
public function addClient(PersonData $data): Client;
public function editClient(int $id, PersonData $data): Client;
// elimina el cliente, su cuenta Y todas sus citas (pasadas y futuras)
public function deleteClient(int $id): void;
}
|
El contrato de la capa de negocio: una interfaz (ejemplo 06), la lista de métodos, sin su código. Las operaciones de lectura devuelven entidades o arreglos de entidades (el comentario [@return list<Client>] especifica su contenido); [?Client]: un cliente, o [null] si no existe. Los comentarios especifican las reglas de cada operación de escritura y las claves de las [BusinessException] que puede lanzar.
11.11.5. src/Business/Descriptor.php
| <?php
// src/Business/Descriptor.php: todo lo que distingue a un médico de un cliente para las
// reglas de negocio (véase BusinessService). Médicos y clientes siguen las
// mismas reglas: el código común se escribe UNA SOLA VEZ y se parametriza mediante un descriptor.
namespace App\Business;
use App\Dao\PersonDao;
use App\Entity\Role;
use Closure;
readonly class Descriptor
{
public function __construct(
public PersonDao $dao,
public Role $role, // DOCTOR o USER
// la clase de la entidad, para crear una persona: Doctor::class o Client::class
public string $entityClass,
public string $notFoundKey, // mensaje si la persona no existe
public string $alreadyExistsKey, // mensaje si ya existen los mismos nombre y apellido
// opcional (null): si está presente, la eliminación se RECHAZA mientras la
// persona tenga citas (countAppointments(id) > 0), con el mensaje hasAppointmentsKey
public ?Closure $countAppointments,
public ?string $hasAppointmentsKey,
// opcional: lo que debe eliminarse ANTES que la persona (las filas que
// la referencian mediante una clave externa); recibe su id
public ?Closure $beforeDelete,
) {
}
}
|
Los médicos y los clientes siguen las mismas reglas de gestión, con algunas diferencias menores: el DAO, el rol de la cuenta, la clase de la entidad que se va a crear, los mensajes de error y la regla de eliminación. Este descriptor reúne estos detalles; el código común los lee. Dos propiedades son funciones ([?Closure]: una función, o [null]): el conteo de citas, que impide la eliminación (solo para médicos), y la eliminación de las referencias a la persona.
11.11.6. src/Business/BusinessService.php
| <?php
// =========================================================================
// src/Business/BusinessService.php: la implementación de la capa de negocio.
//
// La gestión de médicos y clientes obedece tres reglas de negocio:
//
// 1. una persona (médico o cliente) y su cuenta de usuario van SIEMPRE
// juntas: se crean, modifican y eliminan juntas, en la misma
// TRANSACCIÓN - o todo se realiza, o no se escribe nada;
// 2. el login es único en toda la aplicación, y dos médicos (o dos
// clientes) no pueden tener el mismo nombre y apellido;
// 3. eliminación:
// - un MÉDICO que tiene citas no puede eliminarse (sus pacientes
// perderían su cita sin ser avisados): primero deben
// cancelarse. Sus horarios desaparecen con él;
// - un CLIENTE, en cambio, desaparece con TODAS sus citas (pasadas y futuras) -
// ya sea que la eliminación provenga del ADMIN o del propio paciente.
//
// Y dos reglas para reservar, sea cual sea el rol de quien
// reserva (ADMIN, DOCTOR o el propio paciente):
// 4. ninguna cita en el pasado;
// 5. un paciente tiene solo UNA cita próxima a la vez.
//
// Médicos y clientes siguen exactamente las mismas reglas: el código común se
// escribe UNA SOLA VEZ (métodos privados xxxPerson) y se parametriza mediante un descriptor
// que indica de qué tipo de persona se trata.
//
// Las TRANSACCIONES las abre el método transaction (al final del archivo),
// que además traduce a BusinessException los errores que informa la base de datos.
// =========================================================================
namespace App\Business;
use App\Dao\ClientDao;
use App\Dao\SlotDao;
use App\Dao\DoctorDao;
use App\Dao\AppointmentDao;
use App\Dao\UserDao;
use App\Domain\DoctorDaySchedule;
use App\Domain\DoctorDaySlot;
use App\Entity\Client;
use App\Entity\Slot;
use App\Entity\Doctor;
use App\Entity\Person;
use App\Entity\Role;
use App\Entity\Appointment;
use App\Entity\User;
use Closure;
use DateTimeImmutable;
use Doctrine\DBAL\Exception\UniqueConstraintViolationException;
use Doctrine\ORM\EntityManagerInterface;
use Doctrine\ORM\OptimisticLockException;
use Symfony\Component\PasswordHasher\Hasher\PasswordHasherFactoryInterface;
use Symfony\Component\PasswordHasher\PasswordHasherInterface;
class BusinessService implements Business
{
// -----------------------------------------------------------------------
// Errores de la base de datos -> BusinessException
//
// Cuando una restricción UNIQUE rechaza una escritura, Doctrine lanza una
// UniqueConstraintViolationException, cuyo mensaje es el de MySQL. Cita el
// NOMBRE de la restricción:
// Duplicate entry 'Marie-PELISSIER' for key 'doctors.unq_doctors_first_name_last_name'
// (MySQL 8 antepone al nombre el de la tabla, MariaDB no). Por eso
// el script SQL NOMBRA todas sus restricciones.
// -----------------------------------------------------------------------
private const CONSTRAINT_MESSAGES = [
'unq_users_login' => 'ERRORS.LOGIN_TAKEN',
'unq_doctors_first_name_last_name' => 'ERRORS.DOCTOR_ALREADY_EXISTS',
'unq_clients_first_name_last_name' => 'ERRORS.PATIENT_ALREADY_EXISTS',
'unq1_appointments' => 'ERRORS.SLOT_ALREADY_BOOKED',
];
private const CONSTRAINT = "/for key '(?:[^'.]*\\.)?([^']+)'/";
private Descriptor $doctor;
private Descriptor $client;
// el hash de las contraseñas (bcrypt, véase config/packages/security.yaml)
private PasswordHasherInterface $hasher;
// todas las dependencias las proporciona el contenedor de servicios de Symfony
// (inyección de dependencias, véase el ejemplo 06)
public function __construct(
private EntityManagerInterface $em,
private DoctorDao $doctors,
private ClientDao $clients,
private SlotDao $slots,
private AppointmentDao $appointments,
private UserDao $users,
PasswordHasherFactoryInterface $hashers,
) {
$this->hasher = $hashers->getPasswordHasher(User::class);
$this->doctor = new Descriptor(
dao: $doctors,
role: Role::DOCTOR,
entityClass: Doctor::class,
notFoundKey: 'ERRORS.DOCTOR_NOT_FOUND',
alreadyExistsKey: 'ERRORS.DOCTOR_ALREADY_EXISTS',
// $appointments->countByDoctor(...): el propio método, como Closure
// (sintaxis llamada "first-class callable")
countAppointments: $appointments->countByDoctor(...),
hasAppointmentsKey: 'ERRORS.DOCTOR_HAS_APPOINTMENTS',
// un médico sin citas aún puede tener horarios:
// no tienen sentido sin él, se eliminan con él (de lo contrario la
// clave externa slots.doctor_id impediría la eliminación)
beforeDelete: $slots->deleteByDoctor(...));
$this->client = new Descriptor(
dao: $clients,
role: Role::USER,
entityClass: Client::class,
notFoundKey: 'ERRORS.PATIENT_NOT_FOUND',
alreadyExistsKey: 'ERRORS.PATIENT_ALREADY_EXISTS',
// sin countAppointments: la eliminación de un cliente nunca se rechaza;
// sus citas (pasadas y futuras) se eliminan con él (de lo contrario la
// clave externa appointments.client_id impediría la eliminación)
countAppointments: null,
hasAppointmentsKey: null,
beforeDelete: $appointments->deleteByClient(...));
}
// =======================================================================
// lecturas
// =======================================================================
public function getAllClients(): array
{
return $this->clients->list();
}
public function getAllDoctors(): array
{
return $this->doctors->list();
}
public function getAllSlots(int $doctorId): array
{
return $this->slots->listByDoctor($doctorId);
}
public function getDoctorDayAppointments(int $doctorId, DateTimeImmutable $day): array
{
return $this->appointments->doctorDayAppointments($doctorId, $day);
}
public function getClientById(int $id): ?Client
{
return $this->clients->read($id);
}
public function getDoctorById(int $id): ?Doctor
{
return $this->doctors->read($id);
}
public function getAppointmentById(int $id): ?Appointment
{
return $this->appointments->read($id);
}
public function getSlotById(int $id): ?Slot
{
return $this->slots->read($id);
}
public function getClientByUserId(int $userId): ?Client
{
return $this->clients->readByUser($userId);
}
public function getClientUpcomingAppointments(int $clientId): array
{
return $this->appointments->clientUpcomingAppointments($clientId, Dates::today());
}
// la agenda de un médico en un día dado: sus horarios y, para cada uno, la
// cita reservada ese día (null si está libre)
public function getDoctorDaySchedule(int $doctorId, DateTimeImmutable $day): ?DoctorDaySchedule
{
$doctor = $this->getDoctorById($doctorId);
if ($doctor === null) {
return null;
}
// número de horario -> cita reservada en ese horario
$bookings = [];
foreach ($this->getDoctorDayAppointments($doctorId, $day) as $appointment) {
$bookings[$appointment->getSlot()->getId()] = $appointment;
}
// array_map: aplica la función a cada horario y devuelve el arreglo de los resultados
$doctorDaySlots = array_map(
fn (Slot $slot) => new DoctorDaySlot($slot, $bookings[$slot->getId()] ?? null),
$this->getAllSlots($doctorId));
return new DoctorDaySchedule($doctor, $day, $doctorDaySlots);
}
// =======================================================================
// citas
// =======================================================================
// -----------------------------------------------------------------------
// reserva, en una transacción:
// 1. ninguna cita en el pasado;
// 2. BLOQUEAMOS la fila del paciente (SELECT ... FOR UPDATE): si el mismo
// paciente reserva dos horarios al mismo tiempo (dos pestañas, doble
// clic...), la segunda transacción espera el fin de la primera - y entonces ve la
// cita que esta acaba de crear;
// 3. solo una cita próxima por paciente;
// 4. por último la inserción. Si el horario acaba de ser tomado por OTRO paciente,
// es la restricción SQL unq1_appointments (day, slot_id) la que rechaza
// la inserción - traducida a BusinessException por transaction().
// -----------------------------------------------------------------------
public function addAppointment(DateTimeImmutable $day, Slot $slot, Client $client): Appointment
{
return $this->transaction(function () use ($day, $slot, $client) {
$today = Dates::today();
if ($day < $today) {
throw new BusinessException('ERRORS.PAST_DATE');
}
$patientId = $this->clients->lock($client->getId())
?? throw new BusinessException('ERRORS.PATIENT_NOT_FOUND');
if ($this->appointments->countClientUpcoming($patientId, $today) > 0) {
throw new BusinessException('ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT');
}
$appointment = new Appointment($day, $slot, $client);
$this->appointments->add($appointment);
return $appointment;
});
}
public function deleteAppointment(Appointment $appointment): void
{
$this->transaction(fn () => $this->appointments->remove($appointment));
}
// =======================================================================
// médicos y clientes - los métodos públicos delegan en los métodos
// privados comunes, con el descriptor adecuado
// =======================================================================
public function addDoctor(PersonData $data): Doctor
{
return $this->addPerson($this->doctor, $data);
}
public function editDoctor(int $id, PersonData $data): Doctor
{
return $this->editPerson($this->doctor, $id, $data);
}
public function deleteDoctor(int $id): void
{
$this->deletePerson($this->doctor, $id);
}
public function addClient(PersonData $data): Client
{
return $this->addPerson($this->client, $data);
}
public function editClient(int $id, PersonData $data): Client
{
return $this->editPerson($this->client, $id, $data);
}
// el cliente, su cuenta Y todas sus citas (ADMIN, o el propio paciente
// desde "Manage my account": mismo método, misma regla)
public function deleteClient(int $id): void
{
$this->deletePerson($this->client, $id);
}
// -----------------------------------------------------------------------
// creación: la cuenta de usuario Y la persona (que la referencia), en UNA
// transacción. Doctrine inserta primero la cuenta y luego la persona, cuya clave
// externa [user] recibe el id que la base de datos acaba de generar para la cuenta.
// -----------------------------------------------------------------------
private function addPerson(Descriptor $d, PersonData $data): Person
{
$lastName = mb_strtoupper(trim($data->lastName));
$firstName = trim($data->firstName);
// las reglas de la base de datos dbrdvmedecins2: login = apellido en minúsculas,
// contraseña = login - a menos que el ADMIN (o el paciente) haya ingresado otros
$login = mb_strtolower($data->login ?: $lastName);
$password = $data->password ?: $login;
return $this->transaction(function () use ($d, $data, $lastName, $firstName, $login, $password) {
$this->checkPersonUnique($d, $firstName, $lastName, null);
$this->checkLoginFree($login);
// hash: el hash bcrypt de la contraseña
$user = new User($login, $this->hasher->hash($password), "$firstName $lastName", $d->role);
$this->users->add($user);
// new ($d->entityClass)(...): una instancia de la clase cuyo nombre está en la
// propiedad [entityClass] del descriptor (Doctor o Client)
$person = new ($d->entityClass)($data->title, $lastName, $firstName, $user);
$d->dao->add($person);
return $person;
});
}
// -----------------------------------------------------------------------
// modificación: la persona Y su cuenta (el nombre mostrado "firstName LASTNAME" debe
// seguirla; el login y la contraseña solo cambian si se han ingresado).
// -----------------------------------------------------------------------
private function editPerson(Descriptor $d, int $id, PersonData $data): Person
{
return $this->transaction(function () use ($d, $id, $data) {
$person = $d->dao->read($id) ?? throw new BusinessException($d->notFoundKey);
// bloqueo optimista: si la versión en la base de datos ya no es la del
// formulario, alguien ha modificado este registro mientras tanto - lo rechazamos
// en lugar de sobrescribir en silencio sus cambios
if ($data->version !== null && $data->version !== $person->getVersion()) {
throw new BusinessException('ERRORS.CONCURRENT_UPDATE');
}
$lastName = mb_strtoupper(trim($data->lastName));
$firstName = trim($data->firstName);
$this->checkPersonUnique($d, $firstName, $lastName, $id);
$person->edit($data->title, $lastName, $firstName);
// su cuenta: el nombre mostrado y, si se han ingresado, el login y la
// contraseña
$account = $person->getAccount();
$account->setName("$firstName $lastName");
$login = $data->login ? mb_strtolower($data->login) : null;
if ($login !== null && $login !== $account->getLogin()) {
$this->checkLoginFree($login);
$account->setLogin($login);
}
if ($data->password) {
$account->setPassword($this->hasher->hash($data->password));
}
// nada más que hacer: al final de la transacción, Doctrine envía los
// UPDATE de las filas modificadas, con su bloqueo optimista
// UPDATE ... SET ..., version = version + 1 WHERE id = ? AND version = ?
// Si el registro fue modificado DESPUÉS de la lectura anterior, ninguna fila
// se modifica y Doctrine lanza una OptimisticLockException
return $person;
});
}
// -----------------------------------------------------------------------
// eliminación, en UNA transacción, en el orden que imponen las claves
// externas:
// 1. posible rechazo si quedan citas (médico);
// 2. lo que referencia a la persona (horarios de un médico, citas de un
// cliente), de inmediato;
// 3. la persona (referencia su cuenta), luego su cuenta: Doctrine las
// elimina en ese orden al final de la transacción.
// -----------------------------------------------------------------------
private function deletePerson(Descriptor $d, int $id): void
{
$this->transaction(function () use ($d, $id) {
$person = $d->dao->read($id) ?? throw new BusinessException($d->notFoundKey);
if ($d->countAppointments !== null && ($d->countAppointments)($id) > 0) {
throw new BusinessException($d->hasAppointmentsKey);
}
if ($d->beforeDelete !== null) {
($d->beforeDelete)($id);
}
$d->dao->remove($person);
$this->users->remove($person->getAccount());
});
}
// rechaza nombres y apellidos ya usados por OTRA persona del mismo tipo
// ($currentId: la persona que se modifica, que por supuesto tiene derecho
// a conservar su propio nombre y apellido; null en una creación)
private function checkPersonUnique(Descriptor $d, string $firstName, string $lastName, ?int $currentId): void
{
$namesake = $d->dao->namesake($firstName, $lastName);
if ($namesake !== null && $namesake->getId() !== $currentId) {
throw new BusinessException($d->alreadyExistsKey);
}
}
private function checkLoginFree(string $login): void
{
if ($this->users->readByLogin($login) !== null) {
throw new BusinessException('ERRORS.LOGIN_TAKEN');
}
}
// -----------------------------------------------------------------------
// ejecuta [$work] en una transacción (wrapInTransaction, véase el ejemplo 28):
// si la función termina normalmente, Doctrine envía las escrituras pendientes
// a la base de datos (flush) y luego confirma la transacción (COMMIT); si una
// excepción sale de ella (incluida BusinessException), ROLLBACK: no se escribe nada.
//
// Las verificaciones de "login libre" y "nombre + apellido únicos" se hacen ANTES de la
// escritura, para dar un mensaje claro. Pero dos ADMIN podrían
// guardar el mismo login (o el mismo médico) al mismo tiempo: en este
// raro caso, es una restricción SQL de unicidad la que rechaza la segunda escritura.
// Del mismo modo, dos modificaciones simultáneas del mismo registro las decide el
// bloqueo optimista. Por eso capturamos estos errores ALREDEDOR de la transacción,
// para traducirlos a BusinessException. Cualquier otro error es una verdadera
// anomalía: lo dejamos subir.
// Tras una excepción, Doctrine CIERRA el entity manager: la solicitud actual
// ya no debe escribir nada (los controladores redirigen o
// vuelven a mostrar un formulario).
// -----------------------------------------------------------------------
private function transaction(Closure $work): mixed
{
try {
return $this->em->wrapInTransaction($work);
} catch (UniqueConstraintViolationException $e) {
if (preg_match(self::CONSTRAINT, $e->getMessage(), $m)
&& isset(self::CONSTRAINT_MESSAGES[$m[1]])) {
throw new BusinessException(self::CONSTRAINT_MESSAGES[$m[1]], previous: $e);
}
throw $e;
} catch (OptimisticLockException $e) {
throw new BusinessException('ERRORS.CONCURRENT_UPDATE', previous: $e);
}
}
}
|
El archivo más importante de la aplicación. Lo recorreremos por temas.
11.11.6.1. Dependencias y descriptores
Líneas 86–124: el constructor recibe del contenedor el administrador de entidades (para las transacciones), las cinco instancias de DAO y la fábrica de servicios de hash ([PasswordHasherFactoryInterface]), a la que se le pide el de las cuentas: [getPasswordHasher(User::class)] proporciona el servicio que aplica el algoritmo elegido para la clase [User] en [security.yaml] ([bcrypt], 10 iteraciones). A continuación vienen los dos descriptores. Los argumentos con nombre ([dao: $doctors], ejemplo 01) hacen legible la llamada. [$appointments->countByDoctor(...)] (con tres puntos entre paréntesis) no tiene ningún significado especial: es la sintaxis de [PHP] 8.1 que crea, a partir de un método, un [Closure], una función que se llamará más tarde ([($d->countAppointments)($id)], línea 359). Un médico se elimina junto con sus franjas horarias ([deleteByDoctor]), pero no si tiene citas; un cliente se elimina junto con todas sus citas ([deleteByClient]).
11.11.6.2. Operaciones de lectura y calendario
Las operaciones de lectura (líneas 130–178) delegan en la capa DAO. La agenda de un médico (líneas 182–198) se calcula: el médico, sus franjas horarias y las citas de ese día. Las citas se almacenan en un arreglo indexado por número de franja: [$bookings[$slot->getId()] ?? null] devuelve la cita de una franja, o [null] si la franja está libre. [array_map] convierte cada franja horaria en [DoctorDaySlot].
11.11.6.3. Programar una cita
Líneas 216–232: cuatro pasos, en una sola transacción.
- Sin citas en el pasado: los objetos [DateTimeImmutable] admiten los operadores habituales ([<], [>=]...);
- el registro del paciente se bloquea ([lock], [SELECT ... FOR UPDATE]). ¿Por qué? La regla «solo una cita próxima por paciente» se verifica mediante un conteo (tercer paso) y luego se realiza la inserción (cuarto paso). Si el mismo paciente reserva dos franjas horarias al mismo tiempo (dos pestañas, un doble clic), ambas transacciones podrían contar cero citas y luego insertar cada una la suya: se violaría la regla. Con el bloqueo, la segunda transacción espera a que termine la primera y luego cuenta... una cita. [?? throw new BusinessException(...)]: si el cliente ya no existe, [lock] devuelve [null], y el operador [??] evalúa su segundo operando, que lanza la excepción (desde [PHP] 8, [throw] es una expresión);
- conteo de las citas próximas;
- inserción, al final de la transacción. Si la franja horaria acaba de ser tomada por otro paciente, la restricción de la base de datos [unq1_appointments] rechaza la inserción: el método [transaction] traduce este error en [BusinessException].
11.11.6.4. Gestión de médicos y pacientes
Los métodos públicos (líneas 244–274) llaman a los métodos privados compartidos, usando el descriptor correcto.
- Líneas 281–302: la creación. El apellido se escribe en mayúsculas ([mb_strtoupper]: la versión de [strtoupper] que admite letras acentuadas), y al nombre y al apellido se les quitan los espacios innecesarios ([trim]). De forma predeterminada, el nombre de usuario es el apellido en minúsculas y la contraseña es el nombre de usuario (según las reglas de las cuentas de demostración): [$a ?: $b] equivale a [$a] si es «verdadero» (ni [null] ni una cadena vacía), y a [$b] en caso contrario. En la transacción: las validaciones (el nombre y el apellido pueden tener cualquier valor, el nombre de usuario puede tener cualquier valor), luego la cuenta, cuya contraseña se transforma en hash ([hash]), y después la persona, que hace referencia a la cuenta. [new ($d->entityClass)(...)] crea un objeto de la clase cuyo nombre está en la propiedad [entityClass] del descriptor (los paréntesis son obligatorios alrededor de una expresión). [Doctrine] insertará la cuenta antes que la persona: conoce las relaciones entre las entidades y deduce el orden de los objetos [INSERT]. [use (...)]: una función anónima ordinaria ([function () use ($d, ...)]) no puede ver las variables del método que la contiene; [use] se las pasa (una función flecha, [fn () =>], las ve por sí sola, pero solo puede contener una expresión);
- Líneas 308–344: la actualización, con dos bloqueos optimistas. El primero es una comparación (líneas 316–318): la versión del formulario (campo oculto, Ejemplo 28) debe coincidir con la del registro en la base de datos; de lo contrario, alguien modificó el registro entre el momento en que se mostró el formulario y el momento en que se envió. El segundo es el de [Doctrine]: los registros [UPDATE] enviados al final de la transacción llevan la condición [WHERE version = ?], que detecta un cambio ocurrido entre la lectura y la escritura ([OptimisticLockException]). Sigue la cuenta: su nombre para mostrar («firstName LASTNAME») siempre se actualiza; su nombre de usuario y su contraseña se actualizan solo si se ingresaron; su propio bloqueo optimista también protege la fila de la tabla [users]. No hay nada que «guardar»: la entidad leída está bajo el seguimiento del administrador de entidades, que escribirá sus cambios. Al final de la transacción, [Doctrine] almacena las nuevas versiones de las entidades: quien llama recibe la persona actualizada;
- líneas 355–368: la eliminación, en el orden que dictan las claves externas: primero, los registros que hacen referencia a la persona (franjas horarias o citas), seguidos de inmediato por el [DELETE] del DAO; luego la persona y después su cuenta, que [Doctrine] elimina en ese orden al final de la transacción. El orden inverso sería rechazado por la base de datos: no se puede eliminar una fila a la que todavía hace referencia una clave externa;
- líneas 373–387: la persona que se modifica puede conservar su propio nombre y apellido; [$currentId] equivale a [null] en una creación.
11.11.6.5. Transacciones y errores de la base de datos
Líneas 406–419: todas las escrituras usan este método. [wrapInTransaction] ejecuta la función dentro de una transacción (Ejemplo 28): [flush], luego [COMMIT] si termina con normalidad, y [ROLLBACK] si se produce una excepción, incluida una [BusinessException]: una violación de una regla a mitad de una operación no deja rastro. Las comprobaciones de «nombre de usuario disponible» y de «nombre y apellido disponibles» se realizan antes de escribir, para dar un mensaje claro. Sin embargo, dos administradores podrían intentar registrar el mismo nombre de usuario al mismo tiempo: cada uno lo encuentra disponible y el segundo [INSERT] es rechazado por la restricción [unq_users_login]. [Doctrine] lanza entonces una [UniqueConstraintViolationException] (ejemplo 28), cuyo mensaje es el de [MySQL]; contiene el nombre de la restricción violada:
| SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry 'dupont' for key 'users.unq_users_login'
|
La expresión regular de la línea 75 extrae este nombre ([MySQL] 8 lo antepone con el nombre de la tabla, [users.unq_users_login], pero [MariaDB] no: la parte [(?:[^'.]*\.)?] acepta ambas formas), y la tabla de las líneas 68–73 proporciona la clave del mensaje. Cualquier otra violación de restricción es una verdadera anomalía: se vuelve a lanzar ([throw $e]) y dará lugar a una página de error 500. Por último, el conflicto detectado por el bloqueo optimista de [Doctrine] ([OptimisticLockException]) se convierte en la misma [BusinessException] que la detectada por la comparación de versiones.
Recordemos una consecuencia de [wrapInTransaction] (Ejemplo 28): después de una excepción, el administrador de entidades queda cerrado y ya no puede escribir durante la solicitud en curso. Los controladores lo tienen en cuenta: después de una [BusinessException], redirigen o vuelven a mostrar un formulario sin escribir nada más.
11.12. Autenticación
La carpeta [src/Security] incluye los ejemplos 25 a 27, con usuarios en la base de datos y algunas medidas de seguridad adicionales. Repasemos el principio (Ejemplo 25): el cortafuegos [main] de [config/packages/security.yaml] es sin estado ([stateless]); en cada solicitud, un autenticador de diseño propio lee el token JWT de la cookie [rdvmedecins_jwt] e identifica al usuario; las reglas [access_control] determinan entonces el acceso a las páginas.
11.12.1. src/Security/ConnectedUser.php
| <?php
// =========================================================================
// src/Security/ConnectedUser.php: el usuario conectado, tal como lo describe
// su token JWT (véase el ejemplo 25). UserInterface: la interfaz que Symfony espera de los
// usuarios autenticados ($this->getUser() en un controlador, #[CurrentUser],
// app.user e is_granted() en una vista...).
//
// Los claims de nuestros tokens (véase AuthService::tokenCookie):
// sub : el id de la cuenta de usuario (convención JWT: "subject"), como texto
// login : el login
// name : el nombre mostrado ("Marie PELISSIER"), para la barra de navegación
// role : ADMIN, DOCTOR o USER
// iat, exp : fechas de creación y de expiración del token
//
// Este objeto NO proviene de la base de datos: se reconstruye, en cada solicitud, a partir
// del token, cuya firma garantiza el contenido.
// =========================================================================
namespace App\Security;
use App\Entity\Role;
use Symfony\Component\Security\Core\User\UserInterface;
readonly class ConnectedUser implements UserInterface
{
public function __construct(
public int $userId,
public string $login,
public string $name,
public Role $role,
) {
}
// el usuario descrito por los claims de un token ya verificado; null si falta un claim
// o no tiene la forma esperada. Role::tryFrom: null para un rol desconocido
public static function of(array $claims): ?self
{
$role = Role::tryFrom((string) ($claims['role'] ?? ''));
if (! isset($claims['sub'], $claims['login'], $claims['name']) || $role === null
|| ! ctype_digit((string) $claims['sub'])) {
return null;
}
return new self((int) $claims['sub'], (string) $claims['login'], (string) $claims['name'], $role);
}
public function isAdmin(): bool
{
return $this->role === Role::ADMIN;
}
public function isPatient(): bool
{
return $this->role === Role::USER;
}
// ---- la interfaz UserInterface: el identificador del usuario (su login)
// y sus roles en el sentido de Symfony (ROLE_ADMIN, ROLE_DOCTOR o ROLE_USER, véase
// la enumeración Role), verificados por las reglas access_control de
// config/packages/security.yaml
public function getUserIdentifier(): string
{
return $this->login;
}
public function getRoles(): array
{
return [$this->role->symfonyRole()];
}
}
|
El usuario conectado, tal como lo describe su token: el ID de su cuenta, su nombre de usuario, su nombre y su rol. Como [User] en el Ejemplo 25, implementa la interfaz [UserInterface], que [Symfony] espera de los usuarios autenticados. Este objeto no proviene de la base de datos: se reconstruye en cada solicitud a partir del token, cuya firma garantiza su contenido. Por lo tanto, la aplicación no lee la cuenta de la base de datos en cada solicitud. La clase es [readonly] (Ejemplo 08): sus propiedades públicas no pueden modificarse después de la construcción.
- Líneas 36–44: el usuario se describe mediante los datos (claims) de un token que ya ha sido verificado, o [null] si falta alguno de los datos o no tiene el formato esperado. Un token correctamente firmado nunca debería estar mal formado; sin embargo, la clave secreta podría compartirse con otra aplicación, que podría generar tokens distintos: ser cauteloso no cuesta nada. [Role::tryFrom] devuelve el rol, o [null] si el valor es desconocido; [ctype_digit] verifica que una cadena esté formada solo por dígitos;
- líneas 46–54: dos preguntas que las vistas y los controladores formulan con frecuencia;
- Líneas 60–68: la interfaz [UserInterface]. El identificador del usuario es su nombre de usuario; sus roles, tal como los define [Symfony], se limitan a un único rol, [ROLE_ADMIN], [ROLE_DOCTOR] o [ROLE_USER], calculado por la enumeración [Role]. Estos son los que verifican las reglas [access_control], el atributo [#[IsGranted]], y la función [is_granted] de las vistas. (El método [eraseCredentials], que borraba la contraseña en texto plano después del inicio de sesión, se eliminó de la interfaz con [Symfony] 8.)
11.12.2. src/Security/AuthService.php
| <?php
// =========================================================================
// src/Security/AuthService.php: la lógica de autenticación:
// - validate() : verifica un par login / contraseña;
// - tokenCookie() : construye el token JWT de un usuario validado y la
// cookie que lo transporta;
// - currentUser() : el usuario descrito por un token.
//
// ¿Por dónde viaja el token JWT? En una COOKIE (véase el ejemplo 25): un navegador
// que muestra páginas HTML ordinarias la presenta así por sí mismo, en cada
// solicitud. Las opciones de esta cookie importan para la seguridad:
// - HttpOnly: el JavaScript de la página no puede leer la cookie (por lo tanto, un
// script inyectado no podría robar el token);
// - SameSite=Lax: el navegador NO envía la cookie con un POST proveniente de otro
// sitio (primera protección contra el llamado ataque CSRF; la segunda es
// el token anti-CSRF de los formularios);
// - Secure: en producción (HTTPS), la cookie nunca viaja sin cifrar;
// - duración: la cookie desaparece al mismo tiempo que expira el token.
// =========================================================================
namespace App\Security;
use App\Dao\UserDao;
use App\Entity\User;
use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use RuntimeException;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\PasswordHasher\Hasher\PasswordHasherFactoryInterface;
use Throwable;
class AuthService
{
// el nombre de la cookie que lleva el token
public const COOKIE = 'rdvmedecins_jwt';
// los parámetros del archivo .env: #[Autowire(env: ...)] (véase el ejemplo 25)
public function __construct(
private UserDao $users,
private PasswordHasherFactoryInterface $hashers,
#[Autowire(env: 'JWT_SECRET')] private string $secret,
#[Autowire(env: 'int:JWT_DURATION_MINUTES')] private int $duration,
#[Autowire(env: 'bool:COOKIE_SECURE')] private bool $cookieSecure,
) {
// HMAC-SHA256 requiere una clave de al menos 256 bits: lo decimos claramente,
// en lugar de dejar que la biblioteca falle más adelante
if (strlen($this->secret) < 32) {
throw new RuntimeException('JWT_SECRET must be at least 32 characters long (see .env).');
}
}
// null si el login no existe o si la contraseña es incorrecta. verify aplica el hash a la
// contraseña ingresada con la "sal" contenida en el hash almacenado y luego
// compara los dos resultados
public function validate(string $login, string $password): ?User
{
$user = $this->users->readByLogin($login);
if ($user === null
|| ! $this->hashers->getPasswordHasher(User::class)->verify($user->getPassword(), $password)) {
return null;
}
return $user;
}
// -----------------------------------------------------------------------
// el token JWT de [$user], en la cookie que lo transporta. El token está FIRMADO
// (HMAC-SHA256) con la clave secreta: el navegador puede leerlo (no está
// cifrado), pero no modificarlo - cualquier modificación invalidaría la
// firma.
// -----------------------------------------------------------------------
public function tokenCookie(User $user): Cookie
{
$now = time();
$claims = [
'sub' => (string) $user->getId(),
'login' => $user->getLogin(),
'name' => $user->getName(),
'role' => $user->getRole()->value,
'iat' => $now,
'exp' => $now + $this->duration * 60,
];
$token = JWT::encode($claims, $this->secret, 'HS256');
return Cookie::create(self::COOKIE, $token)
->withExpires($now + $this->duration * 60)
->withSecure($this->cookieSecure)
->withHttpOnly(true)
->withSameSite(Cookie::SAMESITE_LAX);
}
// borra la cookie del token: la respuesta lleva una cookie del mismo nombre, vacía y ya expirada
public static function clearCookie(Response $response): Response
{
$response->headers->clearCookie(self::COOKIE);
return $response;
}
// -----------------------------------------------------------------------
// el usuario descrito por un token; null si el token está expirado, falsificado o
// malformado. JWT::decode verifica la firma Y la fecha de expiración (claim exp).
// -----------------------------------------------------------------------
public function currentUser(string $token): ?ConnectedUser
{
try {
// decode devuelve un objeto; (array) lo convierte en un arreglo asociativo
$claims = (array) JWT::decode($token, new Key($this->secret, 'HS256'));
} catch (Throwable) {
return null;
}
return ConnectedUser::of($claims);
}
}
|
- línea 37: el nombre de la cookie del token, una constante de clase, leída mediante [AuthService::COOKIE];
- líneas 40–52: el servicio recibe la capa DAO de las cuentas; la fábrica de servicios de hash (la que corresponde a la clase [User], bcrypt, se declara en [security.yaml]) y tres parámetros del archivo [.env], mediante el atributo [#[Autowire(env: ...)]] (Ejemplo 25). Los prefijos [int:] y [bool:] convierten el texto de la variable de entorno. Si una clave es demasiado corta, se informa en cuanto se inicia el servicio, con un mensaje claro (véase «Problemas frecuentes»);
- Líneas 57–65: verificación de un nombre de usuario y una contraseña (Ejemplo 25), con la cuenta recuperada de la base de datos por la capa DAO. Obsérvese que este servicio usa directamente la capa DAO, sin pasar por la capa de negocio: la verificación de la contraseña no es una regla de negocio;
- Líneas 73–90: el token del usuario y la cookie que lo transporta. Las declaraciones son las mismas que en el Ejemplo 25, con el ID de la cuenta ([sub], una cadena, como lo exige el estándar) y el nombre de usuario. [Cookie::create] crea una cookie, a la que los métodos [with...] agregan características (cada uno devuelve una cookie nueva: el objeto es inmutable): su fecha de expiración (la del token), [Secure] (en producción, con HTTPS), [HttpOnly], y [SameSite=Lax] (véase el comentario de las líneas 9–18);
- líneas 93–97: eliminación de la cookie. [clearCookie(name)] agrega a la respuesta una cookie con el mismo nombre, vacía y ya expirada, de modo que el navegador la elimina. El método es estático: no requiere configuración y las clases que lo llaman no necesitan recibir el servicio;
- líneas 103–112: verificación del token (ejemplo 25).
11.12.3. src/Security/TokenAuthenticator.php
| <?php
// =========================================================================
// src/Security/TokenAuthenticator.php: el AUTENTICADOR del firewall (véase
// config/packages/security.yaml y el ejemplo 25): en cada solicitud, establece quién
// es el usuario, a partir del token JWT de la cookie [rdvmedecins_jwt].
//
// No rechaza nada por sí mismo: un token ausente o inválido deja al visitante
// ANÓNIMO. Son las reglas access_control las que luego rechazan el acceso a las
// páginas protegidas; un visitante anónimo rechazado pasa entonces al PUNTO DE ENTRADA (el
// método start), que lo envía de vuelta a la página de inicio de sesión.
// =========================================================================
namespace App\Security;
use App\Web\Flash;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Event\ResponseEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
use Symfony\Component\Security\Http\Authenticator\Passport\SelfValidatingPassport;
use Symfony\Component\Security\Http\EntryPoint\AuthenticationEntryPointInterface;
class TokenAuthenticator extends AbstractAuthenticator implements AuthenticationEntryPointInterface
{
// el atributo de la solicitud que señala un token inválido, para borrarlo
private const INVALID_TOKEN = '_invalid_token';
public function __construct(
private AuthService $auth,
private Flash $flash,
private UrlGeneratorInterface $urls,
) {
}
// el autenticador solo actúa si la solicitud lleva la cookie del token
public function supports(Request $request): ?bool
{
return $request->cookies->getString(AuthService::COOKIE) !== '';
}
// el token, verificado por AuthService, describe al usuario: el passport
// se valida solo y el badge devuelve directamente a este usuario (sin
// buscarlo en la base de datos, véase el ejemplo 25)
public function authenticate(Request $request): Passport
{
$user = $this->auth->currentUser($request->cookies->getString(AuthService::COOKIE))
?? throw new CustomUserMessageAuthenticationException('invalid token');
return new SelfValidatingPassport(new UserBadge($user->login, fn () => $user));
}
public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response
{
return null;
}
// un token inválido (expirado, falsificado): el visitante sigue anónimo (null) y la
// cookie se borrará de la respuesta, sea cual sea (véase clearInvalidToken)
public function onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response
{
$request->attributes->set(self::INVALID_TOKEN, true);
return null;
}
// -----------------------------------------------------------------------
// el PUNTO DE ENTRADA: un visitante anónimo pide una página protegida. Va a
// la página de inicio de sesión. Si tenía una cookie de token, significa que su token ya no
// es válido (expirado, falsificado): su sesión ha expirado y se lo decimos
// -----------------------------------------------------------------------
public function start(Request $request, ?AuthenticationException $authException = null): Response
{
if ($request->cookies->has(AuthService::COOKIE)) {
$this->flash->error('ERRORS.SESSION_EXPIRED');
}
return new RedirectResponse($this->urls->generate('login'));
}
// -----------------------------------------------------------------------
// un listener de kernel.response (véase el ejemplo 24), escrito en la misma clase:
// borra la cookie de un token inválido, en todas las respuestas
// -----------------------------------------------------------------------
#[AsEventListener(event: KernelEvents::RESPONSE)]
public function clearInvalidToken(ResponseEvent $event): void
{
if ($event->getRequest()->attributes->get(self::INVALID_TOKEN)) {
AuthService::clearCookie($event->getResponse());
}
}
}
|
El autenticador del Ejemplo 25, declarado en [security.yaml] ([custom_authenticators]). También sirve como punto de entrada del cortafuegos: implementa la interfaz [AuthenticationEntryPointInterface], y [Symfony] lo selecciona automáticamente, ya que es el único autenticador del cortafuegos.
- líneas 45–48: [supports] determina si el autenticador debe intervenir: solo si la solicitud contiene la cookie del token. Sin cookie, el visitante es anónimo y no se realiza ninguna otra acción;
- líneas 53–58: [authenticate] verifica el token. Un token no válido provoca una [AuthenticationException] (su subclase, [CustomUserMessageAuthenticationException], lleva un mensaje libre). En caso contrario, un pasaporte autovalidado ([SelfValidatingPassport]: no hay contraseña que verificar; la firma del token sirve como contraseña), cuyo usuario se construye a partir del token sin buscarlo en la base de datos;
- líneas 60–63: después de una autenticación exitosa, [null]: la solicitud continúa hacia la acción solicitada;
- líneas 67–71: después de un fallo (token expirado o falsificado), también [null]: el visitante sigue siendo anónimo. Las reglas [access_control] redirigirán al visitante a la página de inicio de sesión si solicita una página protegida, pero puede ver las páginas públicas (¡incluida la propia página de inicio de sesión!). El único indicio está en un atributo de la solicitud que indica que debe eliminarse la cookie;
- líneas 78–84: el punto de entrada, al que llama el cortafuegos cuando un visitante anónimo solicita una página protegida: una redirección a la página de inicio de sesión. Si la solicitud contenía una cookie de token, significa que ese token ya no es válido: se muestra el mensaje «Su sesión ha expirado: inicie sesión de nuevo.» (un mensaje emergente, que se verá más adelante);
- Líneas 90–96: un escucha del evento [kernel.response] (Ejemplo 24), definido dentro de la misma clase: el atributo [#[AsEventListener]] se aplica a un método, y el autenticador, un servicio como cualquier otro, también se convierte en escucha. Elimina la cookie de un token no válido, sea cual sea la respuesta: la página de inicio de sesión, una página pública o una redirección del punto de entrada. Una cookie no válida no sirve para nada y alteraría el mensaje de la siguiente solicitud.
11.12.4. src/Security/InvalidSession.php
| <?php
// src/Security/InvalidSession.php: el token es válido, pero la cuenta que
// designa ya no existe: fue eliminada desde el inicio de sesión (por el paciente
// mismo en otra pestaña, o por el ADMIN). Tratamos este caso como una sesión
// expirada: el listener ErrorPage borra la cookie y redirige a la página de inicio de
// sesión.
namespace App\Security;
use RuntimeException;
class InvalidSession extends RuntimeException
{
}
|
Un escenario que no se contempló en el Ejemplo 25: el token es válido, pero la cuenta a la que hace referencia ya no existe. Un paciente eliminó su cuenta en una pestaña, pero el token sigue presente en otra pestaña; o el administrador eliminó la cuenta de un paciente conectado. La firma del token no da ninguna indicación sobre la existencia de la cuenta; solo cuando la aplicación busca al paciente asociado a la cuenta ([Utils::connectedPatient], que se verá más adelante) descubre que la cuenta ya no existe. Entonces lanza esta excepción, que el escucha [ErrorPage] (que se verá más adelante) trata como una sesión expirada. La clase está vacía: solo importa su tipo , que el escucha reconoce ([instanceof]).
11.12.5. src/Security/CaptchaService.php, Captcha.php y CaptchaDrawing.php
[CaptchaDrawing.php] y [Captcha.php] provienen del Ejemplo 27. El servicio es casi igual:
| <?php
// =========================================================================
// src/Security/CaptchaService.php: un CAPTCHA ("test to tell a human from a
// robot") construido por el propio servidor, sin ningún servicio externo (véase el ejemplo 27).
//
// Cómo funciona:
// 1. generate() dibuja un texto aleatorio, crea una imagen con él y almacena la respuesta
// correcta EN EL CACHÉ del servidor, bajo un identificador aleatorio;
// 2. la página muestra la imagen y coloca el identificador en un campo oculto del
// formulario (la respuesta en sí nunca sale del servidor);
// 3. verify(id, typed) compara lo ingresado con la respuesta esperada y luego OLVIDA
// este captcha: cada imagen se usa una sola vez, un robot no puede reutilizar
// una respuesta ya encontrada.
//
// ¿Por qué el caché? Una aplicación PHP NO conserva NADA en memoria de una solicitud a
// la siguiente: cada solicitud parte de cero. Lo que debe durar más allá de una solicitud
// va, por lo tanto, al caché (aquí archivos, en var/cache), compartido por todas las
// solicitudes, e incluso por varios servidores con un caché como Redis.
// =========================================================================
namespace App\Security;
use Psr\Cache\CacheItemPoolInterface;
use Symfony\Component\Lock\LockFactory;
class CaptchaService
{
// duración de validez de una imagen, en segundos: 10 minutos para completar el formulario
private const LIFETIME = 600;
public function __construct(private CacheItemPoolInterface $cache, private LockFactory $locks)
{
}
public function generate(): Captcha
{
$text = CaptchaDrawing::randomText(5); // 5 caracteres
$id = bin2hex(random_bytes(12)); // un identificador imposible de adivinar
// el caché olvidará la respuesta por sí solo después de 10 minutos
$item = $this->cache->getItem("captcha.$id");
$this->cache->save($item->set($text)->expiresAfter(self::LIFETIME));
return new Captcha($id, CaptchaDrawing::svg($text));
}
// true si [$typed] es la respuesta correcta al captcha [$id] (sin distinguir
// mayúsculas de minúsculas). El captcha se consume en todos los casos.
public function verify(?string $id, ?string $typed): bool
{
// el identificador viene del navegador: dígitos hexadecimales, o nada
if ($id === null || ! ctype_xdigit($id) || $typed === null) {
return false;
}
// si dos solicitudes presentan el mismo captcha al mismo tiempo, solo una
// obtiene el bloqueo (acquire(false): sin esperar) - la otra falla
$lock = $this->locks->createLock("captcha.$id");
if (! $lock->acquire(false)) {
return false;
}
try {
$item = $this->cache->getItem("captcha.$id");
$this->cache->deleteItem("captcha.$id");
} finally {
$lock->release();
}
return $item->isHit() && strcasecmp($item->get(), trim($typed)) === 0;
}
}
|
- líneas 35–43: una cadena de 5 caracteres generada al azar, un identificador aleatorio ([random_bytes], un generador criptográfico, cuyos bytes se escriben en hexadecimal con [bin2hex]) y la respuesta correcta almacenada en la caché (ejemplo 20) durante 10 minutos ([expiresAfter], en segundos);
- líneas 47–66: una diferencia con respecto al Ejemplo 27. La respuesta se lee y luego se elimina de la caché. Entre la lectura y la eliminación, una segunda solicitud que presente el mismo CAPTCHA también podría leerla: dos intentos para una sola imagen resuelta. Por lo tanto, un bloqueo (Ejemplo 20), específico de este CAPTCHA, protege tanto la lectura como la eliminación. [acquire(false)] lo adquiere de inmediato: devuelve [false] si otra solicitud ya lo tiene, y esa solicitud, que pierde la carrera, falla. El bloque [finally] libera el bloqueo en todos los casos. La comparación ignora las mayúsculas ([strcasecmp] devuelve 0 para dos cadenas que coinciden sin distinguir mayúsculas) y los espacios alrededor de lo ingresado ([trim]).
11.12.6. src/Security/AttemptLimiter.php
| <?php
// =========================================================================
// src/Security/AttemptLimiter.php: segunda muralla contra los robots (la primera
// es el captcha): CONTAMOS los intentos y, superado un umbral, BLOQUEAMOS
// durante un tiempo (véase el ejemplo 27).
//
// - login: tras LOGIN_MAX_FAILURES fallos (captcha incorrecto o contraseña
// incorrecta) para el mismo login desde la misma dirección IP, este par se
// bloquea hasta el final de una ventana de LOGIN_BLOCK_MINUTES minutos, contados
// desde el primer fallo. La misma dirección IP también se bloquea si acumula
// LOGIN_MAX_FAILURES_IP fallos, todos los logins juntos (un robot que prueba
// miles de logins distintos);
// - creación de cuentas: como máximo REGISTRATION_MAX_PER_HOUR cuentas creadas por
// hora desde la misma dirección IP.
//
// Atención en un aula: todas las computadoras salen a menudo a Internet por la
// MISMA dirección IP. Por eso el bloqueo de login se aplica primero al
// par (IP, login) - un estudiante que se equivoca de contraseña no bloquea a
// sus compañeros - y por eso los umbrales pueden ajustarse (archivo .env).
//
// Los contadores son los de los tres limitadores del componente RateLimiter, declarados
// en config/packages/framework.yaml y almacenados en el caché.
// =========================================================================
namespace App\Security;
use Symfony\Component\RateLimiter\LimiterInterface;
use Symfony\Component\RateLimiter\RateLimiterFactoryInterface;
class AttemptLimiter
{
// las fábricas de los limitadores [login], [login_ip] y [registration]: el nombre
// del parámetro designa el limitador (véase el ejemplo 27)
public function __construct(
private RateLimiterFactoryInterface $loginLimiter,
private RateLimiterFactoryInterface $loginIpLimiter,
private RateLimiterFactoryInterface $registrationLimiter,
) {
}
// ---------------------------------------------------------------- login
// número de minutos de bloqueo restantes (0 = el intento está permitido)
public function loginBlockMinutes(string $ip, string $login): int
{
return max(self::remainingMinutes($this->ipLoginLimiter($ip, $login)),
self::remainingMinutes($this->loginIpLimiter->create($ip)));
}
// consume(): un fallo más; el primero abre una ventana de
// LOGIN_BLOCK_MINUTES minutos, al final de la cual el contador vuelve a empezar desde cero
public function loginFailure(string $ip, string $login): void
{
$this->ipLoginLimiter($ip, $login)->consume();
$this->loginIpLimiter->create($ip)->consume();
}
// un inicio de sesión exitoso reinicia el contador de ESTE login
public function loginSuccess(string $ip, string $login): void
{
$this->ipLoginLimiter($ip, $login)->reset();
}
// ---------------------------------------------------------------- registro
public function registrationBlockMinutes(string $ip): int
{
return self::remainingMinutes($this->registrationLimiter->create($ip));
}
public function registrationSuccess(string $ip): void
{
$this->registrationLimiter->create($ip)->consume();
}
// ---------------------------------------------------------------- mecánica común
// el limitador del par (IP, login): create(key) devuelve un limitador que tiene su
// propio contador, bajo esta clave
private function ipLoginLimiter(string $ip, string $login): LimiterInterface
{
return $this->loginLimiter->create("$ip|".mb_strtolower(trim($login)));
}
// consume(0) consulta el limitador sin consumir nada: ¿no queda ningún "token"?
// getRetryAfter: la fecha del final de la ventana actual; los segundos que
// faltan hasta entonces se redondean HACIA ARRIBA al minuto: 30 s -> "1 minute"
private static function remainingMinutes(LimiterInterface $limiter): int
{
$state = $limiter->consume(0);
if ($state->getRemainingTokens() > 0) {
return 0;
}
return max(1, (int) ceil(($state->getRetryAfter()->getTimestamp() - time()) / 60));
}
}
|
La segunda línea de defensa contra los bots, después del CAPTCHA: se cuentan los intentos y, una vez superado un umbral, se bloquea el acceso. El Ejemplo 27 presentó el componente [RateLimiter] de [Symfony]. Los tres limitadores se declaran en [config/packages/framework.yaml] (política [fixed_window]: una ventana de duración fija, abierta por el primer token consumido); el servicio recibe sus fábricas, identificadas por los nombres de los parámetros (líneas 34–38): [$loginLimiter] para el limitador [login], [$loginIpLimiter] para [login_ip], [$registrationLimiter] para [registration]. Una fábrica usa su método [create(key)] para crear un limitador que tiene su propio contador bajo esta clave. Dos reglas:
- el inicio de sesión (líneas 44–62): cada fallo (CAPTCHA o contraseña incorrectos) se cuenta dos veces: para el par (dirección IP, nombre de usuario) y para la dirección IP sola. El par se bloquea después de 5 intentos fallidos (parámetro [LOGIN_MAX_FAILURES]) y la dirección IP después de 25 (parámetro [LOGIN_MAX_FAILURES_IP]), entre todos los nombres de usuario: es el bot que prueba miles de nombres de usuario distintos. ¿Por qué no bloquear primero la dirección IP? En un salón de clases (o en una empresa), todas las máquinas suelen acceder a Internet a través de la misma dirección IP: un estudiante que ingresa mal la contraseña no debería bloquear a sus compañeros. [consume()] consume un token (cuenta como un intento fallido); el primer intento abre una ventana de 15 minutos (parámetro [LOGIN_BLOCK_MINUTES]), al final de la cual el contador se restablece a cero. Un inicio de sesión exitoso restablece el contador de ese usuario ([reset]);
- la creación de cuentas (líneas 66–74): no más de 10 cuentas por hora por dirección IP (parámetro [REGISTRATION_MAX_PER_HOUR]);
- líneas 80–83: la clave de un limitador de tasa. El nombre de usuario se pasa a minúsculas: [Admin] y [admin] se consideran iguales (como en la base de datos; véase su cotejación);
- Líneas 88–95: [consume(0)] consulta el limitador sin consumir ningún token (ejemplo 27): si quedan tokens, el intento se permite; de lo contrario, [getRetryAfter] devuelve la fecha de fin de la ventana actual, y el número de segundos que faltan hasta entonces se redondea hacia arriba al minuto siguiente ([ceil]): si quedan 30 segundos, se muestra «1 minuto». El mensaje que se muestra depende de esto: «Demasiados intentos fallidos. Vuelva a intentarlo en 15 minutos.»
Los contadores de los limitadores se almacenan en la caché: son compartidos por todas las solicitudes y sobreviven a un reinicio del servidor. El comando [php bin/console cache:pool:clear cache.rate_limiter] los restablece todos a cero (útil durante el desarrollo, cuando se ha quedado bloqueado); [php bin/console cache:clear], que vacía todo el directorio [var/cache], hace lo mismo.
11.12.7. src/Security/RegistrationPass.php y RegistrationPassRequired.php
| <?php
// =========================================================================
// src/Security/RegistrationPass.php: el "pass" de creación de cuenta.
//
// Para abrir la página "Create a patient account", primero hay que haber copiado el
// captcha de la página de inicio de sesión (véase RegistrationController, POST
// /register/access). Entonces el servidor emite un pass:
// - un identificador aleatorio, almacenado en una cookie HttpOnly;
// - válido durante 15 minutos (el tiempo de llenar el formulario, incluso al intentarlo
// varias veces tras errores de ingreso);
// - consumido en cuanto se crea una cuenta: UN captcha resuelto = UNA cuenta como máximo.
// Un robot no puede crear cuentas en serie.
//
// Sin un pass válido, GET y POST /register redirigen a la página de inicio de
// sesión (véase el atributo #[RegistrationPassRequired] y el listener
// CheckRegistrationPass): escribir directamente la URL /register no permite
// eludir el captcha.
//
// Como los captchas, los pass viven en el caché.
// =========================================================================
namespace App\Security;
use Psr\Cache\CacheItemPoolInterface;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Component\HttpFoundation\Response;
class RegistrationPass
{
public const COOKIE = 'rdvmedecins_registration';
// el navegador envía la cookie solo a las direcciones /register...
private const PATH = '/register';
// duración de vida de un pass, en minutos
private const LIFETIME = 15;
public function __construct(
private CacheItemPoolInterface $cache,
#[Autowire(env: 'bool:COOKIE_SECURE')] private bool $cookieSecure,
) {
}
// emite un nuevo pass; devuelve la cookie que lo transporta
public function issue(): Cookie
{
$id = bin2hex(random_bytes(12));
$item = $this->cache->getItem("pass.$id");
$this->cache->save($item->set(true)->expiresAfter(self::LIFETIME * 60));
return Cookie::create(self::COOKIE, $id)
->withExpires(time() + self::LIFETIME * 60)
->withPath(self::PATH)
->withSecure($this->cookieSecure)
->withHttpOnly(true)
->withSameSite(Cookie::SAMESITE_LAX);
}
// true si [$id] es un pass existente y no expirado; hasItem: ¿tiene el
// caché este elemento?
public function isValid(?string $id): bool
{
return $id !== null && ctype_xdigit($id) && $this->cache->hasItem("pass.$id");
}
// el pass se ha usado: lo olvidamos...
public function consume(?string $id): void
{
if ($id !== null && ctype_xdigit($id)) {
$this->cache->deleteItem("pass.$id");
}
}
// ... y su cookie se borra mediante una cookie del mismo nombre y la misma ruta, ya expirada
public static function clearCookie(Response $response): Response
{
$response->headers->clearCookie(self::COOKIE, self::PATH);
return $response;
}
}
|
La creación de una cuenta de paciente está protegida por el CAPTCHA de la página de inicio de sesión. Pero el formulario de creación de cuenta está en otra página ([/register]): ¿cómo puede saber el sistema, cuando se solicita el formulario, que el CAPTCHA se resolvió justo antes? Mediante un token: cuando se resuelve el CAPTCHA, el servidor genera un identificador aleatorio, lo almacena en la caché durante 15 minutos y lo envía al navegador en una cookie. El formulario solo se muestra, y la cuenta solo se crea, con un token válido; el token se consume al crear la cuenta. Así, un CAPTCHA resuelto permite crear una cuenta, y escribir directamente la dirección [/register] no lleva a ninguna parte.
- Líneas 46–57: la cookie tiene la ruta [/register] ([withPath]): el navegador solo la envía a las direcciones que comienzan con esta ruta. Contiene solo un identificador aleatorio, imposible de adivinar, y solo la caché del servidor sabe si es válido: la cookie no necesita estar firmada;
- líneas 61–64: [hasItem] indica si la caché contiene una entrada (no expirada) bajo esta clave;
- líneas 75–79: para eliminar una cookie, hay que especificar el mismo nombre y la misma ruta: para el navegador, dos cookies con el mismo nombre pero con rutas distintas son dos cookies diferentes.
| <?php
// src/Security/RegistrationPassRequired.php: un ATRIBUTO PHP propio (véase el
// ejemplo 24), colocado en las acciones que exigen un pass de creación de cuenta
// (véase RegistrationPass y el listener CheckRegistrationPass).
namespace App\Security;
use Attribute;
#[Attribute(Attribute::TARGET_METHOD)]
class RegistrationPassRequired
{
}
|
Un atributo [PHP] de nuestra propia invención, como el [#[Timed]] del Ejemplo 24, se aplica a las acciones que requieren un pase. Lo lee el escucha [CheckRegistrationPass].
11.13. Los escuchas: src/EventListener
Tres escuchas de eventos del núcleo (Ejemplo 24), almacenados en la carpeta [src/EventListener], como es habitual. El atributo [#[AsEventListener]], colocado en la clase, especifica el evento y la prioridad; el método al que se llama es entonces [__invoke].
11.13.1. src/EventListener/SetLanguage.php
| <?php
// =========================================================================
// src/EventListener/SetLanguage.php: el idioma de la solicitud (véase el ejemplo 22):
// el de la cookie [rdvmedecins_language] si es un idioma admitido; inglés en caso contrario.
//
// Prioridad 40: el listener se ejecuta ANTES del enrutamiento de Symfony (prioridad 32). Por lo
// tanto, se ejecuta para TODAS las solicitudes, incluso las que no conducen a ninguna
// ruta (páginas 404, 405...): su página de error queda en el idioma correcto. Por la
// misma razón, también fija el idioma del propio traductor, lo que de otro modo haría
// un listener de Symfony (prioridad 15) que un error de enrutamiento impediría
// ejecutar.
// =========================================================================
namespace App\EventListener;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Contracts\Translation\LocaleAwareInterface;
#[AsEventListener(event: KernelEvents::REQUEST, priority: 40)]
class SetLanguage
{
// la cookie que recuerda el idioma elegido (véase LanguageController)
public const COOKIE = 'rdvmedecins_language';
// los idiomas admitidos (carpeta translations); el primero es el idioma por defecto
public const LANGUAGES = ['en', 'fr'];
// LocaleAwareInterface: un servicio que tiene un idioma, aquí el traductor
public function __construct(private LocaleAwareInterface $translator)
{
}
public function __invoke(RequestEvent $event): void
{
$request = $event->getRequest();
$language = $request->cookies->get(self::COOKIE);
$language = in_array($language, self::LANGUAGES, true) ? $language : self::LANGUAGES[0];
$request->setLocale($language);
$this->translator->setLocale($language);
}
}
|
El idioma de la solicitud (Ejemplo 22): el idioma de la cookie, si es un idioma admitido; de lo contrario, el idioma predeterminado (inglés). Una diferencia con respecto al Ejemplo 22: prioridad 40 (línea 21), que es mayor que la prioridad del enrutamiento (32). El escucha del Ejemplo 22 (prioridad 20) se ejecutaba después del enrutamiento; para una URL que no coincide con ninguna ruta, el enrutamiento lanza una excepción antes del escucha, y la página 404 habría salido en inglés incluso para un usuario francófono. Por la misma razón, el propio escucha establece el idioma del traductor (línea 41), cosa que normalmente hace un escucha de [Symfony] ([LocaleAwareListener]), que también se coloca después del enrutamiento. [LocaleAwareInterface] es la interfaz de los servicios que tienen un idioma; el traductor es uno de ellos, y es este traductor el que [Symfony] inyecta aquí.
11.13.2. src/EventListener/CheckRegistrationPass.php
| <?php
// =========================================================================
// src/EventListener/CheckRegistrationPass.php: las acciones marcadas con
// el atributo #[RegistrationPassRequired] (GET y POST /register) exigen un
// pass válido (véase src/Security/RegistrationPass.php); de lo contrario, de vuelta a
// la página de inicio de sesión, con un mensaje. Escribir directamente la URL
// /register no permite, por lo tanto, eludir el captcha.
//
// Un listener de kernel.controller (véase el ejemplo 24): la acción ya fue elegida, pero
// aún no se ha llamado. Para rechazar, la REEMPLAZA (setController) por una
// función que devuelve una redirección.
// =========================================================================
namespace App\EventListener;
use App\Security\RegistrationPass;
use App\Security\RegistrationPassRequired;
use App\Web\Flash;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpKernel\Event\ControllerEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
#[AsEventListener(event: KernelEvents::CONTROLLER)]
class CheckRegistrationPass
{
public function __construct(
private RegistrationPass $passes,
private Flash $flash,
private UrlGeneratorInterface $urls,
) {
}
public function __invoke(ControllerEvent $event): void
{
if ($event->getAttributes(RegistrationPassRequired::class) === []) {
return;
}
if (! $this->passes->isValid($event->getRequest()->cookies->get(RegistrationPass::COOKIE))) {
$this->flash->error('ERRORS.CAPTCHA_BEFORE_ACCOUNT');
$url = $this->urls->generate('login');
$event->setController(fn () => new RedirectResponse($url));
}
}
}
|
Un escucha de [kernel.controller] (ejemplo 24): la acción está seleccionada pero todavía no se ha llamado.
- líneas 37–39: [getAttributes(class)] devuelve los atributos de esta clase que lleva la acción: una lista vacía; la acción no requiere un token; el escucha no hace nada;
- líneas 40–44: no hay un token válido: se muestra un mensaje y la acción se reemplaza ([setController]) por una función que redirige a la página de inicio de sesión. El núcleo llama a esta función en lugar de la acción. La URL se calcula fuera de la función flecha, que por lo tanto requiere una sola variable.
El escucha recibe sus servicios a través de su constructor: un escucha es un servicio, creado por el contenedor, igual que los controladores.
11.13.3. src/EventListener/ErrorPage.php
| <?php
// =========================================================================
// src/EventListener/ErrorPage.php: cómo los errores se convierten en páginas HTML
// (véase el ejemplo 24). Tres casos:
// 1. una InvalidSession (cuenta eliminada desde el inicio de sesión) -> de vuelta a la
// página de inicio de sesión, como en una sesión expirada;
// 2. un error HTTP: solicitud inválida (400), rol insuficiente (403), página
// desconocida (404), método no admitido (405), token anti-CSRF ausente o incorrecto
// (419)... -> la página de error, con el código original;
// 3. cualquier otra excepción (una verdadera anomalía): Symfony ya la escribió en
// el registro, con su pila de llamadas; en producción (APP_ENV=prod),
// el usuario ve la página de error 500 - nunca la pila de llamadas; en
// desarrollo, la página de depuración de Symfony.
//
// Prioridad -10: después del listener de Symfony que escribe la excepción en el registro
// (0) y después del de seguridad (1), que convierte un rechazo de acceso en una
// redirección a la página de inicio de sesión (visitante anónimo) o en un error 403
// (usuario autenticado); antes del que construye la página de error de Symfony
// (-128).
// =========================================================================
namespace App\EventListener;
use App\Security\AuthService;
use App\Security\InvalidSession;
use App\Web\Flash;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Twig\Environment;
#[AsEventListener(event: KernelEvents::EXCEPTION, priority: -10)]
class ErrorPage
{
public function __construct(
private Environment $twig,
private Flash $flash,
private UrlGeneratorInterface $urls,
// el modo de depuración (APP_ENV=dev): el parámetro kernel.debug del contenedor
#[Autowire('%kernel.debug%')] private bool $debug,
) {
}
public function __invoke(ExceptionEvent $event): void
{
$e = $event->getThrowable();
if ($e instanceof InvalidSession) {
$this->flash->error('ERRORS.SESSION_EXPIRED');
$event->setResponse(AuthService::clearCookie(new RedirectResponse($this->urls->generate('login'))));
return;
}
if ($e instanceof HttpExceptionInterface) {
$event->setResponse($this->page($e->getStatusCode()));
return;
}
// una verdadera anomalía: en desarrollo, la página de depuración de Symfony
if (! $this->debug) {
$event->setResponse($this->page(500));
}
}
// la página de error, con el código HTTP del error y su mensaje
private function page(int $code): Response
{
$message = match ($code) {
400 => 'ERRORS.BAD_REQUEST',
403 => 'ERRORS.FORBIDDEN',
404, 405 => 'ERRORS.NOT_FOUND',
419 => 'ERRORS.PAGE_EXPIRED',
default => 'ERRORS.SERVER_ERROR',
};
return new Response($this->twig->render('error.html.twig', ['pageTitle' => 'ERROR_PAGE.TITLE',
'code' => $code, 'message' => $message]), $code);
}
}
|
Cómo se convierten los errores en páginas HTML: este es el escucha [ErrorPage] del Ejemplo 24, ampliado. Escucha el evento [kernel.exception], con prioridad -10 (línea 37): después del escucha de [Symfony] que registra la excepción en el log (prioridad 0) y después del escucha del componente de seguridad (prioridad 1), que convierte una denegación de acceso en una llamada al punto de entrada (visitante anónimo) o en un error 403 (usuario autenticado con un rol inadecuado); antes del manejador que genera la página de error de [Symfony] (-128). Tres casos:
- líneas 53–57: una [InvalidSession] (la cuenta fue eliminada): el mensaje de «sesión expirada», la eliminación de la cookie del token y la página de inicio de sesión;
- líneas 59–62: un error HTTP: [HttpExceptionInterface] es la interfaz de las excepciones con código HTTP ([NotFoundHttpException], [AccessDeniedHttpException], [HttpException(419)]...), que se obtiene con [getStatusCode]. Se muestra la página de error con este código;
- líneas 65–67: cualquier otra excepción es un verdadero error. En desarrollo ([kernel.debug], ejemplo 24), el escucha no hace nada: se mostrará la página de depuración de [Symfony], con la pila de llamadas. En producción, la página de error 500: el usuario nunca ve la pila de llamadas, que el log ya ha registrado;
- líneas 71–82: la página de error, vista [error.html.twig], que muestra el código y la clave del mensaje. [match] ([PHP] 8) selecciona un valor en función de otro, con igualdad estricta; [404, 405 =>] cubre dos casos; [default] se encarga de todos los demás. El código 405 (Method Not Allowed: un GET a una dirección que solo acepta POST) se muestra como un error de «página no encontrada».
11.14. El controlador de inicio de sesión
11.14.1. src/Controller/AuthController.php
| <?php
// =========================================================================
// src/Controller/AuthController.php: las rutas PÚBLICAS del inicio de sesión:
// GET / redirige a la página de inicio del rol (o a /login)
// GET /login muestra el formulario de inicio de sesión (con su captcha)
// POST /login verifica el límite de intentos, el captcha, login / contraseña
// POST /logout el cierre de sesión
//
// Protección contra robots, en este orden:
// 1. ¿demasiados fallos recientes para este login desde esta dirección IP?
// -> rechazo inmediato, sin siquiera mirar la contraseña;
// 2. ¿respuesta incorrecta al captcha? -> rechazo (contado como un fallo);
// 3. solo entonces, verificación de la contraseña.
// NUNCA verificamos la contraseña de un intento rechazado en los pasos 1 o 2:
// por lo tanto, un robot no puede aprender nada insistiendo.
// =========================================================================
namespace App\Controller;
use App\Entity\Role;
use App\Security\AuthService;
use App\Security\CaptchaService;
use App\Security\AttemptLimiter;
use App\Security\ConnectedUser;
use App\Web\BaseController;
use App\Web\Message;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
class AuthController extends BaseController
{
public function __construct(
private AuthService $auth,
private CaptchaService $captchas,
private AttemptLimiter $limiter,
) {
}
// la página de inicio de cada rol, justo después del inicio de sesión: el nombre de su ruta
public static function homePage(Role $role): string
{
return $role === Role::USER ? 'area' : 'schedule';
}
// -----------------------------------------------------------------------
// GET /
// La ruta es pública: el usuario, si lo hay, es conocido
// ($this->getUser()), pero no se exige nada.
// -----------------------------------------------------------------------
#[Route('/', name: 'home', methods: ['GET'])]
public function home(): Response
{
$user = $this->getUser();
return $this->redirectToRoute($user instanceof ConnectedUser
? self::homePage($user->role) : 'login');
}
// -----------------------------------------------------------------------
// GET /login[?login=xxx]: el parámetro opcional rellena previamente el campo de login
// (se usa justo después de la creación de una cuenta, véase RegistrationController)
// -----------------------------------------------------------------------
#[Route('/login', name: 'login', methods: ['GET'])]
public function form(Request $request): Response
{
// ya con sesión iniciada (token aún válido): directo a la página de inicio
$user = $this->getUser();
if ($user instanceof ConnectedUser) {
return $this->redirectToRoute(self::homePage($user->role));
}
// mb_substr: 30 caracteres como máximo
return $this->page(mb_substr($request->query->getString('login'), 0, 30), null);
}
// -----------------------------------------------------------------------
// POST /login
// -----------------------------------------------------------------------
#[Route('/login', name: 'login_submit', methods: ['POST'])]
public function logIn(Request $request): Response
{
$this->checkCsrf($request);
$login = $request->request->getString('login');
$password = $request->request->getString('password');
$ip = (string) $request->getClientIp();
// 1. ¿demasiados fallos recientes?
$minutes = $this->limiter->loginBlockMinutes($ip, $login);
if ($minutes > 0) {
return $this->page($login, new Message('ERRORS.TOO_MANY_ATTEMPTS', ['minutes' => $minutes]));
}
// 2. el captcha
if (! $this->captchas->verify($request->request->getString('captchaId'),
$request->request->getString('captcha'))) {
$this->limiter->loginFailure($ip, $login);
return $this->page($login, new Message('ERRORS.WRONG_CAPTCHA'));
}
// 3. la contraseña
$user = $login !== '' && $password !== '' ? $this->auth->validate($login, $password) : null;
if ($user === null) {
$this->limiter->loginFailure($ip, $login);
return $this->page($login, new Message('LOGIN.ERROR'));
}
$this->limiter->loginSuccess($ip, $login);
$response = $this->redirectToRoute(self::homePage($user->getRole()));
$response->headers->setCookie($this->auth->tokenCookie($user));
return $response;
}
// -----------------------------------------------------------------------
// POST /logout: borrar la cookie del token y luego ir a la página de inicio de sesión.
// Solo POST: un simple enlace (GET), colocado en otro sitio, no puede
// cerrar la sesión del usuario sin su conocimiento.
// -----------------------------------------------------------------------
#[Route('/logout', name: 'logout', methods: ['POST'])]
public function logOut(Request $request): Response
{
$this->checkCsrf($request);
return AuthService::clearCookie($this->redirectToRoute('login'));
}
// el formulario, siempre con un captcha NUEVO (cada imagen se usa una sola
// vez); se vuelve a mostrar el login ingresado, nunca la contraseña. Un error:
// el código 422, como en un formulario inválido (véase el ejemplo 19)
private function page(string $login, ?Message $error): Response
{
return $this->render('login.html.twig', ['pageTitle' => 'LOGIN.TITLE', 'error' => $error,
'login' => $login, 'captcha' => $this->captchas->generate()],
new Response(status: $error ? 422 : 200));
}
}
|
El controlador de inicio de sesión, basado en el Ejemplo 27. Hereda de la clase [BaseController] de la aplicación (que se verá más adelante), que a su vez es una subclase de [AbstractController].
- líneas 41–44: la página de inicio de cada rol, junto con el nombre de su ruta: «Mi área» para un paciente y el calendario para los demás;
- líneas 51–57: la dirección [/] lleva a la página de inicio del rol o a la página de inicio de sesión. La ruta es pública (regla [access_control] de [security.yaml]): [getUser()] devuelve el usuario establecido por el autenticador, si hay alguno, sin exigir nada. [redirectToRoute] (ejemplo 04) crea una redirección a una ruta con nombre;
- líneas 63–73: un usuario que ya inició sesión va directamente a su página de inicio. El parámetro opcional [login] de la URL rellena previamente el campo (después de la creación de una cuenta); [mb_substr] lo trunca a 30 caracteres;
- Líneas 78–110: el proceso de inicio de sesión, en el orden que se mostró en el Ejemplo 27: el token anti-CSRF (que se verá más adelante), las posibles medidas de bloqueo, el CAPTCHA y la contraseña. Nunca se verifica una contraseña en un intento rechazado por el limitador o por el CAPTCHA: un bot no aprende nada por insistir. [getClientIp] devuelve la dirección IP del cliente. Si el intento falla, la página se genera directamente (sin redirección): el formulario que se vuelve a mostrar siempre tiene un nuevo CAPTCHA y el nombre de usuario ingresado. El error es un objeto [Message] (véase más adelante), formado por una clave y sus parámetros, que se muestra en la parte inferior de la página. Si tiene éxito, el contador de inicios de sesión se restablece a cero y el navegador es redirigido a la página de inicio del rol, con la cookie del token ([headers->setCookie]);
- líneas 117–122: el cierre de sesión elimina la cookie del token (ejemplo 25). Solo acepta POST, junto con el token anti-CSRF: un simple enlace colocado en otro sitio no puede cerrar la sesión del usuario sin que este lo sepa;
- líneas 127–132: la página de inicio de sesión. El tercer parámetro de [render] es la respuesta que se debe completar: se devuelve un error con el código 422 (Unprocessable Content), como con un formulario no válido (ejemplo 19). [new Response(status: ...)] usa un argumento con nombre ([PHP] 8): los dos primeros parámetros del constructor conservan sus valores predeterminados.
La página de inicio de sesión recibe la variable [pageTitle], la clave de traducción del título de la página: todas las acciones la pasan a su vista para la plantilla (véase más adelante).
11.15. La capa web: servicios compartidos
La carpeta [src/Web] contiene los elementos compartidos por los controladores.
11.15.1. src/Web/ApplicationModel.php
| <?php
// =========================================================================
// src/Web/ApplicationModel.php: el caché / fachada de la capa de negocio (el equivalente
// de la clase [ApplicationModel] de las otras versiones de la aplicación): las
// listas de médicos y clientes se leen de la base de datos una vez y luego se sirven
// desde el caché.
//
// ¿Por qué el CACHÉ de Symfony y no simplemente una propiedad de este objeto? Porque
// una aplicación PHP no conserva nada en memoria de una solicitud a la siguiente: este
// objeto es un servicio compartido, pero un servicio solo vive durante UNA solicitud.
// El caché, en cambio, es compartido por todas las solicitudes (véanse los ejemplos 20 y 23).
//
// Estas listas pueden CAMBIAR (el ADMIN agrega, modifica y elimina médicos y
// clientes): por eso cada escritura pasa por esta fachada, que OLVIDA la lista
// correspondiente justo después; la siguiente solicitud que la necesite la lee de nuevo de la base de datos. Ese es
// todo el sentido de un ÚNICO punto de entrada a la capa de negocio: la regla
// "escritura => actualización del caché" está escrita solo aquí.
// =========================================================================
namespace App\Web;
use App\Domain\DoctorDaySchedule;
use App\Entity\Client;
use App\Entity\Slot;
use App\Entity\Doctor;
use App\Entity\Appointment;
use App\Business\PersonData;
use App\Business\Business;
use App\Business\BusinessService;
use DateTimeImmutable;
use Symfony\Contracts\Cache\CacheInterface;
// el mismo contrato que la capa de negocio
class ApplicationModel implements Business
{
private const DOCTORS = 'rdvmedecins.doctors';
private const CLIENTS = 'rdvmedecins.clients';
// CacheInterface: el caché de la aplicación (el servicio cache.app), visto a través de
// la interfaz de los "contracts" de Symfony, más simple que la de PSR-6
public function __construct(private BusinessService $business, private CacheInterface $cache)
{
}
// ------------------------------------------------ lecturas desde el caché
// get(key, function): el valor del caché si existe; de lo contrario, se llama a la función
// y su resultado se almacena en el caché (sin límite de tiempo) antes de
// devolverse. Las entidades se almacenan allí serializadas (véase serialize): cada
// solicitud que las lee obtiene copias de ellas, que Doctrine no rastrea
public function getAllDoctors(): array
{
return $this->cache->get(self::DOCTORS, fn () => $this->business->getAllDoctors());
}
public function getAllClients(): array
{
return $this->cache->get(self::CLIENTS, fn () => $this->business->getAllClients());
}
// el médico cuya cuenta de usuario es [$userId] - se usa para preseleccionar,
// en el caso de un médico con sesión iniciada, su propia agenda. array_find: el primer elemento
// del arreglo que cumple la condición (null si no hay ninguno)
public function getDoctorByUserId(int $userId): ?Doctor
{
return array_find($this->getAllDoctors(), fn (Doctor $d) => $d->getAccount()->getId() === $userId);
}
// ------------------------------------------------ delegaciones simples
public function getAllSlots(int $doctorId): array
{
return $this->business->getAllSlots($doctorId);
}
public function getDoctorDayAppointments(int $doctorId, DateTimeImmutable $day): array
{
return $this->business->getDoctorDayAppointments($doctorId, $day);
}
public function getClientById(int $id): ?Client
{
return $this->business->getClientById($id);
}
public function getDoctorById(int $id): ?Doctor
{
return $this->business->getDoctorById($id);
}
public function getAppointmentById(int $id): ?Appointment
{
return $this->business->getAppointmentById($id);
}
public function getSlotById(int $id): ?Slot
{
return $this->business->getSlotById($id);
}
public function getDoctorDaySchedule(int $doctorId, DateTimeImmutable $day): ?DoctorDaySchedule
{
return $this->business->getDoctorDaySchedule($doctorId, $day);
}
// aquí no hay caché: lo que importa son los datos más recientes (un paciente que
// acaba de modificar o eliminar su cuenta)
public function getClientByUserId(int $userId): ?Client
{
return $this->business->getClientByUserId($userId);
}
public function getClientUpcomingAppointments(int $clientId): array
{
return $this->business->getClientUpcomingAppointments($clientId);
}
public function addAppointment(DateTimeImmutable $day, Slot $slot, Client $client): Appointment
{
return $this->business->addAppointment($day, $slot, $client);
}
public function deleteAppointment(Appointment $appointment): void
{
$this->business->deleteAppointment($appointment);
}
// ------------------------------------------------ escrituras => caché olvidado
// (delete: el elemento se elimina del caché)
public function addDoctor(PersonData $data): Doctor
{
$doctor = $this->business->addDoctor($data);
$this->cache->delete(self::DOCTORS);
return $doctor;
}
public function editDoctor(int $id, PersonData $data): Doctor
{
$doctor = $this->business->editDoctor($id, $data);
$this->cache->delete(self::DOCTORS);
return $doctor;
}
public function deleteDoctor(int $id): void
{
$this->business->deleteDoctor($id);
$this->cache->delete(self::DOCTORS);
}
public function addClient(PersonData $data): Client
{
$client = $this->business->addClient($data);
$this->cache->delete(self::CLIENTS);
return $client;
}
public function editClient(int $id, PersonData $data): Client
{
$client = $this->business->editClient($id, $data);
$this->cache->delete(self::CLIENTS);
return $client;
}
public function deleteClient(int $id): void
{
$this->business->deleteClient($id);
$this->cache->delete(self::CLIENTS);
}
}
|
Todas las versiones de la aplicación tienen una clase llamada [ApplicationModel]: un único punto de entrada de la capa web a la capa de negocio, que mantiene en memoria las listas de médicos y clientes. Casi todas las páginas acceden a estas listas (la lista desplegable de médicos en el calendario, la lista de pacientes en la ventana de reservas y las páginas de administración) y rara vez cambian.
Lo que cambia en [PHP] es el significado de «en memoria». Una aplicación [Java], [C#] o [Python] permanece en memoria entre solicitudes; la versión [Flask] almacenaba estas listas en las propiedades de un único objeto creado al arrancar. Una aplicación [PHP] se vuelve a crear en cada solicitud (Ejemplo 01): el objeto [ApplicationModel] es, en efecto, un servicio compartido, pero existe solo durante una única solicitud (Ejemplo 23). Por lo tanto, las listas se almacenan en la caché de [Symfony] (ejemplo 20), que es compartida por todas las solicitudes.
- Línea 34: la clase implementa la interfaz [Business], igual que [BusinessService]: los controladores llaman a los mismos métodos, sin importar qué clase los atienda;
- Línea 42: esta vez, el caché se recibe mediante la [CacheInterface] interfaz de los «contracts» de [Symfony] (el mismo [cache.app] servicio), que es más simple que la interfaz PSR-6 de los ejemplos;
- Líneas 52–60: [get(key, function)] devuelve el valor almacenado bajo esa clave; si no existe, llama a la función (que lee la lista desde la base de datos), almacena su resultado en el caché indefinidamente y lo devuelve. La primera consulta que necesita la lista la lee directamente de la base de datos; las consultas siguientes la encuentran en el caché. El caché almacena el arreglo de entidades en forma serializada (ejemplo 20) y lo reconstruye al leerlo, junto con las relaciones cargadas (la cuenta de cada persona). Las entidades reconstruidas son copias que el administrador de entidades de [Doctrine] no rastrea: se usan para mostrar datos, nunca para escribir (la capa de negocio siempre vuelve a leer de la base de datos lo que modifica);
- líneas 65–68: el médico asociado a una cuenta, obtenido de la lista del caché mediante [array_find] (ejemplo 06);
- Líneas 72–127: los demás métodos del contrato [Business] simplemente delegan en la capa de negocio. El cliente de una cuenta ([getClientByUserId]) siempre se obtiene de la base de datos, no del caché: prevalecen los datos más recientes (un paciente que acaba de modificar o eliminar su cuenta);
- Líneas 132–170: las actualizaciones. Cada actualización realizada por un médico o un cliente no guarda la lista correspondiente ([delete]): la siguiente consulta que la necesite la obtendrá de la base de datos. Este es el sentido de tener un único punto de entrada: la regla «una escritura actualiza el caché» se implementa solo aquí. Si la escritura falla (por ejemplo, una [BusinessException]), la lista no se sobrescribe: no ha cambiado. Una aplicación que escriba en la base de datos por otra vía (otro programa, otra versión de la aplicación que use la misma base de datos) dejaría el caché desactualizado: [php bin/console cache:pool:clear cache.app] lo vaciaría.
11.15.2. src/Web/Message.php y Flash.php
| <?php
// src/Web/Message.php: un mensaje por traducir: su clave y sus parámetros.
// Las vistas lo muestran con {{ message.key|trans(message.params) }}.
namespace App\Web;
readonly class Message
{
public function __construct(
public string $key,
public array $params = [],
) {
}
}
|
Un mensaje por traducir: una clave y sus parámetros. Los errores de la capa de negocio ([BusinessException]) y los de los controladores se convierten en [Message], que las vistas traducen al idioma de la página.
| <?php
// =========================================================================
// src/Web/Flash.php: los mensajes "flash": un mensaje que se muestra UNA SOLA VEZ, en la
// PÁGINA SIGUIENTE (véase el ejemplo 20). Es el complemento natural del
// patrón "Post / Redirect / Get" que usan todos los formularios de la aplicación: un
// POST exitoso no construye ninguna página, redirige (302) a una página GET; el
// mensaje, en cambio, debe sobrevivir a la redirección.
//
// Symfony los almacena en la SESIÓN (archivos de la carpeta var/sessions, véase
// config/packages/framework.yaml).
//
// Un mensaje no contiene un texto, sino una CLAVE de traducción y sus parámetros
// (un objeto Message): se traduce al mostrarse, en el idioma de
// la página (véase templates/fragments). Dos listas: los éxitos (mostrados en la parte superior de
// la página) y los errores (mostrados en la parte inferior).
// =========================================================================
namespace App\Web;
use Symfony\Component\HttpFoundation\RequestStack;
class Flash
{
// la pila de solicitudes, para llegar a la sesión de la solicitud actual
public function __construct(private RequestStack $requests)
{
}
public function success(string $key, array $params = []): void
{
$this->add('success', $key, $params);
}
public function error(string $key, array $params = []): void
{
$this->add('errors', $key, $params);
}
// getFlashBag: la "bolsa" de los mensajes flash de la sesión; add(type, message)
// agrega un mensaje a la lista de ese tipo (véase el ejemplo 20)
private function add(string $type, string $key, array $params): void
{
$this->requests->getSession()->getFlashBag()->add($type, new Message($key, $params));
}
}
|
Mensajes flash (ejemplo 20): un mensaje colocado en la sesión por una acción, que se muestra en la siguiente página y luego se descarta. Esto complementa el patrón Post/Redirect/Get, que siguen todos los formularios de la aplicación. Hay dos tipos: los mensajes de éxito se muestran en la parte superior de la página y los mensajes de error, en la parte inferior.
- Línea 25: la pila de solicitudes ([RequestStack]), un servicio de [Symfony] que conoce la solicitud actual y, por lo tanto, su sesión. Un servicio compartido no puede recibir la solicitud misma por su constructor: se crea una sola vez y puede usarse para varias solicitudes (una solicitud principal y sus subsolicitudes);
- líneas 41–44: la «bolsa» de mensajes flash de la sesión ([getFlashBag]), en la cual [add(type, message)] completa la lista de este tipo. Esto es lo que hace el método [addFlash] de [AbstractController] (ejemplo 20); al convertirlo en un servicio, se puede colocar un mensaje fuera de un controlador, por ejemplo desde el autenticador o los listeners.
Los objetos [Message] se almacenan tal cual en la sesión: [PHP] serializa los datos de la sesión (ejemplo 20) y los reconstruye en la siguiente solicitud. En las vistas, [app.flashes('errors')] devuelve la lista de mensajes de este tipo y los elimina de la sesión.
11.15.3. src/Web/BaseController.php
| <?php
// =========================================================================
// src/Web/BaseController.php: la clase padre de los controladores de la aplicación. Hereda
// de AbstractController (véase el ejemplo 03) y agrega la verificación del
// token anti-CSRF de los formularios escritos a mano (véase el ejemplo 21).
// =========================================================================
namespace App\Web;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\Exception\HttpException;
abstract class BaseController extends AbstractController
{
// el identificador del token anti-CSRF de los formularios escritos a mano: solo uno
// para toda la aplicación (en las vistas: csrf_token('rdvmedecins')). Los
// formularios del componente Form tienen cada uno el suyo
public const CSRF = 'rdvmedecins';
// -----------------------------------------------------------------------
// un token anti-CSRF ausente o incorrecto: probablemente la página se mostró antes de la
// expiración de la sesión, que contenía el token. Error 419, el código (no oficial,
// pero muy extendido) de una página expirada: el listener ErrorPage muestra
// "The page has expired: reload it, then try again."
// -----------------------------------------------------------------------
protected function checkCsrf(Request $request): void
{
if (! $this->isCsrfTokenValid(self::CSRF, $request->request->getString('_token'))) {
throw new HttpException(419, 'invalid anti-CSRF token');
}
}
}
|
La clase padre de los controladores. Los formularios escritos manualmente en las vistas (inicio de sesión, cierre de sesión, eliminaciones, reservas, etc.) incluyen un token anti-CSRF (ejemplo 21) con el identificador [rdvmedecins]: aquí basta un único identificador, ya que todas estas acciones exigen un usuario con sesión iniciada o un CAPTCHA. Cada formulario del componente Form tiene su propio token, que valida el componente.
Un token ausente o inválido detiene la acción con un error 419 (líneas 27–32), el código (no oficial, pero muy usado) para una página que ha expirado: el token se almacena en la sesión, y una página mostrada antes del fin de la sesión contiene un token que el servidor ya no reconoce. El listener [ErrorPage] muestra entonces «La página ha expirado: vuelva a cargarla e inténtelo de nuevo». [HttpException] es la excepción HTTP genérica: su constructor recibe el código y un mensaje (destinado al registro, no al usuario).
11.15.4. src/Web/Utils.php
| <?php
// =========================================================================
// src/Web/Utils.php: pequeñas funciones utilitarias de la capa web:
// - fechas: "yyyy-mm-dd", días "Wednesday 23 September 2026";
// - entrada: lectura de un entero positivo y de una fecha, enviados por el navegador;
// - usuario: el usuario con sesión iniciada y su paciente (entidad Client).
// Los métodos STATIC se llaman sin objeto (Utils::iso($day)); los demás
// necesitan servicios (la solicitud actual, la seguridad...): la clase es un
// servicio, que los controladores reciben por su constructor.
// =========================================================================
namespace App\Web;
use App\Entity\Client;
use App\Security\InvalidSession;
use App\Security\ConnectedUser;
use DateTimeImmutable;
use IntlDateFormatter;
use Symfony\Bundle\SecurityBundle\Security;
use Symfony\Component\HttpFoundation\RequestStack;
class Utils
{
// Security: el servicio de seguridad de Symfony, que conoce al usuario de la
// solicitud actual (el establecido por el autenticador)
public function __construct(
private RequestStack $requests,
private Security $security,
private ApplicationModel $application,
) {
}
// ----------------------------------------------------------------- fechas
// la fecha, si [$text] es una fecha que existe en el formato yyyy-mm-dd; null en caso contrario.
// createFromFormat acepta "2026-02-30" (que se convierte en el 2 de marzo): por lo tanto
// verificamos que la fecha leída de vuelta se escriba exactamente como el texto recibido
public static function validDate(mixed $text): ?DateTimeImmutable
{
if (! is_string($text) || ! preg_match('/^\d{4}-\d{2}-\d{2}$/', $text)) {
return null;
}
// "!Y-m-d": el signo de exclamación fija la hora en medianoche
$date = DateTimeImmutable::createFromFormat('!Y-m-d', $text);
return $date !== false && $date->format('Y-m-d') === $text ? $date : null;
}
public static function iso(DateTimeImmutable $day): string
{
return $day->format('Y-m-d');
}
// "mercredi 23 septembre 2026" / "Wednesday 23 September 2026", según el idioma
// de la solicitud (véase el ejemplo 16). El patrón ICU: EEEE el día de la semana
// completo, d el día, MMMM el mes completo, y el año
public function formatDay(DateTimeImmutable $day): string
{
$language = $this->requests->getCurrentRequest()?->getLocale() ?? 'en';
return (new IntlDateFormatter($language, IntlDateFormatter::NONE, IntlDateFormatter::NONE,
pattern: 'EEEE d MMMM y'))->format($day);
}
// ----------------------------------------------------------------- entrada
// "3" -> 3; "", "abc", "-2", "+2", null -> null
public static function positiveInteger(mixed $value): ?int
{
if (! is_string($value) || ! preg_match('/^\d{1,9}$/', $value)) {
return null;
}
$n = (int) $value;
return $n > 0 ? $n : null;
}
// ----------------------------------------------------------------- usuario
// el usuario con sesión iniciada. Las acciones protegidas solo se llaman si existe;
// por precaución, su ausencia se trata como una sesión expirada
public function user(): ConnectedUser
{
$user = $this->security->getUser();
return $user instanceof ConnectedUser ? $user : throw new InvalidSession();
}
// -----------------------------------------------------------------------
// El paciente (entidad Client) que corresponde al usuario con sesión iniciada.
//
// El token JWT solo contiene el id de la CUENTA (users.id). Para un rol USER,
// encontramos el cliente correspondiente gracias a la columna clients.user.
//
// Si no hay ninguno, significa que la cuenta fue eliminada desde el inicio de sesión
// mientras su token sigue siendo válido: lo tratamos como una sesión
// expirada (véase InvalidSession).
// -----------------------------------------------------------------------
public function connectedPatient(): Client
{
return $this->application->getClientByUserId($this->user()->userId)
?? throw new InvalidSession();
}
}
|
Algunas funciones de utilidad. Los métodos estáticos se llaman sin un objeto ([Utils::iso($day)]); los demás requieren servicios: por lo tanto, la clase también es un servicio, que los controladores reciben por su constructor.
- Líneas 38–46: la fecha de un parámetro [yyyy-mm-dd] o [null]. Dos verificaciones: el formato (una expresión regular) y luego la existencia de la fecha. [createFromFormat] es tolerante: el 30 de febrero se convierte en el 2 de marzo. Por eso se vuelve a leer la fecha resultante y se verifica que se escriba exactamente igual que el texto recibido. El [!] en el formato fija la hora en medianoche (sin él, la hora sería la actual). [mixed]: cualquier tipo;
- líneas 56–61: «Saturday 26 September 2026» o «samedi 26 septembre 2026», según el idioma de la solicitud. [IntlDateFormatter] (ejemplo 16), con un patrón en lugar de un estilo: los códigos son los de la biblioteca ICU, [EEEE] para el día de la semana escrito completo, [d] para el día, [MMMM] para el mes escrito completo y [y] para el año. El parámetro [pattern] se pasa por nombre: los parámetros que lo preceden en la firma, y para los cuales no se proporciona ningún valor, conservan sus valores predeterminados;
- líneas 66–73: un parámetro de la solicitud puede ser una cadena, como [null], o incluso un arreglo ([?doctorId[]=1], ejemplo 10). Solo se aceptan dígitos (hasta nueve, para no exceder la capacidad), y el número debe ser estrictamente positivo;
- líneas 79–83: el usuario con sesión iniciada, determinado por el autenticador, que devuelve el servicio [Security] de [Symfony]. Las acciones protegidas solo se invocan para un usuario autenticado, pero la ausencia del usuario se trata de todos modos como una sesión expirada. [throw] es una expresión ([PHP] 8): puede aparecer dentro del operador [? :];
- líneas 95–99: el paciente (el [Client]) del usuario con sesión iniciada. El token contiene solo el identificador de la cuenta; el cliente se identifica por la columna [clients.user]. Si no existe, la cuenta se eliminó después de que el usuario inició sesión: [InvalidSession].
11.15.5. src/Twig/ViewsExtension.php
| <?php
// =========================================================================
// src/Twig/ViewsExtension.php: una extensión de Twig (véase el ejemplo 16), que agrega
// a las vistas las funciones que TODAS las páginas necesitan:
// - user() : el usuario con sesión iniciada (o null), para la barra de navegación;
// - titles() : los posibles tratamientos de una persona (Mr, Mme, Melle).
// =========================================================================
namespace App\Twig;
use App\Form\PersonFieldsType;
use App\Security\AuthService;
use App\Security\ConnectedUser;
use Symfony\Bundle\SecurityBundle\Security;
use Symfony\Component\HttpFoundation\RequestStack;
use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;
class ViewsExtension extends AbstractExtension
{
public function __construct(
private Security $security,
private RequestStack $requests,
private AuthService $auth,
) {
}
public function getFunctions(): array
{
return [
new TwigFunction('user', $this->user(...)),
new TwigFunction('titles', fn () => PersonFieldsType::TITLES),
];
}
// -----------------------------------------------------------------------
// el usuario establecido por el firewall. Una página de error 404 o 405 se
// construye ANTES del firewall (el enrutamiento, que falla, va antes que él, véase el
// ejemplo 24): el usuario se lee entonces directamente del token, para que la barra de
// navegación de la página de error esté completa
// -----------------------------------------------------------------------
public function user(): ?ConnectedUser
{
$user = $this->security->getUser();
if ($user instanceof ConnectedUser) {
return $user;
}
$token = $this->requests->getMainRequest()?->cookies->getString(AuthService::COOKIE);
return $token ? $this->auth->currentUser($token) : null;
}
}
|
Una extensión de [Twig] (ejemplo 16), que agrega a las vistas dos funciones que todas las páginas necesitan:
- [user()]: el usuario con sesión iniciada, o [null], para la barra de navegación. Normalmente, es el que proviene del servicio [Security] (línea 44). Sin embargo, una página de error 404 o 405 se genera antes de que el firewall examine la solicitud: el enrutamiento, que falla, tiene prioridad sobre este (ejemplo 24). Entonces el usuario se obtiene directamente del token (líneas 48–49) para que la barra de navegación de la página de error esté completa. [getMainRequest] obtiene la solicitud principal; el operador [?->] devuelve [null] sin llamar al método si el objeto es [null];
- [titles()]: los tratamientos posibles para una persona ([Mr], [Mme], [Melle]), una constante de la clase del formulario de persona (véase más adelante).
[$this->user(...)] (línea 31) es la sintaxis para funciones de primera clase ([PHP] 8.1): crea una función que llama al método [user] de ese objeto. La extensión se declara automáticamente como [Twig], igual que en el ejemplo 16: el contenedor reconoce una clase que hereda de [AbstractExtension].
11.16. Diccionarios
Los textos de la interfaz son los mismos que los de otras versiones de la aplicación, que los almacenaban en archivos JSON anidados:
| {
"LOGIN": {
"TITLE": "Login",
"USERNAME": "Login"
}
}
|
La versión [Flask] los «aplanaba» al iniciar: [LOGIN.TITLE] hacía referencia al texto [Login]. Los diccionarios YAML de [Symfony] hacen lo mismo (ejemplo 22): las claves anidadas se separan con puntos. Por eso simplemente convertimos los archivos JSON a YAML y reemplazamos los parámetros [{{name}}] de las otras versiones por los de la sintaxis ICU, [{name}] (el sufijo [+intl-icu] en los nombres de archivo, ejemplo 22):
| APP:
TITLE: 'RdvMedecins'
LOGOUT: 'Log out'
DOCTORS:
ADDED: 'Doctor {name} has been added (login: {login}).'
ERRORS:
TOO_MANY_ATTEMPTS: 'Too many failed attempts. Try again in {minutes, plural, one {# minute} other {# minutes}}.'
|
Los archivos [translations/messages+intl-icu.fr.yaml] y [messages+intl-icu.en.yaml] no se reproducen aquí. Una clave se representa mediante [{{ 'APP.LOGOUT'|trans }}] en una vista, y un texto con parámetros mediante [{{ 'DOCTORS.ADDED'|trans({name: ..., login: ...}) }}]. Una clave ausente del diccionario se muestra tal cual, lo que señala de inmediato una omisión (y el comando [php bin/console debug:translation fr] enumera las claves usadas por las vistas que faltan en el diccionario). ICU permite algo que las versiones anteriores no podían hacer: el plural («1 minute», «15 minutes»), mediante el formato [plural] (ejemplo 22). Se agregó una entrada de texto: [ERRORS.PAGE_EXPIRED], el mensaje de la página 419, que no existe en las otras versiones.
Los mensajes de error de los formularios también son claves de estos diccionarios ([ERRORS.FIRSTNAME_REQUIRED]...): el componente de validación los traduce en el dominio [messages], gracias a la línea [translation_domain: messages] de [framework.yaml]. Sus parámetros corresponden a las restricciones: [{limit}], para la longitud mínima de la contraseña.
Los formularios de «persona» son formularios del componente Form (ejemplos 18 y 19): una clase de tipo describe los campos y sus restricciones; la acción crea el formulario ([createForm]), le pasa la solicitud ([handleRequest]) y luego verifica si fue enviado y es válido ([isSubmitted], [isValid]). Un formulario inválido se vuelve a mostrar, con los datos ingresados por el usuario y los mensajes de error debajo de los campos (excepto las contraseñas: un campo [PasswordType] nunca se vuelve a mostrar). El token anti-CSRF de cada formulario lo verifica el propio componente.
| <?php
// =========================================================================
// src/Form/PersonFieldsType.php: los campos de los formularios de "persona" y sus
// restricciones (véanse los ejemplos 18 y 19). Tres formularios comparten los mismos
// campos de identidad (tratamiento, nombre, apellido):
//
// PersonFieldsType tratamiento, nombre, apellido
// ├─ PersonType + login / contraseña OPCIONALES, versión
// │ (el ADMIN agrega o modifica un médico / cliente)
// ├─ RegistrationType + login / contraseña / confirmación OBLIGATORIOS
// │ (un paciente crea su cuenta)
// └─ MyAccountType + login, nueva contraseña opcional, contraseña
// ACTUAL OBLIGATORIA, versión
// (un paciente modifica su cuenta)
//
// Las clases hijas HEREDAN de esta (en el sentido de PHP): su buildForm
// llama primero al del padre y luego agrega sus campos.
//
// Los formularios no tienen clase de datos (data_class, véase el ejemplo 19): la
// entrada validada es un arreglo asociativo, que el método data() convierte en
// PersonData para la capa de negocio.
//
// Las etiquetas, los textos de ayuda y los mensajes de error son CLAVES de los
// diccionarios: el componente Form traduce las etiquetas y los textos de ayuda, el
// componente Validator los mensajes (véase config/packages/framework.yaml).
// Secuencialmente: las restricciones se verifican en orden y la verificación
// se detiene en la primera que no se cumple - un solo mensaje por campo.
// Las longitudes máximas son las de las columnas SQL.
// =========================================================================
namespace App\Form;
use App\Business\PersonData;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\CallbackTransformer;
use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\Validator\Constraints as Assert;
abstract class PersonFieldsType extends AbstractType
{
public const TITLES = ['Mr', 'Mme', 'Melle'];
// login: letras minúsculas, dígitos, punto, guion, guion bajo - 30 caracteres como máximo
public const LOGIN_FORMAT = '/^[a-z0-9._-]{1,30}$/';
// longitud mínima de una contraseña ELEGIDA por un paciente
public const PASSWORD_MIN = 6;
public function buildForm(FormBuilderInterface $builder, array $options): void
{
$builder
// array_combine: ['Mr' => 'Mr', ...], la etiqueta y el valor de cada
// opción; choice_translation_domain false: los tratamientos no se traducen
->add('title', ChoiceType::class, [
'label' => 'PERSONS.TITLE_LABEL',
'choices' => array_combine(self::TITLES, self::TITLES),
'choice_translation_domain' => false,
'invalid_message' => 'ERRORS.INVALID_TITLE',
'constraints' => [new Assert\NotBlank(message: 'ERRORS.INVALID_TITLE')],
])
->add('first_name', TextType::class, [
'label' => 'PERSONS.FIRSTNAME_LABEL',
'attr' => ['maxlength' => 20],
'constraints' => [new Assert\Sequentially([
new Assert\NotBlank(message: 'ERRORS.FIRSTNAME_REQUIRED'),
new Assert\Length(max: 20, maxMessage: 'ERRORS.FIRSTNAME_TOO_LONG'),
])],
])
->add('last_name', TextType::class, [
'label' => 'PERSONS.LASTNAME_LABEL',
'attr' => ['maxlength' => 20],
'constraints' => [new Assert\Sequentially([
new Assert\NotBlank(message: 'ERRORS.LASTNAME_REQUIRED'),
new Assert\Length(max: 20, maxMessage: 'ERRORS.LASTNAME_TOO_LONG'),
])],
]);
}
// las opciones comunes: un formulario inválido devuelto tal cual al navegador,
// sin validación por parte del propio navegador (véase el ejemplo 19: el SERVIDOR
// es quien tiene la autoridad); el mensaje de un token anti-CSRF incorrecto
public function configureOptions(OptionsResolver $resolver): void
{
$resolver->setDefaults([
'attr' => ['novalidate' => 'novalidate'],
'csrf_message' => 'ERRORS.PAGE_EXPIRED',
]);
}
// -----------------------------------------------------------------------
// el campo de login, común a los formularios hijos. Un login siempre está en
// minúsculas: un TRANSFORMADOR (CallbackTransformer) convierte lo ingresado ANTES de
// su validación. Su primera función convierte el valor del formulario en texto
// mostrado (aquí, nada que hacer), la segunda lo ingresado en el valor del formulario
// -----------------------------------------------------------------------
protected static function addLogin(FormBuilderInterface $builder, array $options): void
{
$builder->add('login', TextType::class, ['label' => 'PERSONS.LOGIN_LABEL', 'required' => false,
'attr' => ['maxlength' => 30, 'autocomplete' => 'off'], ...$options]);
$builder->get('login')->addModelTransformer(new CallbackTransformer(
fn (?string $login) => $login,
fn (?string $login) => $login === null ? null : mb_strtolower($login)));
}
// lo ingresado validado -> los datos esperados por la capa de negocio. Los campos
// vacíos son null (el componente Form los convierte así)
public static function data(array $input): PersonData
{
$password = $input['password'] ?? null;
return new PersonData($input['title'], $input['last_name'], $input['first_name'],
$input['login'] ?? null, $password === '' ? null : $password,
isset($input['version']) && ctype_digit((string) $input['version']) ? (int) $input['version'] : null);
}
}
|
Tres formularios comparten los mismos campos de identidad (tratamiento, nombre, apellido): el formulario del administrador (para un médico o un cliente), el formulario de creación de cuenta de paciente y «Administrar mi cuenta». Su clase padre común es abstracta; cada una de sus clases hijas amplía estos campos. Ninguno de estos formularios tiene una clase de datos (la opción [data_class] del ejemplo 19): sus datos consisten en un arreglo asociativo, con un elemento por campo.
- líneas 44–50: las reglas de entrada, en forma de constantes, que también leen las vistas (la lista de tratamientos, mediante la función [titles()] de la extensión [Twig]);
- líneas 57–63: el tratamiento, una lista ([ChoiceType], ejemplo 18). [array_combine] genera el arreglo [['Mr' => 'Mr', ...]]: la etiqueta de cada opción y su valor. [choice_translation_domain: false]: los tratamientos no son claves de traducción. [invalid_message]: el mensaje para un valor que no forma parte de la lista (una solicitud construida manualmente);
- Líneas 64–79: nombre y apellido. La restricción [Sequentially] (ejemplo 09) verifica sus restricciones en orden y se detiene en la primera que no se cumple: un solo mensaje por campo. [Length(max: 20)]: 20 caracteres como máximo; la longitud de la columna es SQL; el atributo HTML [maxlength] impide ingresar más caracteres. Los espacios al principio y al final de una entrada los elimina el propio componente Form (la opción [trim] de un campo de texto está establecida en [true]), y una entrada vacía se convierte en [null]; en cambio, un campo con la opción [PasswordType] no se limpia: los espacios pueden formar parte de una contraseña;
- Líneas 85–91: opciones comunes. [novalidate] desactiva las validaciones del navegador ([required], [maxlength]...) cuando se envía el formulario: la validación la realiza el servidor, y su resultado es definitivo (ejemplo 19). [csrf_message]: el mensaje para un token anti-CSRF inválido, el de la página 419;
- líneas 99–106: el login, común a los tres formularios, al que cada uno agrega sus propias opciones (el operador [...] agrega los elementos de un arreglo a otro; una clave presente en ambos toma el último valor). Un login siempre va en minúsculas: un transformador convierte la entrada antes de que se valide. Un transformador de modelo ([addModelTransformer]) tiene dos funciones: la primera transforma los datos del formulario en un valor mostrado (en este caso, no se requiere ninguna acción) y la segunda transforma el valor ingresado en datos del formulario. [CallbackTransformer] crea un transformador a partir de estas dos funciones;
- Líneas 110–116: la entrada validada se convierte en [PersonData] para la capa de negocio: la capa de negocio no conoce los formularios. Una contraseña vacía es [null] (sin cambios, o el valor predeterminado); la versión (el campo oculto del bloqueo optimista, por ejemplo, 28) es un entero, o [null].
| <?php
// src/Form/PersonType.php: el formulario de un médico o de un cliente (ADMIN):
// login y contraseña OPCIONALES (véase src/Business/PersonData.php).
namespace App\Form;
use Symfony\Component\Form\Extension\Core\Type\HiddenType;
use Symfony\Component\Form\Extension\Core\Type\PasswordType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\Validator\Constraints as Assert;
class PersonType extends PersonFieldsType
{
public function buildForm(FormBuilderInterface $builder, array $options): void
{
parent::buildForm($builder, $options);
$creation = $options['creation'];
// se acepta un campo vacío: las restricciones solo se aplican a un valor ingresado
self::addLogin($builder, [
'help' => $creation ? 'PERSONS.LOGIN_HELP_CREATE' : 'PERSONS.LOGIN_HELP_EDIT',
'constraints' => [new Assert\Regex(self::LOGIN_FORMAT, message: 'ERRORS.INVALID_LOGIN')],
]);
$builder->add('password', PasswordType::class, [
'label' => 'PERSONS.PASSWORD_LABEL',
'required' => false,
'help' => $creation ? 'PERSONS.PASSWORD_HELP_CREATE' : 'PERSONS.PASSWORD_HELP_EDIT',
'attr' => ['maxlength' => 72, 'autocomplete' => 'new-password'],
// 72 caracteres como máximo: más allá, bcrypt ignora el resto
'constraints' => [new Assert\Length(max: 72, maxMessage: 'ERRORS.PASSWORD_TOO_LONG')],
]);
// modificación: la versión del registro mostrado, en un campo oculto (el
// bloqueo optimista)
if (! $creation) {
$builder->add('version', HiddenType::class);
}
}
// una opción propia (véase el ejemplo 28): formulario de creación o formulario de modificación
public function configureOptions(OptionsResolver $resolver): void
{
parent::configureOptions($resolver);
$resolver->setDefaults(['creation' => true]);
}
}
|
El formulario del administrador. [parent::buildForm] (línea 17) agrega los campos de la clase padre; luego vienen el nombre de usuario y la contraseña, que son opcionales: una restricción se aplica solo a un valor ingresado (excepto [NotBlank]), por lo que un campo vacío se acepta. [Regex] valida el formato del login; [Length(max: 72)] limita la longitud de la contraseña: [bcrypt] solo considera los primeros 72 bytes (ejemplo 25). La opción [creation] (líneas 40–44), una opción que diseñamos nosotros, declarada con su valor predeterminado (ejemplo 28), distingue entre creación y modificación: los textos de ayuda difieren («Opcional: por defecto, el apellido en minúsculas», «Dejar vacío para conservarlo sin cambios»), y solo la modificación tiene el campo oculto de la versión.
| <?php
// src/Form/RegistrationType.php: "Create a patient account": login, contraseña y
// confirmación OBLIGATORIOS.
namespace App\Form;
use Symfony\Component\Form\Extension\Core\Type\PasswordType;
use Symfony\Component\Form\Extension\Core\Type\RepeatedType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Validator\Constraints as Assert;
class RegistrationType extends PersonFieldsType
{
public function buildForm(FormBuilderInterface $builder, array $options): void
{
parent::buildForm($builder, $options);
self::addLogin($builder, [
'required' => true,
'help' => 'REGISTRATION.LOGIN_HELP',
'attr' => ['maxlength' => 30, 'autocomplete' => 'username'],
'constraints' => [new Assert\Sequentially([
new Assert\NotBlank(message: 'ERRORS.LOGIN_REQUIRED'),
new Assert\Regex(self::LOGIN_FORMAT, message: 'ERRORS.INVALID_LOGIN'),
])],
]);
$builder->add('password', RepeatedType::class, self::repeatedPassword(true));
}
// -----------------------------------------------------------------------
// la contraseña y su confirmación: un campo REPEATED (véase el ejemplo 19), cuyas
// dos entradas deben ser idénticas (de lo contrario: invalid_message). Común a
// el registro (obligatorio) y a la cuenta del paciente (opcional).
// {limit}: en el mensaje PASSWORD_TOO_SHORT, la longitud mínima;
// help_translation_parameters: los parámetros del texto de ayuda
// -----------------------------------------------------------------------
public static function repeatedPassword(bool $required): array
{
$length = new Assert\Length(min: self::PASSWORD_MIN, max: 72,
minMessage: 'ERRORS.PASSWORD_TOO_SHORT', maxMessage: 'ERRORS.PASSWORD_TOO_LONG');
return [
'type' => PasswordType::class,
'required' => $required,
'invalid_message' => 'ERRORS.PASSWORDS_DIFFER',
'first_options' => [
'label' => $required ? 'PERSONS.PASSWORD_LABEL' : 'MY_ACCOUNT.NEW_PASSWORD_LABEL',
'help' => $required ? 'REGISTRATION.PASSWORD_HELP' : 'PERSONS.PASSWORD_HELP_EDIT',
'help_translation_parameters' => ['min' => self::PASSWORD_MIN],
],
'second_options' => ['label' => 'ACCOUNT.CONFIRMATION_LABEL'],
'options' => ['attr' => ['maxlength' => 72, 'autocomplete' => 'new-password']],
'constraints' => $required
? [new Assert\Sequentially([new Assert\NotBlank(message: 'ERRORS.PASSWORD_REQUIRED'), $length])]
: [$length],
];
}
}
|
Creación de una cuenta de paciente: el login y la contraseña son obligatorios, y la contraseña debe confirmarse. La contraseña es un campo repetido ([RepeatedType], ejemplo 19): dos campos [PasswordType] cuyas entradas deben ser idénticas (de lo contrario, el mensaje [invalid_message] se muestra debajo del primero). Sus opciones las genera un método estático, compartido con «Administrar mi cuenta» (líneas 36–55):
- [first_options] y [second_options]: las opciones de cada uno de los dos campos; [options]: las opciones que tienen en común;
- [help_translation_parameters]: los parámetros del texto de ayuda, «Al menos {min} caracteres.»;
- la longitud mínima se exige solo para la contraseña elegida por un paciente (6 caracteres). El mensaje [ERRORS.PASSWORD_TOO_SHORT] contiene [{limit}], el parámetro que la restricción [Length] proporciona a su mensaje;
- [autocomplete="new-password"]: el navegador ofrece generar una contraseña en lugar de rellenar el campo con la contraseña guardada.
| <?php
// src/Form/MyAccountType.php: "Manage my account" (un paciente): login obligatorio,
// nueva contraseña opcional, contraseña ACTUAL OBLIGATORIA.
namespace App\Form;
use Symfony\Component\Form\Extension\Core\Type\HiddenType;
use Symfony\Component\Form\Extension\Core\Type\PasswordType;
use Symfony\Component\Form\Extension\Core\Type\RepeatedType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Validator\Constraints as Assert;
class MyAccountType extends PersonFieldsType
{
public function buildForm(FormBuilderInterface $builder, array $options): void
{
parent::buildForm($builder, $options);
self::addLogin($builder, [
'required' => true,
'attr' => ['maxlength' => 30, 'autocomplete' => 'username'],
'constraints' => [new Assert\Sequentially([
new Assert\NotBlank(message: 'ERRORS.LOGIN_REQUIRED'),
new Assert\Regex(self::LOGIN_FORMAT, message: 'ERRORS.INVALID_LOGIN'),
])],
]);
// opcional: vacío = contraseña sin cambios
$builder->add('password', RepeatedType::class, RegistrationType::repeatedPassword(false));
// la contraseña ACTUAL, obligatoria para cualquier modificación de la cuenta; mapped
// false: no forma parte de los datos del formulario, se lee por separado
$builder->add('current_password', PasswordType::class, [
'label' => 'MY_ACCOUNT.CURRENT_PASSWORD_LABEL',
'help' => 'MY_ACCOUNT.CURRENT_PASSWORD_HELP',
'mapped' => false,
'attr' => ['maxlength' => 72, 'autocomplete' => 'current-password'],
'constraints' => [new Assert\NotBlank(message: 'ERRORS.CURRENT_PASSWORD_REQUIRED')],
]);
$builder->add('version', HiddenType::class);
}
}
|
«Administrar mi cuenta»: la nueva contraseña es opcional (vacía: sin cambios), y la contraseña actual es obligatoria. [mapped: false] (línea 33): la contraseña actual no forma parte de los datos del formulario ([getData()] no la contiene); la acción la lee por separado, mediante [$form->get('current_password')->getData()]. Aquí no la valida el formulario, sino la acción: una contraseña incorrecta debe contarse como un inicio de sesión fallido por el limitador de intentos. ([Symfony] tiene una restricción, [UserPassword], que compara la contraseña ingresada con la del usuario con sesión iniciada; esta restricción no es aplicable aquí: nuestro usuario con sesión iniciada, [ConnectedUser], no contiene el hash de su contraseña.)
11.18. Plantillas de vista
La carpeta [src/Views] contiene las plantillas de vista: objetos creados por una acción, que la vista simplemente lee. La regla que siguen todas las páginas: sin lógica en las vistas. Las acciones preparan datos ya formateados («Sra. Marie PELISSIER», «8:00 – 8:20») y ya filtrados según el rol del usuario; las vistas colocan estos datos en el HTML. Todas estas clases son de tipo [readonly] y solo tienen propiedades, que inicializa su constructor. La carpeta está excluida de los servicios ([config/services.yaml]): son datos, no servicios.
| <?php
// src/Views/OptionView.php: una opción de una lista desplegable (médico, paciente).
//
// La carpeta src/Views contiene los "modelos de vista": objetos
// construidos de una sola vez por una acción, que la vista se limita a leer. Regla
// seguida por todas las páginas: sin lógica en las vistas. Las acciones
// preparan datos YA formateados ("Mme Marie PELISSIER",
// "8:00 - 8:20", selected = true...) y ya filtrados según el rol del
// usuario; las vistas se limitan a colocarlos en el HTML.
namespace App\Views;
readonly class OptionView
{
public function __construct(
public int $id,
public string $label,
public bool $selected,
) {
}
}
|
Una opción de una lista desplegable: el identificador, la etiqueta y si la opción está seleccionada.
| <?php
// src/Views/ScheduleRow.php: una fila de la agenda mostrada (un horario).
namespace App\Views;
readonly class ScheduleRow
{
public function __construct(
public int $slotId,
public string $time, // "8:00 - 8:20"
public bool $free,
// nombre mostrado para un horario ocupado; null = "Booked"
public ?string $patient,
public bool $mine, // la cita del paciente con sesión iniciada
public bool $bookable, // ¿mostrar el botón "Book"?
public string $bookUrl,
// se define solo si se muestra el botón "Cancel"
public ?int $appointmentId,
) {
}
}
|
Una entrada del calendario: una franja horaria y lo que el usuario con sesión iniciada está autorizado a ver y hacer con ella. [patient] se rellena solo si el usuario tiene permiso para ver el nombre del paciente; [bookable] indica si se debe mostrar el botón «Reservar»; [appointmentId] indica si se debe mostrar el botón «Cancelar».
| <?php
// src/Views/ScheduleView.php: la agenda mostrada: el médico, el día, las filas.
namespace App\Views;
readonly class ScheduleView
{
/** @param list<ScheduleRow> $rows */
public function __construct(
public string $doctor, // "Mme Marie PELISSIER"
public string $day, // "Wednesday 23 September 2026"
public array $rows,
) {
}
}
|
| <?php
// src/Views/BookingView.php: el diálogo de reserva de un horario.
namespace App\Views;
readonly class BookingView
{
/** @param list<OptionView> $clients */
public function __construct(
public int $slotId,
public string $time,
// ADMIN / DOCTOR: los pacientes entre los que elegir
public array $clients,
// USER: el paciente es él mismo
public ?string $patient,
) {
}
}
|
El calendario mostrado y la ventana de reserva: para el administrador y los médicos, la lista de pacientes entre los cuales elegir; para un paciente, su propio nombre. El comentario [/** @param list<ScheduleRow> $rows */] especifica, para los editores y las herramientas de análisis, el contenido del arreglo: [PHP] solo puede declarar el tipo [array].
| <?php
// src/Views/PersonKeys.php: las claves de traducción específicas de cada tipo de
// persona (médicos o clientes), para las vistas comunes persons/list y
// persons/form.
namespace App\Views;
readonly class PersonKeys
{
public function __construct(
public string $title, // "Doctors"
public string $add, // "Add a doctor"
public string $edit, // "Edit a doctor"
public string $empty, // "No doctors."
public string $confirmDelete, // "Delete this doctor... ?"
public string $added, // "Doctor {name} has been added (login: {login})."
public string $edited,
public string $deleted,
) {
}
// las ocho claves de una sección del diccionario ("DOCTORS", "CLIENTS")
public static function of(string $section): self
{
return new self("$section.TITLE", "$section.ADD", "$section.EDIT", "$section.EMPTY",
"$section.DELETE_CONFIRM", "$section.ADDED", "$section.UPDATED", "$section.DELETED");
}
}
|
Claves de traducción específicas de los médicos o de los clientes, para las dos vistas que tienen en común. El método estático [of] (líneas 23–27) genera las ocho claves de una sección de los diccionarios: [PersonKeys::of('DOCTORS')] produce [DOCTORS.TITLE], [DOCTORS.ADD]... [new self(...)] crea un objeto de la propia clase.
| <?php
// src/Views/AppointmentView.php: una cita próxima, en el área del paciente.
namespace App\Views;
readonly class AppointmentView
{
public function __construct(
public int $id,
public string $day, // "Wednesday 23 September 2026"
public string $time, // "8:00 - 8:20"
public string $doctor, // "Mme Marie PELISSIER"
public string $scheduleUrl, // la agenda del médico en ese día
) {
}
}
|
Una próxima cita en el área del paciente.
11.19. La capa web: rutas y controladores
11.19.1. Rutas
Las rutas se describen mediante los atributos [#[Route]] de los controladores (ejemplo 02), que se cargan desde el archivo [config/routes.yaml]. El comando [debug:router] las enumera todas, junto con sus nombres, métodos y rutas:
| $ php bin/console debug:router
--------------------- ---------- ----------------------
Name Method Path
--------------------- ---------- ----------------------
home GET /
login GET /login
login_submit POST /login
logout POST /logout
clients_list GET /clients
clients_add GET|POST /clients/add
clients_edit GET|POST /clients/{id}/edit
clients_delete POST /clients/{id}/delete
doctors_list GET /doctors
doctors_add GET|POST /doctors/add
doctors_edit GET|POST /doctors/{id}/edit
doctors_delete POST /doctors/{id}/delete
language GET /language/{code}
area GET /my-area
area_cancel POST /my-area/cancel
account GET|POST /my-account
account_delete POST /my-account/delete
registration_access POST /register/access
registration GET|POST /register
schedule GET /schedule
schedule_book POST /schedule/book
schedule_cancel POST /schedule/cancel
--------------------- ---------- ----------------------
|
Las URL corresponden a las de otras versiones de la aplicación: modificar y eliminar un médico son solicitudes POST ([/doctors/{id}/edit], [/doctors/{id}/delete]), no PUT y DELETE como en el ejemplo 28. El código siempre genera la URL a partir de los nombres de las rutas ([redirectToRoute('login')], [path('schedule')] en las vistas, ejemplo 04): para cambiar una URL basta con modificar su atributo [#[Route]].
Las reglas de acceso no están en los controladores, sino en las reglas [access_control] de [config/packages/security.yaml], como se mostró antes: una regla por prefijo de URL ([^/(doctors|clients)] para el administrador, [^/my-] para los pacientes...), y una regla final que exige un usuario autenticado para todas las demás URL. Las rutas URL de la aplicación se eligieron con este fin: todas las páginas de un mismo rol comienzan igual. Una ruta URL que no coincide con ninguna ruta devuelve una página 404, incluso a un visitante anónimo; una solicitud GET dirigida a una URL que existe solo como POST ([/logout]) da como resultado una página 405, presentada como «página no encontrada» (manejador [ErrorPage]).
11.19.2. src/Controller/LanguageController.php
| <?php
// =========================================================================
// src/Controller/LanguageController.php: GET /language/fr, GET /language/en: los dos
// botones FR / EN de la barra de navegación. Ruta pública: debe poderse
// cambiar el idioma antes de iniciar sesión.
//
// La elección se recuerda en una cookie: en cada solicitud siguiente, el listener
// SetLanguage la vuelve a leer y fija el idioma de la solicitud. Luego volvemos a la
// página de la que veníamos (véase el ejemplo 22).
// =========================================================================
namespace App\Controller;
use App\EventListener\SetLanguage;
use App\Web\BaseController;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
class LanguageController extends BaseController
{
public function __construct(#[Autowire(env: 'bool:COOKIE_SECURE')] private bool $cookieSecure)
{
}
// {code} se limita a los idiomas admitidos (requirements): /language/de da una página 404
#[Route('/language/{code}', name: 'language', requirements: ['code' => 'fr|en'], methods: ['GET'])]
public function change(Request $request, string $code): Response
{
$response = $this->redirect($this->originPage($request));
$response->headers->setCookie(Cookie::create(SetLanguage::COOKIE, $code)
->withExpires(new \DateTimeImmutable('+1 year'))
->withSecure($this->cookieSecure)
->withHttpOnly(true)
->withSameSite(Cookie::SAMESITE_LAX));
return $response;
}
// -----------------------------------------------------------------------
// la página anterior, según el encabezado HTTP "Referer" enviado por el navegador.
// Solo se conserva su ruta (/schedule?...): redirigir a una dirección
// completa proporcionada por la solicitud permitiría enviar al usuario a
// otro sitio (la llamada vulnerabilidad de "open redirect").
// -----------------------------------------------------------------------
private function originPage(Request $request): string
{
$referer = $request->headers->get('Referer');
$url = $referer ? parse_url($referer) : false;
$path = $url['path'] ?? '';
// "//site.com/..." sería entendido por el navegador como una dirección en
// OTRO sitio: también se rechaza
if (! isset($url['scheme']) || ! str_starts_with($path, '/') || str_starts_with($path, '//')
|| str_starts_with($path, '/language/')) {
return '/';
}
return isset($url['query']) ? "$path?{$url['query']}" : $path;
}
}
|
Los botones FR / EN de la barra de navegación: la selección del idioma se almacena en una cookie durante un año (ejemplo 22), y luego el navegador regresa a la página de la que provenía. La cookie es [HttpOnly]: el [JavaScript] de la página no necesita leerla. No está firmada: el listener [SetLanguage] verifica su valor, y un valor desconocido da como resultado inglés (véase el capítulo sobre los intervalos).
- Línea 29: [requirements: ['code' => 'fr|en']] acepta solo estos dos valores para el parámetro [{code}]: [/language/de] no corresponde a ninguna ruta (página 404);
- Líneas 47–59: la página anterior se especifica mediante el encabezado
HTTP ***[Referer], que el navegador envía con la solicitud. Este dato lo proporciona el cliente y, por lo tanto, es sospechoso: redirigir a una URL completa tomada de la solicitud permitiría a un atacante enviar al usuario a su propio sitio mediante un enlace a [/language/fr] que incluya un ***[Referer] falso (la llamada vulnerabilidad de «redirección abierta» ). Por eso, conservamos solo la ruta y los parámetros ([/schedule?doctorId=1&...]), extraídos por la función [parse_url] de [PHP], que divide una URL en sus partes ([scheme], [host], [path], [query]...). Una ruta que comienza con [//] también se rechaza: un navegador interpreta [//site.com/page] como una dirección en otro sitio. Por último, no se puede regresar a [/language/...]: sería un bucle.
11.19.3. src/Controller/ScheduleController.php
| <?php
// =========================================================================
// src/Controller/ScheduleController.php: la página de agenda: elección de un médico y
// de un día, agenda de ese médico en ese día, reserva y cancelación de
// citas.
//
// GET /schedule?doctorId=1&day=2026-09-23 la página
// GET /schedule?doctorId=1&day=2026-09-23&book=7 la misma página, con el
// diálogo de reserva
// del horario 7 abierto
// POST /schedule/book crea una cita
// POST /schedule/cancel cancela una cita
//
// Toda la página queda descrita por su URL: se puede recargar, guardar en favoritos,
// se puede usar el botón "Atrás" del navegador - sin una sola línea de
// JavaScript.
//
// Lo que cada uno ve y puede hacer:
//
// | rol | horario ocupado mostrado | Book | Cancel |
// |---------------|-----------------------------------|--------------------|---------|
// | ADMIN, DOCTOR | nombre del paciente | para un paciente | sí |
// | | | elegido de una lista | |
// | USER (paciente)| "Booked", o SU nombre si es | para sí mismo, si | no (*) |
// | | su propia cita | no tiene ninguna | |
// | | | próxima | |
//
// (*) el paciente cancela su cita desde su página "My area".
//
// CONFIDENCIALIDAD: para un paciente, el nombre de los OTROS pacientes no está
// simplemente oculto por la vista - nunca se pasa a la vista. Por lo tanto, el HTML enviado
// al navegador no lo contiene, ni siquiera oculto (un simple "View page
// source" lo revelaría de otro modo).
//
// Ninguna reserva en el pasado: el botón "Book" solo aparece para
// hoy y los días siguientes (y la capa de negocio la rechazaría
// de todos modos).
//
// Seguridad: todas las URL /schedule exigen un usuario autenticado y
// /schedule/cancel el rol ADMIN o DOCTOR (véase config/packages/security.yaml).
// =========================================================================
namespace App\Controller;
use App\Domain\DoctorDaySchedule;
use App\Entity\Client;
use App\Entity\Person;
use App\Entity\Role;
use App\Business\Dates;
use App\Business\BusinessException;
use App\Views\ScheduleView;
use App\Views\ScheduleRow;
use App\Views\OptionView;
use App\Views\BookingView;
use App\Web\ApplicationModel;
use App\Web\BaseController;
use App\Web\Flash;
use App\Web\Message;
use App\Web\Utils;
use DateTimeImmutable;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
use Symfony\Component\Routing\Attribute\Route;
#[Route('/schedule')]
class ScheduleController extends BaseController
{
public function __construct(
private ApplicationModel $application,
private Utils $utils,
private Flash $flash,
) {
}
// -----------------------------------------------------------------------
// GET /schedule
// Los parámetros de la URL se leen en bruto ($request->query), para distinguir un
// parámetro AUSENTE (null) de un parámetro VACÍO (?doctorId=).
// -----------------------------------------------------------------------
#[Route('', name: 'schedule', methods: ['GET'])]
public function show(Request $request): Response
{
$error = null;
$user = $this->utils->user();
$rights = $this->rights();
// el día: el de la URL si es válido; de lo contrario, hoy
$day = Dates::today();
$rawDay = $request->query->get('day');
if ($rawDay !== null) {
$requestedDay = Utils::validDate($rawDay);
if ($requestedDay !== null) {
$day = $requestedDay;
} else {
$error = 'ERRORS.INVALID_DATE';
}
}
$bookableDay = $day >= Dates::today();
// el médico: el de la URL; en su defecto, para un médico con sesión iniciada, él mismo
$rawDoctorId = $request->query->get('doctorId');
$doctorId = Utils::positiveInteger($rawDoctorId);
if ($rawDoctorId === null && $user->role === Role::DOCTOR) {
$doctorId = $this->application->getDoctorByUserId($user->userId)?->getId();
}
// la lista desplegable de los médicos
$doctors = array_map(fn (Person $d) => self::option($d, $d->getId() === $doctorId),
$this->application->getAllDoctors());
// la agenda, si se ha elegido un médico (y la fecha es válida)
$schedule = null;
if ($doctorId !== null && $error === null) {
$doctorSchedule = $this->application->getDoctorDaySchedule($doctorId, $day);
if ($doctorSchedule === null) {
$error = 'ERRORS.DOCTOR_NOT_FOUND';
} else {
$schedule = $this->scheduleView($doctorSchedule, $rights, $bookableDay);
}
}
// el diálogo de reserva: solo si este usuario puede reservar el horario
// solicitado. array_find: el primer elemento que cumple la condición
// (null si no hay ninguno)
$booking = null;
$slotId = Utils::positiveInteger($request->query->get('book'));
if ($schedule !== null && $slotId !== null) {
$row = array_find($schedule->rows,
fn (ScheduleRow $r) => $r->slotId === $slotId && $r->bookable);
if ($row !== null) {
$booking = new BookingView(
$row->slotId,
$row->time,
$rights['manager']
? array_map(fn (Client $c) => self::option($c, false), $this->application->getAllClients())
: [],
$rights['patient']?->label());
}
}
return $this->render('schedule.html.twig', [
'pageTitle' => 'SCHEDULE.PAGE_TITLE',
'error' => $error ? new Message($error) : null,
'doctors' => $doctors,
'doctorId' => $doctorId,
'day' => Utils::iso($day),
'schedule' => $schedule,
'booking' => $booking,
// la agenda mostrada, sin diálogo de reserva
'backUrl' => $doctorId !== null ? $this->scheduleUrl($doctorId, $day) : $this->generateUrl('schedule'),
'info' => $this->patientInfo($rights, $schedule),
]);
}
// -----------------------------------------------------------------------
// POST /schedule/book campos: doctorId, day, slotId, clientId
//
// Para un paciente (USER), el campo clientId se IGNORA: siempre reserva
// para sí mismo. Confiar en un campo enviado por el navegador
// permitiría a un paciente astuto reservar a nombre de otro.
//
// Patrón "Post / Redirect / Get": sea cual sea el resultado, aquí no se construye ninguna página
// - se deja un mensaje flash y se redirige a la agenda
// (véase el ejemplo 20).
// -----------------------------------------------------------------------
#[Route('/book', name: 'schedule_book', methods: ['POST'])]
public function book(Request $request): Response
{
$this->checkCsrf($request);
[$doctorId, $day] = $this->requestedSchedule($request);
$slotId = Utils::positiveInteger($request->request->get('slotId'));
if ($doctorId === null || $slotId === null) {
// -> página de "solicitud inválida" (véase src/EventListener/ErrorPage.php)
throw new BadRequestHttpException('invalid schedule or slot');
}
$user = $this->utils->user();
if ($user->isPatient()) {
$client = $this->utils->connectedPatient();
} else {
$clientId = Utils::positiveInteger($request->request->get('clientId'));
if ($clientId === null) {
// ningún paciente elegido: se vuelve a abrir el diálogo de reserva
$this->flash->error('ERRORS.CHOOSE_PATIENT');
return $this->redirect($this->scheduleUrl($doctorId, $day, $slotId));
}
$client = $this->application->getClientById($clientId);
}
$slot = $this->application->getSlotById($slotId);
if ($client === null) {
$this->flash->error('ERRORS.PATIENT_NOT_FOUND');
} elseif ($slot === null || $slot->getDoctor()->getId() !== $doctorId) {
$this->flash->error('ERRORS.SLOT_NOT_FOUND');
} else {
try {
// la capa de negocio verifica las reglas (no en el pasado, una sola cita próxima por
// paciente, horario libre)
$this->application->addAppointment($day, $slot, $client);
$this->flash->success('SCHEDULE.BOOKED');
} catch (BusinessException $e) {
// la misma regla, pero con un mensaje en segunda persona cuando es el propio
// paciente quien reserva ("You already have..." en lugar de
// "This patient..."). Las demás excepciones (verdaderas anomalías) no se
// capturan: página 500.
if ($e->key === 'ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT' && $user->isPatient()) {
$this->flash->error('SCHEDULE.ALREADY_BOOKED_INFO');
} else {
$this->flash->error($e->key, $e->params);
}
}
}
return $this->redirect($this->scheduleUrl($doctorId, $day));
}
// -----------------------------------------------------------------------
// POST /schedule/cancel campos: appointmentId, doctorId, day
// (un paciente cancela SU cita desde "My area", no desde aquí)
// -----------------------------------------------------------------------
#[Route('/cancel', name: 'schedule_cancel', methods: ['POST'])]
public function cancel(Request $request): Response
{
$this->checkCsrf($request);
[$doctorId, $day] = $this->requestedSchedule($request);
$appointmentId = Utils::positiveInteger($request->request->get('appointmentId'));
if ($doctorId === null || $appointmentId === null) {
throw new BadRequestHttpException('invalid schedule or appointment');
}
$appointment = $this->application->getAppointmentById($appointmentId);
if ($appointment === null) {
// ya cancelada (por otra persona, o por doble clic)
$this->flash->error('ERRORS.APPOINTMENT_NOT_FOUND');
} else {
$this->application->deleteAppointment($appointment);
$this->flash->success('SCHEDULE.CANCELLED');
}
return $this->redirect($this->scheduleUrl($doctorId, $day));
}
// -----------------------------------------------------------------------
// ¿quién tiene la sesión iniciada y qué puede hacer en esta página?
// manager: ADMIN o DOCTOR;
// patient: el cliente con sesión iniciada (rol USER); de lo contrario, null;
// patientCanBook: un USER sin cita próxima.
// -----------------------------------------------------------------------
private function rights(): array
{
if (! $this->utils->user()->isPatient()) {
return ['manager' => true, 'patient' => null, 'patientCanBook' => false];
}
$patient = $this->utils->connectedPatient();
$upcoming = $this->application->getClientUpcomingAppointments($patient->getId());
return ['manager' => false, 'patient' => $patient, 'patientCanBook' => $upcoming === []];
}
// -----------------------------------------------------------------------
// la agenda del médico, formateada para la vista - y filtrada según los derechos
// -----------------------------------------------------------------------
private function scheduleView(DoctorDaySchedule $doctorSchedule, array $rights, bool $bookableDay): ScheduleView
{
$doctorId = $doctorSchedule->doctor->getId();
$day = $doctorSchedule->day;
$rows = [];
foreach ($doctorSchedule->doctorDaySlots as $dds) {
$slot = $dds->slot;
$appointment = $dds->appointment;
$free = $appointment === null;
// ¿la cita del paciente con sesión iniciada?
$mine = $appointment !== null && $rights['patient'] !== null
&& $appointment->getClient()->getId() === $rights['patient']->getId();
$rows[] = new ScheduleRow(
slotId: $slot->getId(),
time: $slot->time(),
free: $free,
// EL punto de confidencialidad: un paciente solo recibe el nombre de
// SU cita; para las demás, null (la vista muestra "Booked")
patient: $appointment !== null && ($rights['manager'] || $mine) ? $appointment->getClient()->label() : null,
mine: $mine,
bookable: $free && $bookableDay && ($rights['manager'] || $rights['patientCanBook']),
bookUrl: $this->scheduleUrl($doctorId, $day, $slot->getId()),
appointmentId: $appointment !== null && $rights['manager'] ? $appointment->getId() : null);
}
return new ScheduleView($doctorSchedule->doctor->label(), $this->utils->formatDay($day), $rows);
}
// ----------------------------------------------------------------- funciones utilitarias
// los campos ocultos doctorId / day de los formularios POST; [null, null] si
// no son válidos
private function requestedSchedule(Request $request): array
{
$doctorId = Utils::positiveInteger($request->request->get('doctorId'));
$day = Utils::validDate($request->request->get('day'));
return $doctorId === null || $day === null ? [null, null] : [$doctorId, $day];
}
// /schedule?doctorId=1&day=2026-09-23[&book=7]: generateUrl agrega al final
// de la URL los parámetros que no son parámetros de la ruta (véase el ejemplo 16)
private function scheduleUrl(int $doctorId, DateTimeImmutable $day, ?int $book = null): string
{
$params = ['doctorId' => $doctorId, 'day' => Utils::iso($day)];
if ($book !== null) {
$params['book'] = $book;
}
return $this->generateUrl('schedule', $params);
}
private static function option(Person $p, bool $selected): OptionView
{
return new OptionView($p->getId(), $p->label(), $selected);
}
// -----------------------------------------------------------------------
// el mensaje informativo de un paciente que ya tiene una cita próxima
// (por qué no hay botón "Book"), o null. Inútil si SU
// cita aparece en la agenda mostrada (en azul): es el caso justo
// después de que acaba de reservarla, cuando el mensaje estaría fuera de lugar.
// array_any: ¿al menos un elemento cumple la condición?
// -----------------------------------------------------------------------
private function patientInfo(array $rights, ?ScheduleView $schedule): ?string
{
if ($rights['patient'] === null || $rights['patientCanBook']) {
return null;
}
$appointmentShown = $schedule !== null && array_any($schedule->rows, fn (ScheduleRow $r) => $r->mine);
return $appointmentShown ? null : 'SCHEDULE.ALREADY_BOOKED_INFO';
}
}
|
La página principal de la aplicación. El comentario del encabezado resume lo que ve y puede hacer cada usuario. El atributo [#[Route('/schedule')]] de la clase (línea 66) especifica el inicio de la ruta de todas sus rutas (ejemplo 02): la ruta [''] es [/schedule] misma.
11.19.3.1. La URL de la página
La página completa se describe mediante su URL: [/schedule?doctorId=1&day=2026-09-26] muestra la agenda del médico 1 para ese día; [&book=4] abre además la ventana de reserva de la franja 4. Se puede recargar la página, guardarla como marcador o usar el botón Atrás del navegador sin una sola línea de [JavaScript]. El formulario de la parte superior de la página (para seleccionar el médico y el día) es un formulario GET (ejemplo 17): recarga la página con nuevos parámetros. La ventana de reserva de citas se abre mediante un simple enlace y se cierra mediante un enlace a la misma página sin el parámetro [book].
11.19.3.2. GET /schedule
Líneas 81–154:
- los parámetros de la URL se leen tal cual ([$request->query->get('day')]), sin validación por parte de [Symfony]: un parámetro ausente ([null]) no es un error (el sistema usa por defecto hoy o «ningún médico»); una fecha inválida es un error, que se muestra en la parte inferior de la página (las selecciones de médico y día permanecen visibles, pero el calendario no se muestra); un número de médico o de franja horaria que no sea un entero positivo simplemente se ignora;
- un usuario con sesión iniciada que no ha seleccionado un médico ve su agenda: su médico se obtiene a través de su cuenta ([getDoctorByUserId]). [?->getId()]: el operador nullsafe devuelve [null] si el objeto es [null], en lugar de generar un error;
- la lista desplegable de médicos: [array_map] convierte cada médico en [OptionView];
- el calendario, formateado y filtrado según los permisos del usuario ([scheduleView], más abajo);
- la ventana de reserva, solo si la franja horaria solicitada es reservable por ese usuario: un paciente que intente generar la URL [&book=2] para una franja ya reservada no obtendría nada. [array_find] (ejemplo 06) devuelve el primer elemento de un arreglo que cumple una condición, o [null]. La lista de pacientes solo se proporciona al administrador y a los médicos; un paciente recibe únicamente su propio nombre;
- la vista recibe sus variables ([render], ejemplo 13), entre ellas [pageTitle] y [error], que lee la plantilla.
11.19.3.3. POST /schedule/book
Líneas 167–215:
- el token anti-CSRF, seguido de los campos ocultos del formulario de reserva (médico, día, franja horaria). Si estos son inválidos, debe tratarse de una solicitud elaborada manualmente: [BadRequestHttpException], la página de «solicitud inválida» (400);
- Para un paciente, el campo [clientId] se ignora: el paciente siempre reserva una cita para sí mismo ([Utils::connectedPatient]). Confiar en un campo enviado por el navegador permitiría a un paciente malintencionado hacer una reserva en nombre de otra persona. Para el administrador y los médicos, debe haberse seleccionado un paciente; de lo contrario, la ventana de reserva se vuelve a abrir con un mensaje;
- la franja horaria debe pertenecer al médico indicado en la página;
- las reglas de negocio (no en el pasado, una sola cita próxima, franja horaria disponible) las verifica la capa de lógica de negocio. Una [BusinessException] se convierte en un mensaje de error flash; sus propiedades públicas [key] y [params] proporcionan el mensaje. El mismo rechazo («una cita próxima») se formula en segunda persona para el propio paciente («Ya tiene…»). Cualquier otra excepción no se intercepta: es un error real (página 500);
- en todos los casos, el patrón Post/Redirect/Get (ejemplo 20): un mensaje emergente y una redirección al calendario.
11.19.3.4. POST /schedule/cancel
Líneas 221–239: cancelación de una cita por parte del administrador o de un médico (regla [^/schedule/cancel$] derivada de [security.yaml]). Una cita que ya no existe (ya cancelada por otra persona, o por un doble clic) no es un error: solo se muestra un mensaje.
- líneas 247–255: lo que el usuario está autorizado a hacer en la página, en un arreglo asociativo: ¿es el usuario un administrador (ADMIN o DOCTOR)? ¿un paciente (y cuál)? ¿puede este paciente hacer una reserva (sin citas próximas)?
- Líneas 260–285: la agenda del médico, convertida en filas para la vista. La consideración de privacidad está en la línea 278: un paciente solo ve el nombre asociado a su propia cita. Para los demás, la propiedad [patient] se establece en [null], y la vista muestra «Reservado». El nombre no lo oculta la vista: nunca se le pasa y, por lo tanto, no aparece en el código fuente de la página, donde sería fácil leerlo. El botón «Reservar» se muestra para una franja horaria disponible, en un día que aún no ha pasado, a un administrador o a un paciente que puede hacer una reserva; el botón «Cancelar» se muestra solo a los administradores. Los argumentos con nombre ([slotId: $slot->getId()]) hacen legible la construcción de un objeto con ocho propiedades;
- líneas 291–296: los campos ocultos de los formularios POST. [[$doctorId, $day] = ...] (líneas 171 y 225) descompone el arreglo devuelto en dos variables;
- líneas 300–307: la URL de la agenda de un médico en un día determinado. [generateUrl('schedule', [...])] agrega al final de la URL, como parámetros de consulta, los valores que no son parámetros de ruta: [/schedule?doctorId=1&day=2026-09-26];
- líneas 321–328: el mensaje que explica a un paciente por qué no aparece el botón «Reservar» (ya tiene una cita próxima), a menos que esa cita esté en el calendario mostrado (inmediatamente después de reservarla, el mensaje cambiaría de lugar). [array_any] ([PHP] 8.4): ¿al menos un elemento cumple la condición?
11.19.4. src/Controller/PersonsController.php
| <?php
// =========================================================================
// src/Controller/PersonsController.php: la gestión de los médicos y la de los
// clientes (reservada al ADMIN) son IDÉNTICAS: misma lista, mismo formulario,
// mismas reglas. En lugar de escribir las mismas acciones dos veces, las escribimos
// una sola vez en esta clase ABSTRACTA; DoctorsController y ClientsController
// heredan de ella y solo especifican lo que los distingue: el nombre de la sección
// (médicos o clientes), las claves de traducción y los métodos de
// ApplicationModel que deben llamarse.
//
// Los atributos #[Route] de las acciones también se heredan: el atributo #[Route]
// de CADA clase hija les da el comienzo de su ruta (/doctors o
// /clients) y de su nombre (doctors_ o clients_). Así obtenemos, para cada una:
//
// GET /doctors lista doctors_list
// GET /doctors/add formulario vacío doctors_add
// POST /doctors/add creación doctors_add
// GET /doctors/{id}/edit formulario rellenado doctors_edit
// POST /doctors/{id}/edit modificación doctors_edit
// POST /doctors/{id}/delete eliminación doctors_delete
//
// (y las mismas URL bajo /clients). Las vistas también son comunes:
// templates/persons/list.html.twig y persons/form.html.twig.
//
// SEGURIDAD: la regla access_control ^/(doctors|clients) de
// config/packages/security.yaml reserva todas estas URL al ADMIN - incluidas las
// que se agreguen más adelante.
// =========================================================================
namespace App\Controller;
use App\Entity\Person;
use App\Form\PersonFieldsType;
use App\Form\PersonType;
use App\Business\PersonData;
use App\Business\BusinessException;
use App\Views\PersonKeys;
use App\Web\ApplicationModel;
use App\Web\BaseController;
use App\Web\Flash;
use App\Web\Message;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
abstract class PersonsController extends BaseController
{
// los campos del formulario afectados por cada error de negocio de "entrada" (un
// duplicado): se enmarcan en rojo, y el mensaje aparece al final de la página
public const BUSINESS_ERROR_FIELDS = [
'ERRORS.LOGIN_TAKEN' => ['login'],
'ERRORS.DOCTOR_ALREADY_EXISTS' => ['first_name', 'last_name'],
'ERRORS.PATIENT_ALREADY_EXISTS' => ['first_name', 'last_name'],
];
public function __construct(protected ApplicationModel $application, protected Flash $flash)
{
}
// ---- lo que cada tipo de persona debe proporcionar
// "doctors" o "clients": el comienzo de los nombres de las rutas
abstract protected function section(): string;
abstract protected function keys(): PersonKeys;
/** @return list<Person> */
abstract protected function all(): array;
abstract protected function find(int $id): ?Person;
abstract protected function create(PersonData $data): Person;
abstract protected function update(int $id, PersonData $data): Person;
abstract protected function erase(int $id): void;
// -------------------------------------------------------------------
// GET /doctors (o /clients)
// -------------------------------------------------------------------
#[Route('', name: 'list', methods: ['GET'])]
public function list(): Response
{
return $this->render('persons/list.html.twig', ['pageTitle' => $this->keys()->title,
'keys' => $this->keys(), 'section' => $this->section(), 'persons' => $this->all()]);
}
// -------------------------------------------------------------------
// GET /doctors/add: el formulario vacío; POST: la creación
// -------------------------------------------------------------------
#[Route('/add', name: 'add', methods: ['GET', 'POST'])]
public function add(Request $request): Response
{
$form = $this->createForm(PersonType::class, ['title' => 'Mr']);
$form->handleRequest($request);
if ($form->isSubmitted() && $form->isValid()) {
try {
$person = $this->create(PersonFieldsType::data($form->getData()));
} catch (BusinessException $e) {
return $this->businessError($e, $form, null);
}
$this->flash->success($this->keys()->added, self::params($person));
return $this->redirectToRoute($this->section().'_list');
}
return $this->page($form, null);
}
// -------------------------------------------------------------------
// GET /doctors/{id}/edit: el formulario rellenado; POST: la modificación.
// {id<\d+>}: un parámetro formado por dígitos (véase el ejemplo 02):
// /doctors/abc/edit no coincide con ninguna ruta (página 404)
// -------------------------------------------------------------------
#[Route('/{id<\d+>}/edit', name: 'edit', methods: ['GET', 'POST'])]
public function edit(Request $request, int $id): Response
{
$person = $this->find($id) ?? throw $this->createNotFoundException();
// el formulario, rellenado con los valores de la persona (la
// contraseña, en cambio, nunca se muestra)
$form = $this->createForm(PersonType::class, [
'title' => $person->getTitle(), 'first_name' => $person->getFirstName(),
'last_name' => $person->getLastName(), 'login' => $person->getAccount()->getLogin(),
'version' => $person->getVersion(),
], ['creation' => false]);
$form->handleRequest($request);
if ($form->isSubmitted() && $form->isValid()) {
try {
$person = $this->update($id, PersonFieldsType::data($form->getData()));
} catch (BusinessException $e) {
return $this->businessError($e, $form, $person);
}
$this->flash->success($this->keys()->edited, self::params($person));
return $this->redirectToRoute($this->section().'_list');
}
return $this->page($form, $person);
}
// -------------------------------------------------------------------
// POST /doctors/{id}/delete
// (la confirmación "Are you sure?" se pide antes de enviar el formulario,
// véase public/js/app.js)
// -------------------------------------------------------------------
#[Route('/{id<\d+>}/delete', name: 'delete', methods: ['POST'])]
public function delete(Request $request, int $id): Response
{
$this->checkCsrf($request);
$person = $this->find($id);
try {
$this->erase($id);
$this->flash->success($this->keys()->deleted, self::params($person));
} catch (BusinessException $e) {
$this->flash->error($e->key, $e->params);
}
return $this->redirectToRoute($this->section().'_list');
}
// ----------------------------------------------------------------- funciones internas
// $person null: formulario de creación; de lo contrario: formulario de modificación.
// Un formulario rechazado (entrada inválida o regla de negocio): el código 422
private function page(FormInterface $form, ?Person $person, ?Message $error = null,
array $invalidFields = []): Response
{
$keys = $this->keys();
$refused = $error !== null || ($form->isSubmitted() && ! $form->isValid());
return $this->render('persons/form.html.twig', [
'pageTitle' => $person === null ? $keys->add : $keys->edit,
'form' => $form,
'error' => $error,
'invalidFields' => $invalidFields,
'listUrl' => $this->generateUrl($this->section().'_list'),
], new Response(status: $refused ? 422 : 200));
}
// una regla de negocio rechazó la escritura: el formulario se muestra de nuevo, con lo
// ingresado por el usuario (sin la contraseña), el mensaje de la capa de
// negocio (al final de la página) y los campos afectados, si los hay, enmarcados en
// rojo para que el usuario vea de inmediato qué debe corregir
private function businessError(BusinessException $e, FormInterface $form, ?Person $person): Response
{
if (in_array($e->key, ['ERRORS.DOCTOR_NOT_FOUND', 'ERRORS.PATIENT_NOT_FOUND'], true)) {
// eliminado mientras tanto por otro ADMIN: de vuelta a la lista
$this->flash->error($e->key, $e->params);
return $this->redirectToRoute($this->section().'_list');
}
return $this->page($form, $person, new Message($e->key, $e->params),
self::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
}
// {name} y {login} de los mensajes "added / updated / deleted"
private static function params(?Person $person): array
{
return $person === null ? ['name' => '', 'login' => '']
: ['name' => "{$person->getFirstName()} {$person->getLastName()}",
'login' => $person->getAccount()->getLogin()];
}
}
|
La administración de médicos y clientes es idéntica: la misma lista, el mismo formulario, las mismas reglas. Las acciones se escriben una sola vez, en una clase abstracta; [DoctorsController] y [ClientsController] heredan de ella. Cada una debe proporcionar lo que la distingue: este es el papel de los métodos abstractos de las líneas 64–77, declarados sin código; una clase hija que no los implemente sería rechazada por [PHP]. Este es el patrón de diseño conocido como el «método plantilla»: la clase padre define el algoritmo y las clases hijas aportan los detalles.
Los atributos [#[Route]] de las acciones también se heredan. [Symfony] ignora la clase abstracta, pero examina los métodos de cada una de las clases hijas, incluidos los heredados; el atributo [#[Route]] de la clase hija especifica el inicio de su ruta y de su nombre: la acción [list] se convierte en las rutas [doctors_list] ([/doctors]) y [clients_list] ([/clients]). Para agregar una acción a los módulos de administración de médicos o de clientes, basta con escribirla aquí.
- Líneas 51–55: los campos afectados por cada error de entrada de la lógica de negocio: un login duplicado afecta al campo «login»; una coincidencia de nombre afecta a los campos «nombre» y «apellido». Estos campos se resaltarán en rojo;
- línea 57: el constructor, heredado por las clases hijas. Sus propiedades son [protected]: visibles para las clases hijas;
- Líneas 82–87: la lista. Esta vista es común a ambas secciones: recibe las claves de traducción de la sección ([keys]) y su nombre ([section]), que se usa para generar los nombres de las rutas ([section ~ '_add'] en la vista);
- Líneas 92–107: alta. Una sola acción para GET (el formulario vacío, con el tratamiento [Mr] seleccionado) y para POST (creación), como en el ejemplo 19. Una entrada inválida vuelve a cargar el formulario. Una entrada válida pasa a la capa de negocio, que puede rechazar la operación de escritura (por ejemplo, un homónimo o un login ya en uso); de lo contrario, aparece un mensaje de éxito y el usuario regresa a la lista (esquema PRG);
- líneas 114–136: la actualización, para una persona existente: [?? throw $this->createNotFoundException()] (la página 404; [throw] es una expresión que puede usarse a la derecha de [??]). [{id<\d+>}] (línea 114) acepta solo dígitos para el parámetro [{id}] (ejemplo: 02). El formulario se rellena previamente con los valores de la persona y su versión; [handleRequest] los reemplaza por los datos ingresados, en el caso de un POST;
- líneas 143–155: eliminación. El formulario solicitó confirmación en el navegador (ejemplo 21). Los datos de la persona se obtienen antes de eliminarla para generar el mensaje de éxito («Se eliminó al médico Paul TATOU.»);
- líneas 161–173: el formulario, ya sea para creación ([$person] es igual a [null]) o para modificación. Un formulario rechazado (entrada inválida o infracción de una regla de negocio) se devuelve con el código de estado 422 (ejemplo 19). La vista recibe el formulario mismo ([render] lo convierte en una «vista de formulario», ejemplo 18);
- líneas 179–188: la capa de negocio rechazó la operación de escritura. Si una persona fue eliminada mientras tanto (por otro administrador), el usuario regresa a la lista. De lo contrario, el formulario se vuelve a mostrar directamente (sin redirección), como en el caso de un error de entrada: ya contiene los datos ingresados por el usuario. A esto se suman el mensaje de la capa de negocio (que se muestra en la parte inferior de la página, en el área de errores) y los campos que se deben resaltar en rojo. Observe que el administrador de entidades se cierra después de la excepción (la capa de negocio, como se mencionó antes): la acción ahora solo muestra;
- líneas 191–196: los parámetros [{name}] y [{login}] de los mensajes de éxito.
11.19.5. src/Controller/DoctorsController.php y ClientsController.php
| <?php
// src/Controller/DoctorsController.php: la gestión de los médicos (solo rol ADMIN).
// Todas las acciones las escribe PersonsController: aquí solo queda indicar QUÉ llamar y QUÉ
// etiquetas mostrar.
namespace App\Controller;
use App\Entity\Person;
use App\Business\PersonData;
use App\Views\PersonKeys;
use Symfony\Component\Routing\Attribute\Route;
// el comienzo de la ruta y del nombre de todas las rutas heredadas de PersonsController
#[Route('/doctors', name: 'doctors_')]
class DoctorsController extends PersonsController
{
protected function section(): string
{
return 'doctors';
}
// DOCTORS.TITLE, DOCTORS.ADD... (véase translations)
protected function keys(): PersonKeys
{
return PersonKeys::of('DOCTORS');
}
protected function all(): array
{
return $this->application->getAllDoctors();
}
protected function find(int $id): ?Person
{
return $this->application->getDoctorById($id);
}
protected function create(PersonData $data): Person
{
return $this->application->addDoctor($data);
}
protected function update(int $id, PersonData $data): Person
{
return $this->application->editDoctor($id, $data);
}
protected function erase(int $id): void
{
$this->application->deleteDoctor($id);
}
}
|
Aquí solo queda especificar qué métodos llamar (los métodos de [ApplicationModel]) y qué etiquetas mostrar (las claves [DOCTORS.xxx] de los diccionarios), y proporcionar las rutas iniciales y los nombres de las rutas (línea 14). [ApplicationModel] se encuentra en la propiedad [$this->application], declarada por el constructor de la clase padre. [ClientsController] es idéntico, con los métodos de clientes y las claves [CLIENTS.xxx].
11.19.6. src/Controller/RegistrationController.php
| <?php
// =========================================================================
// src/Controller/RegistrationController.php: "Create a patient account": un paciente
// que aún no tiene cuenta la crea él mismo. Rutas PÚBLICAS (por definición, aún no se
// tiene una cuenta):
//
// POST /register/access botón "Create a patient account" de la página de
// inicio de sesión: verifica el captcha de ESA
// página y luego abre el formulario
// GET /register el formulario
// POST /register la creación y luego de vuelta a la página de inicio de sesión
//
// El camino está protegido contra robots por UN solo captcha, el de la página
// de inicio de sesión:
// 1. el botón "Create a patient account" envía el formulario de inicio de sesión a
// /register/access; si el captcha se copia correctamente, el servidor emite un
// pass (véase src/Security/RegistrationPass.php);
// 2. sin un pass válido, /register redirige a la página de inicio de
// sesión (atributo #[RegistrationPassRequired], véase
// src/EventListener/CheckRegistrationPass.php);
// 3. el pass se consume en la creación: un captcha resuelto permite crear
// UNA cuenta;
// 4. además, el número de cuentas creadas por hora y por dirección IP está limitado
// (véase src/Security/AttemptLimiter.php).
//
// La cuenta creada es exactamente la que el ADMIN crearía desde la página "Patients"
// (mismo método de la capa de negocio: addClient), salvo que el paciente
// ELIGE su login y su contraseña (obligatorios, con confirmación).
// =========================================================================
namespace App\Controller;
use App\Form\PersonFieldsType;
use App\Form\RegistrationType;
use App\Business\BusinessException;
use App\Security\CaptchaService;
use App\Security\AttemptLimiter;
use App\Security\RegistrationPass;
use App\Security\RegistrationPassRequired;
use App\Web\ApplicationModel;
use App\Web\BaseController;
use App\Web\Flash;
use App\Web\Message;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
#[Route('/register')]
class RegistrationController extends BaseController
{
public function __construct(
private ApplicationModel $application,
private CaptchaService $captchas,
private AttemptLimiter $limiter,
private RegistrationPass $passes,
private Flash $flash,
) {
}
// -----------------------------------------------------------------------
// POST /register/access campos: captchaId, captcha (los de la página de inicio de
// sesión; login y contraseña, también enviados, se ignoran)
// -----------------------------------------------------------------------
#[Route('/access', name: 'registration_access', methods: ['POST'])]
public function access(Request $request): Response
{
$this->checkCsrf($request);
$ip = (string) $request->getClientIp();
// demasiadas cuentas creadas recientemente desde esta dirección: no tiene caso seguir
$minutes = $this->limiter->registrationBlockMinutes($ip);
if ($minutes > 0) {
$this->flash->error('ERRORS.TOO_MANY_ACCOUNTS', ['minutes' => $minutes]);
return $this->redirectToRoute('login');
}
// captcha ausente o incorrecto: de vuelta a la página de inicio de sesión, con una
// nueva imagen (un fallo cuenta como un fallo de inicio de sesión)
if (! $this->captchas->verify($request->request->getString('captchaId'),
$request->request->getString('captcha'))) {
$this->limiter->loginFailure($ip, '');
$this->flash->error('ERRORS.CAPTCHA_BEFORE_ACCOUNT');
return $this->redirectToRoute('login');
}
// captcha correcto: se emite el pass y se abre el formulario
$response = $this->redirectToRoute('registration');
$response->headers->setCookie($this->passes->issue());
return $response;
}
// -----------------------------------------------------------------------
// GET /register: el formulario; POST /register: la creación. El
// pass se verificó ANTES de la llamada a la acción (#[RegistrationPassRequired]).
// El formulario valida TODA la entrada (campos y confirmación de contraseña):
// el usuario corrige todos sus errores de una sola vez
// -----------------------------------------------------------------------
#[Route('', name: 'registration', methods: ['GET', 'POST'])]
#[RegistrationPassRequired]
public function register(Request $request): Response
{
$form = $this->createForm(RegistrationType::class, ['title' => 'Mr']);
$form->handleRequest($request);
if (! $form->isSubmitted() || ! $form->isValid()) {
return $this->page($form);
}
$ip = (string) $request->getClientIp();
// 1. ¿demasiadas cuentas creadas recientemente desde esta dirección?
$minutes = $this->limiter->registrationBlockMinutes($ip);
if ($minutes > 0) {
return $this->page($form, new Message('ERRORS.TOO_MANY_ACCOUNTS', ['minutes' => $minutes]));
}
// 2. la creación (cliente + cuenta USER, en una transacción)
$data = PersonFieldsType::data($form->getData());
try {
$this->application->addClient($data);
} catch (BusinessException $e) {
// login o nombre + apellido ya en uso: el pass sigue siendo válido
return $this->page($form, new Message($e->key, $e->params),
PersonsController::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
}
// 3. el pass se ha usado: no permitirá crear una 2.ª cuenta
$this->passes->consume($request->cookies->get(RegistrationPass::COOKIE));
$this->limiter->registrationSuccess($ip);
// 4. de vuelta a la página de inicio de sesión, con el login rellenado
$this->flash->success('REGISTRATION.DONE', ['login' => $data->login]);
return RegistrationPass::clearCookie($this->redirectToRoute('login', ['login' => $data->login]));
}
// el formulario; un formulario rechazado: el código 422
private function page(FormInterface $form, ?Message $error = null, array $invalidFields = []): Response
{
$refused = $error !== null || ($form->isSubmitted() && ! $form->isValid());
return $this->render('registration.html.twig', ['pageTitle' => 'REGISTRATION.TITLE',
'form' => $form, 'error' => $error, 'invalidFields' => $invalidFields],
new Response(status: $refused ? 422 : 200));
}
}
|
El paciente crea por sí mismo una cuenta de paciente. El flujo está protegido por un CAPTCHA, el mismo que se usa en la página de inicio de sesión.
- Líneas 65–91: el botón «Crear una cuenta de paciente» de la página de inicio de sesión envía el formulario de inicio de sesión a esta dirección (más adelante, la vista [login]). Si se han creado demasiadas cuentas recientemente desde esta dirección (IP), no hay necesidad de continuar. Si el CAPTCHA falta o es incorrecto: se regresa a la página de inicio de sesión con una imagen nueva y un mensaje; el fallo cuenta como un intento fallido de inicio de sesión (con un nombre de usuario vacío). Si el CAPTCHA es correcto: se almacena un token en una cookie y se redirige al usuario al formulario;
- líneas 99–107: el formulario. El atributo [#[RegistrationPassRequired]] (línea 100) hace que el listener [CheckRegistrationPass] verifique el token antes de llamar a la acción. El formulario valida toda la entrada, incluida la confirmación de la contraseña: el usuario ve todos los errores a la vez;
- Líneas 108–132: creación. El cliente y su cuenta se crean con el mismo método de la capa de negocio que se usa para el administrador ([addClient]); solo el nombre de usuario y la contraseña los elige el paciente. Si un nombre de usuario o un homónimo ya está en uso: se regresa al formulario sin consumir el pase. La creación de una cuenta consume el token (un CAPTCHA resuelto equivale a una cuenta), cuenta para el límite por hora y redirige a la página de inicio de sesión con el nombre de usuario ya rellenado ([redirectToRoute('login', ['login' => ...])] agrega el parámetro [?login=...]), junto con un mensaje de éxito. La cookie del pase se elimina.
11.19.7. src/Controller/PatientAreaController.php
| <?php
// =========================================================================
// src/Controller/PatientAreaController.php: las páginas PERSONALES del paciente (rol
// USER), las que ve justo después de iniciar sesión:
//
// GET /my-area página de inicio: [Manage my account], [View a
// schedule] y su cita próxima
// POST /my-area/cancel cancela SU cita
// GET /my-account formulario de modificación de su cuenta
// POST /my-account modificación
// POST /my-account/delete eliminación de la cuenta (y de sus citas)
//
// Regla de oro de este controlador: el paciente en cuestión es SIEMPRE el del token
// ($this->utils->connectedPatient()), nunca un identificador enviado por el
// navegador. Por lo tanto, un paciente no puede ver, modificar ni cancelar lo que
// pertenece a otro paciente, ni siquiera construyendo sus propias solicitudes.
//
// Cualquier modificación o eliminación de la cuenta exige la contraseña ACTUAL:
// alguien que encuentre una sesión abierta no podría cambiar la
// contraseña ni eliminar la cuenta. Los errores de contraseña actual se
// cuentan como fallos de inicio de sesión (mismo límite).
//
// Seguridad: todas estas URL están reservadas al rol USER (regla ^/my- de
// config/packages/security.yaml).
// =========================================================================
namespace App\Controller;
use App\Entity\Client;
use App\Entity\Appointment;
use App\Form\PersonFieldsType;
use App\Form\MyAccountType;
use App\Business\BusinessException;
use App\Security\AuthService;
use App\Security\AttemptLimiter;
use App\Views\AppointmentView;
use App\Web\ApplicationModel;
use App\Web\BaseController;
use App\Web\Flash;
use App\Web\Message;
use App\Web\Utils;
use Symfony\Component\Form\FormError;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Contracts\Translation\TranslatorInterface;
class PatientAreaController extends BaseController
{
public function __construct(
private ApplicationModel $application,
private AuthService $auth,
private AttemptLimiter $limiter,
private Utils $utils,
private Flash $flash,
private TranslatorInterface $translator,
) {
}
// -----------------------------------------------------------------------
// GET /my-area
// -----------------------------------------------------------------------
#[Route('/my-area', name: 'area', methods: ['GET'])]
public function area(): Response
{
$patient = $this->utils->connectedPatient();
$appointments = array_map(fn (Appointment $a) => new AppointmentView(
$a->getId(),
$this->utils->formatDay($a->getDay()),
$a->getSlot()->time(),
$a->getSlot()->getDoctor()->label(),
// enlace a la agenda del médico en ese día: el paciente ve allí su nombre
$this->generateUrl('schedule', ['doctorId' => $a->getSlot()->getDoctor()->getId(),
'day' => Utils::iso($a->getDay())])),
$this->application->getClientUpcomingAppointments($patient->getId()));
return $this->render('area.html.twig', ['pageTitle' => 'AREA.TITLE',
'patient' => $patient->label(), 'appointments' => $appointments]);
}
// -----------------------------------------------------------------------
// POST /my-area/cancel campo: appointmentId
// -----------------------------------------------------------------------
#[Route('/my-area/cancel', name: 'area_cancel', methods: ['POST'])]
public function cancelAppointment(Request $request): Response
{
$this->checkCsrf($request);
$patient = $this->utils->connectedPatient();
$appointmentId = Utils::positiveInteger($request->request->get('appointmentId'));
$appointment = $appointmentId !== null ? $this->application->getAppointmentById($appointmentId) : null;
// una cita que no existe y la de OTRO paciente reciben la
// misma respuesta: no se revela nada sobre las citas de los demás
if ($appointment === null || $appointment->getClient()->getId() !== $patient->getId()) {
$this->flash->error('ERRORS.APPOINTMENT_NOT_FOUND');
} else {
$this->application->deleteAppointment($appointment);
$this->flash->success('SCHEDULE.CANCELLED');
}
return $this->redirectToRoute('area');
}
// -----------------------------------------------------------------------
// GET /my-account: el formulario, rellenado con los valores del paciente;
// POST /my-account: la modificación
// -----------------------------------------------------------------------
#[Route('/my-account', name: 'account', methods: ['GET', 'POST'])]
public function account(Request $request): Response
{
$patient = $this->utils->connectedPatient();
$form = $this->createForm(MyAccountType::class, [
'title' => $patient->getTitle(), 'first_name' => $patient->getFirstName(), 'last_name' => $patient->getLastName(),
'login' => $patient->getAccount()->getLogin(), 'version' => $patient->getVersion(),
]);
$form->handleRequest($request);
if (! $form->isSubmitted() || ! $form->isValid()) {
return $this->page($form);
}
// la contraseña actual; si es incorrecta: el mensaje va DEBAJO del campo (un error
// agregado al campo, FormError) y al final de la página
$error = $this->checkCurrentPassword($request, $patient,
$form->get('current_password')->getData());
if ($error !== null) {
$form->get('current_password')->addError(
new FormError($this->translator->trans($error->key, $error->params)));
return $this->page($form, $error);
}
try {
$client = $this->application->editClient($patient->getId(),
PersonFieldsType::data($form->getData()));
} catch (BusinessException $e) {
return $this->page($form, new Message($e->key, $e->params),
PersonsController::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
}
// el login y el nombre mostrado están EN el token: se emite uno nuevo;
// de lo contrario, la barra de navegación conservaría el nombre anterior
$this->flash->success('MY_ACCOUNT.UPDATED');
$response = $this->redirectToRoute('area');
$response->headers->setCookie($this->auth->tokenCookie($client->getAccount()));
return $response;
}
// -----------------------------------------------------------------------
// POST /my-account/delete campo: current_password
// La cuenta, el cliente y TODAS sus citas desaparecen juntos y luego se
// cierra la sesión del paciente.
// -----------------------------------------------------------------------
#[Route('/my-account/delete', name: 'account_delete', methods: ['POST'])]
public function deleteAccount(Request $request): Response
{
$this->checkCsrf($request);
$patient = $this->utils->connectedPatient();
$error = $this->checkCurrentPassword($request, $patient,
$request->request->getString('current_password'));
if ($error !== null) {
$this->flash->error($error->key, $error->params);
return $this->redirectToRoute('account');
}
$this->application->deleteClient($patient->getId());
$this->flash->success('MY_ACCOUNT.DELETED');
return AuthService::clearCookie($this->redirectToRoute('login'));
}
// ----------------------------------------------------------------- funciones internas
// la página de la cuenta; un formulario rechazado: el código 422
private function page(FormInterface $form, ?Message $error = null, array $invalidFields = []): Response
{
$refused = $error !== null || ($form->isSubmitted() && ! $form->isValid());
return $this->render('account.html.twig', ['pageTitle' => 'MY_ACCOUNT.TITLE',
'form' => $form, 'error' => $error, 'invalidFields' => $invalidFields],
new Response(status: $refused ? 422 : 200));
}
// null si la contraseña actual es correcta; de lo contrario, el mensaje de error
private function checkCurrentPassword(Request $request, Client $patient, ?string $password): ?Message
{
$ip = (string) $request->getClientIp();
$login = $patient->getAccount()->getLogin();
$minutes = $this->limiter->loginBlockMinutes($ip, $login);
if ($minutes > 0) {
return new Message('ERRORS.TOO_MANY_ATTEMPTS', ['minutes' => $minutes]);
}
if (! $password || $this->auth->validate($login, $password) === null) {
$this->limiter->loginFailure($ip, $login);
return new Message('ERRORS.WRONG_CURRENT_PASSWORD');
}
return null;
}
}
|
Las páginas personales del paciente. La regla de oro de este controlador: el paciente en cuestión es siempre el asociado al token ([Utils::connectedPatient]), nunca un identificador enviado por el navegador. Por lo tanto, un paciente no puede ver, modificar ni cancelar información que pertenezca a otro paciente, ni siquiera elaborando sus propias solicitudes.
- líneas 64–79: Mi área: el nombre del paciente y sus próximas citas, formateadas ([AppointmentView]), cada una con un enlace a la agenda del médico para ese día;
- líneas 84–100: la cancelación de su cita. Tanto una cita inexistente como la cita de otro paciente reciben la misma respuesta: no se revela ninguna información sobre las citas de otros pacientes (ni siquiera su existencia);
- líneas 106–117: el formulario «Administrar mi cuenta», rellenado previamente con los datos del paciente, y su envío;
- líneas 119–142: la modificación. Toda modificación exige la contraseña actual: alguien que encontrara una sesión abierta no podría cambiar la contraseña ni hacer nada más. Si la contraseña actual es incorrecta, el formulario se vuelve a mostrar, con el mensaje debajo del campo y en la parte inferior de la página. [addError(new FormError(...))] agrega un error a un campo, como si la validación lo hubiera detectado (ejemplo 18); su mensaje es un texto ya traducido, de ahí el traductor recibido por el constructor ([TranslatorInterface], ejemplo 22). Después de la modificación, se genera un nuevo token : el login y el nombre mostrado están incluidos en el token, y la barra de navegación conservaría de otro modo el nombre anterior hasta el siguiente inicio de sesión;
- líneas 149–163: eliminación de la cuenta, del cliente y de todas sus citas, mediante el mismo método de lógica de negocio que se usa para el administrador. Este segundo formulario de la página está escrito a mano (un único campo, la contraseña actual), con el token anti-CSRF de la aplicación. Luego se cierra la sesión del paciente (se elimina la cookie del token);
- líneas 177–190: verificación de la contraseña actual. Está sujeta al limitador de intentos, igual que un inicio de sesión: sin esto, alguien con una sesión abierta podría probar miles de contraseñas mediante el formulario «Administrar mi cuenta» y descubrir la correcta.
11.20. Las vistas
Las vistas [Twig] de la carpeta [templates]: una plantilla, fragmentos, macros y páginas.
11.20.1. La plantilla y los fragmentos
11.20.1.1. templates/layout.html.twig
| <!doctype html>
{# =========================================================================
templates/layout.html.twig
-------------------------------------------------------------------------
El layout COMÚN a todas las páginas (ver el ejemplo 15): cada página
(schedule.html.twig, login.html.twig...) lo EXTIENDE ({% extends %}) y llena su
bloque [content].
Twig ESCAPA todo lo que muestra con {{ ... }} (los caracteres < > & " '
se convierten en < >...): protección contra la inyección de HTML a través de un
nombre ingresado, por ejemplo. Para insertar HTML tal cual, hay que pedirlo
explícitamente (filtro raw, ver fragments/captcha.html.twig).
Mensajes: un éxito se muestra en la parte SUPERIOR de la página, un error en la parte INFERIOR, sobre un fondo
rosa claro (fragmento errors).
El layout comparte las variables de la página: [pageTitle] (la clave del título de
la página, pasada por la acción). El idioma de la página es el de la solicitud
(app.request.locale, ver src/EventListener/SetLanguage.php).
========================================================================= #}
<html lang="{{ app.request.locale }}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
{# pageTitle|trans: la traducción de una clave; aquí, la clave es una VARIABLE #}
<title>{{ pageTitle|trans }} - {{ 'APP.TITLE'|trans }}</title>
{# asset(): la URL de un archivo de la carpeta public #}
<link rel="stylesheet" href="{{ asset('lib/bootstrap/css/bootstrap.min.css') }}">
<link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
<div class="container py-4">
{% include 'fragments/navbar.html.twig' %}
{% include 'fragments/success.html.twig' %}
<main>
{% block content %}{% endblock %}
</main>
{% include 'fragments/errors.html.twig' %}
</div>
{# el diálogo "Are you sure?", oculto mientras no se necesite #}
{% include 'fragments/confirmation.html.twig' %}
<script src="{{ asset('js/app.js') }}"></script>
</body>
</html>
|
La plantilla común a todas las páginas (ejemplo 15): cada página la extiende ([{% extends 'layout.html.twig' %}]) y rellena su bloque [content] (línea 36).
- Línea 21: el idioma de la página, [fr] o [en]: el idioma de la solicitud, establecido por el listener [SetLanguage]. [app] es la variable global que [Symfony] proporciona a todas las vistas (ejemplo 15);
- línea 26: el título de la página, traducido: [pageTitle|trans] traduce la clave contenida en la variable [pageTitle], que cada acción pasa a su vista;
- líneas 28–29: la función [asset] devuelve la URL de un archivo de la carpeta [public] (ejemplo 15);
- líneas 33–38: la barra de navegación, los mensajes de éxito en la parte superior de la página, el contenido de la página y el área de errores en la parte inferior de la página. Estos fragmentos se insertan mediante [{% include %}] (ejemplo 15): tienen acceso a las variables de la página;
- líneas 41–42: la ventana «¿Está seguro?», oculta hasta que se necesite, y el script que la muestra.
[Twig] escapa todo lo que muestra mediante [{{ ... }}] (ejemplo 13): un nombre ingresado que contenga HTML ([<script>]) se muestra tal cual, sin interpretarse. Esto constituye una protección sin esfuerzo contra la inyección de HTML (XSS) en todas las páginas.
11.20.1.2. templates/fragments/navbar.html.twig
| {# =========================================================================
templates/fragments/navbar.html.twig - la barra de navegación.
Título, FR/EN, rol, nombre, cierre de sesión - y un menú cuyas entradas dependen
del rol: "Doctors" y "Patients" solo aparecen para el ADMIN. Es
solo una comodidad de visualización: la protección real son las reglas de acceso
(un USER que escribe /doctors a mano obtiene una página 403). Un paciente (USER)
tiene además su menú "My area".
user(): el usuario conectado, o null (ver src/Twig/ViewsExtension.php).
El menú de la página actual aparece resaltado (clase "active"): lo está si
la ruta de la URL (app.request.pathInfo) comienza con ([starts with]) uno de los
prefijos de la entrada. Las entradas del menú: una lista de arreglos [nombre de
la ruta, clave de la etiqueta, prefijos de las rutas para las que la entrada está activa].
========================================================================= #}
{% set user = user() %}
{% set menu = [] %}
{% if user %}
{% if user.isPatient %}
{# activa para /my-area Y /my-account #}
{% set menu = menu|merge([['area', 'APP.MENU_MY_AREA', ['/my-']]]) %}
{% endif %}
{% set menu = menu|merge([['schedule', 'APP.MENU_SCHEDULE', ['/schedule']]]) %}
{% if user.isAdmin %}
{% set menu = menu|merge([['doctors_list', 'APP.MENU_DOCTORS', ['/doctors']],
['clients_list', 'APP.MENU_PATIENTS', ['/clients']]]) %}
{% endif %}
{% endif %}
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
<span class="navbar-brand mb-0">{{ 'APP.TITLE'|trans }}</span>
<ul class="navbar-nav me-auto">
{# entry[0]: el nombre de la ruta; filter conserva los prefijos que coinciden #}
{% for entry in menu %}
{% set active = entry[2]|filter(p => app.request.pathInfo starts with p) is not empty %}
<li class="nav-item">
<a class="nav-link{{ active ? ' active' }}" href="{{ path(entry[0]) }}">{{ entry[1]|trans }}</a>
</li>
{% endfor %}
</ul>
<div class="d-flex align-items-center gap-2">
{# FR / EN: enlaces simples (GET /language/fr), el idioma activo resaltado #}
<div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
{% for code in ['fr', 'en'] %}
<a class="btn {{ app.request.locale == code ? 'btn-light' : 'btn-outline-light' }}"
href="{{ path('language', {code: code}) }}">{{ code|upper }}</a>
{% endfor %}
</div>
{% if user %}
<span class="badge text-bg-light text-primary">{{ user.role.value }}</span>
<span class="text-white">{{ user.name }}</span>
{# logout es un POST: un formulario reducido a su botón (y al token anti-CSRF) #}
<form method="post" action="{{ path('logout') }}" class="m-0">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<button type="submit" class="btn btn-sm btn-outline-light">{{ 'APP.LOGOUT'|trans }}</button>
</form>
{% endif %}
</div>
</nav>
|
La barra de navegación. Los elementos del menú dependen del rol: «Mi área» para un paciente, «Médicos» y «Pacientes» para el administrador. Esto es solo una comodidad: la protección real proviene de las reglas [access_control] (un paciente que escriba [/doctors] manualmente recibirá una página 403).
- Línea 16: el usuario con sesión iniciada, o [null], devuelto por la función [user()] de nuestra extensión;
- Líneas 17–28: el menú lo generan las instrucciones [{% set %}], que producen una lista de entradas: el nombre de la ruta, la clave de la etiqueta y los prefijos de ruta para los cuales la entrada está activa. El filtro [merge] devuelve una nueva lista, formada por los elementos de la primera lista seguidos de los de la segunda (para dos arreglos asociativos, combina sus claves). [user.isPatient]: [Twig] llama al método [isPatient()]. La entrada «Mi área» está activa para [/my-area] y [/my-account] (prefijo [/my-]). Esto roza el límite de la regla «sin lógica en las vistas»: sin embargo, esta lógica solo afecta a la presentación y se usa únicamente aquí;
- Líneas 34–39: para cada entrada, [active] es verdadero si la ruta de la URL solicitada ([app.request.pathInfo]) comienza con ([starts with]) uno de los prefijos de la entrada. El filtro [filter] conserva solo los elementos de una lista que cumplen una condición, escrita como una función flecha ([p => ...]);
- líneas 44–49: los botones FR / EN, que son simples enlaces ([/language/fr]), con el idioma activo resaltado;
- líneas 51–59: para un usuario con sesión iniciada, su rol ([user.role.value]: la cadena del caso de la enumeración), su nombre y el botón de cierre de sesión. El cierre de sesión es una solicitud POST: un formulario reducido a su botón, con su token anti-CSRF ([csrf_token('rdvmedecins')], ejemplo 21).
11.20.1.3. templates/fragments/success.html.twig
| {# =========================================================================
templates/fragments/success.html.twig - los mensajes de ÉXITO dejados por
la acción anterior (cita reservada, médico agregado...), mostrados una sola
vez, en la parte superior de la página (ver src/Web/Flash.php). Un mensaje flash de ERROR,
en cambio, se muestra al final de la página, mediante el fragmento errors.
app.flashes('success'): los mensajes flash de ese tipo (ver el ejemplo 20). Cada
mensaje es un objeto Message: message.key|trans(message.params) es el texto
de la clave, donde {name}, {login}... se reemplazan por sus valores.
========================================================================= #}
{% for message in app.flashes('success') %}
<div class="alert alert-success" role="status">{{ message.key|trans(message.params) }}</div>
{% endfor %}
|
Los mensajes flash de éxito, establecidos por la acción anterior ([Flash::success]), son leídos y eliminados de la sesión por [app.flashes('success')] (ejemplo 20). Cada uno es un objeto [Message], traducido aquí al idioma de la página: [message.key|trans(message.params)]. [role="status"]: un lector de pantalla anuncia el mensaje.
11.20.1.4. templates/fragments/errors.html.twig
| {# =========================================================================
templates/fragments/errors.html.twig - la zona de errores, en la parte INFERIOR de cada
página, sobre un fondo rosa claro (clase .error-zone, ver public/css/styles.css).
Agrupa las tres posibles fuentes de error:
- [error]: el error de la página mostrada (fecha no válida, CAPTCHA mal
copiado, login ya utilizado...), pasado por la acción;
- los mensajes flash de error, dejados por la acción anterior antes de una
redirección (horario ya reservado, eliminación rechazada...);
- los errores de entrada de un formulario no válido (ver el ejemplo 19): sus
mensajes se muestran DEBAJO de los campos; aquí, si no hay otro
mensaje, una simple frase "The form contains errors.".
error ?? null: la variable no existe en todas las páginas.
role="alert": un lector de pantalla anuncia el mensaje apenas se muestra la página,
aunque esté al final.
========================================================================= #}
{% set messages = app.flashes('errors') %}
{% if error ?? null %}
{% set messages = [error]|merge(messages) %}
{% endif %}
{% if messages is empty and form is defined and form.vars.submitted and not form.vars.valid %}
{% set messages = [{key: 'ERRORS.INVALID_FORM', params: []}] %}
{% endif %}
{% if messages is not empty %}
<div class="error-zone" role="alert">
{% for message in messages %}
<div>{{ message.key|trans(message.params) }}</div>
{% endfor %}
</div>
{% endif %}
|
El área de errores, en la parte inferior de cada página, sobre un fondo rosa claro. Combina las tres posibles fuentes de error:
- los mensajes de error flash, generados por la acción anterior (una franja horaria ya reservada, una sesión expirada, etc.);
- el error de la página mostrada ([error]), transmitido por la acción: una fecha inválida, un CAPTCHA mal escrito, un nombre de usuario ya en uso, etc.; colocado al principio de la lista. [error ?? null]: esta variable no existe en todas las páginas; el operador [??] no señala una variable inexistente: la reemplaza por [null];
- Los errores de entrada de un formulario inválido (ejemplo 19): sus mensajes se muestran debajo de los campos; aquí, si no hay otros mensajes, una frase simple: «El formulario contiene errores.». En un formulario largo, esto le indica al usuario que debe desplazarse hacia arriba. [form.vars]: las propiedades de la vista del formulario, entre ellas [submitted] (¿enviado?) y [valid] (¿válido?). El mensaje se escribe como un arreglo asociativo con las mismas claves que las propiedades de un [Message]: para [Twig], [message.key] hace referencia tanto a la clave de un arreglo como a la propiedad de un objeto.
[role="alert"]: un lector de pantalla anuncia el mensaje apenas se muestra la página, incluso si está en la parte inferior. El área permanece fija en la parte inferior de la ventana cuando la página es larga (véase la hoja de estilos más abajo).
11.20.1.5. templates/fragments/confirmation.html.twig
| {# =========================================================================
templates/fragments/confirmation.html.twig - el diálogo modal
"Are you sure?" (ver el ejemplo 21).
Reemplaza el cuadro window.confirm() del navegador, que no se puede
personalizar ni traducir (sus botones se quedan en el idioma del navegador, no
en el de la página).
UN ÚNICO diálogo para toda la página, oculto (d-none) al inicio. Sus etiquetas
se traducen aquí, por el servidor, como el resto de la página; el pequeño script
public/js/app.js se limita a mostrarlo, a poner en él el mensaje específico del
formulario (atributo data-confirmation) y a enviar el formulario si
el usuario confirma.
========================================================================= #}
<div id="confirmation-modal" class="d-none">
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
aria-labelledby="confirmation-modal-title" aria-describedby="confirmation-modal-message">
<div class="modal-dialog modal-dialog-centered">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="confirmation-modal-title">{{ 'CONFIRMATION.TITLE'|trans }}</h5>
<button type="button" class="btn-close" data-action="no" aria-label="{{ 'BOOKING_DIALOG.CLOSE_ARIA'|trans }}"></button>
</div>
<div class="modal-body">
<p class="mb-0" id="confirmation-modal-message"></p>
</div>
<div class="modal-footer">
{# "No, go back" en lugar de "Cancel": la pregunta es a veces
"Cancel this appointment?", y un botón "Cancel" sería ambiguo ahí #}
<button type="button" class="btn btn-secondary" data-action="no">{{ 'CONFIRMATION.NO'|trans }}</button>
<button type="button" class="btn btn-danger" data-action="yes">{{ 'CONFIRMATION.YES'|trans }}</button>
</div>
</div>
</div>
</div>
</div>
|
La ventana modal «¿Está seguro?» del ejemplo 21, que reemplaza el cuadro de diálogo [window.confirm()] del navegador: ese cuadro de diálogo no se formatea correctamente, y sus botones permanecen en el idioma del navegador, no en el de la página. Una sola ventana para toda la página, inicialmente oculta (clase [d-none] proveniente de [Bootstrap]); sus etiquetas las traduce el servidor, igual que el resto de la página. El script [public/js/app.js] la muestra, coloca en ella el mensaje del formulario por confirmar (su atributo [data-confirmation]) y envía el formulario si el usuario confirma. El botón «Rechazar» se rotula «No, volver» en lugar de «Cancelar»: la pregunta a veces es «¿Cancelar esta cita?», y un botón «Cancelar» sería ambiguo en ese contexto.
11.20.1.6. templates/fragments/booking.html.twig
| {# =========================================================================
templates/fragments/booking.html.twig - el diálogo de reserva de
la agenda.
Las clases REALES de Bootstrap de un diálogo modal (.modal, .modal-backdrop...),
hechas visibles "a mano" (show d-block) en lugar de mediante el
JavaScript de Bootstrap. Es el SERVIDOR quien decide mostrarlo (parámetro &book=...
de la URL), y cerrarlo equivale a seguir un enlace a la misma página sin este
parámetro.
El fragmento lee directamente las variables de la página que lo incluye
(booking, doctorId, day, backUrl).
========================================================================= #}
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title">
<div class="modal-dialog modal-dialog-centered">
<form method="post" action="{{ path('schedule_book') }}" class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="booking-title">{{ 'BOOKING_DIALOG.TITLE'|trans }}</h5>
<a class="btn-close" href="{{ backUrl }}" aria-label="{{ 'BOOKING_DIALOG.CLOSE_ARIA'|trans }}"></a>
</div>
<div class="modal-body">
<p>{{ 'BOOKING_DIALOG.SLOT'|trans({time: booking.time}) }}</p>
{# lo que el servidor debe saber además del paciente elegido #}
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<input type="hidden" name="doctorId" value="{{ doctorId }}">
<input type="hidden" name="day" value="{{ day }}">
<input type="hidden" name="slotId" value="{{ booking.slotId }}">
{# un paciente reserva para sí mismo: no hay lista donde elegir (y el
servidor ignora de todos modos un posible clientId) #}
{% if booking.patient %}
<p class="mb-0">
<span>{{ 'BOOKING_DIALOG.PATIENT_LABEL'|trans }}</span>:
<strong>{{ booking.patient }}</strong>
</p>
{% else %}
<label class="form-label" for="clientId">{{ 'BOOKING_DIALOG.PATIENT_LABEL'|trans }}</label>
<select id="clientId" name="clientId" class="form-select" required autofocus>
<option value="">{{ 'BOOKING_DIALOG.CHOOSE_PATIENT'|trans }}</option>
{% for client in booking.clients %}
<option value="{{ client.id }}">{{ client.label }}</option>
{% endfor %}
</select>
{% endif %}
</div>
<div class="modal-footer">
<a class="btn btn-secondary" href="{{ backUrl }}">{{ 'BOOKING_DIALOG.CANCEL'|trans }}</a>
<button type="submit" class="btn btn-primary">{{ 'BOOKING_DIALOG.CONFIRM'|trans }}</button>
</div>
</form>
</div>
</div>
|
La ventana de reserva del calendario. Usa las clases reales de una ventana modal de [Bootstrap] ([modal], [modal-backdrop]...), pero se hace visible «a mano» ([show d-block]), en lugar de mediante el [JavaScript] de [Bootstrap]: es el servidor quien decide mostrarla cuando la URL contiene [&book=...]. Cerrarla (mediante la X o el botón Cancelar) equivale a seguir un enlace a la misma página sin ese parámetro ([backUrl]).
- Líneas 27–30: el token anti-CSRF y lo que el servidor necesita saber: el médico, el día y la franja horaria;
- Líneas 34–47: un paciente ingresa su propio nombre sin seleccionarlo de una lista (y el servidor ignora de todos modos cualquier campo [clientId]). El administrador y los médicos seleccionan al paciente de una lista; [required] y [autofocus]: el navegador exige una selección y coloca el cursor en la lista.
11.20.1.7. templates/fragments/captcha.html.twig
| {# =========================================================================
templates/fragments/captcha.html.twig - el CAPTCHA de la página de
inicio de sesión (ver src/Security/CaptchaService.php). Protege tanto el inicio de
sesión como el acceso a la creación de cuentas (botón "Create a patient account").
Lee la variable [captcha] de la página.
captcha.svg|raw: la imagen SVG se inserta TAL CUAL en la página, sin
escapar. Aquí es inofensivo porque este SVG lo construye el propio servidor
y no contiene nada que provenga del usuario - NUNCA haríamos
eso con datos ingresados por el usuario.
El campo oculto captchaId indica al servidor CUÁL CAPTCHA verificar; la respuesta
correcta nunca se envía al navegador. "Another image" simplemente recarga
la página (path('login'): la URL de la página, sin sus parámetros).
========================================================================= #}
<div class="mb-3">
<label class="form-label" for="captcha">{{ 'CAPTCHA.LABEL'|trans }}</label>
<div class="d-flex align-items-center gap-3 mb-2">
<div class="captcha-image" role="img" aria-label="{{ 'CAPTCHA.IMAGE_ALT'|trans }}">{{ captcha.svg|raw }}</div>
<a class="small" href="{{ path('login') }}">{{ 'CAPTCHA.NEW_IMAGE'|trans }}</a>
</div>
<input type="hidden" name="captchaId" value="{{ captcha.id }}">
<input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off"
spellcheck="false" required class="form-control">
<div class="form-text">{{ 'CAPTCHA.HELP'|trans }}</div>
</div>
|
El CAPTCHA (ejemplo 27). [captcha.svg|raw] inserta la imagen SVG tal cual, sin escaparla: de lo contrario, el navegador mostraría su código XML. Esto es seguro aquí porque este SVG lo genera el servidor y no contiene nada proporcionado por el usuario: nunca haríamos esto con datos ingresados por el usuario. El campo oculto [captchaId] le indica al servidor qué CAPTCHA debe verificar; la respuesta en sí nunca se envía al navegador. El enlace «Otra imagen» recarga la página de inicio de sesión y, con ella, el CAPTCHA.
11.20.2. Macros: templates/macros.html.twig
| {# =========================================================================
templates/macros.html.twig - las macros de los formularios (ver el ejemplo 15).
field(field, invalidFields): un campo de un formulario del componente Form,
con su etiqueta, su mensaje de error o su ayuda (form_row, dibujado por el tema
Bootstrap 5, ver el ejemplo 18). El campo se enmarca en rojo (clase
is-invalid) si tiene un error de entrada (el tema se encarga), o si un error de
NEGOCIO lo designa: su nombre está en la lista [invalidFields] pasada por
la acción (un login ya utilizado...), y el mensaje aparece al final de la página.
Los atributos del campo (maxlength...) se completan, no se reemplazan: merge.
========================================================================= #}
{% macro field(field, invalidFields = []) %}
{% set attr = field.vars.attr %}
{% if field.vars.name in invalidFields %}
{% set attr = attr|merge({class: (attr.class|default('') ~ ' is-invalid')|trim}) %}
{% endif %}
{{ form_row(field, {attr: attr}) }}
{% endmacro %}
{# los campos de identidad (título, nombre, apellido), comunes a tres formularios:
médico/cliente del ADMIN, "Create a patient account" y "Manage my account" #}
{% macro identity(form, invalidFields = []) %}
{# import _self: las macros de ESTE archivo, para llamar a la macro field #}
{% import _self as m %}
{{ m.field(form.title, invalidFields) }}
<div class="row g-3">
<div class="col-sm-6">{{ m.field(form.first_name, invalidFields) }}</div>
<div class="col-sm-6">{{ m.field(form.last_name, invalidFields) }}</div>
</div>
{% endmacro %}
|
Dos macros (ejemplo 15), usadas por las tres páginas que muestran un formulario de «persona».
- Líneas 12–18: un campo de un formulario del componente Form, generado por [form_row] (ejemplo 18): su etiqueta, campo de entrada, mensaje de error o texto de ayuda, junto con las clases del tema [Bootstrap] 5 declarado en [config/packages/twig.yaml]. El tema resalta en rojo un campo con un error de entrada (clase [is-invalid]). La macro también la agrega a un campo identificado por un error de la capa de negocio: la lista [invalidFields] pasada por la acción ([PersonsController::BUSINESS_ERROR_FIELDS]). Un nombre de usuario que ya está en uso no es un error de entrada (tiene el formato correcto), pero el usuario necesita ver qué campo corregir. [field.vars]: las propiedades de la vista del campo, entre ellas su nombre ([name]) y sus atributos HTML ([attr]); estos se agregan ([merge]), no se reemplazan: el campo conserva su [maxlength]. El segundo parámetro de [form_row] reemplaza las propiedades de la vista del campo;
- Líneas 22–30: los campos de identidad, comunes a tres formularios: el tratamiento, seguido del nombre y el apellido lado a lado (la cuadrícula de [Bootstrap]: [row], [col-sm-6]). Una macro no puede ver las otras macros de su archivo: [{% import _self as m %}] (línea 24) las importa.
11.20.3. Las páginas
11.20.3.1. templates/login.html.twig
| {# =========================================================================
templates/login.html.twig - el formulario de inicio de sesión (ver AuthController).
Un <form> HTML ordinario escrito a mano: el propio navegador envía login,
contraseña y respuesta del CAPTCHA en POST /login, sin JavaScript. En caso
de fallo, el servidor devuelve ESTA página, con el login ya ingresado, un NUEVO
CAPTCHA y el error, mostrado al final de la página por el layout.
========================================================================= #}
{% extends 'layout.html.twig' %}
{% block content %}
<div class="row justify-content-center">
<div class="col-sm-8 col-md-6 col-lg-5">
<div class="card p-4">
<h5 class="card-title mb-3">{{ 'LOGIN.TITLE'|trans }}</h5>
<form method="post" action="{{ path('login_submit') }}">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<div class="mb-3">
<label class="form-label" for="login">{{ 'LOGIN.LOGIN_LABEL'|trans }}</label>
{# autofocus: un atributo booleano, escrito si la condición es verdadera, omitido
en caso contrario. El cursor va al primer campo por llenar #}
<input id="login" name="login" type="text" class="form-control" autocomplete="username"
value="{{ login }}" required{{ login == '' ? ' autofocus' }}>
</div>
<div class="mb-3">
<label class="form-label" for="password">{{ 'LOGIN.PASSWORD_LABEL'|trans }}</label>
<input id="password" name="password" type="password" class="form-control"
autocomplete="current-password" required{{ login != '' ? ' autofocus' }}>
</div>
{% include 'fragments/captcha.html.twig' %}
<button type="submit" class="btn btn-primary w-100">{{ 'LOGIN.SUBMIT'|trans }}</button>
{# todavía no hay cuenta: un paciente puede crear una por sí mismo. NO es
un simple enlace: es un segundo botón de envío de ESTE formulario,
que va a otra dirección (formaction). El servidor verifica allí el
CAPTCHA anterior antes de abrir la página de creación de cuenta (ver
RegistrationController). formnovalidate: el navegador no exige
login ni contraseña (inútil para crear una cuenta). Enter en un
campo activa siempre el PRIMER botón del formulario, "Log in". #}
<button type="submit" class="btn btn-outline-primary w-100 mt-3"
formaction="{{ path('registration_access') }}" formnovalidate>{{ 'LOGIN.CREATE_ACCOUNT'|trans }}</button>
<div class="form-text text-center">{{ 'LOGIN.CREATE_ACCOUNT_HELP'|trans }}</div>
</form>
<div class="text-muted small mt-3">
<span>{{ 'LOGIN.DEMO_ACCOUNTS'|trans }}</span>
<ul class="mb-0 mt-1">
<li><code>admin</code> - <span>{{ 'LOGIN.DEMO_ADMIN'|trans }}</span></li>
<li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - <span>{{ 'LOGIN.DEMO_DOCTOR'|trans }}</span></li>
<li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - <span>{{ 'LOGIN.DEMO_USER'|trans }}</span></li>
</ul>
</div>
</div>
</div>
</div>
{% endblock %}
|
El formulario de inicio de sesión, un [<form>] escrito a mano, se envía mediante POST a [/login] (la ruta [login_submit]).
- Líneas 22–28: el nombre de usuario ingresado se vuelve a mostrar después de un intento fallido de inicio de sesión ([login]). El atributo [autofocus] coloca el cursor en el primer campo por rellenar: el nombre de usuario si está vacío, o la contraseña en caso contrario (después de un intento fallido o de crear una cuenta). [{{ login == '' ? ' autofocus' }}]: el operador ternario sin «else» devuelve una cadena vacía si la condición es falsa;
- línea 31: el CAPTCHA;
- líneas 42–43: el botón «Crear una cuenta de paciente» no es un enlace; es un segundo botón que envía el mismo formulario a una dirección distinta (atributo del botón [formaction]). Allí el servidor verifica el CAPTCHA antes de abrir la página de creación de cuenta ([RegistrationController::access]). [formnovalidate]: el navegador no exige un nombre de usuario ni una contraseña (atributos [required]), ya que no son necesarios para crear una cuenta. Presionar la tecla Enter en un campo siempre activa el primer botón de envío del formulario: Iniciar sesión.
11.20.3.2. templates/schedule.html.twig
| {# =========================================================================
templates/schedule.html.twig - la página principal (ver ScheduleController).
Tres bloques:
1. la elección del médico y del día;
2. la agenda;
3. el diálogo de reserva (fragmento booking).
Un posible error (fecha no válida, médico desconocido) se muestra al final de
la página por el layout (fragmento errors).
========================================================================= #}
{% extends 'layout.html.twig' %}
{% block content %}
{# 1. elección del médico y del día: un formulario GET, que simplemente recarga
esta página con ?doctorId=...&day=... en la URL #}
<form method="get" action="{{ path('schedule') }}" class="card p-3 mb-3">
<div class="row g-2 align-items-end">
<div class="col-sm-5">
<label class="form-label" for="doctorId">{{ 'DOCTOR_DAY_PICKER.DOCTOR_LABEL'|trans }}</label>
<select id="doctorId" name="doctorId" class="form-select" required>
<option value="">{{ 'DOCTOR_DAY_PICKER.CHOOSE_DOCTOR'|trans }}</option>
{% for doctor in doctors %}
<option value="{{ doctor.id }}"{{ doctor.selected ? ' selected' }}>{{ doctor.label }}</option>
{% endfor %}
</select>
</div>
<div class="col-sm-4">
<label class="form-label" for="day">{{ 'DOCTOR_DAY_PICKER.DAY_LABEL'|trans }}</label>
<input id="day" name="day" type="date" class="form-control" value="{{ day }}" required>
</div>
<div class="col-sm-3">
<button type="submit" class="btn btn-primary w-100">{{ 'DOCTOR_DAY_PICKER.VIEW_SCHEDULE'|trans }}</button>
</div>
</div>
</form>
{# paciente que ya tiene una cita próxima: por eso no hay botón "Book" #}
{% if info %}
<div class="alert alert-info">
<span>{{ info|trans }}</span>
<a href="{{ path('area') }}" class="alert-link">{{ 'APP.MENU_MY_AREA'|trans }}</a>
</div>
{% endif %}
{# 2. la agenda #}
{% if schedule %}
<div class="card p-3">
<h5>{{ 'SCHEDULE.TITLE_PREFIX'|trans }} {{ schedule.day }} - {{ schedule.doctor }}</h5>
{% if schedule.rows is not empty %}
<table class="table table-hover align-middle">
<thead>
<tr>
<th>{{ 'SCHEDULE.COLUMN_SLOT'|trans }}</th>
<th>{{ 'SCHEDULE.COLUMN_STATUS'|trans }}</th>
<th></th>
</tr>
</thead>
<tbody>
{% for row in schedule.rows %}
<tr{{ row.bookable ? ' class="free-slot"' }}>
<td>{{ row.time }}</td>
<td>
{# [patient] se define solo si el usuario tiene derecho a ver este
nombre (ADMIN, DOCTOR, o el paciente para SU cita) - de lo contrario,
simplemente "Booked" #}
{% if row.free %}
<span class="badge text-bg-success">{{ 'SCHEDULE.FREE'|trans }}</span>
{% elseif row.patient %}
<span class="badge {{ row.mine ? 'text-bg-primary' : 'text-bg-secondary' }}">{{ row.patient }}</span>
{% else %}
<span class="badge text-bg-secondary">{{ 'SCHEDULE.BOOKED_BY_OTHER'|trans }}</span>
{% endif %}
</td>
<td>
{# los botones mostrados los decidió el controlador (bookable,
appointmentId) según el rol del usuario. "Book" es un simple
enlace: reabre esta página con el diálogo de reserva de este horario #}
{% if row.bookable %}
<a class="btn btn-sm btn-outline-success" href="{{ row.bookUrl }}">{{ 'SCHEDULE.BOOK'|trans }}</a>
{% endif %}
{# "Cancel" MODIFICA datos: por lo tanto es un POST #}
{% if row.appointmentId %}
<form method="post" action="{{ path('schedule_cancel') }}" class="m-0"
data-confirmation="{{ 'SCHEDULE.CANCEL_CONFIRM'|trans }}">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<input type="hidden" name="appointmentId" value="{{ row.appointmentId }}">
<input type="hidden" name="doctorId" value="{{ doctorId }}">
<input type="hidden" name="day" value="{{ day }}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{ 'SCHEDULE.CANCEL_APPOINTMENT'|trans }}</button>
</form>
{% endif %}
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p class="text-muted mb-0">{{ 'SCHEDULE.NO_SLOTS'|trans }}</p>
{% endif %}
</div>
{% else %}
<p class="text-muted">{{ 'SCHEDULE.EMPTY_STATE'|trans }}</p>
{% endif %}
{# 3. el diálogo de reserva, solo si la URL contiene &book=... #}
{% if booking %}
{% include 'fragments/booking.html.twig' %}
{% endif %}
{% endblock %}
|
La página principal. Tres secciones: la selección de un médico y un día, el calendario y la ventana de reserva.
- Líneas 15–34: selección de un médico y un día: un formulario GET (ejemplo 17), que recarga la página con [?doctorId=...&day=...] en la URL. El día es un campo [type="date"]: el navegador muestra un calendario y envía la fecha en formato [yyyy-mm-dd], sin importar cómo se muestre ([26/09/2026] en francés);
- líneas 37–42: para un paciente que ya tiene una cita próxima, la razón por la que no aparece el botón «Reservar»;
- líneas 66–72: el estado de la franja: Libre (en verde), el nombre del paciente (en azul para la cita del paciente con sesión iniciada, en gris en los demás casos) o «Reservado». La vista no toma ninguna decisión: [row.patient] solo se rellena si el usuario tiene permiso para ver ese nombre;
- líneas 78–80: «Reservar» es un simple enlace: vuelve a abrir la página con la ventana de reserva de esa franja horaria ([row.bookUrl]). No modifica nada: un GET es suficiente;
- líneas 82–91: «Cancelar» modifica datos: es un formulario POST (ejemplo 21), con su token anti-CSRF, la cita por cancelar y la información para regresar a la misma página (el médico, el día). El atributo [data-confirmation] hace que el script de la página solicite confirmación;
- líneas 106–108: la ventana de reserva, si se solicita mediante la URL (y si la franja horaria está disponible para reservar).
11.20.3.3. templates/persons/list.html.twig
| {# =========================================================================
templates/persons/list.html.twig - la lista de los médicos O de los clientes
(ADMIN). Una sola vista para ambos: las claves de las etiquetas propias de cada uno
llegan en [keys], y [section] ("doctors" o "clients") da el comienzo de los
nombres de las rutas (ver PersonsController): section ~ '_add' -> "doctors_add".
========================================================================= #}
{% extends 'layout.html.twig' %}
{% block content %}
<div class="d-flex justify-content-between align-items-center mb-3">
<h4 class="mb-0">{{ keys.title|trans }}</h4>
<a class="btn btn-primary" href="{{ path(section ~ '_add') }}">{{ keys.add|trans }}</a>
</div>
<div class="card p-3">
{% if persons is not empty %}
<table class="table table-hover align-middle mb-0">
<thead>
<tr>
<th>{{ 'PERSONS.COLUMN_TITLE'|trans }}</th>
<th>{{ 'PERSONS.COLUMN_FIRSTNAME'|trans }}</th>
<th>{{ 'PERSONS.COLUMN_LASTNAME'|trans }}</th>
<th>{{ 'PERSONS.COLUMN_LOGIN'|trans }}</th>
<th></th>
</tr>
</thead>
<tbody>
{# person.title: Twig llama al getter getTitle() (ver el ejemplo 13) #}
{% for person in persons %}
<tr>
<td>{{ person.title }}</td>
<td>{{ person.firstName }}</td>
<td>{{ person.lastName }}</td>
<td><code>{{ person.account.login }}</code></td>
<td class="text-end">
<div class="d-inline-flex gap-2">
<a class="btn btn-sm btn-outline-primary"
href="{{ path(section ~ '_edit', {id: person.id}) }}">{{ 'PERSONS.EDIT'|trans }}</a>
{# data-confirmation: se abrirá un diálogo de confirmación antes de
enviar el formulario (ver public/js/app.js) #}
<form method="post" action="{{ path(section ~ '_delete', {id: person.id}) }}" class="m-0"
data-confirmation="{{ keys.confirmDelete|trans }}">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{ 'PERSONS.DELETE'|trans }}</button>
</form>
</div>
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p class="text-muted mb-0">{{ keys.empty|trans }}</p>
{% endif %}
</div>
{% endblock %}
|
La lista de médicos o clientes: las etiquetas específicas de cada uno son claves de traducción ([keys]), y los nombres de las rutas se generan a partir del nombre de la sección ([path(section ~ '_edit', {id: person.id})]: el operador [~] concatena, lo que da como resultado [doctors_edit] o [clients_edit]). [person.account.login]: el login de la cuenta, rellenado junto con la lista (capa DAO). El botón Eliminar es un formulario POST, con confirmación.
| {# =========================================================================
templates/persons/form.html.twig - creación O modificación de un
médico o de un cliente (ADMIN), con el formulario PersonType.
Cuando se rechaza la entrada (campo vacío, login ya utilizado...), la acción
muestra de nuevo ESTA página, y la vista presenta:
- los valores ya ingresados (excepto la contraseña);
- los campos defectuosos enmarcados en rojo (clase Bootstrap "is-invalid");
- bajo un campo rechazado por la validación, su mensaje;
- el mensaje de error de la página, AL FINAL de la página (fragmento errors).
form_start escribe la etiqueta <form> (método POST, URL de la página); form_end, el
final del formulario, con los campos que aún no se han escrito: el
token anti-CSRF y, en la modificación, el campo oculto de versión (el bloqueo optimista).
========================================================================= #}
{% extends 'layout.html.twig' %}
{% import 'macros.html.twig' as m %}
{% block content %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-3">{{ pageTitle|trans }}</h5>
{{ form_start(form) }}
{# form_errors: los errores del formulario mismo (token anti-CSRF incorrecto) #}
{{ form_errors(form) }}
{# título, nombre, apellido: una macro común a tres formularios #}
{{ m.identity(form, invalidFields) }}
<h6 class="mt-4 text-muted">{{ 'PERSONS.ACCOUNT_SECTION'|trans }}</h6>
{{ m.field(form.login, invalidFields) }}
{# nunca se rellena de antemano: la contraseña nunca vuelve al navegador #}
{{ m.field(form.password) }}
<div class="d-flex gap-2 mt-4">
<button type="submit" class="btn btn-primary">{{ 'PERSONS.SAVE'|trans }}</button>
<a class="btn btn-secondary" href="{{ listUrl }}">{{ 'PERSONS.BACK'|trans }}</a>
</div>
{{ form_end(form) }}
</div>
</div>
</div>
{% endblock %}
|
Creación o edición de un médico o un cliente mediante el formulario [PersonType].
- Línea 16: importación de las macros con el nombre [m];
- Línea 24: [form_start] escribe la etiqueta [<form>]: el método POST, la URL de la página y el atributo [novalidate] (opción del tipo [attr]);
- línea 26: [form_errors(form)] muestra los errores del propio formulario que no se relacionan con ningún campo específico: un token anti-CSRF inválido («La página ha expirado...»);
- línea 28: tratamiento, nombre y apellido, mediante la macro [identity];
- líneas 31–33: el nombre de usuario y la contraseña, que nunca se rellenan previamente. Sus textos de ayuda difieren entre la creación y la modificación (opciones del tipo);
- línea 39: [form_end] cierra el formulario después de escribir los campos que aún no se han escrito: el token anti-CSRF y, al editar, el campo oculto de la versión (el bloqueo optimista).
11.20.3.5. templates/registration.html.twig
| {# =========================================================================
templates/registration.html.twig - "Create a patient account" (página pública, ver
RegistrationController), con el formulario RegistrationType. Los mismos campos de
identidad que el formulario del ADMIN (macro identity), pero el login y la
contraseña son obligatorios, con confirmación. Aquí NO hay CAPTCHA: solo
se llega a esta página después de haber copiado el de la página de
inicio de sesión (botón "Create a patient account").
========================================================================= #}
{% extends 'layout.html.twig' %}
{% import 'macros.html.twig' as m %}
{% block content %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-1">{{ 'REGISTRATION.TITLE'|trans }}</h5>
<p class="text-muted small mb-3">{{ 'REGISTRATION.INTRO'|trans }}</p>
{{ form_start(form) }}
{{ form_errors(form) }}
{{ m.identity(form, invalidFields) }}
<h6 class="mt-4 text-muted">{{ 'PERSONS.ACCOUNT_SECTION'|trans }}</h6>
{{ m.field(form.login, invalidFields) }}
{# el campo repetido: sus dos entradas, una al lado de la otra (first, second) #}
<div class="row g-3">
<div class="col-sm-6">{{ m.field(form.password.first) }}</div>
<div class="col-sm-6">{{ m.field(form.password.second) }}</div>
</div>
<div class="d-flex gap-2 mt-3">
<button type="submit" class="btn btn-primary">{{ 'REGISTRATION.SUBMIT'|trans }}</button>
<a class="btn btn-secondary" href="{{ path('login') }}">{{ 'REGISTRATION.BACK_TO_LOGIN'|trans }}</a>
</div>
{{ form_end(form) }}
</div>
</div>
</div>
{% endblock %}
|
Creación de una cuenta de paciente: los campos de identidad, seguidos del nombre de usuario, la contraseña y la confirmación de la contraseña, que son obligatorios. Los dos campos del campo repetido son [form.password.first] y [form.password.second] (líneas 27–28), colocados lado a lado. El texto de ayuda de la contraseña especifica la longitud mínima: «Al menos 6 caracteres.» Aquí no hay CAPTCHA: solo se puede llegar a esta página después de resolver el CAPTCHA de la página de inicio de sesión.
11.20.3.6. templates/area.html.twig
| {# =========================================================================
templates/area.html.twig - "My area": la página de inicio del paciente (rol
USER), mostrada justo después de iniciar sesión.
- dos opciones: [Manage my account] y [View a schedule];
- su próxima cita, si la tiene, con los medios para cancelarla.
========================================================================= #}
{% extends 'layout.html.twig' %}
{% block content %}
<h4 class="mb-3">{{ 'AREA.HELLO'|trans({name: patient}) }}</h4>
<div class="row g-3 mb-4">
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="{{ path('account') }}">
<h5 class="mb-1">{{ 'AREA.MANAGE_ACCOUNT'|trans }}</h5>
<span class="text-muted">{{ 'AREA.MANAGE_ACCOUNT_HELP'|trans }}</span>
</a>
</div>
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="{{ path('schedule') }}">
<h5 class="mb-1">{{ 'AREA.VIEW_SCHEDULE'|trans }}</h5>
<span class="text-muted">{{ 'AREA.VIEW_SCHEDULE_HELP'|trans }}</span>
</a>
</div>
</div>
<div class="card p-3">
<h5>{{ 'AREA.MY_APPOINTMENT'|trans }}</h5>
{# normalmente solo una (regla "una sola cita próxima a la vez"), pero la
página puede mostrar varias. {% for %} ... {% else %}: un bucle, y
lo que se muestra si la lista está vacía; loop.last: ¿último elemento? #}
{% for appointment in appointments %}
<div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2{{ not loop.last ? ' border-bottom' }}">
<div>
<div class="fw-semibold">{{ appointment.day }}, {{ appointment.time }}</div>
<div class="text-muted">
<span>{{ appointment.doctor }}</span> -
<a href="{{ appointment.scheduleUrl }}">{{ 'AREA.SEE_IN_SCHEDULE'|trans }}</a>
</div>
</div>
<form method="post" action="{{ path('area_cancel') }}" class="m-0"
data-confirmation="{{ 'SCHEDULE.CANCEL_CONFIRM'|trans }}">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<input type="hidden" name="appointmentId" value="{{ appointment.id }}">
<button type="submit" class="btn btn-outline-danger">{{ 'AREA.CANCEL_APPOINTMENT'|trans }}</button>
</form>
</div>
{% else %}
<p class="text-muted mb-0">{{ 'AREA.NO_APPOINTMENT'|trans }}</p>
{% endfor %}
</div>
{% endblock %}
|
«Mi área», la página de inicio del paciente: dos tarjetas grandes («Administrar mi cuenta», «Consultar una agenda») y su próxima cita.
- Líneas 32–50: [{% for %}] ... [{% else %}] (ejemplo 14) es un bucle, seguido de lo que se muestra si la lista está vacía. Normalmente, un paciente tiene como máximo una cita próxima; sin embargo, la página es capaz de mostrar varias citas. [loop.last] (ejemplo 14): el último elemento no lleva separador;
- cada cita tiene un formulario de cancelación (POST, con confirmación), que envía solo su identificador: el servidor verificará que pertenezca al paciente con sesión iniciada.
11.20.3.7. templates/account.html.twig
| {# =========================================================================
templates/account.html.twig - "Manage my account" (rol USER).
Dos formularios independientes en la misma página:
1. la modificación (identidad, login, nueva contraseña opcional), con
el formulario MyAccountType;
2. la eliminación de la cuenta - que también cancela sus citas: un
formulario escrito a mano.
Ambos exigen la contraseña ACTUAL (campo current_password).
========================================================================= #}
{% extends 'layout.html.twig' %}
{% import 'macros.html.twig' as m %}
{% block content %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
{# 1. modificación #}
<div class="card p-4 mb-4">
<h5 class="card-title mb-3">{{ 'MY_ACCOUNT.TITLE'|trans }}</h5>
{{ form_start(form) }}
{{ form_errors(form) }}
{{ m.identity(form, invalidFields) }}
<h6 class="mt-4 text-muted">{{ 'PERSONS.ACCOUNT_SECTION'|trans }}</h6>
{{ m.field(form.login, invalidFields) }}
<div class="row g-3">
<div class="col-sm-6">{{ m.field(form.password.first) }}</div>
<div class="col-sm-6">{{ m.field(form.password.second) }}</div>
</div>
{{ m.field(form.current_password) }}
<div class="d-flex gap-2 mt-4">
<button type="submit" class="btn btn-primary">{{ 'PERSONS.SAVE'|trans }}</button>
<a class="btn btn-secondary" href="{{ path('area') }}">{{ 'MY_ACCOUNT.BACK'|trans }}</a>
</div>
{{ form_end(form) }}
</div>
{# 2. eliminación. El campo de contraseña tiene el mismo NOMBRE que el del primer
formulario (current_password), pero otro id: dos elementos de la misma
página no pueden tener el mismo id #}
<div class="card p-4 border-danger">
<h5 class="card-title text-danger mb-1">{{ 'MY_ACCOUNT.DELETE_TITLE'|trans }}</h5>
<p class="text-muted small">{{ 'MY_ACCOUNT.DELETE_HELP'|trans }}</p>
<form method="post" action="{{ path('account_delete') }}" class="d-flex flex-wrap gap-2 align-items-end"
data-confirmation="{{ 'MY_ACCOUNT.DELETE_CONFIRM'|trans }}">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<div class="flex-grow-1">
<label class="form-label" for="delete_password">{{ 'MY_ACCOUNT.CURRENT_PASSWORD_LABEL'|trans }}</label>
<input id="delete_password" name="current_password" type="password" maxlength="72"
autocomplete="current-password" required class="form-control">
</div>
<button type="submit" class="btn btn-danger">{{ 'MY_ACCOUNT.DELETE_SUBMIT'|trans }}</button>
</form>
</div>
</div>
</div>
{% endblock %}
|
«Administrar mi cuenta»: dos formularios independientes en la misma página.
- Líneas 18–38: la actualización, mediante el formulario [MyAccountType]: los campos de identidad, el login, la nueva contraseña y su confirmación (opcionales) y la contraseña actual (obligatoria). La versión (bloqueo optimista) la establece [form_end];
- Líneas 43–56: eliminación de la cuenta, un formulario escrito a mano con su propio campo de contraseña actual y un campo de confirmación. El campo se llama [current_password] (el campo del primer formulario se llama [my_account[current_password]]: el componente Form antepone el nombre del formulario a los nombres de sus campos) y tiene su propio identificador único: dos elementos de una página no pueden tener el mismo identificador, como lo indica el atributo [for] de una etiqueta label.
11.20.3.8. templates/error.html.twig
| {# =========================================================================
templates/error.html.twig - la página de error (400, 403, 404, 405, 419,
500...), construida por src/EventListener/ErrorPage.php.
========================================================================= #}
{% extends 'layout.html.twig' %}
{% block content %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4 text-center">
<h1 class="display-4 text-danger">{{ code }}</h1>
<p class="lead">{{ message|trans }}</p>
<div><a class="btn btn-primary" href="{{ path('home') }}">{{ 'ERROR_PAGE.BACK'|trans }}</a></div>
</div>
</div>
</div>
{% endblock %}
|
La página de error, generada por el listener [ErrorPage]: el código HTTP, el mensaje y un enlace a la página de inicio ([/], que redirige a la página de inicio del rol o a la página de inicio de sesión).
11.21. Archivos estáticos
La carpeta [public] es el directorio raíz del sitio: el servidor envía tal cual los archivos que se encuentran allí (ejemplo 15). Además de [index.php], contiene [Bootstrap] ([lib/bootstrap]), una hoja de estilos y un script.
11.21.1. public/css/styles.css
| /* =========================================================================
public/css/styles.css: algunos ajustes sobre Bootstrap
(los mismos que en las otras versiones de esta aplicación).
========================================================================= */
body {
background-color: #f5f7fa;
}
.free-slot:hover {
background-color: #e9f7ef;
}
/* ─────────────────────────────────────────────────────────────────────────
.error-zone: los mensajes de error, en la parte inferior de la página, sobre un fondo rosa claro
(véase templates/fragments/errors.html.twig).
position: sticky + bottom: si la página es más alta que la ventana (una
agenda de 12 franjas, por ejemplo), la zona permanece pegada a la parte inferior de la
ventana en lugar de desaparecer bajo el pliegue, sin nunca
cubrir el contenido cuando la página es corta.
z-index: por encima del fondo gris del cuadro de diálogo de reserva (.modal-backdrop).
───────────────────────────────────────────────────────────────────────── */
.error-zone {
position: sticky;
bottom: 1rem;
z-index: 1060;
margin-top: 1.5rem;
padding: 0.75rem 1rem;
background-color: #fdecef; /* rosa claro */
border: 1px solid #f5c2c7;
border-radius: 0.375rem;
color: #842029;
}
/* las dos grandes opciones de la página "My area" del paciente */
.option-card {
transition: border-color 0.15s, box-shadow 0.15s;
}
.option-card:hover {
border-color: #0d6efd;
box-shadow: 0 0.25rem 0.75rem rgba(13, 110, 253, 0.15);
}
/* la imagen del captcha (SVG de 150 x 50 píxeles) */
.captcha-image svg {
display: block;
border: 1px solid #dee2e6;
border-radius: 0.375rem;
}
|
Algunos ajustes adicionales para [Bootstrap], los mismos que en las otras versiones de la aplicación.
- Líneas 10–12: una fila reservable del calendario se pone verde cuando el mouse pasa sobre ella;
- líneas 23–33: el área de errores de la parte inferior de la página tiene un fondo rosa claro. [position: sticky] con [bottom: 1rem]: si la página es más alta que la ventana (un calendario con 12 franjas horarias), el área permanece anclada a la parte inferior de la ventana en lugar de desaparecer debajo de la barra de desplazamiento; si la página es corta, permanece en su lugar sin cubrir nada. [z-index]: aparece sobre el fondo gris de la ventana de reserva;
- líneas 36–43: las dos tarjetas grandes de «Mi área», que se iluminan cuando el mouse pasa sobre ellas;
- líneas 46–50: la imagen del CAPTCHA, con un borde.
11.21.2. public/js/app.js
| // =========================================================================
// public/js/app.js - el ÚNICO JavaScript de la aplicación.
// -------------------------------------------------------------------------
// Toda la aplicación funciona sin JavaScript. Este script agrega una
// comodidad: antes de enviar un formulario que lleva el atributo
// data-confirmation="...", un diálogo modal pregunta "Are you sure?"
// (el diálogo en sí está en la página: templates/fragments/confirmation.html.twig).
// Si JavaScript está desactivado, el formulario simplemente se envía sin
// confirmación - nada se rompe (principio de "progressive enhancement").
//
// ¿Por qué no window.confirm()? Su cuadro no se puede estilizar y sus
// botones permanecen en el idioma del navegador, no en el de la página.
// =========================================================================
(() => {
const modal = document.getElementById('confirmation-modal');
if (!modal) {
return;
}
const message = document.getElementById('confirmation-modal-message');
const noButton = modal.querySelector('.modal-footer [data-action="no"]');
let pendingForm = null; // el formulario por enviar si el usuario confirma
let previousFocus = null; // el elemento al que devolver el foco al cerrar
function open(form) {
pendingForm = form;
previousFocus = document.activeElement;
// textContent (y no innerHTML): el mensaje se muestra como TEXTO,
// nunca interpretado como HTML
message.textContent = form.dataset.confirmation;
modal.classList.remove('d-none');
// el foco va a "No": una pulsación distraída de Enter no elimina nada
noButton.focus();
}
function close() {
modal.classList.add('d-none');
pendingForm = null;
if (previousFocus) {
previousFocus.focus();
}
}
// 1. interceptamos el envío de los formularios que requieren confirmación
document.querySelectorAll('form[data-confirmation]').forEach((form) => {
form.addEventListener('submit', (event) => {
event.preventDefault();
open(form);
});
});
// 2. los botones del diálogo (Yes / No / cruz de cierre)
modal.addEventListener('click', (event) => {
const action = event.target.closest('[data-action]')?.dataset.action;
if (action === 'yes') {
const form = pendingForm;
close();
// form.submit() envía el formulario SIN volver a disparar el
// evento 'submit': no hay nueva solicitud de confirmación
form.submit();
} else if (action === 'no') {
close();
} else if (event.target.classList.contains('modal')) {
close(); // clic en el fondo gris, fuera del diálogo
}
});
// 3. teclado: Escape cierra el diálogo; Tab permanece DENTRO del diálogo
// (de lo contrario el foco iría a la página atenuada, detrás)
modal.addEventListener('keydown', (event) => {
if (event.key === 'Escape') {
close();
} else if (event.key === 'Tab') {
const buttons = [...modal.querySelectorAll('button')];
const first = buttons[0];
const last = buttons[buttons.length - 1];
if (event.shiftKey && document.activeElement === first) {
event.preventDefault();
last.focus();
} else if (!event.shiftKey && document.activeElement === last) {
event.preventDefault();
first.focus();
}
}
});
})();
|
El único [JavaScript] de la aplicación, el del ejemplo 21, con algunas adiciones. Toda la aplicación funciona sin [JavaScript]: este script añade comodidad al pedir una confirmación antes de enviar un formulario que lleva el atributo [data-confirmation]. Si [JavaScript] está desactivado, el formulario se envía sin confirmación: nada se rompe (principio de mejora progresiva).
- Líneas 15–19: el script es una función que se invoca en cuanto se define ([(() => { ... })()]); sus variables no son visibles para el resto de la página. Si no hay una ventana de confirmación en la página, no hace nada;
- Líneas 26–35: apertura de la ventana: se guarda el formulario que se enviará si el usuario confirma, y el mensaje del formulario se muestra en la ventana. [textContent], no [innerHTML]: el mensaje se muestra como texto y nunca se interpreta como HTML. El foco pasa al botón «No»: presionar Enter por accidente no elimina nada;
- líneas 37–43: cierre de la ventana; el foco regresa al elemento que lo tenía anteriormente;
- líneas 46–51: se intercepta el envío de cada formulario por confirmar ([preventDefault] lo impide) y se abre la ventana;
- líneas 54–67: los botones de la ventana. Un único manejador para toda la ventana: [closest('[data-action]')] encuentra el botón en el que se hizo clic o el elemento que lo contiene. «Sí» envía el formulario mediante [form.submit()], que no activa el evento [submit]: no se genera una nueva solicitud de confirmación. Hacer clic en el fondo gris fuera de la ventana la cierra;
- líneas 71–86: el teclado. Esc cierra la ventana; la tecla Tab mueve el foco de un botón a otro sin salir de la ventana (de lo contrario, pasaría a la página en gris que está detrás): esto es lo que esperan los usuarios que navegan con el teclado y con lectores de pantalla.