Skip to content

11. Estudo de caso: a aplicação RdvMedecins

11.1. O problema

A aplicação RdvMedecins gerencia as consultas de um consultório médico. Cada médico tem horários (das 8h às 12h em intervalos de 20 minutos, por exemplo); uma consulta é composta de um dia, um horário e um cliente (um paciente). Este é o porte exato, para o [Laravel], da aplicação [Flask] da lição anterior (que, por sua vez, foi portada das versões [Spring MVC] e [ASP.NET Core MVC]): mesmo banco de dados, mesmas regras de negócio, mesmas páginas, mesmas URLs, mesmo texto. As páginas HTML são geradas pelo servidor usando views [Blade]; o acesso ao banco de dados é feito pelo [Eloquent].

Três papéis de usuário compartilham a aplicação:

ADMIN
o administrador ([admin])
ver agendas, marcar e cancelar consultas de qualquer paciente; gerenciar (listar, adicionar, editar, excluir) médicos e clientes
DOCTOR
Médicos
Ver agendas, marcar consultas e cancelar consultas de qualquer paciente
USER
clientes (pacientes)
ver agendas sem ver os nomes dos outros pacientes; marcar uma consulta para si mesmo; cancelar sua consulta; gerenciar sua conta; criar uma conta

Principais regras de gestão:

  • Nenhuma consulta no passado;
  • Um horário só pode ser reservado uma vez por dia;
  • um paciente tem apenas uma consulta futura por vez;
  • dois médicos (ou dois clientes) não podem ter o mesmo nome e sobrenome, e um login pertence a uma única conta;
  • Um médico com consultas não pode ser excluído; Um cliente é excluído junto com suas consultas;
  • a página de login é protegida contra bots (CAPTCHA, tentativas limitadas), e a criação de uma conta de paciente exige primeiro resolver o CAPTCHA dessa página.

11.2. Usando a aplicação

11.2.1. A página de login

Image

A página apresenta dois botões: Entrar e Criar uma conta de paciente. Ambos exigem que você digite os caracteres exibidos na imagem. Os botões FR / EN mudam o idioma:

Image

Um erro (neste caso, um CAPTCHA digitado incorretamente) é exibido na parte inferior da página sobre um fundo rosa claro:

Image

11.2.2. O calendário, visto pelo administrador e pelos médicos

Depois de fazer login, o administrador é levado à página do calendário. Ele seleciona um médico e um dia:

Image

Image

Cada horário está disponível (botão Reservar) ou ocupado (nome do paciente, botão Cancelar). Clicar em Reservar abre uma janela que pede as informações do paciente. Essa janela é gerada pelo servidor, assim como o restante da página: a URL passa a conter o parâmetro [book=4], que é o número do horário selecionado:

Image

Após a reserva, uma mensagem confirma a consulta:

Image

Clicar em “Cancelar” exibe uma confirmação (aqui pela Dra. Pélissier, cuja barra de navegação não inclui os menus de administração):

Image

11.2.3. O portal do paciente

Um paciente (papel USER) chega a “Minha área”: sua próxima consulta, que ele pode cancelar, e links para gerenciar sua conta e ver seu calendário. Aqui, ele ainda não tem consulta:

Image

No calendário, ele não vê os nomes dos outros pacientes; eles são substituídos por “Reservado”: esse nome nem sequer aparece no código-fonte da página. Ele pode reservar um horário disponível:

Image

A janela de reserva não pede que ele selecione um paciente: ele marca a consulta para si mesmo.

Image

Image

Seu painel agora mostra sua próxima consulta, que ele pode cancelar:

Image

Como ele tem uma consulta futura, não pode marcar outra: o botão “Reservar” não é exibido e, no calendário de outro dia ou de outro médico, uma mensagem explica o motivo:

Image

Gerenciamento da conta: editar suas informações, alterar a senha ou excluir a conta (e as consultas). A senha atual é exigida para qualquer alteração:

Image

Um paciente que tenta abrir uma página reservada ao administrador (aqui, [/doctors], digitada manualmente) recebe uma página de erro:

Image

11.2.4. Gerenciamento de médicos e pacientes

O administrador tem dois menus adicionais, Médicos e Pacientes:

Image

Image

O formulário de adição de um médico, enviado com erros:

Image

Um nome igual ao de um médico existente é rejeitado, mesmo escrito em minúsculas e com acento (o próprio banco de dados compara os nomes sem distinguir maiúsculas de minúsculas nem acentos; veja o exemplo 28):

Image

A exclusão de um paciente exige confirmação:

Image

11.2.5. Criação de uma conta de paciente

Na página de login, o botão “Criar uma conta de paciente” só abre o formulário se o CAPTCHA tiver sido digitado corretamente:

Image

Depois que a conta é criada, o usuário é redirecionado para a página de login com seu nome de usuário já preenchido:

Image

11.2.6. Logout

O token de login é válido por duas horas. Depois desse prazo (ou se o token tiver sido adulterado), a página solicitada redireciona para a página de login com a seguinte mensagem:

Image

11.3. Instalação e execução

A aplicação está na pasta [rdvmedecins2-laravel], ao lado da pasta [examples]. É um projeto independente, com seus próprios arquivos [composer.json] e [.env] e sua própria pasta [vendor]. O arquivo [README.md] da pasta contém tudo o que segue. A introdução deste documento já descreveu a instalação do [PHP] e do [Composer]; vamos detalhá-la aqui.

11.3.1. Software necessário

Três programas são tudo de que você precisa:

  • [PHP] 8.4 ou posterior, com a extensão [pdo_mysql] (a aplicação usa recursos introduzidos na versão 8.4, como [array_find]). Verifique a instalação em um terminal:
php -v
php -m

O segundo comando lista as extensões: [pdo_mysql] deve aparecer nessa lista;

  • [Composer], o gerenciador de bibliotecas do [PHP] (veja os apêndices);
  • um servidor [MySQL] 8, por exemplo o do [Laragon] no [Windows] (veja os apêndices). [MariaDB] também serve: a aplicação foi testada com ele.

O editor recomendado é o [Visual Studio Code], com as extensões [PHP Intelephense] e [Laravel] (veja os apêndices); no entanto, tudo pode ser feito pela linha de comando.

11.3.2. Instalar as bibliotecas

A pasta [vendor] não é fornecida: crie-a uma vez por todas em uma janela de terminal aberta na pasta [rdvmedecins2-laravel] (é preciso estar conectado à Internet):

composer install

O [Composer] lê o arquivo [composer.json] (discutido adiante), baixa o [Laravel], o [firebase/php-jwt] e as bibliotecas das quais eles dependem, e gera o carregador de classes [vendor/autoload.php].

11.3.3. Criar o banco de dados

O banco de dados [dbrdvmedecins2] é criado pelo script [database/dbrdvmedecins2.sql]. Usando o [Laragon], abra a ferramenta [HeidiSQL] (botão Banco de dados) e execute o script pelo menu Arquivo / Executar SQL. Pela linha de comando, na pasta da aplicação:

mysql -u root -p < database/dbrdvmedecins2.sql

A opção [-p] solicita a senha do [root]; omita-a se a conta não tiver senha (como é o caso do [Laragon]). Este é o mesmo banco de dados das outras versões da aplicação: se ele já existir, esta etapa é opcional. O script pode ser executado a qualquer momento para voltar aos dados originais.

11.3.4. Configurar o acesso ao banco de dados

Toda a configuração da instalação está no arquivo [.env] (discutido mais adiante). Por padrão, a aplicação se conecta ao [MySQL] em [127.0.0.1], porta 3306, com o usuário [root] sem senha: essas são as configurações padrão do [Laragon]. Se a sua conta [root] tiver senha, informe-a neste arquivo, na linha [DB_PASSWORD=]. Uma variável de ambiente do sistema tem precedência sobre o arquivo (exemplo 25): isso permite informar a senha sem gravá-la em um arquivo do projeto.

11.3.5. Executar a aplicação

Em uma janela de terminal aberta na pasta [rdvmedecins2-laravel]:

php artisan serve --port=8081
1
2
3
   INFO  Server running on [http://127.0.0.1:8081].

  Press Ctrl+C to stop the server

Em seguida, abra a URL [http://localhost:8081] em um navegador e pare a aplicação com [Ctrl-C]. A porta 8081 permite executar ao mesmo tempo um exemplo do curso (porta 8000).

11.3.6. Contas de demonstração

A senha de cada conta é o seu nome de usuário; você também deve digitar os caracteres da imagem, em maiúsculas ou minúsculas:

[admin]
ADMIN (o administrador)
[pelissier], [tatou], [dupont]
DOCTOR (os médicos)
[martin], [durand], [bistrou], [german]
USER (pacientes)

Um roteiro para explorar a aplicação:

  • [admin]: Agenda, Sra. Marie PELISSIER; hoje: um horário já está reservado pela Sra. Brigitte BISTROU. Reserve um horário para o Sr. Jean MARTIN e depois tente marcar uma segunda consulta para ele (recusada). Menus Médicos e Pacientes: adicionar, editar, excluir (a Dra. PELISSIER, que tem consultas, não pode ser excluída);
  • [pelissier]: sua agenda do dia é exibida diretamente; o endereço [/doctors], digitado manualmente, retorna uma página de erro 403;
  • [martin]: Minha área, sua consulta, o calendário em que os outros pacientes aparecem como “Reservado”; Gerenciar minha conta;
  • página de login: Criar uma conta de paciente e, em seguida, fazer login com a nova conta;
  • Botões FR / EN: toda a interface muda de idioma, inclusive as datas.

11.3.7. Modo de desenvolvimento

O arquivo [.env] fornecido configura a aplicação para desenvolvimento:

  • [DB_LOG=true]: o console do servidor exibe cada comando SQL enviado ao banco de dados, bem como cada etapa das transações (exemplo 28). Por exemplo, para exibir um calendário:
1
2
3
4
5
6
7
8
  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]: uma exceção inesperada exibe a [Laravel] página de depuração (exemplo 03), mostrando a mensagem da exceção e a pilha de chamadas. Em produção, a aplicação exibe sua própria página de erro 500;
  • não há nada a reiniciar após uma alteração: cada requisição relê os arquivos [PHP] (exemplo 01), e uma view modificada é recompilada na requisição seguinte.

O [Xdebug] depurador também permite percorrer a aplicação passo a passo a partir do [Visual Studio Code] (extensão [PHP Debug]): ele é uma extensão do [PHP], que deve ser instalada separadamente (veja xdebug.org).

11.3.8. Um servidor de produção

O servidor [php artisan serve] não se destina ao uso em produção. Em produção, a aplicação é servida por um servidor web ([nginx], [Apache]), que repassa as requisições ao [PHP-FPM], um gerenciador de processos ([PHP]). A raiz do site é a pasta [public]: somente os arquivos dela são acessíveis pelo navegador; as pastas [storage] e [bootstrap/cache] devem ser graváveis pelo servidor. Preparamos a aplicação com alguns comandos:

1
2
3
4
5
composer install --no-dev --optimize-autoloader
php artisan key:generate
php artisan config:cache
php artisan route:cache
php artisan view:cache

[key:generate] writes a new encryption key to the file [.env]; the following three commands combine the configuration, routes, and compiled views into a few files, which load faster than the originals (this process must be repeated after each modification). In the [.env] file, you must also specify production mode, change the secret token key, and declare that the site is served via HTTPS:

1
2
3
4
APP_ENV=production
APP_DEBUG=false
JWT_SECRET=<a long random string>
COOKIE_SECURE=true

Uma sequência aleatória adequada pode ser obtida com o próprio [PHP] : [php -r "echo bin2hex(random_bytes(32));"].

11.3.9. Problemas comuns

Uma aplicação [PHP] não “inicia”: cada requisição reconstrói a aplicação (exemplo 01). Portanto, um banco de dados inacessível não impede a inicialização do servidor: o erro aparece na primeira página que consulta o banco (a página de login não consulta o banco; o processo de login em si, sim). Com [APP_DEBUG=true], o erro é exibido na página de depuração do [Laravel]; em todos os casos, ele é registrado no log [storage/logs/laravel.log]. Por exemplo, com um banco de dados que não 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): ...

As mensagens mais comuns:

[Failed opening required '.../vendor/autoload.php']
O comando [composer install] não foi executado
[Your Composer dependencies require a PHP version ">= 8.4.0"]
A versão do [PHP] é anterior à 8.4
[could not find driver]
A extensão [pdo_mysql] do [PHP] não está ativada (arquivo [php.ini], ou menu PHP / Extensions do [Laragon])
[SQLSTATE[HY000] [2002] Connection refused]
O [MySQL] não foi iniciado ou não está escutando em [127.0.0.1:3306]
[SQLSTATE[HY000] [1045] Access denied for user 'root'@'localhost']
A senha do [MySQL] deve ser informada no [.env] (veja “Configurar o acesso ao banco de dados”)
[SQLSTATE[HY000] [1049] Unknown database 'dbrdvmedecins2']
O script [database/dbrdvmedecins2.sql] não foi executado
[No application encryption key has been specified.]
A variável [APP_KEY] do arquivo [.env] está vazia: [php artisan key:generate]
[JWT_SECRET must be at least 32 characters long (see .env).]
A chave secreta dos tokens é curta demais no [.env]
[Failed to listen on 127.0.0.1:8081 (reason: Address already in use)]
A porta 8081 já está em uso (outra versão da aplicação está em execução?): pare-a ou escolha outra porta

11.4. Arquitetura da aplicação

Image

  • O navegador envia suas requisições ao servidor ([php artisan serve], ou [nginx] + [PHP-FPM]), que as repassa ao [Laravel] por meio do arquivo [public/index.php]. Cada requisição passa primeiro pelas camadas de middleware (veja o capítulo sobre o ciclo de vida): o idioma da requisição ([SetLanguage]), os cookies, a sessão, a proteção anti-CSRF e, em seguida, a autenticação: o usuário é identificado pelo token JWT em seu cookie, e as páginas protegidas são negadas a visitantes sem acesso ([Authenticate], [RequireRoles]);
  • [Http/Controllers]: os controllers da camada web. Todos passam por um único objeto, o [ApplicationModel] (pasta [Web]), que mantém em cache as listas de médicos e clientes e repassa as demais requisições à camada de negócio; [Http/Requests]: validação de formulários;
  • [Auth]: tokens, JWT, CAPTCHA, limites de tentativas e o passe de criação de conta;
  • [Web]: o que os controllers têm em comum: o cache e a fachada [ApplicationModel], as mensagens flash e alguns utilitários; [Views]: os templates de view;
  • [Business]: regras de negócio e transações;
  • [Dao]: a camada DAO, uma classe por tabela;
  • [Models]: os models [Eloquent], que a camada DAO usa para ler e gravar no banco de dados; [Domain]: os objetos do calendário, calculados pela camada de negócio;
  • [resources/views]: as views [Blade], que geram as páginas HTML; [lang]: os dicionários; [public]: a folha de estilo, o script da página e o [Bootstrap];
  • [bootstrap/app.php] e [app/Providers/AppServiceProvider.php] montam tudo; [.env] e a pasta [config]: a configuração.

A pasta da aplicação (exceto [vendor] e o conteúdo 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 é a estrutura de uma aplicação [Laravel] padrão — a gerada pelo comando [composer create-project laravel/laravel] (exemplo 01) —, sem os elementos desnecessários aqui (testes, migrações, ferramentas de build de [JavaScript] etc.). Há duas diferenças em relação aos exemplos: a aplicação tem sua própria pasta [vendor] (os exemplos compartilhavam a da pasta [examples]) e um service provider ([app/Providers/AppServiceProvider.php]), abordado adiante. As classes da aplicação são organizadas na pasta [app] segundo a regra PSR-4 (exemplo 01): a classe [App\Business\BusinessService] está no arquivo [app/Business/BusinessService.php]. [Laravel] não impõe nenhuma dessas pastas (exemplo 06): [Http], [Models], e [Providers] são as que estão em uso; as demais ([Auth], [Dao], [Business]...) fazem parte da arquitetura em camadas do exemplo 28. [Bootstrap] faz parte da aplicação (pasta [public/lib/bootstrap]) desta vez: o estudo de caso é autônomo.

11.5. O banco de dados

O banco de dados [dbrdvmedecins2] tem cinco tabelas:

  • [users]: usuários autorizados a fazer login;
  • [doctors] e [clients]: médicos e pacientes, cada um vinculado à sua conta de usuário;
  • [slots]: os horários disponíveis de cada médico;
  • [appointments]: consultas, um cliente por horário, em um determinado dia.

11.5.1. database/dbrdvmedecins2.sql

-- =========================================================================
-- Banco de dados [dbrdvmedecins2] - MySQL 8
--
-- Evolução de [dbrdvmedecins]:
--   1. as tabelas [doctors] e [clients] ganham uma coluna [user],
--      chave estrangeira para users(id): todo médico e todo cliente é
--      agora também um usuário capaz de fazer login;
--   2. surge um terceiro papel: DOCTOR (além de ADMIN e USER);
--   3. o script cria uma linha em [users] para cada médico (papel DOCTOR)
--      e para cada cliente (papel USER):
--        - login        = sobrenome em minúsculas
--        - senha        = sobrenome em minúsculas, com hash bcrypt (10 rounds)
--        - nome exibido = nome + sobrenome
--
--   4. restrições de unicidade, todas NOMEADAS (a aplicação reconhece
--      o nome da restrição violada na mensagem de erro do MySQL):
--        - unq_users_login                   : um login pertence a uma única conta;
--        - unq_doctors_first_name_last_name  : dois médicos não podem ter o
--                                              mesmo nome e sobrenome;
--        - unq_clients_first_name_last_name  : o mesmo para os clientes.
--      Atenção: a collation utf8mb4_unicode_ci compara sem distinguir
--      maiúsculas e acentos - "Hélène DUPONT" e "helene dupont"
--      são portanto considerados idênticos.
--
-- A tabela [users] agora deve ser criada ANTES de [doctors] e [clients]
-- (elas a referenciam) e removida DEPOIS delas.
-- =========================================================================

-- o script é escrito em UTF-8
SET NAMES utf8mb4;

-- recomeçamos de um banco de dados vazio a cada execução do script (prático em desenvolvimento)
CREATE DATABASE IF NOT EXISTS dbrdvmedecins2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbrdvmedecins2;

-- ordem de remoção: das tabelas "filhas" para as tabelas "pais"
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;

-- -------------------------------------------------------------------------
-- tabela [users]: os usuários autorizados a fazer login na aplicação
-- -------------------------------------------------------------------------
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'
  -- um login pode pertencer a uma única conta
  CONSTRAINT unq_users_login UNIQUE (login)
);

-- -------------------------------------------------------------------------
-- tabela [doctors]: os médicos do consultório
-- -------------------------------------------------------------------------
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),
  -- uma conta por médico e um médico por conta
  CONSTRAINT unq_doctors_user UNIQUE (`user`),
  -- dois médicos não podem ter o mesmo nome e sobrenome
  CONSTRAINT unq_doctors_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- tabela [clients]: os pacientes dos 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),
  -- uma conta por cliente e um cliente por conta
  CONSTRAINT unq_clients_user UNIQUE (`user`),
  -- dois clientes não podem ter o mesmo nome e sobrenome
  CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- tabela [slots]: os horários 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)
);

-- -------------------------------------------------------------------------
-- tabela [appointments]: as consultas agendadas pelos 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),
  -- o mesmo horário, no mesmo dia, só pode ser reservado uma vez
  CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
);

-- =========================================================================
-- Dados de demonstração
-- =========================================================================

-- os usuários: senhas com hash bcrypt (10 rounds de salt)
--   admin/admin (ADMIN)
--   uma conta DOCTOR por médico, uma conta USER por cliente
--   (a conta de demonstração user/user não existe mais: uma conta USER é
--   agora SEMPRE a conta de um cliente, que pode agendar e gerenciar a conta)
--   (login = senha = sobrenome em 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');

-- os médicos: a coluna [user] é buscada a partir do login,
-- em vez de presumir os valores das chaves primárias 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'));

-- horários do médico PELISSIER (doctor_id = 1): das 8h às 12h em intervalos de 20 minutos
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
  (1, 8, 0, 8, 20), (1, 8, 20, 8, 40), (1, 8, 40, 9, 0),
  (1, 9, 0, 9, 20), (1, 9, 20, 9, 40), (1, 9, 40, 10, 0),
  (1, 10, 0, 10, 20), (1, 10, 20, 10, 40), (1, 10, 40, 11, 0),
  (1, 11, 0, 11, 20), (1, 11, 20, 11, 40), (1, 11, 40, 12, 0);

-- horários do médico TATOU (doctor_id = 2): das 14h às 18h em intervalos de 20 minutos
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
  (2, 14, 0, 14, 20), (2, 14, 20, 14, 40), (2, 14, 40, 15, 0),
  (2, 15, 0, 15, 20), (2, 15, 20, 15, 40), (2, 15, 40, 16, 0),
  (2, 16, 0, 16, 20), (2, 16, 20, 16, 40), (2, 16, 40, 17, 0),
  (2, 17, 0, 17, 20), (2, 17, 20, 17, 40), (2, 17, 40, 18, 0);

-- uma consulta já agendada, para ver logo um horário ocupado na agenda
INSERT INTO appointments (day, slot_id, client_id) VALUES
  (CURDATE(), 2, 3);
  • linha 33: o banco de dados é criado se não existir, com o conjunto de caracteres [utf8mb4] e a collation [utf8mb4_unicode_ci], que compara strings sem distinguir maiúsculas de minúsculas nem acentos (exemplo 28);
  • linhas 37–41: as tabelas são excluídas e depois recriadas; o script restaura o banco de dados ao estado inicial. A ordem importa: uma tabela não pode ser excluída enquanto outra tabela a referenciar por meio de uma chave estrangeira;
  • linhas 46–55: users: um login, uma senha com hash de [bcrypt] (exemplo 25), o nome de exibição após o login e o papel ([ADMIN], [DOCTOR], ou [USER]). A restrição [unq_users_login] garante que um nome de usuário pertença a uma única conta;
  • linhas 60–72: cada tabela tem uma chave primária [id], gerada pelo banco de dados, e uma coluna [version], que é o bloqueio otimista (exemplo 28). A coluna [user] é uma chave estrangeira que referencia [users(id)]: o banco de dados rejeita qualquer valor que não seja o ID de um usuário existente. Como [user] é uma palavra reservada do SQL, ela é cercada por acentos graves. Três restrições: [fk_doctors_user] (a chave estrangeira), [unq_doctors_user] (uma conta por médico e um médico por conta) e [unq_doctors_first_name_last_name] (sem homônimos). Todas as restrições são nomeadas: a aplicação reconhece uma restrição violada pelo nome;
  • linhas 77–89: a tabela [clients] tem exatamente as mesmas colunas;
  • linhas 94–103: um horário pertence a um médico; seus horários de início e de fim são armazenados em horas e minutos;
  • linhas 108–118: uma consulta é composta de um dia (tipo [DATE], sem horário), um horário e um cliente. A restrição [unq1_appointments] impede que o mesmo horário seja reservado duas vezes no mesmo dia: o banco de dados garante essa regra, mesmo que dois usuários tentem reservá-lo ao mesmo tempo;
  • linhas 130–140: usuários de demonstração, cuja senha é o login. Os hashes começam com [$2b$10$]: o algoritmo ([bcrypt], variante [2b]) e o custo (10). Em seguida vêm o salt e o hash. Esses hashes foram calculados pela versão [Flask] da aplicação; o [PHP] grava os seus com o prefixo [$2y$], mas verifica ambos da mesma forma (veja [config/hashing.php], abaixo);
  • linhas 144–147: a coluna [user] de cada médico é obtida por uma subconsulta baseada no login, em vez de supor os valores das chaves primárias;
  • linhas 170–171: uma consulta já marcada para hoje ([CURDATE()]) no segundo horário da Dra. PELISSIER para a Sra. BISTROU: o calendário mostra assim, imediatamente, um horário reservado.

Diferentemente do [Laravel], o banco de dados não é criado por meio de migrações ([PHP] classes que descrevem a criação e a evolução das tabelas, executadas por [php artisan migrate]): ele é compartilhado com as outras versões da aplicação, e o script SQL é comum a todas elas.

11.6. A configuração do projeto

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
}
  • Linhas 6–11: as bibliotecas exigidas pela aplicação e as restrições que elas devem atender. [^13.33] significa “versão 13.33 ou uma versão mais recente da mesma versão principal 13”: [Composer] aceita versões que corrigem bugs ou acrescentam recursos, mas não as que poderiam quebrar a aplicação (versão 14). As linhas [php] e [ext-pdo_mysql] não se referem a bibliotecas, mas a requisitos de ambiente: [Composer] impede a instalação se a versão do [PHP] ou a extensão for incompatível, em vez de deixar a aplicação falhar mais tarde;
  • Linhas 12–16: a regra PSR-4 da aplicação: as classes do namespace [App] ficam na pasta [app] (exemplo 01: nos exemplos, [bootstrap/app.php] declarava essa regra ao carregador de classes por meio de [addPsr4]);
  • linhas 18–21: comandos que o [Composer] executa após criar o carregador de classes: o [Laravel] lista os service providers das bibliotecas instaladas ([package:discover], em [bootstrap/cache]).

O [composer install] instala as versões que atendem a essas restrições e registra as versões exatas instaladas em um arquivo chamado [composer.lock]. As instalações seguintes (em outra máquina, por exemplo) usam esse arquivo: elas instalam exatamente as mesmas versões. Já o [composer update] procura as versões mais recentes permitidas pelo [composer.json] e atualiza o [composer.lock]. O comando [composer show] lista o que está instalado na pasta [vendor].

11.6.2. .env

# =========================================================================
# .env: as configurações específicas DESTA instalação (lidas por env('NAME') nos
# arquivos da pasta config). Este arquivo nunca é publicado: ele contém
# segredos. Uma variável de ambiente do sistema tem precedência sobre ele.
# =========================================================================
APP_NAME=RdvMedecins
# local: desenvolvimento; production: em produção
APP_ENV=local
# Chave de criptografia do Laravel (cookies, sessão). Em produção:
# php artisan key:generate (grava uma nova chave neste arquivo)
APP_KEY=base64:+UmYSB3+TOKSr/f/fiqPCyo5IXFgXOLrvO1II52r+q4=
# true: uma exceção inesperada exibe a página de depuração do Laravel, com sua
# pilha de chamadas (NUNCA em produção); false: a página de erro 500 da aplicação
APP_DEBUG=true
APP_URL=http://localhost:8081

# ==== o banco de dados MySQL [dbrdvmedecins2] (script: database/dbrdvmedecins2.sql):
# o servidor, sua porta, o banco de dados, o usuário e sua senha (os do
# Laragon: root, sem senha)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=dbrdvmedecins2
DB_USERNAME=root
DB_PASSWORD=
# true: os comandos SQL enviados ao banco de dados são exibidos no console
DB_LOG=true

# ==== Sessão do Laravel (mensagens flash, token anti-CSRF, entradas a
# exibir novamente): armazenada em um cookie CRIPTOGRAFADO, o servidor não guarda nada
SESSION_DRIVER=cookie
SESSION_LIFETIME=120
# ==== o cache (listas de médicos e clientes, captchas, contadores de
# tentativas, passes): arquivos, em storage/framework/cache
CACHE_STORE=file
# o log: storage/logs/laravel.log
LOG_CHANNEL=single

# ==== autenticação (veja config/rdvmedecins.php)
# chave secreta dos tokens JWT: pelo menos 32 caracteres (HMAC-SHA256)
JWT_SECRET=ef1cfc9709f10b5b5d183b4deb6d5dbbe69518629c3b12a8
# tempo de validade de um token, em minutos (120 min = 2 h)
JWT_DURATION_MINUTES=120
# true em produção (site servido por HTTPS): os cookies nunca trafegam sem criptografia
COOKIE_SECURE=false

# ==== proteção contra robôs (veja app/Auth/AttemptLimiter.php)
LOGIN_MAX_FAILURES=5
LOGIN_BLOCK_MINUTES=15
REGISTRATION_MAX_PER_HOUR=10

O arquivo que contém as configurações específicas desta instalação (exemplo 25): elas variam de uma máquina para outra (o banco de dados, suas credenciais) ou são secretas (as chaves). Ele nunca é publicado; o arquivo [.env.example], que não contém segredos, serve de modelo para ele.

  • Linha 11: a chave de criptografia do [Laravel]: ela criptografa os cookies (exemplo 20), inclusive o cookie de sessão. O comando [php artisan key:generate] grava uma nova;
  • linha 14: durante o desenvolvimento, uma exceção inesperada exibe a página de depuração do [Laravel]; em produção ([false]), a página de erro 500 da aplicação;
  • linhas 20–25: a conexão com o banco de dados (exemplo 28);
  • Linha 31: a sessão do [Laravel] (exemplo 23) é armazenada em um cookie criptografado, e não em arquivos no servidor. A aplicação guarda muito pouca informação ali (mensagens flash, o token anti-CSRF, dados de formulário a reexibir): um único cookie basta, e o servidor não precisa mais armazenar nada entre as requisições. O [Laravel] usa dois cookies: [rdvmedecins_session] contém o ID da sessão, e um segundo cookie, nomeado a partir desse ID, contém os dados da sessão;
  • Linha 35: o cache (exemplo 20) é armazenado em arquivos dentro da pasta [storage/framework/cache]. A aplicação guarda ali as listas de médicos e clientes, os CAPTCHAs, os contadores de tentativas e os tokens de acesso, informações que precisam ser compartilhadas entre todas as requisições. Com vários servidores, seria usado um cache compartilhado, como o [Redis];
  • linhas 41–48: configurações específicas da aplicação: os tokens JWT (exemplo 25) e a proteção contra bots (exemplo 27).

11.6.3. config/app.php, config/session.php, config/hashing.php, config/auth.php

Os arquivos da pasta [config] complementam a configuração padrão do [Laravel] (exemplo 25): somente as chaves que eles escrevem são alteradas.

<?php
// config/app.php: este arquivo COMPLETA a configuração padrão do Laravel
// (vendor/laravel/framework/config/app.php): apenas as chaves escritas aqui mudam
return [
    // o idioma padrão da interface (veja lang/fr.json, lang/en.json) e o idioma
    // de fallback (ele só é usado pelos arquivos PHP da pasta lang: uma chave
    // ausente de um dicionário JSON é exibida como está)
    'locale' => 'en',
    'fallback_locale' => 'en',

    // o fuso horário: o do consultório médico. Ele define a data atual
    // (nenhuma consulta no passado, veja app/Business/Dates.php)
    'timezone' => 'Europe/Paris',
];
  • linhas 8–9: o idioma padrão da interface (exemplo 22) e o idioma de reserva (usado apenas para os arquivos [PHP] da pasta [lang]; veja o exemplo 22);
  • linha 13: o fuso horário. Por padrão, o [Laravel] opera no Tempo Universal Coordenado (UTC); no entanto, a data atual é usada em uma regra de negócio: nenhuma consulta no passado. Em Paris, no verão, entre a meia-noite e as 2h da manhã, o dia em UTC ainda é o dia anterior: o fuso horário do consultório prevalece.
1
2
3
4
5
6
7
8
9
<?php
// config/session.php: a sessão do Laravel (completa a configuração padrão).
// driver [cookie] (veja .env, SESSION_DRIVER): os dados da sessão (mensagens
// flash, token anti-CSRF, entradas a exibir novamente) trafegam em um cookie CRIPTOGRAFADO
return [
    'cookie' => 'rdvmedecins_session',
    // os cookies da aplicação só trafegam por HTTPS em produção
    'secure' => (bool) env('COOKIE_SECURE', false),
];

O nome do cookie de sessão e a opção [secure] dos cookies de sessão, lidos do arquivo [.env] ([(bool)] converte o valor em booleano; [env] já converte [false] e [true]).

<?php
// config/hashing.php: hash de senhas (completa a configuração padrão)
return [
    'driver' => 'bcrypt',
    'bcrypt' => [
        // 10 rounds, como os hashes do script SQL
        'rounds' => 10,
        // Por padrão o Laravel verifica se um hash armazenado é de fato um hash
        // bcrypt... como o PHP o escreve ($2y$). Mas o banco de dados dbrdvmedecins2 é
        // compartilhado com as versões Python ($2b$) e Java ($2a$) da aplicação,
        // cujos hashes o PHP verifica muito bem, sem reconhecê-los como
        // "bcrypt". Por isso essa verificação é desativada
        'verify' => false,
    ],
];

Hash de senhas: [bcrypt], 10 rodadas, como os hashes do script SQL. A linha 13 desativa uma verificação que o [Laravel] realiza por padrão: antes de comparar uma senha com um hash, ele verifica se o hash foi de fato gerado pelo algoritmo configurado, tal como gravado pelo [PHP] ([$2y$]). Os hashes do banco de dados, gerados pelo [Python] ([$2b$]) ou pelo [Java] ([$2a$]), falhariam nessa verificação, embora o [PHP] seja perfeitamente capaz de verificá-los. Esse é o preço de compartilhar um banco de dados com outras aplicações.

<?php
// config/auth.php: autenticação (completa a configuração padrão)
return [
    // o "guard" usado por padrão: o que lê o token JWT do cookie
    'defaults' => [
        'guard' => 'jwt',
    ],
    'guards' => [
        // um guard com o driver [jwt], definido pelo AppServiceProvider (Auth::viaRequest)
        'jwt' => [
            'driver' => 'jwt',
        ],
    ],
];

O guard [jwt], o guard padrão para o driver [jwt]: exatamente como no exemplo 25.

11.6.4. config/rdvmedecins.php

<?php
// config/rdvmedecins.php: as configurações específicas da aplicação, lidas por
// config('rdvmedecins.xxx'). Os valores vêm do arquivo .env; o segundo
// parâmetro de env() é o valor padrão
return [
    'jwt' => [
        // chave secreta dos tokens JWT: pelo menos 32 caracteres (HMAC-SHA256)
        'secret' => env('JWT_SECRET', ''),
        // tempo de validade de um token, em minutos; o cookie que o carrega
        // tem o mesmo tempo de vida
        'duration' => (int) env('JWT_DURATION_MINUTES', 120),
    ],

    // true: os comandos SQL enviados ao banco de dados são exibidos no console
    'db_log' => (bool) env('DB_LOG', false),

    // true em produção (HTTPS): os cookies nunca são enviados sem criptografia
    'cookie_secure' => (bool) env('COOKIE_SECURE', false),

    // proteção contra robôs (veja app/Auth/AttemptLimiter.php):
    // login: falhas permitidas para o mesmo login a partir do mesmo endereço IP,
    // depois bloqueio por esta duração (o endereço IP inteiro também é bloqueado
    // se acumular 5 vezes mais falhas, todos os logins somados)
    'login_max_failures' => (int) env('LOGIN_MAX_FAILURES', 5),
    'login_block_minutes' => (int) env('LOGIN_BLOCK_MINUTES', 15),
    // criação de conta de cliente: máximo de contas criadas por hora e por endereço
    // IP. Em uma sala de aula, todos os computadores costumam sair pelo mesmo endereço:
    // aumente se necessário
    'registration_max_per_hour' => (int) env('REGISTRATION_MAX_PER_HOUR', 10),
];

Configurações específicas da aplicação, lidas por [config('rdvmedecins.jwt.secret')], [config('rdvmedecins.login_max_failures')]... Cada valor vem do arquivo [.env], com um valor padrão. Lembre-se da regra (exemplo 25): [env] é chamado somente em arquivos da pasta [config]; o restante do código lê [config(...)]. Depois que a configuração é colocada em cache ([php artisan config:cache]), o arquivo [.env] deixa de ser lido por completo.

11.7. Quando a aplicação

11.7.1. public/index.php e bootstrap/providers.php

O arquivo [public/index.php] é o dos exemplos (exemplo 01), com o caminho para a pasta [vendor] da aplicação:

<?php
// public/index.php: o ponto de entrada de TODAS as requisições HTTP. A pasta [public]
// é a raiz do site: somente seus arquivos são alcançáveis a partir do navegador
// (Bootstrap, folha de estilo, script), nunca o código da aplicação

use Illuminate\Foundation\Application;
use Illuminate\Http\Request;

// carregador de classes do Composer
require __DIR__.'/../vendor/autoload.php';

// a aplicação, construída por bootstrap/app.php, trata a requisição atual
/** @var Application $app */
$app = require_once __DIR__.'/../bootstrap/app.php';
$app->handleRequest(Request::capture());

O arquivo [bootstrap/providers.php] é novo:

1
2
3
4
5
6
7
8
9
<?php
// bootstrap/providers.php: os service providers da
// aplicação, carregados no início de cada requisição (veja app/Providers)

use App\Providers\AppServiceProvider;

return [
    AppServiceProvider::class,
];

Ele retorna a lista de service providers da aplicação. Um service provider é uma classe cujos dois métodos o [Laravel] chama no início de cada requisição: [register], que registra serviços no contêiner (exemplo 06) e, depois, uma vez registrados todos os providers, [boot], que pode usar qualquer serviço. O próprio [Laravel] é composto de service providers (um para a sessão, um para as views, um para o banco de dados etc.), assim como a maioria das bibliotecas escritas para ele. Nos exemplos, escrevemos essas declarações em [bootstrap/app.php] ([withSingletons], [booted]): isso é conveniente para poucas linhas; uma aplicação de maior porte as agrupa em um service provider, [AppServiceProvider] por convenção.

11.7.2. app/Providers/AppServiceProvider.php

<?php
// =========================================================================
// app/Providers/AppServiceProvider.php: o SERVICE PROVIDER da aplicação
// (declarado em bootstrap/providers.php). É o lugar normal, em uma
// aplicação Laravel, para o que os exemplos escreviam em bootstrap/app.php:
//   - $singletons: os serviços compartilhados (veja o exemplo 06);
//   - boot(): o que deve ser feito no início de cada requisição, depois que todos
//     os serviços estão registrados: o driver de autenticação JWT, as variáveis
//     comuns a todas as views, a exibição dos comandos 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
{
    // -----------------------------------------------------------------------
    // os serviços compartilhados: para cada uma dessas classes, o container do Laravel
    // cria apenas UM objeto (por requisição), entregue a todos que o pedem - os
    // controllers, por meio do construtor. O container constrói as
    // dependências de cada um por conta própria (BusinessService recebe assim seus cinco DAOs): isto é
    // injeção de dependência.
    // -----------------------------------------------------------------------
    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
    {
        // ==== o driver de guard [jwt] (veja config/auth.php, exemplo 25): uma
        // função que recebe a requisição e retorna o usuário autenticado, ou null
        // para um visitante anônimo. O Laravel a chama no primeiro Auth::user() da
        // requisição; se ela encontrou um usuário, ele o guarda pelo resto da
        // requisição (caso contrário, ele chama a função novamente a 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) {
                // um cookie presente mas inválido (expirado, token forjado): nós o limpamos
                Cookie::queue(AuthService::clearingCookie());
            }
            return $user;
        });

        // ==== as variáveis comuns a TODAS as views (veja o exemplo 15): um
        // "view composer" é executado antes de cada view ser construída ('*')
        //   - user     : o usuário conectado (ou null), para a barra de navegação;
        //   - language : "fr" ou "en".
        View::composer('*', function (TheView $view) {
            $view->with(['user' => Auth::user(), 'language' => App::getLocale()]);
        });

        // ==== DB_LOG=true (arquivo .env): cada comando SQL, e cada etapa de uma
        // transação, é exibido no console do servidor (veja o exemplo 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'));
        }
    }
}
  • Linhas 48–60: serviços compartilhados. A propriedade [$singletons] de um service provider é lida pelo [Laravel], que declara cada um de seus pares [interface => class] como um singleton (exemplo 06): isso equivale a [withSingletons]. Aqui, cada classe é declarada individualmente. Lembre-se de que um singleton existe apenas durante uma única requisição (exemplo 06): o benefício aqui é que todos os controllers, middlewares e serviços dentro da mesma requisição compartilham o mesmo [ApplicationModel], o mesmo [BusinessService]... As instâncias de DAO poderiam nem ser declaradas: o contêiner sabe criar uma classe que não foi declarada (exemplo 06), mas criaria um novo objeto a cada requisição;
  • linhas 69–80: o driver de guard [jwt] (exemplo 25). O token é lido do cookie [rdvmedecins_jwt] (o nome é uma constante de [AuthService]) e verificado por [AuthService::currentUser]. Um cookie que existe, mas cujo token deixou de ser válido, é excluído. O [Laravel] guarda o usuário encontrado durante toda a requisição; enquanto não encontrou nenhum (um visitante anônimo), ele chama a função a cada requisição, o que não tem impacto: ler um cookie e, se necessário, verificar uma assinatura é muito rápido;
  • Linhas 86–88: variáveis comuns a todas as views (exemplo 15): o usuário logado (ou [null]), para a barra de navegação, e o idioma da requisição. O padrão ['*'] corresponde a todas as views: o composer é chamado para cada uma delas, inclusive fragmentos e componentes;
  • Linhas 92–99: exibição dos comandos SQL e das transações no console (exemplo 28), se [DB_LOG=true]. [error_log] grava no log de erros do [PHP], ou seja, junto com o [php artisan serve], no console do servidor.

11.7.3. bootstrap/app.php

<?php
// =========================================================================
// bootstrap/app.php: a construção da aplicação (veja o exemplo 01):
//   1. as rotas (routes/web.php);
//   2. os middlewares: idioma, cookies, autenticação, papéis;
//   3. as exceções: como os erros se tornam páginas HTML.
// Os serviços compartilhados são declarados por 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 {
        // o idioma da requisição: um middleware GLOBAL, executado para todas as
        // requisições, antes dos do grupo [web] (veja app/Http/Middleware/SetLanguage.php)
        $middleware->append(SetLanguage::class);

        // O Laravel CRIPTOGRAFA todos os cookies que define. Duas exceções: o token
        // JWT, já assinado; o idioma, lido antes de os cookies serem descriptografados
        $middleware->encryptCookies(except: [AuthService::COOKIE, SetLanguage::COOKIE]);

        // -------------------------------------------------------------------
        // A REGRA DE ACESSO: todas as rotas do grupo [web] exigem um usuário
        // autenticado (middleware Authenticate, alias [auth]) - exceto
        // aquelas que a removem explicitamente (withoutMiddleware, veja
        // routes/web.php: login, criação de conta, escolha do idioma).
        // Esta é a regra "tudo é proibido, exceto o que é permitido": uma rota
        // adicionada depois, que alguém tenha esquecido de proteger, é protegida mesmo assim.
        // -------------------------------------------------------------------
        $middleware->web(append: [Authenticate::class]);

        // um visitante não autenticado que solicita uma página protegida: direto para a
        // página de login. Se ele tinha um cookie de token, seu token não é mais
        // válido (expirado, forjado): sua sessão expirou, nós o informamos
        $middleware->redirectGuestsTo(function (Request $request) {
            if ($request->cookie(AuthService::COOKIE)) {
                Flash::error('ERRORS.SESSION_EXPIRED');
            }
            return route('login');
        });

        // nomes curtos (aliases) para os middlewares usados em routes/web.php
        $middleware->alias([
            'role' => RequireRoles::class,
            'registration.pass' => CheckRegistrationPass::class,
        ]);
    })

    // -----------------------------------------------------------------------
    // Como os erros se tornam páginas HTML (veja o exemplo 24). Três casos:
    //   1. uma InvalidSession (conta excluída desde o login) -> volta à página de
    //      login, como em uma sessão expirada;
    //   2. um erro HTTP: abort(400), abort(403) (papel insuficiente), página
    //      desconhecida (404), método não suportado (405), token anti-CSRF ausente ou
    //      errado (419)... -> a página de erro, com o código original;
    //   3. qualquer outra exceção (uma anomalia real): o Laravel a grava no
    //      log (storage/logs/laravel.log), com sua pilha de chamadas; em
    //      produção (APP_DEBUG=false), o usuário vê a página de erro 500 -
    //      nunca a pilha de chamadas; em desenvolvimento, a página de depuração do Laravel.
    // Uma função render que retorna null deixa o Laravel tratar a exceção
    // do seu próprio jeito.
    // -----------------------------------------------------------------------
    ->withExceptions(function (Exceptions $exceptions): void {
        // a página de erro. $errors: a variável de erros de entrada, que todas
        // as views podem ler, ainda não existe se o erro ocorreu
        // antes do middleware que a cria (uma página 405, por exemplo)
        $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) {
            // essas exceções têm tratamento próprio: redirecionamento para a página de
            // login (AuthenticationException), volta ao formulário com os
            // erros de entrada (ValidationException)...
            if (config('app.debug') || $e instanceof AuthenticationException
                || $e instanceof ValidationException || $e instanceof HttpResponseException) {
                return null;
            }
            return $errorPage(500);
        });
    })
    ->create();

O arquivo que constrói a aplicação (exemplo 01). Ele contém tudo o que se refere ao tratamento das requisições: rotas, middlewares e exceções.

  • linha 28: as rotas ([routes/web.php], discutido mais adiante);
  • linha 33: o idioma da requisição é definido por um middleware global (exemplo 24), executado para todas as requisições, mesmo antes do roteamento;
  • linha 37: o [Laravel] criptografa todos os cookies (exemplo 20), exceto os excluídos: o token JWT, que já é assinado (exemplo 25), e o idioma. O cookie de idioma é lido por um middleware global, que é executado antes do middleware [EncryptCookies] do grupo [web]: ele precisa, portanto, ser legível sem descriptografia. Por que usar um middleware global em vez de um middleware do grupo [web]? Para que até as requisições que não resultam em uma rota (uma página 405) exibam sua página de erro no idioma correto;
  • Linha 47: a regra de acesso da aplicação. O middleware [Authenticate] (o alias [auth] do exemplo 25) é adicionado ao grupo [web], isto é, a todas as rotas. Uma rota pública (a página de login, a criação de conta, a seleção de idioma) deve removê-lo explicitamente usando [withoutMiddleware] (dentro de [routes/web.php]). Isso segue a regra “tudo é proibido, a menos que seja explicitamente permitido”: uma rota adicionada depois, mesmo que você tenha esquecido de protegê-la, fica automaticamente protegida. O erro oposto (uma rota pública que você esqueceu de abrir) é imediatamente visível; o erro de uma página protegida esquecida é muito menos;
  • Linhas 52–57: um visitante não autenticado que solicita uma página protegida é redirecionado para a página de login. Se o navegador do visitante enviou um cookie de token, isso significa que o token deixou de ser válido (expirado ou adulterado): o visitante é avisado por uma mensagem pop-up ([Flash::error], discutido mais adiante). [redirectGuestsTo] aceita uma URL ou uma função que recebe a requisição e retorna a URL;
  • Linhas 60–63: aliases (nomes curtos) para middlewares de rota: [role] e [registration.pass], usados em [routes/web.php].

As linhas 80–113 convertem erros em páginas HTML (exemplo 24):

  • Linhas 84–91: a função que gera a página de erro para um código HTTP: a view [error], o código, a chave da mensagem e o código de resposta HTTP. Um ponto sutil: as views da aplicação leem a variável [$errors] (erros de entrada, exemplo 19), que o middleware [ShareErrorsFromSession] do grupo [web] compartilha com todas as views. Um erro que ocorre antes desse middleware (um método HTTP não suportado, 405, é detectado pelo roteador) chegaria a uma view sem [$errors]: um objeto vazio ([new ViewErrorBag]) é fornecido a ela;
  • linhas 96–99: a exceção [InvalidSession] (a conta do token não existe mais; veja abaixo): retorno à página de login, com o cookie do token apagado, e a mensagem “sessão expirada”;
  • linha 101: todos os erros HTTP, [abort(403)], [abort(404)], uma rota desconhecida, um método não suportado, um token anti-CSRF ausente ou inválido (419, exemplo 18)..., tornam-se a página de erro, junto com seus códigos;
  • Linhas 103–112: qualquer outra exceção é uma anomalia verdadeira (o banco de dados está inacessível, um erro de programação...). O [Laravel] sempre a registra no log [storage/logs/laravel.log], junto com sua pilha de chamadas. Em produção ([APP_DEBUG=false]), o usuário vê a página de erro 500, nunca a pilha de chamadas, que revelaria o código da aplicação a um invasor; em desenvolvimento, a função retorna [null]: o [Laravel] exibe sua página de depuração. Observação: [Throwable] trata todas as exceções, inclusive aquelas que o [Laravel] trata por conta própria, e é melhor deixá-las com ele: [AuthenticationException] (um visitante não autenticado, redirecionado para [/login]), [ValidationException] (uma entrada inválida, devolvida ao formulário, exemplo 19), [HttpResponseException] (uma exceção que carrega sua própria resposta). As funções de renderização são tentadas na ordem em que são declaradas: os erros HTTP já foram tratados pela anterior.

11.8. Os modelos

Os modelos [Eloquent] (exemplo 28): uma classe por tabela.

11.8.1. app/Models/Role.php

<?php
// app/Models/Role.php: os três papéis de um usuário (coluna users.role):
//   - ADMIN  : o administrador - consultas + gerenciamento de médicos e clientes;
//   - DOCTOR : um médico - marca e cancela consultas;
//   - USER   : um cliente (paciente) - marca para si mesmo, gerencia sua conta.
// Uma enumeração "backed" (backed enum): cada case tem um valor, a string
// armazenada como está no banco de dados; Role::from('ADMIN') faz o caminho inverso

namespace App\Models;

enum Role: string
{
    case ADMIN = 'ADMIN';
    case DOCTOR = 'DOCTOR';
    case USER = 'USER';
}

Os três papéis, na forma de uma enumeração ([enum], [PHP] 8.1): um tipo cujos únicos valores possíveis são os seus casos: [Role::ADMIN], [Role::DOCTOR] e [Role::USER]. Uma variável do tipo [Role] não pode conter ['ADMINN']: o erro de digitação é detectado. [enum Role: string] declara uma enumeração com valor associado (backed): cada caso tem um valor, neste caso a string armazenada no banco de dados. [Role::ADMIN->value] é igual a ['ADMIN']; [Role::from('ADMIN')] retorna o caso correspondente (e lança uma exceção para um valor desconhecido); [Role::tryFrom(...)] retorna [null] nesse caso.

11.8.2. app/Models/User.php

<?php
// app/Models/User.php: um usuário autorizado a fazer login (tabela [users]).
// Cada médico e cada cliente possui SUA conta (coluna [user] das tabelas
// [doctors] e [clients], veja Person.php).
//
// restrição de unicidade SQL: unq_users_login (um login pertence a apenas uma
// conta). Ela é criada pelo script database/dbrdvmedecins2.sql; a camada de negócio
// a reconhece pelo seu NOME (veja app/Business/BusinessService.php).

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $table = 'users';

    // a tabela não possui as colunas created_at / updated_at que o Eloquent gerencia por padrão
    public $timestamps = false;

    // as colunas que podem ser preenchidas em massa (User::create([...]), new User([...]))
    protected $fillable = ['login', 'password', 'name', 'role'];

    // a senha COM HASH (bcrypt) nunca sai do objeto se ele for convertido em
    // array ou em JSON
    protected $hidden = ['password'];

    // as conversões: a coluna [role] (um texto) se torna um Role, e vice-versa
    protected function casts(): array
    {
        return ['role' => Role::class, 'version' => 'integer'];
    }
}
  • linha 16: a tabela. O [Eloquent] a teria adivinhado (o nome da classe, em minúsculas, no plural em inglês: [users]); nós a escrevemos em todo lugar, para maior clareza;
  • Linha 19: nenhuma tabela do banco de dados tem as colunas [created_at] e [updated_at], que o [Eloquent] preenche por padrão (exemplo 28);
  • linha 22: as colunas que podem ser preenchidas em massa com [User::create([...])] (exemplo 28);
  • linha 26: o hash da senha não aparecerá se o objeto for convertido em array ou em JSON ([$user->toArray()]): uma precaução;
  • Linhas 29–32: as conversões (exemplo 28): a coluna [role] (texto) vira [Role] ao ser lida, e vice-versa ao ser gravada: [$user->role] é um [Role], nunca uma string. A coluna [version] é lida como inteiro: o driver [PDO] do [MySQL] pode devolver números como strings, e a comparação estrita [$version !== $person->version] da camada de negócio falharia.

11.8.3. app/Models/Person.php

<?php
// app/Models/Person.php: o que os médicos (tabela [doctors]) e
// os clientes (tabela [clients]) têm em comum: um título, um sobrenome, um nome - e a
// conta de usuário associada (coluna [user]).
//
// As duas tabelas têm exatamente as mesmas colunas: elas são descritas UMA VEZ,
// nesta classe ABSTRATA (nunca criamos uma "Person"), da qual
// Doctor e Client herdam; cada uma apenas especifica o nome da sua tabela.
//
// Atenção: [Client] aqui designa um PACIENTE do consultório médico, não um
// cliente HTTP! É o vocabulário do domínio de negócio original, mantido como está.

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

abstract class Person extends Model
{
    public $timestamps = false;

    // [user] é o nome da coluna de chave estrangeira -> users(id): um simples
    // número, o id da conta ($doctor->user)
    protected $fillable = ['title', 'last_name', 'first_name', 'user'];

    protected function casts(): array
    {
        return ['user' => 'integer', 'version' => 'integer'];
    }

    // -----------------------------------------------------------------------
    // A RELAÇÃO com a conta de usuário: uma pessoa tem UMA conta, designada
    // pela chave estrangeira [user]. belongsTo: "pertence a" - a chave estrangeira
    // está NESTA tabela. $doctor->account é então um objeto User, lido do banco de dados
    // no primeiro acesso, ou junto com a consulta por with('account') (veja app/Dao).
    // A relação não pode se chamar [user]: esse nome já é o da
    // coluna, e $doctor->user designa a coluna.
    // -----------------------------------------------------------------------
    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}";
    }
}

As tabelas [doctors] e [clients] têm as mesmas colunas. A descrição comum delas é escrita uma só vez, em uma classe abstrata ([abstract class]): uma classe da qual nunca se criam objetos, que serve apenas como classe base para herança. As classes [Doctor] e [Client] herdam dela e especificam apenas o nome de sua tabela.

  • Linha 24: [user] é a coluna da chave estrangeira; [$doctor->user] é um simples número, o ID da conta;
  • Linhas 39–42: o relacionamento com a conta. Um relacionamento [Eloquent] é um método que descreve o vínculo entre duas tabelas; [belongsTo] (“pertence a”) descreve uma chave estrangeira nesta tabela: [belongsTo(User::class, 'user')] especifica que a coluna [user] contém o ID de um [User]. Ele é usado como propriedade: [$doctor->account] é o objeto [User]. O [Eloquent] o lê do banco de dados no primeiro acesso (isso se chama *lazy loading*, carregamento tardio), ou assim que a consulta que recupera o médico o solicita (se necessário; *eager loading*, veja [with('account')] na camada DAO). O relacionamento não pode se chamar [user]: [$doctor->user] já se refere à coluna, e o [Eloquent] dá prioridade às colunas;
  • Linhas 45–48: o nome de uma pessoa, “Sra. Alice DURAND”, usado por todas as páginas. Em uma string entre aspas, [{$this->title}] insere o valor de uma propriedade.

11.8.4. app/Models/Doctor.php e Client.php

<?php
// app/Models/Doctor.php: um médico (tabela [doctors]).
// Restrição de unicidade SQL: unq_doctors_first_name_last_name (dois médicos não podem
// ter o mesmo nome e sobrenome).

namespace App\Models;

class Doctor extends Person
{
    protected $table = 'doctors';
}
<?php
// app/Models/Client.php: um cliente, ou seja, um PACIENTE (tabela [clients]).
// Restrição de unicidade SQL: unq_clients_first_name_last_name.

namespace App\Models;

class Client extends Person
{
    protected $table = 'clients';
}

Um [Client] é um paciente do consultório, não um cliente HTTP: esse é o vocabulário original do domínio de negócio, preservado em todas as versões da aplicação.

11.8.5. app/Models/Slot.php

<?php
// app/Models/Slot.php: um horário de um médico (tabela [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'];
    }

    // vários horários para o mesmo médico: a chave estrangeira [doctor_id]
    public function doctor(): BelongsTo
    {
        return $this->belongsTo(Doctor::class, 'doctor_id');
    }

    // "8:00 - 8:20"; sprintf('%02d'): "8:05" em vez 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);
    }
}
  • linhas 23–26: o relacionamento com o médico para o horário da consulta (chave estrangeira [doctor_id]);
  • linhas 29–32: o horário, “8:00 – 8:20”. O formato [%02d] do [sprintf] escreve um inteiro com no mínimo dois dígitos, completado com zeros: [8:05] em vez de [8:5].

11.8.6. app/Models/Appointment.php

<?php
// app/Models/Appointment.php: uma consulta (tabela [appointments]): um cliente, em um horário, em um
// dia dado.
// Restrição de unicidade SQL: unq1_appointments (day, slot_id) - um horário é reservado
// apenas uma vez por dia. Criada pelo script SQL, reconhecida pelo seu nome na camada
// de negócio.

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: a coluna [day] (tipo SQL DATE) se torna uma data
    // CarbonImmutable, à meia-noite; ela é gravada no banco de dados no formato yyyy-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');
    }
}
  • Linhas 23–27: a coluna [day] (tipo SQL [DATE]) é convertida em [CarbonImmutable], a classe de datas do [Laravel] (exemplo 12), à meia-noite. Imutável: seus métodos nunca modificam o objeto; eles retornam um novo ([$day->addDay()] retorna o dia seguinte, [$day] permanece inalterado). A aplicação inteira manipula datas imutáveis: uma data compartilhada entre vários objetos não pode ser modificada por um deles sem que os outros saibam;
  • linhas 29–34: dois relacionamentos, um com o cliente e outro com o horário da consulta.

11.9. O domínio: o calendário

11.9.1. app/Domain/DoctorDaySlot.php e DoctorDaySchedule.php

<?php
// app/Domain/DoctorDaySlot.php: um horário, e a consulta eventualmente
// marcada nesse horário em um dia dado (null se o horário estiver livre).
// Um objeto "de negócio" calculado, que não corresponde a nenhuma tabela.
//
// readonly: as propriedades são definidas de uma vez por todas pelo construtor -
// exatamente o que é necessário para um objeto calculado, que ninguém modifica depois.

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: a agenda completa de um médico em um dado
// dia, a lista de seus horários, cada um livre ou ocupado. Calculada por
// BusinessService::getDoctorDaySchedule, transformada em uma tabela 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,
    ) {
    }
}

Dois objetos calculados que não correspondem a nenhuma tabela: um horário e sua eventual consulta em um dia determinado; a agenda de um médico em um único dia, listando seus horários disponíveis. São classes do tipo [readonly] (exemplo 03), cujas propriedades são declaradas no construtor. O comentário [/** @param list<DoctorDaySlot> ... */] especifica o conteúdo do array: o [PHP] não consegue determinar o tipo do conteúdo de um array, mas os editores ([PHP Intelephense]) e as ferramentas de análise leem esses comentários, conhecidos como [PHPDoc].

11.10. A camada DAO

A camada DAO (exemplo 28) agrupa as consultas: uma classe por tabela, sem lógica de negócio. Seus métodos não iniciam transações; a camada de negócio os chama dentro de suas próprias transações. Eles usam o query builder do [Eloquent]: [where], [orderBy], [first], [get]... ; os valores dessas consultas tornam-se parâmetros da consulta SQL: nenhuma injeção de SQL é possível.

11.10.1. app/Dao/PersonDao.php

<?php
// app/Dao/PersonDao.php: a camada DAO comum a médicos e clientes.
//
// Os DAOs dos médicos e dos clientes seriam idênticos: esta classe ABSTRATA
// os escreve apenas uma vez. $this->model é a classe Eloquent em questão
// (Doctor::class ou Client::class): $this->model::query() inicia uma consulta
// na SUA tabela.
//
// As consultas são escritas com o query builder do Eloquent (where,
// orderBy...); o Eloquent as traduz em SQL. Os valores (nome, sobrenome...)
// se tornam PARÂMETROS da consulta: nenhuma concatenação de strings, portanto
// nenhuma injeção de SQL. Esses métodos não abrem nenhuma transação: é a camada
// de negócio que os chama, dentro da sua própria.

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)
    {
    }

    // uma consulta na tabela da classe, conta de usuário incluída
    protected function query(): Builder
    {
        // with('account'): carrega TAMBÉM as contas, com uma segunda consulta
        // (SELECT * FROM users WHERE id IN (...)). Sem isso, cada acesso a
        // $person->account dispararia sua própria consulta
        return $this->model::query()->with('account');
    }

    // lista ordenada por sobrenome e depois por nome
    public function list(): Collection
    {
        return $this->query()->orderBy('last_name')->orderBy('first_name')->get();
    }

    // uma pessoa e sua conta; null se ela não existir
    public function read(int $id): ?Person
    {
        return $this->query()->find($id);
    }

    // a pessoa cuja conta de usuário é [$userId]
    public function readByUser(int $userId): ?Person
    {
        return $this->query()->where('user', $userId)->first();
    }

    // a pessoa que tem este nome e sobrenome, se houver. A comparação é
    // feita pelo MySQL, portanto com a collation do banco de dados (utf8mb4_unicode_ci: sem
    // distinção de maiúsculas e acentos) - exatamente a mesma regra que
    // a da restrição de unicidade SQL
    public function namesake(string $firstName, string $lastName): ?Person
    {
        return $this->model::query()->where('first_name', $firstName)->where('last_name', $lastName)->first();
    }

    // INSERT: o banco de dados gera o id, que o Eloquent armazena no objeto
    public function add(array $columns): Person
    {
        return $this->model::query()->create($columns);
    }

    // -----------------------------------------------------------------------
    // o BLOQUEIO OTIMISTA (veja o exemplo 28):
    //   UPDATE ... SET ..., version = version + 1 WHERE id = ? AND version = ?
    // retorna o número de linhas modificadas: 0 se a linha foi modificada (ou
    // excluída) desde que foi lida
    // -----------------------------------------------------------------------
    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')]);
    }

    // um DELETE enviado diretamente ao banco de dados, sem ler a pessoa antes
    public function remove(int $id): void
    {
        $this->model::query()->whereKey($id)->delete();
    }
}

A camada DAO comum a médicos e clientes, definida uma só vez em uma classe abstrata.

  • Linha 25: a classe [Eloquent] pertinente, [Doctor::class], ou [Client::class] (uma string, o nome completo da classe). O comentário [@param class-string<Person>] esclarece isso para os desenvolvedores. [$this->model::query()] chama o método estático [query] dessa classe: o [PHP] aceita uma variável no lugar de um nome de classe. [query()] inicia uma consulta na tabela do modelo; [Doctor::where(...)] é um atalho para isso;
  • Linhas 30–36: uma consulta que também carrega as contas das pessoas recuperadas: [with('account')] solicita o pré-carregamento do relacionamento [account]. O [Eloquent] então executa duas consultas: uma para as pessoas, seguida de uma para todas as suas contas de uma só vez ([select * from users where id in (2, 3, 4)]; veja a saída do console acima). Sem isso, a lista de médicos exibida pelo administrador dispararia uma consulta por médico no primeiro acesso a [$doctor->account->login]: é o chamado problema das “N + 1 consultas”. Outro motivo: as listas de médicos e clientes são armazenadas em cache ([ApplicationModel], discutido mais adiante); os objetos recuperados do cache precisam estar completos;
  • linhas 39–42: a lista, ordenada por sobrenome e depois por nome; [get()] retorna uma [Collection] e um [Eloquent] (exemplo 28);
  • linhas 45–48: [find] lê uma linha por sua chave primária; [null] se ela não existir;
  • linhas 51–54: a pessoa cuja conta é [$userId]: [first()] retorna a primeira linha, ou [null];
  • linhas 60–63: a pessoa com o mesmo nome e sobrenome. A comparação é feita pelo [MySQL], com a collation do banco de dados: ignorando maiúsculas e acentos, exatamente como na restrição de unicidade (exemplo 28);
  • linhas 66–69: [create] insere uma linha (colunas de [$fillable]) e retorna o objeto, com o ID gerado pelo banco de dados;
  • linhas 77–81: o bloqueio otimista do exemplo 28: [UPDATE ... SET ..., version = version + 1 WHERE id = ? AND version = ?]. O método retorna o número de linhas modificadas: 0 se a linha foi modificada ou excluída desde que foi lida. [[...$columns, 'version' => ...]] cria um array contendo os elementos de [$columns], mais a versão (o operador [...] desempacota um array). [whereKey($id)]: a condição sobre a chave primária;
  • linhas 84–87: o [DELETE] enviado diretamente ao banco de dados, sem ler a linha antes.

11.10.2. app/Dao/DoctorDao.php e ClientDao.php

<?php
// app/Dao/DoctorDao.php: o DAO dos médicos - tudo é herdado de PersonDao.

namespace App\Dao;

use App\Models\Doctor;

class DoctorDao extends PersonDao
{
    public function __construct()
    {
        parent::__construct(Doctor::class);
    }
}

Tudo é herdado: o construtor apenas especifica a classe [Eloquent] ao [PersonDao] ([parent::__construct] chama o construtor da classe pai).

<?php
// app/Dao/ClientDao.php: o DAO dos clientes - o das pessoas, mais um
// método de bloqueio.

namespace App\Dao;

use App\Models\Client;

class ClientDao extends PersonDao
{
    public function __construct()
    {
        parent::__construct(Client::class);
    }

    // -----------------------------------------------------------------------
    // coloca um LOCK na linha de um cliente até o fim da transação
    // atual (SELECT ... FOR UPDATE) e retorna seu id (null se o cliente
    // não existir). Uma segunda transação que solicita o mesmo lock ESPERA
    // a primeira terminar.
    // Usado para a marcação (veja BusinessService::addAppointment): duas
    // marcações simultâneas para o mesmo paciente são assim processadas uma
    // DEPOIS da outra, e a segunda vê a consulta criada pela primeira.
    // -----------------------------------------------------------------------
    public function lock(int $id): ?int
    {
        return Client::query()->whereKey($id)->lockForUpdate()->value('id');
    }
}
  • Linhas 25–28: um bloqueio pessimista, o outro tipo de bloqueio. [lockForUpdate()] adiciona [FOR UPDATE] à consulta: [SELECT id FROM clients WHERE id = ? FOR UPDATE]. A linha lida fica bloqueada até o fim da transação atual: outra transação que solicite o mesmo bloqueio espera a primeira terminar. [value('id')] retorna o valor de uma coluna da primeira linha ([null] se não houver nenhuma). Veremos, na camada de negócio, para que serve esse bloqueio.

11.10.3. app/Dao/SlotDao.php

<?php
// app/Dao/SlotDao.php: camada DAO dos horários.

namespace App\Dao;

use App\Models\Slot;
use Illuminate\Database\Eloquent\Collection;

class SlotDao
{
    // um horário e seu médico
    public function read(int $id): ?Slot
    {
        return Slot::with('doctor')->find($id);
    }

    // os horários de um médico, em ordem cronológica
    public function listByDoctor(int $doctorId): Collection
    {
        return Slot::where('doctor_id', $doctorId)->orderBy('start_hour')->orderBy('start_minute')->get();
    }

    // exclui todos os horários de um médico (exclusão de um 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)]: um horário e seu médico (pré-carregado); [Slot::where(...)->delete()]: um [DELETE] que abrange todas as linhas que satisfazem a condição.

11.10.4. app/Dao/AppointmentDao.php

<?php
// app/Dao/AppointmentDao.php: camada DAO das consultas.
//
// A tabela [appointments] não referencia o médico diretamente: passamos pelo horário.
// whereHas('slot', ...): as consultas cujo horário satisfaz uma condição
// (o Eloquent a escreve em SQL com uma subconsulta EXISTS).

namespace App\Dao;

use App\Models\Appointment;
use Carbon\CarbonImmutable;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;

class AppointmentDao
{
    // uma consulta, seu cliente e seu horário
    public function read(int $id): ?Appointment
    {
        return Appointment::with(['client', 'slot'])->find($id);
    }

    // as consultas de um médico em um dado dia, com seu 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();
    }

    // -----------------------------------------------------------------------
    // as consultas de um cliente a partir do dia [$since] (incluído), em ordem
    // cronológica, com o horário E o médico desse horário ('slot.doctor':
    // uma relação da relação). A ordenação usa colunas da tabela
    // [slots]: é necessário um JOIN SQL; select('appointments.*'): mantemos apenas as
    // colunas de [appointments] para preencher os 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 consultas de um cliente a partir do dia [$since] (incluído)
    public function countClientUpcoming(int $clientId, CarbonImmutable $since): int
    {
        return Appointment::where('client_id', $clientId)->where('day', '>=', $since->toDateString())->count();
    }

    // número de consultas (passadas ou futuras) de um 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();
    }

    // exclui TODAS as consultas (passadas e futuras) de um cliente
    public function deleteByClient(int $clientId): void
    {
        Appointment::where('client_id', $clientId)->delete();
    }
}

A tabela [appointments] não referencia diretamente o médico: ela passa pelo horário.

  • Linhas 24–30: as consultas de um médico em um determinado dia. [whereHas('slot', function)] mantém as consultas para as quais o relacionamento [slot] satisfaz a condição definida pela função: o [Eloquent] traduz isso em uma subconsulta [EXISTS] (veja a saída do console acima). [fn (Builder $q) => ...] é uma arrow function (exemplo 03); ela recebe a consulta sobre a tabela [slots]. A data é comparada no formato [yyyy-mm-dd] ([toDateString()]), que é o mesmo das colunas [DATE];
  • Linhas 39–48: as próximas consultas de um cliente, com o respectivo horário e o médico atribuído a esse horário: [with('slot.doctor')] carrega um relacionamento a partir do relacionamento. A ordenação baseia-se na hora do horário, uma coluna da tabela [slots]: é necessário um join ([join]). [select('appointments.*')] mantém apenas as colunas da tabela [appointments] para preencher os objetos [Appointment] (caso contrário, o ID do horário sobrescreveria o ID da consulta: as duas colunas se chamam [id]);
  • linhas 51–54: [count()] executa um [SELECT COUNT(*)];
  • linhas 62–65: o objeto [CarbonImmutable] é gravado no banco de dados no formato da coluna, usando a conversão declarada pelo modelo.

11.10.5. app/Dao/UserDao.php

<?php
// app/Dao/UserDao.php: camada DAO das contas de usuário. Criar (ou excluir)
// um médico ou um cliente também cria (ou exclui) sua conta - veja app/Business.

namespace App\Dao;

use App\Models\Role;
use App\Models\User;
use Illuminate\Support\Facades\DB;

class UserDao
{
    // null se nenhum usuário tiver 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]);
    }

    // bloqueio otimista, 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();
    }
}

Contas: consulta por login, adição, modificação com bloqueio otimista, exclusão.

11.11. A camada de negócio

A camada de negócio reúne as regras de negócio e as transações (exemplo 28). Ela é descrita por uma interface e implementada por duas classes: [BusinessService], a própria camada de negócio, e [ApplicationModel], o cache da camada web (discutido mais adiante).

11.11.1. app/Business/Dates.php

<?php
// app/Business/Dates.php: a data atual. Ela é usada por REGRAS DE NEGÓCIO (nenhuma
// marcação no passado, apenas uma consulta FUTURA por paciente): ela, portanto,
// vive na camada de negócio. A camada web a reutiliza.

namespace App\Business;

use Carbon\CarbonImmutable;

class Dates
{
    // hoje à meia-noite, no fuso horário da aplicação (config/app.php)
    public static function today(): CarbonImmutable
    {
        return CarbonImmutable::today();
    }
}

A data atual à meia-noite no fuso horário da aplicação ([config/app.php]). Ela é usada nas regras de negócio (nenhuma reserva no passado, apenas uma consulta futura): por isso fica na camada de negócio. Um método estático ([static]) é chamado sem criar um objeto: [Dates::today()].

11.11.2. app/Business/BusinessException.php

<?php
// app/Business/BusinessException.php: a exceção lançada pela camada de negócio quando uma
// REGRA DE NEGÓCIO é violada (login já em uso, médico que ainda tem
// consultas, horário já reservado...). Ela não carrega um texto, mas uma
// CHAVE de tradução (p. ex. "ERRORS.LOGIN_TAKEN"): é a camada web que a
// traduzirá para francês ou inglês ao exibir a página (veja lang/*.json).
//
// Uma BusinessException não é uma anomalia: é uma resposta normal ("este login
// já está em uso"), exibida ao usuário. Qualquer outra exceção é uma verdadeira
// anomalia, que termina na página de erro 500.

namespace App\Business;

use RuntimeException;
use Throwable;

class BusinessException extends RuntimeException
{
    public function __construct(
        // chave de tradução da mensagem
        public readonly string $key,
        // possíveis parâmetros da mensagem (:minutes...)
        public readonly array $params = [],
        ?Throwable $previous = null,
    ) {
        parent::__construct($key, 0, $previous);
    }
}

A exceção lançada quando uma regra de negócio é violada. Ela não carrega texto, mas uma chave de tradução ([ERRORS.LOGIN_TAKEN]) e seus parâmetros: a camada web a traduzirá para o idioma da página (exemplo 22). A camada de negócio não sabe nada sobre os idiomas da interface. [RuntimeException] é uma subclasse do [PHP]. As propriedades do construtor [public readonly] são declaradas e inicializadas pela promoção de construtor (exemplo 03); [parent::__construct($key, 0, $previous)] chama o construtor de [RuntimeException], passando a mensagem, o código e a exceção anterior (aquela que causou esta, um erro de banco de dados, por exemplo: ela aparece no log junto com a nova).

11.11.3. app/Business/PersonData.php

<?php
// app/Business/PersonData.php: os dados digitados em um formulário de "médico" ou "cliente",
// como a camada web os repassa à camada de negócio.

namespace App\Business;

readonly class PersonData
{
    public function __construct(
        public string $title,        // Mr, Mme, Melle
        public string $lastName,
        public string $firstName,
        // criação: opcional (null), por padrão o sobrenome em minúsculas
        // modificação: opcional, o login permanece inalterado se estiver ausente
        public ?string $login = null,
        // criação: opcional, por padrão o login
        // modificação: opcional, a senha permanece inalterada se estiver ausente
        public ?string $password = null,
        // modificação: a versão do registro quando o formulário foi
        // exibido (bloqueio otimista)
        public ?int $version = null,
    ) {
    }
}

Os dados de um formulário de “pessoa”, como transmitidos pela camada web à camada de negócio: uma classe [readonly]. O login, a senha e a versão são opcionais ([?string], [?int], valor padrão [null]); os comentários explicam o que significa a ausência deles.

11.11.4. app/Business/Business.php

<?php
// app/Business/Business.php: o CONTRATO da camada de negócio: leituras, agenda,
// consultas, gerenciamento de médicos e clientes.
//
// Uma INTERFACE descreve os métodos que uma classe deve ter, sem dizer como
// eles são escritos. BusinessService (a camada de negócio) e ApplicationModel (o cache
// da camada web) a implementam; o PHP verifica, ao carregar
// a classe, que nenhum método está faltando.
//
// ?Type: um resultado que pode estar ausente (null: um médico que não 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
{
    // ================================================ leituras
    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;

    // o cliente (paciente) cuja conta de usuário é [$userId]
    public function getClientByUserId(int $userId): ?Client;

    // as consultas de um cliente, de hoje ou futuras, com horário e médico
    public function getClientUpcomingAppointments(int $clientId): Collection;

    // ================================================ consultas (ADMIN, DOCTOR, USER)
    // lança uma BusinessException se:
    //  - o dia é passado ("ERRORS.PAST_DATE");
    //  - o paciente já tem uma consulta futura ("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
    //  - o horário já está ocupado nesse dia ("ERRORS.SLOT_ALREADY_BOOKED").
    public function addAppointment(CarbonImmutable $day, Slot $slot, Client $client): Appointment;

    public function deleteAppointment(Appointment $appointment): void;

    // ================================================ médicos (ADMIN)
    // cria o médico E sua conta de usuário (papel DOCTOR)
    public function addDoctor(PersonData $data): Doctor;

    // modifica o médico E sua conta de usuário
    public function editDoctor(int $id, PersonData $data): Doctor;

    // exclui o médico, seus horários E sua conta - recusado se ele tiver consultas
    public function deleteDoctor(int $id): void;

    // ================================================ clientes
    // (o ADMIN; addClient também é usado para o cadastro de um paciente,
    // editClient e deleteClient pelo paciente para a sua própria conta)
    // cria o cliente E sua conta de usuário (papel USER)
    public function addClient(PersonData $data): Client;

    public function editClient(int $id, PersonData $data): Client;

    // exclui o cliente, sua conta E todas as suas consultas (passadas e futuras)
    public function deleteClient(int $id): void;
}

O contrato da camada de negócio: uma interface (exemplo 06), a lista de métodos, sem o código. As operações de leitura retornam objetos [Eloquent] ou [Collection]; [?Client]: um cliente ou [null] se ele não existir. Os comentários especificam as regras de cada operação de escrita e as chaves dos objetos [BusinessException] que ela pode criar.

11.11.5. app/Business/Descriptor.php

<?php
// app/Business/Descriptor.php: tudo o que distingue um médico de um cliente para as
// regras de negócio (veja BusinessService). Médicos e clientes seguem as
// mesmas regras: o código comum é escrito UMA VEZ, e parametrizado por um 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 ou USER
        public string $notFoundKey,     // mensagem se a pessoa não existir
        public string $alreadyExistsKey, // mensagem se o mesmo nome e sobrenome já existirem
        // opcional (null): se presente, a exclusão é RECUSADA enquanto a
        // pessoa tiver consultas (countAppointments(id) > 0), com a mensagem hasAppointmentsKey
        public ?Closure $countAppointments,
        public ?string $hasAppointmentsKey,
        // opcional: o que deve ser excluído ANTES da pessoa (as linhas que
        // a referenciam por uma chave estrangeira); recebe seu id
        public ?Closure $beforeDelete,
    ) {
    }
}

Médicos e clientes seguem as mesmas regras de gestão, com algumas pequenas diferenças: o DAO, o papel da conta, as mensagens de erro e a regra de exclusão. Este descritor reúne esses detalhes; o código comum os lê. Duas propriedades são funções ([?Closure]: uma função ou [null]): a contagem de consultas, que impede a exclusão (apenas para médicos), e a exclusão do que referencia a pessoa.

11.11.6. app/Business/BusinessService.php

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
<?php
// =========================================================================
// app/Business/BusinessService.php: a implementação da camada de negócio.
//
// O gerenciamento de médicos e clientes obedece a três regras de negócio:
//
//   1. uma pessoa (médico ou cliente) e sua conta de usuário SEMPRE andam
//      juntas: são criadas, modificadas e excluídas juntas, na mesma
//      TRANSAÇÃO - ou tudo dá certo, ou nada é gravado;
//   2. o login é único em toda a aplicação, e dois médicos (ou dois
//      clientes) não podem ter o mesmo nome e sobrenome;
//   3. exclusão:
//      - um MÉDICO que tem consultas não pode ser excluído (seus pacientes
//        perderiam sua consulta sem serem avisados): elas devem primeiro ser
//        canceladas. Seus horários desaparecem com ele;
//      - um CLIENTE, por outro lado, desaparece com TODAS as suas consultas (passadas e futuras) -
//        quer a exclusão venha do ADMIN ou do próprio paciente.
//
// E duas regras para a marcação, qualquer que seja o papel de quem
// marca (ADMIN, DOCTOR ou o próprio paciente):
//   4. nenhuma consulta no passado;
//   5. um paciente tem apenas UMA consulta futura por vez.
//
// Médicos e clientes seguem exatamente as mesmas regras: o código comum é
// escrito UMA VEZ (métodos privados xxxPerson), e parametrizado por um descriptor
// que diz com que tipo de pessoa estamos lidando.
//
// As TRANSAÇÕES são abertas pelo método transaction (no final do arquivo),
// que também traduz em BusinessException os erros relatados pelo banco de dados.
// =========================================================================

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
{
    // -----------------------------------------------------------------------
    // Erros do banco de dados -> BusinessException
    //
    // Quando uma restrição UNIQUE recusa uma gravação, o Laravel lança uma
    // QueryException, cuja mensagem é a do MySQL. Ela cita o NOME da
    // restrição:
    //   Duplicate entry 'Marie-PELISSIER' for key 'doctors.unq_doctors_first_name_last_name'
    // (o MySQL 8 prefixa o nome com o da tabela, o MariaDB não). É por isso que
    // o script SQL NOMEIA todas as suas restrições.
    // -----------------------------------------------------------------------
    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 as dependências são fornecidas pelo service container do Laravel
    // (injeção de dependência, veja o exemplo 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(...): o próprio método, como uma Closure
            // (a chamada sintaxe "first-class callable")
            countAppointments: $appointments->countByDoctor(...),
            hasAppointmentsKey: 'ERRORS.DOCTOR_HAS_APPOINTMENTS',
            // um médico sem consultas ainda pode ter horários:
            // eles não fazem sentido sem ele, são excluídos com ele (caso contrário, a
            // chave estrangeira slots.doctor_id proibiria a exclusão)
            beforeDelete: $slots->deleteByDoctor(...));

        $this->client = new Descriptor(
            dao: $clients,
            role: Role::USER,
            notFoundKey: 'ERRORS.PATIENT_NOT_FOUND',
            alreadyExistsKey: 'ERRORS.PATIENT_ALREADY_EXISTS',
            // sem countAppointments: a exclusão de um cliente nunca é recusada;
            // suas consultas (passadas e futuras) são excluídas com ele (caso contrário,
            // a chave estrangeira appointments.client_id proibiria a exclusão)
            countAppointments: null,
            hasAppointmentsKey: null,
            beforeDelete: $appointments->deleteByClient(...));
    }

    // =======================================================================
    // leituras
    // =======================================================================

    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());
    }

    // a agenda de um médico em um dado dia: seus horários e, para cada um, a
    // consulta marcada nesse dia (null se estiver livre)
    public function getDoctorDaySchedule(int $doctorId, CarbonImmutable $day): ?DoctorDaySchedule
    {
        $doctor = $this->getDoctorById($doctorId);
        if ($doctor === null) {
            return null;
        }
        // nº do horário -> consulta marcada nesse horário (keyBy: uma collection
        // indexada pelo valor de uma coluna)
        $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);
    }

    // =======================================================================
    // consultas
    // =======================================================================

    // -----------------------------------------------------------------------
    // marcação de uma consulta, em uma transação:
    //   1. nenhuma consulta no passado;
    //   2. BLOQUEAMOS a linha do paciente (SELECT ... FOR UPDATE): se o mesmo
    //      paciente marca dois horários no mesmo instante (duas abas, duplo
    //      clique...), a segunda transação espera o fim da primeira - e então vê
    //      a consulta que ela acabou de criar;
    //   3. apenas uma consulta futura por paciente;
    //   4. por fim, a inserção. Se o horário acabou de ser ocupado por OUTRO paciente,
    //      é a restrição SQL unq1_appointments (day, slot_id) que recusa
    //      a inserção - traduzida em 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));
    }

    // =======================================================================
    // médicos e clientes - os métodos públicos delegam aos métodos privados
    // comuns, com o descritor correto
    // =======================================================================

    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);
    }

    // o cliente, sua conta E todas as suas consultas (ADMIN, ou o próprio paciente
    // a partir de "Manage my account": mesmo método, mesma regra)
    public function deleteClient(int $id): void
    {
        $this->deletePerson($this->client, $id);
    }

    // -----------------------------------------------------------------------
    // criação: a conta de usuário, DEPOIS a pessoa (que a referencia), em
    // UMA transação.
    // -----------------------------------------------------------------------
    private function addPerson(Descriptor $d, PersonData $data): Person
    {
        $lastName = Str::upper(trim($data->lastName));
        $firstName = trim($data->firstName);
        // as regras do banco de dados dbrdvmedecins2: login = sobrenome em minúsculas,
        // senha = login - a menos que o ADMIN (ou o paciente) tenha digitado outros
        $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: o hash bcrypt da senha (veja 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: a conta, já em memória, é armazenada na relação
            // [account] da pessoa (não é preciso lê-la novamente do banco de dados)
            return $person->setRelation('account', $user);
        });
    }

    // -----------------------------------------------------------------------
    // modificação: a pessoa E sua conta (o nome exibido "first name LAST NAME" deve
    // acompanhar; o login e a senha só mudam se tiverem sido digitados).
    // -----------------------------------------------------------------------
    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);

            // bloqueio otimista: se a versão no banco de dados não é mais a do
            // formulário, alguém modificou este registro nesse meio tempo - recusamos
            // em vez de sobrescrever silenciosamente as modificações dessa pessoa
            $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);

            // a pessoa: UPDATE ... WHERE id = ? AND version = ? (se o registro foi
            // modificado DEPOIS da leitura acima, nenhuma linha é modificada)
            if ($d->dao->edit($id, $version, ['title' => $data->title, 'last_name' => $lastName,
                'first_name' => $firstName]) === 0) {
                throw new BusinessException('ERRORS.CONCURRENT_UPDATE');
            }

            // sua conta: o nome exibido e, se tiverem sido digitados, o login e a
            // senha
            $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');
            }

            // a pessoa lida novamente: seus novos valores, suas novas versões
            return $d->dao->read($id);
        });
    }

    // -----------------------------------------------------------------------
    // exclusão, em UMA transação, na ordem imposta pelas chaves
    // estrangeiras:
    //   1. possível recusa se restarem consultas (médico);
    //   2. o que referencia a pessoa (horários de um médico, consultas de um
    //      cliente);
    //   3. a pessoa (que referencia sua conta);
    //   4. sua conta.
    // -----------------------------------------------------------------------
    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);
        });
    }

    // recusa nomes e sobrenomes já usados por OUTRA pessoa do mesmo tipo
    // ($currentId: a pessoa que está sendo modificada, que evidentemente tem o direito
    // de manter seu próprio nome e sobrenome; null em uma criação)
    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');
        }
    }

    // -----------------------------------------------------------------------
    // executa [$work] em uma transação (DB::transaction, veja o exemplo 28):
    // COMMIT se a função terminar normalmente; se uma exceção sair dela
    // (BusinessException incluída), ROLLBACK: nada é gravado.
    //
    // As verificações de "login livre" e de "nome + sobrenome únicos" são feitas ANTES da
    // gravação, para dar uma mensagem clara. Mas dois ADMINs poderiam
    // salvar o mesmo login (ou o mesmo médico) no mesmo instante: nesse
    // caso raro, é uma restrição de unicidade SQL que recusa a segunda gravação. Nós
    // interceptamos, portanto, os erros do banco de dados AO REDOR da transação, para
    // traduzi-los na mesma BusinessException. Qualquer outro erro é uma anomalia real:
    // deixamos que ele 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;
        }
    }
}

O arquivo mais importante da aplicação. Vamos percorrê-lo por tema.

11.11.6.1. Os descritores

Linhas 89–113: os dois descritores, criados uma única vez pelo construtor. Os argumentos nomeados ([dao: $doctors], exemplo 01) tornam a chamada legível. [$appointments->countByDoctor(...)] (com três pontos entre parênteses) não conta nada: é a sintaxe do [PHP] 8.1 que gera, a partir de um método, uma [Closure], uma função que será chamada mais tarde ([($d->countAppointments)($id)], linha 349). Um médico é removido junto com seus horários ([deleteByDoctor]), mas não se tiver consultas; um cliente é removido junto com todas as suas consultas ([deleteByClient]).

11.11.6.2. Leituras e o calendário

As leituras (linhas 120–165) são delegadas à camada DAO. A agenda de um médico (linhas 172–185) é calculada: o médico, seus horários e as consultas do dia. [keyBy('slot_id')] transforma a coleção de consultas em uma coleção indexada pelo número do horário: [$bookings->get($slot->id)] retorna a consulta de um determinado horário, ou [null]. [map] transforma cada horário em um [DoctorDaySlot]; [all()] retorna o array [PHP] contido na coleção.

11.11.6.3. Marcação de uma consulta

Linhas 203–217: quatro etapas, em uma única transação.

  • nenhuma consulta no passado: [$day->lt($today)] (*less than*, menor que) compara duas datas;
  • o registro do paciente é bloqueado ([lock], [SELECT ... FOR UPDATE]). Por quê? A regra “apenas uma consulta futura por paciente” é verificada por uma contagem (terceira etapa), e depois ocorre a inserção (quarta etapa). Se o mesmo paciente reservar dois horários ao mesmo tempo (duas abas, um clique duplo), as duas transações poderiam contar zero consultas e depois inserir cada uma a sua: a regra seria violada. Com o bloqueio, a segunda transação espera a primeira terminar e depois conta... uma consulta. [?? throw new BusinessException(...)]: se o cliente não existir mais, [lock] retorna [null], e o operador [??] avalia seu segundo operando, que lança a exceção (desde o [PHP] 8, [throw] é uma expressão);
  • contagem das consultas futuras;
  • inserção. Se o horário acabou de ser ocupado por outro paciente, a restrição do banco de dados [unq1_appointments] rejeita a inserção: o método [transaction] traduz esse erro em [BusinessException].

11.11.6.4. Gerenciamento de médicos e pacientes

Os métodos públicos (linhas 229–256) chamam os métodos privados compartilhados, usando o descritor correto.

  • Linhas 265–285: criação. O sobrenome é colocado em maiúsculas ([Str::upper]), e o nome e o sobrenome têm os espaços desnecessários removidos ([trim]). Por padrão, o login é o sobrenome em minúsculas, e a senha é o login (conforme as regras das contas de demonstração): [$a ?: $b] equivale a [$a] se ele for “válido” (nem [null] nem uma string vazia), e a [$b] caso contrário. Na transação: as validações (o nome e o sobrenome podem ter qualquer valor, o login pode ter qualquer valor), seguidas da conta, com hash gerado por [Hash::make] (exemplo 25), seguida da pessoa, que referencia a conta. [setRelation('account', $user)] armazena a conta, já em memória, no registro da pessoa: [$person->account] não disparará uma consulta. [use (...)]: uma função anônima comum ([function () use ($d, ...)]) não enxerga as variáveis do método que a contém; [use] as passa para ela (uma arrow function, [fn () =>], as enxerga por conta própria, mas só pode conter uma expressão);
  • Linhas 291–334: a modificação, com dois bloqueios otimistas. O primeiro é uma comparação: a versão do formulário (campo oculto, exemplo 28) deve corresponder à do registro no banco de dados; caso contrário, alguém modificou o registro entre o momento em que o formulário foi exibido e o momento em que foi enviado. O segundo é a cláusula [WHERE version = ?] do [UPDATE] ([PersonDao::edit]), que detecta uma alteração ocorrida entre a leitura e a escrita. A conta é tratada assim: seu nome exibido (“nome SOBRENOME”) é sempre atualizado; seu login e sua senha são atualizados somente se tiverem sido informados; seu próprio bloqueio otimista também protege a linha da tabela [users]. Por fim, a pessoa é lida novamente: quem chamou recebe os novos valores e as novas versões;
  • linhas 345–358: a exclusão, na ordem ditada pelas chaves estrangeiras: primeiro o que referencia a pessoa (horários ou consultas), depois a pessoa e, por fim, sua conta. A ordem inversa seria rejeitada pelo banco de dados: uma linha que ainda é referenciada por uma chave estrangeira não pode ser excluída;
  • linhas 363–369: a pessoa que está sendo modificada pode manter seu próprio nome e sobrenome; [$currentId] equivale a [null] para um novo registro.

11.11.6.5. Transações e restrições de unicidade

Linhas 391–402: todas as gravações passam por este método. [DB::transaction] executa a função em uma transação (exemplo 28): [COMMIT] se ela terminar normalmente, [ROLLBACK] se ocorrer uma exceção, inclusive [BusinessException]: uma violação de regra no meio de uma operação não deixa vestígios. As verificações de “login disponível” e de “nome e sobrenome disponíveis” são feitas antes de gravar no banco de dados, para fornecer uma mensagem clara. No entanto, dois administradores poderiam tentar cadastrar o mesmo login ao mesmo tempo: cada um o encontra disponível, e o segundo [INSERT] é rejeitado pela restrição [unq_users_login]. O [Laravel] então lança uma [QueryException], cuja mensagem é a do [MySQL]; ela contém o nome da restrição violada:

SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry 'dupont' for key 'unq_users_login'

A expressão regular da linha 74 extrai esse nome (o [MySQL] 8 o prefixa com o nome da tabela, [users.unq_users_login], mas o [MariaDB] não: a parte "[(?:[^'.]*\.)?]" aceita as duas formas), e o array das linhas 67–72 fornece a chave da mensagem. Qualquer outro erro de banco de dados é uma anomalia verdadeira: ele é relançado ([throw $e]) e resultará em uma página de erro 500.

11.12. Autenticação

A pasta [app/Auth] reúne os exemplos 25 a 27, com usuários do banco de dados e algumas medidas de segurança adicionais.

11.12.1. app/Auth/ConnectedUser.php

<?php
// =========================================================================
// app/Auth/ConnectedUser.php: o usuário logado, conforme descrito por seu
// token JWT (veja o exemplo 25). Authenticatable: a interface que o Laravel espera
// dos usuários autenticados (Auth::user(), auth()->user(), @auth em uma view...).
//
// As claims de nossos tokens (veja AuthService::tokenCookie):
//   sub   : o id da conta de usuário (convenção JWT: "subject"), como texto
//   login : o login
//   name  : o nome exibido ("Marie PELISSIER"), para a barra de navegação
//   role  : ADMIN, DOCTOR ou USER
//   iat, exp : datas de criação e de expiração do token
//
// Este objeto NÃO vem do banco de dados: ele é reconstruído, a cada requisição,
// a partir do token, cuja assinatura garante o conteúdo.
// =========================================================================

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,
    ) {
    }

    // o usuário descrito pelas claims de um token já verificado; null se uma claim
    // estiver ausente ou não tiver a forma esperada. Role::tryFrom: null para um papel desconhecido
    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;
    }

    // a interface Authenticatable: o identificador do usuário é o id
    // de sua conta; a senha e o token "remember me" das sessões do Laravel
    // são irrelevantes aqui
    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 '';
    }
}

O usuário logado, como descrito por seu token: o ID da conta, o nome de usuário, o nome e o papel. Como [User] no exemplo 25, ele implementa a interface [Authenticatable], que o [Laravel] espera dos usuários autenticados. Esse objeto não vem do banco de dados: ele é reconstruído a cada requisição com base no token, cuja assinatura garante o conteúdo. A aplicação, portanto, não lê a conta do banco de dados a cada requisição.

  • Linhas 35–43: o usuário é descrito pelas declarações (claims) de um token já verificado , ou por [null] se alguma das declarações estiver ausente ou não tiver o formato esperado. Um token devidamente assinado nunca deveria estar malformado; no entanto, a chave secreta poderia ser compartilhada com outra aplicação, que poderia gerar tokens diferentes: ser cauteloso não custa nada. [Role::tryFrom] retorna o papel, ou [null] para um valor desconhecido; [ctype_digit] verifica se uma string é composta apenas de dígitos;
  • linhas 45–50: duas perguntas que as views e os controllers fazem com frequência;
  • linhas 58–61 e seguintes: a interface [Authenticatable]. O identificador do usuário é o ID da conta; a senha e o token “lembrar de mim” são irrelevantes.

11.12.2. app/Auth/AuthService.php

<?php
// =========================================================================
// app/Auth/AuthService.php: a lógica de autenticação:
//   - validate()       : verifica um par login / senha;
//   - tokenCookie()    : constrói o token JWT de um usuário validado e o
//                        cookie que o transporta;
//   - currentUser()    : o usuário descrito por um token.
//
// Por onde o token JWT trafega? Em um COOKIE (veja o exemplo 25): um navegador
// que exibe páginas HTML comuns o apresenta, assim, por conta própria, a cada
// requisição. As opções deste cookie importam para a segurança:
//   - HttpOnly: o JavaScript da página não pode ler o cookie (um script
//     injetado não poderia, portanto, roubar o token);
//   - SameSite=Lax: o navegador NÃO envia o cookie em um POST vindo de
//     outro site (primeira proteção contra o chamado ataque CSRF; a segunda é
//     o token anti-CSRF dos formulários, veja @csrf);
//   - Secure: em produção (HTTPS), o cookie nunca trafega sem criptografia;
//   - duração: o cookie desaparece ao mesmo tempo em que o token expira.
// =========================================================================

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
{
    // o nome do cookie que carrega o 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 exige uma chave de pelo menos 256 bits: dizemos isso claramente,
        // em vez de deixar a biblioteca falhar mais adiante
        if (strlen($this->secret) < 32) {
            throw new RuntimeException('JWT_SECRET must be at least 32 characters long (see .env).');
        }
    }

    // null se o login não existe ou se a senha está errada. Hash::check
    // faz o hash da senha digitada com o "salt" contido no hash armazenado
    // e então compara os dois 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;
    }

    // -----------------------------------------------------------------------
    // o token JWT de [$user], no cookie que o transporta. O token é ASSINADO
    // (HMAC-SHA256) com a chave secreta: o navegador pode lê-lo (ele não é
    // criptografado), mas não modificá-lo - qualquer modificação tornaria a assinatura
    // inválida.
    // -----------------------------------------------------------------------
    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(name, value, duração em minutos, path, domain, secure, httpOnly,
        // raw, sameSite): a função do Laravel que constrói um cookie
        return cookie(self::COOKIE, $token, $this->duration, '/', null,
            config('rdvmedecins.cookie_secure'), true, false, 'lax');
    }

    // o cookie que LIMPA o token: o mesmo nome, vazio, já expirado
    public static function clearingCookie(): Cookie
    {
        return cookie()->forget(self::COOKIE);
    }

    // -----------------------------------------------------------------------
    // o usuário descrito por um token; null se o token está expirado, forjado ou
    // malformado. JWT::decode verifica a assinatura E a data de expiração (claim exp).
    // -----------------------------------------------------------------------
    public function currentUser(string $token): ?ConnectedUser
    {
        try {
            // decode retorna um objeto; (array) o converte em um array associativo
            $claims = (array) JWT::decode($token, new Key($this->secret, 'HS256'));
        } catch (Throwable) {
            return null;
        }
        return ConnectedUser::of($claims);
    }
}
  • Linha 35: o nome do cookie do token, uma constante de classe, lida por [AuthService::COOKIE]. Por que não configurá-lo em [config/rdvmedecins.php], como a chave secreta? Porque o [bootstrap/app.php] precisa dele para excluir o cookie da criptografia em um momento em que a configuração ainda não foi carregada: o código de [withMiddleware] é executado antes que o [Laravel] leia os arquivos da pasta [config];
  • linhas 41–50: a chave e a duração do token, lidas da configuração. Se a chave for curta demais, isso é sinalizado assim que o serviço é criado, com uma mensagem clara (veja “Problemas comuns”);
  • linhas 55–62: verificação de um nome de usuário e de uma senha (exemplo 25), com a conta recuperada do banco de dados pela camada DAO. Observe que esse serviço usa diretamente a camada DAO, sem passar pela camada de negócio: a verificação de senha não é uma regra de negócio;
  • Linhas 70–86: o token do usuário e o cookie que o transporta. As declarações são as mesmas do exemplo 25, inclusive o ID da conta ([sub], uma string, como exige o padrão) e o nome de usuário. A função [cookie] do [Laravel] gera um cookie: nome, valor, duração em minutos (a do token), caminho, domínio ([null]: o do site), [secure] (em produção, em HTTPS), [httpOnly], [raw] ([false]: o valor é codificado para uma URL) e [sameSite];
  • linhas 89–92: o cookie que apaga o token: [cookie()->forget(name)] cria um cookie vazio com o mesmo nome, já expirado;
  • linhas 98–107: verificação do token (exemplo 25).

11.12.3. app/Auth/InvalidSession.php

<?php
// app/Auth/InvalidSession.php: o token é válido, mas a conta que ele designa
// não existe mais: foi excluída desde o login (pelo próprio paciente
// em outra aba, ou pelo ADMIN). Tratamos este caso como uma sessão
// expirada: bootstrap/app.php limpa o cookie e redireciona para a página de login.

namespace App\Auth;

use RuntimeException;

class InvalidSession extends RuntimeException
{
}

Um cenário não coberto no exemplo 25: o token é válido, mas a conta a que ele se refere não existe mais. Um paciente excluiu sua conta em uma aba, mas o token ainda está presente em outra aba; ou o administrador excluiu a conta de um paciente logado. A assinatura do token não dá nenhuma indicação sobre a existência da conta; é somente quando a aplicação procura o paciente associado à conta ([Utils::connectedPatient], discutido mais adiante) que ela descobre que a conta não existe mais. Ela então lança esta exceção, que o [bootstrap/app.php] trata como uma sessão expirada. A classe é vazia: só importa o seu tipo , o que permite associá-la à sua própria função de renderização.

11.12.4. app/Auth/CaptchaService.php, Captcha.php e CaptchaDrawing.php

[CaptchaDrawing.php] e [Captcha.php] são do exemplo 27. O serviço é quase o mesmo:

<?php
// =========================================================================
// app/Auth/CaptchaService.php: um CAPTCHA ("teste para distinguir um humano de um
// robô") construído pelo próprio servidor, sem serviço externo (veja o exemplo 27).
//
// Como funciona:
//   1. generate() sorteia um texto aleatório, faz uma imagem dele e armazena a resposta
//      certa NO CACHE do servidor, sob um identificador aleatório;
//   2. a página exibe a imagem e coloca o identificador em um campo oculto do
//      formulário (a própria resposta nunca sai do servidor);
//   3. verify(id, typed) compara o que foi digitado com a resposta esperada e depois ESQUECE
//      este captcha: cada imagem só é usada uma vez, um robô não pode reutilizar
//      uma resposta já encontrada.
//
// Por que o cache? Uma aplicação PHP não guarda NADA na memória de uma requisição
// para a seguinte: cada requisição parte do zero. O que deve durar além de uma requisição
// vai, portanto, para o cache (aqui arquivos, veja CACHE_STORE em .env), compartilhado por
// todas as requisições e até por vários servidores com um cache como o Redis.
// =========================================================================

namespace App\Auth;

use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Str;

class CaptchaService
{
    // duração de validade de uma imagem, em segundos: 10 minutos para preencher o formulário
    private const LIFETIME = 600;

    public function generate(): Captcha
    {
        $text = CaptchaDrawing::randomText(5);        // 5 caracteres
        $id = Str::random(24);                        // um identificador impossível de adivinhar
        // o cache esquecerá a resposta sozinho após 10 minutos
        Cache::put("captcha:$id", $text, self::LIFETIME);
        return new Captcha($id, CaptchaDrawing::svg($text));
    }

    // true se [$typed] é a resposta certa para o captcha [$id] (independentemente
    // de maiúsculas e minúsculas). O captcha é consumido em todos os casos.
    public function verify(?string $id, ?string $typed): bool
    {
        if (! $id || $typed === null) {
            return false;
        }
        $expected = Cache::get("captcha:$id");
        // forget retorna true somente para a requisição que REALMENTE removeu a entrada:
        // se duas requisições apresentam o mesmo captcha no mesmo instante, só uma
        // o remove - a outra falha
        if ($expected === null || ! Cache::forget("captcha:$id")) {
            return false;
        }
        return strcasecmp($expected, trim($typed)) === 0;
    }
}
  • linhas 31–38: uma string de 5 caracteres gerada aleatoriamente, um identificador aleatório ([Str::random], que usa um gerador criptográfico) e a resposta correta armazenada no cache por 10 minutos (exemplo 27);
  • linhas 42–55: uma diferença em relação ao exemplo 27, que usava [Cache::pull] (ler e depois remover). Entre a leitura e a remoção, uma segunda requisição que exibisse o mesmo CAPTCHA também poderia lê-lo: duas tentativas para uma única imagem resolvida. Aqui, a resposta é lida e depois removida por [Cache::forget], que retorna [true] somente se ele tiver de fato removido a entrada: com cache em arquivos, isso envolve apagar um arquivo, o que o sistema operacional permite que apenas um dos dois processos faça. A requisição que perde a corrida falha. Isso equivale ao bloqueio da versão [Flask], em que os CAPTCHAs eram mantidos em memória.

11.12.5. app/Auth/AttemptLimiter.php

<?php
// =========================================================================
// app/Auth/AttemptLimiter.php: segunda linha de defesa contra robôs (a primeira é
// o captcha): CONTAMOS as tentativas e, acima de um limite, BLOQUEAMOS por
// um tempo (veja o exemplo 27).
//
//   - login: após LOGIN_MAX_FAILURES falhas (captcha errado ou senha
//     errada) para o mesmo login a partir do mesmo endereço IP, este par é
//     bloqueado até o fim de uma janela de LOGIN_BLOCK_MINUTES minutos, contada
//     a partir da primeira falha. O mesmo endereço IP também é bloqueado se
//     acumular 5 vezes mais falhas, todos os logins somados (um robô que tenta milhares
//     de logins diferentes);
//   - criação de conta: no máximo REGISTRATION_MAX_PER_HOUR contas criadas por
//     hora a partir do mesmo endereço IP.
//
// Atenção em sala de aula: todos os computadores costumam sair para a Internet pelo
// MESMO endereço IP. É por isso que o bloqueio de login se aplica primeiro ao
// par (IP, login) - um aluno que digita uma senha errada não bloqueia seus
// colegas - e por isso os limites são ajustáveis (arquivo .env).
//
// Os contadores são os do limiter do Laravel (RateLimiter), armazenados no cache.
// =========================================================================

namespace App\Auth;

use Illuminate\Support\Facades\RateLimiter;
use Illuminate\Support\Str;

class AttemptLimiter
{
    private int $maxFailures;

    private int $block;    // em 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 bloqueio restantes (0 = a tentativa é permitida)
    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 no contador; o primeiro hit abre uma janela de
    // [$this->block] segundos, ao fim da qual o contador recomeça do zero
    public function loginFailure(string $ip, string $login): void
    {
        RateLimiter::hit(self::loginKey($ip, $login), $this->block);
        RateLimiter::hit(self::ipKey($ip), $this->block);
    }

    // um login bem-sucedido zera o contador DESTE login
    public function loginSuccess(string $ip, string $login): void
    {
        RateLimiter::clear(self::loginKey($ip, $login));
    }

    // criação de conta

    public function registrationBlockMinutes(string $ip): int
    {
        return $this->remainingMinutes("registration|$ip", $this->maxRegistrations);
    }

    // janela de uma hora
    public function registrationSuccess(string $ip): void
    {
        RateLimiter::hit("registration|$ip", 3600);
    }

    // mecânica comum

    // tooManyAttempts: o contador atingiu [$maximum] na janela
    // atual? availableIn: segundos restantes até o fim desta janela,
    // arredondados PARA CIMA em minutos: 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";
    }
}

A segunda linha de defesa contra bots, depois do CAPTCHA: contamos as tentativas e, quando um limite é excedido, bloqueamos o acesso. O exemplo 27 apresentou o limitador do [Laravel], a fachada [RateLimiter]. Esta classe o usa para duas regras:

  • login (linhas 47–62): cada tentativa malsucedida (CAPTCHA ou senha incorretos) é contada duas vezes: uma para o par (endereço IP, login) e outra apenas para o endereço IP. O par é bloqueado após 5 tentativas malsucedidas (configuração [LOGIN_MAX_FAILURES]), e o endereço IP após 25, em todos os logins: é o bot que tenta milhares de logins diferentes. Por que não bloquear primeiro o endereço IP? Em uma sala de aula (ou em uma empresa), todas as máquinas costumam acessar a Internet pelo mesmo endereço IP: um aluno que digita a senha errada não deve bloquear os colegas. [RateLimiter::hit(key, duration)] incrementa o contador em 1; o primeiro [hit] abre uma janela de 15 minutos (configuração [LOGIN_BLOCK_MINUTES]), ao fim da qual o contador volta a zero. Um login bem-sucedido zera o contador desse usuário ([RateLimiter::clear]);
  • criação de conta (linhas 69–75): no máximo 10 contas por hora por endereço IP (configuração [REGISTRATION_MAX_PER_HOUR]);
  • linhas 85–91: [tooManyAttempts(key, maximum)] indica se o contador atingiu o máximo na janela atual; [availableIn(key)] retorna o número de segundos restantes nessa janela, arredondado para cima até o minuto ([ceil]): restam 30 segundos, mas é anunciado “1 minuto”. A mensagem exibida depende disso: “Muitas tentativas malsucedidas. Tente novamente em 15 minuto(s).”;
  • linhas 93–96: as chaves dos contadores. O login é convertido em minúsculas: [Admin] e [admin] são considerados o mesmo (como no banco de dados; veja sua collation).

Os contadores do [RateLimiter] são armazenados no cache: eles são compartilhados por todas as requisições e sobrevivem a uma reinicialização do servidor. O comando [php artisan cache:clear] limpa o cache, zerando assim todos os contadores (útil durante o desenvolvimento, quando você se bloqueou).

11.12.6. app/Auth/RegistrationPass.php

<?php
// =========================================================================
// app/Auth/RegistrationPass.php: o "passe" de criação de conta.
//
// Para abrir a página "Create a client account", é preciso antes ter copiado o
// captcha da página de login (veja RegistrationController, POST
// /register/access). O servidor então emite um passe:
//   - um identificador aleatório, armazenado em um cookie HttpOnly;
//   - válido por 15 minutos (o tempo de preencher o formulário, mesmo tentando
//     várias vezes após erros de entrada);
//   - consumido assim que uma conta é criada: UM captcha resolvido = UMA conta no máximo.
//     Um robô não pode criar contas em série.
//
// Sem um passe válido, GET e POST /register redirecionam para a página de
// login (middleware CheckRegistrationPass): digitar a URL /register
// diretamente não contorna o captcha.
//
// Assim como os captchas, os passes vivem no cache.
// =========================================================================

namespace App\Auth;

use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Str;
use Symfony\Component\HttpFoundation\Cookie;

class RegistrationPass
{
    public const COOKIE = 'rdvmedecins_registration';

    // duração de um passe, em minutos
    private const LIFETIME = 15;

    // emite um novo passe; retorna seu identificador
    public function issue(): string
    {
        $id = Str::random(24);
        Cache::put("pass:$id", true, self::LIFETIME * 60);
        return $id;
    }

    // true se [$id] é um passe existente e não expirado
    public function isValid(?string $id): bool
    {
        return $id !== null && $id !== '' && Cache::has("pass:$id");
    }

    // o passe foi usado: nós o esquecemos
    public function consume(?string $id): void
    {
        if ($id) {
            Cache::forget("pass:$id");
        }
    }

    // o navegador só envia o cookie para os endereços /register...
    public static function cookie(string $id): Cookie
    {
        return cookie(self::COOKIE, $id, self::LIFETIME, '/register', null,
            config('rdvmedecins.cookie_secure'), true, false, 'lax');
    }

    // ... e ele é limpo por um cookie com o mesmo nome e o mesmo path, já expirado
    public static function clearingCookie(): Cookie
    {
        return cookie()->forget(self::COOKIE, '/register');
    }
}

A criação de uma conta de paciente é protegida pelo CAPTCHA da página de login. Mas o formulário de criação de conta está em outra página ([/register]): como saber, quando o formulário é solicitado, que o CAPTCHA foi resolvido logo antes? Por meio de um token: quando o CAPTCHA é resolvido, o servidor gera um identificador aleatório, armazena-o no cache por 15 minutos e o envia ao navegador em um cookie. O formulário só é exibido, e a conta só é criada, com um token válido; o token é consumido quando a conta é criada. Um CAPTCHA resolvido permite, assim, criar uma conta, e digitar diretamente o endereço [/register] não funcionará.

  • Linhas 57–61: o cookie tem o caminho [/register]; o navegador só o envia a endereços que começam com esse caminho. Ele é criptografado pelo [Laravel], como todos os cookies da aplicação, exceto dois (veja [bootstrap/app.php]): sem a chave da aplicação, ninguém pode criar um cookie válido nem sequer ler o identificador;
  • linhas 64–67: para excluir um cookie, é preciso especificar o mesmo nome e o mesmo caminho: para o navegador, dois cookies com o mesmo nome, mas caminhos diferentes, são considerados dois cookies distintos.

11.12.7. Middleware: app/Http/Middleware

Três componentes de middleware, localizados na [app/Http/Middleware] pasta, como é costume.

<?php
// app/Http/Middleware/SetLanguage.php: o idioma da requisição (veja o exemplo 22):
// o do cookie [rdvmedecins_language] se for um idioma suportado, inglês caso contrário.
//
// Um middleware GLOBAL (veja bootstrap/app.php): ele é executado para TODAS as
// requisições, mesmo aquelas que não levam a nenhuma rota (página 405...). Ele é executado, portanto,
// ANTES do middleware EncryptCookies do grupo [web], que descriptografa os cookies:
// é por isso que o cookie de idioma é excluído da criptografia.

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;
use Symfony\Component\HttpFoundation\Response;

class SetLanguage
{
    // o cookie que memoriza o idioma escolhido (veja LanguageController)
    public const COOKIE = 'rdvmedecins_language';

    // os idiomas suportados (lang/fr.json, lang/en.json); por padrão, inglês
    // (config/app.php, chave 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);
    }
}

O idioma da requisição (exemplo 22): o idioma especificado no cookie, se for um idioma suportado; caso contrário, o idioma padrão da configuração (inglês). Os idiomas e o nome do cookie são constantes, pelo mesmo motivo do nome do cookie do token. Este middleware é global (veja [bootstrap/app.php]).

<?php
// app/Http/Middleware/RequireRoles.php: o papel do usuário deve ser um dos
// listados pela rota; caso contrário, resposta 403 (uma página de erro, veja
// bootstrap/app.php). Um middleware COM PARÂMETROS: em routes/web.php,
//   ->middleware('role:ADMIN,DOCTOR')
// chama handle($request, $next, 'ADMIN', 'DOCTOR'); ...$roles recebe todos eles.
//
// Ele é executado DEPOIS do middleware de autenticação (veja bootstrap/app.php):
// o usuário é, portanto, conhecido.

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);
    }
}

Um middleware com parâmetros. Em [routes/web.php], [->middleware('role:ADMIN,DOCTOR')] refere-se ao middleware com alias [role] (veja [bootstrap/app.php]), com dois parâmetros: [Laravel] chama [handle($request, $next, 'ADMIN', 'DOCTOR')]. O parâmetro variádico [string ...$roles] recebe todos os parâmetros restantes em um array (linha 20). Se algum papel estiver ausente da lista: resposta 403 ([abort(403)], exemplo 24). Isso equivale ao middleware [can:admin] do exemplo 26, sem definir um [Gate]: a aplicação tem apenas regras de papel. Este middleware é sempre colocado em rotas protegidas por [Authenticate], que é executado antes dele: [Authenticate] faz parte do grupo [web], cujos middlewares são executados antes dos da rota. O usuário, portanto, é conhecido.

<?php
// app/Http/Middleware/CheckRegistrationPass.php: GET e POST /register
// exigem um passe válido (veja app/Auth/RegistrationPass.php); caso contrário,
// volta para a página de login, com uma mensagem. Digitar a URL
// /register diretamente não contorna, portanto, o 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);
    }
}

Nenhum token válido: redirecionamento para a página de login com uma mensagem. O middleware recebe o serviço de token em seu construtor: [Laravel] cria o middleware usando o contêiner, que fornece suas dependências, assim como faz com os controllers.

11.12.8. app/Http/Controllers/AuthController.php

<?php
// =========================================================================
// app/Http/Controllers/AuthController.php: as rotas PÚBLICAS do login:
//   GET  /        redireciona para a página inicial do papel (ou para /login)
//   GET  /login   exibe o formulário de login (com seu captcha)
//   POST /login   verifica limite de tentativas, captcha, login / senha
//   POST /logout  o logout
//
// Proteção contra robôs, nesta ordem:
//   1. falhas recentes demais para este login a partir deste endereço IP?
//      -> recusa imediata, sem sequer olhar a senha;
//   2. resposta errada ao captcha? -> recusa (contada como falha);
//   3. só então, verificação da senha.
// NUNCA verificamos a senha de uma tentativa recusada nas etapas 1 ou 2:
// um robô, portanto, não pode aprender nada insistindo.
// =========================================================================

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,
    ) {
    }

    // a página inicial de cada papel, logo após o login
    public static function homePage(Role $role): string
    {
        return $role === Role::USER ? route('area') : route('schedule');
    }

    // -----------------------------------------------------------------------
    // GET /
    // A rota é pública: o usuário, se houver um, é conhecido (Auth::user()),
    // mas nada é exigido.
    // -----------------------------------------------------------------------
    public function home(): RedirectResponse
    {
        $user = Auth::user();
        return redirect($user ? self::homePage($user->role) : route('login'));
    }

    // -----------------------------------------------------------------------
    // GET /login[?login=xxx]: o parâmetro opcional preenche previamente o campo de login
    // (usado logo após a criação de uma conta, veja RegistrationController)
    // -----------------------------------------------------------------------
    public function showLogin(Request $request): View|RedirectResponse
    {
        // já logado (token ainda válido): direto para a página inicial
        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. falhas recentes demais?
        $minutes = $this->limiter->loginBlockMinutes($ip, $login);
        if ($minutes > 0) {
            return $this->page($login, new Message('ERRORS.TOO_MANY_ATTEMPTS', ['minutes' => $minutes]));
        }

        // 2. o 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. a senha
        $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: limpa o cookie do token e vai para a página de login.
    // Somente POST: um simples link (GET), colocado em outro site, não pode
    // deslogar o usuário sem que ele saiba.
    // -----------------------------------------------------------------------
    public function logOut(): RedirectResponse
    {
        return redirect()->route('login')->withCookie(AuthService::clearingCookie());
    }

    // o formulário, sempre com um NOVO captcha (cada imagem só é usada
    // uma vez); reexibimos o login digitado, nunca a senha
    private function page(string $login, ?Message $error): View
    {
        return view('login', ['pageTitle' => 'LOGIN.TITLE', 'error' => $error, 'login' => $login,
            'captcha' => $this->captchas->generate()]);
    }
}

O controller de conexão, baseado no exemplo 27.

  • Linhas 41–44: a página inicial de cada papel: “Minha área” para um paciente, o calendário para os demais. [route('area')] gera a URL da rota chamada [area] (exemplo 04);
  • linhas 51–55: o endereço [/] redireciona para a página inicial do papel ou para a página de login. A rota é pública: [Auth::user()] retorna o usuário, se houver um, sem exigir nenhuma entrada;
  • linhas 61–68: um usuário que já está logado vai direto para sua página inicial. O parâmetro opcional [login] da URL preenche previamente o campo (após a criação de uma conta); [Str::limit] trunca-o em 30 caracteres sem acrescentar nada (o terceiro parâmetro, [''], substitui as reticências usuais);
  • Linhas 73–100: o processo de login, na ordem mostrada no exemplo 27: bloqueio potencial, o CAPTCHA, a senha. Uma senha nunca é verificada para uma tentativa rejeitada pelo limitador ou pelo CAPTCHA: um bot não aprende nada ao insistir. Em caso de falha, a página é renderizada diretamente (sem redirecionamento): o formulário reexibido sempre tem um novo CAPTCHA e o login digitado. O erro é um objeto [Message] (veja abaixo), uma chave e seus parâmetros, exibido na parte inferior da página. Em caso de sucesso, o contador de logins é zerado e o navegador é redirecionado para a página inicial do papel, com o cookie do token ([withCookie]);
  • linhas 107–110: o logout exclui o cookie do token (exemplo 25).

A página de login recebe a variável [pageTitle], a chave de tradução do título da página: todas as ações a repassam à sua view para o template (veja abaixo).

11.13. A camada web: serviços compartilhados

A pasta [app/Web] contém os elementos compartilhados pelos controllers.

11.13.1. app/Web/ApplicationModel.php

<?php
// =========================================================================
// app/Web/ApplicationModel.php: o cache / fachada da camada de negócio (o equivalente
// da classe [ApplicationModel] das outras versões da aplicação): as
// listas de médicos e de clientes são lidas do banco de dados uma vez e depois servidas
// a partir do cache.
//
// Por que o CACHE do Laravel, e não simplesmente uma propriedade deste objeto? Porque
// uma aplicação PHP não guarda nada na memória de uma requisição para a seguinte: este
// objeto é um singleton (veja AppServiceProvider), mas um singleton só vive durante
// UMA requisição. O cache, por sua vez, é compartilhado por todas as requisições (veja
// os exemplos 20 e 23).
//
// Essas listas podem MUDAR (o ADMIN adiciona, modifica, exclui médicos e
// clientes): cada gravação passa, portanto, por esta fachada, que ESQUECE a lista
// em questão logo depois; a próxima requisição que precisar dela a lê novamente do banco de dados. É
// todo o sentido de um ÚNICO ponto de entrada para a camada de negócio: a regra
// "gravação => atualização do cache" é escrita somente aqui.
// =========================================================================

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;

// mesmo contrato da camada de negócio
class ApplicationModel implements Business
{
    private const DOCTORS = 'rdvmedecins.doctors';

    private const CLIENTS = 'rdvmedecins.clients';

    public function __construct(private BusinessService $business)
    {
    }

    // leituras a partir do cache

    // rememberForever: o valor do cache, se existir; caso contrário, a função é
    // chamada e seu resultado armazenado no cache (sem limite de tempo) antes de
    // ser retornado
    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());
    }

    // o médico cuja conta de usuário é [$userId] - usado para pré-selecionar,
    // para um médico logado, sua própria agenda. firstWhere: o primeiro elemento
    // da coleção cuja propriedade [user] é igual a $userId
    public function getDoctorByUserId(int $userId): ?Doctor
    {
        return $this->getAllDoctors()->firstWhere('user', $userId);
    }

    // delegações 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);
    }

    // sem cache aqui: o que importa são os dados mais recentes (um paciente que
    // acabou de modificar ou excluir sua conta)
    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);
    }

    // gravações => cache esquecido

    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 as versões da aplicação têm uma classe chamada [ApplicationModel]: um ponto de entrada único da camada web para a camada de negócio, que mantém em memória as listas de médicos e clientes. Essas listas são acessadas por quase todas as páginas (a lista suspensa de médicos no calendário, a lista de pacientes na janela de agendamento e as páginas de administração) e raramente mudam.

O que muda em [PHP] é o significado de “em memória”. Uma aplicação como [Java], [C#] ou [Python] permanece em memória entre as requisições; a versão [Flask] armazenava essas listas nas propriedades de um único objeto criado na inicialização. Uma aplicação [PHP] é recriada a cada requisição (exemplo 01): o objeto [ApplicationModel] é de fato um singleton, mas existe apenas durante uma única requisição. As listas são, portanto, armazenadas no cache do [Laravel] (exemplo 20), que é compartilhado por todas as requisições.

  • Linhas 51–54: [Cache::rememberForever(key, function)] retorna o valor armazenado sob essa chave; se ele não existir, chama a função (que lê a lista do banco de dados), armazena o resultado no cache indefinidamente e o retorna. A primeira requisição que precisa da lista a lê do banco de dados; as seguintes a encontram no cache. O cache armazena a coleção de objetos [Eloquent] em forma serializada (exemplo 20) e a reconstrói na leitura, junto com os relacionamentos carregados (a conta de cada pessoa);
  • linhas 64–67: o médico associado a uma conta, obtido da lista do cache: [firstWhere('user', $userId)] retorna o primeiro elemento da coleção cuja propriedade [user] é igual a [$userId];
  • linhas 71–123: os demais métodos do contrato [Business] simplesmente delegam à camada de negócio. O cliente de uma conta ([getClientByUserId]) é sempre obtido do banco de dados, não do cache: o que importa são os dados mais recentes (um paciente que acabou de modificar ou excluir sua conta);
  • Linhas 130–133 e seguintes: as atualizações. Cada operação de escrita de um médico ou cliente limpa a lista correspondente ([Cache::forget]): a próxima requisição que precisar dela a lerá novamente do banco de dados. [tap(value, function)] chama a função e depois retorna o valor: neste caso, o médico recém-criado, após a limpeza do cache. Esse é todo o objetivo de um ponto de entrada único: a regra “uma operação de escrita atualiza o cache” é definida apenas aqui. Uma aplicação que escreve no banco de dados por outro caminho (outro programa, outra versão da aplicação usando o mesmo banco) deixaria o cache desatualizado: [php artisan cache:clear] o limparia.

11.13.2. app/Web/Message.php e Flash.php

<?php
// app/Web/Message.php: uma mensagem a traduzir: sua chave e seus parâmetros.
// As views a exibem com {{ __($message->key, $message->params) }}.

namespace App\Web;

readonly class Message
{
    public function __construct(
        public string $key,
        public array $params = [],
    ) {
    }
}

Uma mensagem a ser traduzida: uma chave e seus parâmetros. Os erros da camada de negócio ([BusinessException]) e os dos controllers tornam-se [Message], que as views traduzem para o idioma da página.

<?php
// =========================================================================
// app/Web/Flash.php: as mensagens "flash": uma mensagem a exibir UMA ÚNICA VEZ, na
// PRÓXIMA página (veja o exemplo 20). É o complemento natural do padrão
// "Post / Redirect / Get" usado por todos os formulários da aplicação: um
// POST bem-sucedido não constrói uma página, ele redireciona (302) para uma página GET; a
// mensagem, por sua vez, deve sobreviver ao redirecionamento.
//
// O Laravel as armazena na SESSÃO, aqui em um cookie CRIPTOGRAFADO (driver [cookie],
// veja .env): o servidor não guarda nada entre duas requisições.
//
// Uma mensagem não contém um texto, mas uma CHAVE de tradução e seus parâmetros:
// ela é traduzida no momento da exibição, no idioma da página (veja
// resources/views/fragments). Duas listas: os sucessos (exibidos no topo da
// página) e os erros (exibidos no rodapé).
// =========================================================================

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): um valor legível somente durante a PRÓXIMA
    // requisição; nós o completamos se a requisição atual já tiver colocado um
    private static function add(string $list, string $key, array $params): void
    {
        $messages = session($list, []);
        $messages[] = new Message($key, $params);
        session()->flash($list, $messages);
    }
}

Mensagens flash (exemplo 20): uma mensagem armazenada na sessão por uma ação, exibida pela próxima página e depois descartada. Isso complementa o padrão Post/Redirect/Get, seguido por todos os formulários da aplicação. Duas listas, armazenadas na sessão sob as chaves [flash_success] e [flash_errors]: as mensagens de sucesso são exibidas na parte superior da página e as de erro, na parte inferior.

  • Linhas 34–39: uma ação pode armazenar várias mensagens: acrescentamos à lista já armazenada pela requisição atual ([session($list, [])] a lê, com uma lista vazia por padrão) e depois a armazenamos novamente. [session()->flash(key, value)] armazena um valor que persistirá apenas até o fim da próxima requisição (exemplo 20).

[Message] Os objetos são armazenados como estão na sessão: [Laravel] serializa os dados da sessão (exemplo 20) e os reconstrói durante a próxima requisição. Com o driver [cookie] (arquivo [.env]), eles são transmitidos em um cookie criptografado.

11.13.3. app/Web/Utils.php

<?php
// =========================================================================
// app/Web/Utils.php: pequenas funções utilitárias da camada web:
//   - datas: "yyyy-mm-dd", dias "Wednesday 23 September 2026";
//   - entrada: leitura de um inteiro positivo, de uma data, enviados pelo navegador;
//   - usuário: o usuário logado e seu paciente (entidade Client).
// Métodos STATIC: eles são chamados sem criar um 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
{
    // datas

    // a data, se [$text] é uma data que existe no formato yyyy-mm-dd; null caso contrário.
    // createFromFormat aceita "2026-02-30" (que vira 2 de março): verificamos, portanto,
    // que a data lida de volta é escrita exatamente como o texto recebido
    public static function validDate(?string $text): ?CarbonImmutable
    {
        if ($text === null || ! preg_match('/^\d{4}-\d{2}-\d{2}$/', $text)) {
            return null;
        }
        // "!Y-m-d": o ponto de exclamação zera a hora para a meia-noite
        $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", conforme o idioma
    // da requisição. isoFormat: dddd o dia da semana por extenso, D o
    // dia, MMMM o mês por extenso, YYYY o ano (veja o exemplo 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;
    }

    // usuário

    // o usuário logado. As ações protegidas só são chamadas se ele existir;
    // por precaução, sua ausência é tratada como uma sessão expirada
    public static function user(): ConnectedUser
    {
        return Auth::user() ?? throw new InvalidSession();
    }

    // -----------------------------------------------------------------------
    // O paciente (entidade Client) que corresponde ao usuário logado.
    //
    // O token JWT contém apenas o id da CONTA (users.id). Para um papel USER,
    // encontramos o cliente correspondente graças à coluna clients.user.
    //
    // Se não houver nenhum, a conta foi excluída desde o login
    // enquanto seu token ainda é válido: tratamos como uma sessão
    // expirada (veja InvalidSession).
    // -----------------------------------------------------------------------
    public static function connectedPatient(ApplicationModel $application): Client
    {
        return $application->getClientByUserId(self::user()->userId)
            ?? throw new InvalidSession();
    }
}

Algumas funções utilitárias, na forma de métodos estáticos.

  • Linhas 26–34: a data de um parâmetro [yyyy-mm-dd] ou [null]. Duas verificações: o formato (uma expressão regular) e depois a existência da data. [createFromFormat] é tolerante: 30 de fevereiro se torna 2 de março. Por isso relemos a data resultante e verificamos se ela é escrita exatamente como o texto recebido. O [!] no formato define a hora como meia-noite (sem ele, a hora seria a atual);
  • Linhas 44–47: “samedi 26 septembre 2026” ou “Saturday 26 September 2026”, dependendo do idioma da requisição. [isoFormat] (exemplo 16) usa os códigos de formato da biblioteca [JavaScript] [Moment.js] : [dddd], o dia da semana por extenso; [D], o dia; [MMMM], o mês por extenso; [YYYY], o ano. [locale(...)] retorna uma cópia da data configurada para um idioma específico;
  • linhas 52–59: um parâmetro de consulta é uma string, ou [null], ou até um array ([?doctorId[]=1], exemplo 10). Somente dígitos são aceitos (até nove: sem estouro), e o número deve ser estritamente positivo. [mixed]: qualquer tipo;
  • linhas 65–68: o usuário logado. [Auth::user()] retorna [null] para um visitante anônimo; as ações protegidas só são chamadas para um usuário autenticado, mas a ausência de usuário ainda é tratada como uma sessão expirada;
  • linhas 80–84: o paciente ([Client]) do usuário logado. O token contém apenas o ID da conta; o cliente é identificado pela coluna [clients.user]. Se ele não existir, a conta foi excluída desde que o usuário fez login: [InvalidSession].

11.14. Os dicionários

Os textos da interface são os mesmos das outras versões da aplicação, que os armazenavam em arquivos JSON aninhados:

1
2
3
4
5
6
{
  "LOGIN": {
    "TITLE": "Login",
    ...
  }
}

A versão [Flask] os “achatava” na inicialização: [LOGIN.TITLE] referia-se ao texto em [Login]. [Laravel] lê dicionários JSON planos (exemplo 22), em que a chave é o texto a ser traduzido ou um identificador: achatamos os dicionários de uma vez por todas e substituímos os parâmetros [{name}] das outras versões pela notação usada no [Laravel] e [:name]:

1
2
3
4
5
6
7
{
    "APP.TITLE": "RdvMedecins",
    "APP.LOGOUT": "Log out",
    ...
    "DOCTORS.ADDED": "Doctor :name has been added (login: :login).",
    ...
}

Os arquivos [lang/fr.json] e [lang/en.json] contêm 153 textos cada; eles não são reproduzidos aqui. Uma chave é representada por [__('APP.LOGOUT')], e um texto parametrizado por [__('DOCTORS.ADDED', ['name' => ..., 'login' => ...])]. [Laravel] procura primeiro a chave completa no dicionário JSON do idioma; se não a encontrar, procura nos arquivos [PHP] da pasta [lang/en] (exemplo 09); se isso falhar, exibe a própria chave, o que sinaliza imediatamente uma omissão. Uma entrada de texto foi adicionada: [ERRORS.PAGE_EXPIRED], a mensagem da página 419, que não existe nas outras versões.

11.15. Formulários

Os formulários de “pessoa” são validados por form requests ([FormRequest], exemplo 19): classes que descrevem as regras de validação de uma requisição. Vamos relembrar o princípio: uma ação que recebe um [FormRequest] como parâmetro só é chamada se a entrada for válida; caso contrário, o [Laravel] redireciona o navegador de volta à página do formulário, junto com as mensagens de erro ([$errors] na view) e a entrada a ser reexibida ([old('field')]), exceto as senhas.

11.15.1. app/Http/Requests/PersonFieldsRequest.php

<?php
// =========================================================================
// app/Http/Requests/PersonFieldsRequest.php: os campos dos formulários de "pessoa"
// e suas regras de validação (veja o exemplo 19). Três formulários
// compartilham os mesmos campos de identidade (título, nome, sobrenome):
//
//   PersonFieldsRequest            título, nome, sobrenome
//    ├─ PersonRequest              + login / senha OPCIONAIS, version
//    │                               (o ADMIN adiciona ou modifica um médico / cliente)
//    ├─ RegistrationRequest        + login / senha / confirmação OBRIGATÓRIOS
//    │                               (um paciente cria sua conta)
//    └─ MyAccountRequest           + login, nova senha opcional, senha
//                                    ATUAL OBRIGATÓRIA, version
//                                    (um paciente modifica sua conta)
//
// Uma classe ABSTRATA: ela nunca é usada sozinha; suas filhas completam
// suas regras (array_merge) e suas mensagens.
//
// Lembretes (exemplo 19): uma ação que recebe um FormRequest como parâmetro só
// é chamada se a entrada for válida; caso contrário, o Laravel redireciona o navegador de volta para
// a página do formulário, com as mensagens de erro ($errors na
// view) e a entrada a reexibir (old('field')) - NUNCA as senhas.
// As mensagens são os textos dos dicionários 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, ponto, hífen, sublinhado - no máximo 30 caracteres
    public const LOGIN_FORMAT = '/^[a-z0-9._-]{1,30}$/';

    // comprimento mínimo de uma senha ESCOLHIDA por um paciente
    public const PASSWORD_MIN = 6;

    // antes da validação: um login está sempre em minúsculas. Os espaços
    // supérfluos já foram removidos de todos os campos pelo middleware TrimStrings
    // do Laravel - exceto das senhas (password,
    // password_confirmation, current_password), das quais eles podem fazer parte; um
    // campo vazio virou null (middleware ConvertEmptyStringsToNull)
    protected function prepareForValidation(): void
    {
        if (is_string($this->input('login'))) {
            $this->merge(['login' => Str::lower($this->input('login'))]);
        }
    }

    // bail: a validação de um campo para na primeira regra violada -
    // uma única mensagem por campo. Comprimentos máximos = os das colunas 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'],
        ];
    }

    // field.rule -> mensagem
    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'),
        ];
    }

    // a versão (bloqueio otimista), se o formulário tiver uma
    public function version(): ?int
    {
        return $this->filled('version') ? (int) $this->input('version') : null;
    }
}

Três formulários compartilham os mesmos campos de identidade (título, nome, sobrenome): o formulário do administrador (para um médico ou um cliente), o formulário de criação de conta de paciente e “Gerenciar minha conta”. Sua classe-mãe comum é abstrata; cada uma de suas classes-filhas estende suas regras.

  • linhas 34–40: as regras de entrada, na forma de constantes, que também são lidas pelas views (a lista de títulos);
  • Linhas 47–52: [prepareForValidation] é chamado antes da validação: a entrada pode ser transformada ali. Um login é sempre em minúsculas: [merge] substitui o valor do campo na requisição. As outras normalizações já são feitas por dois componentes de middleware globais do [Laravel] (veja o capítulo sobre o ciclo de vida): [TrimStrings] remove espaços no início e no fim de todos os valores, exceto os dos campos [password], [password_confirmation] e [current_password] (espaços podem fazer parte de uma senha); [ConvertEmptyStringsToNull] substitui uma string vazia por [null]. É por isso que os campos de senha da aplicação têm esses nomes, que correspondem ao uso do [Laravel];
  • Linhas 56–63: as regras dos três campos. [bail] interrompe a validação de um campo assim que a primeira regra é violada: apenas uma mensagem por campo. [Rule::in(...)]: o valor deve ser um dos da lista. [max:20]: máximo de 20 caracteres; o tamanho da coluna é definido pelo SQL;
  • linhas 66–84: mensagens de erro, obtidas dos dicionários. A chave ['first_name.required'] refere-se à mensagem da regra [required] no campo [first_name]; a chave ['first_name'] sozinha refere-se à mensagem de todas as outras regras desse campo. A mensagem de uma regra é procurada primeiro sob a chave [field.rule], depois sob a chave [rule] (a mensagem dessa regra para todos os campos) e, por fim, sob a chave [field]. As regras das classes-filhas (login, senhas) têm suas mensagens aqui: uma mensagem não utilizada não causa problemas. O método [messages] é chamado durante a validação, no idioma da requisição;
  • linhas 87–90: a versão (o campo oculto do bloqueio otimista), como inteiro, ou [null] se o campo estiver vazio ou ausente. [filled]: o campo está presente e não vazio.

11.15.2. app/Http/Requests/PersonRequest.php, RegistrationRequest.php, MyAccountRequest.php

<?php
// app/Http/Requests/PersonRequest.php: o formulário de um médico ou de um cliente
// (ADMIN): login e senha OPCIONAIS (veja app/Business/PersonData.php).

namespace App\Http\Requests;

use App\Business\PersonData;

class PersonRequest extends PersonFieldsRequest
{
    // nullable: um campo vazio (null) é aceito, sem verificar as outras regras
    public function rules(): array
    {
        return array_merge(parent::rules(), [
            'login' => ['bail', 'nullable', 'string', 'regex:'.self::LOGIN_FORMAT],
            // 72 caracteres no máximo: além disso, o bcrypt ignora o restante
            'password' => ['bail', 'nullable', 'string', 'max:72'],
            // campo oculto do formulário de modificação (bloqueio otimista)
            'version' => ['nullable', 'integer'],
        ]);
    }

    // a entrada validada -> os dados esperados pela camada de negócio
    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());
    }
}

O formulário do administrador. [array_merge] acrescenta três regras às da classe-mãe: o nome de usuário e a senha são opcionais ([nullable]: o valor [null] é aceito, e as demais regras então não são verificadas); [regex:...] valida o formato do nome de usuário; [max:72] limita o tamanho de uma senha: [bcrypt] considera apenas os primeiros 72 bytes (exemplo 25). O método [personData] (linhas 24–28) converte a entrada validada em [PersonData] para a camada de negócio: a camada de negócio não conhece requisições HTTP.

<?php
// app/Http/Requests/RegistrationRequest.php: "Create a client account": login, senha
// e confirmação OBRIGATÓRIOS.

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: a confirmação deve ser idêntica à senha
            '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'));
    }
}

Criação de uma conta de paciente: login e senha são obrigatórios, e a senha deve ser confirmada. A regra [same:password] exige que o campo [password_confirmation] tenha o mesmo valor que o campo [password]; sua mensagem (“A confirmação não corresponde à senha.”) aparece abaixo do campo de confirmação. [Laravel] também tem uma regra, [confirmed], que verifica a mesma coisa, mas a partir do campo [password]; sua mensagem apareceria abaixo do campo de senha.

<?php
// app/Http/Requests/MyAccountRequest.php: "Manage my account" (um paciente): login
// obrigatório, nova senha opcional, senha ATUAL obrigatória.

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: vazio = senha inalterada
            'password' => ['bail', 'nullable', 'string', 'min:'.self::PASSWORD_MIN, 'max:72'],
            'password_confirmation' => ['same:password'],
            // a senha ATUAL, obrigatória para qualquer modificação da conta
            '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());
    }
}

“Gerenciar minha conta”: a nova senha é opcional (deixe em branco para manter a senha atual), e a senha atual é obrigatória. A regra [same:password] aplica-se mesmo a um campo de confirmação vazio: se uma nova senha for digitada, a confirmação também deve ser digitada. A senha atual não é verificada aqui, mas pela ação: uma senha incorreta deve ser contada pelo limitador de tentativas como um login malsucedido. [Laravel] tem uma regra, [current_password], que compara a senha digitada com a do usuário logado; essa regra não é adequada aqui: nosso usuário logado ([ConnectedUser]) não contém o hash de sua senha.

11.16. Templates de view

A pasta [app/Views] contém os templates de view: objetos criados por uma ação, que a view simplesmente lê. A regra seguida por todas as páginas é: nenhuma lógica nas views. As ações preparam dados já formatados (“Sra. Marie PELISSIER”, “8:00 – 8:20”) e já filtrados de acordo com o papel do usuário; as views apenas os colocam no HTML. Todas essas classes são [readonly] e têm apenas propriedades, promovidas pelo seu construtor.

<?php
// app/Views/OptionView.php: uma opção de uma lista suspensa (médico, paciente).
//
// A pasta app/Views contém os "view models": objetos
// construídos de uma só vez por uma ação, que a view apenas lê. Regra
// seguida por todas as páginas: nenhuma lógica nas views. As ações
// preparam dados JÁ formatados ("Mme Marie PELISSIER",
// "8:00 - 8:20", selected = true...) e já filtrados conforme o papel
// do usuário; as views apenas os colocam no HTML.

namespace App\Views;

readonly class OptionView
{
    public function __construct(
        public int $id,
        public string $label,
        public bool $selected,
    ) {
    }
}

Uma opção em uma lista suspensa: o ID, o rótulo e se a opção está selecionada.

<?php
// app/Views/ScheduleRow.php: uma linha da agenda exibida (um horário).

namespace App\Views;

readonly class ScheduleRow
{
    public function __construct(
        public int $slotId,
        public string $time,         // "8:00 - 8:20"
        public bool $free,
        // nome exibido para um horário ocupado; null = "Booked"
        public ?string $patient,
        public bool $mine,           // a consulta do paciente logado
        public bool $bookable,       // exibir o botão "Book"?
        public string $bookUrl,
        // definido somente se o botão "Cancel" for exibido
        public ?int $appointmentId,
    ) {
    }
}

Uma entrada no calendário: um intervalo de tempo e o que o usuário logado está autorizado a ver e fazer com ele. [patient] só é preenchido se o usuário tiver permissão para ver o nome do paciente; [bookable] indica se o botão “Agendar” deve ser exibido; [appointmentId] indica se o botão “Cancelar” deve ser exibido.

<?php
// app/Views/ScheduleView.php: a agenda exibida: o médico, o dia, as linhas.

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: a janela de agendamento de um horário.

namespace App\Views;

readonly class BookingView
{
    /** @param list<OptionView> $clients */
    public function __construct(
        public int $slotId,
        public string $time,
        // ADMIN / DOCTOR: os pacientes a escolher
        public array $clients,
        // USER: o paciente é ele mesmo
        public ?string $patient,
    ) {
    }
}

O calendário exibido e a janela de agendamento: para o administrador e os médicos, a lista de pacientes para escolha; para um paciente, o próprio nome.

<?php
// app/Views/PersonKeys.php: as chaves de tradução específicas de cada tipo de
// pessoa (médicos ou clientes), para as views comuns persons/list e
// 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,
    ) {
    }

    // as oito chaves de uma seção do dicionário ("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");
    }
}

As chaves de tradução específicas de médicos ou clientes, para as duas views que eles têm em comum. O método estático [of] (linhas 23–27) gera as oito chaves de uma seção dos dicionários: [PersonKeys::of('DOCTORS')] produz [DOCTORS.TITLE], [DOCTORS.ADD]... [new self(...)] cria um objeto da própria classe.

<?php
// app/Views/AppointmentView.php: uma consulta futura, na área do 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,  // a agenda do médico nesse dia
    ) {
    }
}

Uma consulta futura na área do paciente.

11.17. A camada web: rotas e controllers

11.17.1. routes/web.php

<?php
// =========================================================================
// routes/web.php: todas as URLs da aplicação.
//
// Lembrete (veja bootstrap/app.php): todas estas rotas exigem um usuário
// autenticado, EXCETO as do primeiro grupo, que removem o middleware
// de autenticação (withoutMiddleware). O middleware [role:...] também exige
// um dos papéis listados; ele se aplica a uma rota ou a todas as rotas de um
// grupo.
//
// ->name(...): o NOME da rota, com o qual o código constrói suas URLs
// (route('schedule', [...]), redirect()->route('login')...): mudar uma URL
// exige então apenas modificar este arquivo.
// =========================================================================

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;

// as rotas PÚBLICAS
Route::withoutMiddleware(Authenticate::class)->group(function () {
    // o login (veja 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');
    });

    // a escolha do idioma: /language/fr, /language/en; qualquer outro valor: 404
    Route::get('language/{code}', [LanguageController::class, 'change'])
        ->whereIn('code', SetLanguage::LANGUAGES)->name('language');

    // a criação de uma conta de cliente (veja RegistrationController); o formulário
    // exige um passe (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');
        });
    });

    // nenhuma outra rota corresponde à URL solicitada: página 404. Uma rota "fallback"
    // em vez do 404 automático do Laravel: assim a requisição
    // passa pelos middlewares do grupo [web] (sessão, usuário...) e a
    // página de erro tem sua barra de navegação completa
    Route::fallback(fn () => abort(404));
});

// a agenda (todos os papéis)
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');
    // um paciente cancela SUA consulta a partir de "My area", não daqui
    Route::post('cancel', 'cancel')->middleware('role:ADMIN,DOCTOR')->name('schedule.cancel');
});

// médicos e clientes (ADMIN)
// As duas seções têm as MESMAS rotas (veja PersonsController): um laço
// as declara para cada uma. Os nomes das rotas são prefixados pela seção:
// 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} deve ser composto de 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');
        });
}

// a área do 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 as rotas de URL da aplicação. Observe que todas essas rotas exigem um usuário autenticado (o middleware [Authenticate], adicionado ao grupo [web] por [bootstrap/app.php]), exceto aquelas que removem essa exigência.

  • Linhas 28–56: as rotas públicas. [withoutMiddleware] remove um middleware das rotas do grupo: neste caso, a autenticação. Entre elas estão o login ([AuthController]), a seleção de idioma e a criação de conta de paciente;
  • Linhas 30–35: [Route::controller] (exemplo 02) especifica o controller das rotas do grupo: cada rota passa a nomear apenas seu método. [->name('login')] atribui um nome à rota (exemplo 04): o código gera sua URL usando esse nome ([route('login')], [redirect()->route('login')]), e alterar uma URL exige modificar apenas esse arquivo. O nome [login] também tem significado para o [Laravel]: é a página para a qual o middleware [Authenticate] redireciona um visitante anônimo se nenhuma outra página for especificada;
  • linhas 38–39: [whereIn('code', [...])] aceita apenas os valores da lista para o parâmetro [{code}]: [/language/de] não corresponde a nenhuma rota (página 404);
  • linhas 43–49: criação de conta. [prefix('register')] adiciona [/register] antes das URLs do grupo: [Route::get('', ...)] é a própria rota [/register]. O formulário (GET e POST) também exige um passe: o middleware com alias [registration.pass];
  • linha 55: a rota fallback, selecionada quando nenhuma outra rota corresponde a uma requisição GET. Sem ela, o [Laravel] ele próprio gera um erro 404 antes de os middlewares do grupo [web] serem executados: sem sessão, sem cookies descriptografados... A página de erro não teria nem o nome do usuário em sua barra de navegação nem um token anti-CSRF para o botão de logout. Com a rota fallback, a requisição passa pelo grupo [web] e, em seguida, a ação gera um erro 404. A rota é pública: um endereço desconhecido retorna uma página 404, mesmo para um visitante anônimo. Efeito colateral: uma requisição GET a uma URL que existe apenas como POST ([/logout]) também retorna uma página 404, e não um 405;
  • linhas 59–64: o calendário. Sua página é acessível a todos os usuários autenticados; o agendamento está disponível para os três papéis (ou seja, qualquer usuário autenticado; a lista de papéis documenta essa regra); o cancelamento está disponível para o administrador e os médicos: [->middleware('role:ADMIN,DOCTOR')];
  • linhas 70–81: as rotas de médicos e clientes são as mesmas: um laço as declara para cada uma das duas seções. O arquivo de rotas é um arquivo [PHP] comum: nele é possível escrever laços, condições e funções. Para cada seção, há um grupo: o controller, o prefixo da URL ([/doctors]), o prefixo do nome ([->name("$section.")]: a rota chamada [list] passa a se chamar [doctors.list]) e o middleware [role:ADMIN], que protege todas as rotas do grupo, inclusive as adicionadas posteriormente. [whereNumber('id')] aceita apenas números para o parâmetro [{id}] (por exemplo, 02);
  • linhas 84–90: a área do paciente, reservada ao papel USER.

Os códigos de URL correspondem aos de outras versões da aplicação: modificar e excluir um médico são requisições POST ([/doctors/{id}/edit], [/doctors/{id}/delete]), e não PUT e DELETE como no exemplo 28. O comando [php artisan route:list] exibe a lista de rotas, junto com seus nomes e ações.

11.17.2. app/Http/Controllers/LanguageController.php

<?php
// =========================================================================
// app/Http/Controllers/LanguageController.php: GET /language/fr, GET /language/en: os
// dois botões FR / EN da barra de navegação. Rota pública: é preciso poder
// mudar o idioma antes de fazer login.
//
// A escolha é memorizada em um cookie: a cada requisição seguinte, o middleware
// SetLanguage o lê novamente e define o idioma da requisição. Depois voltamos para a página
// de onde viemos (veja o exemplo 22).
// =========================================================================

namespace App\Http\Controllers;

use App\Http\Middleware\SetLanguage;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class LanguageController
{
    // {code} é limitado aos idiomas suportados pela rota (whereIn): /language/de resulta em uma página 404
    public function change(Request $request, string $code): RedirectResponse
    {
        // um ano: 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'));
    }

    // -----------------------------------------------------------------------
    // a página anterior, conforme o cabeçalho HTTP "Referer" enviado pelo navegador.
    // Mantemos apenas seu path (/schedule?...): redirecionar para um endereço
    // completo fornecido pela requisição permitiria enviar o usuário para
    // outro site (a chamada falha 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/..." seria entendido pelo navegador como um endereço em
        // OUTRO site: também recusado
        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;
    }
}

Os botões FR / EN da barra de navegação: a escolha do idioma é armazenada em um cookie por um ano (exemplo 22), após o que o navegador retorna à página de onde veio. O cookie não é criptografado (veja [bootstrap/app.php]); ele é [httpOnly]: o [JavaScript] da página não precisa lê-lo.

  • Linhas 35–47: a página anterior é indicada pelo cabeçalho HTTP [Referer] que o navegador envia com a requisição. Trata-se de um dado fornecido pelo cliente e, portanto, suspeito: redirecionar para uma URL completa vinda da requisição permitiria a um atacante enviar o usuário ao seu próprio site por meio de um link para [/language/fr] com um [Referer] falso (a chamada vulnerabilidade de *open redirect*). Por isso, mantemos apenas o caminho e os parâmetros ([/schedule?doctorId=1&...]), extraídos pela função [parse_url] do [PHP], que divide uma URL em suas partes ([scheme], [host], [path], [query]...). Um caminho que começa com [//] também é rejeitado: um navegador interpreta [//site.com/page] como um endereço em outro site. Por fim, não podemos retornar a [/language/...]: seria um laço.

11.17.3. app/Http/Controllers/ScheduleController.php

<?php
// =========================================================================
// app/Http/Controllers/ScheduleController.php: a página da agenda: escolha de um
// médico e de um dia, agenda desse médico nesse dia, agendamento e cancelamento
// de consultas.
//
//   GET  /schedule?doctorId=1&day=2026-09-23               a página
//   GET  /schedule?doctorId=1&day=2026-09-23&book=7        a mesma página, com a
//                                                          janela de agendamento
//                                                          do horário 7 aberta
//   POST /schedule/book                                    cria uma consulta
//   POST /schedule/cancel                                  cancela uma consulta
//
// A página inteira é descrita por sua URL: ela pode ser recarregada,
// salva nos favoritos, o botão "Voltar" do navegador pode ser usado - sem uma única linha de
// JavaScript.
//
// O que cada um vê e pode fazer:
//
//   | papel         | horário ocupado exibido           | Book               | Cancel  |
//   |===============|===================================|====================|=========|
//   | ADMIN, DOCTOR | nome do paciente                  | para um paciente   | sim     |
//   |               |                                   | escolhido em uma   |         |
//   | USER (paciente)| "Booked", ou SEU nome se for     | para si mesmo, se  | não (*) |
//   |               | sua própria consulta              | não tiver consulta |         |
//   |               |                                   | futura             |         |
//
//   (*) o paciente cancela sua consulta a partir de sua página "My area".
//
// CONFIDENCIALIDADE: para um paciente, o nome dos OUTROS pacientes não é
// simplesmente ocultado pela view - ele nunca é passado para a view. O HTML enviado
// ao navegador, portanto, não o contém, nem mesmo oculto (um simples "Exibir código-fonte da página"
// o revelaria de outra forma).
//
// Nenhum agendamento no passado: o botão "Book" só aparece para
// hoje e os dias seguintes (e a camada de negócio o recusaria
// de qualquer maneira).
//
// Segurança: todas as URLs /schedule exigem um usuário autenticado (regra
// geral, veja bootstrap/app.php); o middleware [role] das rotas POST também
// exige um dos papéis listados (veja 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
    // Os parâmetros da URL são lidos brutos ($request->query), para distinguir um
    // parâmetro AUSENTE (null) de um parâmetro VAZIO (?doctorId=).
    // -----------------------------------------------------------------------
    public function show(Request $request): View
    {
        $error = null;
        $user = Utils::user();
        $rights = $this->rights();

        // o dia: o da URL se for válido, caso contrário hoje
        $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());

        // o médico: o da URL; na falta dele, para um médico logado, ele mesmo
        $rawDoctorId = $request->query('doctorId');
        $doctorId = Utils::positiveInteger($rawDoctorId);
        if ($rawDoctorId === null && $user->role === Role::DOCTOR) {
            $doctorId = $this->application->getDoctorByUserId($user->userId)?->id;
        }

        // a lista suspensa de médicos
        $doctors = $this->application->getAllDoctors()
            ->map(fn (Person $m) => self::option($m, $m->id === $doctorId))->all();

        // a agenda, se um médico foi escolhido (e a data é 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);
            }
        }

        // a janela de agendamento: somente se o horário solicitado puder ser agendado
        // por este usuário. array_find: o primeiro elemento que satisfaz a
        // condição (null se não houver nenhum)
        $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,
            // a agenda exibida, sem janela de agendamento
            'backUrl' => $doctorId !== null ? self::scheduleUrl($doctorId, $day) : route('schedule'),
            'info' => $this->patientInfo($rights, $schedule),
        ]);
    }

    // -----------------------------------------------------------------------
    // POST /schedule/book   campos: doctorId, day, slotId, clientId
    //
    // Para um paciente (USER), o campo clientId é IGNORADO: ele sempre agenda
    // para si mesmo. Confiar em um campo enviado pelo navegador
    // permitiria a um paciente astuto agendar em nome de outro.
    //
    // Padrão "Post / Redirect / Get": qualquer que seja o resultado, nenhuma página é construída
    // aqui - colocamos uma mensagem flash e redirecionamos para a agenda
    // (veja o exemplo 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" (veja bootstrap/app.php)
        }
        $user = Utils::user();

        if ($user->isPatient()) {
            $client = Utils::connectedPatient($this->application);
        } else {
            $clientId = Utils::positiveInteger($request->input('clientId'));
            if ($clientId === null) {
                // nenhum paciente escolhido: reabrimos a janela de agendamento
                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 {
                // as regras (não no passado, apenas uma consulta futura por
                // paciente, horário livre) são verificadas pela camada de negócio
                $this->application->addAppointment($day, $slot, $client);
                Flash::success('SCHEDULE.BOOKED');
            } catch (BusinessException $e) {
                // mesma regra, mas uma mensagem na 2ª pessoa quando é o próprio
                // paciente que agenda ("You already have..." em vez de
                // "This patient..."). As outras exceções (anomalias reais) não
                // são capturadas: 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
    // (um paciente cancela SUA consulta a partir de "My area", não daqui)
    // -----------------------------------------------------------------------
    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) {
            // já cancelada (por outra pessoa, ou clique duplo)
            Flash::error('ERRORS.APPOINTMENT_NOT_FOUND');
        } else {
            $this->application->deleteAppointment($appointment);
            Flash::success('SCHEDULE.CANCELLED');
        }
        return redirect(self::scheduleUrl($doctorId, $day));
    }

    // -----------------------------------------------------------------------
    // quem está logado e o que pode fazer nesta página?
    //   manager: ADMIN ou DOCTOR;
    //   patient: o cliente logado (papel USER), caso contrário null;
    //   patientCanBook: um USER sem consulta futura.
    // -----------------------------------------------------------------------
    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()];
    }

    // -----------------------------------------------------------------------
    // a agenda do médico, formatada para a view - e filtrada conforme os direitos
    // -----------------------------------------------------------------------
    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;
            // a consulta do paciente logado?
            $mine = $appointment !== null && $rights['patient'] !== null && $appointment->client_id === $rights['patient']->id;
            $rows[] = new ScheduleRow(
                slotId: $slot->id,
                time: $slot->time(),
                free: $free,
                // O ponto de confidencialidade: um paciente só recebe o nome de
                // SUA consulta; para as outras, null (a view exibe "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);
    }

    // funções utilitárias

    // os campos ocultos doctorId / day dos formulários POST; [null, null] se
    // forem invá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() acrescenta ao final da
    // URL os parâmetros que não são parâmetros de path
    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);
    }

    // -----------------------------------------------------------------------
    // a mensagem informativa de um paciente que já tem uma consulta futura
    // (por que não há botão "Book"), ou null. Inútil se SUA
    // consulta aparece na agenda exibida (em azul): é o caso logo
    // depois de ele a ter acabado de agendar, quando a mensagem estaria fora 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';
    }
}

A página principal da aplicação. O comentário de cabeçalho resume o que cada usuário vê e pode fazer.

11.17.3.1. Os elementos da URL na página

A página inteira é descrita por sua URL: [/schedule?doctorId=1&day=2026-09-26] exibe a agenda do médico 1 nesse dia; [&book=4] abre também a janela para agendar o intervalo 4. É possível recarregar a página, adicioná-la aos favoritos ou usar o botão Voltar do navegador sem uma única linha de [JavaScript]. O formulário no topo da página (para selecionar o médico e o dia) é um formulário GET (exemplo 17): ele recarrega a página com novos parâmetros. A janela de agendamento de consulta é aberta por um simples link e fechada por um link para a mesma página sem o parâmetro [book].

11.17.3.2. GET /schedule

Linhas 76–148:

  • os parâmetros da URL são lidos como estão ([$request->query('day')]), sem validação pelo [Laravel]: um parâmetro ausente ([null]) não é um erro (assume por padrão “hoje” ou “nenhum médico”); uma data inválida é um erro, exibido na parte inferior da página, sem impedir que o restante do conteúdo seja exibido; um número de médico ou de intervalo que não seja um inteiro positivo é simplesmente ignorado;
  • Um paciente conectado que não selecionou um médico pode ver sua agenda: o sistema procura seu médico por meio de sua conta ([getDoctorByUserId]). [?->id]: o operador null-safe retorna [null] se o objeto for [null], em vez de gerar um erro;
  • a lista suspensa de médicos: cada médico se torna um [OptionView]; [map(...)->all()] retorna um array;
  • o calendário, formatado e filtrado de acordo com as permissões do usuário ([scheduleView], abaixo);
  • a janela de agendamento, somente se o intervalo solicitado puder ser agendado por esse usuário: um paciente que tentar gerar a URL [&book=2] de um intervalo já reservado não obteria nada. [array_find] ([PHP] 8.4) retorna o primeiro elemento de um array que satisfaz uma condição, ou [null]. A lista de pacientes é fornecida apenas ao administrador e aos médicos; um paciente recebe somente o próprio nome;
  • a view recebe suas variáveis ([view('schedule', [...])], exemplo 13), incluindo [pageTitle] e [error], que são lidas pelo template.

11.17.3.3. POST /schedule/book

Linhas 161–206:

  • Os campos ocultos do formulário de agendamento (médico, dia, intervalo) são verificados; se forem inválidos, trata-se de uma requisição criada manualmente: [abort(400)], a página de “requisição inválida”;
  • Para um paciente, o campo [clientId] é ignorado: o paciente sempre agenda para si mesmo ([Utils::connectedPatient]). Confiar em um campo enviado pelo navegador permitiria que um paciente mal-intencionado fizesse uma reserva em nome de outra pessoa. Para o administrador e os médicos, um paciente deve ter sido selecionado; caso contrário, a janela de agendamento é reaberta com uma mensagem;
  • o intervalo deve pertencer ao médico indicado na página;
  • as regras de negócio (não no passado, apenas uma consulta futura, intervalo disponível) são verificadas pela camada de negócio. Uma [BusinessException] torna-se uma mensagem de erro flash. A mesma rejeição, “uma consulta futura”, é exibida à segunda pessoa em nome do próprio paciente (“Você já tem...”). Qualquer outra exceção não é interceptada: trata-se de um erro verdadeiro (página 500);
  • em todos os casos, aplica-se o padrão Post/Redirect/Get (exemplo 20): uma mensagem flash e um redirecionamento para o calendário.

11.17.3.4. POST /schedule/cancel

Linhas 212–228: cancelamento de uma consulta pelo administrador ou por um médico (o middleware [role:ADMIN,DOCTOR] na rota). Uma consulta que não existe mais (já cancelada por outra pessoa ou por causa de um clique duplo) não é uma exceção: é apenas uma mensagem.

11.17.3.5. Permissões, o calendário formatado e funções utilitárias

  • linhas 236–244: o que o usuário está autorizado a fazer na página, em um array associativo: o usuário é um administrador (ADMIN ou DOCTOR)? um paciente (e qual)? esse paciente pode fazer uma reserva (nenhuma consulta futura)?
  • Linhas 249–273: a agenda do médico, convertida em linhas para a view. O ponto-chave quanto à confidencialidade está na linha 266: um paciente vê apenas o nome associado à sua própria consulta. Para os demais, a propriedade [patient] é definida como [null], e a view exibe “Reservado”. O nome não é ocultado pela view: ele nunca é passado à view e, portanto, não aparece no código-fonte da página, onde seria fácil lê-lo. O botão “Agendar” é exibido para um intervalo disponível, em um dia que ainda não passou, para um administrador ou um paciente que pode fazer uma reserva; o botão “Cancelar” é exibido apenas para administradores. Os argumentos nomeados ([slotId: $slot->id]) tornam legível a construção de um objeto com oito propriedades;
  • linhas 288–295: a URL da agenda de um médico em um determinado dia. [route('schedule', [...])] acrescenta, no final da URL, como parâmetros de consulta, os valores que não são parâmetros de caminho: [/schedule?doctorId=1&day=2026-09-26];
  • linhas 308–315: a mensagem que explica a um paciente por que não há botão “Agendar” (ele já tem uma consulta futura), a menos que essa consulta esteja no calendário exibido (logo após agendá-la, a mensagem seria deslocada). [array_any] ([PHP] 8.4): pelo menos um elemento satisfaz a condição?

11.17.4. app/Http/Controllers/PersonsController.php

<?php
// =========================================================================
// app/Http/Controllers/PersonsController.php: o gerenciamento dos médicos e
// o dos clientes (reservado ao ADMIN) são IDÊNTICOS: mesma lista, mesmo formulário,
// mesmas regras. Em vez de escrever as mesmas ações duas vezes, nós as escrevemos uma só vez
// nesta classe ABSTRATA; DoctorsController e ClientsController
// herdam dela e especificam apenas o que os distingue: o nome da seção
// (doctors ou clients), as chaves de tradução e os métodos do
// ApplicationModel a chamar. Obtemos assim, para cada um (veja routes/web.php):
//
//   GET  /doctors                    lista
//   GET  /doctors/add                formulário vazio
//   POST /doctors/add                criação
//   GET  /doctors/{id}/edit          formulário preenchido
//   POST /doctors/{id}/edit          modificação
//   POST /doctors/{id}/delete        exclusão
//
// (e as mesmas URLs sob /clients). As views também são comuns:
// resources/views/persons/list.blade.php e persons/form.blade.php.
//
// SEGURANÇA: o middleware [role:ADMIN] é colocado no GRUPO das rotas de cada
// seção (veja routes/web.php): ele protege todas as suas ações - inclusive as
// que forem adicionadas a ela mais tarde.
// =========================================================================

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
{
    // os campos do formulário envolvidos em cada erro de negócio de "entrada" (uma
    // duplicata): eles são contornados em vermelho, com a mensagem no rodapé da 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)
    {
    }

    // o que cada tipo de pessoa deve fornecer

    // "doctors" ou "clients": o início das URLs e dos nomes das rotas
    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 (ou /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 já validou a entrada: uma entrada inválida não chega
    // até aqui (o Laravel redirecionou de volta ao formulário, com os erros)
    // -------------------------------------------------------------------
    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} deve ser composto de dígitos (whereNumber, veja routes/web.php):
    // /doctors/abc/edit não corresponde a nenhuma rota (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
    // (a confirmação "Are you sure?" é solicitada antes de o formulário ser enviado,
    // veja 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');
    }

    // funções internas

    // $person null: formulário de criação; caso contrário: formulário de modificação,
    // preenchido com seus valores (a menos que a view tenha uma entrada a reexibir: 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'),
        ]);
    }

    // uma regra de negócio recusou a gravação: de volta ao formulário (back), com
    // a entrada do usuário (withInput, sem as senhas), a mensagem da camada
    // de negócio (no rodapé da página) e os campos envolvidos, se houver,
    // contornados em vermelho para que o usuário veja imediatamente o que corrigir
    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)) {
            // excluído nesse meio tempo por outro ADMIN: de volta à lista
            return redirect()->route($this->section().'.list');
        }
        return back()->withInput(request()->except('password'))
            ->with('invalidFields', self::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
    }

    // :name e :login das mensagens "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 ?? ''];
    }
}

O gerenciamento de médicos e clientes é idêntico: mesma lista, mesmo formulário, mesmas regras. As ações são escritas uma só vez, em uma classe abstrata; [DoctorsController] e [ClientsController] herdam dela. Cada uma deve fornecer o que a distingue: este é o papel dos métodos abstratos nas linhas 56–68, declarados sem código; uma classe-filha que não os implementasse seria rejeitada pelo [PHP]. Este é o padrão de projeto conhecido como “template method”: a classe-mãe define o algoritmo, enquanto as classes-filhas fornecem os detalhes.

  • linhas 43–47: os campos afetados por cada erro de entrada da camada de negócio: um nome de usuário duplicado afeta o campo “login”; um conflito de nome afeta os campos “nome” e “sobrenome”. Esses campos serão destacados em vermelho;
  • Linhas 73–77: a lista. A view é comum às duas seções: ela recebe as chaves de tradução da seção ([keys]) e seu nome ([section]), que são usados para gerar a URL ([route("$section.addForm")]);
  • linhas 92–101: a adição. A entrada já foi validada por [PersonRequest]: uma entrada inválida não chega a este ponto ([Laravel] redirecionou o navegador de volta ao formulário, junto com os erros). Resta a camada de negócio, que pode rejeitar a gravação (por causa de um homônimo ou de um login já em uso); caso contrário, aparece uma mensagem de sucesso e o usuário volta à lista (padrão PRG);
  • linhas 108–112: o formulário de atualização de um usuário existente: [?? abort(404)] ([abort] lança uma exceção: é uma expressão, utilizável à direita de [??]);
  • linhas 117–126: a atualização; o ID vem do caminho da URL ([{id}]), os dados vêm do formulário;
  • linhas 133–143: a exclusão. O formulário solicitou confirmação no navegador (exemplo 21). A pessoa é recuperada antes da exclusão para a mensagem de sucesso (“O médico Paul TATOU foi excluído.”);
  • linhas 149–161: o formulário, para criação ([$person] é igual a [null]) ou modificação. A view recebe a pessoa e exibe seus valores, exceto após uma rejeição, caso em que reexibe os dados digitados ([old], exemplo 19);
  • linhas 167–176: a camada de negócio rejeitou a operação de escrita. Se a pessoa foi excluída nesse meio tempo (por outro administrador): volta para a lista. Caso contrário, volta ao formulário ([back()], a página anterior, exemplo 19), como no caso de um erro de entrada: a entrada a ser reexibida ([withInput], sem a senha), a mensagem da camada de negócio (uma mensagem de erro flash, exibida na parte inferior da página) e os campos a serem destacados em vermelho ([with('invalidFields', ...)], um valor flash lido pela view). [request()]: a requisição atual, acessível em qualquer lugar;
  • linhas 179–183: os parâmetros [:name] e [:login] das mensagens de sucesso.

11.17.5. app/Http/Controllers/DoctorsController.php e ClientsController.php

<?php
// app/Http/Controllers/DoctorsController.php: o gerenciamento dos médicos (somente papel
// ADMIN). Todas as ações são escritas por PersonsController: resta
// aqui apenas dizer O QUE chamar e QUAIS rótulos exibir.

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... (veja 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);
    }
}

Resta aqui apenas especificar o que chamar (os métodos de [ApplicationModel]) e quais rótulos exibir (as chaves [DOCTORS.xxx] nos dicionários). O construtor é herdado de [PersonsController]: [ApplicationModel] está contido na propriedade [$this->application], declarada como [protected] (visível para as classes-filhas). [ClientsController] é idêntico, com os métodos de cliente e as chaves de [CLIENTS.xxx].

11.17.6. app/Http/Controllers/RegistrationController.php

<?php
// =========================================================================
// app/Http/Controllers/RegistrationController.php: "Create a client account": um
// paciente que ainda não tem conta a cria ele mesmo. Rotas PÚBLICAS (ainda não
// se tem conta, por definição):
//
//   POST /register/access     botão "Create a client account" da página de
//                             login: verifica o captcha DESTA
//                             página e depois abre o formulário
//   GET  /register            o formulário
//   POST /register            a criação e depois volta para a página de login
//
// O caminho é protegido contra robôs por UM captcha, o da página de
// login:
//   1. o botão "Create a client account" envia o formulário de login para
//      /register/access; se o captcha for copiado corretamente, o servidor emite um
//      passe (veja app/Auth/RegistrationPass.php);
//   2. sem um passe válido, /register redireciona para a página de
//      login (middleware CheckRegistrationPass);
//   3. o passe é consumido na criação: um captcha resolvido permite
//      criar UMA conta;
//   4. além disso, o número de contas criadas por hora e por endereço IP é limitado
//      (veja app/Auth/AttemptLimiter.php).
//
// A conta criada é exatamente a que o ADMIN criaria a partir da página "Clients"
// (mesmo método da camada de negócio: addClient), exceto que o paciente
// ESCOLHE seu login e sua senha (obrigatórios, com confirmação).
// =========================================================================

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
{
    // os campos que NUNCA são devolvidos ao 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 (os da página de
    // login; login e password, também enviados, são ignorados)
    // -----------------------------------------------------------------------
    public function access(Request $request): RedirectResponse
    {
        $ip = (string) $request->ip();

        // contas demais criadas recentemente a partir deste endereço: não é preciso ir adiante
        $minutes = $this->limiter->registrationBlockMinutes($ip);
        if ($minutes > 0) {
            Flash::error('ERRORS.TOO_MANY_ACCOUNTS', ['minutes' => $minutes]);
            return redirect()->route('login');
        }

        // captcha ausente ou errado: de volta à página de login, com uma
        // nova imagem (uma falha conta como falha 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 correto: emitimos o passe e abrimos o formulário
        return redirect()->route('registration')
            ->withCookie(RegistrationPass::cookie($this->passes->issue()));
    }

    // -----------------------------------------------------------------------
    // GET /register (o passe foi verificado pelo middleware)
    // -----------------------------------------------------------------------
    public function form(): View
    {
        return view('registration', ['pageTitle' => 'REGISTRATION.TITLE']);
    }

    // -----------------------------------------------------------------------
    // POST /register. RegistrationRequest já validou TODA a entrada (campos
    // e confirmação da senha): o usuário corrige todos os seus erros
    // de uma só vez
    // -----------------------------------------------------------------------
    public function create(RegistrationRequest $request): RedirectResponse
    {
        $ip = (string) $request->ip();

        // 1. contas demais criadas recentemente a partir deste endereço?
        $minutes = $this->limiter->registrationBlockMinutes($ip);
        if ($minutes > 0) {
            Flash::error('ERRORS.TOO_MANY_ACCOUNTS', ['minutes' => $minutes]);
            return back()->withInput($request->except(self::PASSWORDS));
        }

        // 2. a criação (cliente + conta USER, em uma transação)
        try {
            $this->application->addClient($request->personData());
        } catch (BusinessException $e) {
            // login ou nome + sobrenome já utilizados: o passe continua válido
            Flash::error($e->key, $e->params);
            return back()->withInput($request->except(self::PASSWORDS))
                ->with('invalidFields', PersonsController::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
        }

        // 3. o passe foi usado: ele não permitirá criar uma 2ª conta
        $this->passes->consume($request->cookie(RegistrationPass::COOKIE));
        $this->limiter->registrationSuccess($ip);

        // 4. de volta à página de login, login preenchido
        $login = $request->input('login');
        Flash::success('REGISTRATION.DONE', ['login' => $login]);
        return redirect()->route('login', ['login' => $login])
            ->withCookie(RegistrationPass::clearingCookie());
    }
}

O paciente cria ele mesmo uma conta de paciente. O fluxo é protegido por um CAPTCHA, o mesmo usado na página de login.

  • Linhas 60–82: o botão “Criar uma conta de paciente” da página de login envia o formulário de login para este endereço (mais adiante, a view [login]). Se muitas contas foram criadas recentemente a partir deste endereço (IP), não há motivo para prosseguir. Se o CAPTCHA estiver ausente ou incorreto: volta para a página de login com uma nova imagem e uma mensagem; a falha conta como uma tentativa de login malsucedida (com um nome de usuário vazio). Se o CAPTCHA estiver correto: um token é armazenado em um cookie e o usuário é redirecionado para o formulário;
  • linhas 87–90: o formulário. O token foi verificado pelo middleware [registration.pass] da rota;
  • Linhas 97–127: criação. [RegistrationRequest] validou todos os dados digitados, inclusive a confirmação da senha: o usuário vê todos os seus erros de uma só vez. O cliente e sua conta são criados com o mesmo método da camada de negócio usado para o administrador ([addClient]); apenas o nome de usuário e a senha são escolhidos pelo paciente. Se um nome de usuário ou um homônimo já estiver em uso: volta ao formulário, sem consumir o token. A criação de uma conta consome o token (um CAPTCHA resolvido equivale a uma conta), conta para o limite por hora e redireciona para a página de login com o nome de usuário preenchido ([route('login', ['login' => $login])] acrescenta o parâmetro [?login=...]), junto com uma mensagem de sucesso. O cookie do passe é apagado.

A constante [PASSWORDS] (linha 46) lista os campos que nunca devem ser reenviados ao navegador: [back()->withInput()], sem parâmetro, manteria toda a entrada para o próximo formulário, inclusive as senhas; [$request->except([...])] reenvia o formulário sem esses campos. Quando o [Laravel] volta ao formulário (por causa de um erro de validação), ele exclui automaticamente os campos [password], [password_confirmation], e [current_password].

11.17.7. app/Http/Controllers/PatientAreaController.php

<?php
// =========================================================================
// app/Http/Controllers/PatientAreaController.php: as páginas PESSOAIS do paciente (papel
// USER), as que ele vê logo após fazer login:
//
//   GET  /my-area                  página inicial: [Manage my account], [View a
//                                  schedule] e sua consulta futura
//   POST /my-area/cancel           cancela SUA consulta
//   GET  /my-account               formulário de modificação de sua conta
//   POST /my-account               modificação
//   POST /my-account/delete        exclusão da conta (e de suas consultas)
//
// Regra de ouro deste controller: o paciente envolvido é SEMPRE o do token
// (Utils::connectedPatient), nunca um identificador enviado pelo navegador. Um
// paciente não pode, portanto, nem ver, nem modificar, nem cancelar o que pertence a outro
// paciente, mesmo construindo ele mesmo suas requisições.
//
// Qualquer modificação ou exclusão da conta exige a senha ATUAL:
// quem encontrasse uma sessão deixada aberta não poderia nem mudar a
// senha, nem excluir a conta. Os erros de senha atual são
// contados como falhas de login (mesmo limite).
// =========================================================================

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(),
            // link para a agenda do médico nesse dia: o paciente vê seu nome ali
            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;
        // uma consulta que não existe e a de OUTRO paciente recebem a
        // mesma resposta: não revelamos nada sobre as consultas dos outros
        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: o formulário, preenchido com os valores do paciente
    // -----------------------------------------------------------------------
    public function accountForm(): View
    {
        $patient = Utils::connectedPatient($this->application);
        return view('account', ['pageTitle' => 'MY_ACCOUNT.TITLE', 'patient' => $patient]);
    }

    // -----------------------------------------------------------------------
    // POST /my-account (MyAccountRequest validou a entrada)
    // -----------------------------------------------------------------------
    public function editAccount(MyAccountRequest $request): RedirectResponse
    {
        $patient = Utils::connectedPatient($this->application);

        // a senha atual; se errada: a mensagem vai ABAIXO do campo e no rodapé da 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] ?? []);
        }
        // o login e o nome exibido estão NO token: emitimos um novo,
        // caso contrário a barra de navegação manteria o nome antigo
        Flash::success('MY_ACCOUNT.UPDATED');
        return redirect()->route('area')->withCookie($this->auth->tokenCookie($client->account));
    }

    // -----------------------------------------------------------------------
    // POST /my-account/delete   campo: current_password
    // A conta, o cliente e TODAS as suas consultas desaparecem juntos e, em seguida, o
    // paciente é deslogado.
    // -----------------------------------------------------------------------
    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());
    }

    // funções internas

    // null se a senha atual está correta; caso contrário, a mensagem de erro
    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;
    }
}

As páginas pessoais do paciente. A regra de ouro deste controller: o paciente em questão é sempre aquele associado ao token ([Utils::connectedPatient]), nunca um identificador enviado pelo navegador. Um paciente não pode, portanto, ver, modificar ou cancelar informações de outro paciente, mesmo que construa suas próprias requisições.

  • linhas 53–66: Minha área: o nome do paciente e suas próximas consultas, formatadas ([AppointmentView]), cada uma com um link para a agenda do médico naquele dia;
  • linhas 71–85: cancelamento da consulta do paciente. Uma consulta inexistente e a consulta de outro paciente recebem a mesma resposta: nenhuma informação sobre as consultas de outros pacientes é divulgada (nem mesmo sua existência);
  • linhas 90–94: o formulário “Gerenciar minha conta”, preenchido previamente com as informações do paciente;
  • linhas 99–122: a modificação. Qualquer modificação exige a senha atual: alguém que encontrasse uma sessão deixada aberta não conseguiria alterar a senha nem fazer qualquer outra coisa. Uma senha atual incorreta: volta ao formulário, com uma mensagem abaixo do campo ([withErrors] adiciona um erro de entrada, como se a validação o tivesse detectado) e na parte inferior da página (mensagem flash). Após a edição, um novo token é gerado: o login e o nome de exibição estão incluídos no token; caso contrário, a barra de navegação manteria o nome antigo até o próximo login;
  • linhas 129–140: exclusão da conta, do cliente e de todas as suas consultas, usando o mesmo método da camada de negócio que o do administrador. A senha atual é obrigatória; o paciente é então desconectado (cookie do token apagado);
  • linhas 145–158: verificação da senha atual. Ela está sujeita ao limitador de tentativas, assim como um login: sem isso, alguém com uma sessão aberta poderia tentar milhares de senhas pelo formulário “Gerenciar minha conta” e descobrir a correta.

11.18. As views

As views [Blade] na pasta [resources/views]: um template, fragmentos, componentes e páginas.

11.18.1. O template e os fragmentos

11.18.1.1. resources/views/layout.blade.php

<!doctype html>
{{-- =========================================================================
     resources/views/layout.blade.php
     -------------------------------------------------------------------------
     The layout COMMON to all the pages (see example 15): each page
     (schedule.blade.php, login.blade.php...) EXTENDS it (@extends) and fills its
     [content] section.

     Blade ESCAPES everything it displays with {{ ... }} (the characters < > & " '
     become &lt; &gt;...): protection against HTML injection through a typed
     name, for example. To insert HTML as is, it must be requested
     explicitly ({!! ... !!}, see components/captcha.blade.php).

     Messages: a success is displayed at the TOP of the page, an error at the BOTTOM, on a
     light pink background (errors fragment).

     The layout shares the variables of the page: [pageTitle] (the key of the title of
     the page, passed by the action); [language] and [user], added to all
     the views by AppServiceProvider.
     ========================================================================= --}}
<html lang="{{ $language }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {{-- __($key): the translation of a key; here, the key is a VARIABLE --}}
  <title>{{ __($pageTitle) }} - {{ __('APP.TITLE') }}</title>
  {{-- asset(): the URL of a file of the public folder --}}
  <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>
  {{-- the "Are you sure?" dialog, hidden as long as it is not needed --}}
  @include('fragments.confirmation')
  <script src="{{ asset('js/app.js') }}"></script>
</body>
</html>

O template comum a todas as páginas (exemplo 15): cada página o estende ([@extends('layout')]) e preenche sua seção [content] (linha 36).

  • linha 21: o idioma da página, [fr] ou [en], fornecido a todas as views pelo view composer [AppServiceProvider];
  • linha 26: o título da página, traduzido: [__($pageTitle)] traduz a chave contida na variável [$pageTitle], que cada ação passa à sua view;
  • linhas 28–29: a função [asset] gera a URL de um arquivo da pasta [public] (exemplo 15);
  • linhas 33–38: a barra de navegação, as mensagens de sucesso no topo da página, o conteúdo da página e a área de erros na parte inferior da página. Esses fragmentos são inseridos por [@include] (exemplo 15): eles acessam as variáveis da página;
  • linha 41: a janela “Tem certeza?”, que fica oculta até ser necessária, e o script que a exibe.

[Blade] escapa tudo o que exibe usando [{{ ... }}] (exemplo 14): um nome digitado que contenha HTML ([<script>]) é exibido como está, sem ser interpretado. Isso impede que HTML (XSS) seja injetado sem esforço em todas as páginas.

11.18.1.2. resources/views/fragments/navbar.blade.php

{{-- =========================================================================
     resources/views/fragments/navbar.blade.php - the navigation bar.

     Title, FR/EN, role, name, logout - and a menu whose entries depend
     on the role: "Doctors" and "Clients" only appear for the ADMIN. It is
     only a display convenience: the real protection is the middlewares of the
     routes (a USER who types /doctors by hand gets a 403 page). A patient
     (USER) also has their "My area" menu.

     The menu of the current page is highlighted ("active" class):
     request()->is('schedule*') is true if the path of the URL starts with "schedule".
     The menu entries: an array [URL, label key, pattern of the paths for
     which the entry is active], traversed by @foreach.
     ========================================================================= --}}
@php
  $menu = [];
  if ($user) {
      if ($user->isPatient()) {
          // ativo para /my-area E /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>
    {{-- the logout is a POST: a form reduced to its button (and to the anti-CSRF token) --}}
    <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>

A barra de navegação. Os itens do menu dependem do papel: “Minha área” para um paciente, “Médicos” e “Pacientes” para o administrador. Isso é apenas uma comodidade: a proteção real vem do middleware das rotas (um paciente que digitar [/doctors] manualmente receberá uma página 403).

  • Linhas 15–28: o menu é definido em um bloco [@php] (exemplo 14), um array de entradas: URL (a chave do rótulo) e o padrão de caminhos para os quais a entrada está ativa. [request()->is('schedule*')] é verdadeiro se o caminho da URL requisitada corresponder ao padrão ([*]: qualquer sequência de caracteres). A entrada “Minha área” fica ativa para [/my-area] e [/my-account] (padrão [my-*]). Isso está no limite da regra “nenhuma lógica nas views”: no entanto, essa lógica diz respeito apenas à exibição e é usada somente aqui;
  • linhas 33–38: [@foreach] decompõe cada entrada do array em três variáveis (exemplo 25). [@class([...])] (exemplo 16) escreve o atributo [class] com as classes cuja condição é verdadeira;
  • linhas 44–47: os botões FR / EN, links simples ([/language/fr]), com o idioma ativo destacado;
  • linhas 50–58: para um usuário logado, seu papel ([$user->role->value]: a string que representa o caso da enumeração), seu nome e o botão de logout. O logout é uma requisição POST: um formulário reduzido ao seu botão, com seu token anti-CSRF ([@csrf], exemplo 18).

11.18.1.3. resources/views/fragments/success.blade.php

{{-- =========================================================================
     resources/views/fragments/success.blade.php - the SUCCESS messages put
     by the previous action (appointment booked, doctor added...), displayed
     only once, at the top of the page (see app/Web/Flash.php). An ERROR flash
     message, for its part, is displayed at the bottom of the page, by the errors fragment.

     Each message is a Message object: __($message->key, $message->params)
     is the text of the key, where :name, :login... are replaced by their values.
     ========================================================================= --}}
@foreach (session('flash_success', []) as $message)
<div class="alert alert-success" role="status">{{ __($message->key, $message->params) }}</div>
@endforeach

As mensagens flash de sucesso, definidas pela ação anterior ([Flash::success]), são lidas da sessão por [session('flash_success', [])] (uma lista vazia por padrão). Cada uma é um objeto [Message], traduzido aqui para o idioma da página: [__($message->key, $message->params)]. [role="status"]: um leitor de tela anuncia a mensagem.

11.18.1.4. resources/views/fragments/errors.blade.php

{{-- =========================================================================
     resources/views/fragments/errors.blade.php - the error zone, at the BOTTOM of
     each page, on a light pink background (class .error-zone, see public/css/styles.css).

     It gathers the three possible sources of errors:
       - $error: the error of the displayed page (invalid date, captcha wrongly
         copied...), passed by the action;
       - the error flash messages, put by the previous action before a
         redirection (slot already booked, login already taken, deletion refused...);
       - the input errors ($errors, see example 19): their messages are
         displayed UNDER the fields; here, if there is no other message, a
         simple sentence "The form contains errors.".

     $error ?? null: the variable does not exist in all the pages.
     role="alert": a screen reader announces the message as soon as the
     page is displayed, even if it is at the bottom.
     ========================================================================= --}}
@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

A área de erros, na parte inferior de cada página, sobre um fundo rosa claro. Ela lista as três possíveis fontes de erro:

  • o erro da página exibida ([$error]), disparado pela ação: uma data inválida, um CAPTCHA digitado incorretamente etc. [$error ?? null]: a variável não existe em todas as páginas; o operador [??] não sinaliza uma variável inexistente: ele a substitui por [null];
  • mensagens de erro flash, disparadas pela ação anterior (um intervalo já reservado, um nome de usuário já em uso etc.);
  • erros de entrada ([$errors], exemplo 19): suas mensagens são exibidas abaixo dos campos; aqui, se não houver outras mensagens, aparece uma frase simples: “O formulário contém erros.” Em um formulário longo, isso avisa ao usuário que ele precisa voltar ao topo.

[array_unshift] adiciona um item ao início de um array. [role="alert"]: um leitor de tela anuncia a mensagem assim que a página é exibida, mesmo que ela esteja na parte inferior. A área permanece ancorada na parte inferior da janela quando a página é longa (veja a folha de estilos, abaixo).

11.18.1.5. resources/views/fragments/confirmation.blade.php

{{-- =========================================================================
     resources/views/fragments/confirmation.blade.php - the modal dialog
     "Are you sure?" (see example 21).

     It replaces the browser's window.confirm() box, which can neither be styled
     nor translated (its buttons stay in the language of the browser, not
     in that of the page).

     ONE SINGLE dialog for the whole page, hidden (d-none) at first. Its labels
     are translated here, by the server, like the rest of the page; the small script
     public/js/app.js merely displays it, puts in it the message specific to the
     form (data-confirmation attribute), and sends the form if
     the user confirms.
     ========================================================================= --}}
<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" rather than "Cancel": the question is sometimes
               "Cancel this appointment?", and a "Cancel" button would be ambiguous there --}}
          <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>

A janela modal “Tem certeza?” do exemplo 21, que substitui a caixa de diálogo [window.confirm()] do navegador: essa caixa de diálogo não é formatada corretamente, e seus botões permanecem no idioma do navegador, não no da página. Uma única janela para a página inteira, inicialmente oculta (classe [d-none] proveniente do [Bootstrap]); seus rótulos são traduzidos pelo servidor, assim como o restante da página. O script [public/js/app.js] a exibe, coloca dentro dela a mensagem do formulário a ser confirmado (seu atributo [data-confirmation]) e envia o formulário se o usuário confirmar. O botão “Cancelar” tem o rótulo “Não, voltar” em vez de “Cancelar”: a pergunta às vezes é “Cancelar esta consulta?”, e um botão “Cancelar” seria ambíguo nesse contexto.

11.18.1.6. resources/views/fragments/booking.blade.php

{{-- =========================================================================
     resources/views/fragments/booking.blade.php - the booking window
     of the schedule.

     The REAL Bootstrap classes of a modal dialog (.modal, .modal-backdrop...),
     made visible "hard-coded" (show d-block) rather than by Bootstrap's
     JavaScript. It is the SERVER that decides to display it (&book=...
     parameter of the URL), and closing it amounts to following a link to the same page without this
     parameter.

     The fragment directly reads the variables of the page that includes it
     ($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>

        {{-- what the server must know in addition to the chosen patient --}}
        @csrf
        <input type="hidden" name="doctorId" value="{{ $doctorId }}">
        <input type="hidden" name="day" value="{{ $day }}">
        <input type="hidden" name="slotId" value="{{ $booking->slotId }}">

        {{-- a patient books for themselves: no list to choose from (and the
             server ignores a possible clientId anyway) --}}
        @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>

A janela de agendamento do calendário. Ela usa as classes reais de uma janela modal do [Bootstrap] ([modal], [modal-backdrop]...), mas tornada visível de forma "fixa no código" ([show d-block]), em vez de por meio do [JavaScript] do [Bootstrap]: é o servidor que decide exibi-la quando a URL contém [&book=...]. Fechá-la (pelo X ou pelo botão Cancelar) equivale a seguir um link para a mesma página sem esse parâmetro ([$backUrl]).

  • linhas 27–30: o token anti-CSRF e o que o servidor precisa saber: o médico, o dia e o horário;
  • linhas 34–47: um paciente faz a reserva para si mesmo: seu nome, sem lista para escolher (e o servidor ignora qualquer campo [clientId] de qualquer maneira). O administrador e os médicos selecionam o paciente em uma lista; [required] e [autofocus]: o navegador exige uma seleção e coloca o cursor na lista.

11.18.2. Os componentes

Três componentes anônimos (Exemplo 15), na pasta [resources/views/components], usados pelas páginas na forma de uma tag [<x-name>].

11.18.2.1. resources/views/components/field.blade.php

{{-- =========================================================================
     resources/views/components/field.blade.php - an input field, its label,
     its error message or its help (see example 19): <x-field name="login" ... />

     @props: the attributes expected by the component, with their default value.
     The displayed value: old($name, $value), the input to redisplay after a refusal,
     otherwise the given value. A password is NEVER redisplayed.
     The field is outlined in red (Bootstrap class is-invalid) if it has an input
     error ($errors), or if a business error designates it (invalidFields, see
     PersonsController::businessError); the error message then replaces the help.
     ========================================================================= --}}
@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

Um campo de entrada, com seu rótulo, mensagem de erro ou dica: o componente [x-field] do Exemplo 19, totalmente configurado.

  • Linha 12: os atributos do componente e seus valores padrão. Em uma página, [<x-field name="login" :label="__('PERSONS.LOGIN_LABEL')" max="30" required />]: um atributo precedido por [:] recebe o valor de uma expressão [PHP], enquanto os demais recebem uma string; um atributo sem valor ([required]) é definido como [true];
  • linhas 14–16: o campo é inválido se contiver um erro de entrada ([$errors->has($name)]) ou se um erro da camada de negócio o sinalizar como tal: a lista [invalidFields], armazenada na sessão pela action ([PersonsController::businessError]). Um nome de usuário já utilizado não é um erro de entrada (tem o formato correto), mas o usuário precisa ver qual campo corrigir;
  • linhas 18–22: o valor exibido é [old($name, $value)]: a entrada a ser reexibida após uma rejeição; caso contrário, o valor transmitido pela página (o do registro modificado). Uma senha nunca é reexibida: não há atributo [value] para um campo [password]. [@required($required)] define o atributo booleano [required] se a condição for verdadeira;
  • linhas 23–29: a mensagem de erro do campo ([$message], exemplo 19) ou, caso não haja, a eventual ajuda disponível. A classe [invalid-feedback] do [Bootstrap] só fica visível após um campo da classe [is-invalid].

11.18.2.2. resources/views/components/person-fields.blade.php

{{-- =========================================================================
     resources/views/components/person-fields.blade.php - the identity fields
     (title, first name, last name), common to three forms: doctor/client of the ADMIN,
     "Create a client account" and "Manage my account": <x-person-fields :person="..." />

     :person: the person whose values are displayed (null for an empty
     form). $person?->title: null if $person is null ("nullsafe" operator).
     The list of titles comes from the class that validates them (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 identidade comuns a três formulários: título (uma lista), nome e sobrenome (dois [x-field] campos: um componente pode usar outro componente). O atributo [person] é a pessoa cujos valores são exibidos, ou [null] para um formulário vazio. [$person?->title]: o operador null-safe retorna [null] se [$person] for nulo. A lista de títulos vem da classe que os valida ([PersonFieldsRequest::TITLES]): a regra é escrita uma só vez. [@selected(...)] escreve o atributo [selected] da opção selecionada.

11.18.2.3. resources/views/components/captcha.blade.php

{{-- =========================================================================
     resources/views/components/captcha.blade.php - the captcha of the login
     page (see app/Auth/CaptchaService.php). It protects both the
     login and the access to the account creation ("Create a client account" button).

     {!! ... !!}: the SVG image is inserted AS IS in the page, without
     escaping. It is harmless here because this SVG is built by the
     server itself and contains nothing that comes from the user - one would
     NEVER do this with an input.

     The hidden field captchaId tells the server WHICH captcha to verify; the right
     answer, for its part, is never sent to the browser. "Another image" simply
     reloads the page (url()->current(): the URL of the page, without its parameters).
     ========================================================================= --}}
@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>

O CAPTCHA (exemplo 27). [{!! $captcha->svg !!}] insere a imagem SVG como está, sem escapá-la; caso contrário, o navegador exibiria seu código XML. Isso é seguro aqui porque esse SVG é gerado pelo servidor e não contém nada fornecido pelo usuário: nunca faríamos isso com uma entrada do usuário. O campo oculto [captchaId] informa ao servidor qual CAPTCHA verificar; a resposta em si nunca é enviada ao navegador. O link “Outra imagem” recarrega a página ([url()->current()]: a URL da página, sem seus parâmetros) e, portanto, o CAPTCHA.

11.18.3. As páginas

11.18.3.1. resources/views/login.blade.php

{{-- =========================================================================
     resources/views/login.blade.php - the login form (see
     AuthController). An ordinary HTML <form>: the browser itself sends
     login, password and captcha answer in POST /login, without JavaScript. In
     case of failure, the server sends back THIS page, with the login already typed, a
     NEW captcha and the error, displayed at the bottom of the page by the layout.
     ========================================================================= --}}
@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: a boolean attribute, written if the condition is true, omitted
               otherwise. The cursor goes to the first field to fill in --}}
          <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>

        {{-- no account yet: a patient can create one themselves. It is NOT
             a simple link: it is a second submit button of THIS form,
             which goes to another address (formaction). There the server checks the
             captcha above before opening the account creation page (see
             RegistrationController). formnovalidate: the browser does not require
             login and password (useless to create an account). Enter in a
             field always triggers the FIRST button of the form, "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

O formulário de login, um [<form>] padrão, é enviado como POST para [/login].

  • Linhas 22–23: o nome de usuário digitado é reexibido após uma tentativa de login malsucedida ([$login]). O atributo [autofocus] coloca o cursor no primeiro campo a ser preenchido: o nome de usuário, se estiver vazio, ou a senha, caso contrário (após uma tentativa malsucedida ou após a criação de uma conta);
  • linha 31: o CAPTCHA;
  • linhas 42–43: o botão “Criar uma conta de paciente” não é um link; é um segundo botão que envia o mesmo formulário para outro endereço (atributo de botão [formaction]). O servidor verifica o CAPTCHA ali antes de abrir a página de criação de conta ([RegistrationController::access]). [formnovalidate]: o navegador não exige nome de usuário e senha (atributos [required]), pois eles não são necessários para criar uma conta. Pressionar a tecla Enter em um campo sempre aciona o primeiro botão de envio do formulário: Entrar.

11.18.3.2. resources/views/schedule.blade.php

{{-- =========================================================================
     resources/views/schedule.blade.php - the main page (see ScheduleController).
     Three blocks:
       1. the choice of the doctor and of the day;
       2. the schedule;
       3. the booking window (booking fragment).
     A possible error (invalid date, unknown doctor) is displayed at the bottom of
     the page by the layout (errors fragment).
     ========================================================================= --}}
@extends('layout')

@section('content')
  {{-- 1. choice of the doctor and of the day: a GET form, which simply reloads
          this page with ?doctorId=...&day=... in the 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] is only set if the user has the right to see this
                 name (ADMIN, DOCTOR, or the patient for THEIR appointment) - otherwise,
                 simply "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>
            {{-- the displayed buttons have been decided by the controller (bookable,
                 appointmentId) according to the user's role. "Book" is a simple
                 link: it reopens this page with the booking window of this slot --}}
            @if ($row->bookable)
            <a class="btn btn-sm btn-outline-success" href="{{ $row->bookUrl }}">{{ __('SCHEDULE.BOOK') }}</a>
            @endif
            {{-- "Cancel" MODIFIES data: it is therefore a 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. the booking window, only if the URL contains &book=... --}}
  @if ($booking)
  @include('fragments.booking')
  @endif
@endsection

A página principal. Três seções: seleção de um médico e de um dia, o calendário e a janela de agendamento.

  • Linhas 15–34: seleção de um médico e de um dia: um formulário GET (Exemplo 17), que recarrega a página com [?doctorId=...&day=...] na URL. O dia é um campo [type="date"]: o navegador exibe um calendário e envia a data no formato [yyyy-mm-dd], independentemente de como a exibe ([26/09/2026] em francês);
  • linhas 37–42: para um paciente que já tem uma consulta futura, o motivo de não haver botão “Agendar”;
  • linhas 66–72: o status do horário: “Livre” (em verde), o nome do paciente (em azul para a consulta do paciente logado, em cinza caso contrário) ou “Reservado”. A view não toma nenhuma decisão: [$row->patient] só é preenchido se o usuário tiver permissão para ver esse nome;
  • linhas 78–80: “Agendar” é um simples link: ele reabre a página com a janela de agendamento para aquele horário ([$row->bookUrl]). Não modifica nada: um GET é suficiente;
  • linhas 82–91: “Cancelar” modifica dados: é um formulário POST (exemplo 21), com seu token anti-CSRF, a consulta a ser cancelada e as informações para voltar à mesma página (o médico, o dia). O atributo [data-confirmation] faz o script da página solicitar uma confirmação;
  • linhas 106–108: a janela de agendamento, se solicitada pela URL (e se o horário estiver disponível para agendamento).

11.18.3.3. resources/views/persons/list.blade.php

{{-- =========================================================================
     resources/views/persons/list.blade.php - the list of the doctors OR of the
     clients (ADMIN). A single view for both: the keys of the labels specific to
     each one arrive in $keys, and $section ("doctors" or "clients") gives the
     start of the route names (see 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: a confirmation dialog will open before
                   the form is sent (see 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

A lista de médicos ou clientes: os rótulos específicos de cada um são chaves de tradução ([$keys]), e os valores das URLs são gerados a partir do nome da seção ([route("$section.editForm", ['id' => ...])]: em uma string delimitada por aspas, [$section] é substituído por seu valor, [doctors] ou [clients]). [$person->account?->login]: o login da conta, carregado com a lista ([with('account')], camada DAO). [isNotEmpty()]: a coleção não está vazia. O botão Excluir é um formulário POST, com confirmação.

11.18.3.4. resources/views/persons/form.blade.php

{{-- =========================================================================
     resources/views/persons/form.blade.php - creation OR modification of a
     doctor or of a client (ADMIN). $creating distinguishes the two cases; $person
     is the modified person (null for a creation).

     When the input is refused (empty field, login already taken...), the action sends
     the browser back to THIS page (redirection), and the view displays:
       - the values already typed (old(), in the x-field components);
       - the faulty fields outlined in red (Bootstrap class "is-invalid");
       - under a field refused by the validation, its message;
       - the error message of the page, AT THE BOTTOM of the page (errors fragment).
     ========================================================================= --}}
@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: we let the SERVER validate (it is the one that is authoritative); the
           browser's checks (required...) are only a convenience, that a
           user can always bypass --}}
      <form method="post" action="{{ $action }}" novalidate>
        @csrf
        @unless ($creating)
        {{-- the version of the displayed record: the optimistic lock --}}
        <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">
          {{-- never pre-filled: the password never goes back to the browser --}}
          <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

Criação ou edição de um médico ou de um cliente.

  • Linha 24: o atributo [novalidate] desativa os controles do navegador ([required], [maxlength]...) quando o formulário é enviado: o servidor valida o formulário, e sua validação é definitiva. Os validadores do navegador são apenas uma conveniência que qualquer um pode contornar; desativá-los aqui permite ver as mensagens do servidor;
  • Linhas 26–29: [@unless] (“a menos que”) é o oposto de [@if]. Durante uma modificação, a versão do registro (o bloqueio otimista) é armazenada em um campo oculto;
  • linha 32: título, nome e sobrenome, preenchidos previamente com os valores da pessoa;
  • linhas 37–44: o nome de usuário, preenchido previamente com o nome de usuário da conta ([$person?->account?->login]: dois operadores null-safe encadeados), e a senha, que nunca é preenchida previamente. Suas dicas diferem na criação (“por padrão, o sobrenome em minúsculas”) e na edição (“Deixe em branco para mantê-la inalterada”).

11.18.3.5. resources/views/registration.blade.php

{{-- =========================================================================
     resources/views/registration.blade.php - "Create a client account" (public
     page, see RegistrationController). Same identity fields as the
     ADMIN's form (x-person-fields component), but the login and the
     password are required, with confirmation. No captcha HERE: one only gets
     to this page after having copied that of the login page
     ("Create a client account" button).
     ========================================================================= --}}
@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

Criação de uma conta de paciente: os campos de identidade (um formulário vazio), seguidos do nome de usuário, da senha e da confirmação da senha, que são obrigatórios. [@php($min = ...)]: a forma curta de [@php], para uma única instrução. O texto de ajuda da senha especifica o comprimento mínimo: [__('REGISTRATION.PASSWORD_HELP', ['min' => $min])], “Pelo menos 6 caracteres.” Sem CAPTCHA aqui: só se chega a esta página depois de resolver o CAPTCHA da página de login.

11.18.3.6. resources/views/area.blade.php

{{-- =========================================================================
     resources/views/area.blade.php - "My area": the home page of the patient
     (USER role), displayed right after their login.
       - two options: [Manage my account] and [View a schedule];
       - their upcoming appointment, if they have one, with the means to cancel it.
     ========================================================================= --}}
@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>
    {{-- normally only one (rule "one upcoming appointment at a time"), but the
         page can display several. @forelse ... @empty: a loop, and what
         is displayed if the list is empty; $loop->last: last element? --}}
    @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

“Minha área”, a página inicial do paciente: dois cartões grandes (“Gerenciar minha conta”, “Ver uma agenda”) e sua próxima consulta.

  • Linhas 32–51: [@forelse] (Exemplo 14) é um laço, seguido ([@empty]) pelo que exibir se a lista estiver vazia. Normalmente, um paciente tem no máximo uma consulta futura; no entanto, a página foi projetada para exibir várias consultas. [$loop->last] (Exemplo 14): o último item não tem separador;
  • cada consulta tem um formulário de cancelamento (POST, com confirmação), que envia apenas o seu ID: o servidor verificará se ela pertence ao paciente logado.

11.18.3.7. resources/views/account.blade.php

{{-- =========================================================================
     resources/views/account.blade.php - "Manage my account" (USER role).
     Two independent forms on the same page:
       1. the modification (identity, login, optional new password);
       2. the deletion of the account - which also cancels its appointments.
     Both require the CURRENT password (current_password field).
     ========================================================================= --}}
@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. deletion. The password field has the same NAME as that of the first
         form (current_password), but another id: two elements of the same
         page cannot have the same 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

“Gerenciar minha conta”: dois formulários independentes na mesma página.

  • linhas 19–53: edição: a versão (bloqueio otimista), os campos de identidade, o nome de usuário, a nova senha e sua confirmação (opcionais) e a senha atual (obrigatória);
  • Linhas 62–71: exclusão da conta, com seu próprio campo de senha atual e confirmação. O campo tem o mesmo nome que o do primeiro formulário ([current_password]: apenas um formulário é enviado por vez), mas não o mesmo ID: dois elementos de uma página não podem ter o mesmo ID, como indica o atributo [for] de um label.

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

A página de erro, gerada por [bootstrap/app.php]: o código HTTP, a mensagem e um link para a página inicial ([/], que redireciona para a página inicial do papel ou para a página de login).

11.19. Arquivos estáticos

A pasta [public] é a raiz do site: o servidor envia os arquivos ali localizados como estão (exemplo 15). Além de [index.php], ela contém o [Bootstrap] ([lib/bootstrap]), uma folha de estilo e um script.

11.19.1. public/css/styles.css

/* =========================================================================
   public/css/styles.css - alguns ajustes sobre o Bootstrap
   (os mesmos das outras versões desta aplicação).
   ========================================================================= */

body {
  background-color: #f5f7fa;
}

.free-slot:hover {
  background-color: #e9f7ef;
}

/* -
   .error-zone: as mensagens de erro, na parte inferior da página, sobre um fundo rosa claro
   (veja resources/views/fragments/errors.blade.php).
   position: sticky + bottom: se a página for mais alta que a janela (uma
   agenda de 12 horários, por exemplo), a zona permanece colada na parte inferior da
   janela em vez de desaparecer abaixo da dobra - sem nunca cobrir
   o conteúdo quando a página é curta.
   z-index: acima do fundo cinza da janela 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;
}

/* as duas grandes opções da página "My area" do 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);
}

/* a imagem do captcha (SVG de 150 x 50 pixels) */
.captcha-image svg {
  display: block;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}

Alguns ajustes adicionais para o [Bootstrap], os mesmos das outras versões da aplicação.

  • Linhas 10–12: uma linha reservável do calendário fica verde quando o mouse passa sobre ela;
  • linhas 23–33: a área de erro no final da página tem um fundo rosa claro. [position: sticky] com [bottom: 1rem]: se a página for mais alta que a janela (um calendário com 12 horários), a área permanece ancorada na parte inferior da janela em vez de desaparecer abaixo da barra de rolagem; se a página for curta, ela fica no lugar sem cobrir nada. [z-index]: ela aparece sobre o fundo cinza da janela de agendamento;
  • linhas 36–43: os dois cartões grandes “Minha área”, que se destacam quando o mouse passa sobre eles;
  • linhas 46–50: a imagem do CAPTCHA, com uma borda.

11.19.2. public/js/app.js

// =========================================================================
// public/js/app.js - o ÚNICO JavaScript da aplicação.
// -------------------------------------------------------------------------
// A aplicação inteira funciona sem JavaScript. Este script acrescenta uma
// comodidade: antes de enviar um formulário que carrega o atributo
// data-confirmation="...", uma caixa de diálogo modal pergunta "Are you sure?"
// (a própria caixa de diálogo está na página: resources/views/fragments/confirmation.blade.php).
// Se o JavaScript estiver desativado, o formulário é simplesmente enviado sem
// confirmação - nada quebra (princípio de "progressive enhancement").
//
// Por que não window.confirm()? Sua caixa não pode ser estilizada e seus
// botões permanecem no idioma do navegador, não no da 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; // o formulário a enviar se o usuário confirmar
  let previousFocus = null; // o elemento ao qual devolver o foco ao fechar

  function open(form) {
    pendingForm = form;
    previousFocus = document.activeElement;
    // textContent (e não innerHTML): a mensagem é exibida como TEXTO,
    // nunca interpretada como HTML
    message.textContent = form.dataset.confirmation;
    modal.classList.remove('d-none');
    // o foco vai para "No": um Enter pressionado distraidamente não exclui nada
    noButton.focus();
  }

  function close() {
    modal.classList.add('d-none');
    pendingForm = null;
    if (previousFocus) {
      previousFocus.focus();
    }
  }

  // 1. interceptamos o envio dos formulários a confirmar
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault();
      open(form);
    });
  });

  // 2. os botões da caixa de diálogo (Yes / No / cruz de fechamento)
  modal.addEventListener('click', (event) => {
    const action = event.target.closest('[data-action]')?.dataset.action;
    if (action === 'yes') {
      const form = pendingForm;
      close();
      // form.submit() envia o formulário SEM disparar novamente o
      // evento 'submit': nenhum novo pedido de confirmação
      form.submit();
    } else if (action === 'no') {
      close();
    } else if (event.target.classList.contains('modal')) {
      close(); // clique no fundo cinza, fora da caixa de diálogo
    }
  });

  // 3. teclado: Escape fecha a caixa de diálogo; Tab permanece DENTRO da caixa
  //    (senão o foco iria para a página acinzentada, atrá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();
      }
    }
  });
})();

O único [JavaScript] da aplicação — o do Exemplo 21 — com algumas adições. Toda a aplicação funciona sem [JavaScript]: este script acrescenta conveniência ao pedir uma confirmação antes de enviar um formulário que traga o atributo [data-confirmation]. Se o [JavaScript] estiver desativado, o formulário é enviado sem confirmação: nada quebra (princípio do aprimoramento progressivo).

  • Linhas 15–21: o script é uma função chamada assim que é definida ([(() => { ... })()]); suas variáveis não são visíveis para o restante da página. Sem uma janela de confirmação na página, ele não faz nada;
  • Linhas 26–35: abertura da janela: o formulário a ser enviado após a confirmação é armazenado, e a mensagem do formulário é exibida na janela. [textContent], e não [innerHTML]: a mensagem é exibida como texto e nunca é interpretada como HTML. O foco passa para o botão “Não”: pressionar Enter acidentalmente não exclui nada;
  • linhas 37–43: fechamento da janela; o foco volta ao elemento que o tinha anteriormente;
  • linhas 46–50: o envio de cada formulário a ser confirmado é interceptado ([preventDefault] o impede), e a janela se abre;
  • linhas 54–67: os botões da janela. Um único handler para toda a janela: [closest('[data-action]')] identifica o botão clicado ou o elemento que o contém. “Sim” envia o formulário por meio de [form.submit()], que não dispara o evento [submit]: nenhum novo pedido de confirmação é emitido. Clicar no fundo acinzentado fora da janela a fecha;
  • linhas 71–86: o teclado. Esc fecha a janela; a tecla Tab move o foco de um botão para outro sem sair da janela (caso contrário, ele iria para a página acinzentada atrás dela): é o que esperam os usuários que navegam com o teclado e leitores de tela.