11. Caso de estudio: la aplicación RdvMedecins
11.1. El problema
La aplicación RdvMedecins administra 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 consta de un día, una franja horaria y un cliente (un paciente). Esta es la adaptación exacta, en [Laravel], de la aplicación [Flask] de la lección anterior (que a su vez fue adaptada de las versiones [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 son generadas por el servidor mediante vistas [Blade]; el acceso a la base de datos está a cargo de [Eloquent].
Tres roles de usuario comparten la aplicación:
ADMIN | el administrador ([admin]) | ver agendas, hacer y cancelar citas de cualquier paciente; gestionar (listar, agregar, editar, eliminar) médicos y clientes |
DOCTOR | Médicos | Ver agendas, hacer citas y cancelar citas de cualquier paciente |
USER | clientes (pacientes) | ver las agendas sin ver los nombres de otros pacientes; reservar una cita para sí mismos; cancelar su cita; gestionar su cuenta; crear una cuenta |
Reglas de gestión principales:
- No se permiten citas en el pasado;
- una franja horaria se reserva una sola vez por día;
- un paciente tiene una sola cita próxima a la vez;
- dos médicos (o dos clientes) no pueden tener el mismo nombre y apellido, y un nombre de usuario pertenece a una sola cuenta;
- un médico con citas no puede eliminarse; un cliente se elimina junto con sus citas;
- la página de inicio de sesión está protegida contra bots (CAPTCHA, intentos limitados), y crear una cuenta de paciente exige 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 exigen ingresar los caracteres que muestra la imagen. Los botones FR / EN cambian el idioma:

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

11.2.2. El calendario, visto por el administrador y los médicos
Una vez iniciada la sesión, el administrador llega 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, 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í, del Dr. 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; 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 ahora muestra su próxima cita, que puede cancelar:

Como ya 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 se rechaza, incluso si está escrito en minúsculas y con acento (la propia base de datos compara los nombres sin distinguir entre mayúsculas y minúsculas ni acentos; vea el ejemplo 28):

Eliminar 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 ingresó 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. Pasado ese tiempo (o si el token fue 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-laravel], 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 ampliamos.
11.3.1. Software necesario
Bastan tres programas:
- [PHP] 8.4 o posterior, con la extensión [pdo_mysql] (la aplicación usa características introducidas en la versión 8.4, como [array_find]). Verifique la instalación en un terminal:
El segundo comando lista las extensiones: [pdo_mysql] debe aparecer en ella;
- [Composer], el administrador de bibliotecas de [PHP] (vea los apéndices);
- un servidor [MySQL] 8, por ejemplo el de [Laragon] en [Windows] (vea los apéndices). [MariaDB] también sirve: la aplicación se ha probado con él.
El editor recomendado es [Visual Studio Code], con las extensiones [PHP Intelephense] y [Laravel] (vea los apéndices); sin embargo, todo puede hacerse desde la línea de comandos.
11.3.2. Instalar las bibliotecas
La carpeta [vendor] no se incluye: créela una vez por todas en una ventana de terminal abierta en la carpeta [rdvmedecins2-laravel] (debe estar conectado a Internet):
[Composer] lee el archivo [composer.json] (que se explica más adelante), descarga [Laravel], [firebase/php-jwt] y las bibliotecas de las que dependen, y genera el cargador de clases [vendor/autoload.php].
11.3.3. Crear la base de datos
La base de datos [dbrdvmedecins2] se crea con el script [database/dbrdvmedecins2.sql]. Con [Laragon], abra la herramienta [HeidiSQL] (botón Base de datos) y ejecute el script desde el menú Archivo / Ejecutar archivo SQL. Desde 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 otras 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. Configurar el acceso a la base de datos
Toda la configuración de la instalación se encuentra en el archivo [.env] (que se explica más adelante). De forma predeterminada, 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 predeterminada de [Laragon]. Si su cuenta [root] tiene contraseña, escríbala en este archivo, en la línea [DB_PASSWORD=]. Una variable de entorno del sistema tiene prioridad sobre el archivo (ejemplo 25): esto permite indicar la contraseña sin escribirla en un archivo del proyecto.
11.3.5. Ejecutar la aplicación
En una ventana de terminal abierta en la carpeta [rdvmedecins2-laravel]:
| php artisan serve --port=8081
|
| INFO Server running on [http://127.0.0.1:8081].
Press Ctrl+C to stop the server
|
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).
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 (pacientes) |
Guía para explorar la aplicación:
- [admin]: Agenda, Sra. Marie PELISSIER; hoy: una franja horaria ya está reservada por la Sra. Brigitte BISTROU. Reserve una franja para el Sr. Jean MARTIN y luego intente reservarle una segunda cita (rechazada). Menús Médicos y Pacientes: agregar, editar, eliminar (la Dra. PELISSIER, que tiene citas, no puede eliminarse);
- [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] suministrado configura la aplicación para el desarrollo:
- [DB_LOG=true]: la consola del servidor muestra cada comando SQL enviado a la base de datos, así como cada etapa de las transacciones (ejemplo 28). Por ejemplo, para mostrar un calendario:
| select * from `doctors` order by `last_name` asc, `first_name` asc []
select * from `users` where `users`.`id` in (2, 3, 4) []
select * from `doctors` where `doctors`.`id` = ? limit 1 [1]
select * from `users` where `users`.`id` in (2) []
select * from `appointments` where `day` = ? and exists (select * from `slots` where `appointments`.`slot_id` = `slots`.`id` and `doctor_id` = ?) ["2026-09-26",1]
select * from `clients` where `clients`.`id` in (3) []
select * from `slots` where `doctor_id` = ? order by `start_hour` asc, `start_minute` asc [1]
2026-09-26 18:50:14 /schedule .................................... ~ 0.10ms
|
- [APP_DEBUG=true]: una excepción inesperada muestra la [Laravel] 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 una vista modificada se recompila en la siguiente solicitud.
El depurador [Xdebug] 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 (vea xdebug.org).
11.3.8. Un servidor de producción
El servidor [php artisan serve] 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; las carpetas [storage] y [bootstrap/cache] deben poder ser escritas por el servidor. Preparamos la aplicación con unos pocos comandos:
| composer install --no-dev --optimize-autoloader
php artisan key:generate
php artisan config:cache
php artisan route:cache
php artisan view:cache
|
[key:generate] escribe una nueva clave de cifrado en el archivo [.env]; los tres comandos siguientes combinan la configuración, las rutas y las vistas compiladas en unos pocos archivos, que se cargan más rápido que los originales (este proceso debe repetirse después de cada modificación). En el archivo [.env] también debe indicar el modo de producción, cambiar la clave secreta de los tokens y declarar que el sitio se sirve mediante HTTPS:
| APP_ENV=production
APP_DEBUG=false
JWT_SECRET=<a long random string>
COOKIE_SECURE=true
|
Puede obtenerse una cadena aleatoria adecuada con [PHP] mismo: [php -r "echo bin2hex(random_bytes(32));"].
11.3.9. Problemas frecuentes
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 se inicie: el error aparece en la primera página que consulta la base de datos (la página de inicio de sesión no la consulta; el proceso de inicio de sesión sí). Con [APP_DEBUG=true], el error se muestra en la [Laravel] página de depuración; en todos los casos, se registra en el log [storage/logs/laravel.log]. Por ejemplo, con una base de datos que no existe:
| [2026-09-26 18:55:12] local.ERROR: SQLSTATE[HY000] [1049] Unknown database 'dbunknown' (Connection: mysql, Host: 127.0.0.1, Port: 3306, Database: dbunknown, SQL: select * from `users` where `login` = admin limit 1) {"exception":"[object] (Illuminate\\Database\\QueryException(code: 1049): ...
|
Los mensajes más comunes:
[Failed opening required '.../vendor/autoload.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 de [Laragon]) |
[SQLSTATE[HY000] [2002] Connection refused] | [MySQL] no se ha iniciado, o no escucha en [127.0.0.1:3306] |
[SQLSTATE[HY000] [1045] Access denied for user 'root'@'localhost'] | La contraseña de [MySQL] debe ingresarse en [.env] (vea “Configurar el acceso a la base de datos”) |
[SQLSTATE[HY000] [1049] Unknown database 'dbrdvmedecins2'] | El script [database/dbrdvmedecins2.sql] no se ejecutó |
[No application encryption key has been specified.] | La variable [APP_KEY] del archivo [.env] está vacía: [php artisan key:generate] |
[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 127.0.0.1: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 artisan serve], o [nginx] + [PHP-FPM]), que las reenvía a [Laravel] a través del archivo [public/index.php]. Cada solicitud pasa primero por las capas de middleware (vea el capítulo sobre el ciclo de vida): el idioma de la solicitud ([SetLanguage]), las cookies, la sesión, la protección anti-CSRF y, por último, la autenticación: el usuario se identifica a partir del token JWT de su cookie, y las páginas protegidas se niegan a los visitantes que no tienen acceso ([Authenticate], [RequireRoles]);
- [Http/Controllers]: los controladores de la capa web. Todos pasan por un único objeto, [ApplicationModel] (carpeta [Web]), que guarda en caché las listas de médicos y clientes y reenvía las demás solicitudes a la capa de negocio; [Http/Requests]: la validación de formularios;
- [Auth]: tokens, JWT, CAPTCHA, límites de intentos y el pase de creación de cuenta;
- [Web]: lo que los controladores tienen en común: la caché y la fachada [ApplicationModel], los mensajes flash y algunas utilidades; [Views]: las plantillas de vistas;
- [Business]: las reglas de negocio y las transacciones;
- [Dao]: la capa DAO, una clase por tabla;
- [Models]: los modelos [Eloquent], que la capa DAO lee y escribe en la base de datos; [Domain]: los objetos del calendario, calculados por la capa de negocio;
- [resources/views]: las vistas [Blade], que generan las páginas HTML; [lang]: los diccionarios; [public]: la hoja de estilos, el script de la página y [Bootstrap];
- [bootstrap/app.php] y [app/Providers/AppServiceProvider.php] lo ensamblan todo; [.env] y la carpeta [config]: la configuración.
La carpeta de la aplicación (sin [vendor] ni el contenido de [storage]):
| rdvmedecins2-laravel/
├── app/
│ ├── Auth/
│ │ ├── AttemptLimiter.php
│ │ ├── AuthService.php
│ │ ├── Captcha.php
│ │ ├── CaptchaDrawing.php
│ │ ├── CaptchaService.php
│ │ ├── ConnectedUser.php
│ │ ├── InvalidSession.php
│ │ ├── README.md
│ │ └── RegistrationPass.php
│ ├── Business/
│ │ ├── Business.php
│ │ ├── BusinessException.php
│ │ ├── BusinessService.php
│ │ ├── Dates.php
│ │ ├── Descriptor.php
│ │ ├── PersonData.php
│ │ └── README.md
│ ├── Dao/
│ │ ├── AppointmentDao.php
│ │ ├── ClientDao.php
│ │ ├── DoctorDao.php
│ │ ├── PersonDao.php
│ │ ├── README.md
│ │ ├── SlotDao.php
│ │ └── UserDao.php
│ ├── Domain/
│ │ ├── DoctorDaySchedule.php
│ │ ├── DoctorDaySlot.php
│ │ └── README.md
│ ├── Http/
│ │ ├── Controllers/
│ │ │ ├── AuthController.php
│ │ │ ├── ClientsController.php
│ │ │ ├── DoctorsController.php
│ │ │ ├── LanguageController.php
│ │ │ ├── PatientAreaController.php
│ │ │ ├── PersonsController.php
│ │ │ ├── RegistrationController.php
│ │ │ └── ScheduleController.php
│ │ ├── Middleware/
│ │ │ ├── CheckRegistrationPass.php
│ │ │ ├── RequireRoles.php
│ │ │ └── SetLanguage.php
│ │ ├── README.md
│ │ └── Requests/
│ │ ├── MyAccountRequest.php
│ │ ├── PersonFieldsRequest.php
│ │ ├── PersonRequest.php
│ │ └── RegistrationRequest.php
│ ├── Models/
│ │ ├── Appointment.php
│ │ ├── Client.php
│ │ ├── Doctor.php
│ │ ├── Person.php
│ │ ├── README.md
│ │ ├── Role.php
│ │ ├── Slot.php
│ │ └── User.php
│ ├── Providers/
│ │ └── AppServiceProvider.php
│ ├── Views/
│ │ ├── AppointmentView.php
│ │ ├── BookingView.php
│ │ ├── OptionView.php
│ │ ├── PersonKeys.php
│ │ ├── README.md
│ │ ├── ScheduleRow.php
│ │ └── ScheduleView.php
│ └── Web/
│ ├── ApplicationModel.php
│ ├── Flash.php
│ ├── Message.php
│ ├── README.md
│ └── Utils.php
├── artisan
├── bootstrap/
│ ├── app.php
│ ├── cache/
│ └── providers.php
├── composer.json
├── config/
│ ├── app.php
│ ├── auth.php
│ ├── hashing.php
│ ├── rdvmedecins.php
│ └── session.php
├── database/
│ ├── dbrdvmedecins2.sql
│ └── README.md
├── .env
├── .env.example
├── lang/
│ ├── en.json
│ └── fr.json
├── public/
│ ├── css/
│ │ └── styles.css
│ ├── index.php
│ ├── js/
│ │ └── app.js
│ └── lib/
│ └── bootstrap/
├── README.md
├── resources/
│ └── views/
│ ├── account.blade.php
│ ├── area.blade.php
│ ├── components/
│ │ ├── captcha.blade.php
│ │ ├── field.blade.php
│ │ └── person-fields.blade.php
│ ├── error.blade.php
│ ├── fragments/
│ │ ├── booking.blade.php
│ │ ├── confirmation.blade.php
│ │ ├── errors.blade.php
│ │ ├── navbar.blade.php
│ │ └── success.blade.php
│ ├── layout.blade.php
│ ├── login.blade.php
│ ├── persons/
│ │ ├── form.blade.php
│ │ └── list.blade.php
│ ├── README.md
│ ├── registration.blade.php
│ └── schedule.blade.php
├── routes/
│ └── web.php
└── storage/
|
Esta es la estructura de una aplicación [Laravel] estándar, la que genera el comando [composer create-project laravel/laravel] (Ejemplo 01), sin los elementos que aquí no se necesitan (pruebas, migraciones, herramientas de compilación [JavaScript], etc.). 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 un proveedor de servicios ([app/Providers/AppServiceProvider.php]), que se explica más adelante. Las clases de la aplicación se organizan en la carpeta [app], según la regla PSR-4 (Ejemplo 01): la clase [App\Business\BusinessService] está en el archivo [app/Business/BusinessService.php]. [Laravel] no impone ninguna de estas carpetas (Ejemplo 06): [Http], [Models] y [Providers] son las que se usan; las demás ([Auth], [Dao], [Business]...) 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]: usuarios autorizados a iniciar sesión;
- [doctors] y [clients]: médicos y 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 hacia 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
-- - contraseña = apellido en minúsculas, con hash bcrypt (10 rondas)
-- - nombre mostrado = 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 los
-- mismos nombre y apellido;
-- - unq_clients_first_name_last_name : lo mismo para los clientes.
-- Atención: la colación 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]
-- (estas la referencian), y eliminarse DESPUÉS de ellas.
-- =========================================================================
-- el script está escrito en UTF-8
SET NAMES utf8mb4;
-- partimos 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 los mismos 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 los mismos nombre y apellido
CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);
-- -------------------------------------------------------------------------
-- tabla [slots]: los intervalos de tiempo 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),
-- el mismo intervalo, en el 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 sal)
-- 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'));
-- intervalos del médico PELISSIER (doctor_id = 1): de 8:00 a 12:00 en pasos 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);
-- intervalos del médico TATOU (doctor_id = 2): de 14:00 a 18:00 en pasos 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 intervalo 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 collation [utf8mb4_unicode_ci], que compara 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 restablece la base de datos a su estado inicial. El orden importa: una tabla no puede eliminarse mientras otra la referencie mediante una clave externa;
- líneas 46–55: users: un nombre de usuario, una contraseña con hash generado por [bcrypt] (ejemplo 25), el nombre que se muestra una vez iniciada la 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 en 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 el nombre de usuario. Los hashes comienzan con [$2b$10$]: el algoritmo ([bcrypt], variante [2b]) y el costo (10). Siguen la sal y el hash. Estos hashes los calculó la versión [Flask] de la aplicación; [PHP] escribe los suyos con el prefijo [$2y$], pero verifica ambos por igual (vea [config/hashing.php], más adelante);
- 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 de la Dra. PELISSIER para la Sra. BISTROU: el calendario muestra así de inmediato una franja horaria reservada.
A diferencia de [Laravel], la base de datos no se crea mediante migraciones ([PHP] clases que describen la creación y la evolución de las tablas, ejecutadas por [php artisan migrate]): se comparte con las demás versiones de la aplicación, y el script SQL es común a todas ellas.
11.6. La configuración del proyecto
11.6.1. composer.json
| {
"name": "rdvmedecins/rdvmedecins2-laravel",
"description": "RdvMedecins: medical appointment booking, HTML pages built by the server (Laravel + Blade)",
"type": "project",
"license": "MIT",
"require": {
"php": "^8.4",
"ext-pdo_mysql": "*",
"laravel/framework": "^13.33",
"firebase/php-jwt": "^7.0"
},
"autoload": {
"psr-4": {
"App\\": "app/"
}
},
"scripts": {
"post-autoload-dump": [
"Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
"@php artisan package:discover --ansi"
]
},
"config": {
"optimize-autoloader": true,
"sort-packages": true
},
"minimum-stability": "stable",
"prefer-stable": true
}
|
- Líneas 6–11: las bibliotecas que requiere la aplicación y las restricciones que deben cumplir. [^13.33] se lee “versión 13.33 o una versión más reciente de la misma versión mayor 13”: [Composer] acepta versiones que corrigen errores o agregan funciones, pero no las que podrían romper la aplicación (versión 14). Las líneas [php] y [ext-pdo_mysql] no se refieren a bibliotecas, sino a requisitos del entorno: [Composer] impide la instalación si la versión de [PHP] o la extensión es incompatible, en lugar de dejar que la aplicación falle más tarde;
- Líneas 12–16: la regla PSR-4 de la aplicación: las clases del espacio de nombres [App] se encuentran en la carpeta [app] (Ejemplo 01: en los ejemplos, [bootstrap/app.php] declaraba esta regla por sí mismo al cargador de clases mediante [addPsr4]);
- líneas 18–21: comandos que [Composer] ejecuta después de crear el cargador de clases: [Laravel] lista los proveedores de servicios de las bibliotecas instaladas ([package:discover], en [bootstrap/cache]).
[composer install] instala las versiones que cumplen estas restricciones y registra las versiones exactas instaladas en un archivo llamado [composer.lock]. Las instalaciones posteriores (en otra máquina, por ejemplo) 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] lista lo que está instalado en la carpeta [vendor].
11.6.2. .env
| # =========================================================================
# .env: los ajustes específicos de ESTA instalación (leídos por env('NAME') en los
# archivos de la carpeta config). Este archivo nunca se publica: contiene
# secretos. Una variable de entorno del sistema tiene precedencia sobre él.
# =========================================================================
APP_NAME=RdvMedecins
# local: desarrollo; production: en producción
APP_ENV=local
# clave de cifrado de Laravel (cookies, sesión). En producción:
# php artisan key:generate (escribe una nueva clave en este archivo)
APP_KEY=base64:+UmYSB3+TOKSr/f/fiqPCyo5IXFgXOLrvO1II52r+q4=
# true: una excepción inesperada muestra la página de depuración de Laravel, con su
# pila de llamadas (NUNCA en producción); false: la página de error 500 de la aplicación
APP_DEBUG=true
APP_URL=http://localhost:8081
# - la base de datos MySQL [dbrdvmedecins2] (script: database/dbrdvmedecins2.sql):
# el servidor, su puerto, la base de datos, el usuario y su contraseña (los de
# Laragon: root, sin contraseña)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=dbrdvmedecins2
DB_USERNAME=root
DB_PASSWORD=
# true: las instrucciones SQL enviadas a la base de datos se muestran en la consola
DB_LOG=true
# - la sesión de Laravel (mensajes flash, token anti-CSRF, entrada que se
# vuelve a mostrar): almacenada en una cookie CIFRADA, el servidor no conserva nada
SESSION_DRIVER=cookie
SESSION_LIFETIME=120
# - la caché (listas de médicos y de clientes, captchas, contadores de
# intentos, pases): archivos, en storage/framework/cache
CACHE_STORE=file
# el registro: storage/logs/laravel.log
LOG_CHANNEL=single
# - autenticación (véase config/rdvmedecins.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
# true en producción (sitio servido por HTTPS): las cookies nunca viajan sin cifrar
COOKIE_SECURE=false
# - protección contra robots (véase app/Auth/AttemptLimiter.php)
LOGIN_MAX_FAILURES=5
LOGIN_BLOCK_MINUTES=15
REGISTRATION_MAX_PER_HOUR=10
|
El archivo que contiene los ajustes específicos de esta instalación (ejemplo 25): varían de una máquina a otra (la base de datos, sus credenciales) o son secretos (las claves). Nunca se publica; el archivo [.env.example], que no contiene secretos, le sirve de plantilla.
- Línea 11: la clave de cifrado de [Laravel]: cifra las cookies (ejemplo 20), incluida la cookie de sesión. El comando [php artisan key:generate] escribe una nueva;
- línea 14: durante el desarrollo, una excepción inesperada muestra la [Laravel] página de depuración; en producción ([false]), la página de error 500 de la aplicación;
- líneas 20–25: la conexión a la base de datos (ejemplo 28);
- Línea 31: la sesión de [Laravel] (Ejemplo 23) se almacena en una cookie cifrada en lugar de en archivos del servidor. La aplicación guarda allí muy poca información (mensajes flash, el token anti-CSRF, datos de formularios que se volverán a mostrar): una sola cookie basta, y el servidor ya no necesita almacenar nada entre solicitudes. [Laravel] usa dos cookies: [rdvmedecins_session] contiene el ID de sesión, y una segunda cookie, con el nombre de ese ID, contiene los datos de la sesión;
- Línea 35: la caché (ejemplo 20) se almacena en archivos dentro de la carpeta [storage/framework/cache]. La aplicación guarda allí las listas de médicos y clientes, los CAPTCHA, los contadores de intentos y los tokens de acceso: información que debe compartirse entre todas las solicitudes. Con varios servidores se usaría una caché compartida, como [Redis];
- líneas 41–48: ajustes propios de la aplicación: los tokens JWT (ejemplo 25) y la protección contra bots (ejemplo 27).
11.6.3. config/app.php, config/session.php, config/hashing.php, config/auth.php
Los archivos de la carpeta [config] complementan la configuración predeterminada de [Laravel] (Ejemplo 25): solo se modifican las claves que escriben.
| <?php
// config/app.php: este archivo COMPLETA la configuración predeterminada de Laravel
// (vendor/laravel/framework/config/app.php): solo cambian las claves escritas aquí
return [
// el idioma predeterminado de la interfaz (véanse lang/fr.json, lang/en.json), y el
// idioma de respaldo (solo lo usan los archivos PHP de la carpeta lang: una clave
// ausente de un diccionario JSON se muestra tal cual)
'locale' => 'en',
'fallback_locale' => 'en',
// la zona horaria: la del consultorio médico. Determina la fecha actual
// (ninguna cita en el pasado, véase app/Business/Dates.php)
'timezone' => 'Europe/Paris',
];
|
- líneas 8–9: el idioma predeterminado de la interfaz (Ejemplo 22) y el idioma de respaldo (que se usa solo para los archivos [PHP] de la carpeta [lang]; vea el Ejemplo 22);
- línea 13: la zona horaria. De forma predeterminada, [Laravel] opera en 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 en UTC sigue siendo el anterior: prevalece la zona horaria del consultorio.
| <?php
// config/session.php: la sesión de Laravel (completa la configuración predeterminada).
// Controlador [cookie] (véase .env, SESSION_DRIVER): los datos de sesión (mensajes
// flash, token anti-CSRF, entrada que se vuelve a mostrar) viajan en una cookie CIFRADA
return [
'cookie' => 'rdvmedecins_session',
// las cookies de la aplicación solo viajan por HTTPS en producción
'secure' => (bool) env('COOKIE_SECURE', false),
];
|
El nombre de la cookie de sesión y la opción [secure] de las cookies de sesión, leídos del archivo [.env] ([(bool)] convierte el valor a booleano; [env] ya reconoce [false] y [true]).
| <?php
// config/hashing.php: el hash de contraseñas (completa la configuración predeterminada)
return [
'driver' => 'bcrypt',
'bcrypt' => [
// 10 rondas, como los hashes del script SQL
'rounds' => 10,
// Por omisión, Laravel verifica que un hash almacenado sea efectivamente un hash bcrypt
// tal como lo escribe PHP ($2y$). Pero la base de datos dbrdvmedecins2 está
// compartida con las versiones Python ($2b$) y Java ($2a$) de la aplicación,
// cuyos hashes PHP verifica muy bien, sin reconocerlos como
// "bcrypt". Por eso esta verificación se desactiva
'verify' => false,
],
];
|
Hash de contraseñas: [bcrypt], 10 rondas, como los hashes del script SQL. La línea 13 desactiva una verificación que [Laravel] realiza de forma predeterminada: antes de comparar una contraseña con un hash, comprueba que el hash haya sido generado realmente por el algoritmo configurado, tal como lo escribe [PHP] ([$2y$]). Los hashes de la base de datos, generados por [Python] ([$2b$]) o por [Java] ([$2a$]), no pasarían esta verificación, aunque [PHP] es perfectamente capaz de verificarlos. Es el precio de compartir una base de datos con otras aplicaciones.
| <?php
// config/auth.php: la autenticación (completa la configuración predeterminada)
return [
// el "guard" usado por omisión: el que lee el token JWT de la cookie
'defaults' => [
'guard' => 'jwt',
],
'guards' => [
// un guard con el controlador [jwt], definido por AppServiceProvider (Auth::viaRequest)
'jwt' => [
'driver' => 'jwt',
],
],
];
|
El guardia [jwt], el guardia predeterminado para el controlador [jwt]: exactamente igual que en el Ejemplo 25.
11.6.4. config/rdvmedecins.php
| <?php
// config/rdvmedecins.php: los ajustes específicos de la aplicación, leídos por
// config('rdvmedecins.xxx'). Los valores provienen del archivo .env; el segundo
// parámetro de env() es el valor predeterminado
return [
'jwt' => [
// clave secreta de los tokens JWT: al menos 32 caracteres (HMAC-SHA256)
'secret' => env('JWT_SECRET', ''),
// duración de validez de un token, en minutos; la cookie que lo transporta
// tiene la misma duración
'duration' => (int) env('JWT_DURATION_MINUTES', 120),
],
// true: las instrucciones SQL enviadas a la base de datos se muestran en la consola
'db_log' => (bool) env('DB_LOG', false),
// true en producción (HTTPS): las cookies nunca se envían sin cifrar
'cookie_secure' => (bool) env('COOKIE_SECURE', false),
// protección contra robots (véase app/Auth/AttemptLimiter.php):
// login: fallos permitidos para el mismo login desde la misma dirección IP,
// luego bloqueo durante esta duración (también se bloquea toda la dirección IP
// si acumula 5 veces más fallos, todos los logins juntos)
'login_max_failures' => (int) env('LOGIN_MAX_FAILURES', 5),
'login_block_minutes' => (int) env('LOGIN_BLOCK_MINUTES', 15),
// creación de cuentas de cliente: máximo de cuentas creadas por hora y por dirección
// IP. En un salón de clases, todas las computadoras suelen salir por la misma dirección:
// aumente el valor si es necesario
'registration_max_per_hour' => (int) env('REGISTRATION_MAX_PER_HOUR', 10),
];
|
Ajustes propios de la aplicación, leídos con [config('rdvmedecins.jwt.secret')], [config('rdvmedecins.login_max_failures')]... Cada valor proviene del archivo [.env], con un valor predeterminado. Recuerde la regla (Ejemplo 25): [env] se llama solo en los archivos de la carpeta [config]; el resto del código lee [config(...)]. Una vez que la configuración está en caché ([php artisan config:cache]), el archivo [.env] ya no se lee en absoluto.
11.7. Cuando la aplicación
11.7.1. public/index.php y bootstrap/providers.php
El archivo [public/index.php] es el de los ejemplos (Ejemplo 01), con la ruta a la carpeta [vendor] de la aplicación:
| <?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
use Illuminate\Foundation\Application;
use Illuminate\Http\Request;
// cargador de clases de Composer
require __DIR__.'/../vendor/autoload.php';
// la aplicación, construida por bootstrap/app.php, atiende la solicitud actual
/** @var Application $app */
$app = require_once __DIR__.'/../bootstrap/app.php';
$app->handleRequest(Request::capture());
|
El archivo [bootstrap/providers.php] es nuevo:
| <?php
// bootstrap/providers.php: los proveedores de servicios (service providers) de la
// aplicación, cargados al inicio de cada solicitud (véase app/Providers)
use App\Providers\AppServiceProvider;
return [
AppServiceProvider::class,
];
|
Devuelve la lista de proveedores de servicios de la aplicación. Un proveedor de servicios es una clase cuyos dos métodos llama [Laravel] al inicio de cada solicitud: [register], que registra servicios en el contenedor (ejemplo 06) y luego, una vez registrados todos los proveedores, [boot], que puede usar cualquier servicio. [Laravel] mismo está compuesto por proveedores de servicios (uno para la sesión, uno para las vistas, uno para la base de datos, etc.), igual que la mayoría de las bibliotecas escritas para él. En los ejemplos, escribíamos estas declaraciones en [bootstrap/app.php] ([withSingletons], [booted]): esto es cómodo para unas pocas líneas; una aplicación a gran escala las agrupa en un proveedor de servicios, [AppServiceProvider] por convención.
11.7.2. app/Providers/AppServiceProvider.php
| <?php
// =========================================================================
// app/Providers/AppServiceProvider.php: el PROVEEDOR DE SERVICIOS de la aplicación
// (declarado en bootstrap/providers.php). Es el lugar normal, en una
// aplicación Laravel, para lo que los ejemplos escribían en bootstrap/app.php:
// - $singletons: los servicios compartidos (véase el ejemplo 06);
// - boot(): lo que debe hacerse al inicio de cada solicitud, una vez registrados todos
// los servicios: el controlador de autenticación JWT, las variables
// comunes a todas las vistas, la visualización de las instrucciones SQL.
// =========================================================================
namespace App\Providers;
use App\Auth\AuthService;
use App\Auth\CaptchaService;
use App\Auth\AttemptLimiter;
use App\Auth\RegistrationPass;
use App\Dao\ClientDao;
use App\Dao\SlotDao;
use App\Dao\DoctorDao;
use App\Dao\AppointmentDao;
use App\Dao\UserDao;
use App\Business\BusinessService;
use App\Web\ApplicationModel;
use Illuminate\Database\Events\QueryExecuted;
use Illuminate\Database\Events\TransactionBeginning;
use Illuminate\Database\Events\TransactionCommitted;
use Illuminate\Database\Events\TransactionRolledBack;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Cookie;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\View;
use Illuminate\Support\ServiceProvider;
use Illuminate\View\View as TheView;
class AppServiceProvider extends ServiceProvider
{
// -----------------------------------------------------------------------
// los servicios compartidos: para cada una de estas clases, el contenedor de Laravel
// crea un solo objeto (por solicitud), entregado a todos los que lo piden: los
// controladores, a través de su constructor. El contenedor construye por sí mismo las
// dependencias de cada uno (así, BusinessService recibe sus cinco DAO): esto es la
// inyección de dependencias.
// -----------------------------------------------------------------------
public array $singletons = [
DoctorDao::class => DoctorDao::class,
ClientDao::class => ClientDao::class,
SlotDao::class => SlotDao::class,
AppointmentDao::class => AppointmentDao::class,
UserDao::class => UserDao::class,
BusinessService::class => BusinessService::class,
ApplicationModel::class => ApplicationModel::class,
AuthService::class => AuthService::class,
CaptchaService::class => CaptchaService::class,
AttemptLimiter::class => AttemptLimiter::class,
RegistrationPass::class => RegistrationPass::class,
];
public function boot(): void
{
// - el controlador de guard [jwt] (véase config/auth.php, ejemplo 25): una
// función que recibe la solicitud y devuelve el usuario autenticado, o null
// para un visitante anónimo. Laravel la invoca en el primer Auth::user() de la
// solicitud; si encontró un usuario, lo conserva durante el resto de la
// solicitud (de lo contrario, vuelve a invocar la función en cada Auth::user())
Auth::viaRequest('jwt', function (Request $request) {
$token = $request->cookie(AuthService::COOKIE);
if (! is_string($token) || $token === '') {
return null;
}
$user = app(AuthService::class)->currentUser($token);
if ($user === null) {
// una cookie presente pero no válida (expirada, token falsificado): la borramos
Cookie::queue(AuthService::clearingCookie());
}
return $user;
});
// - las variables comunes a TODAS las vistas (véase el ejemplo 15): un
// "view composer" se ejecuta antes de construir cada vista ('*')
// - user : el usuario con sesión iniciada (o null), para la barra de navegación;
// - language : "fr" o "en".
View::composer('*', function (TheView $view) {
$view->with(['user' => Auth::user(), 'language' => App::getLocale()]);
});
// - DB_LOG=true (archivo .env): cada instrucción SQL, y cada paso de una
// transacción, se muestra en la consola del servidor (véase el ejemplo 28)
if (config('rdvmedecins.db_log')) {
DB::listen(fn (QueryExecuted $q) => error_log($q->sql.' '.json_encode($q->bindings, JSON_UNESCAPED_UNICODE)));
Event::listen(TransactionBeginning::class, fn () => error_log('BEGIN'));
Event::listen(TransactionCommitted::class, fn () => error_log('COMMIT'));
Event::listen(TransactionRolledBack::class, fn () => error_log('ROLLBACK'));
}
}
}
|
- Líneas 48–60: servicios compartidos. La propiedad [$singletons] de un proveedor de servicios la lee [Laravel], que declara cada uno de sus pares [interface => class] como singleton (Ejemplo 06): esto equivale a [withSingletons]. Aquí, cada clase se declara por separado. Recuerde que un singleton existe solo durante una única solicitud (Ejemplo 06): la ventaja aquí es que todos los controladores, middleware y servicios de la misma solicitud comparten el mismo [ApplicationModel], el mismo [BusinessService]... Las instancias de DAO podrían ni siquiera declararse: el contenedor sabe crear una clase que no ha sido declarada (Ejemplo 06), pero crearía un objeto nuevo para cada solicitud;
- líneas 69–80: el controlador de guardia [jwt] (ejemplo 25). El token se lee de la cookie [rdvmedecins_jwt] (el nombre es una constante de [AuthService]) y lo verifica [AuthService::currentUser]. Una cookie que existe pero cuyo token ya no es válido se elimina. [Laravel] conserva el usuario encontrado durante toda la solicitud; mientras no haya encontrado ninguno (un visitante anónimo), llama a la función en cada solicitud, lo cual no tiene impacto: leer una cookie y, si es necesario, verificar una firma es muy rápido;
- Líneas 86–88: variables comunes a todas las vistas (Ejemplo 15): el usuario conectado (o [null]), para la barra de navegación, y el idioma de la solicitud. El patrón ['*'] coincide con todas las vistas: el composer se llama para cada una, incluidos los fragmentos y los componentes;
- Líneas 92–99: visualización de las órdenes SQL y de las transacciones en la consola (Ejemplo 28), si [DB_LOG=true]. [error_log] escribe en el log de errores de [PHP], es decir, con [php artisan serve], en la consola del servidor.
11.7.3. bootstrap/app.php
| <?php
// =========================================================================
// bootstrap/app.php: la construcción de la aplicación (véase el ejemplo 01):
// 1. las rutas (routes/web.php);
// 2. los middlewares: idioma, cookies, autenticación, roles;
// 3. las excepciones: cómo los errores se convierten en páginas HTML.
// Los servicios compartidos se declaran en app/Providers/AppServiceProvider.php.
// =========================================================================
use App\Auth\AuthService;
use App\Auth\InvalidSession;
use App\Http\Middleware\RequireRoles;
use App\Http\Middleware\SetLanguage;
use App\Http\Middleware\CheckRegistrationPass;
use App\Web\Flash;
use Illuminate\Auth\AuthenticationException;
use Illuminate\Auth\Middleware\Authenticate;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Http\Exceptions\HttpResponseException;
use Illuminate\Http\Request;
use Illuminate\Support\ViewErrorBag;
use Illuminate\Validation\ValidationException;
use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
return Application::configure(basePath: dirname(__DIR__))
->withRouting(web: __DIR__.'/../routes/web.php')
->withMiddleware(function (Middleware $middleware): void {
// el idioma de la solicitud: un middleware GLOBAL, ejecutado para todas las
// solicitudes, antes que los del grupo [web] (véase app/Http/Middleware/SetLanguage.php)
$middleware->append(SetLanguage::class);
// Laravel CIFRA todas las cookies que establece. Dos excepciones: el token
// JWT, que ya está firmado; el idioma, leído antes de descifrar las cookies
$middleware->encryptCookies(except: [AuthService::COOKIE, SetLanguage::COOKIE]);
// -------------------------------------------------------------------
// LA REGLA DE ACCESO: todas las rutas del grupo [web] exigen un usuario
// autenticado (middleware Authenticate, alias [auth]), excepto
// las que lo quitan explícitamente (withoutMiddleware, véase
// routes/web.php: inicio de sesión, creación de cuenta, elección de idioma).
// Es la regla "todo está prohibido salvo lo permitido": una ruta
// agregada después, que se hubiera olvidado de proteger, queda protegida de todos modos.
// -------------------------------------------------------------------
$middleware->web(append: [Authenticate::class]);
// un visitante no autenticado que solicita una página protegida: se le envía a la
// página de inicio de sesión. Si tenía una cookie de token, su token ya no es
// válido (expirado, falsificado): su sesión expiró, se lo decimos
$middleware->redirectGuestsTo(function (Request $request) {
if ($request->cookie(AuthService::COOKIE)) {
Flash::error('ERRORS.SESSION_EXPIRED');
}
return route('login');
});
// nombres cortos (alias) para los middlewares usados en routes/web.php
$middleware->alias([
'role' => RequireRoles::class,
'registration.pass' => CheckRegistrationPass::class,
]);
})
// -----------------------------------------------------------------------
// 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 con una sesión expirada;
// 2. un error HTTP: abort(400), abort(403) (rol insuficiente), 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 anomalía real): Laravel la escribe en el
// registro (storage/logs/laravel.log), con su pila de llamadas; en
// producción (APP_DEBUG=false), el usuario ve la página de error 500,
// nunca la pila de llamadas; en desarrollo, la página de depuración de Laravel.
// Una función render que devuelve null deja que Laravel maneje la excepción a su
// manera.
// -----------------------------------------------------------------------
->withExceptions(function (Exceptions $exceptions): void {
// la página de error. $errors: la variable de errores de entrada, que todas
// las vistas pueden leer, aún no existe si el error ocurrió
// antes del middleware que la crea (una página 405, por ejemplo)
$errorPage = function (int $code) {
$message = match ($code) {
400 => 'ERRORS.BAD_REQUEST',
403 => 'ERRORS.FORBIDDEN',
404 => 'ERRORS.NOT_FOUND',
419 => 'ERRORS.PAGE_EXPIRED',
default => 'ERRORS.SERVER_ERROR',
};
return response()->view('error', ['pageTitle' => 'ERROR_PAGE.TITLE', 'code' => $code,
'message' => $message, 'errors' => new ViewErrorBag], $code);
};
$exceptions->render(function (InvalidSession $e) {
Flash::error('ERRORS.SESSION_EXPIRED');
return redirect()->route('login')->withCookie(AuthService::clearingCookie());
});
$exceptions->render(fn (HttpExceptionInterface $e) => $errorPage($e->getStatusCode()));
$exceptions->render(function (Throwable $e) use ($errorPage) {
// estas excepciones tienen su propio manejo: redirección a la
// página de inicio de sesión (AuthenticationException), regreso al formulario con los
// errores de entrada (ValidationException)...
if (config('app.debug') || $e instanceof AuthenticationException
|| $e instanceof ValidationException || $e instanceof HttpResponseException) {
return null;
}
return $errorPage(500);
});
})
->create();
|
El archivo que construye la aplicación (Ejemplo 01). Contiene todo lo relacionado con el manejo de solicitudes: rutas, middleware y excepciones.
- línea 28: las rutas ([routes/web.php], que se explican más adelante);
- línea 33: el idioma de la solicitud lo establece un middleware global (ejemplo 24), que se ejecuta para todas las solicitudes, incluso antes del enrutamiento;
- línea 37: [Laravel] cifra todas las cookies (Ejemplo 20), excepto las excluidas: el token JWT, que ya está firmado (Ejemplo 25), y el idioma. La cookie del idioma la lee un middleware global, que se ejecuta antes del middleware [EncryptCookies] del grupo [web]: por lo tanto, debe poder leerse sin descifrar. ¿Por qué usar un middleware global en lugar de uno del grupo [web]? Para que incluso las solicitudes que no llegan a ninguna ruta (una página 405) muestren su página de error en el idioma correcto;
- Línea 47: la regla de acceso de la aplicación. El middleware [Authenticate] (el alias [auth] del Ejemplo 25) se agrega al grupo [web], es decir, a todas las rutas. Una ruta pública (la página de inicio de sesión, la creación de cuenta, la selección de idioma) debe quitárselo explícitamente mediante [withoutMiddleware] (dentro de [routes/web.php]). Esto sigue la regla “todo está prohibido salvo lo permitido explícitamente”: una ruta agregada más tarde, aunque olvide protegerla, queda protegida automáticamente. El error contrario (una ruta pública que olvidó abrir) se nota de inmediato; el error de una página protegida olvidada se nota mucho menos;
- Líneas 52–57: un visitante no autenticado que solicita una página protegida es redirigido a la página de inicio de sesión. Si el navegador del visitante envió una cookie de token, significa que ese token ya no es válido (venció o fue manipulado): se avisa al visitante mediante un mensaje emergente ([Flash::error], que se explica más adelante). [redirectGuestsTo] acepta una URL, o una función que recibe la solicitud y devuelve la URL;
- Líneas 60–63: alias (nombres cortos) para el middleware de rutas: [role] y [registration.pass], usados en [routes/web.php].
Las líneas 80–113 convierten los errores en páginas HTML (Ejemplo 24):
- Líneas 84–91: la función que genera la página de error para un código HTTP: la vista [error], el código, la clave del mensaje y el código de respuesta HTTP. Un punto sutil: las vistas de la aplicación leen la variable [$errors] (errores de entrada, Ejemplo 19), que el middleware [ShareErrorsFromSession] del grupo [web] comparte con todas las vistas. Un error que ocurre antes de este middleware (un método HTTP no admitido, 405, lo detecta el enrutador) llegaría a una vista sin [$errors]: por eso se le proporciona uno vacío ([new ViewErrorBag]);
- líneas 96–99: la excepción [InvalidSession] (la cuenta del token ya no existe; vea más abajo): regreso a la página de inicio de sesión, con la cookie del token borrada, y el mensaje “sesión expirada”;
- línea 101: todos los errores HTTP ([abort(403)], [abort(404)], una ruta desconocida, un método no admitido, un token anti-CSRF ausente o inválido (419, ejemplo 18)...) se convierten en la página de error, junto con sus códigos;
- Líneas 103–112: cualquier otra excepción es una verdadera anomalía (la base de datos es inaccesible, un error de programación...). [Laravel] siempre la registra en el log [storage/logs/laravel.log], junto con su pila de llamadas. En producción ([APP_DEBUG=false]), el usuario ve la página de error 500, nunca la pila de llamadas, que revelaría el código de la aplicación a un atacante; en desarrollo, la función devuelve [null]: [Laravel] muestra su página de depuración. Nota: [Throwable] captura todas las excepciones, incluidas las que [Laravel] maneja por sí mismo, y estas deben dejársele a él: [AuthenticationException] (un visitante no autenticado, redirigido a [/login]), [ValidationException] (una entrada inválida, devuelta al formulario, ejemplo 19), [HttpResponseException] (una excepción que lleva su propia respuesta). Las funciones de renderizado se prueban en el orden en que se declaran: los errores HTTP ya fueron manejados por la anterior.
11.8. Los modelos
Los modelos [Eloquent] (ejemplo 28): una clase por tabla.
11.8.1. app/Models/Role.php
| <?php
// app/Models/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\Models;
enum Role: string
{
case ADMIN = 'ADMIN';
case DOCTOR = 'DOCTOR';
case USER = 'USER';
}
|
Los tres roles, en forma de enumeración ([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 valor asociado: cada caso tiene un valor, en este caso la cadena almacenada en la base de datos. [Role::ADMIN->value] es igual a ['ADMIN']; [Role::from('ADMIN')] devuelve el caso correspondiente (y lanza una excepción para un valor desconocido); [Role::tryFrom(...)] devuelve [null] en ese caso.
11.8.2. app/Models/User.php
| <?php
// app/Models/User.php: un usuario autorizado a iniciar sesión (tabla [users]).
// Cada médico y cada cliente posee SU cuenta (columna [user] de las tablas
// [doctors] y [clients], véase Person.php).
//
// restricción SQL de unicidad: 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 app/Business/BusinessService.php).
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
protected $table = 'users';
// la tabla no tiene las columnas created_at / updated_at que Eloquent gestiona por omisión
public $timestamps = false;
// las columnas que pueden asignarse de forma masiva (User::create([...]), new User([...]))
protected $fillable = ['login', 'password', 'name', 'role'];
// la contraseña con HASH (bcrypt) nunca sale del objeto si este se convierte en un
// arreglo o en JSON
protected $hidden = ['password'];
// las conversiones: la columna [role] (un texto) se convierte en un Role, y viceversa
protected function casts(): array
{
return ['role' => Role::class, 'version' => 'integer'];
}
}
|
- línea 16: la tabla. [Eloquent] la habría deducido (el nombre de la clase, en minúsculas, en plural inglés: [users]); aquí la escribimos en todos lados para mayor claridad;
- Línea 19: ninguna tabla de la base de datos tiene las columnas [created_at] y [updated_at], que [Eloquent] rellena de forma predeterminada (Ejemplo 28);
- línea 22: las columnas que pueden rellenarse en bloque con [User::create([...])] (ejemplo 28);
- línea 26: el hash de la contraseña no aparecerá si el objeto se convierte en un arreglo o en JSON ([$user->toArray()]): una precaución;
- Líneas 29–32: las conversiones (Ejemplo 28): la columna [role] (texto) se convierte en [Role] al leerse, y viceversa al escribirse: [$user->role] es [Role], nunca una cadena. La columna [version] se lee como entero: el controlador [PDO] de [MySQL] puede devolver los números como cadenas, y la comparación estricta de la capa de negocio [$version !== $person->version] fallaría.
11.8.3. app/Models/Person.php
| <?php
// app/Models/Person.php: lo que tienen en común los médicos (tabla [doctors]) y
// los clientes (tabla [clients]): un tratamiento, 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 creamos una "Person"), de la cual
// Doctor y Client heredan; cada una solo especifica el nombre de su tabla.
//
// Atención: ¡[Client] aquí designa a un PACIENTE del consultorio médico, no a un cliente
// HTTP! Es el vocabulario del dominio de negocio original, conservado tal cual.
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
abstract class Person extends Model
{
public $timestamps = false;
// [user] es el nombre de la columna de clave externa -> users(id): un simple
// número, el id de la cuenta ($doctor->user)
protected $fillable = ['title', 'last_name', 'first_name', 'user'];
protected function casts(): array
{
return ['user' => 'integer', 'version' => 'integer'];
}
// -----------------------------------------------------------------------
// La RELACIÓN con la cuenta de usuario: una persona tiene UNA cuenta, designada
// por la clave externa [user]. belongsTo: "pertenece a": la clave externa
// está en ESTA tabla. $doctor->account es entonces un objeto User, leído de la base de datos
// en el primer acceso, o de inmediato con la consulta con with('account') (véase app/Dao).
// La relación no puede llamarse [user]: este nombre ya es el de la
// columna, y $doctor->user designa la columna.
// -----------------------------------------------------------------------
public function account(): BelongsTo
{
return $this->belongsTo(User::class, 'user');
}
// "Mme Alice DURAND"
public function label(): string
{
return "{$this->title} {$this->first_name} {$this->last_name}";
}
}
|
Las tablas [doctors] y [clients] tienen las mismas columnas. Su descripción común 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 y solo especifican el nombre de su tabla.
- Línea 24: [user] es la columna de la clave externa; [$doctor->user] es un simple número, el ID de la cuenta;
- Líneas 39–42: la relación con la cuenta. Una relación [Eloquent] es un método que describe el vínculo entre dos tablas; [belongsTo] (“pertenece a”) describe una clave externa en esta tabla: [belongsTo(User::class, 'user')] especifica que la columna [user] contiene el ID de un [User]. Se usa como propiedad: [$doctor->account] es el objeto [User]. [Eloquent] la lee de la base de datos en el primer acceso (esto se llama *carga diferida*), o en cuanto la consulta que recupera al médico la solicita (si es necesario; *carga anticipada*, vea [with('account')] en la capa DAO). La relación no puede llamarse [user]: [$doctor->user] ya se refiere a la columna, y [Eloquent] da prioridad a las columnas;
- Líneas 45–48: el nombre de una persona, “Sra. Alice DURAND”, usado por todas las páginas. En una cadena delimitada por comillas, [{$this->title}] inserta el valor de una propiedad.
11.8.4. app/Models/Doctor.php y Client.php
| <?php
// app/Models/Doctor.php: un médico (tabla [doctors]).
// Restricción SQL de unicidad: unq_doctors_first_name_last_name (dos médicos no pueden
// tener el mismo nombre y apellido).
namespace App\Models;
class Doctor extends Person
{
protected $table = 'doctors';
}
|
| <?php
// app/Models/Client.php: un cliente, es decir, un PACIENTE (tabla [clients]).
// Restricción SQL de unicidad: unq_clients_first_name_last_name.
namespace App\Models;
class Client extends Person
{
protected $table = 'clients';
}
|
Un [Client] es un paciente del consultorio, no un cliente HTTP: es el vocabulario original del dominio de negocio, conservado en todas las versiones de la aplicación.
11.8.5. app/Models/Slot.php
| <?php
// app/Models/Slot.php: un horario (franja) de un médico (tabla [slots]):
// 8:00 - 8:20, etc.
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
class Slot extends Model
{
protected $table = 'slots';
public $timestamps = false;
protected function casts(): array
{
return ['doctor_id' => 'integer', 'start_hour' => 'integer', 'start_minute' => 'integer',
'end_hour' => 'integer', 'end_minute' => 'integer', 'version' => 'integer'];
}
// varios horarios para el mismo médico: la clave externa [doctor_id]
public function doctor(): BelongsTo
{
return $this->belongsTo(Doctor::class, 'doctor_id');
}
// "8:00 - 8:20"; sprintf('%02d'): "8:05" en lugar de "8:5"
public function time(): string
{
return sprintf('%d:%02d - %d:%02d', $this->start_hour, $this->start_minute, $this->end_hour, $this->end_minute);
}
}
|
- líneas 23–26: la relación con el médico para la franja horaria de la cita (clave externa [doctor_id]);
- líneas 29–32: la franja horaria, “8:00 – 8:20”. El formato [%02d] de [sprintf] escribe un entero con un mínimo de dos dígitos, rellenado con ceros: [8:05] en lugar de [8:5].
11.8.6. app/Models/Appointment.php
| <?php
// app/Models/Appointment.php: una cita (tabla [appointments]): un cliente, en un horario, en un
// día dado.
// Restricción SQL de unicidad: unq1_appointments (day, slot_id): un horario se reserva
// una sola vez por día. Creada por el script SQL, reconocida por su nombre en la
// capa de negocio.
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
class Appointment extends Model
{
protected $table = 'appointments';
public $timestamps = false;
protected $fillable = ['day', 'slot_id', 'client_id'];
// immutable_date: la columna [day] (tipo SQL DATE) se convierte en una fecha
// CarbonImmutable, a medianoche; se escribe en la base de datos en formato aaaa-mm-dd
protected function casts(): array
{
return ['day' => 'immutable_date', 'slot_id' => 'integer', 'client_id' => 'integer',
'version' => 'integer'];
}
public function client(): BelongsTo
{
return $this->belongsTo(Client::class, 'client_id');
}
public function slot(): BelongsTo
{
return $this->belongsTo(Slot::class, 'slot_id');
}
}
|
- Líneas 23–27: la columna [day] (tipo SQL [DATE]) se convierte a [CarbonImmutable], la clase de fecha de [Laravel] (ejemplo 12), a medianoche. Inmutable: sus métodos nunca modifican el objeto; devuelven uno nuevo ([$day->addDay()] devuelve el día siguiente, [$day] permanece sin cambios). Toda la aplicación maneja 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 29–34: dos relaciones, una con el cliente y otra con la franja horaria de la cita.
11.9. El dominio: el calendario
11.9.1. app/Domain/DoctorDaySlot.php y DoctorDaySchedule.php
| <?php
// app/Domain/DoctorDaySlot.php: un horario, y la cita posiblemente
// reservada en ese horario en un día dado (null si el horario está libre).
// Un objeto de "negocio" calculado, que no corresponde a ninguna tabla.
//
// readonly: las propiedades las fija el constructor de una vez por todas,
// justo lo que hace falta para un objeto calculado, que nadie modifica después.
namespace App\Domain;
use App\Models\Slot;
use App\Models\Appointment;
readonly class DoctorDaySlot
{
public function __construct(
public Slot $slot,
public ?Appointment $appointment,
) {
}
}
|
| <?php
// app/Domain/DoctorDaySchedule.php: la agenda completa de un médico para un
// día dado, la lista de sus horarios, cada uno libre u ocupado. Calculada por
// BusinessService::getDoctorDaySchedule, convertida en una tabla HTML por
// ScheduleController.
namespace App\Domain;
use App\Models\Doctor;
use Carbon\CarbonImmutable;
readonly class DoctorDaySchedule
{
/** @param list<DoctorDaySlot> $doctorDaySlots */
public function __construct(
public Doctor $doctor,
public CarbonImmutable $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 sus franjas horarias disponibles. Son clases de tipo [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 transacciones; la capa de negocio los llama dentro de sus propias transacciones. Usan el constructor de consultas de [Eloquent]: [where], [orderBy], [first], [get]... ; los valores de estas consultas se convierten en parámetros de la consulta SQL: no es posible ninguna inyección SQL.
11.10.1. app/Dao/PersonDao.php
| <?php
// app/Dao/PersonDao.php: la capa DAO común a los médicos y a 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->model es la clase Eloquent correspondiente
// (Doctor::class o Client::class): $this->model::query() inicia una consulta
// sobre SU tabla.
//
// Las consultas se escriben con el constructor de consultas de Eloquent (where,
// orderBy...); Eloquent las traduce a SQL. Los valores (nombre, apellido...)
// se convierten en PARÁMETROS de la consulta: 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\Models\Person;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Support\Facades\DB;
abstract class PersonDao
{
/** @param class-string<Person> $model */
public function __construct(protected string $model)
{
}
// una consulta sobre la tabla de la clase, con la cuenta de usuario incluida
protected function query(): Builder
{
// with('account'): carga TAMBIÉN las cuentas, con una segunda consulta
// (SELECT * FROM users WHERE id IN (...)). Sin ella, cada acceso a
// $person->account provocaría su propia consulta
return $this->model::query()->with('account');
}
// lista ordenada por apellido y luego por nombre
public function list(): Collection
{
return $this->query()->orderBy('last_name')->orderBy('first_name')->get();
}
// una persona y su cuenta; null si no existe
public function read(int $id): ?Person
{
return $this->query()->find($id);
}
// la persona cuya cuenta de usuario es [$userId]
public function readByUser(int $userId): ?Person
{
return $this->query()->where('user', $userId)->first();
}
// la persona que tiene este nombre y apellido, si existe. La comparación la
// hace MySQL, por lo tanto con la collation de la base de datos (utf8mb4_unicode_ci: sin
// distinguir mayúsculas ni acentos): exactamente la misma regla que
// la de la restricción SQL de unicidad
public function namesake(string $firstName, string $lastName): ?Person
{
return $this->model::query()->where('first_name', $firstName)->where('last_name', $lastName)->first();
}
// INSERT: la base de datos genera el id, que Eloquent almacena en el objeto
public function add(array $columns): Person
{
return $this->model::query()->create($columns);
}
// -----------------------------------------------------------------------
// el BLOQUEO OPTIMISTA (véase el ejemplo 28):
// UPDATE ... SET ..., version = version + 1 WHERE id = ? AND version = ?
// devuelve el número de filas modificadas: 0 si la fila fue modificada (o
// eliminada) desde que se leyó
// -----------------------------------------------------------------------
public function edit(int $id, int $version, array $columns): int
{
return $this->model::query()->whereKey($id)->where('version', $version)
->update([...$columns, 'version' => DB::raw('version + 1')]);
}
// un DELETE enviado directamente a la base de datos, sin leer antes a la persona
public function remove(int $id): void
{
$this->model::query()->whereKey($id)->delete();
}
}
|
La capa DAO común a médicos y clientes, definida una sola vez en una clase abstracta.
- Línea 25: la clase [Eloquent] correspondiente, [Doctor::class], o [Client::class] (una cadena, el nombre completo de la clase). El comentario [@param class-string<Person>] lo aclara para los desarrolladores. [$this->model::query()] llama al método estático [query] de esa clase: [PHP] acepta una variable en lugar de un nombre de clase. [query()] inicia una consulta sobre la tabla del modelo; [Doctor::where(...)] es un atajo para ello;
- Líneas 30–36: una consulta que también carga las cuentas de las personas recuperadas: [with('account')] solicita la precarga de la relación [account]. [Eloquent] ejecuta entonces dos consultas: una para las personas, seguida de otra para todas sus cuentas a la vez ([select * from users where id in (2, 3, 4)]; vea la salida de la consola más arriba). Sin esto, la lista de médicos que muestra el administrador desencadenaría una consulta por médico en el primer acceso a [$doctor->account->login]: es el llamado problema de las “N + 1 consultas”. Otra razón: las listas de médicos y clientes se guardan en la caché ([ApplicationModel], que se explica más adelante); los objetos recuperados de la caché deben estar completos;
- líneas 39–42: la lista, ordenada por apellido y luego por nombre; [get()] devuelve una [Collection] y de [Eloquent] (ejemplo 28);
- líneas 45–48: [find] lee una fila por su clave primaria; [null] si no existe;
- líneas 51–54: la persona cuya cuenta es [$userId]: [first()] devuelve la primera fila, o [null];
- líneas 60–63: la persona con el mismo nombre y apellido. La comparación la realiza [MySQL], con la collation de la base de datos: sin distinguir mayúsculas ni acentos, exactamente como en la restricción de unicidad (ejemplo 28);
- líneas 66–69: [create] inserta una fila (columnas de [$fillable]) y devuelve el objeto, junto con el ID generado por la base de datos;
- líneas 77–81: el bloqueo optimista del Ejemplo 28: [UPDATE ... SET ..., version = version + 1 WHERE id = ? AND version = ?]. El método devuelve el número de filas modificadas: 0 si la fila ha sido modificada o eliminada desde que se leyó. [[...$columns, 'version' => ...]] crea un arreglo que contiene los elementos de [$columns], más la versión (el operador [...] desempaqueta un arreglo). [whereKey($id)]: la condición sobre la clave primaria;
- líneas 84–87: un [DELETE] enviado directamente a la base de datos, sin leer antes la fila.
11.10.2. app/Dao/DoctorDao.php y ClientDao.php
| <?php
// app/Dao/DoctorDao.php: el DAO de los médicos: todo se hereda de PersonDao.
namespace App\Dao;
use App\Models\Doctor;
class DoctorDao extends PersonDao
{
public function __construct()
{
parent::__construct(Doctor::class);
}
}
|
Todo se hereda: el constructor solo indica la clase [Eloquent] a [PersonDao] ([parent::__construct] llama al constructor de la clase padre).
| <?php
// app/Dao/ClientDao.php: el DAO de los clientes: el de las personas, más un
// método de bloqueo.
namespace App\Dao;
use App\Models\Client;
class ClientDao extends PersonDao
{
public function __construct()
{
parent::__construct(Client::class);
}
// -----------------------------------------------------------------------
// pone un BLOQUEO sobre la fila de un cliente hasta el final de la
// transacción en curso (SELECT ... FOR UPDATE), y devuelve su id (null si el cliente
// no existe). Una segunda transacción que solicite el mismo bloqueo ESPERA a que
// la primera termine.
// Se usa para reservar (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
{
return Client::query()->whereKey($id)->lockForUpdate()->value('id');
}
}
|
- Líneas 25–28: un bloqueo pesimista, el otro tipo de bloqueo. [lockForUpdate()] agrega [FOR UPDATE] a la consulta: [SELECT id FROM clients WHERE id = ? FOR UPDATE]. La fila leída queda bloqueada hasta el final de la transacción en curso: otra transacción que solicite el mismo bloqueo espera a que la primera termine. [value('id')] devuelve el valor de una columna de la primera fila ([null] si no hay ninguna). Veremos, en la capa de negocio, para qué sirve este bloqueo.
11.10.3. app/Dao/SlotDao.php
| <?php
// app/Dao/SlotDao.php: capa DAO de los horarios.
namespace App\Dao;
use App\Models\Slot;
use Illuminate\Database\Eloquent\Collection;
class SlotDao
{
// un horario y su médico
public function read(int $id): ?Slot
{
return Slot::with('doctor')->find($id);
}
// los horarios de un médico, en orden cronológico
public function listByDoctor(int $doctorId): Collection
{
return Slot::where('doctor_id', $doctorId)->orderBy('start_hour')->orderBy('start_minute')->get();
}
// elimina todos los horarios de un médico (eliminación de un médico):
// DELETE FROM slots WHERE doctor_id = ?
public function deleteByDoctor(int $doctorId): void
{
Slot::where('doctor_id', $doctorId)->delete();
}
}
|
[Slot::with('doctor')->find($id)]: una franja horaria y su médico (precargado); [Slot::where(...)->delete()]: un [DELETE] que abarca todas las filas que cumplen la condición.
11.10.4. app/Dao/AppointmentDao.php
| <?php
// app/Dao/AppointmentDao.php: capa DAO de las citas.
//
// La tabla [appointments] no hace referencia directa al médico: pasamos por el horario.
// whereHas('slot', ...): las citas cuyo horario cumple una condición
// (Eloquent la escribe en SQL con una subconsulta EXISTS).
namespace App\Dao;
use App\Models\Appointment;
use Carbon\CarbonImmutable;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
class AppointmentDao
{
// una cita, su cliente y su horario
public function read(int $id): ?Appointment
{
return Appointment::with(['client', 'slot'])->find($id);
}
// las citas de un médico en un día dado, con su cliente
public function doctorDayAppointments(int $doctorId, CarbonImmutable $day): Collection
{
return Appointment::with('client')
->where('day', $day->toDateString())
->whereHas('slot', fn (Builder $q) => $q->where('doctor_id', $doctorId))
->get();
}
// -----------------------------------------------------------------------
// las citas de un cliente a partir del día [$since] (incluido), en orden
// cronológico, con el horario Y el médico de ese horario ('slot.doctor':
// una relación de la relación). El orden usa columnas de la tabla
// [slots]: hace falta un JOIN SQL; select('appointments.*'): solo conservamos las
// columnas de [appointments] para llenar los objetos Appointment
// -----------------------------------------------------------------------
public function clientUpcomingAppointments(int $clientId, CarbonImmutable $since): Collection
{
return Appointment::with('slot.doctor')
->select('appointments.*')
->join('slots', 'slots.id', '=', 'appointments.slot_id')
->where('appointments.client_id', $clientId)
->where('appointments.day', '>=', $since->toDateString())
->orderBy('appointments.day')->orderBy('slots.start_hour')->orderBy('slots.start_minute')
->get();
}
// número de citas de un cliente a partir del día [$since] (incluido)
public function countClientUpcoming(int $clientId, CarbonImmutable $since): int
{
return Appointment::where('client_id', $clientId)->where('day', '>=', $since->toDateString())->count();
}
// número de citas (pasadas o futuras) de un médico
public function countByDoctor(int $doctorId): int
{
return Appointment::whereHas('slot', fn (Builder $q) => $q->where('doctor_id', $doctorId))->count();
}
public function add(CarbonImmutable $day, int $slotId, int $clientId): Appointment
{
return Appointment::create(['day' => $day, 'slot_id' => $slotId, 'client_id' => $clientId]);
}
// DELETE FROM appointments WHERE id = ?
public function remove(int $id): void
{
Appointment::whereKey($id)->delete();
}
// elimina TODAS las citas (pasadas y futuras) de un cliente
public function deleteByClient(int $clientId): void
{
Appointment::where('client_id', $clientId)->delete();
}
}
|
La tabla [appointments] no referencia directamente al médico: pasa por la franja horaria.
- Líneas 24–30: las citas de un médico en un día determinado. [whereHas('slot', function)] retiene las citas para las cuales la relación [slot] cumple la condición definida por la función: [Eloquent] lo traduce en una subconsulta [EXISTS] (vea la salida de la consola más arriba). [fn (Builder $q) => ...] es una función flecha (ejemplo 03); recibe la consulta sobre la tabla [slots]. La fecha se compara en su formato [yyyy-mm-dd] ([toDateString()]), que es el mismo de las columnas [DATE];
- Líneas 39–48: las próximas citas de un cliente, junto con su franja horaria y el médico asignado a esa franja: [with('slot.doctor')] carga una relación a partir de la relación. El orden se basa en la hora de la franja horaria, una columna de la tabla [slots]: se requiere una unión ([join]). [select('appointments.*')] retiene solo las columnas de la tabla [appointments] para poblar los objetos [Appointment] (de lo contrario, el ID de la franja horaria sobrescribiría el ID de la cita: ambas columnas se llaman [id]);
- líneas 51–54: [count()] ejecuta un [SELECT COUNT(*)];
- líneas 62–65: el objeto [CarbonImmutable] se escribe en la base de datos en el formato de la columna, mediante la conversión declarada por el modelo.
11.10.5. app/Dao/UserDao.php
| <?php
// app/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 app/Business.
namespace App\Dao;
use App\Models\Role;
use App\Models\User;
use Illuminate\Support\Facades\DB;
class UserDao
{
// null si ningún usuario tiene este login
public function readByLogin(string $login): ?User
{
return User::where('login', $login)->first();
}
public function add(string $login, string $hashed, string $name, Role $role): User
{
return User::create(['login' => $login, 'password' => $hashed, 'name' => $name, 'role' => $role]);
}
// bloqueo optimista, como PersonDao::edit
public function edit(int $id, int $version, array $columns): int
{
return User::whereKey($id)->where('version', $version)
->update([...$columns, 'version' => DB::raw('version + 1')]);
}
public function remove(int $id): void
{
User::whereKey($id)->delete();
}
}
|
Cuentas: consulta por nombre de usuario, alta, modificación con bloqueo optimista y eliminación.
11.11. La capa de negocio
La capa de negocio reúne las reglas de negocio y las transacciones (Ejemplo 28). Se describe mediante una interfaz y la implementan dos clases: [BusinessService], la capa de negocio propiamente dicha, y [ApplicationModel], la caché de la capa web (que se explica más adelante).
11.11.1. app/Business/Dates.php
| <?php
// app/Business/Dates.php: la fecha actual. La usan las REGLAS DE NEGOCIO (ninguna
// reserva en el pasado, una sola cita FUTURA por paciente): por lo tanto
// vive en la capa de negocio. La capa web la reutiliza.
namespace App\Business;
use Carbon\CarbonImmutable;
class Dates
{
// hoy a medianoche, en la zona horaria de la aplicación (config/app.php)
public static function today(): CarbonImmutable
{
return CarbonImmutable::today();
}
}
|
La fecha actual a medianoche en la zona horaria de la aplicación ([config/app.php]). Se usa en las reglas de negocio (no se permiten reservas en el pasado, solo una cita próxima): por eso reside en la capa de negocio. Un método estático ([static]) se llama sin crear un objeto: [Dates::today()].
11.11.2. app/Business/BusinessException.php
| <?php
// app/Business/BusinessException.php: la excepción lanzada por la capa de negocio cuando se viola 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 lang/*.json).
//
// Una BusinessException no es una anomalía: es una respuesta normal ("este login
// ya está en uso"), mostrada 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 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 log junto con la nueva).
11.11.3. app/Business/PersonData.php
| <?php
// app/Business/PersonData.php: los datos ingresados en un formulario de "médico" o de "cliente",
// tal como la capa web los transmite 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 omisión el apellido en minúsculas
// modificación: opcional, el login no cambia si está ausente
public ?string $login = null,
// creación: opcional, por omisión 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,
) {
}
}
|
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. app/Business/Business.php
| <?php
// app/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 (la caché
// de la capa web) la implementan ambas; 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...).
namespace App\Business;
use App\Domain\DoctorDaySchedule;
use App\Models\Client;
use App\Models\Slot;
use App\Models\Doctor;
use App\Models\Appointment;
use Carbon\CarbonImmutable;
use Illuminate\Database\Eloquent\Collection;
interface Business
{
// - lecturas
public function getAllClients(): Collection;
public function getAllDoctors(): Collection;
public function getAllSlots(int $doctorId): Collection;
public function getDoctorDayAppointments(int $doctorId, CarbonImmutable $day): Collection;
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, CarbonImmutable $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
public function getClientUpcomingAppointments(int $clientId): Collection;
// - citas (ADMIN, DOCTOR, USER)
// lanza una BusinessException si:
// - el día ya pasó ("ERRORS.PAST_DATE");
// - el paciente ya tiene una cita futura ("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
// - el horario ya está ocupado ese día ("ERRORS.SLOT_ALREADY_BOOKED").
public function addAppointment(CarbonImmutable $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 por 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 objetos [Eloquent] o [Collection]; [?Client]: un cliente, o [null] si no existe. Los comentarios especifican las reglas de cada operación de escritura y las claves de los objetos [BusinessException] que puede crear.
11.11.5. app/Business/Descriptor.php
| <?php
// app/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 con un descriptor.
namespace App\Business;
use App\Dao\PersonDao;
use App\Models\Role;
use Closure;
readonly class Descriptor
{
public function __construct(
public PersonDao $dao,
public Role $role, // DOCTOR o USER
public string $notFoundKey, // mensaje si la persona no existe
public string $alreadyExistsKey, // mensaje si ya existen el mismo 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
// hacen referencia a ella mediante una clave externa); recibe su id
public ?Closure $beforeDelete,
) {
}
}
|
Médicos y clientes siguen las mismas reglas de gestión, con algunas diferencias menores: el DAO, el rol de la cuenta, 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 lo que referencia a la persona.
11.11.6. app/Business/BusinessService.php
| <?php
// =========================================================================
// app/Business/BusinessService.php: la implementación de la capa de negocio.
//
// La gestión de médicos y clientes obedece a tres reglas de negocio:
//
// 1. una persona (médico o cliente) y su cuenta de usuario van SIEMPRE
// juntas: se crean, se modifican y se eliminan juntas, en la misma
// TRANSACCIÓN: o todo tiene éxito, 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 la reserva, sea cual sea el rol de quien
// reserva (ADMIN, DOCTOR o el propio paciente):
// 4. ninguna cita en el pasado;
// 5. un paciente tiene UNA SOLA cita futura 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 con un descriptor
// que indica con 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 informados por 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\Models\Client;
use App\Models\Slot;
use App\Models\Doctor;
use App\Models\Person;
use App\Models\Role;
use App\Models\Appointment;
use Carbon\CarbonImmutable;
use Closure;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\QueryException;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Str;
class BusinessService implements Business
{
// -----------------------------------------------------------------------
// Errores de la base de datos -> BusinessException
//
// Cuando una restricción UNIQUE rechaza una escritura, Laravel lanza una
// QueryException, 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 el nombre de la tabla, MariaDB no). Por eso
// el script SQL da NOMBRE a 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;
// todas las dependencias las proporciona el contenedor de servicios de Laravel
// (inyección de dependencias, véase el ejemplo 06)
public function __construct(
private DoctorDao $doctors,
private ClientDao $clients,
private SlotDao $slots,
private AppointmentDao $appointments,
private UserDao $users,
) {
$this->doctor = new Descriptor(
dao: $doctors,
role: Role::DOCTOR,
notFoundKey: 'ERRORS.DOCTOR_NOT_FOUND',
alreadyExistsKey: 'ERRORS.DOCTOR_ALREADY_EXISTS',
// $appointments->countByDoctor(...): el método mismo, como una 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,
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(): Collection
{
return $this->clients->list();
}
public function getAllDoctors(): Collection
{
return $this->doctors->list();
}
public function getAllSlots(int $doctorId): Collection
{
return $this->slots->listByDoctor($doctorId);
}
public function getDoctorDayAppointments(int $doctorId, CarbonImmutable $day): Collection
{
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): Collection
{
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, CarbonImmutable $day): ?DoctorDaySchedule
{
$doctor = $this->getDoctorById($doctorId);
if ($doctor === null) {
return null;
}
// n.º de horario -> cita reservada en ese horario (keyBy: una colección
// indexada por el valor de una columna)
$bookings = $this->getDoctorDayAppointments($doctorId, $day)->keyBy('slot_id');
$doctorDaySlots = $this->getAllSlots($doctorId)
->map(fn (Slot $slot) => new DoctorDaySlot($slot, $bookings->get($slot->id)))
->all();
return new DoctorDaySchedule($doctor, $day, $doctorDaySlots);
}
// =======================================================================
// citas
// =======================================================================
// -----------------------------------------------------------------------
// reserva de una cita, 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 a que termine la primera, y entonces ve
// la cita que esta acaba de crear;
// 3. una sola cita futura 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(CarbonImmutable $day, Slot $slot, Client $client): Appointment
{
return $this->transaction(function () use ($day, $slot, $client) {
$today = Dates::today();
if ($day->lt($today)) {
throw new BusinessException('ERRORS.PAST_DATE');
}
$patientId = $this->clients->lock($client->id)
?? throw new BusinessException('ERRORS.PATIENT_NOT_FOUND');
if ($this->appointments->countClientUpcoming($patientId, $today) > 0) {
throw new BusinessException('ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT');
}
return $this->appointments->add($day, $slot->id, $patientId);
});
}
public function deleteAppointment(Appointment $appointment): void
{
$this->transaction(fn () => $this->appointments->remove($appointment->id));
}
// =======================================================================
// doctores y clientes - los métodos públicos delegan en los métodos privados
// comunes, con el descriptor correcto
// =======================================================================
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, LUEGO la persona (que la referencia), en
// UNA sola transacción.
// -----------------------------------------------------------------------
private function addPerson(Descriptor $d, PersonData $data): Person
{
$lastName = Str::upper(trim($data->lastName));
$firstName = trim($data->firstName);
// las reglas de la base de datos dbrdvmedecins2: login = apellido en minúsculas,
// contraseña = login, salvo que el ADMIN (o el paciente) haya escrito otros
$login = Str::lower($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::make: el hash bcrypt de la contraseña (ver config/hashing.php)
$user = $this->users->add($login, Hash::make($password), "$firstName $lastName", $d->role);
$person = $d->dao->add(['title' => $data->title, 'last_name' => $lastName,
'first_name' => $firstName, 'user' => $user->id]);
// setRelation: la cuenta, ya en memoria, se almacena en la relación
// [account] de la persona (no hace falta volver a leerla de la base de datos)
return $person->setRelation('account', $user);
});
}
// -----------------------------------------------------------------------
// modificación: la persona Y su cuenta (el nombre mostrado "first name LAST NAME" debe
// seguir el cambio; el login y la contraseña solo cambian si se escribieron).
// -----------------------------------------------------------------------
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 modificó este registro entretanto: se rechaza
// en lugar de sobrescribir silenciosamente sus modificaciones
$version = $data->version ?? $person->version;
if ($version !== $person->version) {
throw new BusinessException('ERRORS.CONCURRENT_UPDATE');
}
$lastName = Str::upper(trim($data->lastName));
$firstName = trim($data->firstName);
$this->checkPersonUnique($d, $firstName, $lastName, $id);
// la persona: UPDATE ... WHERE id = ? AND version = ? (si el registro
// fue modificado DESPUÉS de la lectura anterior, no se modifica ninguna fila)
if ($d->dao->edit($id, $version, ['title' => $data->title, 'last_name' => $lastName,
'first_name' => $firstName]) === 0) {
throw new BusinessException('ERRORS.CONCURRENT_UPDATE');
}
// su cuenta: el nombre mostrado y, si se escribieron, el login y la
// contraseña
$account = $person->account;
$columns = ['name' => "$firstName $lastName"];
$login = $data->login ? Str::lower($data->login) : null;
if ($login !== null && $login !== $account->login) {
$this->checkLoginFree($login);
$columns['login'] = $login;
}
if ($data->password) {
$columns['password'] = Hash::make($data->password);
}
if ($this->users->edit($account->id, $account->version, $columns) === 0) {
throw new BusinessException('ERRORS.CONCURRENT_UPDATE');
}
// la persona leída de nuevo: sus nuevos valores, sus nuevas versiones
return $d->dao->read($id);
});
}
// -----------------------------------------------------------------------
// eliminación, en UNA sola transacción, en el orden impuesto por las claves
// externas:
// 1. posible rechazo si quedan citas (médico);
// 2. lo que referencia a la persona (franjas de un médico, citas de un
// cliente);
// 3. la persona (que referencia su cuenta);
// 4. su cuenta.
// -----------------------------------------------------------------------
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($id);
$this->users->remove($person->user);
});
}
// rechaza nombres y apellidos ya usados por OTRA persona del mismo tipo
// ($currentId: la persona que se modifica, que obviamente 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->id !== $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 (DB::transaction, ver ejemplo 28):
// COMMIT si la función termina normalmente; si de ella sale una excepción
// (incluida BusinessException), ROLLBACK: no se escribe nada.
//
// Las verificaciones "free login" y "unique first + last names" 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) en el mismo instante: en este
// caso poco frecuente, es una restricción SQL de unicidad la que rechaza la segunda escritura. Por
// eso interceptamos los errores de la base de datos ALREDEDOR de la transacción, para
// traducirlos a la misma BusinessException. Cualquier otro error es una verdadera
// anomalía: dejamos que se propague.
// -----------------------------------------------------------------------
private function transaction(Closure $work): mixed
{
try {
return DB::transaction($work);
} catch (QueryException $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;
}
}
}
|
El archivo más importante de la aplicación. Lo recorreremos por temas.
11.11.6.1. Los descriptores
Líneas 89–113: los dos descriptores, creados una sola vez por el constructor. Los argumentos con nombre ([dao: $doctors], ejemplo 01) hacen legible la llamada. [$appointments->countByDoctor(...)] (con tres puntos entre paréntesis) no cuenta nada: es la sintaxis de [PHP] 8.1 que genera, a partir de un método, un [Closure], una función que se llamará más tarde ([($d->countAppointments)($id)], línea 349). 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. Lecturas y calendario
Las lecturas (líneas 120–165) se delegan en la capa DAO. La agenda de un médico (líneas 172–185) se calcula: el médico, sus franjas horarias y las citas de ese día. [keyBy('slot_id')] transforma la colección de citas en una colección indexada por número de franja: [$bookings->get($slot->id)] devuelve la cita de una franja determinada, o [null]. [map] transforma cada franja horaria en [DoctorDaySlot]; [all()] devuelve el arreglo [PHP] contenido en la colección.
11.11.6.3. Programación de una cita
Líneas 203–217: cuatro pasos, en una sola transacción.
- No se permiten citas en el pasado: [$day->lt($today)] (*less than*, menor que) compara dos fechas;
- el registro del paciente se bloquea ([lock], [SELECT ... FOR UPDATE]). ¿Por qué? La regla “una sola 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 la primera termine 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 (porque desde [PHP] 8, [throw] es una expresión);
- conteo de las citas próximas;
- inserció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 229–256) llaman a los métodos privados compartidos, con el descriptor correspondiente.
- Líneas 265–285: la creación. El apellido se escribe en mayúsculas ([Str::upper]), 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 “válido” (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, con hash mediante [Hash::make] (ejemplo 25), luego la persona, que referencia la cuenta. [setRelation('account', $user)] almacena la cuenta, que ya está en memoria, en el registro de la persona: [$person->account] no desencadenará una consulta. [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 291–334: la modificación, con dos bloqueos optimistas. El primero es una comparación: 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 la cláusula [WHERE version = ?] del [UPDATE] ([PersonDao::edit]), que detecta un cambio ocurrido entre la lectura y la escritura. La cuenta se procesa así: su nombre mostrado (“nombre APELLIDO”) siempre se actualiza; su nombre de usuario y su contraseña se actualizan solo si se ingresaron; su propio bloqueo optimista protege también la fila de la tabla [users]. Por último, la persona se lee de nuevo: quien llama recibe sus nuevos valores y sus nuevas versiones;
- líneas 345–358: la eliminación, en el orden que imponen las claves externas: primero lo que referencia a la persona (franjas horarias o citas), luego la persona y después su cuenta. El orden inverso sería rechazado por la base de datos: una fila que sigue referenciada por una clave externa no puede eliminarse;
- líneas 363–369: la persona que se está modificando puede conservar su propio nombre y apellido; [$currentId] equivale a [null] para un registro nuevo.
11.11.6.5. Transacciones y restricciones de unicidad
Líneas 391–402: todas las escrituras pasan por este método. [DB::transaction] ejecuta la función en una transacción (Ejemplo 28): [COMMIT] si termina con normalidad, [ROLLBACK] si se produce una excepción, incluida [BusinessException]: una violación de 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 en la base de datos, 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]. [Laravel] lanza entonces una [QueryException], 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 'unq_users_login'
|
La expresión regular de la línea 74 extrae este nombre ([MySQL] 8 lo antepone con el nombre de la tabla, [users.unq_users_login], pero [MariaDB] no lo hace: la parte "[(?:[^'.]*\.)?]" acepta ambas formas), y el arreglo de las líneas 67–72 proporciona la clave del mensaje. Cualquier otro error de la base de datos es una verdadera anomalía: se vuelve a lanzar ([throw $e]) y dará como resultado una página de error 500.
11.12. Autenticación
La carpeta [app/Auth] abarca los ejemplos 25 a 27, con usuarios en la base de datos y algunas medidas de seguridad adicionales.
11.12.1. app/Auth/ConnectedUser.php
| <?php
// =========================================================================
// app/Auth/ConnectedUser.php: el usuario conectado, tal como lo describe su
// token JWT (ver ejemplo 25). Authenticatable: la interfaz que Laravel espera de los
// usuarios autenticados (Auth::user(), auth()->user(), @auth en una vista...).
//
// Los claims de nuestros tokens (ver 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\Auth;
use App\Models\Role;
use Illuminate\Contracts\Auth\Authenticatable;
readonly class ConnectedUser implements Authenticatable
{
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 Authenticatable: el identificador del usuario es el id
// de su cuenta; la contraseña y el token "remember me" de las sesiones de Laravel
// no son relevantes aquí
public function getAuthIdentifierName(): string
{
return 'userId';
}
public function getAuthIdentifier(): int
{
return $this->userId;
}
public function getAuthPasswordName(): string
{
return '';
}
public function getAuthPassword(): string
{
return '';
}
public function getRememberToken(): ?string
{
return null;
}
public function setRememberToken($value): void
{
}
public function getRememberTokenName(): string
{
return '';
}
}
|
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 [Authenticatable] que [Laravel] 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.
- Líneas 35–43: el usuario se describe mediante las declaraciones (claims) de un token ya verificado , o [null] si falta alguna de las declaraciones 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 prudente no cuesta nada. [Role::tryFrom] devuelve el rol, o [null] para un valor desconocido; [ctype_digit] verifica que una cadena conste solo de dígitos;
- líneas 45–50: dos preguntas que las vistas y los controladores suelen hacer;
- líneas 58–61 y siguientes: la interfaz [Authenticatable]. El identificador del usuario es el ID de su cuenta; la contraseña y el token de “recordarme” no son relevantes.
11.12.2. app/Auth/AuthService.php
| <?php
// =========================================================================
// app/Auth/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 (ver 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 (un script
// inyectado no podría entonces 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, ver @csrf);
// - 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\Auth;
use App\Dao\UserDao;
use App\Models\User;
use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use Illuminate\Support\Facades\Hash;
use RuntimeException;
use Symfony\Component\HttpFoundation\Cookie;
use Throwable;
class AuthService
{
// el nombre de la cookie que transporta el token
public const COOKIE = 'rdvmedecins_jwt';
private string $secret;
private int $duration;
public function __construct(private UserDao $users)
{
$this->secret = config('rdvmedecins.jwt.secret');
$this->duration = config('rdvmedecins.jwt.duration');
// 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. Hash::check
// aplica un hash a la contraseña escrita con el "salt" contenido 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 || ! Hash::check($password, $user->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->id,
'login' => $user->login,
'name' => $user->name,
'role' => $user->role->value,
'iat' => $now,
'exp' => $now + $this->duration * 60,
];
$token = JWT::encode($claims, $this->secret, 'HS256');
// cookie(nombre, valor, duración en minutos, ruta, dominio, secure, httpOnly,
// raw, sameSite): la función de Laravel que construye una cookie
return cookie(self::COOKIE, $token, $this->duration, '/', null,
config('rdvmedecins.cookie_secure'), true, false, 'lax');
}
// la cookie que ELIMINA el token: el mismo nombre, vacía, ya expirada
public static function clearingCookie(): Cookie
{
return cookie()->forget(self::COOKIE);
}
// -----------------------------------------------------------------------
// el usuario descrito por un token; null si el token está expirado, falsificado o
// mal formado. 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 35: el nombre de la cookie del token, una constante de clase, que lee [AuthService::COOKIE]. ¿Por qué no configurarla en [config/rdvmedecins.php], como la clave secreta? Porque [bootstrap/app.php] la necesita para excluir la cookie del cifrado en un momento en que la configuración aún no se ha cargado: el código de [withMiddleware] se ejecuta antes de que [Laravel] lea los archivos de la carpeta [config];
- líneas 41–50: la clave y la duración de vida de los tokens, leídas de la configuración. Si la clave es demasiado corta, se avisa en cuanto se crea el servicio, con un mensaje claro (vea “Problemas frecuentes”);
- líneas 55–62: 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. Observe que este servicio usa la capa DAO directamente, sin pasar por la capa de negocio: verificar una contraseña no es una regla de negocio;
- Líneas 70–86: el token del usuario y la cookie que lo transporta. Las declaraciones (claims) son las mismas que en el Ejemplo 25, incluido el ID de la cuenta ([sub], una cadena, como exige el estándar) y el nombre de usuario. La función [cookie] de [Laravel] genera una cookie: nombre, valor, duración en minutos (la del token), ruta, dominio ([null]: el del sitio), [secure] (en producción, sobre HTTPS), [httpOnly], [raw] ([false]: el valor se codifica para una URL) y [sameSite];
- líneas 89–92: la cookie que borra el token: [cookie()->forget(name)] crea una cookie vacía con el mismo nombre que ya ha expirado;
- líneas 98–107: verificación del token (ejemplo 25).
11.12.3. app/Auth/InvalidSession.php
| <?php
// app/Auth/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 propio paciente
// en otra pestaña, o por el ADMIN). Tratamos este caso como una sesión
// expirada: bootstrap/app.php elimina la cookie y redirige a la página de login.
namespace App\Auth;
use RuntimeException;
class InvalidSession extends RuntimeException
{
}
|
Un caso que no cubre el Ejemplo 25: el token es válido, pero la cuenta a la que se refiere ya no existe. Un paciente eliminó su cuenta en una pestaña, pero el token sigue presente en otra; 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 explica más adelante) descubre que la cuenta ya no existe. Entonces lanza esta excepción, que [bootstrap/app.php] trata como una sesión expirada. La clase está vacía: solo importa su tipo , lo que permite asociarla a su propia función de renderizado.
11.12.4. app/Auth/CaptchaService.php, Captcha.php y CaptchaDrawing.php
[CaptchaDrawing.php] y [Captcha.php] provienen del Ejemplo 27. El servicio es casi el mismo:
| <?php
// =========================================================================
// app/Auth/CaptchaService.php: un CAPTCHA ("test to tell a human from a
// robot") construido por el propio servidor, sin un servicio externo (ver ejemplo 27).
//
// Cómo funciona:
// 1. generate() dibuja un texto aleatorio, genera una imagen con él y almacena la respuesta
// correcta EN LA 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 nunca sale del servidor);
// 3. verify(id, typed) compara lo escrito 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é la caché? Una aplicación PHP no guarda 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 entonces a la caché (aquí archivos, ver CACHE_STORE en .env), compartida por
// todas las solicitudes, e incluso por varios servidores con una caché como Redis.
// =========================================================================
namespace App\Auth;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Str;
class CaptchaService
{
// duración de validez de una imagen, en segundos: 10 minutos para llenar el formulario
private const LIFETIME = 600;
public function generate(): Captcha
{
$text = CaptchaDrawing::randomText(5); // 5 caracteres
$id = Str::random(24); // un identificador imposible de adivinar
// la caché olvidará la respuesta por sí sola después de 10 minutos
Cache::put("captcha:$id", $text, self::LIFETIME);
return new Captcha($id, CaptchaDrawing::svg($text));
}
// true si [$typed] es la respuesta correcta del 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
{
if (! $id || $typed === null) {
return false;
}
$expected = Cache::get("captcha:$id");
// forget devuelve true solo para la solicitud que ELIMINÓ realmente la entrada:
// si dos solicitudes presentan el mismo captcha en el mismo instante, solo una
// la elimina; la otra falla
if ($expected === null || ! Cache::forget("captcha:$id")) {
return false;
}
return strcasecmp($expected, trim($typed)) === 0;
}
}
|
- líneas 31–38: una cadena de 5 caracteres generada al azar, un identificador aleatorio ([Str::random], que usa un generador criptográfico) y la respuesta correcta almacenada en la caché durante 10 minutos (Ejemplo 27);
- líneas 42–55: una diferencia con el Ejemplo 27, que usaba [Cache::pull] (leer y luego eliminar). Entre la lectura y la eliminación, una segunda solicitud que mostrara el mismo CAPTCHA también podría leerlo: dos intentos con una sola imagen resuelta. Aquí, la respuesta se lee y luego se elimina con [Cache::forget], que devuelve [true] solo si realmente eliminó la entrada: con la caché en archivos, esto implica borrar un archivo, algo que el sistema operativo permite que haga solo uno de los dos procesos. La solicitud que pierde la carrera falla. Esto equivale al bloqueo de la versión [Flask], donde los CAPTCHA se mantenían en memoria.
11.12.5. app/Auth/AttemptLimiter.php
| <?php
// =========================================================================
// app/Auth/AttemptLimiter.php: segunda línea de defensa contra los robots (la primera es
// el captcha): CONTAMOS los intentos y, pasado un umbral, BLOQUEAMOS durante
// un tiempo (ver ejemplo 27).
//
// - login: después de LOGIN_MAX_FAILURES fallos (captcha incorrecto o contraseña
// incorrecta) para el mismo login desde la misma dirección IP, este par queda
// bloqueado hasta el final de una ventana de LOGIN_BLOCK_MINUTES minutos, contada
// desde el primer fallo. La misma dirección IP también se bloquea si acumula
// 5 veces más fallos, todos los logins juntos (un robot que prueba miles de
// logins distintos);
// - creación de cuenta: 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 suelen salir a Internet por la
// MISMA dirección IP. Por eso el bloqueo de login se aplica primero al par
// (IP, login): un estudiante que escribe una contraseña incorrecta no bloquea a sus
// compañeros, y por eso los umbrales son ajustables (archivo .env).
//
// Los contadores son los del limitador de Laravel (RateLimiter), almacenados en la caché.
// =========================================================================
namespace App\Auth;
use Illuminate\Support\Facades\RateLimiter;
use Illuminate\Support\Str;
class AttemptLimiter
{
private int $maxFailures;
private int $block; // en segundos
private int $maxRegistrations;
public function __construct()
{
$this->maxFailures = config('rdvmedecins.login_max_failures');
$this->block = config('rdvmedecins.login_block_minutes') * 60;
$this->maxRegistrations = config('rdvmedecins.registration_max_per_hour');
}
// login
// número de minutos de bloqueo restantes (0 = el intento está permitido)
public function loginBlockMinutes(string $ip, string $login): int
{
return max($this->remainingMinutes(self::loginKey($ip, $login), $this->maxFailures),
$this->remainingMinutes(self::ipKey($ip), $this->maxFailures * 5));
}
// RateLimiter::hit: +1 al contador; el primer hit abre una ventana de
// [$this->block] segundos, al final de la cual el contador vuelve a cero
public function loginFailure(string $ip, string $login): void
{
RateLimiter::hit(self::loginKey($ip, $login), $this->block);
RateLimiter::hit(self::ipKey($ip), $this->block);
}
// un inicio de sesión exitoso reinicia el contador de ESTE login
public function loginSuccess(string $ip, string $login): void
{
RateLimiter::clear(self::loginKey($ip, $login));
}
// creación de cuenta
public function registrationBlockMinutes(string $ip): int
{
return $this->remainingMinutes("registration|$ip", $this->maxRegistrations);
}
// ventana de una hora
public function registrationSuccess(string $ip): void
{
RateLimiter::hit("registration|$ip", 3600);
}
// mecánica común
// tooManyAttempts: ¿el contador alcanzó [$maximum] en la ventana
// actual? availableIn: segundos restantes antes del final de esta ventana,
// redondeados HACIA ARRIBA al minuto: 30 s restantes -> "1 minute"
private function remainingMinutes(string $key, int $maximum): int
{
if (! RateLimiter::tooManyAttempts($key, $maximum)) {
return 0;
}
return max(1, (int) ceil(RateLimiter::availableIn($key) / 60));
}
private static function loginKey(string $ip, string $login): string
{
return "login|$ip|".Str::lower(trim($login));
}
private static function ipKey(string $ip): string
{
return "ip|$ip";
}
}
|
La segunda línea de defensa contra los bots, después del CAPTCHA: se cuentan los intentos y, al superar un umbral, se bloquea el acceso. El Ejemplo 27 presentó el limitador de [Laravel], la fachada [RateLimiter]. Esta clase lo usa para dos reglas:
- inicio de sesión (líneas 47–62): cada intento fallido (CAPTCHA o contraseña incorrectos) se cuenta dos veces: una para el par (dirección IP, nombre de usuario) y otra solo para la dirección IP. El par se bloquea después de 5 intentos fallidos (parámetro [LOGIN_MAX_FAILURES]), y la dirección IP después de 25, 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. [RateLimiter::hit(key, duration)] incrementa el contador en 1; el primer [hit] abre una ventana de 15 minutos (parámetro [LOGIN_BLOCK_MINUTES]), al final de la cual el contador vuelve a cero. Un inicio de sesión exitoso restablece el contador de ese usuario ([RateLimiter::clear]);
- creación de cuentas (líneas 69–75): un máximo de 10 cuentas por hora por dirección IP (parámetro [REGISTRATION_MAX_PER_HOUR]);
- líneas 85–91: [tooManyAttempts(key, maximum)] indica si el contador ha alcanzado el máximo en la ventana actual; [availableIn(key)] devuelve el número de segundos que quedan en esta ventana, redondeado hacia arriba al minuto ([ceil]): quedan 30 segundos, pero se anuncia “1 minuto”. El mensaje que se muestra depende de ello: “Demasiados intentos fallidos. Vuelva a intentarlo en 15 minuto(s).”;
- líneas 93–96: las claves de los contadores. El nombre de usuario se convierte a minúsculas: [Admin] y [admin] se consideran iguales (como en la base de datos; vea su collation).
Los contadores de [RateLimiter] se almacenan en la caché: son compartidos por todas las solicitudes y sobreviven a un reinicio del servidor. El comando [php artisan cache:clear] vacía la caché y, con ello, restablece todos los contadores a cero (útil durante el desarrollo cuando se ha bloqueado usted mismo).
11.12.6. app/Auth/RegistrationPass.php
| <?php
// =========================================================================
// app/Auth/RegistrationPass.php: el "pass" de la creación de cuenta.
//
// Para abrir la página "Create a client account", primero hay que haber copiado el
// captcha de la página de login (ver RegistrationController, POST
// /register/access). Entonces el servidor emite un pase:
// - un identificador aleatorio, almacenado en una cookie HttpOnly;
// - válido durante 15 minutos (el tiempo de llenar el formulario, incluso con
// varios intentos tras errores de entrada);
// - consumido apenas se crea una cuenta: UN captcha resuelto = UNA cuenta como máximo.
// Un robot no puede crear cuentas en serie.
//
// Sin un pase válido, GET y POST /register redirigen a la página de
// login (middleware CheckRegistrationPass): escribir directamente la URL /register
// no evita el captcha.
//
// Como los captchas, los pases viven en la caché.
// =========================================================================
namespace App\Auth;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Str;
use Symfony\Component\HttpFoundation\Cookie;
class RegistrationPass
{
public const COOKIE = 'rdvmedecins_registration';
// duración de un pase, en minutos
private const LIFETIME = 15;
// emite un nuevo pase; devuelve su identificador
public function issue(): string
{
$id = Str::random(24);
Cache::put("pass:$id", true, self::LIFETIME * 60);
return $id;
}
// true si [$id] es un pase existente y no expirado
public function isValid(?string $id): bool
{
return $id !== null && $id !== '' && Cache::has("pass:$id");
}
// el pase fue usado: lo olvidamos
public function consume(?string $id): void
{
if ($id) {
Cache::forget("pass:$id");
}
}
// el navegador solo envía la cookie a las direcciones /register...
public static function cookie(string $id): Cookie
{
return cookie(self::COOKIE, $id, self::LIFETIME, '/register', null,
config('rdvmedecins.cookie_secure'), true, false, 'lax');
}
// ... y se elimina con una cookie del mismo nombre y ruta, ya expirada
public static function clearingCookie(): Cookie
{
return cookie()->forget(self::COOKIE, '/register');
}
}
|
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 saber, 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 guarda 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 funcionará.
- Líneas 57–61: la cookie tiene la ruta [/register]; el navegador solo la envía a las direcciones que comienzan con esta ruta. [Laravel] la cifra, como todas las cookies de la aplicación excepto dos (vea [bootstrap/app.php]): sin la clave de la aplicación, nadie puede crear una cookie válida ni siquiera leer el identificador;
- líneas 64–67: para eliminar una cookie, debe indicar el mismo nombre y la misma ruta: para el navegador, dos cookies con el mismo nombre pero rutas distintas se consideran dos cookies separadas.
11.12.7. Middleware: app/Http/Middleware
Tres componentes de middleware, ubicados en la carpeta [app/Http/Middleware], como es habitual.
| <?php
// app/Http/Middleware/SetLanguage.php: el idioma de la solicitud (ver ejemplo 22):
// el de la cookie [rdvmedecins_language] si es un idioma admitido, inglés en caso contrario.
//
// Un middleware GLOBAL (ver bootstrap/app.php): se ejecuta para TODAS las
// solicitudes, incluso las que no llevan a ninguna ruta (página 405...). Por lo tanto se ejecuta
// ANTES del middleware EncryptCookies del grupo [web], que descifra las cookies:
// por eso la cookie del idioma se excluye del cifrado.
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;
use Symfony\Component\HttpFoundation\Response;
class SetLanguage
{
// la cookie que recuerda el idioma elegido (ver LanguageController)
public const COOKIE = 'rdvmedecins_language';
// los idiomas admitidos (lang/fr.json, lang/en.json); por defecto, inglés
// (config/app.php, clave locale)
public const LANGUAGES = ['fr', 'en'];
public function handle(Request $request, Closure $next): Response
{
$language = $request->cookie(self::COOKIE);
if (in_array($language, self::LANGUAGES, true)) {
App::setLocale($language);
}
return $next($request);
}
}
|
El idioma de la solicitud (ejemplo 22): el idioma especificado en la cookie, si es un idioma admitido; de lo contrario, el idioma predeterminado de la configuración (inglés). Los idiomas y el nombre de la cookie son constantes, por la misma razón que el nombre de la cookie del token. Este middleware es global (véase [bootstrap/app.php]).
| <?php
// app/Http/Middleware/RequireRoles.php: el rol del usuario debe ser uno de
// los que enumera la ruta; de lo contrario, respuesta 403 (una página de error, ver
// bootstrap/app.php). Un middleware CON PARÁMETROS: en routes/web.php,
// ->middleware('role:ADMIN,DOCTOR')
// llama a handle($request, $next, 'ADMIN', 'DOCTOR'); ...$roles los recibe todos.
//
// Se ejecuta DESPUÉS del middleware de autenticación (ver bootstrap/app.php):
// por lo tanto el usuario ya es conocido.
namespace App\Http\Middleware;
use App\Web\Utils;
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
class RequireRoles
{
public function handle(Request $request, Closure $next, string ...$roles): Response
{
if (! in_array(Utils::user()->role->value, $roles, true)) {
abort(403);
}
return $next($request);
}
}
|
Un middleware con parámetros. En [routes/web.php], [->middleware('role:ADMIN,DOCTOR')] hace referencia al middleware con alias [role] (véase [bootstrap/app.php]), con dos parámetros: [Laravel] llama a [handle($request, $next, 'ADMIN', 'DOCTOR')]. El parámetro variádico [string ...$roles] recibe todos los parámetros restantes en un arreglo (línea 20). Si falta un rol en la lista: respuesta 403 ([abort(403)], Ejemplo 24). Esto equivale al middleware [can:admin] del Ejemplo 26, sin definir un [Gate]: la aplicación solo tiene reglas de roles. Este middleware siempre se coloca en rutas protegidas por [Authenticate], que se ejecuta antes que él: [Authenticate] forma parte del grupo [web], cuyos middleware se ejecutan antes que los de la ruta. Por lo tanto, el usuario ya es conocido.
| <?php
// app/Http/Middleware/CheckRegistrationPass.php: GET y POST /register
// requieren un pase válido (ver app/Auth/RegistrationPass.php); de lo contrario,
// regresan a la página de login, con un mensaje. Escribir directamente la URL
// /register por lo tanto no evita el captcha.
namespace App\Http\Middleware;
use App\Auth\RegistrationPass;
use App\Web\Flash;
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
class CheckRegistrationPass
{
public function __construct(private RegistrationPass $passes)
{
}
public function handle(Request $request, Closure $next): Response
{
if (! $this->passes->isValid($request->cookie(RegistrationPass::COOKIE))) {
Flash::error('ERRORS.CAPTCHA_BEFORE_ACCOUNT');
return redirect()->route('login');
}
return $next($request);
}
}
|
Sin token válido: redirección a la página de inicio de sesión con un mensaje. El middleware recibe el servicio de tokens en su constructor: [Laravel] crea el middleware mediante el contenedor, que le proporciona sus dependencias, igual que hace con los controladores.
11.12.8. app/Http/Controllers/AuthController.php
| <?php
// =========================================================================
// app/Http/Controllers/AuthController.php: las rutas PÚBLICAS del login:
// GET / redirige a la página de inicio del rol (o a /login)
// GET /login muestra el formulario de login (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\Http\Controllers;
use App\Auth\AuthService;
use App\Auth\CaptchaService;
use App\Auth\AttemptLimiter;
use App\Models\Role;
use App\Web\Message;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Str;
use Illuminate\View\View;
class AuthController
{
public function __construct(
private AuthService $auth,
private CaptchaService $captchas,
private AttemptLimiter $limiter,
) {
}
// la página de inicio de cada rol, justo después del login
public static function homePage(Role $role): string
{
return $role === Role::USER ? route('area') : route('schedule');
}
// -----------------------------------------------------------------------
// GET /
// La ruta es pública: el usuario, si lo hay, es conocido (Auth::user()),
// pero no se exige nada.
// -----------------------------------------------------------------------
public function home(): RedirectResponse
{
$user = Auth::user();
return redirect($user ? self::homePage($user->role) : route('login'));
}
// -----------------------------------------------------------------------
// GET /login[?login=xxx]: el parámetro opcional rellena previamente el campo login
// (se usa justo después de la creación de una cuenta, ver RegistrationController)
// -----------------------------------------------------------------------
public function showLogin(Request $request): View|RedirectResponse
{
// ya autenticado (token aún válido): directo a la página de inicio
if ($user = Auth::user()) {
return redirect(self::homePage($user->role));
}
return $this->page(Str::limit((string) $request->query('login', ''), 30, ''), null);
}
// -----------------------------------------------------------------------
// POST /login
// -----------------------------------------------------------------------
public function logIn(Request $request): View|RedirectResponse
{
$login = (string) $request->input('login', '');
$password = (string) $request->input('password', '');
$ip = (string) $request->ip();
// 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->input('captchaId'), $request->input('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);
return redirect(self::homePage($user->role))->withCookie($this->auth->tokenCookie($user));
}
// -----------------------------------------------------------------------
// POST /logout: elimina la cookie del token y luego va a la página de login.
// Solo POST: un simple enlace (GET), colocado en otro sitio, no puede
// cerrar la sesión del usuario sin que lo sepa.
// -----------------------------------------------------------------------
public function logOut(): RedirectResponse
{
return redirect()->route('login')->withCookie(AuthService::clearingCookie());
}
// el formulario, siempre con un NUEVO captcha (cada imagen se usa una sola
// vez); volvemos a mostrar el login escrito, nunca la contraseña
private function page(string $login, ?Message $error): View
{
return view('login', ['pageTitle' => 'LOGIN.TITLE', 'error' => $error, 'login' => $login,
'captcha' => $this->captchas->generate()]);
}
}
|
El controlador de conexión, que se basa en el Ejemplo 27.
- Líneas 41–44: la página de inicio de cada rol: “Mi área” para un paciente, el calendario para los demás. [route('area')] genera la URL de la ruta llamada [area] (Ejemplo 04);
- líneas 51–55: la dirección [/] redirige a la página de inicio del rol o a la página de inicio de sesión. La ruta es pública: [Auth::user()] devuelve el usuario, si existe, sin exigir ninguna entrada;
- líneas 61–68: 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 crear una cuenta); [Str::limit] lo trunca a 30 caracteres sin agregar nada (el tercer parámetro, [''], reemplaza los puntos suspensivos habituales);
- Líneas 73–100: el proceso de inicio de sesión, en el orden mostrado en el Ejemplo 27: posible bloqueo, el CAPTCHA, la contraseña. Nunca se verifica la contraseña de un intento rechazado por el limitador o por el CAPTCHA: un bot no aprende nada al insistir. En caso de fallo, la página se renderiza directamente (sin redirección): el formulario que se vuelve a mostrar siempre tiene un nuevo CAPTCHA y el inicio de sesión ingresado. El error es un objeto [Message] (véase más abajo), una clave y sus parámetros, que se muestra en la parte inferior de la página. Si el inicio de sesión es exitoso, el contador de intentos se restablece a cero y el navegador es redirigido a la página de inicio del rol, con la cookie del token ([withCookie]);
- líneas 107–110: el cierre de sesión elimina la cookie del token (ejemplo 25).
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 abajo).
11.13. La capa web: servicios compartidos
La carpeta [app/Web] contiene los elementos compartidos por los controladores.
11.13.1. app/Web/ApplicationModel.php
| <?php
// =========================================================================
// app/Web/ApplicationModel.php: la 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 la caché.
//
// ¿Por qué la caché de Laravel, y no simplemente una propiedad de este objeto? Porque
// una aplicación PHP no guarda nada en memoria de una solicitud a la siguiente: este
// objeto es un singleton (ver AppServiceProvider), pero un singleton solo vive durante
// UNA solicitud. La caché, en cambio, es compartida por todas las solicitudes (ver
// ejemplos 20 y 23).
//
// Estas listas pueden CAMBIAR (el ADMIN agrega, modifica y elimina médicos y
// clientes): por lo tanto 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. Este es
// todo el sentido de un ÚNICO punto de entrada a la capa de negocio: la regla
// "write => cache update" está escrita solo aquí.
// =========================================================================
namespace App\Web;
use App\Domain\DoctorDaySchedule;
use App\Business\PersonData;
use App\Business\Business;
use App\Business\BusinessService;
use App\Models\Client;
use App\Models\Slot;
use App\Models\Doctor;
use App\Models\Appointment;
use Carbon\CarbonImmutable;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Support\Facades\Cache;
// mismo contrato que la capa de negocio
class ApplicationModel implements Business
{
private const DOCTORS = 'rdvmedecins.doctors';
private const CLIENTS = 'rdvmedecins.clients';
public function __construct(private BusinessService $business)
{
}
// lecturas desde la caché
// rememberForever: el valor de la caché si existe; de lo contrario, se llama a la
// función y su resultado se almacena en la caché (sin límite de tiempo) antes de
// devolverse
public function getAllDoctors(): Collection
{
return Cache::rememberForever(self::DOCTORS, fn () => $this->business->getAllDoctors());
}
public function getAllClients(): Collection
{
return Cache::rememberForever(self::CLIENTS, fn () => $this->business->getAllClients());
}
// el médico cuya cuenta de usuario es [$userId]: sirve para preseleccionar,
// para un médico conectado, su propia agenda. firstWhere: el primer elemento
// de la colección cuya propiedad [user] es igual a $userId
public function getDoctorByUserId(int $userId): ?Doctor
{
return $this->getAllDoctors()->firstWhere('user', $userId);
}
// delegaciones simples
public function getAllSlots(int $doctorId): Collection
{
return $this->business->getAllSlots($doctorId);
}
public function getDoctorDayAppointments(int $doctorId, CarbonImmutable $day): Collection
{
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, CarbonImmutable $day): ?DoctorDaySchedule
{
return $this->business->getDoctorDaySchedule($doctorId, $day);
}
// sin caché aquí: 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): Collection
{
return $this->business->getClientUpcomingAppointments($clientId);
}
public function addAppointment(CarbonImmutable $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é olvidada
public function addDoctor(PersonData $data): Doctor
{
return tap($this->business->addDoctor($data), fn () => Cache::forget(self::DOCTORS));
}
public function editDoctor(int $id, PersonData $data): Doctor
{
return tap($this->business->editDoctor($id, $data), fn () => Cache::forget(self::DOCTORS));
}
public function deleteDoctor(int $id): void
{
$this->business->deleteDoctor($id);
Cache::forget(self::DOCTORS);
}
public function addClient(PersonData $data): Client
{
return tap($this->business->addClient($data), fn () => Cache::forget(self::CLIENTS));
}
public function editClient(int $id, PersonData $data): Client
{
return tap($this->business->editClient($id, $data), fn () => Cache::forget(self::CLIENTS));
}
public function deleteClient(int $id): void
{
$this->business->deleteClient($id);
Cache::forget(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 reserva 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 como [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 iniciar. Una aplicación [PHP] se vuelve a crear con cada solicitud (Ejemplo 01): el objeto [ApplicationModel] es, en efecto, un singleton, pero existe solo durante una única solicitud. Por lo tanto, las listas se almacenan en la caché de [Laravel] (ejemplo 20), que es compartida por todas las solicitudes.
- Líneas 51–54: [Cache::rememberForever(key, function)] devuelve el valor almacenado con esta clave; si no existe, llama a la función (que lee la lista de la base de datos), almacena su resultado en la caché de forma indefinida y lo devuelve. La primera solicitud que necesita la lista la lee de la base de datos; las siguientes la encuentran en la caché. La caché almacena la colección de objetos [Eloquent] en forma serializada (Ejemplo 20) y la reconstruye al leerla, junto con las relaciones cargadas (la cuenta de cada persona);
- líneas 64–67: el médico asociado a una cuenta, obtenido de la lista en caché: [firstWhere('user', $userId)] devuelve el primer elemento de la colección cuya propiedad [user] es igual a [$userId];
- líneas 71–123: 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 de la caché: lo que importa son los datos más recientes (un paciente que acaba de modificar o eliminar su cuenta);
- Líneas 130–133 y siguientes: las actualizaciones. Cada operación de escritura de un médico o cliente borra la lista correspondiente ([Cache::forget]): la siguiente solicitud que la necesite la leerá de nuevo de la base de datos. [tap(value, function)] llama a la función y luego devuelve el valor: en este caso, el médico recién creado, después de borrar la caché. Este es el sentido de un único punto de entrada: la regla “una operación de escritura actualiza la caché” se define solo aquí. Una aplicación que escribe 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 la caché desactualizada: [php artisan cache:clear] la borraría.
11.13.2. app/Web/Message.php y Flash.php
| <?php
// app/Web/Message.php: un mensaje por traducir: su clave y sus parámetros.
// Las vistas lo muestran con {{ __($message->key, $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
// =========================================================================
// app/Web/Flash.php: los mensajes "flash": un mensaje que se muestra UNA VEZ, en la
// página SIGUIENTE (ver 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 una página, redirige (302) a una página GET; el
// mensaje, por su parte, debe sobrevivir a la redirección.
//
// Laravel los almacena en la SESIÓN, aquí en una cookie CIFRADA (driver [cookie],
// ver .env): el servidor no guarda nada entre dos solicitudes.
//
// Un mensaje no contiene un texto, sino una CLAVE de traducción y sus parámetros:
// se traduce al momento de mostrarse, en el idioma de la página (ver
// resources/views/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;
class Flash
{
public static function success(string $key, array $params = []): void
{
self::add('flash_success', $key, $params);
}
public static function error(string $key, array $params = []): void
{
self::add('flash_errors', $key, $params);
}
// session()->flash(key, value): un valor legible solo durante la solicitud
// SIGUIENTE; lo completamos si la solicitud actual ya colocó uno
private static function add(string $list, string $key, array $params): void
{
$messages = session($list, []);
$messages[] = new Message($key, $params);
session()->flash($list, $messages);
}
}
|
Mensajes flash (ejemplo 20): un mensaje almacenado 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. Dos listas, almacenadas en la sesión bajo las claves [flash_success] y [flash_errors]: los mensajes de éxito se muestran en la parte superior de la página y los mensajes de error en la parte inferior.
- Líneas 34–39: una acción puede almacenar varios mensajes: se agrega a la lista ya almacenada por la solicitud actual ([session($list, [])] la lee, con una lista vacía por defecto) y luego se almacena de nuevo. [session()->flash(key, value)] almacena un valor que solo persistirá hasta el final de la siguiente solicitud (ejemplo 20).
[Message] Los objetos se almacenan tal cual en la sesión: [Laravel] serializa los datos de la sesión (Ejemplo 20) y los reconstruye durante la siguiente solicitud. Con el controlador [cookie] (archivo [.env]), se transmiten en una cookie cifrada.
11.13.3. app/Web/Utils.php
| <?php
// =========================================================================
// app/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, de una fecha, enviados por el navegador;
// - usuario: el usuario conectado y su paciente (entidad Client).
// Métodos ESTÁTICOS: se llaman sin crear un objeto (Utils::iso($day)).
// =========================================================================
namespace App\Web;
use App\Auth\InvalidSession;
use App\Auth\ConnectedUser;
use App\Models\Client;
use Carbon\CarbonImmutable;
use Illuminate\Support\Facades\App;
use Illuminate\Support\Facades\Auth;
class Utils
{
// fechas
// la fecha, si [$text] es una fecha existente en formato yyyy-mm-dd; null en caso contrario.
// createFromFormat acepta "2026-02-30" (que pasa a ser 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(?string $text): ?CarbonImmutable
{
if ($text === null || ! 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 = CarbonImmutable::createFromFormat('!Y-m-d', $text);
return $date !== null && $date->format('Y-m-d') === $text ? $date : null;
}
public static function iso(CarbonImmutable $day): string
{
return $day->format('Y-m-d');
}
// "mercredi 23 septembre 2026" / "Wednesday 23 September 2026", según el idioma
// de la solicitud. isoFormat: dddd el día de la semana completo, D el
// día, MMMM el mes completo, YYYY el año (ver ejemplo 16)
public static function formatDay(CarbonImmutable $day): string
{
return $day->locale(App::getLocale())->isoFormat('dddd D MMMM YYYY');
}
// 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 conectado. Las acciones protegidas solo se invocan cuando el usuario existe;
// por precaución, su ausencia se trata como una sesión expirada
public static function user(): ConnectedUser
{
return Auth::user() ?? throw new InvalidSession();
}
// -----------------------------------------------------------------------
// El paciente (entidad Client) que corresponde al usuario conectado.
//
// 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, la cuenta fue eliminada desde el inicio de sesión
// mientras su token aún es válido: lo tratamos como una sesión
// expirada (ver InvalidSession).
// -----------------------------------------------------------------------
public static function connectedPatient(ApplicationModel $application): Client
{
return $application->getClientByUserId(self::user()->userId)
?? throw new InvalidSession();
}
}
|
Algunas funciones de utilidad, en forma de métodos estáticos.
- Líneas 26–34: la fecha de un parámetro [yyyy-mm-dd] o [null]. Dos comprobaciones: el formato (una expresión regular) y luego la existencia de la fecha. [createFromFormat] es permisivo: 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 establece la hora a medianoche (sin él, la hora sería la hora actual);
- Líneas 44–47: “samedi 26 septembre 2026” o “Saturday 26 September 2026”, según el idioma de la solicitud. [isoFormat] (ejemplo 16) usa los códigos de formato de la biblioteca [JavaScript] [Moment.js] : [dddd], el día de la semana en letras; [D], el día; [MMMM], el mes en letras; [YYYY], el año. [locale(...)] devuelve una copia de la fecha configurada para un idioma específico;
- líneas 52–59: un parámetro de consulta es una cadena, o [null], o incluso un arreglo ([?doctorId[]=1], ejemplo 10). Solo se aceptan dígitos (hasta nueve: sin desbordamiento) y el número debe ser estrictamente positivo. [mixed]: cualquier tipo;
- líneas 65–68: el usuario que inició sesión. [Auth::user()] devuelve [null] para un visitante anónimo; las acciones protegidas solo se invocan para un usuario autenticado, pero la ausencia de usuario se trata de todos modos como una sesión expirada;
- líneas 80–84: el paciente ([Client]) del usuario que inició sesión. El token contiene solo el ID de la cuenta; el cliente se identifica por la columna [clients.user]. Si no existe, la cuenta se eliminó desde que el usuario inició sesión: [InvalidSession].
11.14. Los 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",
...
}
}
|
La versión [Flask] los “aplanaba” al iniciar: [LOGIN.TITLE] hacía referencia al texto en [Login]. [Laravel] lee diccionarios JSON planos (ejemplo 22), donde la clave es el texto por traducir o un identificador: aplanamos los diccionarios de una vez por todas y reemplazamos los parámetros [{name}] de otras versiones por la notación usada en [Laravel] y [:name]:
| {
"APP.TITLE": "RdvMedecins",
"APP.LOGOUT": "Log out",
...
"DOCTORS.ADDED": "Doctor :name has been added (login: :login).",
...
}
|
Los archivos [lang/fr.json] y [lang/en.json] contienen cada uno 153 textos; no se reproducen aquí. Una clave se representa con [__('APP.LOGOUT')], y un texto con parámetros con [__('DOCTORS.ADDED', ['name' => ..., 'login' => ...])]. [Laravel] busca primero la clave completa en el diccionario JSON del idioma; si no la encuentra, la busca en los [PHP] archivos de la carpeta [lang/en] (ejemplo 09); si eso falla, muestra la propia clave, lo que señala de inmediato una omisión. Se agregó una entrada de texto: [ERRORS.PAGE_EXPIRED], el mensaje de la página 419, que no está presente en las demás versiones.
Los formularios de “Persona” se validan mediante form requests ([FormRequest], ejemplo 19): clases que describen las reglas de validación de una solicitud. Repasemos el principio: una acción que recibe un [FormRequest] como parámetro solo se invoca si la entrada es válida; de lo contrario, [Laravel] redirige el navegador de vuelta a la página del formulario, junto con los mensajes de error ([$errors] en la vista) y la entrada que debe volver a mostrarse ([old('field')]), excepto las contraseñas.
11.15.1. app/Http/Requests/PersonFieldsRequest.php
| <?php
// =========================================================================
// app/Http/Requests/PersonFieldsRequest.php: los campos de los formularios de
// "person" y sus reglas de validación (ver ejemplo 19). Tres formularios
// comparten los mismos campos de identidad (título, nombre, apellido):
//
// PersonFieldsRequest título, nombre, apellido
// ├─ PersonRequest + login / contraseña OPCIONALES, version
// │ (el ADMIN agrega o modifica un médico / cliente)
// ├─ RegistrationRequest + login / contraseña / confirmación OBLIGATORIOS
// │ (un paciente crea su cuenta)
// └─ MyAccountRequest + login, nueva contraseña opcional, contraseña
// ACTUAL OBLIGATORIA, version
// (un paciente modifica su cuenta)
//
// Una clase ABSTRACTA: nunca se usa sola; sus hijas completan
// sus reglas (array_merge) y sus mensajes.
//
// Recordatorios (ejemplo 19): una acción que recibe un FormRequest como parámetro
// solo se llama si la entrada es válida; de lo contrario, Laravel devuelve al navegador
// a la página del formulario (redirección), con los mensajes de error ($errors en la
// vista) y la entrada que debe volver a mostrarse (old('field')), NUNCA las contraseñas.
// Los mensajes son los textos de los diccionarios lang/*.json: __('ERRORS...').
// =========================================================================
namespace App\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Support\Str;
use Illuminate\Validation\Rule;
abstract class PersonFieldsRequest extends FormRequest
{
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;
// antes de la validación: un login siempre está en minúsculas. Los espacios
// superfluos ya fueron eliminados de todos los campos por el middleware
// TrimStrings de Laravel, excepto de las contraseñas (password,
// password_confirmation, current_password), de las que pueden formar parte; un
// campo vacío se convirtió en null (middleware ConvertEmptyStringsToNull)
protected function prepareForValidation(): void
{
if (is_string($this->input('login'))) {
$this->merge(['login' => Str::lower($this->input('login'))]);
}
}
// bail: la validación de un campo se detiene en su primera regla incumplida:
// un solo mensaje por campo. Longitudes máximas = las de las columnas SQL
public function rules(): array
{
return [
'title' => ['bail', 'required', Rule::in(self::TITLES)],
'first_name' => ['bail', 'required', 'string', 'max:20'],
'last_name' => ['bail', 'required', 'string', 'max:20'],
];
}
// campo.regla -> mensaje
public function messages(): array
{
return [
'title' => __('ERRORS.INVALID_TITLE'),
'first_name.required' => __('ERRORS.FIRSTNAME_REQUIRED'),
'first_name' => __('ERRORS.FIRSTNAME_TOO_LONG'),
'last_name.required' => __('ERRORS.LASTNAME_REQUIRED'),
'last_name' => __('ERRORS.LASTNAME_TOO_LONG'),
'login.required' => __('ERRORS.LOGIN_REQUIRED'),
'login' => __('ERRORS.INVALID_LOGIN'),
'password.required' => __('ERRORS.PASSWORD_REQUIRED'),
'password.min' => __('ERRORS.PASSWORD_TOO_SHORT', ['min' => self::PASSWORD_MIN]),
'password' => __('ERRORS.PASSWORD_TOO_LONG'),
'password_confirmation.required' => __('ERRORS.CONFIRMATION_REQUIRED'),
'password_confirmation' => __('ERRORS.PASSWORDS_DIFFER'),
'current_password' => __('ERRORS.CURRENT_PASSWORD_REQUIRED'),
'version' => __('ERRORS.INVALID_FORM'),
];
}
// la versión (bloqueo optimista), si el formulario tiene una
public function version(): ?int
{
return $this->filled('version') ? (int) $this->input('version') : null;
}
}
|
Tres formularios comparten los mismos campos de identidad (título, 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 sus reglas.
- líneas 34–40: las reglas de entrada, en forma de constantes, que también leen las vistas (la lista de títulos);
- Líneas 47–52: [prepareForValidation] se llama antes de la validación: allí se puede transformar la entrada. Un inicio de sesión siempre va en minúsculas: [merge] reemplaza el valor del campo en la solicitud. Las demás validaciones ya las realizan dos componentes de middleware globales de [Laravel] (véase el capítulo sobre el ciclo de vida): [TrimStrings] elimina los espacios iniciales y finales de todos los valores, excepto los de los campos [password], [password_confirmation] y [current_password] (los espacios pueden formar parte de una contraseña); [ConvertEmptyStringsToNull] reemplaza una cadena vacía por [null]. Por eso los campos de contraseña de la aplicación tienen estos nombres, que corresponden al uso de [Laravel];
- Líneas 56–63: las reglas de los tres campos. [bail] detiene la validación de un campo en cuanto se infringe la primera regla: un solo mensaje por campo. [Rule::in(...)]: el valor debe ser uno de los de la lista. [max:20]: 20 caracteres como máximo; la longitud de la columna está definida por SQL;
- líneas 66–84: mensajes de error, tomados de los diccionarios. La clave ['first_name.required'] hace referencia al mensaje de la regla [required] en el campo [first_name]; la clave ['first_name'] por sí sola hace referencia al mensaje de todas las demás reglas de este campo. El mensaje de una regla se busca primero bajo la clave [field.rule], luego bajo la clave [rule] (el mensaje de esta regla para todos los campos) y después bajo la clave [field]. Las reglas de las clases hijas (inicio de sesión, contraseñas) tienen aquí sus mensajes: un mensaje sin usar no causa ningún problema. El método [messages] se llama durante la validación, en el idioma de la solicitud;
- líneas 87–90: la versión (el campo oculto del bloqueo optimista), como entero, o [null] si el campo está vacío o ausente. [filled]: el campo está presente y no está vacío.
11.15.2. app/Http/Requests/PersonRequest.php, RegistrationRequest.php, MyAccountRequest.php
| <?php
// app/Http/Requests/PersonRequest.php: el formulario de un médico o de un cliente
// (ADMIN): login y contraseña OPCIONALES (ver app/Business/PersonData.php).
namespace App\Http\Requests;
use App\Business\PersonData;
class PersonRequest extends PersonFieldsRequest
{
// nullable: se acepta un campo vacío (null), sin verificar las demás reglas
public function rules(): array
{
return array_merge(parent::rules(), [
'login' => ['bail', 'nullable', 'string', 'regex:'.self::LOGIN_FORMAT],
// 72 caracteres como máximo: más allá, bcrypt ignora el resto
'password' => ['bail', 'nullable', 'string', 'max:72'],
// campo oculto del formulario de modificación (bloqueo optimista)
'version' => ['nullable', 'integer'],
]);
}
// la entrada validada -> los datos que espera la capa de negocio
public function personData(): PersonData
{
return new PersonData($this->input('title'), $this->input('last_name'), $this->input('first_name'),
$this->input('login'), $this->input('password'), $this->version());
}
}
|
El formulario del administrador. [array_merge] agrega tres reglas a las de la clase padre: el nombre de usuario y la contraseña son opcionales ([nullable]: se acepta el valor [null] y entonces no se comprueban las demás reglas); [regex:...] valida el formato del nombre de usuario; [max:72] limita la longitud de una contraseña: [bcrypt] solo considera los primeros 72 bytes (ejemplo 25). El método [personData] (líneas 24–28) convierte la entrada validada en [PersonData] para la capa de negocio: la capa de negocio no reconoce las solicitudes HTTP.
| <?php
// app/Http/Requests/RegistrationRequest.php: "Create a client account": login, contraseña
// y confirmación OBLIGATORIOS.
namespace App\Http\Requests;
use App\Business\PersonData;
class RegistrationRequest extends PersonFieldsRequest
{
public function rules(): array
{
return array_merge(parent::rules(), [
'login' => ['bail', 'required', 'string', 'regex:'.self::LOGIN_FORMAT],
'password' => ['bail', 'required', 'string', 'min:'.self::PASSWORD_MIN, 'max:72'],
// same:password: la confirmación debe ser idéntica a la contraseña
'password_confirmation' => ['bail', 'required', 'same:password'],
]);
}
public function personData(): PersonData
{
return new PersonData($this->input('title'), $this->input('last_name'), $this->input('first_name'),
$this->input('login'), $this->input('password'));
}
}
|
Creación de una cuenta de paciente: el inicio de sesión y la contraseña son obligatorios, y la contraseña debe confirmarse. La regla [same:password] exige que el campo [password_confirmation] tenga el mismo valor que el campo [password]; su mensaje (“La confirmación no coincide con la contraseña.”) aparece debajo del campo de confirmación. [Laravel] también tiene una regla, [confirmed], que comprueba lo mismo, pero a partir del campo [password]; su mensaje aparecería debajo del campo de contraseña.
| <?php
// app/Http/Requests/MyAccountRequest.php: "Manage my account" (un paciente): login
// obligatorio, nueva contraseña opcional, contraseña ACTUAL obligatoria.
namespace App\Http\Requests;
use App\Business\PersonData;
class MyAccountRequest extends PersonFieldsRequest
{
public function rules(): array
{
return array_merge(parent::rules(), [
'login' => ['bail', 'required', 'string', 'regex:'.self::LOGIN_FORMAT],
// opcional: vacío = contraseña sin cambios
'password' => ['bail', 'nullable', 'string', 'min:'.self::PASSWORD_MIN, 'max:72'],
'password_confirmation' => ['same:password'],
// la contraseña ACTUAL, obligatoria para cualquier modificación de la cuenta
'current_password' => ['required'],
'version' => ['nullable', 'integer'],
]);
}
public function personData(): PersonData
{
return new PersonData($this->input('title'), $this->input('last_name'), $this->input('first_name'),
$this->input('login'), $this->input('password'), $this->version());
}
}
|
“Administrar mi cuenta”: la nueva contraseña es opcional (déjela en blanco para conservar la actual) y la contraseña actual es obligatoria. La regla [same:password] se aplica incluso a un campo de confirmación vacío: si se ingresa una nueva contraseña, también debe ingresarse la confirmación. La contraseña actual no se verifica aquí, sino en la acción: una contraseña incorrecta debe ser contada por el limitador de intentos como un inicio de sesión fallido. [Laravel] tiene una regla, [current_password], que compara la contraseña ingresada con la del usuario que inició sesión; esta regla no es adecuada aquí: nuestro usuario conectado ([ConnectedUser]) no contiene el hash de su contraseña.
11.16. Plantillas de vista
La carpeta [app/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 es: 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 los colocan en el HTML. Todas estas clases son [readonly] y solo tienen propiedades, que se promueven mediante su constructor.
| <?php
// app/Views/OptionView.php: una opción de una lista desplegable (médico, paciente).
//
// La carpeta app/Views contiene los "view models": 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 ID, la etiqueta y si la opción está seleccionada.
| <?php
// app/Views/ScheduleRow.php: una fila de la agenda mostrada (una franja).
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 una franja ocupada; null = "Booked"
public ?string $patient,
public bool $mine, // la cita del paciente conectado
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: un intervalo de tiempo y lo que el usuario que inició sesión está autorizado a ver y hacer con él. [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
// app/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
// app/Views/BookingView.php: la ventana de reserva de una franja.
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 cuales elegir
public array $clients,
// USER: el paciente es el propio usuario
public ?string $patient,
) {
}
}
|
El calendario mostrado y la ventana de reserva: para el administrador y los médicos, la lista de pacientes entre los que elegir; para un paciente, su propio nombre.
| <?php
// app/Views/PersonKeys.php: las claves de traducción propias 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");
}
}
|
Las claves de traducción específicas de médicos o 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
// app/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.17. La capa web: rutas y controladores
11.17.1. routes/web.php
| <?php
// =========================================================================
// routes/web.php: todas las URL de la aplicación.
//
// Recordatorio (ver bootstrap/app.php): todas estas rutas exigen un usuario
// autenticado, EXCEPTO las del primer grupo, que quitan el middleware de
// autenticación (withoutMiddleware). El middleware [role:...] además exige
// uno de los roles enumerados; se aplica a una ruta o a todas las rutas de un
// grupo.
//
// ->name(...): el NOMBRE de la ruta, con el cual el código construye sus URL
// (route('schedule', [...]), redirect()->route('login')...): cambiar una URL
// solo requiere modificar este archivo.
// =========================================================================
use App\Http\Controllers\ScheduleController;
use App\Http\Controllers\AuthController;
use App\Http\Controllers\ClientsController;
use App\Http\Controllers\PatientAreaController;
use App\Http\Controllers\RegistrationController;
use App\Http\Controllers\LanguageController;
use App\Http\Controllers\DoctorsController;
use App\Http\Middleware\SetLanguage;
use Illuminate\Auth\Middleware\Authenticate;
use Illuminate\Support\Facades\Route;
// las rutas PÚBLICAS
Route::withoutMiddleware(Authenticate::class)->group(function () {
// el login (ver AuthController)
Route::controller(AuthController::class)->group(function () {
Route::get('/', 'home')->name('home');
Route::get('login', 'showLogin')->name('login');
Route::post('login', 'logIn');
Route::post('logout', 'logOut')->name('logout');
});
// la elección del idioma: /language/fr, /language/en; cualquier otro valor: 404
Route::get('language/{code}', [LanguageController::class, 'change'])
->whereIn('code', SetLanguage::LANGUAGES)->name('language');
// la creación de una cuenta de cliente (ver RegistrationController); el formulario
// requiere un pase (middleware registration.pass)
Route::controller(RegistrationController::class)->prefix('register')->group(function () {
Route::post('access', 'access')->name('registration.access');
Route::middleware('registration.pass')->group(function () {
Route::get('', 'form')->name('registration');
Route::post('', 'create');
});
});
// ninguna otra ruta coincide con la URL solicitada: página 404. Una ruta "fallback"
// en lugar del 404 automático de Laravel: así la solicitud pasa
// por los middlewares del grupo [web] (sesión, usuario...), y la
// página de error tiene su barra de navegación completa
Route::fallback(fn () => abort(404));
});
// la agenda (todos los roles)
Route::controller(ScheduleController::class)->prefix('schedule')->group(function () {
Route::get('', 'show')->name('schedule');
Route::post('book', 'book')->middleware('role:ADMIN,DOCTOR,USER')->name('schedule.book');
// un paciente cancela SU cita desde "My area", no desde aquí
Route::post('cancel', 'cancel')->middleware('role:ADMIN,DOCTOR')->name('schedule.cancel');
});
// médicos y clientes (ADMIN)
// Las dos secciones tienen las MISMAS rutas (ver PersonsController): un ciclo
// las declara para cada una. Los nombres de las rutas llevan el prefijo de la sección:
// doctors.list, clients.list...
foreach (['doctors' => DoctorsController::class, 'clients' => ClientsController::class] as $section => $controller) {
Route::controller($controller)->prefix($section)->name("$section.")->middleware('role:ADMIN')
->group(function () {
Route::get('', 'list')->name('list');
Route::get('add', 'addForm')->name('addForm');
Route::post('add', 'add')->name('add');
// whereNumber: {id} debe estar formado por dígitos
Route::get('{id}/edit', 'editForm')->whereNumber('id')->name('editForm');
Route::post('{id}/edit', 'edit')->whereNumber('id')->name('edit');
Route::post('{id}/delete', 'delete')->whereNumber('id')->name('delete');
});
}
// el área del paciente (USER)
Route::controller(PatientAreaController::class)->middleware('role:USER')->group(function () {
Route::get('my-area', 'patientArea')->name('area');
Route::post('my-area/cancel', 'cancelAppointment')->name('area.cancel');
Route::get('my-account', 'accountForm')->name('account');
Route::post('my-account', 'editAccount')->name('account.edit');
Route::post('my-account/delete', 'deleteAccount')->name('account.delete');
});
|
Todas las rutas URL de la aplicación. Observe que todas estas rutas requieren un usuario autenticado (el middleware [Authenticate], agregado al grupo [web] por [bootstrap/app.php]), excepto aquellas que eliminan este requisito.
- Líneas 28–56: las rutas públicas. [withoutMiddleware] quita un componente de middleware de las rutas del grupo: en este caso, la autenticación. Entre ellas están el inicio de sesión ([AuthController]), la selección de idioma y la creación de cuentas de paciente;
- Líneas 30–35: [Route::controller] (Ejemplo 02) especifica el controlador de las rutas del grupo: cada ruta nombra ahora solo su método. [->name('login')] asigna un nombre a la ruta (Ejemplo 04): el código genera su URL con este nombre ([route('login')], [redirect()->route('login')]), y cambiar una URL requiere modificar solo ese archivo. El nombre [login] también tiene un significado especial para [Laravel]: es la página a la que el middleware [Authenticate] redirige a un visitante anónimo si no se especifica otra página;
- líneas 38–39: [whereIn('code', [...])] acepta solo los valores de la lista para el parámetro [{code}]: [/language/de] no corresponde a ninguna ruta (página 404);
- líneas 43–49: creación de cuentas. [prefix('register')] agrega [/register] antes de las entradas de URL del grupo: [Route::get('', ...)] es la propia ruta [/register]. El formulario (GET y POST) también requiere un pase: el middleware con alias [registration.pass];
- línea 55: la ruta de respaldo (fallback), seleccionada cuando ninguna otra ruta coincide con una solicitud GET. Sin ella, [Laravel] genera por sí mismo un error 404 antes de que se ejecuten los middleware del grupo [web]: sin sesión, sin cookies descifradas... La página de error no tendría ni el nombre del usuario en su barra de navegación ni un token anti-CSRF para el botón de cierre de sesión. Con la ruta de respaldo, la solicitud pasa por el grupo [web] y luego la acción genera un error 404. La ruta es pública: una dirección desconocida devuelve una página 404, incluso a un visitante anónimo. Efecto secundario: una solicitud GET a una URL que solo existe como POST ([/logout]) también devuelve una página 404, no un 405;
- líneas 59–64: el calendario. Su página es accesible para todos los usuarios autenticados; la reserva está disponible para los tres roles (es decir, cualquier usuario autenticado; la lista de roles documenta esta regla); la cancelación está disponible para el administrador y los médicos: [->middleware('role:ADMIN,DOCTOR')];
- líneas 70–81: las rutas de médicos y clientes son las mismas: un bucle las declara para cada una de las dos secciones. El archivo de rutas es un archivo [PHP] estándar: en él se pueden escribir bucles, condiciones y funciones. Para cada sección hay un grupo: el controlador, el prefijo de la URL ([/doctors]), el prefijo del nombre ([->name("$section.")]: la ruta llamada [list] se llama [doctors.list]) y el middleware [role:ADMIN], que protege todas las rutas del grupo, incluidas las que se agreguen después. [whereNumber('id')] acepta solo números para el parámetro [{id}] (p. ej., 02);
- líneas 84–90: el área del paciente, reservada para el rol USER.
Los códigos de URL corresponden a 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 comando [php artisan route:list] muestra la lista de rutas, junto con sus nombres y acciones.
11.17.2. app/Http/Controllers/LanguageController.php
| <?php
// =========================================================================
// app/Http/Controllers/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 middleware
// SetLanguage la vuelve a leer y define el idioma de la solicitud. Luego regresamos a la página
// de la que veníamos (ver ejemplo 22).
// =========================================================================
namespace App\Http\Controllers;
use App\Http\Middleware\SetLanguage;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
class LanguageController
{
// {code} se limita a los idiomas admitidos por la ruta (whereIn): /language/de da una página 404
public function change(Request $request, string $code): RedirectResponse
{
// un año: 60 * 24 * 365 minutos
return redirect($this->originPage($request))->withCookie(cookie(
SetLanguage::COOKIE, $code, 60 * 24 * 365, '/', null,
config('rdvmedecins.cookie_secure'), true, false, 'lax'));
}
// -----------------------------------------------------------------------
// la página anterior, según el encabezado HTTP "Referer" que envía el navegador.
// Solo conservamos su ruta (/schedule?...): redirigir a una dirección
// completa suministrada 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/..." el navegador lo entendería 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 de idioma se almacena en una cookie durante un año (Ejemplo 22), después de lo cual el navegador regresa a la página de la que provino. La cookie no está cifrada (véase [bootstrap/app.php]); es [httpOnly]: el [JavaScript] de la página no necesita leerla.
- Líneas 35–47: la página anterior se especifica mediante el encabezado HTTP [Referer] que el navegador envía con la solicitud. Son datos proporcionados por el cliente y, por lo tanto, sospechosos: 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] con un [Referer] falso (la vulnerabilidad llamada *open redirect*). Por eso, conservamos solo la ruta y los parámetros ([/schedule?doctorId=1&...]), extraídos mediante la función [parse_url] de [PHP], que divide una URL en sus partes ([scheme], [host], [path], [query]...). También se rechaza una ruta que comience con [//] : un navegador interpreta [//site.com/page] como una dirección en otro sitio. Por último, no se puede volver a [/language/...]: sería un bucle.
| <?php
// =========================================================================
// app/Http/Controllers/ScheduleController.php: la página de la 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 la
// ventana de reserva
// de la franja 7 abierta
// POST /schedule/book crea una cita
// POST /schedule/cancel cancela una cita
//
// Toda la página está descrita por su URL: se puede recargar, guardar en favoritos,
// usar el botón "Back" del navegador, sin una sola línea de
// JavaScript.
//
// Lo que cada uno ve y puede hacer:
//
// | rol | franja ocupada mostrada | Book | Cancel |
// |===============|===================================|====================|=========|
// | ADMIN, DOCTOR | nombre del paciente | para un paciente | sí |
// | | | elegido en una lista | |
// | USER (paciente)| "Booked", o SU nombre si es | para sí mismo, si | no (*) |
// | | su propia cita | no tiene ninguna | |
// | | | cita 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 (de lo contrario un simple "View page
// source" lo revelaría).
//
// Sin reservas en el pasado: el botón "Book" solo aparece para
// hoy y los días siguientes (y la capa de negocio
// de todos modos la rechazaría).
//
// Seguridad: todas las URL /schedule exigen un usuario autenticado (regla
// general, ver bootstrap/app.php); el middleware [role] de las rutas POST además
// exige uno de los roles enumerados (ver routes/web.php).
// =========================================================================
namespace App\Http\Controllers;
use App\Domain\DoctorDaySchedule;
use App\Business\Dates;
use App\Business\BusinessException;
use App\Models\Client;
use App\Models\Person;
use App\Models\Role;
use App\Views\ScheduleView;
use App\Views\ScheduleRow;
use App\Views\OptionView;
use App\Views\BookingView;
use App\Web\ApplicationModel;
use App\Web\Flash;
use App\Web\Message;
use App\Web\Utils;
use Carbon\CarbonImmutable;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\View\View;
class ScheduleController
{
public function __construct(private ApplicationModel $application)
{
}
// -----------------------------------------------------------------------
// GET /schedule
// Los parámetros de la URL se leen sin procesar ($request->query), para distinguir un
// parámetro AUSENTE (null) de un parámetro VACÍO (?doctorId=).
// -----------------------------------------------------------------------
public function show(Request $request): View
{
$error = null;
$user = 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('day');
if ($rawDay !== null) {
$requestedDay = Utils::validDate(is_string($rawDay) ? $rawDay : null);
if ($requestedDay !== null) {
$day = $requestedDay;
} else {
$error = 'ERRORS.INVALID_DATE';
}
}
$dayBookable = $day->gte(Dates::today());
// el médico: el de la URL; en su defecto, para un médico conectado, él mismo
$rawDoctorId = $request->query('doctorId');
$doctorId = Utils::positiveInteger($rawDoctorId);
if ($rawDoctorId === null && $user->role === Role::DOCTOR) {
$doctorId = $this->application->getDoctorByUserId($user->userId)?->id;
}
// la lista desplegable de médicos
$doctors = $this->application->getAllDoctors()
->map(fn (Person $m) => self::option($m, $m->id === $doctorId))->all();
// la agenda, si se eligió 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, $dayBookable);
}
}
// la ventana de reserva: solo si la franja solicitada puede ser reservada
// por este usuario. array_find: el primer elemento que cumple la
// condición (null si no hay ninguno)
$booking = null;
$slotId = Utils::positiveInteger($request->query('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']
? $this->application->getAllClients()->map(fn (Client $c) => self::option($c, false))->all()
: [],
$rights['patient']?->label());
}
}
return view('schedule', [
'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 ventana de reserva
'backUrl' => $doctorId !== null ? self::scheduleUrl($doctorId, $day) : route('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
// - colocamos un mensaje flash y redirigimos a la agenda
// (ver ejemplo 20).
// -----------------------------------------------------------------------
public function book(Request $request): RedirectResponse
{
[$doctorId, $day] = $this->readScheduleRequest($request);
$slotId = Utils::positiveInteger($request->input('slotId'));
if ($doctorId === null || $slotId === null) {
abort(400); // -> página "bad request" (ver bootstrap/app.php)
}
$user = Utils::user();
if ($user->isPatient()) {
$client = Utils::connectedPatient($this->application);
} else {
$clientId = Utils::positiveInteger($request->input('clientId'));
if ($clientId === null) {
// ningún paciente elegido: reabrimos la ventana de reserva
Flash::error('ERRORS.CHOOSE_PATIENT');
return redirect(self::scheduleUrl($doctorId, $day, $slotId));
}
$client = $this->application->getClientById($clientId);
}
$slot = $this->application->getSlotById($slotId);
if ($client === null) {
Flash::error('ERRORS.PATIENT_NOT_FOUND');
} elseif ($slot === null || $slot->doctor_id !== $doctorId) {
Flash::error('ERRORS.SLOT_NOT_FOUND');
} else {
try {
// las reglas (no en el pasado, una sola cita próxima por
// paciente, franja libre) las verifica la capa de negocio
$this->application->addAppointment($day, $slot, $client);
Flash::success('SCHEDULE.BOOKED');
} catch (BusinessException $e) {
// misma regla, pero con un mensaje en 2.ª persona cuando es el
// propio paciente quien reserva ("You already have..." en lugar de
// "This patient..."). Las demás excepciones (anomalías reales) no
// se capturan: página 500.
if ($e->key === 'ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT' && $user->isPatient()) {
Flash::error('SCHEDULE.ALREADY_BOOKED_INFO');
} else {
Flash::error($e->key, $e->params);
}
}
}
return redirect(self::scheduleUrl($doctorId, $day));
}
// -----------------------------------------------------------------------
// POST /schedule/cancel campos: appointmentId, doctorId, day
// (un paciente cancela SU cita desde "My area", no desde aquí)
// -----------------------------------------------------------------------
public function cancel(Request $request): RedirectResponse
{
[$doctorId, $day] = $this->readScheduleRequest($request);
$appointmentId = Utils::positiveInteger($request->input('appointmentId'));
if ($doctorId === null || $appointmentId === null) {
abort(400);
}
$appointment = $this->application->getAppointmentById($appointmentId);
if ($appointment === null) {
// ya cancelada (por otra persona, o doble clic)
Flash::error('ERRORS.APPOINTMENT_NOT_FOUND');
} else {
$this->application->deleteAppointment($appointment);
Flash::success('SCHEDULE.CANCELLED');
}
return redirect(self::scheduleUrl($doctorId, $day));
}
// -----------------------------------------------------------------------
// ¿quién está conectado y qué puede hacer en esta página?
// manager: ADMIN o DOCTOR;
// patient: el cliente conectado (rol USER), de lo contrario null;
// patientCanBook: un USER sin cita próxima.
// -----------------------------------------------------------------------
private function rights(): array
{
if (! Utils::user()->isPatient()) {
return ['manager' => true, 'patient' => null, 'patientCanBook' => false];
}
$patient = Utils::connectedPatient($this->application);
$upcoming = $this->application->getClientUpcomingAppointments($patient->id);
return ['manager' => false, 'patient' => $patient, 'patientCanBook' => $upcoming->isEmpty()];
}
// -----------------------------------------------------------------------
// la agenda del médico, formateada para la vista y filtrada según los derechos
// -----------------------------------------------------------------------
private function scheduleView(DoctorDaySchedule $doctorSchedule, array $rights, bool $dayBookable): ScheduleView
{
$doctorId = $doctorSchedule->doctor->id;
$day = $doctorSchedule->day;
$rows = [];
foreach ($doctorSchedule->doctorDaySlots as $dds) {
$slot = $dds->slot;
$appointment = $dds->appointment;
$free = $appointment === null;
// ¿la cita del paciente conectado?
$mine = $appointment !== null && $rights['patient'] !== null && $appointment->client_id === $rights['patient']->id;
$rows[] = new ScheduleRow(
slotId: $slot->id,
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->client->label() : null,
mine: $mine,
bookable: $free && $dayBookable && ($rights['manager'] || $rights['patientCanBook']),
bookUrl: self::scheduleUrl($doctorId, $day, $slot->id),
appointmentId: $appointment !== null && $rights['manager'] ? $appointment->id : null);
}
return new ScheduleView($doctorSchedule->doctor->label(), Utils::formatDay($day), $rows);
}
// funciones utilitarias
// los campos ocultos doctorId / day de los formularios POST; [null, null] si
// no son válidos
private function readScheduleRequest(Request $request): array
{
$doctorId = Utils::positiveInteger($request->input('doctorId'));
$day = Utils::validDate(is_string($request->input('day')) ? $request->input('day') : null);
return $doctorId === null || $day === null ? [null, null] : [$doctorId, $day];
}
// /schedule?doctorId=1&day=2026-09-23[&book=7]: route() agrega al final de
// la URL los parámetros que no son parámetros de ruta
private static function scheduleUrl(int $doctorId, CarbonImmutable $day, ?int $book = null): string
{
$params = ['doctorId' => $doctorId, 'day' => Utils::iso($day)];
if ($book !== null) {
$params['book'] = $book;
}
return route('schedule', $params);
}
private static function option(Person $p, bool $selected): OptionView
{
return new OptionView($p->id, $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. Innecesario si SU
// cita aparece en la agenda mostrada (en azul): es el caso justo
// después de haberla reservado, cuando el mensaje estaría fuera de lugar.
// -----------------------------------------------------------------------
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 cada usuario ve y puede hacer.
11.17.3.1. Los elementos de URL de la página
Toda la página 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 para reservar el intervalo 4. Se puede recargar la página, guardarla en marcadores 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 con un simple enlace y se cierra con un enlace a la misma página sin el parámetro [book].
11.17.3.2. GET /schedule
Líneas 76–148:
- los parámetros de la URL se leen tal cual ([$request->query('day')]), sin validación por parte de [Laravel]: un parámetro ausente ([null]) no es un error (por defecto es “hoy” o “ningún médico”); una fecha no válida es un error, que se muestra en la parte inferior de la página, sin impedir que se muestre el resto del contenido; un número de médico o de intervalo que no sea un entero positivo simplemente se ignora;
- un paciente conectado que no ha seleccionado un médico puede ver su agenda: el sistema busca a su médico a partir de su cuenta ([getDoctorByUserId]). [?->id]: el operador null-safe devuelve [null] si el objeto es [null], en lugar de generar un error;
- la lista desplegable de médicos: cada médico se convierte en un [OptionView]; [map(...)->all()] devuelve un arreglo;
- el calendario, formateado y filtrado según los permisos del usuario ([scheduleView], más abajo);
- la ventana de reserva, solo si el intervalo solicitado es reservable por ese usuario: un paciente que intente generar la URL [&book=2] de un intervalo ya reservado no obtendría nada. [array_find] ([PHP] 8.4) devuelve el primer elemento de un arreglo que cumple una condición, o [null]. La lista de pacientes se proporciona solo al administrador y a los médicos; un paciente recibe únicamente su propio nombre;
- la vista recibe sus variables ([view('schedule', [...])], ejemplo 13), entre ellas [pageTitle] y [error], que lee la plantilla.
11.17.3.3. POST /schedule/book
Líneas 161–206:
- se comprueban los campos ocultos del formulario de la cita (médico, día, intervalo); si no son válidos, debe de tratarse de una solicitud creada manualmente: [abort(400)], la página de “solicitud no válida”;
- para un paciente, el campo [clientId] se ignora: el paciente siempre reserva para sí mismo ([Utils::connectedPatient]). Confiar en un campo enviado por el navegador permitiría que un paciente malintencionado hiciera una reserva a 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;
- el intervalo debe pertenecer al médico indicado en la página;
- las reglas de negocio (no en el pasado, una sola cita próxima, intervalo disponible) las verifica la capa de lógica de negocio. Una [BusinessException] se convierte en un mensaje de error flash. El mismo rechazo, “una cita próxima”, se muestra a la segunda persona en nombre del propio paciente (“Ya tiene…”). Cualquier otra excepción no se intercepta: es un verdadero error (página 500);
- en todos los casos se aplica el patrón Post/Redirect/Get (ejemplo 20): un mensaje flash y una redirección al calendario.
11.17.3.4. POST /schedule/cancel
Líneas 212–228: cancelación de una cita por el administrador o un médico (el middleware [role:ADMIN,DOCTOR] en la ruta). Una cita que ya no existe (ya cancelada por otra persona, o por un doble clic) no es una excepción: es simplemente un mensaje.
- líneas 236–244: 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 249–273: la agenda del médico, convertida en filas para la vista. El punto clave en materia de confidencialidad es la línea 266: 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 pasa a la vista 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 un intervalo 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->id]) hacen legible la construcción de un objeto con ocho propiedades;
- líneas 288–295: la URL de la agenda de un médico en un día determinado. [route('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 308–315: el mensaje que explica a un paciente por qué no hay 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 se movería). [array_any] ([PHP] 8.4): ¿al menos un elemento cumple la condición?
11.17.4. app/Http/Controllers/PersonsController.php
| <?php
// =========================================================================
// app/Http/Controllers/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 dos veces las mismas acciones, las escribimos una vez
// en esta clase ABSTRACTA; DoctorsController y ClientsController
// heredan de ella y solo especifican lo que los distingue: el nombre de la sección
// (doctors o clients), las claves de traducción y los métodos de
// ApplicationModel que deben llamarse. Así obtenemos, para cada uno (ver routes/web.php):
//
// GET /doctors lista
// GET /doctors/add formulario vacío
// POST /doctors/add creación
// GET /doctors/{id}/edit formulario prellenado
// POST /doctors/{id}/edit modificación
// POST /doctors/{id}/delete eliminación
//
// (y las mismas URL bajo /clients). Las vistas también son comunes:
// resources/views/persons/list.blade.php y persons/form.blade.php.
//
// SEGURIDAD: el middleware [role:ADMIN] se coloca en el GRUPO de rutas de cada
// sección (ver routes/web.php): protege todas sus acciones, incluidas las
// que se le agreguen más adelante.
// =========================================================================
namespace App\Http\Controllers;
use App\Http\Requests\PersonRequest;
use App\Business\PersonData;
use App\Business\BusinessException;
use App\Models\Person;
use App\Views\PersonKeys;
use App\Web\ApplicationModel;
use App\Web\Flash;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Http\RedirectResponse;
use Illuminate\View\View;
abstract class PersonsController
{
// los campos del formulario implicados en cada error de negocio de tipo "input" (un
// duplicado): se resaltan en rojo, y el mensaje queda 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)
{
}
// lo que debe proporcionar cada tipo de persona
// "doctors" o "clients": el inicio de las URL y de los nombres de ruta
abstract protected function section(): string;
abstract protected function keys(): PersonKeys;
abstract protected function listAll(): Collection;
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 remove(int $id): void;
// -------------------------------------------------------------------
// GET /doctors (o /clients)
// -------------------------------------------------------------------
public function list(): View
{
return view('persons.list', ['pageTitle' => $this->keys()->title, 'keys' => $this->keys(),
'section' => $this->section(), 'persons' => $this->listAll()]);
}
// -------------------------------------------------------------------
// GET /doctors/add
// -------------------------------------------------------------------
public function addForm(): View
{
return $this->form(null);
}
// -------------------------------------------------------------------
// POST /doctors/add
// PersonRequest ya validó la entrada: una entrada no válida no llega
// hasta aquí (Laravel devolvió al formulario, con los errores)
// -------------------------------------------------------------------
public function add(PersonRequest $request): RedirectResponse
{
try {
$person = $this->create($request->personData());
} catch (BusinessException $e) {
return $this->businessError($e);
}
Flash::success($this->keys()->added, self::params($person));
return redirect()->route($this->section().'.list');
}
// -------------------------------------------------------------------
// GET /doctors/{id}/edit
// {id} debe estar formado por dígitos (whereNumber, ver routes/web.php):
// /doctors/abc/edit no coincide con ninguna ruta (página 404)
// -------------------------------------------------------------------
public function editForm(int $id): View
{
$person = $this->find($id) ?? abort(404);
return $this->form($person);
}
// -------------------------------------------------------------------
// POST /doctors/{id}/edit
// -------------------------------------------------------------------
public function edit(PersonRequest $request, int $id): RedirectResponse
{
try {
$person = $this->update($id, $request->personData());
} catch (BusinessException $e) {
return $this->businessError($e);
}
Flash::success($this->keys()->edited, self::params($person));
return redirect()->route($this->section().'.list');
}
// -------------------------------------------------------------------
// POST /doctors/{id}/delete
// (la confirmación "Are you sure?" se solicita antes de enviar el formulario,
// ver public/js/app.js)
// -------------------------------------------------------------------
public function delete(int $id): RedirectResponse
{
$person = $this->find($id);
try {
$this->remove($id);
Flash::success($this->keys()->deleted, self::params($person));
} catch (BusinessException $e) {
Flash::error($e->key, $e->params);
}
return redirect()->route($this->section().'.list');
}
// funciones internas
// $person null: formulario de creación; de lo contrario: formulario de modificación,
// prellenado con sus valores (salvo que la vista tenga una entrada que volver a mostrar: old())
private function form(?Person $person): View
{
$creating = $person === null;
$keys = $this->keys();
return view('persons.form', [
'pageTitle' => $creating ? $keys->add : $keys->edit,
'creating' => $creating,
'person' => $person,
'action' => $creating ? route($this->section().'.add')
: route($this->section().'.edit', ['id' => $person->id]),
'listUrl' => route($this->section().'.list'),
]);
}
// una regla de negocio rechazó la escritura: regresamos al formulario (back), con
// la entrada del usuario (withInput, sin las contraseñas), el mensaje de
// la capa de negocio (al final de la página) y los campos implicados, si los hay,
// resaltados en rojo para que el usuario vea de inmediato qué corregir
private function businessError(BusinessException $e): RedirectResponse
{
Flash::error($e->key, $e->params);
if (in_array($e->key, ['ERRORS.DOCTOR_NOT_FOUND', 'ERRORS.PATIENT_NOT_FOUND'], true)) {
// eliminado entretanto por otro ADMIN: regreso a la lista
return redirect()->route($this->section().'.list');
}
return back()->withInput(request()->except('password'))
->with('invalidFields', self::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
}
// :name y :login de los mensajes "added / edited / deleted"
private static function params(?Person $person): array
{
return $person === null ? ['name' => '', 'login' => '']
: ['name' => "{$person->first_name} {$person->last_name}", 'login' => $person->account?->login ?? ''];
}
}
|
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 56–68, 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 “método plantilla”: la clase padre define el algoritmo, mientras que las clases hijas aportan los detalles.
- líneas 43–47: los campos afectados por cada error de entrada de la lógica de negocio: un nombre de usuario duplicado afecta al campo “inicio de sesión”; un conflicto de nombres afecta a los campos “nombre” y “apellido”. Estos campos se resaltarán en rojo;
- Líneas 73–77: la lista. La vista es común a ambas secciones: recibe las claves de traducción de la sección ([keys]) y su nombre ([section]), que se usan para generar la URL ([route("$section.addForm")]);
- líneas 92–101: la adición. La entrada ya fue validada por [PersonRequest]: una entrada no válida no llega a este punto ([Laravel] redirigió el navegador de vuelta al formulario, junto con los errores). Queda la capa de lógica de negocio, que puede rechazar el guardado (por un homónimo o un inicio de sesión ya en uso); de lo contrario, aparece un mensaje de éxito y se devuelve al usuario a la lista (esquema PRG);
- líneas 108–112: el formulario de actualización de un usuario existente: [?? abort(404)] ([abort] lanza una excepción: es una expresión, utilizable a la derecha de [??]);
- líneas 117–126: la actualización; el ID proviene de la ruta de la URL ([{id}]), los datos del formulario;
- líneas 133–143: la eliminación. El formulario solicitó confirmación en el navegador (ejemplo 21). La persona se recupera antes de eliminarla para el mensaje de éxito (“Se eliminó al médico Paul TATOU.”);
- líneas 149–161: el formulario, para creación ([$person] es igual a [null]) o modificación. La vista recibe la persona y muestra sus valores, excepto después de un rechazo, en cuyo caso vuelve a mostrar los datos ingresados ([old], ejemplo 19);
- líneas 167–176: la capa de negocio rechazó la operación de escritura. Si la persona fue eliminada mientras tanto (por otro administrador): regreso a la lista. De lo contrario, regreso al formulario ([back()], la página anterior, ejemplo 19), como en el caso de un error de entrada: la entrada que debe volver a mostrarse ([withInput], sin la contraseña), el mensaje de la capa de negocio (un mensaje de error flash, que se muestra en la parte inferior de la página) y los campos que deben resaltarse en rojo ([with('invalidFields', ...)], un dato flash que lee la vista). [request()]: la solicitud actual, accesible desde cualquier lugar;
- líneas 179–183: los parámetros [:name] y [:login] de los mensajes de éxito.
11.17.5. app/Http/Controllers/DoctorsController.php y ClientsController.php
| <?php
// app/Http/Controllers/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\Http\Controllers;
use App\Business\PersonData;
use App\Models\Person;
use App\Views\PersonKeys;
use Illuminate\Database\Eloquent\Collection;
class DoctorsController extends PersonsController
{
protected function section(): string
{
return 'doctors';
}
// DOCTORS.TITLE, DOCTORS.ADD... (ver lang/*.json)
protected function keys(): PersonKeys
{
return PersonKeys::of('DOCTORS');
}
protected function listAll(): Collection
{
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 remove(int $id): void
{
$this->application->deleteDoctor($id);
}
}
|
Aquí solo queda especificar qué llamar (los métodos de [ApplicationModel]) y qué etiquetas mostrar (las claves [DOCTORS.xxx] de los diccionarios). El constructor se hereda de [PersonsController]: [ApplicationModel] está contenido en la propiedad [$this->application], declarada como [protected] (visible para las clases hijas). [ClientsController] es idéntico, con los métodos de cliente y las claves de [CLIENTS.xxx].
11.17.6. app/Http/Controllers/RegistrationController.php
| <?php
// =========================================================================
// app/Http/Controllers/RegistrationController.php: "Create a client account": un
// paciente que aún no tiene cuenta la crea por sí mismo. Rutas PÚBLICAS (por definición,
// aún no se tiene una cuenta):
//
// POST /register/access botón "Create a client account" de la página de
// login: verifica el captcha de ESTA
// página y luego abre el formulario
// GET /register el formulario
// POST /register la creación y luego regreso a la página de login
//
// El camino está protegido contra robots por UN captcha, el de la página de
// login:
// 1. el botón "Create a client account" envía el formulario de login a
// /register/access; si el captcha se copia correctamente, el servidor emite un
// pase (ver app/Auth/RegistrationPass.php);
// 2. sin un pase válido, /register redirige a la página de
// login (middleware CheckRegistrationPass);
// 3. el pase 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
// (ver app/Auth/AttemptLimiter.php).
//
// La cuenta creada es exactamente la que crearía el ADMIN desde la página "Clients"
// (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\Http\Controllers;
use App\Auth\CaptchaService;
use App\Auth\AttemptLimiter;
use App\Auth\RegistrationPass;
use App\Http\Requests\RegistrationRequest;
use App\Business\BusinessException;
use App\Web\ApplicationModel;
use App\Web\Flash;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\View\View;
class RegistrationController
{
// los campos que NUNCA se devuelven al navegador
private const PASSWORDS = ['password', 'password_confirmation'];
public function __construct(
private ApplicationModel $application,
private CaptchaService $captchas,
private AttemptLimiter $limiter,
private RegistrationPass $passes,
) {
}
// -----------------------------------------------------------------------
// POST /register/access campos: captchaId, captcha (los de la página de
// login; login y contraseña, también enviados, se ignoran)
// -----------------------------------------------------------------------
public function access(Request $request): RedirectResponse
{
$ip = (string) $request->ip();
// demasiadas cuentas creadas recientemente desde esta dirección: no hace falta ir más lejos
$minutes = $this->limiter->registrationBlockMinutes($ip);
if ($minutes > 0) {
Flash::error('ERRORS.TOO_MANY_ACCOUNTS', ['minutes' => $minutes]);
return redirect()->route('login');
}
// captcha ausente o incorrecto: regreso a la página de login, con una
// nueva imagen (un fallo cuenta como un fallo de login)
if (! $this->captchas->verify($request->input('captchaId'), $request->input('captcha'))) {
$this->limiter->loginFailure($ip, '');
Flash::error('ERRORS.CAPTCHA_BEFORE_ACCOUNT');
return redirect()->route('login');
}
// captcha correcto: emitimos el pase y abrimos el formulario
return redirect()->route('registration')
->withCookie(RegistrationPass::cookie($this->passes->issue()));
}
// -----------------------------------------------------------------------
// GET /register (el middleware ya verificó el pase)
// -----------------------------------------------------------------------
public function form(): View
{
return view('registration', ['pageTitle' => 'REGISTRATION.TITLE']);
}
// -----------------------------------------------------------------------
// POST /register. RegistrationRequest ya validó TODA la entrada (campos
// y confirmación de contraseña): el usuario corrige todos sus errores
// de una sola vez
// -----------------------------------------------------------------------
public function create(RegistrationRequest $request): RedirectResponse
{
$ip = (string) $request->ip();
// 1. ¿demasiadas cuentas creadas recientemente desde esta dirección?
$minutes = $this->limiter->registrationBlockMinutes($ip);
if ($minutes > 0) {
Flash::error('ERRORS.TOO_MANY_ACCOUNTS', ['minutes' => $minutes]);
return back()->withInput($request->except(self::PASSWORDS));
}
// 2. la creación (cliente + cuenta USER, en una transacción)
try {
$this->application->addClient($request->personData());
} catch (BusinessException $e) {
// login o nombre + apellido ya tomados: el pase sigue siendo válido
Flash::error($e->key, $e->params);
return back()->withInput($request->except(self::PASSWORDS))
->with('invalidFields', PersonsController::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
}
// 3. el pase fue usado: no permitirá crear una 2.ª cuenta
$this->passes->consume($request->cookie(RegistrationPass::COOKIE));
$this->limiter->registrationSuccess($ip);
// 4. regreso a la página de login, con el login prellenado
$login = $request->input('login');
Flash::success('REGISTRATION.DONE', ['login' => $login]);
return redirect()->route('login', ['login' => $login])
->withCookie(RegistrationPass::clearingCookie());
}
}
|
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 60–82: 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: regreso a la página de inicio de sesión con una imagen nueva y un mensaje; el fallo cuenta como un intento de inicio de sesión fallido (con un nombre de usuario vacío). Si el CAPTCHA es correcto: se almacena un token en una cookie y el usuario es redirigido al formulario;
- líneas 87–90: el formulario. El token ha sido verificado por el middleware [registration.pass] de la ruta;
- Líneas 97–127: la creación. [RegistrationRequest] ha validado todos los datos ingresados, incluida la confirmación de la contraseña: el usuario ve todos sus errores a la vez. El cliente y su cuenta se crean con el mismo método de la capa de negocio que 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: regreso al formulario, sin consumir el token. Crear 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 rellenado previamente ([route('login', ['login' => $login])] agrega el parámetro [?login=...]), junto con un mensaje de éxito. La cookie del pase se borra.
La constante [PASSWORDS] (línea 46) enumera los campos que nunca deben reenviarse al navegador: [back()->withInput()], sin parámetro, conservaría toda la entrada para el siguiente formulario, incluidas las contraseñas; [$request->except([...])] reenvía el formulario sin estos campos. Cuando [Laravel] regresa al formulario (por un error de validación), excluye automáticamente los campos [password], [password_confirmation], y [current_password].
11.17.7. app/Http/Controllers/PatientAreaController.php
| <?php
// =========================================================================
// app/Http/Controllers/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 próxima cita
// 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
// (Utils::connectedPatient), nunca un identificador enviado por el navegador. Un
// paciente por lo tanto no puede ver, ni modificar, ni cancelar lo que pertenece a otro
// paciente, ni siquiera construyendo él mismo sus solicitudes.
//
// Cualquier modificación o eliminación de la cuenta exige la contraseña ACTUAL:
// alguien que encontrara 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 login (mismo límite).
// =========================================================================
namespace App\Http\Controllers;
use App\Auth\AuthService;
use App\Auth\AttemptLimiter;
use App\Http\Requests\MyAccountRequest;
use App\Business\BusinessException;
use App\Models\Client;
use App\Models\Appointment;
use App\Views\AppointmentView;
use App\Web\ApplicationModel;
use App\Web\Flash;
use App\Web\Message;
use App\Web\Utils;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\View\View;
class PatientAreaController
{
public function __construct(
private ApplicationModel $application,
private AuthService $auth,
private AttemptLimiter $limiter,
) {
}
// -----------------------------------------------------------------------
// GET /my-area
// -----------------------------------------------------------------------
public function patientArea(): View
{
$patient = Utils::connectedPatient($this->application);
$appointments = $this->application->getClientUpcomingAppointments($patient->id)->map(fn (Appointment $a) => new AppointmentView(
$a->id,
Utils::formatDay($a->day),
$a->slot->time(),
$a->slot->doctor->label(),
// enlace a la agenda del médico en ese día: el paciente ve allí su nombre
route('schedule', ['doctorId' => $a->slot->doctor_id, 'day' => Utils::iso($a->day)])))
->all();
return view('area', ['pageTitle' => 'AREA.TITLE', 'patient' => $patient->label(),
'appointments' => $appointments]);
}
// -----------------------------------------------------------------------
// POST /my-area/cancel campo: appointmentId
// -----------------------------------------------------------------------
public function cancelAppointment(Request $request): RedirectResponse
{
$patient = Utils::connectedPatient($this->application);
$appointmentId = Utils::positiveInteger($request->input('appointmentId'));
$appointment = $appointmentId !== null ? $this->application->getAppointmentById($appointmentId) : null;
// una cita que no existe y la de OTRO paciente reciben la
// misma respuesta: no revelamos nada sobre las citas de los demás
if ($appointment === null || $appointment->client_id !== $patient->id) {
Flash::error('ERRORS.APPOINTMENT_NOT_FOUND');
} else {
$this->application->deleteAppointment($appointment);
Flash::success('SCHEDULE.CANCELLED');
}
return redirect()->route('area');
}
// -----------------------------------------------------------------------
// GET /my-account: el formulario, prellenado con los valores del paciente
// -----------------------------------------------------------------------
public function accountForm(): View
{
$patient = Utils::connectedPatient($this->application);
return view('account', ['pageTitle' => 'MY_ACCOUNT.TITLE', 'patient' => $patient]);
}
// -----------------------------------------------------------------------
// POST /my-account (MyAccountRequest validó la entrada)
// -----------------------------------------------------------------------
public function editAccount(MyAccountRequest $request): RedirectResponse
{
$patient = Utils::connectedPatient($this->application);
// la contraseña actual; si es incorrecta: el mensaje va DEBAJO del campo y al final de la página
$error = $this->checkCurrentPassword($request, $patient, $request->input('current_password'));
if ($error !== null) {
Flash::error($error->key, $error->params);
return back()->withInput($request->except(['password', 'password_confirmation', 'current_password']))
->withErrors(['current_password' => __($error->key, $error->params)]);
}
try {
$client = $this->application->editClient($patient->id, $request->personData());
} catch (BusinessException $e) {
Flash::error($e->key, $e->params);
return back()->withInput($request->except(['password', 'password_confirmation', 'current_password']))
->with('invalidFields', PersonsController::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
}
// el login y el nombre mostrado ESTÁN en el token: emitimos uno nuevo,
// de lo contrario la barra de navegación conservaría el nombre anterior
Flash::success('MY_ACCOUNT.UPDATED');
return redirect()->route('area')->withCookie($this->auth->tokenCookie($client->account));
}
// -----------------------------------------------------------------------
// POST /my-account/delete campo: current_password
// La cuenta, el cliente y TODAS sus citas desaparecen juntos, y luego el
// paciente cierra sesión.
// -----------------------------------------------------------------------
public function deleteAccount(Request $request): RedirectResponse
{
$patient = Utils::connectedPatient($this->application);
$error = $this->checkCurrentPassword($request, $patient, $request->input('current_password'));
if ($error !== null) {
Flash::error($error->key, $error->params);
return redirect()->route('account');
}
$this->application->deleteClient($patient->id);
Flash::success('MY_ACCOUNT.DELETED');
return redirect()->route('login')->withCookie(AuthService::clearingCookie());
}
// funciones internas
// 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->ip();
$login = $patient->account->login;
$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 de otro paciente, aunque construya sus propias solicitudes.
- líneas 53–66: 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 71–85: cancelación de la cita del paciente. Una cita inexistente y 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 90–94: el formulario “Administrar mi cuenta”, rellenado previamente con la información del paciente;
- líneas 99–122: la modificación. Toda modificación requiere la contraseña actual: alguien que encontrara una sesión abierta no podría cambiar la contraseña ni hacer nada más. Una contraseña actual incorrecta: regreso al formulario, con un mensaje debajo del campo ([withErrors] agrega un error de entrada, como si la validación lo hubiera detectado) y en la parte inferior de la página (mensaje flash). Después de la edición, se genera un nuevo token : el inicio de sesión y el nombre para mostrar se incluyen en el token; de lo contrario, la barra de navegación conservaría el nombre anterior hasta el siguiente inicio de sesión;
- líneas 129–140: eliminación de la cuenta, del cliente y de todas sus citas, con el mismo método de lógica de negocio que para el administrador. Se requiere la contraseña actual; luego se cierra la sesión del paciente (cookie del token borrada);
- líneas 145–158: 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.18. Las vistas
Las vistas [Blade] de la carpeta [resources/views]: una plantilla, fragmentos, componentes y páginas.
11.18.1. La plantilla y los fragmentos
11.18.1.1. resources/views/layout.blade.php
| <!doctype html>
{{-- =========================================================================
resources/views/layout.blade.php
-------------------------------------------------------------------------
La plantilla base COMÚN a todas las páginas (véase el ejemplo 15): cada página
(schedule.blade.php, login.blade.php...) la EXTIENDE (@extends) y llena su
sección [content].
Blade ESCAPA todo lo que muestra con {{ ... }} (los caracteres < > & " '
se convierten en < >...): protección contra la inyección de HTML mediante un
nombre escrito, por ejemplo. Para insertar HTML tal cual, debe solicitarse
explícitamente ({!! ... !!}, véase components/captcha.blade.php).
Mensajes: un éxito se muestra en la PARTE SUPERIOR de la página, un error en la INFERIOR, sobre un
fondo rosa claro (fragmento errors).
La plantilla base comparte las variables de la página: [pageTitle] (la clave del título de
la página, pasada por la acción); [language] y [user], agregadas a todas
las vistas por AppServiceProvider.
========================================================================= --}}
<html lang="{{ $language }}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
{{-- __($key): la traducción de una clave; aquí, la clave es una VARIABLE --}}
<title>{{ __($pageTitle) }} - {{ __('APP.TITLE') }}</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')
@include('fragments.success')
<main>
@yield('content')
</main>
@include('fragments.errors')
</div>
{{-- el cuadro de diálogo "Are you sure?", oculto mientras no se necesite --}}
@include('fragments.confirmation')
<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')]) y completa su sección [content] (línea 36).
- línea 21: el idioma de la página, [fr] o [en], proporcionado a todas las vistas por el view composer [AppServiceProvider];
- línea 26: el título de la página, traducido: [__($pageTitle)] traduce la clave contenida en la variable [$pageTitle], que cada acción pasa a su vista;
- líneas 28–29: la función [asset] genera 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): acceden a las variables de la página;
- línea 41: la ventana “¿Está seguro?”, que permanece oculta hasta que se necesita, y el script que la muestra.
[Blade] escapa todo lo que muestra mediante [{{ ... }}] (Ejemplo 14): un nombre ingresado que contenga HTML ([<script>]) se muestra tal cual, sin ser interpretado. Esto evita que se inyecte HTML (XSS) sin esfuerzo en todas las páginas.
11.18.1.2. resources/views/fragments/navbar.blade.php
| {{-- =========================================================================
resources/views/fragments/navbar.blade.php - 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 "Clients" solo aparecen para el ADMIN. Es
solo una comodidad de visualización: la protección real son los middlewares de las
rutas (un USER que escribe /doctors a mano obtiene una página 403). Un paciente
(USER) tiene además su menú "My area".
El menú de la página actual se resalta (clase "active"):
request()->is('schedule*') es verdadero si la ruta de la URL empieza con "schedule".
Las entradas del menú: un arreglo [URL, clave de etiqueta, patrón de las rutas para
las que la entrada está activa], recorrido por @foreach.
========================================================================= --}}
@php
$menu = [];
if ($user) {
if ($user->isPatient()) {
// activo para /my-area Y /my-account
$menu[] = [route('area'), 'APP.MENU_MY_AREA', 'my-*'];
}
$menu[] = [route('schedule'), 'APP.MENU_SCHEDULE', 'schedule*'];
if ($user->isAdmin()) {
$menu[] = [route('doctors.list'), 'APP.MENU_DOCTORS', 'doctors*'];
$menu[] = [route('clients.list'), 'APP.MENU_PATIENTS', 'clients*'];
}
}
@endphp
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
<span class="navbar-brand mb-0">{{ __('APP.TITLE') }}</span>
<ul class="navbar-nav me-auto">
@foreach ($menu as [$href, $key, $pattern])
<li class="nav-item">
{{-- @class: the classes whose condition is true --}}
<a @class(['nav-link', 'active' => request()->is($pattern)]) href="{{ $href }}">{{ __($key) }}</a>
</li>
@endforeach
</ul>
<div class="d-flex align-items-center gap-2">
{{-- FR / EN: simple links (GET /language/fr), the active language highlighted --}}
<div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
@foreach (['fr', 'en'] as $code)
<a class="btn {{ $language === $code ? 'btn-light' : 'btn-outline-light' }}"
href="{{ route('language', ['code' => $code]) }}">{{ strtoupper($code) }}</a>
@endforeach
</div>
@if ($user)
<span class="badge text-bg-light text-primary">{{ $user->role->value }}</span>
<span class="text-white">{{ $user->name }}</span>
{{-- el cierre de sesión es un POST: un formulario reducido a su botón (y al token anti-CSRF) --}}
<form method="post" action="{{ route('logout') }}" class="m-0">
@csrf
<button type="submit" class="btn btn-sm btn-outline-light">{{ __('APP.LOGOUT') }}</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 del middleware de las rutas (un paciente que escriba manualmente [/doctors] recibirá una página 403).
- Líneas 15–28: el menú se define en un bloque [@php] (Ejemplo 14), un arreglo de entradas: URL (la clave de la etiqueta) y el patrón de rutas para las que la entrada está activa. [request()->is('schedule*')] es verdadero si la ruta de la URL solicitada coincide con el patrón ([*]: cualquier secuencia de caracteres). La entrada “Mi área” está activa para [/my-area] y [/my-account] (patrón [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 33–38: [@foreach] descompone cada entrada del arreglo en tres variables (ejemplo 25). [@class([...])] (ejemplo 16) escribe el atributo [class] con las clases para las que la condición es verdadera;
- líneas 44–47: los botones FR / EN, enlaces simples ([/language/fr]), con el idioma activo resaltado;
- líneas 50–58: para un usuario que inició sesión, su rol ([$user->role->value]: la cadena que representa el 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], ejemplo 18).
11.18.1.3. resources/views/fragments/success.blade.php
| {{-- =========================================================================
resources/views/fragments/success.blade.php - los mensajes de ÉXITO puestos
por la acción anterior (cita reservada, médico agregado...), mostrados
una sola vez, en la parte superior de la página (véase app/Web/Flash.php). Un mensaje flash
de ERROR, por su parte, se muestra en la parte inferior de la página, por el fragmento errors.
Cada mensaje es un objeto Message: __($message->key, $message->params)
es el texto de la clave, donde :name, :login... se reemplazan por sus valores.
========================================================================= --}}
@foreach (session('flash_success', []) as $message)
<div class="alert alert-success" role="status">{{ __($message->key, $message->params) }}</div>
@endforeach
|
Los mensajes flash de éxito, establecidos por la acción anterior ([Flash::success]), se leen de la sesión mediante [session('flash_success', [])] (una lista vacía por defecto). Cada uno es un objeto [Message], traducido aquí al idioma de la página: [__($message->key, $message->params)]. [role="status"]: un lector de pantalla anuncia el mensaje.
11.18.1.4. resources/views/fragments/errors.blade.php
| {{-- =========================================================================
resources/views/fragments/errors.blade.php - la zona de errores, en la PARTE INFERIOR de
cada página, sobre un fondo rosa claro (clase .error-zone, véase public/css/styles.css).
Reúne las tres posibles fuentes de errores:
- $error: el error de la página mostrada (fecha inválida, captcha mal
copiado...), pasado por la acción;
- los mensajes flash de error, puestos por la acción anterior antes de una
redirección (horario ya reservado, login ya tomado, eliminación rechazada...);
- los errores de entrada ($errors, véase el ejemplo 19): sus mensajes se
muestran BAJO los campos; aquí, si no hay ningún 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 en cuanto la
página se muestra, aunque esté en la parte inferior.
========================================================================= --}}
@php
$messages = session('flash_errors', []);
if ($error ?? null) {
array_unshift($messages, $error);
}
if (! $messages && $errors->any()) {
$messages[] = new App\Web\Message('ERRORS.INVALID_FORM');
}
@endphp
@if ($messages)
<div class="error-zone" role="alert">
@foreach ($messages as $message)
<div>{{ __($message->key, $message->params) }}</div>
@endforeach
</div>
@endif
|
El área de errores, en la parte inferior de cada página, sobre un fondo rosa claro. Enumera las tres posibles fuentes de error:
- el error de la página mostrada ([$error]), provocado por la acción: una fecha no válida, un CAPTCHA mal escrito, etc. [$error ?? null]: la variable no existe en todas las páginas; el operador [??] no marca una variable inexistente: la reemplaza por [null];
- mensajes de error flash, provocados por la acción anterior (un intervalo ya reservado, un nombre de usuario ya en uso, etc.);
- errores de entrada ([$errors], ejemplo 19): sus mensajes se muestran debajo de los campos; aquí, si no hay otros mensajes, aparece una frase sencilla: “El formulario contiene errores”. En un formulario largo, esto le indica al usuario que debe volver a subir.
[array_unshift] agrega un elemento al principio de un arreglo. [role="alert"]: un lector de pantalla anuncia el mensaje en cuanto se muestra la página, incluso si está en la parte inferior. El área permanece anclada en la parte inferior de la ventana cuando la página es larga (véase la hoja de estilos, más abajo).
11.18.1.5. resources/views/fragments/confirmation.blade.php
| {{-- =========================================================================
resources/views/fragments/confirmation.blade.php - el cuadro de diálogo modal
"Are you sure?" (véase el ejemplo 21).
Reemplaza el cuadro window.confirm() del navegador, que no se puede estilizar
ni traducir (sus botones se quedan en el idioma del navegador, no
en el de la página).
UN SOLO cuadro de 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 colocar 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') }}</h5>
<button type="button" class="btn-close" data-action="no" aria-label="{{ __('BOOKING_DIALOG.CLOSE_ARIA') }}"></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 a veces es
"Cancel this appointment?", y un botón "Cancel" sería ambiguo ahí --}}
<button type="button" class="btn btn-secondary" data-action="no">{{ __('CONFIRMATION.NO') }}</button>
<button type="button" class="btn btn-danger" data-action="yes">{{ __('CONFIRMATION.YES') }}</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: este 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] procedente 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 su interior el mensaje del formulario por confirmar (su atributo [data-confirmation]) y envía el formulario si el usuario confirma. El botón “Cancelar” se etiqueta “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.18.1.6. resources/views/fragments/booking.blade.php
| {{-- =========================================================================
resources/views/fragments/booking.blade.php - la ventana de reserva
de la agenda.
Las clases REALES de Bootstrap de un cuadro de diálogo modal (.modal, .modal-backdrop...),
hechas visibles "de forma fija" (show d-block) en lugar de mediante el
JavaScript de Bootstrap. Es el SERVIDOR quien decide mostrarla (parámetro &book=...
de la URL), y cerrarla 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="{{ route('schedule.book') }}" class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="booking-title">{{ __('BOOKING_DIALOG.TITLE') }}</h5>
<a class="btn-close" href="{{ $backUrl }}" aria-label="{{ __('BOOKING_DIALOG.CLOSE_ARIA') }}"></a>
</div>
<div class="modal-body">
<p>{{ __('BOOKING_DIALOG.SLOT', ['time' => $booking->time]) }}</p>
{{-- lo que el servidor debe saber además del paciente elegido --}}
@csrf
<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 para elegir (y el
servidor ignora de todos modos un posible clientId) --}}
@if ($booking->patient)
<p class="mb-0">
<span>{{ __('BOOKING_DIALOG.PATIENT_LABEL') }}</span>:
<strong>{{ $booking->patient }}</strong>
</p>
@else
<label class="form-label" for="clientId">{{ __('BOOKING_DIALOG.PATIENT_LABEL') }}</label>
<select id="clientId" name="clientId" class="form-select" required autofocus>
<option value="">{{ __('BOOKING_DIALOG.CHOOSE_PATIENT') }}</option>
@foreach ($booking->clients as $client)
<option value="{{ $client->id }}">{{ $client->label }}</option>
@endforeach
</select>
@endif
</div>
<div class="modal-footer">
<a class="btn btn-secondary" href="{{ $backUrl }}">{{ __('BOOKING_DIALOG.CANCEL') }}</a>
<button type="submit" class="btn btn-primary">{{ __('BOOKING_DIALOG.CONFIRM') }}</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 de forma “fija en el código” ([show d-block]), en lugar de mediante el [JavaScript] de [Bootstrap]: es el servidor el que decide mostrarla cuando la URL contiene [&book=...]. Cerrarla (con la X o con 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 el intervalo;
- líneas 34–47: un paciente hace una reserva para sí mismo: su nombre, sin lista para elegir (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.18.2. Los componentes
Tres componentes anónimos (Ejemplo 15), en la carpeta [resources/views/components], que las páginas usan en forma de etiqueta [<x-name>].
11.18.2.1. resources/views/components/field.blade.php
| {{-- =========================================================================
resources/views/components/field.blade.php - un campo de entrada, su etiqueta,
su mensaje de error o su ayuda (véase el ejemplo 19): <x-field name="login" ... />
@props: los atributos esperados por el componente, con su valor por defecto.
El valor mostrado: old($name, $value), la entrada que se vuelve a mostrar tras un rechazo,
de lo contrario el valor dado. Una contraseña NUNCA se vuelve a mostrar.
El campo se resalta en rojo (clase de Bootstrap is-invalid) si tiene un error
de entrada ($errors), o si un error de negocio lo designa (invalidFields, véase
PersonsController::businessError); el mensaje de error reemplaza entonces a la ayuda.
========================================================================= --}}
@props(['name', 'label', 'type' => 'text', 'value' => null, 'help' => null, 'max' => null,
'autocomplete' => null, 'required' => false])
@php
$invalid = $errors->has($name) || in_array($name, session('invalidFields', []), true);
@endphp
<label class="form-label" for="{{ $name }}">{{ $label }}</label>
<input id="{{ $name }}" name="{{ $name }}" type="{{ $type }}" @class(['form-control', 'is-invalid' => $invalid])
@if ($type !== 'password') value="{{ old($name, $value) }}" @endif
@if ($max) maxlength="{{ $max }}" @endif
@if ($autocomplete) autocomplete="{{ $autocomplete }}" @endif
@required($required)>
@error($name)
<div class="invalid-feedback">{{ $message }}</div>
@else
@if ($help)
<div class="form-text">{{ $help }}</div>
@endif
@enderror
|
Un campo de entrada, con su etiqueta, mensaje de error o información sobre herramientas: el componente [x-field] del Ejemplo 19, totalmente configurado.
- Línea 12: los atributos del componente y sus valores predeterminados. En una página, [<x-field name="login" :label="__('PERSONS.LOGIN_LABEL')" max="30" required />]: a un atributo precedido por [:] se le asigna el valor de una expresión [PHP], mientras que a los demás se les asigna una cadena; un atributo sin valor ([required]) se establece en [true];
- líneas 14–16: el campo es no válido si contiene un error de entrada ([$errors->has($name)]), o si un error de la capa de negocio lo señala como tal: la lista [invalidFields], almacenada en la sesión por la acción ([PersonsController::businessError]). Un nombre de usuario que ya está en uso no es un error de entrada (tiene el formato correcto), pero el usuario debe ver qué campo corregir;
- líneas 18–22: el valor mostrado es [old($name, $value)]: la entrada que debe volver a mostrarse después de un rechazo; de lo contrario, el valor transmitido por la página (el del registro modificado). Una contraseña nunca se vuelve a mostrar: no hay atributo [value] para un campo [password]. [@required($required)] establece el atributo booleano [required] si la condición es verdadera;
- líneas 23–29: el mensaje de error del campo ([$message], ejemplo 19) o, en su defecto, la ayuda disponible. La clase [invalid-feedback] de [Bootstrap] solo es visible después de un campo de clase [is-invalid].
11.18.2.2. resources/views/components/person-fields.blade.php
| {{-- =========================================================================
resources/views/components/person-fields.blade.php - los campos de identidad
(título, nombre, apellido), comunes a tres formularios: médico/cliente del ADMIN,
"Create a client account" y "Manage my account": <x-person-fields :person="..." />
:person: la persona cuyos valores se muestran (null para un formulario
vacío). $person?->title: null si $person es null (operador "nullsafe").
La lista de títulos proviene de la clase que los valida (PersonFieldsRequest).
========================================================================= --}}
@props(['person' => null])
@php
$chosenTitle = old('title', $person?->title ?? 'Mr');
@endphp
<div class="mb-3">
<label class="form-label" for="title">{{ __('PERSONS.TITLE_LABEL') }}</label>
<select id="title" name="title" @class(['form-select', 'is-invalid' => $errors->has('title')])>
@foreach (App\Http\Requests\PersonFieldsRequest::TITLES as $title)
<option value="{{ $title }}" @selected($title === $chosenTitle)>{{ $title }}</option>
@endforeach
</select>
@error('title')
<div class="invalid-feedback">{{ $message }}</div>
@enderror
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<x-field name="first_name" :label="__('PERSONS.FIRSTNAME_LABEL')" :value="$person?->first_name" max="20" required />
</div>
<div class="col-sm-6">
<x-field name="last_name" :label="__('PERSONS.LASTNAME_LABEL')" :value="$person?->last_name" max="20" required />
</div>
</div>
|
Campos de identidad comunes a tres formularios: título (una lista), nombre y apellido (dos campos [x-field]: un componente puede usar otro componente). El atributo [person] es la persona cuyos valores se muestran, o [null] para un formulario vacío. [$person?->title]: el operador null-safe devuelve [null] si [$person] es null. La lista de títulos proviene de la clase que los valida ([PersonFieldsRequest::TITLES]): la regla se escribe una sola vez. [@selected(...)] escribe el atributo [selected] de la opción seleccionada.
11.18.2.3. resources/views/components/captcha.blade.php
| {{-- =========================================================================
resources/views/components/captcha.blade.php - el captcha de la página de
inicio de sesión (véase app/Auth/CaptchaService.php). Protege tanto el
inicio de sesión como el acceso a la creación de cuenta (botón "Create a client account").
{!! ... !!}: 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 se haría esto con una entrada del usuario.
El campo oculto captchaId le indica al servidor CUÁL captcha verificar; la respuesta
correcta, por su parte, nunca se envía al navegador. "Another image" simplemente
recarga la página (url()->current(): la URL de la página, sin sus parámetros).
========================================================================= --}}
@props(['captcha'])
<div class="mb-3">
<label class="form-label" for="captcha">{{ __('CAPTCHA.LABEL') }}</label>
<div class="d-flex align-items-center gap-3 mb-2">
<div class="captcha-image" role="img" aria-label="{{ __('CAPTCHA.IMAGE_ALT') }}">{!! $captcha->svg !!}</div>
<a class="small" href="{{ url()->current() }}">{{ __('CAPTCHA.NEW_IMAGE') }}</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') }}</div>
</div>
|
El CAPTCHA (ejemplo 27). [{!! $captcha->svg !!}] inserta la imagen SVG tal cual, sin escaparla; de lo contrario, el navegador mostraría su código XML. Aquí es seguro porque este SVG lo genera el servidor y no contiene nada proporcionado por el usuario: nunca haríamos esto con entradas del 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 ([url()->current()]: la URL de la página, sin sus parámetros) y, con ella, el CAPTCHA.
11.18.3. Las páginas
11.18.3.1. resources/views/login.blade.php
| {{-- =========================================================================
resources/views/login.blade.php - el formulario de inicio de sesión (véase
AuthController). Un <form> HTML ordinario: el propio navegador envía
el login, la contraseña y la respuesta del captcha en POST /login, sin JavaScript. En
caso de fallo, el servidor devuelve ESTA página, con el login ya escrito, un
NUEVO captcha y el error, mostrado en la parte inferior de la página por la plantilla base.
========================================================================= --}}
@extends('layout')
@section('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') }}</h5>
<form method="post" action="{{ route('login') }}">
@csrf
<div class="mb-3">
<label class="form-label" for="login">{{ __('LOGIN.LOGIN_LABEL') }}</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 @if ($login === '') autofocus @endif>
</div>
<div class="mb-3">
<label class="form-label" for="password">{{ __('LOGIN.PASSWORD_LABEL') }}</label>
<input id="password" name="password" type="password" class="form-control"
autocomplete="current-password" required @if ($login !== '') autofocus @endif>
</div>
<x-captcha :captcha="$captcha" />
<button type="submit" class="btn btn-primary w-100">{{ __('LOGIN.SUBMIT') }}</button>
{{-- aún 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). Allí el servidor verifica el
captcha de arriba antes de abrir la página de creación de cuenta (véase
RegistrationController). formnovalidate: el navegador no exige
login ni contraseña (inútil para crear una cuenta). Enter en un
campo siempre activa el PRIMER botón del formulario, "Log in". --}}
<button type="submit" class="btn btn-outline-primary w-100 mt-3"
formaction="{{ route('registration.access') }}" formnovalidate>{{ __('LOGIN.CREATE_ACCOUNT') }}</button>
<div class="form-text text-center">{{ __('LOGIN.CREATE_ACCOUNT_HELP') }}</div>
</form>
<div class="text-muted small mt-3">
<span>{{ __('LOGIN.DEMO_ACCOUNTS') }}</span>
<ul class="mb-0 mt-1">
<li><code>admin</code> - <span>{{ __('LOGIN.DEMO_ADMIN') }}</span></li>
<li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - <span>{{ __('LOGIN.DEMO_DOCTOR') }}</span></li>
<li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - <span>{{ __('LOGIN.DEMO_USER') }}</span></li>
</ul>
</div>
</div>
</div>
</div>
@endsection
|
El formulario de inicio de sesión, un [<form>] estándar, se envía mediante POST a [/login].
- Líneas 22–23: el nombre de usuario ingresado se vuelve a mostrar después de un intento de inicio de sesión fallido ([$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);
- 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 diferente (atributo de 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.18.3.2. resources/views/schedule.blade.php
| {{-- =========================================================================
resources/views/schedule.blade.php - la página principal (véase ScheduleController).
Tres bloques:
1. la elección del médico y del día;
2. la agenda;
3. la ventana de reserva (fragmento booking).
Un posible error (fecha inválida, médico desconocido) se muestra en la parte inferior de
la página por la plantilla base (fragmento errors).
========================================================================= --}}
@extends('layout')
@section('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="{{ route('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') }}</label>
<select id="doctorId" name="doctorId" class="form-select" required>
<option value="">{{ __('DOCTOR_DAY_PICKER.CHOOSE_DOCTOR') }}</option>
@foreach ($doctors as $doctor)
<option value="{{ $doctor->id }}" @selected($doctor->selected)>{{ $doctor->label }}</option>
@endforeach
</select>
</div>
<div class="col-sm-4">
<label class="form-label" for="day">{{ __('DOCTOR_DAY_PICKER.DAY_LABEL') }}</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') }}</button>
</div>
</div>
</form>
{{-- patient who already has an upcoming appointment: why there is no "Book" button --}}
@if ($info)
<div class="alert alert-info">
<span>{{ __($info) }}</span>
<a href="{{ route('area') }}" class="alert-link">{{ __('APP.MENU_MY_AREA') }}</a>
</div>
@endif
{{-- 2. the schedule --}}
@if ($schedule)
<div class="card p-3">
<h5>{{ __('SCHEDULE.TITLE_PREFIX') }} {{ $schedule->day }} - {{ $schedule->doctor }}</h5>
@if ($schedule->rows)
<table class="table table-hover align-middle">
<thead>
<tr>
<th>{{ __('SCHEDULE.COLUMN_SLOT') }}</th>
<th>{{ __('SCHEDULE.COLUMN_STATUS') }}</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach ($schedule->rows as $row)
<tr @class(['free-slot' => $row->bookable])>
<td>{{ $row->time }}</td>
<td>
{{-- [patient] solo se define 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') }}</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') }}</span>
@endif
</td>
<td>
{{-- los botones mostrados fueron decididos por el controlador (bookable,
appointmentId) según el rol del usuario. "Book" es un simple
enlace: reabre esta página con la ventana de reserva de este horario --}}
@if ($row->bookable)
<a class="btn btn-sm btn-outline-success" href="{{ $row->bookUrl }}">{{ __('SCHEDULE.BOOK') }}</a>
@endif
{{-- "Cancel" MODIFICA datos: por lo tanto es un POST --}}
@if ($row->appointmentId)
<form method="post" action="{{ route('schedule.cancel') }}" class="m-0"
data-confirmation="{{ __('SCHEDULE.CANCEL_CONFIRM') }}">
@csrf
<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') }}</button>
</form>
@endif
</td>
</tr>
@endforeach
</tbody>
</table>
@else
<p class="text-muted mb-0">{{ __('SCHEDULE.NO_SLOTS') }}</p>
@endif
</div>
@else
<p class="text-muted">{{ __('SCHEDULE.EMPTY_STATE') }}</p>
@endif
{{-- 3. la ventana de reserva, solo si la URL contiene &book=... --}}
@if ($booking)
@include('fragments.booking')
@endif
@endsection
|
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 la 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 hay botón “Reservar”;
- líneas 66–72: el estado del intervalo: “Libre” (en verde), el nombre del paciente (en azul para la cita del paciente que inició sesión, 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 ese intervalo ([$row->bookUrl]). No modifica nada: basta con un GET;
- líneas 82–91: “Cancelar” modifica datos: es un formulario POST (ejemplo 21), con su token anti-CSRF, la cita que se cancelará y la información para volver 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 el intervalo está disponible para reservar).
11.18.3.3. resources/views/persons/list.blade.php
| {{-- =========================================================================
resources/views/persons/list.blade.php - la lista de los médicos O de los
clientes (ADMIN). Una sola vista para ambos: las claves de las etiquetas específicas de
cada uno llegan en $keys, y $section ("doctors" o "clients") da el
inicio de los nombres de las rutas (véase PersonsController).
========================================================================= --}}
@extends('layout')
@section('content')
<div class="d-flex justify-content-between align-items-center mb-3">
<h4 class="mb-0">{{ __($keys->title) }}</h4>
<a class="btn btn-primary" href="{{ route("$section.addForm") }}">{{ __($keys->add) }}</a>
</div>
<div class="card p-3">
@if ($persons->isNotEmpty())
<table class="table table-hover align-middle mb-0">
<thead>
<tr>
<th>{{ __('PERSONS.COLUMN_TITLE') }}</th>
<th>{{ __('PERSONS.COLUMN_FIRSTNAME') }}</th>
<th>{{ __('PERSONS.COLUMN_LASTNAME') }}</th>
<th>{{ __('PERSONS.COLUMN_LOGIN') }}</th>
<th></th>
</tr>
</thead>
<tbody>
@foreach ($persons as $person)
<tr>
<td>{{ $person->title }}</td>
<td>{{ $person->first_name }}</td>
<td>{{ $person->last_name }}</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="{{ route("$section.editForm", ['id' => $person->id]) }}">{{ __('PERSONS.EDIT') }}</a>
{{-- data-confirmation: se abrirá un cuadro de diálogo de confirmación antes de
enviar el formulario (véase public/js/app.js) --}}
<form method="post" action="{{ route("$section.delete", ['id' => $person->id]) }}" class="m-0"
data-confirmation="{{ __($keys->confirmDelete) }}">
@csrf
<button type="submit" class="btn btn-sm btn-outline-danger">{{ __('PERSONS.DELETE') }}</button>
</form>
</div>
</td>
</tr>
@endforeach
</tbody>
</table>
@else
<p class="text-muted mb-0">{{ __($keys->empty) }}</p>
@endif
</div>
@endsection
|
La lista de médicos o clientes: las etiquetas específicas de cada uno son claves de traducción ([$keys]), y los valores de las URL se generan a partir del nombre de la sección ([route("$section.editForm", ['id' => ...])]: en una cadena entre comillas, [$section] se reemplaza por su valor, [doctors] o [clients]). [$person->account?->login]: el inicio de sesión de la cuenta, cargado con la lista ([with('account')], capa DAO). [isNotEmpty()]: la colección no está vacía. El botón Eliminar es un formulario POST, con confirmación.
| {{-- =========================================================================
resources/views/persons/form.blade.php - creación O modificación de un
médico o de un cliente (ADMIN). $creating distingue los dos casos; $person
es la persona modificada (null en una creación).
Cuando se rechaza la entrada (campo vacío, login ya tomado...), la acción devuelve
el navegador a ESTA página (redirección), y la vista muestra:
- los valores ya escritos (old(), en los componentes x-field);
- los campos erróneos resaltados en rojo (clase de Bootstrap "is-invalid");
- bajo un campo rechazado por la validación, su mensaje;
- el mensaje de error de la página, en la PARTE INFERIOR de la página (fragmento errors).
========================================================================= --}}
@extends('layout')
@section('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) }}</h5>
{{-- novalidate: dejamos que el SERVIDOR valide (es quien tiene la autoridad); las
comprobaciones del navegador (required...) son solo una comodidad, que un
usuario siempre puede eludir --}}
<form method="post" action="{{ $action }}" novalidate>
@csrf
@unless ($creating)
{{-- la versión del registro mostrado: el bloqueo optimista --}}
<input type="hidden" name="version" value="{{ old('version', $person->version) }}">
@endunless
{{-- title, first name, last name: component common to three forms --}}
<x-person-fields :person="$person" />
<h6 class="mt-4 text-muted">{{ __('PERSONS.ACCOUNT_SECTION') }}</h6>
<div class="mb-3">
<x-field name="login" :label="__('PERSONS.LOGIN_LABEL')" :value="$person?->account?->login"
max="30" autocomplete="off"
:help="__($creating ? 'PERSONS.LOGIN_HELP_CREATE' : 'PERSONS.LOGIN_HELP_EDIT')" />
</div>
<div class="mb-4">
{{-- nunca se rellena de antemano: la contraseña nunca vuelve al navegador --}}
<x-field name="password" type="password" :label="__('PERSONS.PASSWORD_LABEL')" max="72"
autocomplete="new-password"
:help="__($creating ? 'PERSONS.PASSWORD_HELP_CREATE' : 'PERSONS.PASSWORD_HELP_EDIT')" />
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{ __('PERSONS.SAVE') }}</button>
<a class="btn btn-secondary" href="{{ $listUrl }}">{{ __('PERSONS.BACK') }}</a>
</div>
</form>
</div>
</div>
</div>
@endsection
|
Creación o edición de un médico o de un cliente.
- Línea 24: el atributo [novalidate] desactiva los controles del navegador ([required], [maxlength]...) al enviar el formulario: el servidor valida el formulario y su validación es definitiva. Los validadores del navegador son solo una comodidad que cualquiera puede eludir; desactivarlos aquí permite ver los mensajes del servidor;
- Líneas 26–29: [@unless] (“a menos que”) es lo opuesto de [@if]. Durante una modificación, la versión del registro (el bloqueo optimista) se almacena en un campo oculto;
- línea 32: título, nombre y apellido, rellenados previamente con los valores de la persona;
- líneas 37–44: el nombre de usuario, rellenado previamente con el nombre de usuario de la cuenta ([$person?->account?->login]: dos operadores null-safe encadenados) y la contraseña, que nunca se rellena previamente. Sus información sobre herramientas difieren para la creación (“por defecto, el apellido en minúsculas”) y para la edición (“Déjelo vacío para conservarlo sin cambios”).
11.18.3.5. resources/views/registration.blade.php
| {{-- =========================================================================
resources/views/registration.blade.php - "Create a client account" (página
pública, véase RegistrationController). Mismos campos de identidad que el formulario
del ADMIN (componente x-person-fields), pero el login y la
contraseña son obligatorios, con confirmación. Sin captcha AQUÍ: 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 client account").
========================================================================= --}}
@extends('layout')
@section('content')
@php($min = App\Http\Requests\PersonFieldsRequest::PASSWORD_MIN)
<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') }}</h5>
<p class="text-muted small mb-3">{{ __('REGISTRATION.INTRO') }}</p>
<form method="post" action="{{ route('registration') }}" novalidate>
@csrf
<x-person-fields />
<h6 class="mt-4 text-muted">{{ __('PERSONS.ACCOUNT_SECTION') }}</h6>
<div class="mb-3">
<x-field name="login" :label="__('PERSONS.LOGIN_LABEL')" max="30" autocomplete="username" required
:help="__('REGISTRATION.LOGIN_HELP')" />
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<x-field name="password" type="password" :label="__('PERSONS.PASSWORD_LABEL')" max="72"
autocomplete="new-password" required :help="__('REGISTRATION.PASSWORD_HELP', ['min' => $min])" />
</div>
<div class="col-sm-6">
<x-field name="password_confirmation" type="password" :label="__('ACCOUNT.CONFIRMATION_LABEL')"
max="72" autocomplete="new-password" required />
</div>
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{ __('REGISTRATION.SUBMIT') }}</button>
<a class="btn btn-secondary" href="{{ route('login') }}">{{ __('REGISTRATION.BACK_TO_LOGIN') }}</a>
</div>
</form>
</div>
</div>
</div>
@endsection
|
Creación de una cuenta de paciente: los campos de identidad (un formulario vacío), seguidos del nombre de usuario, la contraseña y la confirmación de la contraseña, que son obligatorios. [@php($min = ...)]: la forma corta de [@php], para una sola instrucción. El texto de ayuda de la contraseña indica la longitud mínima: [__('REGISTRATION.PASSWORD_HELP', ['min' => $min])], “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.18.3.6. resources/views/area.blade.php
| {{-- =========================================================================
resources/views/area.blade.php - "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 la forma de cancelarla.
========================================================================= --}}
@extends('layout')
@section('content')
<h4 class="mb-3">{{ __('AREA.HELLO', ['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="{{ route('account') }}">
<h5 class="mb-1">{{ __('AREA.MANAGE_ACCOUNT') }}</h5>
<span class="text-muted">{{ __('AREA.MANAGE_ACCOUNT_HELP') }}</span>
</a>
</div>
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="{{ route('schedule') }}">
<h5 class="mb-1">{{ __('AREA.VIEW_SCHEDULE') }}</h5>
<span class="text-muted">{{ __('AREA.VIEW_SCHEDULE_HELP') }}</span>
</a>
</div>
</div>
<div class="card p-3">
<h5>{{ __('AREA.MY_APPOINTMENT') }}</h5>
{{-- normalmente solo una (regla "una cita próxima a la vez"), pero la
página puede mostrar varias. @forelse ... @empty: un bucle, y lo que
se muestra si la lista está vacía; $loop->last: ¿último elemento? --}}
@forelse ($appointments as $appointment)
<div @class(['d-flex flex-wrap justify-content-between align-items-center gap-2 py-2',
'border-bottom' => ! $loop->last])>
<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') }}</a>
</div>
</div>
<form method="post" action="{{ route('area.cancel') }}" class="m-0"
data-confirmation="{{ __('SCHEDULE.CANCEL_CONFIRM') }}">
@csrf
<input type="hidden" name="appointmentId" value="{{ $appointment->id }}">
<button type="submit" class="btn btn-outline-danger">{{ __('AREA.CANCEL_APPOINTMENT') }}</button>
</form>
</div>
@empty
<p class="text-muted mb-0">{{ __('AREA.NO_APPOINTMENT') }}</p>
@endforelse
</div>
@endsection
|
“Mi área”, la página de inicio del paciente: dos tarjetas grandes (“Administrar mi cuenta”, “Ver una agenda”) y su próxima cita.
- Líneas 32–51: [@forelse] (Ejemplo 14) es un bucle, seguido ([@empty]) 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 está diseñada para 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 ID: el servidor verificará que pertenece al paciente que inició sesión.
11.18.3.7. resources/views/account.blade.php
| {{-- =========================================================================
resources/views/account.blade.php - "Manage my account" (rol USER).
Dos formularios independientes en la misma página:
1. la modificación (identidad, login, nueva contraseña opcional);
2. la eliminación de la cuenta, que también cancela sus citas.
Ambos requieren la contraseña ACTUAL (campo current_password).
========================================================================= --}}
@extends('layout')
@section('content')
@php($min = App\Http\Requests\PersonFieldsRequest::PASSWORD_MIN)
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
{{-- 1. modification --}}
<div class="card p-4 mb-4">
<h5 class="card-title mb-3">{{ __('MY_ACCOUNT.TITLE') }}</h5>
<form method="post" action="{{ route('account.edit') }}" novalidate>
@csrf
<input type="hidden" name="version" value="{{ old('version', $patient->version) }}">
<x-person-fields :person="$patient" />
<h6 class="mt-4 text-muted">{{ __('PERSONS.ACCOUNT_SECTION') }}</h6>
<div class="mb-3">
<x-field name="login" :label="__('PERSONS.LOGIN_LABEL')" :value="$patient->account->login"
max="30" autocomplete="username" required />
</div>
<div class="row g-3 mb-3">
<div class="col-sm-6">
<x-field name="password" type="password" :label="__('MY_ACCOUNT.NEW_PASSWORD_LABEL')" max="72"
autocomplete="new-password" :help="__('PERSONS.PASSWORD_HELP_EDIT')" />
</div>
<div class="col-sm-6">
<x-field name="password_confirmation" type="password" :label="__('ACCOUNT.CONFIRMATION_LABEL')"
max="72" autocomplete="new-password" />
</div>
</div>
<div class="mb-4">
<x-field name="current_password" type="password" :label="__('MY_ACCOUNT.CURRENT_PASSWORD_LABEL')"
max="72" autocomplete="current-password" required
:help="__('MY_ACCOUNT.CURRENT_PASSWORD_HELP')" />
</div>
<div class="d-flex gap-2">
<button type="submit" class="btn btn-primary">{{ __('PERSONS.SAVE') }}</button>
<a class="btn btn-secondary" href="{{ route('area') }}">{{ __('MY_ACCOUNT.BACK') }}</a>
</div>
</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') }}</h5>
<p class="text-muted small">{{ __('MY_ACCOUNT.DELETE_HELP') }}</p>
<form method="post" action="{{ route('account.delete') }}" class="d-flex flex-wrap gap-2 align-items-end"
data-confirmation="{{ __('MY_ACCOUNT.DELETE_CONFIRM') }}">
@csrf
<div class="flex-grow-1">
<label class="form-label" for="delete_password">{{ __('MY_ACCOUNT.CURRENT_PASSWORD_LABEL') }}</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') }}</button>
</form>
</div>
</div>
</div>
@endsection
|
“Administrar mi cuenta”: dos formularios independientes en la misma página.
- líneas 19–53: edición: la versión (bloqueo optimista), los campos de identidad, el nombre de usuario, la nueva contraseña y su confirmación (opcionales) y la contraseña actual (obligatoria);
- Líneas 62–71: eliminación de la cuenta, con su propio campo de contraseña actual y confirmación. El campo tiene el mismo nombre que el del primer formulario ([current_password]: solo se envía un formulario a la vez), pero no el mismo ID: dos elementos de una página no pueden tener el mismo ID, como lo indica el atributo [for] de una etiqueta.
11.18.3.8. resources/views/error.blade.php
| {{-- =========================================================================
resources/views/error.blade.php - the error page (400, 403, 404, 419,
500...), built by bootstrap/app.php (withExceptions).
========================================================================= --}}
@extends('layout')
@section('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) }}</p>
<div><a class="btn btn-primary" href="{{ route('home') }}">{{ __('ERROR_PAGE.BACK') }}</a></div>
</div>
</div>
</div>
@endsection
|
La página de error, generada por [bootstrap/app.php]: 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.19. Archivos estáticos
La carpeta [public] es la 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.19.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, al final de la página, sobre un fondo rosa claro
(vea resources/views/fragments/errors.blade.php).
position: sticky + bottom: si la página es más alta que la ventana (una
agenda de 12 intervalos, por ejemplo), la zona se queda pegada al fondo de la
ventana en lugar de desaparecer bajo el pliegue - sin cubrir nunca
el contenido cuando la página es corta.
z-index: por encima del fondo gris del 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 en 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 intervalos), 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, se queda 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.19.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: resources/views/fragments/confirmation.blade.php).
// 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 que se enviará si el usuario confirma
let previousFocus = null; // el elemento al que se devuelve el foco al cerrar
function open(form) {
pendingForm = form;
previousFocus = document.activeElement;
// textContent (y no innerHTML): el mensaje se muestra como TEXTO,
// nunca se interpreta 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 deben confirmarse
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 se pide una nueva 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 aporta 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–21: 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 la página no tiene una ventana de confirmación, no hace nada;
- Líneas 26–35: apertura de la ventana: se almacena el formulario que se enviará tras la confirmación 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 antes;
- líneas 46–50: se intercepta el envío de cada formulario que debe confirmarse ([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]')] identifica 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 emite 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 los lectores de pantalla.