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 por um dia, um horário e um cliente (um paciente). Trata-se do porte exato para o [Symfony] da aplicação [Laravel] da lição anterior (que, por sua vez, foi portada das versões [Flask], [Spring MVC] e [ASP.NET Core MVC]): o mesmo banco de dados, as mesmas regras de negócio, as mesmas páginas, as mesmas URLs, os mesmos textos. As páginas HTML são geradas pelo servidor por meio de views [Twig]; o acesso ao banco de dados é feito pelo [Doctrine].
Três papéis de usuário compartilham a aplicação:
ADMIN | o administrador ([admin]) | ver as agendas, marcar e cancelar consultas para qualquer paciente; gerenciar (listar, adicionar, editar, excluir) médicos e clientes |
DOCTOR | Médicos | Ver as agendas, marcar consultas e cancelar consultas de qualquer paciente |
USER | clientes (pacientes) | ver as agendas sem ver os nomes de outros pacientes; marcar uma consulta para si mesmos; cancelar a própria consulta; gerenciar a própria conta; criar uma conta |
Principais regras de gerenciamento:
- nenhuma consulta no passado;
- um horário só pode ser reservado uma vez por dia;
- um paciente só pode ter 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 resolver primeiro o CAPTCHA dessa página.
11.2. Uso da aplicação
11.2.1. A página de login

A página tem dois botões: Log in e Create a patient account. Ambos exigem que você digite os caracteres mostrados na imagem. Os botões FR / EN mudam o idioma:

Um erro (neste caso, um CAPTCHA digitado incorretamente) é exibido no final da página, sobre um fundo rosa-claro:

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:


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

Após a marcação, uma mensagem confirma a consulta:

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

11.2.3. O portal do paciente
Um paciente (papel USER) chega a “My area”: 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 uma consulta:

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

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


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

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

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:

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

11.2.4. Gerenciamento de médicos e pacientes
O administrador tem dois menus adicionais, Doctors e Patients:


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

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 letras maiúsculas e minúsculas nem acentos; veja o exemplo 28):

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

11.2.5. Criação de uma conta de paciente
Na página de login, o botão “Create a patient account” só abre o formulário se o CAPTCHA tiver sido digitado corretamente:

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

11.2.6. Logout
O token de login é válido por duas horas. Passado esse tempo (ou se o token tiver sido adulterado), a página solicitada redireciona para a página de login com a seguinte mensagem:

11.3. Instalação e execução
A aplicação está na pasta [rdvmedecins2-symfony], ao lado da pasta [examples]. É um projeto autônomo, 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]; aqui vamos aprofundá-la.
11.3.1. Software necessário
Três programas são tudo de que você precisa:
- [PHP] 8.4 ou posterior, com as extensões [pdo_mysql] e [intl] (o [Symfony] 8 exige o [PHP] 8.4, e a aplicação usa recursos introduzidos nessa versão, como [array_find]). Verifique a instalação em um terminal:
O segundo comando lista as extensões: [pdo_mysql] e [intl] devem constar da lista;
- [Composer], o gerenciador de bibliotecas do [PHP] (veja os apêndices);
- um [MySQL] 8 servidor, por exemplo, o do [Laragon] no [Windows] (veja os apêndices). [MariaDB] também serve.
O editor recomendado é o [Visual Studio Code], com as extensões [PHP Intelephense] e [Twig Language 2] (veja os apêndices); no entanto, tudo pode ser feito pela linha de comando.
11.3.2. Instale as bibliotecas
A pasta [vendor] não é fornecida: crie-a uma vez por todas em uma janela de terminal aberta na pasta [rdvmedecins2-symfony] (você precisa estar conectado à Internet):
[Composer] lê o arquivo [composer.json] (discutido adiante), baixa [Symfony], [Doctrine], [Twig], [firebase/php-jwt] e as bibliotecas das quais dependem, e gera o carregador de classes [vendor/autoload.php], bem como o arquivo [vendor/autoload_runtime.php] do componente [Runtime] (discutido adiante).
11.3.3. Crie o banco de dados
O banco de dados [dbrdvmedecins2] é criado pelo script [database/dbrdvmedecins2.sql]. Com o [Laragon], abra a ferramenta [HeidiSQL] (botão Database) e execute o script pelo menu File / Run SQL. Na linha de comando, na pasta da aplicação:
| mysql -u root -p < database/dbrdvmedecins2.sql
|
A opção [-p] solicita a senha de [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.
Toda a configuração da instalação está no arquivo [.env] (discutido adiante). Por padrão, a aplicação se conecta ao [MySQL] em [127.0.0.1], porta 3306, usando o usuário [root] sem senha: essas são as configurações padrão do [Laragon]. Se a sua conta [root] tiver senha, digite-a neste arquivo, na linha da URL [DATABASE_URL], após [root:]. Uma variável de ambiente do sistema tem precedência sobre o arquivo (exemplo 25): isso permite informar a URL do banco de dados sem gravá-la em um arquivo do projeto.
11.3.5. Inicie a aplicação
Em uma janela de terminal aberta na pasta [rdvmedecins2-symfony]:
| php -S localhost:8081 -t public
|
| [Sun Sep 27 18:40:12 2026] PHP 8.4.21 Development Server (http://localhost:8081) started
|
Em seguida, abra a URL [http://localhost:8081] em um navegador e encerre a aplicação com [Ctrl-C]. A porta 8081 permite executar ao mesmo tempo um exemplo do curso (porta 8000). A ferramenta de linha de comando [symfony] (veja os apêndices) oferece um servidor mais completo, que também pode servir a aplicação em HTTPS: [symfony server:start --port=8081].
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]: Schedule, Sra. Marie PELISSIER; hoje: um horário já está reservado pela Sra. Brigitte BISTROU. Reserve um horário para o Sr. Jean MARTIN e, em seguida, tente marcar uma segunda consulta para ele (recusada). Menus Doctors e Patients: 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]: My area, sua consulta, o calendário em que os outros pacientes aparecem como “Booked”; Manage my account;
- página de login: Create a patient account e, em seguida, faça 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 ([APP_ENV=dev]):
- O console do servidor exibe o log do [Symfony] (exemplo 24): a rota selecionada, as etapas de segurança e cada comando SQL enviado ao banco de dados (exemplo 28). Por exemplo, para exibir um calendário (linhas abreviadas):
| [info] Matched route "schedule".
[debug] Checking for authenticator support.
[debug] Checking support on authenticator.
[info] Authenticator successful!
[debug] Authenticator set no success response: request continues.
[info] Connecting with parameters [array]
[debug] Executing statement: SELECT d0_.id AS id_0, ..., u1_.login AS login_7, ... FROM doctors d0_ INNER JOIN users u1_ ON d0_.`user` = u1_.`id` WHERE d0_.id = ? (parameters: [array], types: [array])
[debug] Executing statement: SELECT a0_.id AS id_0, ... FROM appointments a0_ INNER JOIN clients c1_ ON a0_.client_id = c1_.id INNER JOIN slots s2_ ON a0_.slot_id = s2_.id WHERE a0_.day = ? AND s2_.doctor_id = ? (parameters: [array], types: [array])
[debug] Executing statement: SELECT s0_.id AS id_0, ... FROM slots s0_ WHERE s0_.doctor_id = ? ORDER BY s0_.start_hour ASC, s0_.start_minute ASC (parameters: [array], types: [array])
127.0.0.1:55220 [200]: GET /schedule?doctorId=1&day=2026-09-27
[info] Disconnecting
|
Aqui vemos o roteamento, o autenticador e, em seguida, três consultas: o médico e sua conta, as consultas de hoje e seus pacientes, e os horários disponíveis do médico. A lista de médicos no menu suspenso, no entanto, não é lida; ela vem do cache (discutido adiante);
- uma exceção inesperada exibe a página de depuração do [Symfony] (exemplo 03), com 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, no modo [dev], o [Symfony] reconstrói seu próprio cache (o contêiner, as rotas e as views compiladas) quando um arquivo é alterado.
O [Xdebug] depurador também permite executar a aplicação passo a passo a partir do [Visual Studio Code] (extensão [PHP Debug]): é uma extensão do [PHP], que deve ser instalada separadamente (veja xdebug.org). A barra de depuração do [Symfony] ([WebProfilerBundle], [composer require --dev symfony/web-profiler-bundle]) exibe os detalhes da requisição na parte inferior de cada página: a rota, o usuário, os comandos SQL e seus parâmetros, as traduções, os tempos de execução...
11.3.8. Um servidor de produção
O servidor de desenvolvimento do [PHP] não se destina à produção. Em produção, a aplicação é servida por um servidor web ([nginx], [Apache]), que encaminha 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; a pasta [var] deve ter permissão de escrita para o servidor. No arquivo [.env], é preciso especificar o modo de produção, alterar as chaves secretas e declarar que o site é servido por HTTPS:
| APP_ENV=prod
APP_SECRET=<a long random string>
JWT_SECRET=<another long random string>
COOKIE_SECURE=1
|
Uma string aleatória adequada pode ser obtida do próprio [PHP] : [php -r "echo bin2hex(random_bytes(32));"]. A aplicação é então preparada com dois comandos:
| composer install --no-dev --optimize-autoloader
php bin/console cache:clear
|
O segundo comando gera o cache de produção (o contêiner compilado, as rotas, as views compiladas etc.): no modo [prod], o [Symfony] não verifica mais se os arquivos mudaram, o que é mais rápido; portanto, ele deve ser executado novamente após cada modificação. O comando [composer dump-env prod] também converte o arquivo [.env] em um arquivo [PHP] ([.env.local.php]), que é lido mais rapidamente.
11.3.9. Problemas comuns
Uma aplicação [PHP] não “inicia”: cada requisição reconstrói a aplicação (exemplo 01). Um banco de dados inacessível, portanto, não impede o servidor de iniciar: o erro aparece na primeira página que consulta o banco de dados (a página de login não consulta o banco de dados; o processo de conexão, sim). No modo [dev], o erro é exibido na página de depuração do [Symfony]; em todos os casos, ele é registrado no arquivo de log, que o servidor de desenvolvimento exibe no console. Por exemplo, com um banco de dados que não existe:
| [critical] Uncaught PHP Exception Doctrine\DBAL\Exception\ConnectionException: "An exception occurred in the driver: SQLSTATE[HY000] [1049] Unknown database 'dbunknown'" at ExceptionConverter.php line 91
|
As mensagens mais comuns:
[Failed opening required '.../vendor/autoload_runtime.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 em [DATABASE_URL] (veja “Configure o acesso ao banco de dados”) |
[SQLSTATE[HY000] [1049] Unknown database 'dbrdvmedecins2'] | O script [database/dbrdvmedecins2.sql] não foi executado |
[JWT_SECRET must be at least 32 characters long (see .env).] | A chave secreta dos tokens é curta demais em [.env] |
[Failed to listen on localhost:8081 (reason: Address already in use)] | A porta 8081 já está em uso (outra versão da aplicação está em execução?): encerre-a ou escolha outra porta |
11.4. Arquitetura da aplicação

- O navegador envia suas requisições ao servidor ([php -S], ou [nginx] + [PHP-FPM]), que as encaminha ao [Symfony] por meio do arquivo [public/index.php]. O núcleo do [Symfony] publica eventos relacionados ao processamento da requisição (veja o capítulo sobre o ciclo de vida), aos quais os listeners respondem: o idioma da requisição ([SetLanguage]), o roteamento, a sessão e, em seguida, o firewall do componente de segurança: o usuário é identificado com base no token JWT de seu cookie ([TokenAuthenticator]), e as regras [access_control] negam o acesso às páginas protegidas aos visitantes não autorizados. Os erros resultam em páginas HTML ([ErrorPage]);
- [Controller]: os controllers da camada web. Todos passam por um único objeto, [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; [Form]: formulários e suas restrições; [Views]: templates das views;
- [Security]: tokens, JWT, o autenticador, o CAPTCHA, o limite 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], a classe pai dos controllers, as mensagens flash e alguns utilitários;
- [Business]: regras de negócio e transações;
- [Dao]: a camada DAO, uma classe por tabela;
- [Entity]: as entidades [Doctrine], que a camada DAO lê do banco de dados e grava nele; [Domain]: os objetos da agenda, calculados pela camada de negócio;
- [templates]: as views [Twig], que geram as páginas HTML; [translations]: os dicionários; [public]: a folha de estilos, o script da página e o [Bootstrap];
- a pasta [config] e o arquivo [.env]: a configuração, que reúne tudo.
A pasta da aplicação (exceto [vendor] e [var]):
| rdvmedecins2-symfony/
├── bin/
│ └── console
├── composer.json
├── config/
│ ├── bundles.php
│ ├── packages/
│ │ ├── doctrine.yaml
│ │ ├── framework.yaml
│ │ ├── security.yaml
│ │ └── twig.yaml
│ ├── routes.yaml
│ └── services.yaml
├── database/
│ ├── dbrdvmedecins2.sql
│ └── README.md
├── .env
├── public/
│ ├── css/
│ │ └── styles.css
│ ├── index.php
│ ├── js/
│ │ └── app.js
│ └── lib/
│ └── bootstrap/
├── README.md
├── src/
│ ├── Controller/
│ │ ├── ScheduleController.php
│ │ ├── AuthController.php
│ │ ├── ClientsController.php
│ │ ├── PatientAreaController.php
│ │ ├── RegistrationController.php
│ │ ├── LanguageController.php
│ │ ├── DoctorsController.php
│ │ ├── PersonsController.php
│ │ └── README.md
│ ├── Dao/
│ │ ├── ClientDao.php
│ │ ├── SlotDao.php
│ │ ├── DoctorDao.php
│ │ ├── PersonDao.php
│ │ ├── README.md
│ │ ├── AppointmentDao.php
│ │ └── UserDao.php
│ ├── Domain/
│ │ ├── DoctorDaySchedule.php
│ │ ├── DoctorDaySlot.php
│ │ └── README.md
│ ├── Entity/
│ │ ├── Client.php
│ │ ├── Slot.php
│ │ ├── Doctor.php
│ │ ├── Person.php
│ │ ├── README.md
│ │ ├── Role.php
│ │ ├── Appointment.php
│ │ └── User.php
│ ├── EventListener/
│ │ ├── SetLanguage.php
│ │ ├── ErrorPage.php
│ │ ├── README.md
│ │ └── CheckRegistrationPass.php
│ ├── Form/
│ │ ├── PersonFieldsType.php
│ │ ├── RegistrationType.php
│ │ ├── MyAccountType.php
│ │ ├── PersonType.php
│ │ └── README.md
│ ├── Kernel.php
│ ├── Business/
│ │ ├── Dates.php
│ │ ├── Descriptor.php
│ │ ├── PersonData.php
│ │ ├── Business.php
│ │ ├── BusinessException.php
│ │ ├── BusinessService.php
│ │ └── README.md
│ ├── Security/
│ │ ├── AuthService.php
│ │ ├── Captcha.php
│ │ ├── CaptchaService.php
│ │ ├── CaptchaDrawing.php
│ │ ├── TokenAuthenticator.php
│ │ ├── AttemptLimiter.php
│ │ ├── RegistrationPass.php
│ │ ├── RegistrationPassRequired.php
│ │ ├── README.md
│ │ ├── InvalidSession.php
│ │ └── ConnectedUser.php
│ ├── Twig/
│ │ └── ViewsExtension.php
│ ├── Views/
│ │ ├── ScheduleView.php
│ │ ├── PersonKeys.php
│ │ ├── ScheduleRow.php
│ │ ├── OptionView.php
│ │ ├── README.md
│ │ ├── AppointmentView.php
│ │ └── BookingView.php
│ └── Web/
│ ├── ApplicationModel.php
│ ├── BaseController.php
│ ├── Flash.php
│ ├── Message.php
│ ├── Utils.php
│ └── README.md
├── templates/
│ ├── schedule.html.twig
│ ├── account.html.twig
│ ├── error.html.twig
│ ├── area.html.twig
│ ├── fragments/
│ │ ├── captcha.html.twig
│ │ ├── confirmation.html.twig
│ │ ├── errors.html.twig
│ │ ├── navbar.html.twig
│ │ ├── booking.html.twig
│ │ └── success.html.twig
│ ├── registration.html.twig
│ ├── layout.html.twig
│ ├── login.html.twig
│ ├── macros.html.twig
│ ├── persons/
│ │ ├── form.html.twig
│ │ └── list.html.twig
│ └── README.md
└── translations/
├── messages+intl-icu.en.yaml
└── messages+intl-icu.fr.yaml
|
Esta é a estrutura de uma aplicação [Symfony] padrão — a que é criada pelo comando [composer create-project symfony/skeleton] (Exemplo 01) — complementada com os bundles de que a aplicação precisa. 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 seu ponto de entrada usa o componente [Runtime] do [Symfony] (tratado adiante). As classes da aplicação estão organizadas na pasta [src], segundo a regra PSR-4 (exemplo 01): a classe [App\Business\BusinessService] está no arquivo [src/Business/BusinessService.php]. O [Symfony] não exige nenhuma destas pastas: [Controller], [Entity], [EventListener], [Form] e [Twig] são as de uso corrente (as usadas pelo [MakerBundle]), enquanto as demais ([Dao], [Business], [Security]...) fazem parte da arquitetura em camadas do Exemplo 28. [Bootstrap] faz parte da aplicação desta vez (pasta [public/lib/bootstrap]): o estudo de caso é autossuficiente.
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 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): cada médico e cada 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 vale para os clientes.
-- Atenção: o collation utf8mb4_unicode_ci compara sem distinguir
-- maiúsculas de minúsculas nem 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 "pai"
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 agendado 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 supor 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 imediatamente 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 diferenciar maiúsculas de minúsculas nem acentos (exemplo 28);
- linhas 37–41: as tabelas são descartadas e depois recriadas; o script restaura o banco de dados ao estado inicial. A ordem importa: uma tabela não pode ser descartada enquanto outra tabela a referenciar por meio de uma chave estrangeira;
- Linhas 46–55: Users: um nome de usuário e uma senha com hash gerado com [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 da linguagem SQL, ela vem entre crases. 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 término são armazenados em horas e minutos;
- linhas 108–118: uma consulta é composta de um dia (tipo [DATE], sem hora), 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 impõe essa regra, mesmo que dois usuários tentem reservá-lo ao mesmo tempo;
- linhas 130–140: usuários de demonstração, cuja senha é o próprio 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] gera os seus com o prefixo [$2y$], mas verifica ambos igualmente bem;
- linhas 144–147: a coluna [user] de cada médico é obtida por meio de 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 do Dr. PELISSIER para a Sra. BISTROU: assim, a agenda já mostra imediatamente um horário reservado.
Ao contrário do que ocorre com o [Symfony], o banco de dados não é criado pelo [Doctrine] a partir das entidades, nem por meio de migrações (exemplo 28): ele é compartilhado com as outras versões da aplicação, e o script SQL é comum a todas elas. O comando [php bin/console doctrine:schema:validate] verifica se as descrições das entidades são consistentes e se correspondem às tabelas do banco de dados.
11.6. A configuração do projeto
11.6.1. composer.json
| {
"name": "rdvmedecins/rdvmedecins2-symfony",
"description": "RdvMedecins: booking medical appointments, HTML pages built by the server (Symfony + Twig + Doctrine)",
"type": "project",
"license": "MIT",
"require": {
"php": ">=8.4",
"ext-intl": "*",
"ext-pdo_mysql": "*",
"doctrine/doctrine-bundle": "^3.3",
"doctrine/orm": "^3.7",
"firebase/php-jwt": "^7.2",
"symfony/asset": "^8.1",
"symfony/console": "^8.1",
"symfony/dotenv": "^8.1",
"symfony/form": "^8.1",
"symfony/framework-bundle": "^8.1",
"symfony/lock": "^8.1",
"symfony/rate-limiter": "^8.1",
"symfony/runtime": "^8.1",
"symfony/security-bundle": "^8.1",
"symfony/translation": "^8.1",
"symfony/twig-bundle": "^8.1",
"symfony/validator": "^8.1",
"symfony/yaml": "^8.1",
"twig/twig": "^3.30"
},
"autoload": {
"psr-4": {
"App\\": "src/"
}
},
"config": {
"allow-plugins": {
"symfony/runtime": true
},
"optimize-autoloader": true,
"sort-packages": true
},
"minimum-stability": "stable",
"prefer-stable": true
}
|
- Linhas 6–27: as bibliotecas exigidas pela aplicação e as restrições que devem atender. [^8.1] lê-se “versão 8.1 ou uma versão mais recente da mesma versão principal 8”: o [Composer] aceita versões que corrigem bugs ou acrescentam funcionalidades, mas não as que poderiam quebrar a aplicação (versão 9). As linhas [php], [ext-intl] e [ext-pdo_mysql] não se referem a bibliotecas, mas a requisitos do ambiente: o [Composer] recusará a instalação se a versão do [PHP] ou de suas extensões for incompatível, em vez de deixar a aplicação falhar mais tarde. O [Symfony] não é uma biblioteca única: cada um de seus componentes (roteamento, formulários, segurança etc.) é uma biblioteca, e a aplicação solicita apenas os de que precisa; o [Composer] instala, além disso, as bibliotecas das quais eles dependem;
- Linhas 28–32: a regra PSR-4 da aplicação: as classes do namespace [App] ficam na pasta [src] (Exemplo 01: nos exemplos, o próprio arquivo [public/index.php] declarava essa regra ao carregador de classes por meio de [addPsr4]);
- Linhas 34–36: o componente [Runtime] é um plugin (plugin) do [Composer]; ele é executado durante a instalação para gravar o arquivo [vendor/autoload_runtime.php]. [Composer] pede permissão para executar o código de um plugin; aqui essa permissão é concedida.
[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: instalam exatamente as mesmas versões. [composer update], por outro lado, procura as versões mais recentes permitidas por [composer.json] e atualiza o [composer.lock]. O comando [composer show] lista o que está instalado na pasta [vendor]. Em um projeto típico, esse arquivo é complementado pelo [Symfony Flex] a cada [composer require] (exemplo 01).
11.6.2. .env
| # =========================================================================
# .env: as configurações específicas DESTA instalação, lidas no início de cada
# requisição pelo componente Dotenv (veja public/index.php). Elas viram
# variáveis de ambiente, que a configuração (pasta config) lê por meio de
# %env(NAME)%. Uma variável de ambiente real do sistema tem precedência sobre este arquivo.
# =========================================================================
# dev: desenvolvimento; prod: produção (veja README.md)
APP_ENV=dev
# A chave secreta do Symfony (tokens anti-CSRF, assinaturas...). Em produção:
# outro valor, longo e aleatório
APP_SECRET=34b2364cc4c93df6e4ee35251a048088
# Banco de dados MySQL [dbrdvmedecins2] (script: database/dbrdvmedecins2.sql):
# o SGBD, o usuário e sua senha (os do Laragon: root, sem
# senha), o servidor, sua porta, o banco de dados, depois a versão do servidor (para MariaDB:
# serverVersion=10.11.2-MariaDB, por exemplo) e o conjunto de caracteres
DATABASE_URL="mysql://root:@127.0.0.1:3306/dbrdvmedecins2?serverVersion=8.0.32&charset=utf8mb4"
# Autenticação (veja src/Security/AuthService.php)
# chave secreta dos tokens JWT: pelo menos 32 caracteres (HMAC-SHA256)
JWT_SECRET=ef1cfc9709f10b5b5d183b4deb6d5dbbe69518629c3b12a8
# duração de validade de um token, em minutos (120 min = 2 h)
JWT_DURATION_MINUTES=120
# 1 em produção (site servido por HTTPS): os cookies nunca trafegam sem criptografia
COOKIE_SECURE=0
# Proteção contra robôs (veja src/Security/AttemptLimiter.php)
# falhas de login permitidas para o mesmo login a partir do mesmo endereço IP, depois
# bloqueio por esta duração (em minutos); um endereço IP também é bloqueado se
# acumular LOGIN_MAX_FAILURES_IP falhas, todos os logins juntos (um robô que tenta
# milhares de logins diferentes)
LOGIN_MAX_FAILURES=5
LOGIN_MAX_FAILURES_IP=25
LOGIN_BLOCK_MINUTES=15
# contas de clientes criadas no máximo 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=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 confidenciais (as chaves). Em um projeto real, os segredos de produção não são incluídos aqui: eles são fornecidos por variáveis de ambiente reais, por um arquivo [.env.local] que nunca é publicado, ou pelo cofre de segredos do [Symfony] (exemplo 25).
- linha 9: o modo da aplicação: [dev] (desenvolvimento: modo de depuração, página de depuração, cache reconstruído a cada alteração) ou [prod];
- linha 12: a chave secreta do [Symfony], usada em particular para os tokens anti-CSRF (exemplo 21);
- linha 18: a conexão com o banco de dados (exemplo 28);
- linhas 20–38: configurações específicas da aplicação: os tokens JWT (exemplo 25) e a proteção contra bots (exemplo 27).
11.6.3. config/bundles.php e config/packages/framework.yaml
| <?php
// config/bundles.php: os bundles da aplicação (veja o exemplo 01): o núcleo do
// Symfony, as views Twig, a segurança e o Doctrine (acesso ao banco de dados)
return [
Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true],
Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true],
];
|
Os quatro bundles da aplicação: o núcleo do [Symfony], o [Twig] (Exemplo 13), a segurança (Exemplo 25) e o [Doctrine] (Exemplo 28).
| # =========================================================================
# config/packages/framework.yaml: a configuração do FrameworkBundle
# =========================================================================
framework:
secret: '%env(APP_SECRET)%'
# Os idiomas (veja o exemplo 22): inglês por padrão, francês; o
# serviço de tradução e seus dicionários (pasta translations)
default_locale: en
enabled_locales: ['en', 'fr']
translator:
default_path: '%kernel.project_dir%/translations'
fallbacks: ['en']
# Validação de formulários: suas mensagens são CHAVES de nossos
# dicionários (ERRORS.FIRSTNAME_REQUIRED...), traduzidas no domínio
# [messages], o mesmo das views (por padrão: o domínio [validators])
validation:
translation_domain: messages
# A SESSÃO (mensagens flash, tokens anti-CSRF): arquivos da pasta
# var/sessions. O cookie de sessão nunca é legível pelo JavaScript da
# página (httponly), nem enviado com uma requisição POST vinda de outro site
# (samesite lax), nem, em produção, enviado sem criptografia (secure)
session:
handler_id: null
save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
name: rdvmedecins_session
cookie_httponly: true
cookie_samesite: lax
cookie_secure: '%env(bool:COOKIE_SECURE)%'
csrf_protection: true
# Os locks (veja o exemplo 20), para os limiters de tentativas
lock: 'flock://%kernel.project_dir%/var/lock'
# Os LIMITERS de tentativas (veja o exemplo 27 e src/Security/AttemptLimiter.php).
# fixed_window: no máximo [limit] tentativas por período [interval], contadas
# a partir da primeira tentativa
rate_limiter:
# as falhas de login de um login, a partir de um endereço IP
login:
policy: fixed_window
limit: '%env(int:LOGIN_MAX_FAILURES)%'
interval: '%env(LOGIN_BLOCK_MINUTES)% minutes'
# as falhas de login de um endereço IP, todos os logins juntos
login_ip:
policy: fixed_window
limit: '%env(int:LOGIN_MAX_FAILURES_IP)%'
interval: '%env(LOGIN_BLOCK_MINUTES)% minutes'
# as contas criadas a partir de um endereço IP, por hora
registration:
policy: fixed_window
limit: '%env(int:REGISTRATION_MAX_PER_HOUR)%'
interval: '1 hour'
|
- linhas 9–13: idiomas e o tradutor (Exemplo 22);
- linhas 18–19: o componente de validação traduz suas mensagens no domínio [validators] (exemplo 09); nossas restrições usam como chaves de mensagem as chaves de nossos dicionários ([ERRORS.FIRSTNAME_REQUIRED]...), que estão no domínio [messages]: informamos isso ao componente de validação. Assim, um único dicionário por idioma basta para toda a aplicação;
- linhas 25–32: a sessão (exemplo 20): arquivos na pasta [var/sessions]. A aplicação armazena muito pouco ali: mensagens flash e tokens anti-CSRF. O cookie de sessão se chama [rdvmedecins_session]; ele nunca é legível pelo [JavaScript] da página, nem é enviado com uma requisição POST originada em outro site, nem, em produção, enviado em texto simples (o prefixo [bool:] converte a variável em booleano, exemplo 25);
- linha 35: os locks (exemplo 20), usados pelos limitadores de tentativas e pelo serviço de CAPTCHA;
- linhas 40–55: os três limitadores antibot (exemplo 27), cujas configurações vêm do arquivo [.env]. Um valor pode combinar texto e uma variável: ['%env(LOGIN_BLOCK_MINUTES)% minutes'].
O cache da aplicação (o serviço [cache.app], Exemplo 20) não precisa ser configurado: ele é armazenado em arquivos na pasta [var/cache/dev/pools] (ou [prod]). A aplicação armazena ali as listas de médicos e clientes, CAPTCHAs, contadores de tentativas e passes — tudo o que precisa ser compartilhado entre todas as requisições. Com vários servidores, escolheríamos um cache compartilhado, como o [Redis] ([framework.cache.app: cache.adapter.redis]).
11.6.4. config/packages/security.yaml
| # =========================================================================
# config/packages/security.yaml: segurança (veja os exemplos 25 e 26)
# =========================================================================
security:
# o hash das senhas das contas: bcrypt, 10 rounds, como os
# hashes do script SQL. O PHP também verifica os hashes $2b$ (Python) e $2a$
# (Java) das outras versões da aplicação, que compartilham o mesmo banco de dados
password_hashers:
App\Entity\User:
algorithm: bcrypt
cost: 10
# o provider de usuários: irrelevante aqui, o usuário conectado é
# descrito por seu token (veja src/Security/TokenAuthenticator.php); o Symfony
# exige mesmo assim um: uma lista vazia
providers:
none:
memory: ~
firewalls:
# UM firewall para toda a aplicação, STATELESS: o usuário não é
# armazenado na sessão, ele é reencontrado a cada requisição a partir do
# token JWT de seu cookie
main:
stateless: true
provider: none
custom_authenticators:
- App\Security\TokenAuthenticator
# ---------------------------------------------------------------------
# A REGRA DE ACESSO: as regras são examinadas em ordem, a primeira cujo
# pattern (caminho) corresponde ao caminho da URL se aplica:
# - algumas URLs PÚBLICAS (PUBLIC_ACCESS): a página inicial, o login, a
# escolha do idioma, a criação de uma conta;
# - URLs reservadas a certos papéis (uma lista de papéis: UM deles basta);
# - todas as OUTRAS exigem um usuário autenticado (última regra).
# É a regra "tudo é proibido, exceto o que é permitido": uma URL adicionada
# depois, e que se tenha esquecido de proteger, fica protegida por padrão.
# Um visitante anônimo recusado é enviado à página de login (o entry
# point do firewall); um usuário autenticado sem o papel solicitado
# recebe uma página de erro 403.
# ---------------------------------------------------------------------
access_control:
- { path: ^/$, roles: PUBLIC_ACCESS }
- { path: ^/(login|logout)$, roles: PUBLIC_ACCESS }
- { path: ^/language/, roles: PUBLIC_ACCESS }
- { path: ^/register, roles: PUBLIC_ACCESS }
# um paciente cancela SUA consulta em "Minha área", não na agenda
- { path: ^/schedule/cancel$, roles: [ROLE_ADMIN, ROLE_DOCTOR] }
- { path: ^/(doctors|clients), roles: ROLE_ADMIN }
- { path: ^/my-, roles: ROLE_USER }
- { path: ^/, roles: IS_AUTHENTICATED }
|
Configuração de segurança (exemplos 25 e 26):
- Linhas 8–11: hash de senhas: [bcrypt], 10 rounds, como os hashes do script SQL. Para verificar uma senha, o [PHP] lê o algoritmo e o custo no próprio hash: os hashes do banco de dados, gerados pelo [Python] ([$2b$]) ou pelo [Java] ([$2a$]), são verificados da mesma forma que os do [PHP] ([$2y$]);
- linhas 16–18: o provedor de usuários. O autenticador da aplicação não precisa de um: o usuário conectado é identificado por seu token, sem leitura do banco de dados (exemplo 25). Mas o componente de segurança exige um: um provedor [memory], sem usuários;
- linhas 24–28: um único firewall stateless para toda a aplicação, com o nosso autenticador. Sem padrão ([pattern]): ele cobre todas as URLs. Os arquivos da pasta [public] ([Bootstrap], a folha de estilos, o script) não passam pelo [Symfony]: o servidor web os serve diretamente;
- Linhas 43–52: as regras de acesso da aplicação. As regras [access_control] são avaliadas em ordem, e é aplicada a primeira cujo padrão corresponde ao caminho da URL. [PUBLIC_ACCESS] concede acesso à URL a todos, inclusive a visitantes anônimos: a página inicial, o login, a seleção de idioma e a criação de conta. Em seguida vêm as regras de URLs reservadas a determinados papéis: uma lista de papéis (linha 49) significa que basta qualquer um deles. A última regra, [^/], aplica-se a todas as demais URLs e exige um usuário autenticado. Essa é a regra “tudo é proibido, exceto o que é permitido”: uma URL adicionada depois — mesmo que você se esqueça de protegê-la — fica automaticamente protegida. O erro oposto — uma URL pública deixada sem proteção por acidente — salta aos olhos imediatamente; o erro de uma página protegida esquecida é bem menos perceptível.
Os papéis são verificados aqui, em um único arquivo, por meio de padrões de URL, em vez de atributos [#[IsGranted]] nas actions (exemplo 26): ambas as formas são possíveis e podem ser combinadas.
11.6.5. config/packages/doctrine.yaml, twig.yaml, config/routes.yaml
| # config/packages/doctrine.yaml: Doctrine, acesso ao banco de dados (veja o exemplo 28)
doctrine:
# a conexão: a DATABASE_URL do arquivo .env. Em modo de depuração, cada instrução
# SQL é escrita no log, que o servidor de desenvolvimento exibe
dbal:
url: '%env(resolve:DATABASE_URL)%'
# as ENTIDADES: as classes da pasta src/Entity, descritas por atributos PHP
orm:
mappings:
App:
type: attribute
dir: '%kernel.project_dir%/src/Entity'
prefix: 'App\Entity'
|
A configuração do [Doctrine] é a mostrada no Exemplo 28.
| # config/packages/twig.yaml: as views Twig (pasta templates)
twig:
default_path: '%kernel.project_dir%/templates'
# os formulários são desenhados com as classes do Bootstrap 5 (veja o exemplo 18)
form_themes: ['bootstrap_5_layout.html.twig']
|
Os campos dos formulários são desenhados com as classes do [Bootstrap] 5 (Exemplo 18).
| # config/routes.yaml: as rotas são descritas pelos atributos #[Route] dos
# controllers da pasta src/Controller (veja o exemplo 01)
controllers:
resource: routing.controllers
|
As rotas são descritas pelos atributos [#[Route]] dos controllers (Exemplo 01). O comando [php bin/console debug:router] lista todas elas (veja adiante, a camada web).
11.7. Para iniciar a aplicação
11.7.1. public/index.php e bin/console
| <?php
// public/index.php: o ponto de entrada de TODAS as requisições HTTP. A pasta
// [public] é a raiz do site: apenas seus arquivos são acessíveis a partir do
// navegador (Bootstrap, folha de estilo, script), nunca o código da aplicação.
//
// O arquivo vendor/autoload_runtime.php é escrito pelo componente Runtime do Symfony
// (a biblioteca symfony/runtime): ele carrega as classes, lê o arquivo
// .env, ativa o modo de depuração e depois chama a função abaixo, que retorna o
// kernel da aplicação; por fim, faz com que ele trate a requisição atual, envie a
// resposta e encerre a requisição (veja o arquivo index.php dos exemplos)
use App\Kernel;
require_once dirname(__DIR__).'/vendor/autoload_runtime.php';
return function (array $context) {
return new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
};
|
O ponto de entrada dos exemplos (Exemplo 01) carregava as classes, lia o arquivo [.env], ativava o modo de depuração, criava o núcleo, fazia-o processar a requisição, enviava a resposta e encerrava a requisição. Tudo isso é feito aqui pelo componente [Runtime] do [Symfony] (linha 14): esta é a forma do arquivo [public/index.php] em uma aplicação [Symfony] padrão.
- Linha 14: o arquivo [vendor/autoload_runtime.php], gerado pelo [Composer] (veja [composer.json]), carrega o carregador de classes e depois executa o script que o incluiu, neste caso [public/index.php], para obter seu valor de retorno: um arquivo [PHP] incluído pode retornar um valor ([return]), como uma função;
- Linhas 16–18: esse valor é uma função anônima que recebe o contexto da aplicação (as variáveis de ambiente, lidas de [.env] pelo componente [Runtime]) e retorna o núcleo. O componente [Runtime] cuida do resto: os objetos [Request], [handle], [send] e [terminate] .
A vantagem dessa abordagem é que o mesmo [index.php] funciona com servidores diferentes do [PHP-FPM]. Com o modo worker do [FrankenPHP] (veja a seção sobre escopos), por exemplo, um “runtime” diferente mantém o kernel na memória e o faz processar as requisições sequencialmente, sem que este arquivo mude. O arquivo [bin/console] tem a mesma estrutura: sua função cuida da execução de comandos, construída em torno do kernel.
11.7.2. src/Kernel.php e config/services.yaml
| <?php
// src/Kernel.php: o kernel da aplicação (veja o exemplo 01)
namespace App;
use Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait;
use Symfony\Component\HttpKernel\Kernel as BaseKernel;
class Kernel extends BaseKernel
{
use MicroKernelTrait;
public function boot(): void
{
parent::boot();
// o fuso horário: o do consultório médico. Ele define a data de hoje (nenhuma
// consulta no passado, veja src/Business/Dates.php)
date_default_timezone_set('Europe/Paris');
}
}
|
O núcleo dos exemplos (Exemplo 01), com um método adicional:
- linhas 13–19: [boot] é chamado quando o kernel inicia, a cada requisição. Ele define o fuso horário do [PHP]. Por padrão, o [PHP] opera no fuso horário especificado em sua configuração ([date.timezone], no arquivo [php.ini]), que costuma ser o Tempo Universal Coordenado (UTC); no entanto, a data atual é usada em uma regra de negócio: sem consultas no passado. Em Paris, entre a meia-noite e as 2h da manhã no verão, o dia em UTC ainda é o dia anterior: o fuso horário do consultório prevalece.
| # =========================================================================
# config/services.yaml: os SERVIÇOS da aplicação (veja o exemplo 06). Todas as
# classes da pasta src/ são declaradas ao contêiner, que as cria sob demanda e
# dá a cada uma os objetos de que ela precisa (injeção de dependência): um
# controller recebe o ApplicationModel, que recebe a camada de negócio, que recebe os
# DAOs, que recebem o entity manager do Doctrine...
# Apenas um objeto de cada classe durante uma requisição.
# =========================================================================
services:
_defaults:
autowire: true
autoconfigure: true
App\:
resource: '../src/'
# Objetos de DADOS, criados pelo código (ou pelo Doctrine), nunca pelo
# contêiner: eles não são serviços
exclude:
- '../src/Entity/'
- '../src/Domain/'
- '../src/Views/'
- '../src/Kernel.php'
|
- Linhas 10–15: todas as classes da pasta [src] são serviços criados pelo contêiner, que fornece a cada uma os objetos que ela solicita em seu construtor (exemplo 06). Os serviços são compartilhados: um único [ApplicationModel], um único [BusinessService]... para toda a requisição (veja o capítulo sobre escopos);
- linhas 16–22: exceto as classes de dados: entidades criadas pelo [Doctrine] ou pela camada de negócio, objetos de agenda calculados e modelos de view criados pelas actions. Elas são excluídas: não são serviços. (Outras classes de dados, como [PersonData] ou [Message], são declaradas, mas, como ninguém as solicita ao contêiner, ele as descarta por conta própria.)
Não há mais nada a declarar: os listeners ([#[AsEventListener]]), os controllers ([#[Route]]), as extensões [Twig], os tipos de formulário e o autenticador são reconhecidos pelo contêiner com base em seus atributos ou em sua classe pai ([autoconfigure]) e configurados de acordo. O comando [php bin/console debug:container App] lista os serviços da aplicação.
11.8. As entidades
As entidades [Doctrine] (Exemplo 28): uma classe por tabela, na pasta [src/Entity].
11.8.1. src/Entity/Role.php
| <?php
// src/Entity/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 tal como está no banco de dados; Role::from('ADMIN') faz o caminho inverso.
namespace App\Entity;
enum Role: string
{
case ADMIN = 'ADMIN';
case DOCTOR = 'DOCTOR';
case USER = 'USER';
// o papel no sentido do Symfony (veja config/packages/security.yaml): ROLE_ADMIN...
public function symfonyRole(): string
{
return 'ROLE_'.$this->value;
}
}
|
Os três papéis, enumerados da seguinte forma ([enum], [PHP] 8.1): um tipo cujos únicos valores possíveis são 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 valores associados: cada caso tem um valor, neste caso a string de base. [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. Uma enumeração pode ter métodos: [symfonyRole()] (linhas 18–21) retorna o papel no formato definido pelo [Symfony], [ROLE_ADMIN], [ROLE_DOCTOR] ou [ROLE_USER] (exemplo 25) — o verificado pelas regras [access_control]. [$this] designa aqui o caso.
11.8.2. src/Entity/User.php
| <?php
// =========================================================================
// src/Entity/User.php: um usuário autorizado a fazer login (tabela [users]).
// Cada médico e cada cliente tem 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 src/Business/BusinessService.php).
//
// PasswordAuthenticatedUserInterface: um usuário que possui uma senha (com hash);
// é o que o serviço de hash do Symfony espera (veja AuthService).
// =========================================================================
namespace App\Entity;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
#[ORM\Entity]
#[ORM\Table(name: 'users')]
class User implements PasswordAuthenticatedUserInterface
{
#[ORM\Id]
#[ORM\GeneratedValue]
#[ORM\Column]
private ?int $id = null;
// o número de versão da linha: o bloqueio otimista (veja o exemplo 28)
#[ORM\Version]
#[ORM\Column(type: Types::INTEGER)]
private int $version = 0;
public function __construct(
#[ORM\Column(length: 30)]
private string $login,
// a senha com HASH (bcrypt), nunca a senha em si
#[ORM\Column(length: 100)]
private string $password,
// o nome exibido depois do login: "Marie PELISSIER"
#[ORM\Column(length: 40)]
private string $name,
// enumType: a coluna (um texto) vira um Role, e vice-versa
#[ORM\Column(length: 10, enumType: Role::class)]
private Role $role,
) {
}
public function getId(): ?int
{
return $this->id;
}
public function getVersion(): int
{
return $this->version;
}
public function getLogin(): string
{
return $this->login;
}
public function getPassword(): string
{
return $this->password;
}
public function getName(): string
{
return $this->name;
}
public function getRole(): Role
{
return $this->role;
}
public function setLogin(string $login): void
{
$this->login = $login;
}
public function setPassword(string $hash): void
{
$this->password = $hash;
}
public function setName(string $name): void
{
$this->name = $name;
}
}
|
- linhas 21–23: a entidade da tabela [users]. Ela implementa a interface [PasswordAuthenticatedUserInterface] do componente de segurança (Exemplo 25): é o que o serviço de hash de senhas espera;
- linhas 25–33: a chave primária e a versão, o bloqueio otimista (Exemplo 28);
- linhas 35–48: as demais colunas são declaradas no construtor por meio de promoção de construtor (Exemplo 03): os atributos [#[ORM\Column]] podem ser aplicados tanto a um parâmetro promovido quanto a uma propriedade. [length] especifica o tamanho das colunas [VARCHAR]. Linha 45: a opção [enumType] converte a coluna [role] (texto) em [Role] nas operações de leitura, e vice-versa nas de gravação: [$user->getRole()] retorna um [Role], nunca uma string;
- Linhas 50–93: os getters e três métodos setter. A chave primária e a versão não têm métodos setter: o [Doctrine] as mantém atualizadas.
11.8.3. src/Entity/Person.php
| <?php
// =========================================================================
// src/Entity/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 (uma "Person" nunca é criada), da qual
// Doctor e Client herdam; cada uma apenas especifica o nome de sua tabela.
// #[ORM\MappedSuperclass]: uma classe pai cujas colunas são as das
// entidades que herdam dela, mas que não tem tabela própria.
//
// Atenção: [Client] aqui significa 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\Entity;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;
#[ORM\MappedSuperclass]
abstract class Person
{
#[ORM\Id]
#[ORM\GeneratedValue]
#[ORM\Column]
protected ?int $id = null;
// bloqueio otimista (veja o exemplo 28)
#[ORM\Version]
#[ORM\Column(type: Types::INTEGER)]
protected int $version = 0;
public function __construct(
// Mr, Mme, Melle
#[ORM\Column(length: 5)]
protected string $title,
#[ORM\Column(name: 'last_name', length: 20)]
protected string $lastName,
#[ORM\Column(name: 'first_name', length: 20)]
protected string $firstName,
// -------------------------------------------------------------------
// A RELAÇÃO com a conta de usuário: uma pessoa tem UMA conta,
// designada pela chave estrangeira [user]. #[ORM\OneToOne]: uma conta por
// pessoa, uma pessoa por conta; #[ORM\JoinColumn]: a coluna da
// chave estrangeira (entre crases: `user` é uma palavra da linguagem
// SQL do MySQL). $doctor->getAccount() retorna um objeto User, lido do banco de dados no
// primeiro acesso - ou imediatamente pela consulta, se ela o pedir (veja src/Dao)
// -------------------------------------------------------------------
#[ORM\OneToOne]
#[ORM\JoinColumn(name: '`user`', nullable: false)]
protected User $account,
) {
}
public function getId(): ?int
{
return $this->id;
}
public function getVersion(): int
{
return $this->version;
}
public function getTitle(): string
{
return $this->title;
}
public function getLastName(): string
{
return $this->lastName;
}
public function getFirstName(): string
{
return $this->firstName;
}
public function getAccount(): User
{
return $this->account;
}
public function edit(string $title, string $lastName, string $firstName): void
{
$this->title = $title;
$this->lastName = $lastName;
$this->firstName = $firstName;
}
// "Mme Alice DURAND"
public function label(): string
{
return "{$this->title} {$this->firstName} {$this->lastName}";
}
}
|
As tabelas [doctors] e [clients] têm as mesmas colunas. A descrição comum é escrita uma só vez, em uma classe abstrata ([abstract class]): uma classe para a qual nunca se criam objetos, que serve apenas de classe base para herança. As classes [Doctor] e [Client] herdam dela.
- Linha 22: o atributo [#[ORM\MappedSuperclass]] faz da classe uma superclasse: suas colunas são as de cada uma das entidades que herdam dela, mas ela não tem tabela própria. (O [Doctrine] também oferece suporte a verdadeiras hierarquias de entidades, organizadas em uma única tabela ou em uma tabela por classe: não é o caso aqui, em que as duas tabelas são independentes.) As propriedades são [protected]: visíveis para as classes filhas;
- Linhas 51–53: o relacionamento com a conta. [#[ORM\OneToOne]]: uma pessoa tem uma conta, e uma conta pertence a no máximo uma pessoa. [#[ORM\JoinColumn]] refere-se à coluna da chave estrangeira, [user], e garante que ela não fique vazia ([nullable: false]). O nome da coluna vem entre crases: [user] é uma palavra da linguagem SQL do [MySQL], e o [Doctrine] a colocará entre crases dessa forma nos comandos SQL que escreve (veja a saída do console acima). A propriedade [account] é um objeto [User], não um número: essa é a finalidade de um ORM. Quando o [Doctrine] lê uma pessoa, ele também lê sua conta se a consulta assim exigir (carregamento lazy tardio; veja a camada DAO); caso contrário, coloca na propriedade um objeto lazy [User] (lazy), que só será lido do banco de dados no primeiro acesso a uma de suas propriedades — exceto o ID, que ele já conhece;
- linhas 87–92: modificação das três colunas de identidade;
- linhas 95–98: o nome de uma pessoa, “Ms. Alice DURAND”, usado por todas as páginas. Em uma string entre aspas, [{$this->title}] insere o valor de uma propriedade.
11.8.4. src/Entity/Doctor.php e Client.php
| <?php
// src/Entity/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\Entity;
use Doctrine\ORM\Mapping as ORM;
#[ORM\Entity]
#[ORM\Table(name: 'doctors')]
class Doctor extends Person
{
}
|
| <?php
// src/Entity/Client.php: um cliente, ou seja, um PACIENTE (tabela [clients]).
// Restrição de unicidade SQL: unq_clients_first_name_last_name.
namespace App\Entity;
use Doctrine\ORM\Mapping as ORM;
#[ORM\Entity]
#[ORM\Table(name: 'clients')]
class Client extends Person
{
}
|
Duas entidades que especificam apenas sua tabela: todo o resto é herdado. 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. src/Entity/Slot.php
| <?php
// src/Entity/Slot.php: um horário de um médico (tabela [slots]):
// 8:00 - 8:20, etc. Os horários são criados pelo script SQL: a aplicação
// apenas os lê.
namespace App\Entity;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;
#[ORM\Entity]
#[ORM\Table(name: 'slots')]
class Slot
{
#[ORM\Id]
#[ORM\GeneratedValue]
#[ORM\Column]
private ?int $id = null;
#[ORM\Version]
#[ORM\Column(type: Types::INTEGER)]
private int $version = 0;
// vários horários para o mesmo médico: #[ORM\ManyToOne], por meio da chave
// estrangeira [doctor_id]
#[ORM\ManyToOne]
#[ORM\JoinColumn(name: 'doctor_id', nullable: false)]
private Doctor $doctor;
#[ORM\Column(name: 'start_hour')]
private int $startHour;
#[ORM\Column(name: 'start_minute')]
private int $startMinute;
#[ORM\Column(name: 'end_hour')]
private int $endHour;
#[ORM\Column(name: 'end_minute')]
private int $endMinute;
public function getId(): ?int
{
return $this->id;
}
public function getDoctor(): Doctor
{
return $this->doctor;
}
// "8:00 - 8:20"; sprintf('%02d'): "8:05" em vez de "8:5"
public function time(): string
{
return sprintf('%d:%02d - %d:%02d', $this->startHour, $this->startMinute, $this->endHour, $this->endMinute);
}
}
|
- linhas 26–28: o relacionamento do horário com o médico. [#[ORM\ManyToOne]]: vários horários para o mesmo médico, por meio da chave estrangeira [doctor_id];
- linhas 30–40: as horas e minutos de início e de término. Os horários são criados pelo script SQL: a classe não tem construtor, e o [Doctrine] preenche suas propriedades por conta própria;
- linhas 53–56: o intervalo de tempo, “8:00 – 8:20”. O formato [%02d] de [sprintf] escreve um inteiro de dois dígitos, preenchido com zeros: [8:05] em vez de [8:5].
11.8.6. src/Entity/Appointment.php
| <?php
// src/Entity/Appointment.php: uma consulta (tabela [appointments]): um cliente, em um horário,
// em um determinado dia.
// 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\Entity;
use DateTimeImmutable;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;
#[ORM\Entity]
#[ORM\Table(name: 'appointments')]
class Appointment
{
#[ORM\Id]
#[ORM\GeneratedValue]
#[ORM\Column]
private ?int $id = null;
#[ORM\Version]
#[ORM\Column(type: Types::INTEGER)]
private int $version = 0;
public function __construct(
// o tipo date_immutable: a coluna [day] (tipo SQL DATE) vira uma data
// DateTimeImmutable, à meia-noite; ela é escrita no banco de dados no formato yyyy-mm-dd
#[ORM\Column(type: Types::DATE_IMMUTABLE)]
private DateTimeImmutable $day,
#[ORM\ManyToOne]
#[ORM\JoinColumn(name: 'slot_id', nullable: false)]
private Slot $slot,
#[ORM\ManyToOne]
#[ORM\JoinColumn(name: 'client_id', nullable: false)]
private Client $client,
) {
}
public function getId(): ?int
{
return $this->id;
}
public function getDay(): DateTimeImmutable
{
return $this->day;
}
public function getSlot(): Slot
{
return $this->slot;
}
public function getClient(): Client
{
return $this->client;
}
}
|
- linhas 30–31: a coluna [day] (tipo SQL [DATE]) é convertida em [DateTimeImmutable] à meia-noite (tipo [Doctrine] [date_immutable]). Imutável: seus métodos nunca modificam o objeto; eles retornam um novo ([$day->modify('+1 day')] retorna o dia seguinte, [$day] permanece inalterado). A aplicação inteira trabalha com datas imutáveis: uma data compartilhada entre vários objetos não pode ser modificada por um deles sem que os outros saibam;
- linhas 32–37: dois relacionamentos, um com o horário e outro com o cliente da consulta.
11.9. O domínio: a agenda
11.9.1. src/Domain/DoctorDaySlot.php e DoctorDaySchedule.php
| <?php
// src/Domain/DoctorDaySlot.php: um horário e a consulta eventualmente
// marcada nesse horário em um determinado dia (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 é preciso para um objeto calculado, que ninguém modifica depois.
namespace App\Domain;
use App\Entity\Slot;
use App\Entity\Appointment;
readonly class DoctorDaySlot
{
public function __construct(
public Slot $slot,
public ?Appointment $appointment,
) {
}
}
|
| <?php
// src/Domain/DoctorDaySchedule.php: a agenda completa de um médico em um determinado
// 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\Entity\Doctor;
use DateTimeImmutable;
readonly class DoctorDaySchedule
{
/** @param list<DoctorDaySlot> $doctorDaySlots */
public function __construct(
public Doctor $doctor,
public DateTimeImmutable $day,
public array $doctorDaySlots,
) {
}
}
|
Dois objetos calculados que não correspondem a nenhuma tabela: um horário e sua eventual consulta em determinado dia; a agenda de um médico para um único dia, listando seus horários disponíveis. São classes [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 editores ([PHP Intelephense]) e ferramentas de análise leem esses comentários, conhecidos como [PHPDoc].
11.10. A camada DAO
A camada DAO (Exemplo 28) reúne as consultas: uma classe por tabela, sem lógica de negócio. Seus métodos não iniciam uma transação; a camada de negócio os chama dentro de suas próprias transações. Eles são escritos em DQL (Exemplo 28) ou por meio do query builder do [Doctrine], que gera uma consulta DQL por meio de chamadas de métodos; os valores são parâmetros da consulta: injeção de SQL não é possível.
11.10.1. src/Dao/PersonDao.php
| <?php
// =========================================================================
// src/Dao/PersonDao.php: a camada DAO comum aos médicos e aos clientes.
//
// Os DAOs dos médicos e dos clientes seriam idênticos: esta classe ABSTRATA
// os escreve uma única vez. $this->entityClass é a classe da entidade em questão
// (Doctor::class ou Client::class): as consultas DQL tratam de SUA tabela.
//
// As consultas são escritas em DQL, a linguagem de consulta do Doctrine (veja o
// exemplo 28), que o Doctrine traduz para SQL. Os valores (nome, sobrenome...) são
// PARÂMETROS da consulta (:firstName): sem concatenação de strings, portanto sem
// injeção de SQL. Esses métodos não abrem nenhuma transação: é a camada de
// negócio que os chama, dentro da sua.
// =========================================================================
namespace App\Dao;
use App\Entity\Person;
use Doctrine\ORM\EntityManagerInterface;
use Doctrine\ORM\QueryBuilder;
abstract class PersonDao
{
/** @param class-string<Person> $entityClass */
public function __construct(protected EntityManagerInterface $em, protected string $entityClass)
{
}
// -----------------------------------------------------------------------
// uma consulta sobre a tabela da classe, conta de usuário incluída. O
// QUERY BUILDER do Doctrine (createQueryBuilder) constrói a consulta DQL
// por meio de chamadas de método:
// SELECT p, a FROM App\Entity\Doctor p JOIN p.account a
// JOIN p.account a: o join SQL com a tabela [users]; SELECT p, a: as
// contas são carregadas PELA MESMA consulta. Sem isso, cada acesso a
// $person->getAccount() dispararia sua própria consulta
// -----------------------------------------------------------------------
protected function query(): QueryBuilder
{
return $this->em->createQueryBuilder()
->select('p', 'a')
->from($this->entityClass, 'p')
->join('p.account', 'a');
}
// lista ordenada por sobrenome e depois por nome
/** @return list<Person> */
public function list(): array
{
return $this->query()->orderBy('p.lastName')->addOrderBy('p.firstName')->getQuery()->getResult();
}
// uma pessoa e sua conta; null se ela não existir
public function read(int $id): ?Person
{
return $this->query()->where('p.id = :id')->setParameter('id', $id)
->getQuery()->getOneOrNullResult();
}
// a pessoa cuja conta de usuário é [$userId]
public function readByUser(int $userId): ?Person
{
return $this->query()->where('a.id = :userId')->setParameter('userId', $userId)
->getQuery()->getOneOrNullResult();
}
// 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
// diferenciar maiúsculas e acentos) - exatamente a mesma regra da
// restrição de unicidade SQL
public function namesake(string $firstName, string $lastName): ?Person
{
return $this->query()->where('p.firstName = :firstName')->andWhere('p.lastName = :lastName')
->setParameter('firstName', $firstName)->setParameter('lastName', $lastName)
->setMaxResults(1)->getQuery()->getOneOrNullResult();
}
// a pessoa será inserida pelo próximo flush (o da transação da
// camada de negócio); o banco de dados gerará seu id, que o Doctrine armazenará no objeto
public function add(Person $person): void
{
$this->em->persist($person);
}
// a pessoa será excluída pelo próximo flush
public function remove(Person $person): void
{
$this->em->remove($person);
}
}
|
A camada DAO comum a médicos e clientes, implementada uma só vez em uma classe abstrata.
- Linha 25: o construtor recebe o entity manager (Exemplo 28) e a classe em questão, [Doctor::class] ou [Client::class] (uma string que representa o nome completo da classe). O comentário [@param class-string<Person>] deixa isso claro para os desenvolvedores. O contêiner de serviços não sabe qual string fornecer: são as classes filhas que chamam este construtor;
- linhas 38–44: uma consulta que também carrega as contas dos usuários lidos. [createQueryBuilder] cria um query builder; [select('p', 'a')], [from($this->entityClass, 'p')], e [join('p.account', 'a')] escrevem a consulta DQL [SELECT p, a FROM App\Entity\Doctor p JOIN p.account a]. A junção ([JOIN]) segue o relacionamento [account] da entidade: o [Doctrine] deriva a condição SQL ([ON d0_.user = u1_.id]). O [SELECT] para os dois aliases exige o carregamento eager das contas: uma única consulta recupera as pessoas e suas contas. Sem isso, a lista de médicos exibida pelo administrador dispararia uma consulta por médico no primeiro acesso a [$doctor->getAccount()->getLogin()]: é o chamado problema das “N + 1 consultas”. Outro motivo: as listas de médicos e clientes são armazenadas no cache ([ApplicationModel], tratado adiante); os objetos colocados no cache precisam estar completos;
- linhas 48–51: a lista, ordenada por sobrenome e depois por nome ([orderBy], depois [addOrderBy]: um segundo critério; um segundo [orderBy] substituiria o primeiro). [getQuery()] retorna a consulta DQL; [getResult()] a executa e retorna o array de entidades;
- linhas 54–58: [where] adiciona uma condição com um parâmetro nomeado ([:id]), cujo valor é fornecido por [setParameter]. [getOneOrNullResult] retorna a única entidade encontrada ou [null];
- linhas 61–65: a pessoa cuja conta é [$userId], condição baseada no ID da conta vinculada;
- linhas 71–76: a pessoa com o mesmo nome e sobrenome. [andWhere] adiciona uma segunda condição (um segundo [where] substituiria o primeiro). A comparação é feita pelo [MySQL], usando a collation do banco de dados: sem diferenciar maiúsculas de minúsculas e ignorando acentos, exatamente como a restrição de unicidade (Exemplo 28);
- linhas 80–89: a inserção e a exclusão, que serão enviadas ao banco de dados pelo [flush] como parte da transação da camada de negócio (Exemplo 28).
Não há método de atualização: a camada de negócio modifica a entidade lida, e o [Doctrine] enviará [UPDATE] no [flush] (rastreamento de alterações, Exemplo 28), usando um bloqueio otimista.
11.10.2. src/Dao/DoctorDao.php e ClientDao.php
| <?php
// src/Dao/DoctorDao.php: o DAO dos médicos - tudo é herdado de PersonDao.
namespace App\Dao;
use App\Entity\Doctor;
use Doctrine\ORM\EntityManagerInterface;
class DoctorDao extends PersonDao
{
public function __construct(EntityManagerInterface $em)
{
parent::__construct($em, Doctor::class);
}
}
|
Tudo é herdado: o construtor recebe o entity manager do contêiner e o repassa ao [PersonDao] junto com a classe da entidade ([parent::__construct] chama o construtor da classe pai).
| <?php
// src/Dao/ClientDao.php: o DAO dos clientes - o das pessoas, mais um método
// de bloqueio.
namespace App\Dao;
use App\Entity\Client;
use Doctrine\DBAL\LockMode;
use Doctrine\ORM\EntityManagerInterface;
class ClientDao extends PersonDao
{
public function __construct(EntityManagerInterface $em)
{
parent::__construct($em, Client::class);
}
// -----------------------------------------------------------------------
// 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 peça o mesmo lock ESPERA até que a
// primeira termine. LockMode::PESSIMISTIC_WRITE: o lock "pessimista"
// do Doctrine, que exige uma transação aberta.
// Usado para o agendamento (veja BusinessService::addAppointment): dois
// agendamentos simultâneos para o mesmo paciente são assim processados um
// DEPOIS do outro, e o segundo vê a consulta criada pelo primeiro.
// -----------------------------------------------------------------------
public function lock(int $id): ?int
{
$row = $this->em->createQuery('SELECT c.id FROM App\Entity\Client c WHERE c.id = :id')
->setParameter('id', $id)
->setLockMode(LockMode::PESSIMISTIC_WRITE)
->getOneOrNullResult();
return $row['id'] ?? null;
}
}
|
- Linhas 28–35: um bloqueio pessimista, o outro tipo de bloqueio. [setLockMode(LockMode::PESSIMISTIC_WRITE)] adiciona [FOR UPDATE] à consulta: [SELECT c0_.id AS id_0 FROM clients c0_ WHERE c0_.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. O [Doctrine] nega esse bloqueio fora de uma transação. A consulta lê apenas o ID ([SELECT c.id]): seu resultado não é uma entidade, mas um array associativo ([['id' => 3]]), ou [null]. Veremos, na camada de negócio, para que serve esse bloqueio.
11.10.3. src/Dao/SlotDao.php
| <?php
// src/Dao/SlotDao.php: camada DAO dos horários.
namespace App\Dao;
use App\Entity\Slot;
use Doctrine\ORM\EntityManagerInterface;
class SlotDao
{
public function __construct(private EntityManagerInterface $em)
{
}
// um horário e seu médico
public function read(int $id): ?Slot
{
return $this->em->createQuery(
'SELECT s, d FROM App\Entity\Slot s JOIN s.doctor d WHERE s.id = :id')
->setParameter('id', $id)->getOneOrNullResult();
}
// os horários de um médico, em ordem cronológica. s.doctor = :doctorId:
// uma associação comparada a um id, o da chave estrangeira
/** @return list<Slot> */
public function listByDoctor(int $doctorId): array
{
return $this->em->createQuery(
'SELECT s FROM App\Entity\Slot s WHERE s.doctor = :doctorId ORDER BY s.startHour, s.startMinute')
->setParameter('doctorId', $doctorId)->getResult();
}
// exclui todos os horários de um médico (exclusão de um médico): uma
// consulta DQL DELETE, executada imediatamente:
// DELETE FROM slots WHERE doctor_id = ?
public function deleteByDoctor(int $doctorId): void
{
$this->em->createQuery('DELETE FROM App\Entity\Slot s WHERE s.doctor = :doctorId')
->setParameter('doctorId', $doctorId)->execute();
}
}
|
Um horário e seu médico (pré-carregado); os horários de um médico, em ordem cronológica: [s.doctor = :doctorId] compara um relacionamento com um ID — o da chave estrangeira; e um [DELETE] escrito em DQL, executado imediatamente ([execute()]), sem ler as linhas antes.
11.10.4. src/Dao/AppointmentDao.php
| <?php
// =========================================================================
// src/Dao/AppointmentDao.php: camada DAO das consultas.
//
// A tabela [appointments] não referencia o médico diretamente: passamos pelo horário
// (JOIN a.slot s ... WHERE s.doctor = ...).
// As datas são passadas com seu tipo (Types::DATE_IMMUTABLE): o Doctrine
// as escreve no formato do banco de dados, yyyy-mm-dd.
// =========================================================================
namespace App\Dao;
use App\Entity\Appointment;
use DateTimeImmutable;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\EntityManagerInterface;
class AppointmentDao
{
public function __construct(private EntityManagerInterface $em)
{
}
// uma consulta, seu cliente e seu horário
public function read(int $id): ?Appointment
{
return $this->em->createQuery(
'SELECT a, c, s FROM App\Entity\Appointment a JOIN a.client c JOIN a.slot s WHERE a.id = :id')
->setParameter('id', $id)->getOneOrNullResult();
}
// as consultas de um médico em um determinado dia, com seu cliente
/** @return list<Appointment> */
public function doctorDayAppointments(int $doctorId, DateTimeImmutable $day): array
{
return $this->em->createQuery(
'SELECT a, c FROM App\Entity\Appointment a JOIN a.client c JOIN a.slot s
WHERE a.day = :day AND s.doctor = :doctorId')
->setParameter('day', $day, Types::DATE_IMMUTABLE)
->setParameter('doctorId', $doctorId)
->getResult();
}
// -----------------------------------------------------------------------
// as consultas de um cliente a partir do dia [$since] (inclusive), em ordem
// cronológica, com o horário E o médico desse horário (dois joins:
// JOIN a.slot s JOIN s.doctor d, e SELECT a, s, d)
// -----------------------------------------------------------------------
/** @return list<Appointment> */
public function clientUpcomingAppointments(int $clientId, DateTimeImmutable $since): array
{
return $this->em->createQuery(
'SELECT a, s, d FROM App\Entity\Appointment a JOIN a.slot s JOIN s.doctor d
WHERE a.client = :clientId AND a.day >= :since
ORDER BY a.day, s.startHour, s.startMinute')
->setParameter('clientId', $clientId)
->setParameter('since', $since, Types::DATE_IMMUTABLE)
->getResult();
}
// número de consultas de um cliente a partir do dia [$since] (inclusive);
// getSingleScalarResult: o único valor da única linha do resultado
public function countClientUpcoming(int $clientId, DateTimeImmutable $since): int
{
return (int) $this->em->createQuery(
'SELECT COUNT(a.id) FROM App\Entity\Appointment a WHERE a.client = :clientId AND a.day >= :since')
->setParameter('clientId', $clientId)
->setParameter('since', $since, Types::DATE_IMMUTABLE)
->getSingleScalarResult();
}
// número de consultas (passadas ou futuras) de um médico
public function countByDoctor(int $doctorId): int
{
return (int) $this->em->createQuery(
'SELECT COUNT(a.id) FROM App\Entity\Appointment a JOIN a.slot s WHERE s.doctor = :doctorId')
->setParameter('doctorId', $doctorId)
->getSingleScalarResult();
}
// a consulta será inserida no próximo flush
public function add(Appointment $appointment): void
{
$this->em->persist($appointment);
}
public function remove(Appointment $appointment): void
{
$this->em->remove($appointment);
}
// exclui TODAS as consultas (passadas e futuras) de um cliente, imediatamente
public function deleteByClient(int $clientId): void
{
$this->em->createQuery('DELETE FROM App\Entity\Appointment a WHERE a.client = :clientId')
->setParameter('clientId', $clientId)->execute();
}
}
|
A tabela [appointments] não referencia diretamente o médico: ela passa pelo horário.
- Linhas 34–42: as consultas de um médico em determinado dia e seus clientes. Duas junções: uma ([a.client c]) para carregar os clientes ([SELECT a, c]), a outra ([a.slot s]) para o filtro por médico. O terceiro parâmetro de [setParameter] especifica o tipo do valor ao [Doctrine]: um [DateTimeImmutable] é então escrito no formato da coluna [DATE], [yyyy-mm-dd];
- linhas 50–59: as próximas consultas de um paciente, com seu horário e o médico associado a esse horário: [JOIN s.doctor d] segue um relacionamento a partir da relação. A ordenação também é feita pelo horário, uma coluna de outra tabela: isso é possibilitado pela junção;
- linhas 63–79: contagens. [COUNT(a.id)] conta as consultas; [getSingleScalarResult] retorna o único valor da única linha do resultado (uma string, convertida em inteiro por [(int)]);
- linhas 93–97: exclusão de todas as consultas de um cliente, usando DQL.
11.10.5. src/Dao/UserDao.php
| <?php
// src/Dao/UserDao.php: camada DAO das contas de usuário. Criar (ou excluir)
// um médico ou um cliente também cria (ou exclui) a conta dele - veja src/Business.
// Uma conta modificada é alterada por seus métodos (setLogin...): o Doctrine enviará
// o UPDATE no próximo flush (rastreamento de alterações, veja o exemplo 28).
namespace App\Dao;
use App\Entity\User;
use Doctrine\ORM\EntityManagerInterface;
class UserDao
{
public function __construct(private EntityManagerInterface $em)
{
}
// null se nenhum usuário tiver esse login; findOneBy: o repositório da entidade
// procura a linha cujas colunas têm esses valores
public function readByLogin(string $login): ?User
{
return $this->em->getRepository(User::class)->findOneBy(['login' => $login]);
}
public function add(User $user): void
{
$this->em->persist($user);
}
public function remove(User $user): void
{
$this->em->remove($user);
}
}
|
Contas: recuperação por login, com armazenamento de entidades (exemplo 28): [findOneBy(criteria)] retorna a única entidade que atende aos critérios ou [null]; adição e exclusão.
11.11. A camada de negócio
A camada de negócio reúne regras de negócio e transações (Exemplo 28). Ela é descrita por uma interface, implementada por duas classes: [BusinessService], a camada de negócio propriamente dita, e [ApplicationModel], o cache da camada web (tratado adiante).
11.11.1. src/Business/Dates.php
| <?php
// src/Business/Dates.php: a data de hoje. Ela é usada pelas REGRAS DE NEGÓCIO (sem
// reserva no passado, apenas uma consulta FUTURA por paciente): por isso
// fica na camada de negócio. A camada web a reutiliza.
namespace App\Business;
use DateTimeImmutable;
class Dates
{
// hoje à meia-noite, no fuso horário da aplicação (veja src/Kernel.php)
public static function today(): DateTimeImmutable
{
return new DateTimeImmutable('today');
}
}
|
A data atual à meia-noite (['today']), no fuso horário da aplicação (veja [src/Kernel.php]). Ela é usada em regras de negócio (sem reservas 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. src/Business/BusinessException.php
| <?php
// =========================================================================
// src/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 as traduções).
//
// Uma BusinessException não é uma anomalia: é uma resposta normal ("this login
// is already taken"), exibida ao usuário. Qualquer outra exceção é uma anomalia
// real, 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 nada sabe 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 (a que causou esta — um erro do banco de dados, por exemplo: ela aparece no log junto com a nova).
11.11.3. src/Business/PersonData.php
| <?php
// src/Business/PersonData.php: os dados digitados em um formulário de "doctor" ou "client",
// 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), assume 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, assume 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,
) {
}
}
|
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 sua ausência significa.
11.11.4. src/Business/Business.php
| <?php
// =========================================================================
// src/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
// 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...).
// list<Doctor> (em um comentário de documentação /**): um array de médicos, indexado 0, 1, 2...
// =========================================================================
namespace App\Business;
use App\Domain\DoctorDaySchedule;
use App\Entity\Client;
use App\Entity\Slot;
use App\Entity\Doctor;
use App\Entity\Appointment;
use DateTimeImmutable;
interface Business
{
// leituras
/** @return list<Client> */
public function getAllClients(): array;
/** @return list<Doctor> */
public function getAllDoctors(): array;
/** @return list<Slot> */
public function getAllSlots(int $doctorId): array;
/** @return list<Appointment> */
public function getDoctorDayAppointments(int $doctorId, DateTimeImmutable $day): array;
public function getClientById(int $id): ?Client;
public function getDoctorById(int $id): ?Doctor;
public function getAppointmentById(int $id): ?Appointment;
public function getSlotById(int $id): ?Slot;
public function getDoctorDaySchedule(int $doctorId, DateTimeImmutable $day): ?DoctorDaySchedule;
// 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
/** @return list<Appointment> */
public function getClientUpcomingAppointments(int $clientId): array;
// consultas (ADMIN, DOCTOR, USER)
// lança uma BusinessException se:
// - o dia for passado ("ERRORS.PAST_DATE");
// - o paciente já tiver uma consulta futura ("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
// - o horário já estiver ocupado nesse dia ("ERRORS.SLOT_ALREADY_BOOKED").
public function addAppointment(DateTimeImmutable $day, Slot $slot, Client $client): Appointment;
public function deleteAppointment(Appointment $appointment): void;
// médicos (ADMIN)
// cria o médico E a conta de usuário dele (papel DOCTOR)
public function addDoctor(PersonData $data): Doctor;
// modifica o médico E a conta de usuário dele
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 no cadastro de um paciente,
// editClient e deleteClient pelo paciente para a própria conta)
// cria o cliente E a conta de usuário dele (papel USER)
public function addClient(PersonData $data): Client;
public function editClient(int $id, PersonData $data): Client;
// exclui o cliente, sua conta E todas as consultas dele (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 entidades ou arrays de entidades (o comentário [@return list<Client>] especifica seu conteúdo); [?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 das [BusinessException] que ela pode lançar.
11.11.5. src/Business/Descriptor.php
| <?php
// src/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 descritor.
namespace App\Business;
use App\Dao\PersonDao;
use App\Entity\Role;
use Closure;
readonly class Descriptor
{
public function __construct(
public PersonDao $dao,
public Role $role, // DOCTOR ou USER
// a classe da entidade, para criar uma pessoa: Doctor::class ou Client::class
public string $entityClass,
public string $notFoundKey, // mensagem se a pessoa não existir
public string $alreadyExistsKey, // mensagem se já existirem o mesmo nome e sobrenome
// 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 meio de uma chave estrangeira); recebe o id dela
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, a classe da entidade a ser criada, 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 das referências à pessoa.
11.11.6. src/Business/BusinessService.php
| <?php
// =========================================================================
// src/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 a conta de usuário dela andam SEMPRE
// 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 a consulta sem serem avisados): elas devem antes
// ser canceladas. Seus horários desaparecem junto com ele;
// - um CLIENTE, por outro lado, desaparece com TODAS as suas consultas (passadas e futuras) -
// seja a exclusão feita pelo ADMIN ou pelo próprio paciente.
//
// E duas regras para a reserva, qualquer que seja o papel de quem
// reserva (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 descritor
// que diz com que tipo de pessoa estamos lidando.
//
// As TRANSAÇÕES são abertas pelo método transaction (no fim do arquivo),
// que também traduz em BusinessException os erros informados 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\Entity\Client;
use App\Entity\Slot;
use App\Entity\Doctor;
use App\Entity\Person;
use App\Entity\Role;
use App\Entity\Appointment;
use App\Entity\User;
use Closure;
use DateTimeImmutable;
use Doctrine\DBAL\Exception\UniqueConstraintViolationException;
use Doctrine\ORM\EntityManagerInterface;
use Doctrine\ORM\OptimisticLockException;
use Symfony\Component\PasswordHasher\Hasher\PasswordHasherFactoryInterface;
use Symfony\Component\PasswordHasher\PasswordHasherInterface;
class BusinessService implements Business
{
// -----------------------------------------------------------------------
// Erros do banco de dados -> BusinessException
//
// Quando uma restrição UNIQUE recusa uma gravação, o Doctrine lança uma
// UniqueConstraintViolationException, 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 dá NOME a 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;
// o hash das senhas (bcrypt, veja config/packages/security.yaml)
private PasswordHasherInterface $hasher;
// todas as dependências são fornecidas pelo contêiner de serviços do Symfony
// (injeção de dependência, veja o exemplo 06)
public function __construct(
private EntityManagerInterface $em,
private DoctorDao $doctors,
private ClientDao $clients,
private SlotDao $slots,
private AppointmentDao $appointments,
private UserDao $users,
PasswordHasherFactoryInterface $hashers,
) {
$this->hasher = $hashers->getPasswordHasher(User::class);
$this->doctor = new Descriptor(
dao: $doctors,
role: Role::DOCTOR,
entityClass: Doctor::class,
notFoundKey: 'ERRORS.DOCTOR_NOT_FOUND',
alreadyExistsKey: 'ERRORS.DOCTOR_ALREADY_EXISTS',
// $appointments->countByDoctor(...): 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, e são excluídos junto (senão a
// chave estrangeira slots.doctor_id impediria a exclusão)
beforeDelete: $slots->deleteByDoctor(...));
$this->client = new Descriptor(
dao: $clients,
role: Role::USER,
entityClass: Client::class,
notFoundKey: 'ERRORS.PATIENT_NOT_FOUND',
alreadyExistsKey: 'ERRORS.PATIENT_ALREADY_EXISTS',
// sem countAppointments: a exclusão de um cliente nunca é recusada;
// as consultas dele (passadas e futuras) são excluídas junto (senão a
// chave estrangeira appointments.client_id impediria a exclusão)
countAppointments: null,
hasAppointmentsKey: null,
beforeDelete: $appointments->deleteByClient(...));
}
// =======================================================================
// leituras
// =======================================================================
public function getAllClients(): array
{
return $this->clients->list();
}
public function getAllDoctors(): array
{
return $this->doctors->list();
}
public function getAllSlots(int $doctorId): array
{
return $this->slots->listByDoctor($doctorId);
}
public function getDoctorDayAppointments(int $doctorId, DateTimeImmutable $day): array
{
return $this->appointments->doctorDayAppointments($doctorId, $day);
}
public function getClientById(int $id): ?Client
{
return $this->clients->read($id);
}
public function getDoctorById(int $id): ?Doctor
{
return $this->doctors->read($id);
}
public function getAppointmentById(int $id): ?Appointment
{
return $this->appointments->read($id);
}
public function getSlotById(int $id): ?Slot
{
return $this->slots->read($id);
}
public function getClientByUserId(int $userId): ?Client
{
return $this->clients->readByUser($userId);
}
public function getClientUpcomingAppointments(int $clientId): array
{
return $this->appointments->clientUpcomingAppointments($clientId, Dates::today());
}
// a agenda de um médico em um dado dia: seus horários e, para cada um, a
// consulta reservada nesse dia (null se estiver livre)
public function getDoctorDaySchedule(int $doctorId, DateTimeImmutable $day): ?DoctorDaySchedule
{
$doctor = $this->getDoctorById($doctorId);
if ($doctor === null) {
return null;
}
// número do horário -> consulta reservada nesse horário
$bookings = [];
foreach ($this->getDoctorDayAppointments($doctorId, $day) as $appointment) {
$bookings[$appointment->getSlot()->getId()] = $appointment;
}
// array_map: aplica a função a cada horário e retorna o array dos resultados
$doctorDaySlots = array_map(
fn (Slot $slot) => new DoctorDaySlot($slot, $bookings[$slot->getId()] ?? null),
$this->getAllSlots($doctorId));
return new DoctorDaySchedule($doctor, $day, $doctorDaySlots);
}
// =======================================================================
// consultas
// =======================================================================
// -----------------------------------------------------------------------
// reserva, em uma transação:
// 1. nenhuma consulta no passado;
// 2. BLOQUEAMOS a linha do paciente (SELECT ... FOR UPDATE): se o mesmo
// paciente reservar dois horários ao mesmo tempo (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(DateTimeImmutable $day, Slot $slot, Client $client): Appointment
{
return $this->transaction(function () use ($day, $slot, $client) {
$today = Dates::today();
if ($day < $today) {
throw new BusinessException('ERRORS.PAST_DATE');
}
$patientId = $this->clients->lock($client->getId())
?? throw new BusinessException('ERRORS.PATIENT_NOT_FOUND');
if ($this->appointments->countClientUpcoming($patientId, $today) > 0) {
throw new BusinessException('ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT');
}
$appointment = new Appointment($day, $slot, $client);
$this->appointments->add($appointment);
return $appointment;
});
}
public function deleteAppointment(Appointment $appointment): void
{
$this->transaction(fn () => $this->appointments->remove($appointment));
}
// =======================================================================
// médicos e clientes - os métodos públicos delegam para os métodos
// privados comuns, com o descritor adequado
// =======================================================================
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 consultas dele (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 E a pessoa (que a referencia), em UMA
// transação. O Doctrine insere primeiro a conta, depois a pessoa, cuja chave
// estrangeira [user] recebe o id que o banco acabou de gerar para a conta.
// -----------------------------------------------------------------------
private function addPerson(Descriptor $d, PersonData $data): Person
{
$lastName = mb_strtoupper(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 informado outros
$login = mb_strtolower($data->login ?: $lastName);
$password = $data->password ?: $login;
return $this->transaction(function () use ($d, $data, $lastName, $firstName, $login, $password) {
$this->checkPersonUnique($d, $firstName, $lastName, null);
$this->checkLoginFree($login);
// hash: o hash bcrypt da senha
$user = new User($login, $this->hasher->hash($password), "$firstName $lastName", $d->role);
$this->users->add($user);
// new ($d->entityClass)(...): uma instância da classe cujo nome está na
// propriedade [entityClass] do descritor (Doctor ou Client)
$person = new ($d->entityClass)($data->title, $lastName, $firstName, $user);
$d->dao->add($person);
return $person;
});
}
// -----------------------------------------------------------------------
// modificação: a pessoa E a conta dela (o nome exibido "firstName LASTNAME" deve
// acompanhar; o login e a senha só mudam se tiverem sido informados).
// -----------------------------------------------------------------------
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 alterações dessa pessoa
if ($data->version !== null && $data->version !== $person->getVersion()) {
throw new BusinessException('ERRORS.CONCURRENT_UPDATE');
}
$lastName = mb_strtoupper(trim($data->lastName));
$firstName = trim($data->firstName);
$this->checkPersonUnique($d, $firstName, $lastName, $id);
$person->edit($data->title, $lastName, $firstName);
// a conta dela: o nome exibido e, se tiverem sido informados, o login e a
// senha
$account = $person->getAccount();
$account->setName("$firstName $lastName");
$login = $data->login ? mb_strtolower($data->login) : null;
if ($login !== null && $login !== $account->getLogin()) {
$this->checkLoginFree($login);
$account->setLogin($login);
}
if ($data->password) {
$account->setPassword($this->hasher->hash($data->password));
}
// nada mais a fazer: no fim da transação, o Doctrine envia os
// UPDATEs das linhas modificadas, com o bloqueio otimista
// UPDATE ... SET ..., version = version + 1 WHERE id = ? AND version = ?
// Se o registro foi modificado DEPOIS da leitura acima, nenhuma linha
// é modificada, e o Doctrine lança uma OptimisticLockException
return $person;
});
}
// -----------------------------------------------------------------------
// exclusão, em UMA transação, na ordem imposta pelas chaves
// estrangeiras:
// 1. possível recusa se ainda houver consultas (médico);
// 2. o que referencia a pessoa (horários de um médico, consultas de um
// cliente), imediatamente;
// 3. a pessoa (ela referencia a conta), depois a conta: o Doctrine
// as exclui nessa ordem no fim da transação.
// -----------------------------------------------------------------------
private function deletePerson(Descriptor $d, int $id): void
{
$this->transaction(function () use ($d, $id) {
$person = $d->dao->read($id) ?? throw new BusinessException($d->notFoundKey);
if ($d->countAppointments !== null && ($d->countAppointments)($id) > 0) {
throw new BusinessException($d->hasAppointmentsKey);
}
if ($d->beforeDelete !== null) {
($d->beforeDelete)($id);
}
$d->dao->remove($person);
$this->users->remove($person->getAccount());
});
}
// recusa nome e sobrenome já usados por OUTRA pessoa do mesmo tipo
// ($currentId: a pessoa que está sendo modificada, que naturalmente tem o direito
// de manter o próprio nome e sobrenome; null para 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->getId() !== $currentId) {
throw new BusinessException($d->alreadyExistsKey);
}
}
private function checkLoginFree(string $login): void
{
if ($this->users->readByLogin($login) !== null) {
throw new BusinessException('ERRORS.LOGIN_TAKEN');
}
}
// -----------------------------------------------------------------------
// executa [$work] em uma transação (wrapInTransaction, veja o exemplo 28):
// se a função terminar normalmente, o Doctrine envia as gravações pendentes
// ao banco de dados (flush) e depois confirma a transação (COMMIT); se uma
// exceção sair dela (BusinessException inclusive), ROLLBACK: nada é gravado.
//
// As verificações de "login livre" e de "nome e 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 SQL de unicidade que recusa a segunda gravação.
// Da mesma forma, duas modificações simultâneas do mesmo registro são decididas pelo
// bloqueio otimista. Por isso capturamos esses erros EM VOLTA da transação,
// para traduzi-los em BusinessException. Qualquer outro erro é uma anomalia real:
// deixamos que ele suba.
// Após uma exceção, o Doctrine FECHA o entity manager: a requisição atual
// não deve mais gravar nada (os controllers redirecionam ou
// reexibem um formulário).
// -----------------------------------------------------------------------
private function transaction(Closure $work): mixed
{
try {
return $this->em->wrapInTransaction($work);
} catch (UniqueConstraintViolationException $e) {
if (preg_match(self::CONSTRAINT, $e->getMessage(), $m)
&& isset(self::CONSTRAINT_MESSAGES[$m[1]])) {
throw new BusinessException(self::CONSTRAINT_MESSAGES[$m[1]], previous: $e);
}
throw $e;
} catch (OptimisticLockException $e) {
throw new BusinessException('ERRORS.CONCURRENT_UPDATE', previous: $e);
}
}
}
|
O arquivo mais importante da aplicação. Vamos percorrê-lo por tópico.
11.11.6.1. Dependências e descritores
Linhas 86–124: o construtor recebe do contêiner o entity manager (para as transações), as cinco instâncias de DAO e a fábrica de serviços de hash ([PasswordHasherFactoryInterface]), à qual se pede o serviço das contas: [getPasswordHasher(User::class)] fornece o serviço que aplica o algoritmo escolhido para a classe [User] em [security.yaml] ([bcrypt], 10 iterações). Em seguida vêm os dois descritores. Os argumentos nomeados ([dao: $doctors], exemplo 01) tornam a chamada legível. [$appointments->countByDoctor(...)] (com três pontos entre parênteses) não tem significado especial: é a sintaxe do [PHP] 8.1 que cria, a partir de um método, um [Closure] — uma função que será chamada mais tarde ([($d->countAppointments)($id)], linha 359). 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. Operações de leitura e a agenda
As operações de leitura (linhas 130–178) delegam à camada DAO. A agenda de um médico (linhas 182–198) é calculada: o médico, seus horários e as consultas do dia. As consultas são armazenadas em um array indexado pelo número do horário: [$bookings[$slot->getId()] ?? null] retorna a consulta de um horário ou [null] se o horário estiver livre. [array_map] converte cada horário em [DoctorDaySlot].
11.11.6.3. Marcação de uma consulta
Linhas 216–232: quatro etapas, em uma única transação.
- Sem consultas no passado: os objetos [DateTimeImmutable] aceitam os operadores usuais ([<], [>=]...);
- 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 então cada uma inserir a sua: a regra seria violada. Com o bloqueio, a segunda transação espera a primeira terminar e então 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, no fim da transação. Se o horário acabou de ser tomado 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 244–274) chamam os métodos privados compartilhados, usando o descritor correto.
- Linhas 281–302: criação. O sobrenome é convertido em maiúsculas ([mb_strtoupper]: a versão de [strtoupper] que oferece suporte a letras acentuadas), 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 “verdadeiro” (nem [null] nem uma string vazia), e a [$b] caso contrário. Na transação: as validações (nome e sobrenome podem ter qualquer valor, o login pode ter qualquer valor), depois a conta, cuja senha recebe hash ([hash]), e então a pessoa, que referencia a conta. [new ($d->entityClass)(...)] cria um objeto da classe cujo nome está na propriedade [entityClass] do descritor (os parênteses são obrigatórios em torno de uma expressão). [Doctrine] inserirá a conta antes da pessoa: ele conhece os relacionamentos entre as entidades e deduz a ordem dos objetos [INSERT]. [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 repassa a ela (uma arrow function, [fn () =>], as enxerga por conta própria, mas só pode conter uma expressão);
- Linhas 308–344: a atualização, com dois bloqueios otimistas. O primeiro é uma comparação (linhas 316–318): 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 é o do [Doctrine]: os registros [UPDATE] enviados no fim da transação carregam a condição [WHERE version = ?], que detecta uma alteração ocorrida entre a leitura e a gravação ([OptimisticLockException]). A conta vem em seguida: seu nome de exibição (“firstName LASTNAME”) é sempre atualizado; seu login e sua senha só são atualizados se tiverem sido informados; seu próprio bloqueio otimista também protege a linha da tabela [users]. Não há nada a “salvar”: a entidade lida é rastreada pelo entity manager, que gravará suas alterações. No fim da transação, o [Doctrine] armazena as novas versões das entidades: o chamador recebe a pessoa atualizada;
- linhas 355–368: exclusão, na ordem ditada pelas chaves estrangeiras: primeiro, os registros que referenciam a pessoa (horários ou consultas), seguidos imediatamente por [DELETE] do DAO; depois a pessoa e, por fim, sua conta, que o [Doctrine] exclui nessa ordem no fim da transação. 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 373–387: a pessoa que está sendo modificada pode manter seu próprio nome e sobrenome; [$currentId] equivale a [null] em uma criação.
11.11.6.5. Transações do banco de dados e erros
Linhas 406–419: todas as gravações usam este método. [wrapInTransaction] executa a função dentro de uma transação (Exemplo 28): [flush], depois [COMMIT] se ela terminar normalmente, e [ROLLBACK] se ocorrer uma exceção — inclusive uma [BusinessException]: a violação de uma regra no meio de uma operação não deixa rastro. As verificações de “login disponível” e de “nome e sobrenome disponíveis” são feitas antes da gravação, 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]. [Doctrine] então lança uma [UniqueConstraintViolationException] (exemplo 28), 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 'users.unq_users_login'
|
A expressão regular da linha 75 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 a tabela das linhas 68–73 fornece a chave da mensagem. Qualquer outra violação de restrição é uma anomalia verdadeira: ela é relançada ([throw $e]) e resultará em uma página de erro 500. Por fim, o conflito detectado pelo bloqueio otimista do [Doctrine] ([OptimisticLockException]) se torna a mesma [BusinessException] que a detectada pela comparação de versões.
Lembre-se de uma consequência de [wrapInTransaction] (Exemplo 28): após uma exceção, o entity manager é fechado e não pode mais gravar durante a requisição atual. Os controllers levam isso em conta: após uma [BusinessException], eles redirecionam ou exibem novamente um formulário sem gravar mais nada.
11.12. Autenticação
A pasta [src/Security] inclui os exemplos 25 a 27, com usuários do banco de dados e algumas medidas de segurança adicionais. Vamos relembrar o princípio (Exemplo 25): o firewall [main] de [config/packages/security.yaml] é stateless ([stateless]); a cada requisição, um autenticador de nossa autoria lê o token JWT do cookie [rdvmedecins_jwt] e identifica o usuário; as regras [access_control] determinam então o acesso às páginas.
11.12.1. src/Security/ConnectedUser.php
| <?php
// =========================================================================
// src/Security/ConnectedUser.php: o usuário logado, conforme descrito pelo
// token JWT dele (veja o exemplo 25). UserInterface: a interface que o Symfony espera
// dos usuários autenticados ($this->getUser() em um controller, #[CurrentUser],
// app.user e is_granted() em uma view...).
//
// As claims dos 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\Security;
use App\Entity\Role;
use Symfony\Component\Security\Core\User\UserInterface;
readonly class ConnectedUser implements UserInterface
{
public function __construct(
public int $userId,
public string $login,
public string $name,
public Role $role,
) {
}
// o usuário descrito pelas claims de um token já verificado; null se uma claim
// estiver ausente ou não tiver o formato esperado. 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 UserInterface: o identificador do usuário (o login dele)
// e seus papéis no sentido do Symfony (ROLE_ADMIN, ROLE_DOCTOR ou ROLE_USER, veja
// a enumeração Role), verificados pelas regras access_control de
// config/packages/security.yaml
public function getUserIdentifier(): string
{
return $this->login;
}
public function getRoles(): array
{
return [$this->role->symfonyRole()];
}
}
|
O usuário conectado, conforme 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 [UserInterface], que o [Symfony] espera dos usuários autenticados. 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. A aplicação, portanto, não lê a conta no banco de dados a cada requisição. A classe é [readonly] (Exemplo 08): suas propriedades públicas não podem ser modificadas após a construção.
- Linhas 36–44: o usuário é descrito pelas declarações (claims) de um token que já foi verificado, ou por [null] se uma 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 46–54: duas perguntas que as views e os controllers fazem com frequência;
- Linhas 60–68: a interface [UserInterface]. O identificador do usuário é seu login; seus papéis, conforme definidos pelo [Symfony], limitam-se a um único papel, [ROLE_ADMIN], [ROLE_DOCTOR] ou [ROLE_USER], calculado pela enumeração [Role]. Esses são os verificados pelas regras [access_control], pelo atributo [#[IsGranted]], e pela função [is_granted] das views. (O método [eraseCredentials], que apagava a senha em texto simples após o login, foi removido da interface com o [Symfony] 8.)
11.12.2. src/Security/AuthService.php
| <?php
// =========================================================================
// src/Security/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 viaja o token JWT? Em um COOKIE (veja o exemplo 25): um navegador
// que exibe páginas HTML comuns o apresenta por conta própria, a cada
// requisição. As opções desse cookie importam para a segurança:
// - HttpOnly: o JavaScript da página não consegue ler o cookie (um script
// injetado não poderia, portanto, roubar o token);
// - SameSite=Lax: o navegador NÃO envia o cookie com um POST vindo de outro
// site (primeira proteção contra o chamado ataque CSRF; a segunda é
// o token anti-CSRF dos formulários);
// - Secure: em produção (HTTPS), o cookie nunca trafega sem criptografia;
// - duração: o cookie desaparece ao mesmo tempo que o token expira.
// =========================================================================
namespace App\Security;
use App\Dao\UserDao;
use App\Entity\User;
use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use RuntimeException;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\PasswordHasher\Hasher\PasswordHasherFactoryInterface;
use Throwable;
class AuthService
{
// o nome do cookie que carrega o token
public const COOKIE = 'rdvmedecins_jwt';
// as configurações do arquivo .env: #[Autowire(env: ...)] (veja o exemplo 25)
public function __construct(
private UserDao $users,
private PasswordHasherFactoryInterface $hashers,
#[Autowire(env: 'JWT_SECRET')] private string $secret,
#[Autowire(env: 'int:JWT_DURATION_MINUTES')] private int $duration,
#[Autowire(env: 'bool:COOKIE_SECURE')] private bool $cookieSecure,
) {
// HMAC-SHA256 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 existir ou se a senha estiver errada. verify aplica o hash à
// senha digitada com o "salt" contido no hash armazenado e depois
// compara os dois resultados
public function validate(string $login, string $password): ?User
{
$user = $this->users->readByLogin($login);
if ($user === null
|| ! $this->hashers->getPasswordHasher(User::class)->verify($user->getPassword(), $password)) {
return null;
}
return $user;
}
// -----------------------------------------------------------------------
// 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 invalidaria a
// assinatura.
// -----------------------------------------------------------------------
public function tokenCookie(User $user): Cookie
{
$now = time();
$claims = [
'sub' => (string) $user->getId(),
'login' => $user->getLogin(),
'name' => $user->getName(),
'role' => $user->getRole()->value,
'iat' => $now,
'exp' => $now + $this->duration * 60,
];
$token = JWT::encode($claims, $this->secret, 'HS256');
return Cookie::create(self::COOKIE, $token)
->withExpires($now + $this->duration * 60)
->withSecure($this->cookieSecure)
->withHttpOnly(true)
->withSameSite(Cookie::SAMESITE_LAX);
}
// limpa o cookie do token: a resposta carrega um cookie de mesmo nome, vazio, já expirado
public static function clearCookie(Response $response): Response
{
$response->headers->clearCookie(self::COOKIE);
return $response;
}
// -----------------------------------------------------------------------
// o usuário descrito por um token; null se o token estiver 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 array associativo
$claims = (array) JWT::decode($token, new Key($this->secret, 'HS256'));
} catch (Throwable) {
return null;
}
return ConnectedUser::of($claims);
}
}
|
- linha 37: o nome do cookie do token, uma constante de classe, lida por [AuthService::COOKIE];
- linhas 40–52: o serviço recebe a camada DAO das contas; a fábrica de serviços de hash (a correspondente à classe [User], bcrypt, é declarada em [security.yaml]) e três configurações do arquivo [.env], por meio do atributo [#[Autowire(env: ...)]] (Exemplo 25). Os prefixos [int:] e [bool:] convertem o texto da variável de ambiente. Se uma chave for curta demais, isso é informado assim que o serviço é iniciado, com uma mensagem clara (veja “Problemas comuns”);
- Linhas 57–65: verificação de um nome de usuário e uma senha (Exemplo 25), com a conta recuperada do banco de dados pela camada DAO. Observe que este serviço usa a camada DAO diretamente, sem passar pela camada de negócio: a verificação de senha não é uma regra de negócio;
- Linhas 73–90: o token do usuário e o cookie que o transporta. As declarações são as mesmas do Exemplo 25, com o ID da conta ([sub], uma string, como exige o padrão) e o nome de usuário. [Cookie::create] cria um cookie, que os métodos [with...] complementam (cada um retorna um novo cookie: o objeto é imutável): sua data de expiração (a do token), [Secure] (em produção, sobre HTTPS), [HttpOnly], e [SameSite=Lax] (veja o comentário nas linhas 9–18);
- linhas 93–97: exclusão do cookie. [clearCookie(name)] adiciona à resposta um cookie com o mesmo nome — vazio e já expirado — para que o navegador o exclua. O método é estático: não requer configuração, e as classes que o chamam não precisam receber o serviço;
- linhas 103–112: verificação do token (exemplo 25).
11.12.3. src/Security/TokenAuthenticator.php
| <?php
// =========================================================================
// src/Security/TokenAuthenticator.php: o AUTENTICADOR do firewall (veja
// config/packages/security.yaml e o exemplo 25): a cada requisição, ele estabelece quem
// é o usuário, a partir do token JWT do cookie [rdvmedecins_jwt].
//
// Ele mesmo não recusa nada: um token ausente ou inválido deixa o visitante
// ANÔNIMO. São as regras access_control que então recusam o acesso às
// páginas protegidas; um visitante anônimo recusado é então entregue ao ENTRY POINT (o
// método start), que o envia de volta à página de login.
// =========================================================================
namespace App\Security;
use App\Web\Flash;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Event\ResponseEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
use Symfony\Component\Security\Http\Authenticator\Passport\SelfValidatingPassport;
use Symfony\Component\Security\Http\EntryPoint\AuthenticationEntryPointInterface;
class TokenAuthenticator extends AbstractAuthenticator implements AuthenticationEntryPointInterface
{
// o atributo da requisição que sinaliza um token inválido, a ser limpo
private const INVALID_TOKEN = '_invalid_token';
public function __construct(
private AuthService $auth,
private Flash $flash,
private UrlGeneratorInterface $urls,
) {
}
// o autenticador só age se a requisição carregar o cookie do token
public function supports(Request $request): ?bool
{
return $request->cookies->getString(AuthService::COOKIE) !== '';
}
// o token, verificado pelo AuthService, descreve o usuário: o passport
// se valida sozinho, e o badge devolve esse usuário diretamente (sem
// procurá-lo no banco de dados, veja o exemplo 25)
public function authenticate(Request $request): Passport
{
$user = $this->auth->currentUser($request->cookies->getString(AuthService::COOKIE))
?? throw new CustomUserMessageAuthenticationException('invalid token');
return new SelfValidatingPassport(new UserBadge($user->login, fn () => $user));
}
public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response
{
return null;
}
// um token inválido (expirado, forjado): o visitante continua anônimo (null) e o
// cookie será limpo da resposta, seja ela qual for (veja clearInvalidToken)
public function onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response
{
$request->attributes->set(self::INVALID_TOKEN, true);
return null;
}
// -----------------------------------------------------------------------
// o ENTRY POINT: um visitante anônimo pede uma página protegida. Direto para
// a página de login. Se ele tinha um cookie de token, significa que o token dele não é
// mais válido (expirado, forjado): a sessão dele expirou, e avisamos isso
// -----------------------------------------------------------------------
public function start(Request $request, ?AuthenticationException $authException = null): Response
{
if ($request->cookies->has(AuthService::COOKIE)) {
$this->flash->error('ERRORS.SESSION_EXPIRED');
}
return new RedirectResponse($this->urls->generate('login'));
}
// -----------------------------------------------------------------------
// um listener de kernel.response (veja o exemplo 24), escrito na mesma classe:
// ele limpa o cookie de um token inválido, em todas as respostas
// -----------------------------------------------------------------------
#[AsEventListener(event: KernelEvents::RESPONSE)]
public function clearInvalidToken(ResponseEvent $event): void
{
if ($event->getRequest()->attributes->get(self::INVALID_TOKEN)) {
AuthService::clearCookie($event->getResponse());
}
}
}
|
O autenticador do Exemplo 25, declarado em [security.yaml] ([custom_authenticators]). Ele também serve de ponto de entrada do firewall: implementa a interface [AuthenticationEntryPointInterface], e o [Symfony] o seleciona automaticamente, já que é o único autenticador do firewall.
- linhas 45–48: [supports] determina se o autenticador deve intervir: somente se a requisição contiver o cookie do token. Sem cookie, o visitante é anônimo, e nenhuma outra ação é tomada;
- linhas 53–58: [authenticate] verifica o token. Um token inválido dispara uma [AuthenticationException] (sua subclasse, [CustomUserMessageAuthenticationException], carrega uma mensagem livre). Caso contrário, um passaporte autovalidado ([SelfValidatingPassport]: não há senha a verificar; a assinatura do token serve de senha), cujo usuário é construído a partir do token sem consulta ao banco de dados;
- linhas 60–63: após uma autenticação bem-sucedida, [null]: a requisição prossegue para a action solicitada;
- linhas 67–71: após uma falha (token expirado ou forjado), [null] também: o visitante permanece anônimo. As regras [access_control] redirecionarão o visitante para a página de login se ele solicitar uma página protegida, mas ele pode ver as páginas públicas (inclusive a própria página de login!). A única indicação está em um atributo da requisição informando que o cookie deve ser excluído;
- linhas 78–84: o ponto de entrada, chamado pelo firewall quando um visitante anônimo solicita uma página protegida: um redirecionamento para a página de login. Se a requisição continha um cookie de token, isso significa que o token não é mais válido: a mensagem “Your session has expired: please log in again.” é exibida (uma mensagem pop-up, tratada adiante);
- Linhas 90–96: um listener do evento [kernel.response] (Exemplo 24), definido na mesma classe: o atributo [#[AsEventListener]] é aplicado a um método, e o autenticador — um serviço como qualquer outro — também se torna um listener. Ele exclui o cookie de um token inválido, seja qual for a resposta: a página de login, uma página pública ou um redirecionamento do ponto de entrada. Um cookie inválido não serve para nada e corromperia a mensagem da requisição seguinte.
11.12.4. src/Security/InvalidSession.php
| <?php
// src/Security/InvalidSession.php: o token é válido, mas a conta que ele
// designa não existe mais: ela foi excluída desde o login (pelo próprio paciente
// em outra aba, ou pelo ADMIN). Tratamos esse caso como uma sessão
// expirada: o listener ErrorPage limpa o cookie e redireciona para a página de
// login.
namespace App\Security;
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 conectado. 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], tratado adiante) é que descobre que a conta não existe mais. Ela então lança esta exceção, que o listener [ErrorPage] (tratado adiante) trata como uma sessão expirada. A classe é vazia: importa apenas seu tipo , que o listener reconhece ([instanceof]).
11.12.5. src/Security/CaptchaService.php, Captcha.php e CaptchaDrawing.php
[CaptchaDrawing.php] e [Captcha.php] são do Exemplo 27. O serviço é quase o mesmo:
| <?php
// =========================================================================
// src/Security/CaptchaService.php: um CAPTCHA ("test to tell a human from a
// robot") construído pelo próprio servidor, sem nenhum serviço externo (veja o exemplo 27).
//
// Como funciona:
// 1. generate() sorteia um texto aleatório, gera 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 resposta em si nunca sai do servidor);
// 3. verify(id, typed) compara a entrada com a resposta esperada e depois ESQUECE
// esse captcha: cada imagem é usada uma única vez, um robô não pode reenviar
// uma resposta já descoberta.
//
// 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 começa do zero. O que deve durar além de uma requisição
// vai, portanto, para o cache (aqui arquivos, em var/cache), compartilhado por todas as
// requisições, e até por vários servidores com um cache como o Redis.
// =========================================================================
namespace App\Security;
use Psr\Cache\CacheItemPoolInterface;
use Symfony\Component\Lock\LockFactory;
class CaptchaService
{
// duração de validade de uma imagem, em segundos: 10 minutos para preencher o formulário
private const LIFETIME = 600;
public function __construct(private CacheItemPoolInterface $cache, private LockFactory $locks)
{
}
public function generate(): Captcha
{
$text = CaptchaDrawing::randomText(5); // 5 caracteres
$id = bin2hex(random_bytes(12)); // um identificador impossível de adivinhar
// o cache esquecerá a resposta sozinho após 10 minutos
$item = $this->cache->getItem("captcha.$id");
$this->cache->save($item->set($text)->expiresAfter(self::LIFETIME));
return new Captcha($id, CaptchaDrawing::svg($text));
}
// true se [$typed] for a resposta certa para o captcha [$id] (sem diferenciar
// maiúsculas de minúsculas). O captcha é consumido em todos os casos.
public function verify(?string $id, ?string $typed): bool
{
// o identificador vem do navegador: dígitos hexadecimais, ou nada
if ($id === null || ! ctype_xdigit($id) || $typed === null) {
return false;
}
// se duas requisições apresentarem o mesmo captcha no mesmo instante, apenas uma
// obtém o lock (acquire(false): sem esperar) - a outra falha
$lock = $this->locks->createLock("captcha.$id");
if (! $lock->acquire(false)) {
return false;
}
try {
$item = $this->cache->getItem("captcha.$id");
$this->cache->deleteItem("captcha.$id");
} finally {
$lock->release();
}
return $item->isHit() && strcasecmp($item->get(), trim($typed)) === 0;
}
}
|
- linhas 35–43: uma string de 5 caracteres gerada aleatoriamente, um identificador aleatório ([random_bytes], um gerador criptográfico, cujos bytes são escritos em hexadecimal por [bin2hex]) e a resposta correta armazenada no cache (exemplo 20) por 10 minutos ([expiresAfter], em segundos);
- linhas 47–66: uma diferença em relação ao Exemplo 27. A resposta é lida e depois removida do cache. Entre a leitura e a remoção, uma segunda requisição que apresentasse o mesmo CAPTCHA também poderia lê-la: duas tentativas para uma única imagem resolvida. Um lock (Exemplo 20), específico deste CAPTCHA, protege portanto tanto a leitura quanto a remoção. [acquire(false)] o adquire imediatamente: retorna [false] se outra requisição já o detiver, e essa requisição, que perde a corrida, falha. O bloco [finally] libera o lock em todos os casos. A comparação ignora maiúsculas e minúsculas ([strcasecmp] retorna 0 para duas strings iguais sem diferenciar maiúsculas de minúsculas) e os espaços ao redor da entrada ([trim]).
11.12.6. src/Security/AttemptLimiter.php
| <?php
// =========================================================================
// src/Security/AttemptLimiter.php: segunda barreira 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, esse 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
// LOGIN_MAX_FAILURES_IP falhas, somando todos os logins (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 uma 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 erra a senha não bloqueia os
// colegas - e por isso que os limites podem ser ajustados (arquivo .env).
//
// Os contadores são os dos três limiters do componente RateLimiter, declarados
// em config/packages/framework.yaml e armazenados no cache.
// =========================================================================
namespace App\Security;
use Symfony\Component\RateLimiter\LimiterInterface;
use Symfony\Component\RateLimiter\RateLimiterFactoryInterface;
class AttemptLimiter
{
// as fábricas dos limiters [login], [login_ip] e [registration]: o nome
// do parâmetro designa o limiter (veja o exemplo 27)
public function __construct(
private RateLimiterFactoryInterface $loginLimiter,
private RateLimiterFactoryInterface $loginIpLimiter,
private RateLimiterFactoryInterface $registrationLimiter,
) {
}
// login
// número de minutos de bloqueio restantes (0 = a tentativa é permitida)
public function loginBlockMinutes(string $ip, string $login): int
{
return max(self::remainingMinutes($this->ipLoginLimiter($ip, $login)),
self::remainingMinutes($this->loginIpLimiter->create($ip)));
}
// consume(): mais uma falha; a primeira abre uma janela de
// LOGIN_BLOCK_MINUTES minutos, ao fim da qual o contador recomeça do zero
public function loginFailure(string $ip, string $login): void
{
$this->ipLoginLimiter($ip, $login)->consume();
$this->loginIpLimiter->create($ip)->consume();
}
// um login bem-sucedido zera o contador DESTE login
public function loginSuccess(string $ip, string $login): void
{
$this->ipLoginLimiter($ip, $login)->reset();
}
// cadastro
public function registrationBlockMinutes(string $ip): int
{
return self::remainingMinutes($this->registrationLimiter->create($ip));
}
public function registrationSuccess(string $ip): void
{
$this->registrationLimiter->create($ip)->consume();
}
// mecânica comum
// o limiter do par (IP, login): create(key) retorna um limiter que tem seu
// próprio contador, sob essa chave
private function ipLoginLimiter(string $ip, string $login): LimiterInterface
{
return $this->loginLimiter->create("$ip|".mb_strtolower(trim($login)));
}
// consume(0) consulta o limiter sem consumir nada: sobrou algum "token"?
// getRetryAfter: a data do fim da janela atual; os segundos que
// restam até lá são arredondados PARA CIMA até o minuto: 30 s -> "1 minute"
private static function remainingMinutes(LimiterInterface $limiter): int
{
$state = $limiter->consume(0);
if ($state->getRemainingTokens() > 0) {
return 0;
}
return max(1, (int) ceil(($state->getRetryAfter()->getTimestamp() - time()) / 60));
}
}
|
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 componente [RateLimiter] do [Symfony]. Os três limitadores são declarados em [config/packages/framework.yaml] (política [fixed_window]: uma janela de duração fixa, aberta pelo primeiro token consumido); o serviço recebe suas fábricas, identificadas pelos nomes dos parâmetros (linhas 34–38): [$loginLimiter] para o limitador [login], [$loginIpLimiter] para [login_ip], [$registrationLimiter] para [registration]. Uma fábrica usa seu método [create(key)] para criar um limitador que tem seu próprio contador sob essa chave. Duas regras:
- o login (linhas 44–62): cada falha (CAPTCHA ou senha incorretos) é contada duas vezes: para o par (endereço IP, login) e somente 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 (configuração [LOGIN_MAX_FAILURES_IP]), considerando 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 seus vizinhos. [consume()] consome um token (conta como uma tentativa malsucedida); a primeira tentativa 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 ([reset]);
- a criação de contas (linhas 66–74): no máximo 10 contas por hora por endereço IP (configuração [REGISTRATION_MAX_PER_HOUR]);
- linhas 80–83: a chave de um limitador. O login é convertido em minúsculas: [Admin] e [admin] são considerados iguais (como no banco de dados; veja sua collation);
- Linhas 88–95: [consume(0)] consulta o limitador sem consumir nenhum token (exemplo 27): se ainda houver tokens, a tentativa é permitida; caso contrário, [getRetryAfter] retorna a data de término da janela atual, e o número de segundos restantes até lá é arredondado para cima, até o minuto seguinte ([ceil]): se restam 30 segundos, é exibido “1 minuto”. A mensagem exibida depende disso: “Too many failed attempts. Try again in 15 minutes.”
Os contadores dos limitadores são armazenados no cache: são compartilhados por todas as requisições e sobrevivem a uma reinicialização do servidor. O comando [php bin/console cache:pool:clear cache.rate_limiter] zera todos eles (útil durante o desenvolvimento, quando você acaba bloqueando a si mesmo); [php bin/console cache:clear], que limpa todo o diretório [var/cache], faz o mesmo.
11.12.7. src/Security/RegistrationPass.php e RegistrationPassRequired.php
| <?php
// =========================================================================
// src/Security/RegistrationPass.php: o "pass" da criação de conta.
//
// Para abrir a página "Create a patient account", é preciso antes ter copiado o
// captcha da página de login (veja RegistrationController, POST
// /register/access). O servidor então emite um pass:
// - um identificador aleatório, armazenado em um cookie HttpOnly;
// - válido por 15 minutos (o tempo de preencher o formulário, mesmo com várias
// tentativas após erros de entrada);
// - consumido assim que uma conta é criada: UM captcha resolvido = NO MÁXIMO UMA conta.
// Um robô não consegue criar contas em série.
//
// Sem um pass válido, GET e POST /register redirecionam para a página de
// login (veja o atributo #[RegistrationPassRequired] e o listener
// CheckRegistrationPass): digitar a URL /register diretamente não permite
// contornar o captcha.
//
// Como os captchas, os passes vivem no cache.
// =========================================================================
namespace App\Security;
use Psr\Cache\CacheItemPoolInterface;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Component\HttpFoundation\Response;
class RegistrationPass
{
public const COOKIE = 'rdvmedecins_registration';
// o cookie só é enviado pelo navegador para os endereços /register...
private const PATH = '/register';
// duração de vida de um pass, em minutos
private const LIFETIME = 15;
public function __construct(
private CacheItemPoolInterface $cache,
#[Autowire(env: 'bool:COOKIE_SECURE')] private bool $cookieSecure,
) {
}
// emite um novo pass; retorna o cookie que o transporta
public function issue(): Cookie
{
$id = bin2hex(random_bytes(12));
$item = $this->cache->getItem("pass.$id");
$this->cache->save($item->set(true)->expiresAfter(self::LIFETIME * 60));
return Cookie::create(self::COOKIE, $id)
->withExpires(time() + self::LIFETIME * 60)
->withPath(self::PATH)
->withSecure($this->cookieSecure)
->withHttpOnly(true)
->withSameSite(Cookie::SAMESITE_LAX);
}
// true se [$id] for um pass existente e não expirado; hasItem: o
// cache tem este item?
public function isValid(?string $id): bool
{
return $id !== null && ctype_xdigit($id) && $this->cache->hasItem("pass.$id");
}
// o pass foi usado: nós o esquecemos...
public function consume(?string $id): void
{
if ($id !== null && ctype_xdigit($id)) {
$this->cache->deleteItem("pass.$id");
}
}
// ... e seu cookie é limpo por um cookie de mesmo nome e mesmo caminho, já expirado
public static function clearCookie(Response $response): Response
{
$response->headers->clearCookie(self::COOKIE, self::PATH);
return $response;
}
}
|
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 fica em outra página ([/register]): como o sistema pode 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 leva a lugar nenhum.
- Linhas 46–57: o cookie tem o caminho [/register] ([withPath]): o navegador o envia apenas para endereços que começam com esse caminho. Ele contém apenas um identificador aleatório — impossível de adivinhar — e somente o cache do servidor sabe se ele é válido: o cookie não precisa ser assinado;
- linhas 61–64: [hasItem] indica se o cache contém uma entrada (não expirada) sob essa chave;
- linhas 75–79: 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 dois cookies distintos.
| <?php
// src/Security/RegistrationPassRequired.php: um ATRIBUTO PHP próprio nosso (veja o
// exemplo 24), colocado nas actions que exigem um pass de criação de conta
// (veja RegistrationPass e o listener CheckRegistrationPass).
namespace App\Security;
use Attribute;
#[Attribute(Attribute::TARGET_METHOD)]
class RegistrationPassRequired
{
}
|
Um atributo [PHP] de nossa própria criação, como o [#[Timed]] do Exemplo 24, é aplicado às actions que exigem um passe. Ele é lido pelo listener [CheckRegistrationPass].
11.13. Os listeners: src/EventListener
Três listeners de eventos do kernel (Exemplo 24), armazenados na pasta [src/EventListener], como é costume. O atributo [#[AsEventListener]], colocado na classe, especifica o evento e a prioridade; o método chamado é então [__invoke].
11.13.1. src/EventListener/SetLanguage.php
| <?php
// =========================================================================
// src/EventListener/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.
//
// Prioridade 40: o listener roda ANTES do roteamento do Symfony (prioridade 32). Ele
// roda, portanto, para TODAS as requisições, mesmo aquelas que não levam a nenhuma
// rota (páginas 404, 405...): a página de erro delas fica no idioma certo. Pelo
// mesmo motivo, ele também define o idioma do próprio translator, o que de outra forma seria feito por
// um listener do Symfony (prioridade 15) que um erro de roteamento impediria
// de rodar.
// =========================================================================
namespace App\EventListener;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Contracts\Translation\LocaleAwareInterface;
#[AsEventListener(event: KernelEvents::REQUEST, priority: 40)]
class SetLanguage
{
// o cookie que lembra o idioma escolhido (veja LanguageController)
public const COOKIE = 'rdvmedecins_language';
// os idiomas suportados (pasta translations); o primeiro é o idioma padrão
public const LANGUAGES = ['en', 'fr'];
// LocaleAwareInterface: um serviço que tem um idioma, aqui o translator
public function __construct(private LocaleAwareInterface $translator)
{
}
public function __invoke(RequestEvent $event): void
{
$request = $event->getRequest();
$language = $request->cookies->get(self::COOKIE);
$language = in_array($language, self::LANGUAGES, true) ? $language : self::LANGUAGES[0];
$request->setLocale($language);
$this->translator->setLocale($language);
}
}
|
O idioma da requisição (Exemplo 22): o idioma do cookie, se for um idioma suportado; caso contrário, o idioma padrão (inglês). Uma diferença em relação ao Exemplo 22: prioridade 40 (linha 21), que é maior que a do roteamento (32). O listener do Exemplo 22 (prioridade 20) era executado depois do roteamento; para uma URL que não corresponde a nenhuma rota, o roteamento lança uma exceção antes do listener, e a página 404 ficaria em inglês mesmo para um usuário francófono. Pelo mesmo motivo, o próprio listener define o idioma do tradutor (linha 41), o que normalmente é feito por um listener do [Symfony] ([LocaleAwareListener]), também posicionado depois do roteamento. [LocaleAwareInterface] é a interface dos serviços que têm um idioma; o tradutor é um deles, e é esse tradutor que o [Symfony] injeta aqui.
11.13.2. src/EventListener/CheckRegistrationPass.php
| <?php
// =========================================================================
// src/EventListener/CheckRegistrationPass.php: as actions marcadas com
// o atributo #[RegistrationPassRequired] (GET e POST /register) exigem um
// pass válido (veja src/Security/RegistrationPass.php); caso contrário, volta para
// a página de login, com uma mensagem. Digitar a URL
// /register diretamente, portanto, não permite contornar o captcha.
//
// Um listener de kernel.controller (veja o exemplo 24): a action foi escolhida, mas
// ainda não foi chamada. Para recusar, ele a SUBSTITUI (setController) por uma
// função que retorna um redirecionamento.
// =========================================================================
namespace App\EventListener;
use App\Security\RegistrationPass;
use App\Security\RegistrationPassRequired;
use App\Web\Flash;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpKernel\Event\ControllerEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
#[AsEventListener(event: KernelEvents::CONTROLLER)]
class CheckRegistrationPass
{
public function __construct(
private RegistrationPass $passes,
private Flash $flash,
private UrlGeneratorInterface $urls,
) {
}
public function __invoke(ControllerEvent $event): void
{
if ($event->getAttributes(RegistrationPassRequired::class) === []) {
return;
}
if (! $this->passes->isValid($event->getRequest()->cookies->get(RegistrationPass::COOKIE))) {
$this->flash->error('ERRORS.CAPTCHA_BEFORE_ACCOUNT');
$url = $this->urls->generate('login');
$event->setController(fn () => new RedirectResponse($url));
}
}
}
|
Um listener de [kernel.controller] (exemplo 24): a action é selecionada, mas ainda não foi chamada.
- linhas 37–39: [getAttributes(class)] retorna os atributos dessa classe presentes na action: uma lista vazia; a action não exige um token; o listener não faz nada;
- linhas 40–44: nenhum token válido: uma mensagem é exibida, e a action é substituída ([setController]) por uma função que redireciona para a página de login. O kernel chama essa função no lugar da action. A URL é calculada fora da arrow function, que, portanto, requer apenas uma variável.
O listener recebe seus serviços por meio do construtor: um listener é um serviço, criado pelo contêiner, assim como os controllers.
11.13.3. src/EventListener/ErrorPage.php
| <?php
// =========================================================================
// src/EventListener/ErrorPage.php: como os erros viram páginas HTML
// (veja o exemplo 24). Três casos:
// 1. uma InvalidSession (conta excluída desde o login) -> volta para a página
// de login, como em uma sessão expirada;
// 2. um erro HTTP: requisição inválida (400), papel insuficiente (403), 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 Symfony já a gravou no
// log, com a pilha de chamadas; em produção (APP_ENV=prod),
// o usuário vê a página de erro 500 - nunca a pilha de chamadas; em
// desenvolvimento, a página de debug do Symfony.
//
// Prioridade -10: depois do listener do Symfony que grava a exceção no log
// (0) e depois do de segurança (1), que transforma uma recusa de acesso em um
// redirecionamento para a página de login (visitante anônimo) ou em um erro
// 403 (usuário autenticado); antes daquele que constrói a página de erro do Symfony
// (-128).
// =========================================================================
namespace App\EventListener;
use App\Security\AuthService;
use App\Security\InvalidSession;
use App\Web\Flash;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Twig\Environment;
#[AsEventListener(event: KernelEvents::EXCEPTION, priority: -10)]
class ErrorPage
{
public function __construct(
private Environment $twig,
private Flash $flash,
private UrlGeneratorInterface $urls,
// o modo debug (APP_ENV=dev): o parâmetro kernel.debug do contêiner
#[Autowire('%kernel.debug%')] private bool $debug,
) {
}
public function __invoke(ExceptionEvent $event): void
{
$e = $event->getThrowable();
if ($e instanceof InvalidSession) {
$this->flash->error('ERRORS.SESSION_EXPIRED');
$event->setResponse(AuthService::clearCookie(new RedirectResponse($this->urls->generate('login'))));
return;
}
if ($e instanceof HttpExceptionInterface) {
$event->setResponse($this->page($e->getStatusCode()));
return;
}
// uma anomalia real: em desenvolvimento, a página de debug do Symfony
if (! $this->debug) {
$event->setResponse($this->page(500));
}
}
// a página de erro, com o código HTTP do erro e sua mensagem
private function page(int $code): Response
{
$message = match ($code) {
400 => 'ERRORS.BAD_REQUEST',
403 => 'ERRORS.FORBIDDEN',
404, 405 => 'ERRORS.NOT_FOUND',
419 => 'ERRORS.PAGE_EXPIRED',
default => 'ERRORS.SERVER_ERROR',
};
return new Response($this->twig->render('error.html.twig', ['pageTitle' => 'ERROR_PAGE.TITLE',
'code' => $code, 'message' => $message]), $code);
}
}
|
Como os erros se tornam páginas HTML: este é o listener [ErrorPage] do Exemplo 24, ampliado. Ele escuta o evento [kernel.exception], com prioridade -10 (linha 37): depois do listener do [Symfony] que registra a exceção no log (prioridade 0) e depois do listener do componente de segurança (prioridade 1), que converte uma negação de acesso em uma chamada ao ponto de entrada (visitante anônimo) ou em um erro 403 (usuário autenticado com um papel inadequado); antes do manipulador que gera a página de erro do [Symfony] (-128). Três casos:
- linhas 53–57: uma [InvalidSession] (a conta foi excluída): a mensagem de “sessão expirada”, a exclusão do cookie do token e a página de login;
- linhas 59–62: um erro HTTP: [HttpExceptionInterface] é a interface das exceções com código HTTP ([NotFoundHttpException], [AccessDeniedHttpException], [HttpException(419)]...), obtido por [getStatusCode]. A página de erro é exibida, mostrando esse código;
- linhas 65–67: qualquer outra exceção é um erro verdadeiro. Em desenvolvimento ([kernel.debug], exemplo 24), o listener não faz nada: será exibida a página de depuração do [Symfony], mostrando a pilha de chamadas. Em produção, a página de erro 500: o usuário nunca vê a pilha de chamadas, que o log já registrou;
- linhas 71–82: a página de erro, view [error.html.twig], mostrando o código e a chave da mensagem. [match] ([PHP] 8) seleciona um valor com base em outro, usando igualdade estrita; [404, 405 =>] cobre dois casos; [default] trata todos os outros. O código 405 (Method Not Allowed: um GET em um endereço que só aceita POST) é exibido como um erro de "página não encontrada".
11.14. O controller de login
11.14.1. src/Controller/AuthController.php
| <?php
// =========================================================================
// src/Controller/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, a verificação da senha.
// NUNCA verificamos a senha de uma tentativa recusada nas etapas 1 ou 2:
// um robô, portanto, não aprende nada ao insistir.
// =========================================================================
namespace App\Controller;
use App\Entity\Role;
use App\Security\AuthService;
use App\Security\CaptchaService;
use App\Security\AttemptLimiter;
use App\Security\ConnectedUser;
use App\Web\BaseController;
use App\Web\Message;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
class AuthController extends BaseController
{
public function __construct(
private AuthService $auth,
private CaptchaService $captchas,
private AttemptLimiter $limiter,
) {
}
// a página inicial de cada papel, logo após o login: o nome da rota dela
public static function homePage(Role $role): string
{
return $role === Role::USER ? 'area' : 'schedule';
}
// -----------------------------------------------------------------------
// GET /
// A rota é pública: o usuário, se houver, é conhecido
// ($this->getUser()), mas nada é exigido.
// -----------------------------------------------------------------------
#[Route('/', name: 'home', methods: ['GET'])]
public function home(): Response
{
$user = $this->getUser();
return $this->redirectToRoute($user instanceof ConnectedUser
? self::homePage($user->role) : 'login');
}
// -----------------------------------------------------------------------
// GET /login[?login=xxx]: o parâmetro opcional preenche previamente o campo de login
// (usado logo após a criação de uma conta, veja RegistrationController)
// -----------------------------------------------------------------------
#[Route('/login', name: 'login', methods: ['GET'])]
public function form(Request $request): Response
{
// já logado (token ainda válido): direto para a página inicial
$user = $this->getUser();
if ($user instanceof ConnectedUser) {
return $this->redirectToRoute(self::homePage($user->role));
}
// mb_substr: 30 caracteres no máximo
return $this->page(mb_substr($request->query->getString('login'), 0, 30), null);
}
// -----------------------------------------------------------------------
// POST /login
// -----------------------------------------------------------------------
#[Route('/login', name: 'login_submit', methods: ['POST'])]
public function logIn(Request $request): Response
{
$this->checkCsrf($request);
$login = $request->request->getString('login');
$password = $request->request->getString('password');
$ip = (string) $request->getClientIp();
// 1. 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->request->getString('captchaId'),
$request->request->getString('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);
$response = $this->redirectToRoute(self::homePage($user->getRole()));
$response->headers->setCookie($this->auth->tokenCookie($user));
return $response;
}
// -----------------------------------------------------------------------
// POST /logout: limpa o cookie do token e depois 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.
// -----------------------------------------------------------------------
#[Route('/logout', name: 'logout', methods: ['POST'])]
public function logOut(Request $request): Response
{
$this->checkCsrf($request);
return AuthService::clearCookie($this->redirectToRoute('login'));
}
// o formulário, sempre com um NOVO captcha (cada imagem é usada uma única
// vez); o login digitado é exibido novamente, nunca a senha. Um erro:
// o código 422, como para um formulário inválido (veja o exemplo 19)
private function page(string $login, ?Message $error): Response
{
return $this->render('login.html.twig', ['pageTitle' => 'LOGIN.TITLE', 'error' => $error,
'login' => $login, 'captcha' => $this->captchas->generate()],
new Response(status: $error ? 422 : 200));
}
}
|
O controller de login, baseado no Exemplo 27. Ele herda da classe [BaseController] da aplicação (tratada adiante), que por sua vez é uma subclasse de [AbstractController].
- linhas 41–44: a página inicial de cada papel, com o nome de sua rota: “My area” para um paciente e a agenda para os demais;
- linhas 51–57: o endereço [/] leva à página inicial do papel ou à página de login. A rota é pública (regra [access_control] de [security.yaml]): [getUser()] retorna o usuário estabelecido pelo autenticador, se houver, sem exigir nada. [redirectToRoute] (exemplo 04) cria um redirecionamento para uma rota nomeada;
- linhas 63–73: um usuário que já está conectado vai diretamente para sua página inicial. O parâmetro opcional [login] da URL preenche previamente o campo (após a criação da conta); [mb_substr] o trunca em 30 caracteres;
- Linhas 78–110: o processo de login, na ordem mostrada no Exemplo 27: o token anti-CSRF (tratado adiante), eventuais bloqueios, o CAPTCHA e a senha. A senha nunca é verificada em uma tentativa rejeitada pelo limitador ou pelo CAPTCHA: um bot não aprende nada ao insistir. [getClientIp] retorna o endereço IP do cliente. Se a tentativa falhar, a página é renderizada diretamente (sem redirecionamento): o formulário exibido novamente sempre tem um novo CAPTCHA e o login informado. O erro é um objeto [Message] (veja adiante), composto de uma chave e seus parâmetros, exibido na parte inferior da página. Se houver sucesso, o contador de logins é zerado, e o navegador é redirecionado para a página inicial do papel, com o cookie do token ([headers->setCookie]);
- linhas 117–122: o logout exclui o cookie do token (exemplo 25). Ele só aceita POST, junto com o token anti-CSRF: um simples link colocado em outro site não pode desconectar o usuário sem que ele saiba;
- linhas 127–132: a página de login. O terceiro parâmetro de [render] é a resposta a ser preenchida: um erro é retornado com o código 422 (Unprocessable Content), como em um formulário inválido (exemplo 19). [new Response(status: ...)] usa um argumento nomeado ([PHP] 8): os dois primeiros parâmetros do construtor mantêm seus valores padrão.
A página de login recebe a variável [pageTitle], a chave de tradução do título da página: todas as actions a passam para sua view, para o template (veja adiante).
11.15. A camada web: serviços compartilhados
A pasta [src/Web] contém os elementos compartilhados pelos controllers.
11.15.1. src/Web/ApplicationModel.php
| <?php
// =========================================================================
// src/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 clientes são lidas do banco de dados uma vez e depois servidas
// do cache.
//
// Por que o CACHE do Symfony, 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 serviço compartilhado, mas um serviço só vive durante UMA requisição.
// O cache, por outro lado, é 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
// envolvida logo em seguida; 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 apenas aqui.
// =========================================================================
namespace App\Web;
use App\Domain\DoctorDaySchedule;
use App\Entity\Client;
use App\Entity\Slot;
use App\Entity\Doctor;
use App\Entity\Appointment;
use App\Business\PersonData;
use App\Business\Business;
use App\Business\BusinessService;
use DateTimeImmutable;
use Symfony\Contracts\Cache\CacheInterface;
// mesmo contrato da camada de negócio
class ApplicationModel implements Business
{
private const DOCTORS = 'rdvmedecins.doctors';
private const CLIENTS = 'rdvmedecins.clients';
// CacheInterface: o cache da aplicação (o serviço cache.app), visto por meio
// da interface dos "contracts" do Symfony, mais simples que a do PSR-6
public function __construct(private BusinessService $business, private CacheInterface $cache)
{
}
// leituras a partir do cache
// get(key, function): 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. As entidades são armazenadas ali serializadas (veja serialize): cada
// requisição que as lê recebe cópias delas, que o Doctrine não rastreia
public function getAllDoctors(): array
{
return $this->cache->get(self::DOCTORS, fn () => $this->business->getAllDoctors());
}
public function getAllClients(): array
{
return $this->cache->get(self::CLIENTS, fn () => $this->business->getAllClients());
}
// o médico cuja conta de usuário é [$userId] - usado para pré-selecionar,
// para um médico logado, a própria agenda dele. array_find: o primeiro elemento
// do array que satisfaz a condição (null se não houver nenhum)
public function getDoctorByUserId(int $userId): ?Doctor
{
return array_find($this->getAllDoctors(), fn (Doctor $d) => $d->getAccount()->getId() === $userId);
}
// delegações simples
public function getAllSlots(int $doctorId): array
{
return $this->business->getAllSlots($doctorId);
}
public function getDoctorDayAppointments(int $doctorId, DateTimeImmutable $day): array
{
return $this->business->getDoctorDayAppointments($doctorId, $day);
}
public function getClientById(int $id): ?Client
{
return $this->business->getClientById($id);
}
public function getDoctorById(int $id): ?Doctor
{
return $this->business->getDoctorById($id);
}
public function getAppointmentById(int $id): ?Appointment
{
return $this->business->getAppointmentById($id);
}
public function getSlotById(int $id): ?Slot
{
return $this->business->getSlotById($id);
}
public function getDoctorDaySchedule(int $doctorId, DateTimeImmutable $day): ?DoctorDaySchedule
{
return $this->business->getDoctorDaySchedule($doctorId, $day);
}
// sem cache aqui: o que importa são os dados mais recentes (um paciente que
// acabou de modificar ou excluir a própria conta)
public function getClientByUserId(int $userId): ?Client
{
return $this->business->getClientByUserId($userId);
}
public function getClientUpcomingAppointments(int $clientId): array
{
return $this->business->getClientUpcomingAppointments($clientId);
}
public function addAppointment(DateTimeImmutable $day, Slot $slot, Client $client): Appointment
{
return $this->business->addAppointment($day, $slot, $client);
}
public function deleteAppointment(Appointment $appointment): void
{
$this->business->deleteAppointment($appointment);
}
// gravações => cache esquecido
// (delete: o item é removido do cache)
public function addDoctor(PersonData $data): Doctor
{
$doctor = $this->business->addDoctor($data);
$this->cache->delete(self::DOCTORS);
return $doctor;
}
public function editDoctor(int $id, PersonData $data): Doctor
{
$doctor = $this->business->editDoctor($id, $data);
$this->cache->delete(self::DOCTORS);
return $doctor;
}
public function deleteDoctor(int $id): void
{
$this->business->deleteDoctor($id);
$this->cache->delete(self::DOCTORS);
}
public function addClient(PersonData $data): Client
{
$client = $this->business->addClient($data);
$this->cache->delete(self::CLIENTS);
return $client;
}
public function editClient(int $id, PersonData $data): Client
{
$client = $this->business->editClient($id, $data);
$this->cache->delete(self::CLIENTS);
return $client;
}
public function deleteClient(int $id): void
{
$this->business->deleteClient($id);
$this->cache->delete(self::CLIENTS);
}
}
|
Todas as versões da aplicação têm uma classe chamada [ApplicationModel]: um único ponto de entrada 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 na agenda, a lista de pacientes na janela de reserva e as páginas de administração) e raramente mudam.
O que muda no [PHP] é o significado de “em memória”. Uma aplicação [Java], [C#] ou [Python] permanece na 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 serviço compartilhado, mas existe apenas durante uma única requisição (Exemplo 23). As listas são, portanto, armazenadas no cache do [Symfony] (exemplo 20), que é compartilhado por todas as requisições.
- Linha 34: a classe implementa a interface [Business], assim como [BusinessService]: os controllers chamam os mesmos métodos, independentemente de qual classe os atenda;
- Linha 42: desta vez, o cache é recebido por meio da interface [CacheInterface] dos “contracts” do [Symfony] (o mesmo serviço [cache.app]), que é mais simples do que a interface PSR-6 dos exemplos;
- Linhas 52–60: [get(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 consulta que precisa da lista a lê diretamente do banco de dados; as consultas seguintes a encontram no cache. O cache armazena o array de entidades em forma serializada (exemplo 20) e o reconstrói na leitura, junto com os relacionamentos carregados (a conta de cada pessoa). As entidades reconstruídas são cópias que o entity manager do [Doctrine] não rastreia: elas servem para exibição, nunca para escrita (a camada de negócio sempre relê do banco de dados o que vai modificar);
- linhas 65–68: o médico associado a uma conta, recuperado da lista em cache por [array_find] (exemplo 06);
- Linhas 72–127: os demais métodos do contrato [Business] simplesmente delegam para a camada de negócio. O cliente de uma conta ([getClientByUserId]) é sempre recuperado do banco de dados, e não do cache: os dados mais recentes têm prioridade (um paciente que acabou de modificar ou excluir sua conta);
- Linhas 132–170: as atualizações. Cada atualização feita por um médico ou um cliente não grava a lista correspondente ([delete]): a próxima consulta que precisar dela a recuperará do banco de dados. Esse é o objetivo de um ponto de entrada único: a regra “uma escrita atualiza o cache” é implementada somente aqui. Se a escrita falhar (por exemplo, uma [BusinessException]), a lista não é sobrescrita: ela não mudou. Uma aplicação que escreve no banco de dados por outro caminho (outro programa, outra versão da aplicação usando o mesmo banco de dados) deixaria o cache desatualizado: [php bin/console cache:pool:clear cache.app] o limparia.
11.15.2. src/Web/Message.php e Flash.php
| <?php
// src/Web/Message.php: uma mensagem a traduzir: sua chave e seus parâmetros.
// As views a exibem com {{ message.key|trans(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 se tornam [Message], que as views traduzem para o idioma da página.
| <?php
// =========================================================================
// src/Web/Flash.php: as mensagens "flash": uma mensagem a exibir UMA 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 nenhuma página, ele redireciona (302) para uma página GET; a
// mensagem, por outro lado, precisa sobreviver ao redirecionamento.
//
// O Symfony as armazena na SESSÃO (arquivos da pasta var/sessions, veja
// config/packages/framework.yaml).
//
// Uma mensagem não contém um texto, mas uma CHAVE de tradução e seus parâmetros
// (um objeto Message): ela é traduzida na hora da exibição, no idioma da
// página (veja templates/fragments). Duas listas: os sucessos (exibidos no topo da
// página) e os erros (exibidos no rodapé).
// =========================================================================
namespace App\Web;
use Symfony\Component\HttpFoundation\RequestStack;
class Flash
{
// a pilha de requisições, para alcançar a sessão da requisição atual
public function __construct(private RequestStack $requests)
{
}
public function success(string $key, array $params = []): void
{
$this->add('success', $key, $params);
}
public function error(string $key, array $params = []): void
{
$this->add('errors', $key, $params);
}
// getFlashBag: o "bag" das mensagens flash da sessão; add(type, message)
// adiciona uma mensagem à lista desse tipo (veja o exemplo 20)
private function add(string $type, string $key, array $params): void
{
$this->requests->getSession()->getFlashBag()->add($type, new Message($key, $params));
}
}
|
Mensagens flash (exemplo 20): uma mensagem colocada na sessão por uma ação, exibida pela próxima página e depois descartada. Isso complementa o padrão Post/Redirect/Get, que todos os formulários da aplicação seguem. Há dois tipos: as mensagens de sucesso são exibidas no topo da página, e as mensagens de erro, na parte inferior.
- Linha 25: a pilha de requisições ([RequestStack]), um serviço do [Symfony] que conhece a requisição atual e, portanto, sua sessão. Um serviço compartilhado não pode receber a própria requisição por meio do construtor: ele é criado uma única vez e pode ser usado para várias requisições (uma requisição principal e suas subrequisições);
- linhas 41–44: o “bag” de mensagens flash da sessão ([getFlashBag]), no qual [add(type, message)] completa a lista desse tipo. É isso que o método [addFlash] de [AbstractController] faz (Exemplo 20); transformá-lo em um serviço permite colocar uma mensagem fora de um controller, como no authenticator ou nos listeners.
Os objetos [Message] são armazenados como estão na sessão: o [PHP] serializa os dados da sessão (Exemplo 20) e os reconstrói na requisição seguinte. Nas views, [app.flashes('errors')] exibe a lista de mensagens desse tipo e as remove da sessão.
11.15.3. src/Web/BaseController.php
| <?php
// =========================================================================
// src/Web/BaseController.php: a classe pai dos controllers da aplicação. Ela
// herda de AbstractController (veja o exemplo 03) e acrescenta a verificação do
// token anti-CSRF dos formulários escritos à mão (veja o exemplo 21).
// =========================================================================
namespace App\Web;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\Exception\HttpException;
abstract class BaseController extends AbstractController
{
// o identificador do token anti-CSRF dos formulários escritos à mão: apenas um
// para toda a aplicação (nas views: csrf_token('rdvmedecins')). Os
// formulários do componente Form têm cada um o seu próprio
public const CSRF = 'rdvmedecins';
// -----------------------------------------------------------------------
// um token anti-CSRF ausente ou errado: a página provavelmente foi exibida antes
// da expiração da sessão, que continha o token. Erro 419, o código (não oficial,
// mas difundido) de uma página expirada: o listener ErrorPage exibe
// "The page has expired: reload it, then try again."
// -----------------------------------------------------------------------
protected function checkCsrf(Request $request): void
{
if (! $this->isCsrfTokenValid(self::CSRF, $request->request->getString('_token'))) {
throw new HttpException(419, 'invalid anti-CSRF token');
}
}
}
|
A classe pai dos controllers. Os formulários escritos manualmente nas views (login, logout, exclusões, reservas etc.) incluem um token anti-CSRF (Exemplo 21) com o identificador [rdvmedecins]: um único identificador basta aqui, já que todas essas ações exigem um usuário autenticado ou um CAPTCHA. Cada formulário do componente Form tem seu próprio token, validado pelo componente.
Um token ausente ou inválido interrompe a ação com um erro 419 (linhas 27–32), o código (não oficial, mas amplamente usado) para uma página que expirou: o token é armazenado na sessão, e uma página exibida antes do fim da sessão contém um token que o servidor não reconhece mais. O listener [ErrorPage] então exibe “A página expirou: recarregue-a e tente novamente.” [HttpException] é a exceção HTTP genérica: seu construtor recebe o código e uma mensagem (destinada ao log, não ao usuário).
11.15.4. src/Web/Utils.php
| <?php
// =========================================================================
// src/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).
// Os métodos ESTÁTICOS são chamados sem um objeto (Utils::iso($day)); os outros
// precisam de serviços (a requisição atual, a segurança...): a classe é um
// serviço, que os controllers recebem por meio do construtor.
// =========================================================================
namespace App\Web;
use App\Entity\Client;
use App\Security\InvalidSession;
use App\Security\ConnectedUser;
use DateTimeImmutable;
use IntlDateFormatter;
use Symfony\Bundle\SecurityBundle\Security;
use Symfony\Component\HttpFoundation\RequestStack;
class Utils
{
// Security: o serviço de segurança do Symfony, que conhece o usuário da
// requisição atual (aquele estabelecido pelo autenticador)
public function __construct(
private RequestStack $requests,
private Security $security,
private ApplicationModel $application,
) {
}
// datas
// a data, se [$text] for uma data existente no formato yyyy-mm-dd; null caso contrário.
// createFromFormat aceita "2026-02-30" (que vira 2 de março): por isso
// verificamos que a data lida de volta é escrita exatamente como o texto recebido
public static function validDate(mixed $text): ?DateTimeImmutable
{
if (! is_string($text) || ! preg_match('/^\d{4}-\d{2}-\d{2}$/', $text)) {
return null;
}
// "!Y-m-d": o ponto de exclamação zera o horário para a meia-noite
$date = DateTimeImmutable::createFromFormat('!Y-m-d', $text);
return $date !== false && $date->format('Y-m-d') === $text ? $date : null;
}
public static function iso(DateTimeImmutable $day): string
{
return $day->format('Y-m-d');
}
// "mercredi 23 septembre 2026" / "Wednesday 23 September 2026", conforme o idioma
// da requisição (veja o exemplo 16). O padrão ICU: EEEE o dia da semana por
// extenso, d o dia, MMMM o mês por extenso, y o ano
public function formatDay(DateTimeImmutable $day): string
{
$language = $this->requests->getCurrentRequest()?->getLocale() ?? 'en';
return (new IntlDateFormatter($language, IntlDateFormatter::NONE, IntlDateFormatter::NONE,
pattern: 'EEEE d MMMM y'))->format($day);
}
// entrada
// "3" -> 3; "", "abc", "-2", "+2", null -> null
public static function positiveInteger(mixed $value): ?int
{
if (! is_string($value) || ! preg_match('/^\d{1,9}$/', $value)) {
return null;
}
$n = (int) $value;
return $n > 0 ? $n : null;
}
// usuário
// o usuário logado. As actions protegidas só são chamadas se ele existir;
// por precaução, a ausência dele é tratada como uma sessão expirada
public function user(): ConnectedUser
{
$user = $this->security->getUser();
return $user instanceof ConnectedUser ? $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, significa que a conta foi excluída desde o login
// enquanto o token ainda é válido: tratamos como uma sessão
// expirada (veja InvalidSession).
// -----------------------------------------------------------------------
public function connectedPatient(): Client
{
return $this->application->getClientByUserId($this->user()->userId)
?? throw new InvalidSession();
}
}
|
Algumas funções utilitárias. Os métodos static são chamados sem um objeto ([Utils::iso($day)]); os demais exigem serviços: a classe é, portanto, também um serviço, que os controllers recebem por meio do construtor.
- Linhas 38–46: a data de um parâmetro [yyyy-mm-dd] ou [null]. Duas verificações: o formato (uma expressão regular) e, em seguida, a existência da data. [createFromFormat] é tolerante: 30 de fevereiro vira 2 de março. Relemos então 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). [mixed]: qualquer tipo;
- linhas 56–61: “Saturday 26 September 2026” ou “samedi 26 septembre 2026”, conforme o idioma da requisição. [IntlDateFormatter] (exemplo 16), com um padrão (pattern) em vez de um estilo: os códigos são os da biblioteca ICU, [EEEE] para o dia da semana por extenso, [d] para o dia, [MMMM] para o mês por extenso e [y] para o ano. O parâmetro [pattern] é passado pelo nome: os parâmetros que o precedem na assinatura, e para os quais nenhum valor é fornecido, mantêm seus valores padrão;
- linhas 66–73: um parâmetro de requisição pode ser uma string, como [null], ou até um array ([?doctorId[]=1], exemplo 10). Somente dígitos são aceitos (até nove, para evitar estouro de capacidade), e o número deve ser estritamente positivo;
- linhas 79–83: o usuário logado, determinado pelo authenticator, é retornado pelo serviço [Security] do [Symfony]. As ações protegidas só são chamadas para um usuário autenticado, mas a ausência do usuário ainda é tratada como uma sessão expirada. [throw] é uma expressão ([PHP] 8): pode aparecer no operador [? :];
- linhas 95–99: o paciente (o [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.15.5. src/Twig/ViewsExtension.php
| <?php
// =========================================================================
// src/Twig/ViewsExtension.php: uma extensão Twig (veja o exemplo 16), que acrescenta
// às views as funções de que TODAS as páginas precisam:
// - user() : o usuário logado (ou null), para a barra de navegação;
// - titles() : os possíveis títulos de uma pessoa (Mr, Mme, Melle).
// =========================================================================
namespace App\Twig;
use App\Form\PersonFieldsType;
use App\Security\AuthService;
use App\Security\ConnectedUser;
use Symfony\Bundle\SecurityBundle\Security;
use Symfony\Component\HttpFoundation\RequestStack;
use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;
class ViewsExtension extends AbstractExtension
{
public function __construct(
private Security $security,
private RequestStack $requests,
private AuthService $auth,
) {
}
public function getFunctions(): array
{
return [
new TwigFunction('user', $this->user(...)),
new TwigFunction('titles', fn () => PersonFieldsType::TITLES),
];
}
// -----------------------------------------------------------------------
// o usuário estabelecido pelo firewall. Uma página de erro 404 ou 405 é
// construída ANTES do firewall (o roteamento, que falha, vem antes dele, veja o
// exemplo 24): o usuário é então lido diretamente do token, para que
// a barra de navegação da página de erro fique completa
// -----------------------------------------------------------------------
public function user(): ?ConnectedUser
{
$user = $this->security->getUser();
if ($user instanceof ConnectedUser) {
return $user;
}
$token = $this->requests->getMainRequest()?->cookies->getString(AuthService::COOKIE);
return $token ? $this->auth->currentUser($token) : null;
}
}
|
Uma extensão do [Twig] (Exemplo 16), que adiciona às views duas funções de que todas as páginas precisam:
- [user()]: o usuário logado, ou [null], para a barra de navegação. Normalmente, é o do serviço [Security] (linha 44). No entanto, uma página de erro 404 ou 405 é gerada antes que o firewall examine a requisição: o roteamento, que falha, tem precedência sobre ele (Exemplo 24). O usuário é então recuperado diretamente do token (linhas 48–49), para que a barra de navegação da página de erro fique completa. [getMainRequest] fornece a requisição principal; o operador [?->] retorna [null] sem chamar o método se o objeto for [null];
- [titles()]: os títulos possíveis para uma pessoa ([Mr], [Mme], [Melle]), uma constante da classe do formulário de pessoa (veja abaixo).
[$this->user(...)] (linha 31) é a sintaxe das first-class functions ([PHP] 8.1): ela cria uma função que chama o método [user] desse objeto. A extensão é declarada automaticamente como [Twig], assim como no Exemplo 16: o container reconhece uma classe que herda de [AbstractExtension].
11.16. Dicionários
Os textos da interface são os mesmos das outras versões da aplicação, que os armazenavam em arquivos JSON aninhados:
| {
"LOGIN": {
"TITLE": "Login",
"USERNAME": "Login"
}
}
|
A versão [Flask] os “achatava” na inicialização: [LOGIN.TITLE] referia-se ao texto [Login]. Os dicionários YAML do [Symfony] fazem o mesmo (exemplo 22): as chaves aninhadas são separadas por pontos. Portanto, simplesmente convertemos os arquivos JSON para YAML e substituímos os parâmetros [{{name}}] das outras versões pelos da sintaxe ICU, [{name}] (o sufixo [+intl-icu] nos nomes dos arquivos, exemplo 22):
| APP:
TITLE: 'RdvMedecins'
LOGOUT: 'Log out'
DOCTORS:
ADDED: 'Doctor {name} has been added (login: {login}).'
ERRORS:
TOO_MANY_ATTEMPTS: 'Too many failed attempts. Try again in {minutes, plural, one {# minute} other {# minutes}}.'
|
Os arquivos [translations/messages+intl-icu.fr.yaml] e [messages+intl-icu.en.yaml] não são reproduzidos aqui. Uma chave é representada por [{{ 'APP.LOGOUT'|trans }}] em uma view, e um texto parametrizado por [{{ 'DOCTORS.ADDED'|trans({name: ..., login: ...}) }}]. Uma chave ausente do dicionário é exibida como está, o que sinaliza imediatamente uma omissão (e o comando [php bin/console debug:translation fr] lista as chaves usadas pelas views que estão ausentes do dicionário). O ICU permite algo que as versões anteriores não conseguiam fazer: o plural (“1 minute”, “15 minutes”), usando o formato [plural] (exemplo 22). Uma entrada de texto foi adicionada: [ERRORS.PAGE_EXPIRED], a mensagem da página 419, que não existe nas outras versões.
As mensagens de erro dos formulários também são chaves nesses dicionários ([ERRORS.FIRSTNAME_REQUIRED]...): o componente de validação as traduz no domínio [messages], usando a linha [translation_domain: messages] de [framework.yaml]. Seus parâmetros correspondem às restrições: [{limit}], para o comprimento mínimo da senha.
Os formulários de “pessoa” são formulários do componente Form (exemplos 18 e 19): uma classe de tipo descreve os campos e suas restrições; a ação cria o formulário ([createForm]), passa a requisição a ele ([handleRequest]) e depois verifica se ele foi enviado e se é válido ([isSubmitted], [isValid]). Um formulário inválido é exibido novamente, mostrando a entrada do usuário e as mensagens de erro abaixo dos campos (exceto as senhas: um campo [PasswordType] nunca é reexibido). O token anti-CSRF de cada formulário é verificado pelo próprio componente.
| <?php
// =========================================================================
// src/Form/PersonFieldsType.php: os campos dos formulários de "pessoa" e suas
// restrições (veja os exemplos 18 e 19). Três formulários compartilham os mesmos
// campos de identidade (título, nome, sobrenome):
//
// PersonFieldsType título, nome, sobrenome
// ├─ PersonType + login / senha OPCIONAIS, version
// │ (o ADMIN adiciona ou modifica um médico / cliente)
// ├─ RegistrationType + login / senha / confirmação OBRIGATÓRIOS
// │ (um paciente cria sua conta)
// └─ MyAccountType + login, nova senha opcional, senha
// ATUAL OBRIGATÓRIA, version
// (um paciente modifica sua conta)
//
// As classes filhas HERDAM desta (no sentido do PHP): o buildForm delas
// chama primeiro o do pai e depois acrescenta seus campos.
//
// Os formulários não têm classe de dados (data_class, veja o exemplo 19): a
// entrada validada é um array associativo, que o método data() transforma em
// PersonData para a camada de negócio.
//
// Os rótulos, os textos de ajuda e as mensagens de erro são CHAVES dos
// dicionários: o componente Form traduz os rótulos e os textos de ajuda, o
// componente Validator as mensagens (veja config/packages/framework.yaml).
// Em sequência: as restrições são verificadas em ordem, e a verificação
// para na primeira que não for satisfeita - apenas uma mensagem por campo.
// Os comprimentos máximos são os das colunas SQL.
// =========================================================================
namespace App\Form;
use App\Business\PersonData;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\CallbackTransformer;
use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\Validator\Constraints as Assert;
abstract class PersonFieldsType extends AbstractType
{
public const TITLES = ['Mr', 'Mme', 'Melle'];
// login: letras minúsculas, dígitos, 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;
public function buildForm(FormBuilderInterface $builder, array $options): void
{
$builder
// array_combine: ['Mr' => 'Mr', ...], o rótulo e o valor de cada
// opção; choice_translation_domain false: os títulos não são traduzidos
->add('title', ChoiceType::class, [
'label' => 'PERSONS.TITLE_LABEL',
'choices' => array_combine(self::TITLES, self::TITLES),
'choice_translation_domain' => false,
'invalid_message' => 'ERRORS.INVALID_TITLE',
'constraints' => [new Assert\NotBlank(message: 'ERRORS.INVALID_TITLE')],
])
->add('first_name', TextType::class, [
'label' => 'PERSONS.FIRSTNAME_LABEL',
'attr' => ['maxlength' => 20],
'constraints' => [new Assert\Sequentially([
new Assert\NotBlank(message: 'ERRORS.FIRSTNAME_REQUIRED'),
new Assert\Length(max: 20, maxMessage: 'ERRORS.FIRSTNAME_TOO_LONG'),
])],
])
->add('last_name', TextType::class, [
'label' => 'PERSONS.LASTNAME_LABEL',
'attr' => ['maxlength' => 20],
'constraints' => [new Assert\Sequentially([
new Assert\NotBlank(message: 'ERRORS.LASTNAME_REQUIRED'),
new Assert\Length(max: 20, maxMessage: 'ERRORS.LASTNAME_TOO_LONG'),
])],
]);
}
// as opções comuns: um formulário inválido devolvido como está ao navegador,
// sem validação pelo próprio navegador (veja o exemplo 19: é o SERVIDOR
// que tem a palavra final); a mensagem de um token anti-CSRF errado
public function configureOptions(OptionsResolver $resolver): void
{
$resolver->setDefaults([
'attr' => ['novalidate' => 'novalidate'],
'csrf_message' => 'ERRORS.PAGE_EXPIRED',
]);
}
// -----------------------------------------------------------------------
// o campo de login, comum aos formulários filhos. Um login é sempre em
// minúsculas: um TRANSFORMER (CallbackTransformer) converte a entrada ANTES
// da validação. A primeira função dele transforma o valor do formulário em
// texto exibido (aqui, nada a fazer), a segunda transforma a entrada no valor do formulário
// -----------------------------------------------------------------------
protected static function addLogin(FormBuilderInterface $builder, array $options): void
{
$builder->add('login', TextType::class, ['label' => 'PERSONS.LOGIN_LABEL', 'required' => false,
'attr' => ['maxlength' => 30, 'autocomplete' => 'off'], ...$options]);
$builder->get('login')->addModelTransformer(new CallbackTransformer(
fn (?string $login) => $login,
fn (?string $login) => $login === null ? null : mb_strtolower($login)));
}
// a entrada validada -> os dados esperados pela camada de negócio. Os campos
// vazios são null (o componente Form os converte assim)
public static function data(array $input): PersonData
{
$password = $input['password'] ?? null;
return new PersonData($input['title'], $input['last_name'], $input['first_name'],
$input['login'] ?? null, $password === '' ? null : $password,
isset($input['version']) && ctype_digit((string) $input['version']) ? (int) $input['version'] : null);
}
}
|
Três formulários compartilham os mesmos campos de identidade (título, nome e 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 pai comum é abstrata; cada uma de suas classes filhas estende esses campos. Nenhum desses formulários tem uma classe de dados (a opção [data_class] do Exemplo 19): seus dados consistem em um array associativo, com um elemento por campo.
- linhas 44–50: as regras de entrada, na forma de constantes, que também são lidas pelas views (a lista de títulos, pela função [titles()] da extensão [Twig]);
- linhas 57–63: o título, uma lista ([ChoiceType], Exemplo 18). [array_combine] gera o array [['Mr' => 'Mr', ...]]: o rótulo de cada opção e seu valor. [choice_translation_domain: false]: os títulos não são chaves de tradução. [invalid_message]: a mensagem para um valor que não faz parte da lista (uma requisição construída manualmente);
- Linhas 64–79: nome e sobrenome. A restrição [Sequentially] (exemplo 09) verifica suas restrições em ordem e para na primeira que não for atendida: apenas uma mensagem por campo. [Length(max: 20)]: no máximo 20 caracteres; o comprimento da coluna é SQL; o atributo HTML [maxlength] impede que mais caracteres sejam digitados. Os espaços no início e no fim de uma entrada são removidos pelo próprio componente Form (a opção [trim] de um campo de texto é definida como [true]), e uma entrada vazia se torna [null]; um campo com a opção [PasswordType], por outro lado, não é limpo: os espaços podem fazer parte de uma senha;
- Linhas 85–91: opções comuns. [novalidate] desativa as validações do navegador ([required], [maxlength]...) quando o formulário é enviado: o servidor realiza a validação, e seu resultado é definitivo (exemplo 19). [csrf_message]: a mensagem para um token anti-CSRF inválido, a da página 419;
- linhas 99–106: o login, comum aos três formulários, ao qual cada um acrescenta suas próprias opções (o operador [...] adiciona os elementos de um array a outro; uma chave presente em ambos assume o último valor). Um login é sempre em minúsculas: um transformer converte a entrada antes de ela ser validada. Um model transformer ([addModelTransformer]) tem duas funções: a primeira transforma os dados do formulário em um valor exibido (neste caso, nenhuma ação é necessária) e a segunda transforma o valor digitado em dados do formulário. [CallbackTransformer] cria um transformer a partir dessas duas funções;
- Linhas 110–116: a entrada validada é convertida em [PersonData] para a camada de negócio: a camada de negócio não conhece os formulários. Uma senha vazia é [null] (inalterada, ou o valor padrão); a versão (o campo oculto do bloqueio otimista, por exemplo, 28) é um inteiro ou [null].
| <?php
// src/Form/PersonType.php: o formulário de um médico ou de um cliente (ADMIN):
// login e senha OPCIONAIS (veja src/Business/PersonData.php).
namespace App\Form;
use Symfony\Component\Form\Extension\Core\Type\HiddenType;
use Symfony\Component\Form\Extension\Core\Type\PasswordType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\Validator\Constraints as Assert;
class PersonType extends PersonFieldsType
{
public function buildForm(FormBuilderInterface $builder, array $options): void
{
parent::buildForm($builder, $options);
$creation = $options['creation'];
// um campo vazio é aceito: as restrições só se aplicam a um valor informado
self::addLogin($builder, [
'help' => $creation ? 'PERSONS.LOGIN_HELP_CREATE' : 'PERSONS.LOGIN_HELP_EDIT',
'constraints' => [new Assert\Regex(self::LOGIN_FORMAT, message: 'ERRORS.INVALID_LOGIN')],
]);
$builder->add('password', PasswordType::class, [
'label' => 'PERSONS.PASSWORD_LABEL',
'required' => false,
'help' => $creation ? 'PERSONS.PASSWORD_HELP_CREATE' : 'PERSONS.PASSWORD_HELP_EDIT',
'attr' => ['maxlength' => 72, 'autocomplete' => 'new-password'],
// 72 caracteres no máximo: além disso, o bcrypt ignora o resto
'constraints' => [new Assert\Length(max: 72, maxMessage: 'ERRORS.PASSWORD_TOO_LONG')],
]);
// modificação: a versão do registro exibido, em um campo oculto (o
// bloqueio otimista)
if (! $creation) {
$builder->add('version', HiddenType::class);
}
}
// uma opção própria nossa (veja o exemplo 28): formulário de criação ou formulário de modificação
public function configureOptions(OptionsResolver $resolver): void
{
parent::configureOptions($resolver);
$resolver->setDefaults(['creation' => true]);
}
}
|
O formulário do administrador. [parent::buildForm] (linha 17) adiciona os campos da classe pai; em seguida vêm o nome de usuário e a senha, que são opcionais: uma restrição se aplica apenas a um valor que foi digitado (exceto [NotBlank]), de modo que um campo vazio é aceito. [Regex] valida o formato do login; [Length(max: 72)] limita o comprimento da senha: o [bcrypt] considera apenas os primeiros 72 bytes (Exemplo 25). A opção [creation] (linhas 40–44), uma opção que criamos, declarada com seu valor padrão (exemplo 28), distingue entre criação e modificação: as dicas de ajuda diferem (“Opcional: por padrão, o sobrenome em minúsculas”, “Deixe vazio para mantê-la inalterada”), e somente a modificação tem o campo oculto de versão.
| <?php
// src/Form/RegistrationType.php: "Create a patient account": login, senha e
// confirmação OBRIGATÓRIOS.
namespace App\Form;
use Symfony\Component\Form\Extension\Core\Type\PasswordType;
use Symfony\Component\Form\Extension\Core\Type\RepeatedType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Validator\Constraints as Assert;
class RegistrationType extends PersonFieldsType
{
public function buildForm(FormBuilderInterface $builder, array $options): void
{
parent::buildForm($builder, $options);
self::addLogin($builder, [
'required' => true,
'help' => 'REGISTRATION.LOGIN_HELP',
'attr' => ['maxlength' => 30, 'autocomplete' => 'username'],
'constraints' => [new Assert\Sequentially([
new Assert\NotBlank(message: 'ERRORS.LOGIN_REQUIRED'),
new Assert\Regex(self::LOGIN_FORMAT, message: 'ERRORS.INVALID_LOGIN'),
])],
]);
$builder->add('password', RepeatedType::class, self::repeatedPassword(true));
}
// -----------------------------------------------------------------------
// a senha e sua confirmação: um campo REPEATED (veja o exemplo 19), cujas
// duas entradas devem ser idênticas (caso contrário: invalid_message). Comum ao
// cadastro (obrigatório) e à conta do paciente (opcional).
// {limit}: na mensagem PASSWORD_TOO_SHORT, o comprimento mínimo;
// help_translation_parameters: os parâmetros do texto de ajuda
// -----------------------------------------------------------------------
public static function repeatedPassword(bool $required): array
{
$length = new Assert\Length(min: self::PASSWORD_MIN, max: 72,
minMessage: 'ERRORS.PASSWORD_TOO_SHORT', maxMessage: 'ERRORS.PASSWORD_TOO_LONG');
return [
'type' => PasswordType::class,
'required' => $required,
'invalid_message' => 'ERRORS.PASSWORDS_DIFFER',
'first_options' => [
'label' => $required ? 'PERSONS.PASSWORD_LABEL' : 'MY_ACCOUNT.NEW_PASSWORD_LABEL',
'help' => $required ? 'REGISTRATION.PASSWORD_HELP' : 'PERSONS.PASSWORD_HELP_EDIT',
'help_translation_parameters' => ['min' => self::PASSWORD_MIN],
],
'second_options' => ['label' => 'ACCOUNT.CONFIRMATION_LABEL'],
'options' => ['attr' => ['maxlength' => 72, 'autocomplete' => 'new-password']],
'constraints' => $required
? [new Assert\Sequentially([new Assert\NotBlank(message: 'ERRORS.PASSWORD_REQUIRED'), $length])]
: [$length],
];
}
}
|
Criação de uma conta de paciente: o login e a senha são obrigatórios, e a senha deve ser confirmada. A senha é um campo repetido ([RepeatedType], exemplo 19): dois campos [PasswordType], cujas entradas devem ser idênticas (caso contrário, a mensagem [invalid_message] é exibida abaixo do primeiro). Suas opções são geradas por um método estático, compartilhado com “Gerenciar minha conta” (linhas 36–55):
- [first_options] e [second_options]: as opções de cada um dos dois campos; [options]: as opções que eles têm em comum;
- [help_translation_parameters]: os parâmetros do texto de ajuda, “Pelo menos {min} caracteres.”;
- o comprimento mínimo é exigido apenas para a senha escolhida por um paciente (6 caracteres). A mensagem [ERRORS.PASSWORD_TOO_SHORT] contém [{limit}], o parâmetro que a restrição [Length] fornece à sua mensagem;
- [autocomplete="new-password"]: o navegador se oferece para gerar uma senha, em vez de preencher o campo com a senha salva.
| <?php
// src/Form/MyAccountType.php: "Manage my account" (um paciente): login obrigatório,
// nova senha opcional, senha ATUAL OBRIGATÓRIA.
namespace App\Form;
use Symfony\Component\Form\Extension\Core\Type\HiddenType;
use Symfony\Component\Form\Extension\Core\Type\PasswordType;
use Symfony\Component\Form\Extension\Core\Type\RepeatedType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Validator\Constraints as Assert;
class MyAccountType extends PersonFieldsType
{
public function buildForm(FormBuilderInterface $builder, array $options): void
{
parent::buildForm($builder, $options);
self::addLogin($builder, [
'required' => true,
'attr' => ['maxlength' => 30, 'autocomplete' => 'username'],
'constraints' => [new Assert\Sequentially([
new Assert\NotBlank(message: 'ERRORS.LOGIN_REQUIRED'),
new Assert\Regex(self::LOGIN_FORMAT, message: 'ERRORS.INVALID_LOGIN'),
])],
]);
// opcional: vazio = senha inalterada
$builder->add('password', RepeatedType::class, RegistrationType::repeatedPassword(false));
// a senha ATUAL, exigida para qualquer modificação da conta; mapped
// false: ela não faz parte dos dados do formulário, é lida separadamente
$builder->add('current_password', PasswordType::class, [
'label' => 'MY_ACCOUNT.CURRENT_PASSWORD_LABEL',
'help' => 'MY_ACCOUNT.CURRENT_PASSWORD_HELP',
'mapped' => false,
'attr' => ['maxlength' => 72, 'autocomplete' => 'current-password'],
'constraints' => [new Assert\NotBlank(message: 'ERRORS.CURRENT_PASSWORD_REQUIRED')],
]);
$builder->add('version', HiddenType::class);
}
}
|
“Gerenciar minha conta”: a nova senha é opcional (vazia: inalterada), e a senha atual é obrigatória. [mapped: false] (linha 33): a senha atual não faz parte dos dados do formulário ([getData()] não a contém); a ação a lê separadamente, por meio de [$form->get('current_password')->getData()]. Ela não é validada aqui, mas pela ação: uma senha incorreta deve ser contada pelo limitador de tentativas como um login malsucedido. (O [Symfony] tem uma restrição, [UserPassword], que compara a senha digitada com a do usuário logado; essa restrição não se aplica aqui: nosso usuário logado, [ConnectedUser], não contém o hash de sua senha.)
11.18. Templates de views
A pasta [src/Views] contém os templates de views: 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 (“Ms. Marie PELISSIER”, “8:00 – 8:20”) e já filtrados de acordo com o papel do usuário; as views apenas colocam esses dados no HTML. Todas essas classes são do tipo [readonly] e têm apenas propriedades, inicializadas pelo construtor. A pasta é excluída dos serviços ([config/services.yaml]): são dados, não serviços.
| <?php
// src/Views/OptionView.php: uma opção de uma lista suspensa (médico, paciente).
//
// A pasta src/Views contém os "view models": objetos
// construídos de uma só vez por uma action, que a view apenas lê. Regra
// seguida por todas as páginas: nenhuma lógica nas views. As actions
// 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 de uma lista suspensa: o ID, o rótulo e se a opção está selecionada.
| <?php
// src/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 apenas se o botão "Cancel" for exibido
public ?int $appointmentId,
) {
}
}
|
Uma entrada da agenda: um horário e o que o usuário logado está autorizado a ver e a 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 “Reservar” deve ser exibido; [appointmentId] indica se o botão “Cancelar” deve ser exibido.
| <?php
// src/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
// src/Views/BookingView.php: a caixa de diálogo de reserva 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 entre os quais escolher
public array $clients,
// USER: o paciente é ele mesmo
public ?string $patient,
) {
}
}
|
A agenda exibida e a janela de reserva: para o administrador e os médicos, a lista de pacientes para escolha; para um paciente, o próprio nome. O comentário [/** @param list<ScheduleRow> $rows */] especifica, para editores e ferramentas de análise, o conteúdo do array: o [PHP] só consegue declarar o tipo [array].
| <?php
// src/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");
}
}
|
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
// src/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 próxima consulta na área do paciente.
11.19. A camada web: rotas e controllers
11.19.1. Rotas
As rotas são descritas pelos atributos [#[Route]] dos controllers (Exemplo 02), que são carregados pelo arquivo [config/routes.yaml]. O comando [debug:router] as lista todas, junto com seus nomes, métodos e caminhos:
| $ php bin/console debug:router
--------------------- ---------- ----------------------
Name Method Path
--------------------- ---------- ----------------------
home GET /
login GET /login
login_submit POST /login
logout POST /logout
clients_list GET /clients
clients_add GET|POST /clients/add
clients_edit GET|POST /clients/{id}/edit
clients_delete POST /clients/{id}/delete
doctors_list GET /doctors
doctors_add GET|POST /doctors/add
doctors_edit GET|POST /doctors/{id}/edit
doctors_delete POST /doctors/{id}/delete
language GET /language/{code}
area GET /my-area
area_cancel POST /my-area/cancel
account GET|POST /my-account
account_delete POST /my-account/delete
registration_access POST /register/access
registration GET|POST /register
schedule GET /schedule
schedule_book POST /schedule/book
schedule_cancel POST /schedule/cancel
--------------------- ---------- ----------------------
|
As URLs correspondem às 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 código sempre gera a URL com base nos nomes das rotas ([redirectToRoute('login')], [path('schedule')] nas views, Exemplo 04): mudar uma URL exige modificar apenas o seu atributo [#[Route]].
As regras de acesso não estão nos controllers, mas nas regras [access_control] de [config/packages/security.yaml], como mostrado acima: uma regra por prefixo de URL ([^/(doctors|clients)] para o administrador, [^/my-] para os pacientes...), e uma regra final que exige um usuário autenticado para todas as outras URLs. As URLs da aplicação foram escolhidas com essa finalidade: todas as páginas de um mesmo papel começam da mesma forma. Uma URL que não corresponde a nenhuma rota retorna uma página 404, até mesmo para um visitante anônimo; uma requisição GET dirigida a uma URL que existe apenas como POST ([/logout]) resulta em uma página 405, apresentada como “página não encontrada” (handler [ErrorPage]).
11.19.2. src/Controller/LanguageController.php
| <?php
// =========================================================================
// src/Controller/LanguageController.php: GET /language/fr, GET /language/en: os dois
// botões FR / EN da barra de navegação. Rota pública: é preciso poder
// trocar de idioma antes de fazer login.
//
// A escolha é lembrada em um cookie: a cada requisição seguinte, o listener
// SetLanguage o lê de novo e define o idioma da requisição. Depois voltamos à
// página de onde viemos (veja o exemplo 22).
// =========================================================================
namespace App\Controller;
use App\EventListener\SetLanguage;
use App\Web\BaseController;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
class LanguageController extends BaseController
{
public function __construct(#[Autowire(env: 'bool:COOKIE_SECURE')] private bool $cookieSecure)
{
}
// {code} é limitado aos idiomas suportados (requirements): /language/de resulta em uma página 404
#[Route('/language/{code}', name: 'language', requirements: ['code' => 'fr|en'], methods: ['GET'])]
public function change(Request $request, string $code): Response
{
$response = $this->redirect($this->originPage($request));
$response->headers->setCookie(Cookie::create(SetLanguage::COOKIE, $code)
->withExpires(new \DateTimeImmutable('+1 year'))
->withSecure($this->cookieSecure)
->withHttpOnly(true)
->withSameSite(Cookie::SAMESITE_LAX));
return $response;
}
// -----------------------------------------------------------------------
// a página anterior, segundo o cabeçalho HTTP "Referer" enviado pelo navegador.
// Apenas o caminho dela é mantido (/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: recusado também
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 na barra de navegação: a escolha do idioma é armazenada em um cookie por um ano (exemplo 22), e então o navegador volta à página de onde veio. O cookie é [HttpOnly]: o [JavaScript] da página não precisa lê-lo. Ele não é assinado: o listener [SetLanguage] verifica seu valor, e um valor desconhecido resulta em inglês (veja o capítulo sobre intervalos).
- Linha 29: [requirements: ['code' => 'fr|en']] aceita apenas esses dois valores para o parâmetro [{code}]: [/language/de] não corresponde a nenhuma rota (página 404);
- Linhas 47–59: a página anterior é indicada pelo cabeçalho
HTTP ***[Referer], que o navegador envia com a requisição. Esse dado é fornecido pelo cliente e, portanto, é suspeito: redirecionar para uma URL completa vinda da requisição permitiria que um atacante enviasse o usuário para o próprio site por meio de um link para [/language/fr] que inclua 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 voltar para [/language/...]: seria um loop.
11.19.3. src/Controller/ScheduleController.php
| <?php
// =========================================================================
// src/Controller/ScheduleController.php: a página da agenda: escolha de um médico e
// de um dia, agenda desse médico nesse dia, reserva 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 caixa de
// diálogo de reserva
// do horário 7 aberta
// POST /schedule/book cria uma consulta
// POST /schedule/cancel cancela uma consulta
//
// A página inteira é descrita pela sua URL: ela pode ser recarregada, adicionada aos favoritos,
// o botão "Back" 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 na lista | |
// | USER (paciente)| "Booked", ou o nome DELE se for | para si mesmo, se | não (*) |
// | | a consulta dele | não tiver consulta | |
// | | | futura | |
//
// (*) o paciente cancela a consulta dele a partir da página "My area".
//
// CONFIDENCIALIDADE: para um paciente, o nome dos OUTROS pacientes não é
// simplesmente ocultado pela view - ele nunca é repassado à view. O HTML enviado
// ao navegador, portanto, não o contém, nem mesmo oculto (um simples "View page
// source" o revelaria).
//
// Nenhuma reserva no passado: o botão "Book" só aparece para
// hoje e os dias seguintes (e a camada de negócio a recusaria
// de qualquer forma).
//
// Segurança: todas as URLs /schedule exigem um usuário autenticado, e
// /schedule/cancel o papel ADMIN ou DOCTOR (veja config/packages/security.yaml).
// =========================================================================
namespace App\Controller;
use App\Domain\DoctorDaySchedule;
use App\Entity\Client;
use App\Entity\Person;
use App\Entity\Role;
use App\Business\Dates;
use App\Business\BusinessException;
use App\Views\ScheduleView;
use App\Views\ScheduleRow;
use App\Views\OptionView;
use App\Views\BookingView;
use App\Web\ApplicationModel;
use App\Web\BaseController;
use App\Web\Flash;
use App\Web\Message;
use App\Web\Utils;
use DateTimeImmutable;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
use Symfony\Component\Routing\Attribute\Route;
#[Route('/schedule')]
class ScheduleController extends BaseController
{
public function __construct(
private ApplicationModel $application,
private Utils $utils,
private Flash $flash,
) {
}
// -----------------------------------------------------------------------
// GET /schedule
// Os parâmetros da URL são lidos em estado bruto ($request->query), para distinguir um
// parâmetro AUSENTE (null) de um parâmetro VAZIO (?doctorId=).
// -----------------------------------------------------------------------
#[Route('', name: 'schedule', methods: ['GET'])]
public function show(Request $request): Response
{
$error = null;
$user = $this->utils->user();
$rights = $this->rights();
// o dia: o da URL se for válido, caso contrário hoje
$day = Dates::today();
$rawDay = $request->query->get('day');
if ($rawDay !== null) {
$requestedDay = Utils::validDate($rawDay);
if ($requestedDay !== null) {
$day = $requestedDay;
} else {
$error = 'ERRORS.INVALID_DATE';
}
}
$bookableDay = $day >= Dates::today();
// o médico: o da URL; na falta dele, para um médico logado, ele mesmo
$rawDoctorId = $request->query->get('doctorId');
$doctorId = Utils::positiveInteger($rawDoctorId);
if ($rawDoctorId === null && $user->role === Role::DOCTOR) {
$doctorId = $this->application->getDoctorByUserId($user->userId)?->getId();
}
// a lista suspensa dos médicos
$doctors = array_map(fn (Person $d) => self::option($d, $d->getId() === $doctorId),
$this->application->getAllDoctors());
// a agenda, se um médico estiver escolhido (e a data for válida)
$schedule = null;
if ($doctorId !== null && $error === null) {
$doctorSchedule = $this->application->getDoctorDaySchedule($doctorId, $day);
if ($doctorSchedule === null) {
$error = 'ERRORS.DOCTOR_NOT_FOUND';
} else {
$schedule = $this->scheduleView($doctorSchedule, $rights, $bookableDay);
}
}
// a caixa de diálogo de reserva: somente se o horário pedido puder ser reservado
// 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->get('book'));
if ($schedule !== null && $slotId !== null) {
$row = array_find($schedule->rows,
fn (ScheduleRow $r) => $r->slotId === $slotId && $r->bookable);
if ($row !== null) {
$booking = new BookingView(
$row->slotId,
$row->time,
$rights['manager']
? array_map(fn (Client $c) => self::option($c, false), $this->application->getAllClients())
: [],
$rights['patient']?->label());
}
}
return $this->render('schedule.html.twig', [
'pageTitle' => 'SCHEDULE.PAGE_TITLE',
'error' => $error ? new Message($error) : null,
'doctors' => $doctors,
'doctorId' => $doctorId,
'day' => Utils::iso($day),
'schedule' => $schedule,
'booking' => $booking,
// a agenda exibida, sem caixa de diálogo de reserva
'backUrl' => $doctorId !== null ? $this->scheduleUrl($doctorId, $day) : $this->generateUrl('schedule'),
'info' => $this->patientInfo($rights, $schedule),
]);
}
// -----------------------------------------------------------------------
// POST /schedule/book campos: doctorId, day, slotId, clientId
//
// Para um paciente (USER), o campo clientId é IGNORADO: ele sempre reserva
// para si mesmo. Confiar em um campo enviado pelo navegador
// permitiria a um paciente astuto reservar em nome de outro.
//
// Padrão "Post / Redirect / Get": qualquer que seja o resultado, nenhuma página é construída
// aqui - deixamos uma mensagem flash e redirecionamos para a agenda
// (veja o exemplo 20).
// -----------------------------------------------------------------------
#[Route('/book', name: 'schedule_book', methods: ['POST'])]
public function book(Request $request): Response
{
$this->checkCsrf($request);
[$doctorId, $day] = $this->requestedSchedule($request);
$slotId = Utils::positiveInteger($request->request->get('slotId'));
if ($doctorId === null || $slotId === null) {
// -> página "invalid request" (veja src/EventListener/ErrorPage.php)
throw new BadRequestHttpException('invalid schedule or slot');
}
$user = $this->utils->user();
if ($user->isPatient()) {
$client = $this->utils->connectedPatient();
} else {
$clientId = Utils::positiveInteger($request->request->get('clientId'));
if ($clientId === null) {
// nenhum paciente escolhido: a caixa de diálogo de reserva é aberta novamente
$this->flash->error('ERRORS.CHOOSE_PATIENT');
return $this->redirect($this->scheduleUrl($doctorId, $day, $slotId));
}
$client = $this->application->getClientById($clientId);
}
$slot = $this->application->getSlotById($slotId);
if ($client === null) {
$this->flash->error('ERRORS.PATIENT_NOT_FOUND');
} elseif ($slot === null || $slot->getDoctor()->getId() !== $doctorId) {
$this->flash->error('ERRORS.SLOT_NOT_FOUND');
} else {
try {
// 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);
$this->flash->success('SCHEDULE.BOOKED');
} catch (BusinessException $e) {
// mesma regra, mas uma mensagem na 2ª pessoa quando é o próprio
// paciente que reserva ("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()) {
$this->flash->error('SCHEDULE.ALREADY_BOOKED_INFO');
} else {
$this->flash->error($e->key, $e->params);
}
}
}
return $this->redirect($this->scheduleUrl($doctorId, $day));
}
// -----------------------------------------------------------------------
// POST /schedule/cancel campos: appointmentId, doctorId, day
// (um paciente cancela A consulta DELE a partir de "My area", não daqui)
// -----------------------------------------------------------------------
#[Route('/cancel', name: 'schedule_cancel', methods: ['POST'])]
public function cancel(Request $request): Response
{
$this->checkCsrf($request);
[$doctorId, $day] = $this->requestedSchedule($request);
$appointmentId = Utils::positiveInteger($request->request->get('appointmentId'));
if ($doctorId === null || $appointmentId === null) {
throw new BadRequestHttpException('invalid schedule or appointment');
}
$appointment = $this->application->getAppointmentById($appointmentId);
if ($appointment === null) {
// já cancelada (por outra pessoa, ou duplo clique)
$this->flash->error('ERRORS.APPOINTMENT_NOT_FOUND');
} else {
$this->application->deleteAppointment($appointment);
$this->flash->success('SCHEDULE.CANCELLED');
}
return $this->redirect($this->scheduleUrl($doctorId, $day));
}
// -----------------------------------------------------------------------
// quem está logado e o que essa pessoa 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 (! $this->utils->user()->isPatient()) {
return ['manager' => true, 'patient' => null, 'patientCanBook' => false];
}
$patient = $this->utils->connectedPatient();
$upcoming = $this->application->getClientUpcomingAppointments($patient->getId());
return ['manager' => false, 'patient' => $patient, 'patientCanBook' => $upcoming === []];
}
// -----------------------------------------------------------------------
// a agenda do médico, formatada para a view - e filtrada conforme os direitos
// -----------------------------------------------------------------------
private function scheduleView(DoctorDaySchedule $doctorSchedule, array $rights, bool $bookableDay): ScheduleView
{
$doctorId = $doctorSchedule->doctor->getId();
$day = $doctorSchedule->day;
$rows = [];
foreach ($doctorSchedule->doctorDaySlots as $dds) {
$slot = $dds->slot;
$appointment = $dds->appointment;
$free = $appointment === null;
// a consulta do paciente logado?
$mine = $appointment !== null && $rights['patient'] !== null
&& $appointment->getClient()->getId() === $rights['patient']->getId();
$rows[] = new ScheduleRow(
slotId: $slot->getId(),
time: $slot->time(),
free: $free,
// O ponto de confidencialidade: um paciente só recebe o nome da
// PRÓPRIA consulta; para as outras, null (a view exibe "Booked")
patient: $appointment !== null && ($rights['manager'] || $mine) ? $appointment->getClient()->label() : null,
mine: $mine,
bookable: $free && $bookableDay && ($rights['manager'] || $rights['patientCanBook']),
bookUrl: $this->scheduleUrl($doctorId, $day, $slot->getId()),
appointmentId: $appointment !== null && $rights['manager'] ? $appointment->getId() : null);
}
return new ScheduleView($doctorSchedule->doctor->label(), $this->utils->formatDay($day), $rows);
}
// funções utilitárias
// os campos ocultos doctorId / day dos formulários POST; [null, null] se
// forem inválidos
private function requestedSchedule(Request $request): array
{
$doctorId = Utils::positiveInteger($request->request->get('doctorId'));
$day = Utils::validDate($request->request->get('day'));
return $doctorId === null || $day === null ? [null, null] : [$doctorId, $day];
}
// /schedule?doctorId=1&day=2026-09-23[&book=7]: generateUrl acrescenta ao fim
// da URL os parâmetros que não são parâmetros do caminho (veja o exemplo 16)
private function scheduleUrl(int $doctorId, DateTimeImmutable $day, ?int $book = null): string
{
$params = ['doctorId' => $doctorId, 'day' => Utils::iso($day)];
if ($book !== null) {
$params['book'] = $book;
}
return $this->generateUrl('schedule', $params);
}
private static function option(Person $p, bool $selected): OptionView
{
return new OptionView($p->getId(), $p->label(), $selected);
}
// -----------------------------------------------------------------------
// 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 A CONSULTA DELE
// aparecer na agenda exibida (em azul): é o caso logo
// depois de ele a ter reservado, quando a mensagem ficaria fora de lugar.
// array_any: pelo menos um elemento satisfaz a condição?
// -----------------------------------------------------------------------
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. O atributo [#[Route('/schedule')]] da classe (linha 66) especifica o início do caminho de todas as suas rotas (exemplo 02): a rota [''] é [/schedule] em si.
11.19.3.1. A URL da 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] também abre a janela de reserva do horário 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 reserva de consulta é aberta por um simples link e fechada por um link para a mesma página sem o parâmetro [book].
11.19.3.2. GET /schedule
Linhas 81–154:
- os parâmetros da URL são lidos como estão ([$request->query->get('day')]), sem validação pelo [Symfony]: um parâmetro ausente ([null]) não é um erro (o sistema assume por padrão hoje ou “nenhum médico”); uma data inválida é um erro, exibido na parte inferior da página (a seleção do médico e do dia permanece visível, mas a agenda não é exibida); um número de médico ou de horário que não seja um inteiro positivo é simplesmente ignorado;
- um usuário logado que não selecionou um médico vê a sua agenda: seu médico é recuperado por meio de sua conta ([getDoctorByUserId]). [?->getId()]: o operador nullsafe retorna [null] se o objeto for [null], em vez de gerar um erro;
- a lista suspensa de médicos: [array_map] converte cada médico em [OptionView];
- a agenda, formatada e filtrada de acordo com as permissões do usuário ([scheduleView], abaixo);
- a janela de reserva, somente se o horário solicitado for reservável por esse usuário: um paciente que tentar gerar a URL [&book=2] para um horário já reservado não obteria nada. [array_find] (exemplo 06) retorna o primeiro elemento de um array que satisfaz uma condição, ou [null]. A lista de pacientes é fornecida somente ao administrador e aos médicos; um paciente recebe apenas o próprio nome;
- a view recebe suas variáveis ([render], exemplo 13), incluindo [pageTitle] e [error], que são lidas pelo template.
11.19.3.3. POST /schedule/book
Linhas 167–215:
- o token anti-CSRF, seguido dos campos ocultos do formulário de reserva (médico, dia, horário). Como eles são inválidos, trata-se necessariamente de uma requisição construída manualmente: [BadRequestHttpException], a página de “requisição inválida” (400);
- Para um paciente, o campo [clientId] é ignorado: o paciente sempre faz a consulta 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 reserva é reaberta com uma mensagem;
- o horário deve pertencer ao médico indicado na página;
- as regras de negócio (não estar no passado, apenas uma consulta futura, horário disponível) são verificadas pela camada de lógica de negócio. Uma [BusinessException] se torna uma mensagem de erro flash; suas propriedades públicas [key] e [params] fornecem a mensagem. A mesma rejeição (“uma consulta futura”) é redigida na segunda pessoa para o 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, o padrão Post/Redirect/Get (exemplo 20): uma mensagem pop-up e um redirecionamento para a agenda.
11.19.3.4. POST /schedule/cancel
Linhas 221–239: cancelamento de uma consulta pelo administrador ou por um médico (regra [^/schedule/cancel$] derivada de [security.yaml]). Uma consulta que não existe mais (já cancelada por outra pessoa, ou por causa de um clique duplo) não é um erro: gera apenas uma mensagem.
- linhas 247–255: 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 260–285: a agenda do médico, convertida em linhas para a view. A questão da privacidade está na linha 278: um paciente vê apenas o nome associado à sua própria consulta. Para as 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 “Reservar” é exibido para um horário 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 os administradores. Os argumentos nomeados ([slotId: $slot->getId()]) tornam legível a construção de um objeto com oito propriedades;
- linhas 291–296: os campos ocultos dos formulários POST. [[$doctorId, $day] = ...] (linhas 171 e 225) decompõe o array renderizado em duas variáveis;
- linhas 300–307: a URL da agenda de um médico em um determinado dia. [generateUrl('schedule', [...])] adiciona ao final da URL, como parâmetros de consulta, os valores que não são parâmetros do caminho: [/schedule?doctorId=1&day=2026-09-26];
- linhas 321–328: a mensagem que explica a um paciente por que não há botão “Reservar” (ele já tem uma consulta futura), a menos que essa consulta esteja na agenda exibida (logo após reservá-la, a mensagem ficaria deslocada). [array_any] ([PHP] 8.4): pelo menos um elemento satisfaz a condição?
11.19.4. src/Controller/PersonsController.php
| <?php
// =========================================================================
// src/Controller/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 actions duas vezes, escrevemos-as
// uma vez nesta classe ABSTRATA; DoctorsController e ClientsController
// herdam dela e especificam apenas o que os distingue: o nome da seção
// (médicos ou clientes), as chaves de tradução e os métodos do
// ApplicationModel a chamar.
//
// Os atributos #[Route] das actions também são herdados: o atributo #[Route]
// de CADA classe filha dá a elas o início do caminho (/doctors ou
// /clients) e do nome (doctors_ ou clients_). Assim obtemos, para cada uma:
//
// GET /doctors lista doctors_list
// GET /doctors/add formulário vazio doctors_add
// POST /doctors/add criação doctors_add
// GET /doctors/{id}/edit formulário preenchido doctors_edit
// POST /doctors/{id}/edit modificação doctors_edit
// POST /doctors/{id}/delete exclusão doctors_delete
//
// (e as mesmas URLs sob /clients). As views também são comuns:
// templates/persons/list.html.twig e persons/form.html.twig.
//
// SEGURANÇA: a regra access_control ^/(doctors|clients) de
// config/packages/security.yaml reserva todas essas URLs ao ADMIN - inclusive as
// que forem acrescentadas depois.
// =========================================================================
namespace App\Controller;
use App\Entity\Person;
use App\Form\PersonFieldsType;
use App\Form\PersonType;
use App\Business\PersonData;
use App\Business\BusinessException;
use App\Views\PersonKeys;
use App\Web\ApplicationModel;
use App\Web\BaseController;
use App\Web\Flash;
use App\Web\Message;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
abstract class PersonsController extends BaseController
{
// os campos do formulário envolvidos em cada erro de negócio de "entrada" (uma
// duplicidade): eles são emoldurados em vermelho, e a mensagem fica 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, protected Flash $flash)
{
}
// o que cada tipo de pessoa deve fornecer
// "doctors" ou "clients": o início dos nomes das rotas
abstract protected function section(): string;
abstract protected function keys(): PersonKeys;
/** @return list<Person> */
abstract protected function all(): array;
abstract protected function find(int $id): ?Person;
abstract protected function create(PersonData $data): Person;
abstract protected function update(int $id, PersonData $data): Person;
abstract protected function erase(int $id): void;
// -------------------------------------------------------------------
// GET /doctors (ou /clients)
// -------------------------------------------------------------------
#[Route('', name: 'list', methods: ['GET'])]
public function list(): Response
{
return $this->render('persons/list.html.twig', ['pageTitle' => $this->keys()->title,
'keys' => $this->keys(), 'section' => $this->section(), 'persons' => $this->all()]);
}
// -------------------------------------------------------------------
// GET /doctors/add: o formulário vazio; POST: a criação
// -------------------------------------------------------------------
#[Route('/add', name: 'add', methods: ['GET', 'POST'])]
public function add(Request $request): Response
{
$form = $this->createForm(PersonType::class, ['title' => 'Mr']);
$form->handleRequest($request);
if ($form->isSubmitted() && $form->isValid()) {
try {
$person = $this->create(PersonFieldsType::data($form->getData()));
} catch (BusinessException $e) {
return $this->businessError($e, $form, null);
}
$this->flash->success($this->keys()->added, self::params($person));
return $this->redirectToRoute($this->section().'_list');
}
return $this->page($form, null);
}
// -------------------------------------------------------------------
// GET /doctors/{id}/edit: o formulário preenchido; POST: a modificação.
// {id<\d+>}: um parâmetro formado por dígitos (veja o exemplo 02):
// /doctors/abc/edit não corresponde a nenhuma rota (página 404)
// -------------------------------------------------------------------
#[Route('/{id<\d+>}/edit', name: 'edit', methods: ['GET', 'POST'])]
public function edit(Request $request, int $id): Response
{
$person = $this->find($id) ?? throw $this->createNotFoundException();
// o formulário, preenchido com os valores da pessoa (a
// senha, por outro lado, nunca é exibida)
$form = $this->createForm(PersonType::class, [
'title' => $person->getTitle(), 'first_name' => $person->getFirstName(),
'last_name' => $person->getLastName(), 'login' => $person->getAccount()->getLogin(),
'version' => $person->getVersion(),
], ['creation' => false]);
$form->handleRequest($request);
if ($form->isSubmitted() && $form->isValid()) {
try {
$person = $this->update($id, PersonFieldsType::data($form->getData()));
} catch (BusinessException $e) {
return $this->businessError($e, $form, $person);
}
$this->flash->success($this->keys()->edited, self::params($person));
return $this->redirectToRoute($this->section().'_list');
}
return $this->page($form, $person);
}
// -------------------------------------------------------------------
// POST /doctors/{id}/delete
// (a confirmação "Are you sure?" é pedida antes de o formulário ser enviado,
// veja public/js/app.js)
// -------------------------------------------------------------------
#[Route('/{id<\d+>}/delete', name: 'delete', methods: ['POST'])]
public function delete(Request $request, int $id): Response
{
$this->checkCsrf($request);
$person = $this->find($id);
try {
$this->erase($id);
$this->flash->success($this->keys()->deleted, self::params($person));
} catch (BusinessException $e) {
$this->flash->error($e->key, $e->params);
}
return $this->redirectToRoute($this->section().'_list');
}
// funções internas
// $person null: formulário de criação; caso contrário: formulário de modificação.
// Um formulário recusado (entrada inválida ou regra de negócio): o código 422
private function page(FormInterface $form, ?Person $person, ?Message $error = null,
array $invalidFields = []): Response
{
$keys = $this->keys();
$refused = $error !== null || ($form->isSubmitted() && ! $form->isValid());
return $this->render('persons/form.html.twig', [
'pageTitle' => $person === null ? $keys->add : $keys->edit,
'form' => $form,
'error' => $error,
'invalidFields' => $invalidFields,
'listUrl' => $this->generateUrl($this->section().'_list'),
], new Response(status: $refused ? 422 : 200));
}
// uma regra de negócio recusou a gravação: o formulário é exibido novamente, com
// a entrada do usuário (sem a senha), a mensagem da camada
// de negócio (no rodapé da página) e os campos envolvidos, se houver, emoldurados
// em vermelho para que o usuário veja imediatamente o que corrigir
private function businessError(BusinessException $e, FormInterface $form, ?Person $person): Response
{
if (in_array($e->key, ['ERRORS.DOCTOR_NOT_FOUND', 'ERRORS.PATIENT_NOT_FOUND'], true)) {
// excluído nesse meio-tempo por outro ADMIN: volta para a lista
$this->flash->error($e->key, $e->params);
return $this->redirectToRoute($this->section().'_list');
}
return $this->page($form, $person, new Message($e->key, $e->params),
self::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
}
// {name} e {login} das mensagens "added / updated / deleted"
private static function params(?Person $person): array
{
return $person === null ? ['name' => '', 'login' => '']
: ['name' => "{$person->getFirstName()} {$person->getLastName()}",
'login' => $person->getAccount()->getLogin()];
}
}
|
O gerenciamento de médicos e clientes é idêntico: mesma lista, mesmo formulário, mesmas regras. As ações são escritas uma única vez, em uma classe abstrata; [DoctorsController] e [ClientsController] herdam dela. Cada uma deve fornecer o que a diferencia: esse é o papel dos métodos abstratos das linhas 64–77, 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 pai define o algoritmo, e as classes filhas fornecem os detalhes.
Os atributos [#[Route]] das ações também são herdados. [Symfony] ignora a classe abstrata, mas examina os métodos de cada uma das classes filhas, inclusive os herdados; o atributo [#[Route]] da classe filha especifica o início de seu caminho e de seu nome: a ação [list] se torna as rotas [doctors_list] ([/doctors]) e [clients_list] ([/clients]). Para adicionar uma ação aos módulos de gerenciamento de médicos ou de clientes, basta escrevê-la aqui.
- Linhas 51–55: os campos afetados por cada erro de entrada da lógica de negócio: um login duplicado afeta o campo “login”; uma homonímia afeta os campos “nome” e “sobrenome”. Esses campos serão destacados em vermelho;
- linha 57: o construtor, herdado pelas classes filhas. Suas propriedades são [protected]: visíveis para as classes filhas;
- Linhas 82–87: a lista. Essa view é comum às duas seções: ela recebe as chaves de tradução da seção ([keys]) e seu nome ([section]), que é usado para gerar os nomes das rotas ([section ~ '_add'] na view);
- Linhas 92–107: adição. Uma única ação para GET (o formulário vazio, com o título [Mr] selecionado) e POST (criação), como no Exemplo 19. Uma entrada inválida recarrega o formulário. Uma entrada válida segue para a camada de negócio, que pode rejeitar a operação de escrita (por exemplo, um homônimo, um login já em uso); caso contrário, aparece uma mensagem de sucesso e o usuário volta à lista (padrão PRG);
- linhas 114–136: a atualização, para uma pessoa existente: [?? throw $this->createNotFoundException()] (a página 404; [throw] é uma expressão que pode ser usada à direita de [??]). [{id<\d+>}] (linha 114) aceita apenas dígitos para o parâmetro [{id}] (exemplo: 02). O formulário é preenchido previamente com os valores da pessoa e sua versão; [handleRequest] os substitui pelos dados digitados, resultando em POST;
- linhas 143–155: exclusão. O formulário pediu confirmação no navegador (exemplo 21). As informações da pessoa são recuperadas antes da exclusão para gerar a mensagem de sucesso (“O médico Paul TATOU foi excluído.”);
- linhas 161–173: o formulário, seja para criação ([$person] igual a [null]) ou para modificação. Um formulário rejeitado (entrada inválida ou violação de regra de negócio) é devolvido com o código de status 422 (exemplo 19). A view recebe o próprio formulário ([render] o converte em uma “view de formulário”, exemplo 18);
- linhas 179–188: a camada de negócio rejeitou a operação de escrita. Se uma pessoa foi excluída nesse meio-tempo (por outro administrador), o usuário volta para a lista. Caso contrário, o formulário é exibido novamente diretamente (sem redirecionamento), como no caso de um erro de entrada: ele já contém a entrada do usuário. A isso se somam a mensagem da camada de negócio (exibida na parte inferior da página, na área de erros) e os campos a serem destacados em vermelho. Observe que o entity manager é fechado após a exceção (a camada de negócio, como mencionado acima): a ação agora apenas exibe;
- linhas 191–196: os parâmetros [{name}] e [{login}] das mensagens de sucesso.
11.19.5. src/Controller/DoctorsController.php e ClientsController.php
| <?php
// src/Controller/DoctorsController.php: o gerenciamento dos médicos (somente o papel
// ADMIN). Todas as actions são escritas por PersonsController: resta
// aqui apenas dizer O QUE chamar e QUAIS rótulos exibir.
namespace App\Controller;
use App\Entity\Person;
use App\Business\PersonData;
use App\Views\PersonKeys;
use Symfony\Component\Routing\Attribute\Route;
// o início do caminho e do nome de todas as rotas herdadas de PersonsController
#[Route('/doctors', name: 'doctors_')]
class DoctorsController extends PersonsController
{
protected function section(): string
{
return 'doctors';
}
// DOCTORS.TITLE, DOCTORS.ADD... (veja as traduções)
protected function keys(): PersonKeys
{
return PersonKeys::of('DOCTORS');
}
protected function all(): array
{
return $this->application->getAllDoctors();
}
protected function find(int $id): ?Person
{
return $this->application->getDoctorById($id);
}
protected function create(PersonData $data): Person
{
return $this->application->addDoctor($data);
}
protected function update(int $id, PersonData $data): Person
{
return $this->application->editDoctor($id, $data);
}
protected function erase(int $id): void
{
$this->application->deleteDoctor($id);
}
}
|
Resta aqui apenas especificar quais métodos chamar (os métodos de [ApplicationModel]) e quais rótulos exibir (as chaves [DOCTORS.xxx] nos dicionários), além de fornecer os caminhos iniciais e os nomes das rotas (linha 14). O [ApplicationModel] fica na propriedade [$this->application], declarada pelo construtor da classe pai. [ClientsController] é idêntico, com os métodos de cliente e as chaves [CLIENTS.xxx].
11.19.6. src/Controller/RegistrationController.php
| <?php
// =========================================================================
// src/Controller/RegistrationController.php: "Create a patient account": um paciente
// que ainda não tem conta a cria por conta própria. Rotas PÚBLICAS (por definição, ainda não se
// tem conta):
//
// POST /register/access botão "Create a patient account" da página
// de login: verifica o captcha DESSA
// página e depois abre o formulário
// GET /register o formulário
// POST /register a criação, 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 patient account" envia o formulário de login para
// /register/access; se o captcha for copiado corretamente, o servidor emite um
// pass (veja src/Security/RegistrationPass.php);
// 2. sem um pass válido, /register redireciona para a página de
// login (atributo #[RegistrationPassRequired], veja
// src/EventListener/CheckRegistrationPass.php);
// 3. o pass é 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 src/Security/AttemptLimiter.php).
//
// A conta criada é exatamente a que o ADMIN criaria a partir da página "Patients"
// (mesmo método da camada de negócio: addClient), exceto que o paciente
// ESCOLHE o login e a senha (obrigatórios, com confirmação).
// =========================================================================
namespace App\Controller;
use App\Form\PersonFieldsType;
use App\Form\RegistrationType;
use App\Business\BusinessException;
use App\Security\CaptchaService;
use App\Security\AttemptLimiter;
use App\Security\RegistrationPass;
use App\Security\RegistrationPassRequired;
use App\Web\ApplicationModel;
use App\Web\BaseController;
use App\Web\Flash;
use App\Web\Message;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
#[Route('/register')]
class RegistrationController extends BaseController
{
public function __construct(
private ApplicationModel $application,
private CaptchaService $captchas,
private AttemptLimiter $limiter,
private RegistrationPass $passes,
private Flash $flash,
) {
}
// -----------------------------------------------------------------------
// POST /register/access campos: captchaId, captcha (os da página de
// login; login e senha, também enviados, são ignorados)
// -----------------------------------------------------------------------
#[Route('/access', name: 'registration_access', methods: ['POST'])]
public function access(Request $request): Response
{
$this->checkCsrf($request);
$ip = (string) $request->getClientIp();
// contas criadas demais recentemente a partir deste endereço: não adianta ir adiante
$minutes = $this->limiter->registrationBlockMinutes($ip);
if ($minutes > 0) {
$this->flash->error('ERRORS.TOO_MANY_ACCOUNTS', ['minutes' => $minutes]);
return $this->redirectToRoute('login');
}
// captcha ausente ou errado: volta para a página de login, com uma
// nova imagem (uma falha conta como falha de login)
if (! $this->captchas->verify($request->request->getString('captchaId'),
$request->request->getString('captcha'))) {
$this->limiter->loginFailure($ip, '');
$this->flash->error('ERRORS.CAPTCHA_BEFORE_ACCOUNT');
return $this->redirectToRoute('login');
}
// captcha correto: o pass é emitido e o formulário é aberto
$response = $this->redirectToRoute('registration');
$response->headers->setCookie($this->passes->issue());
return $response;
}
// -----------------------------------------------------------------------
// GET /register: o formulário; POST /register: a criação. O
// pass foi verificado ANTES da chamada da action (#[RegistrationPassRequired]).
// O formulário valida TODA a entrada (campos e confirmação da senha):
// o usuário corrige todos os seus erros de uma só vez
// -----------------------------------------------------------------------
#[Route('', name: 'registration', methods: ['GET', 'POST'])]
#[RegistrationPassRequired]
public function register(Request $request): Response
{
$form = $this->createForm(RegistrationType::class, ['title' => 'Mr']);
$form->handleRequest($request);
if (! $form->isSubmitted() || ! $form->isValid()) {
return $this->page($form);
}
$ip = (string) $request->getClientIp();
// 1. contas criadas demais recentemente a partir deste endereço?
$minutes = $this->limiter->registrationBlockMinutes($ip);
if ($minutes > 0) {
return $this->page($form, new Message('ERRORS.TOO_MANY_ACCOUNTS', ['minutes' => $minutes]));
}
// 2. a criação (cliente + conta USER, em uma transação)
$data = PersonFieldsType::data($form->getData());
try {
$this->application->addClient($data);
} catch (BusinessException $e) {
// login ou nome e sobrenome já em uso: o pass continua válido
return $this->page($form, new Message($e->key, $e->params),
PersonsController::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
}
// 3. o pass foi usado: ele não permitirá criar uma 2ª conta
$this->passes->consume($request->cookies->get(RegistrationPass::COOKIE));
$this->limiter->registrationSuccess($ip);
// 4. volta para a página de login, com o login preenchido
$this->flash->success('REGISTRATION.DONE', ['login' => $data->login]);
return RegistrationPass::clearCookie($this->redirectToRoute('login', ['login' => $data->login]));
}
// o formulário; um formulário recusado: o código 422
private function page(FormInterface $form, ?Message $error = null, array $invalidFields = []): Response
{
$refused = $error !== null || ($form->isSubmitted() && ! $form->isValid());
return $this->render('registration.html.twig', ['pageTitle' => 'REGISTRATION.TITLE',
'form' => $form, 'error' => $error, 'invalidFields' => $invalidFields],
new Response(status: $refused ? 422 : 200));
}
}
|
O paciente cria ele mesmo uma conta de paciente. O fluxo é protegido por um CAPTCHA, o mesmo usado na página de login.
- Linhas 65–91: 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 contas demais foram criadas recentemente a partir deste endereço (IP), não há motivo para prosseguir. Se o CAPTCHA estiver ausente ou incorreto: volta-se à 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 99–107: o formulário. O atributo [#[RegistrationPassRequired]] (linha 100) faz com que o token seja verificado pelo listener [CheckRegistrationPass] antes de a ação ser chamada. O formulário valida todas as entradas, inclusive a confirmação da senha: o usuário vê todos os erros de uma só vez;
- Linhas 108–132: criação. O cliente e sua conta são criados com o mesmo método da camada de negócio usado pelo 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á existir: volta-se ao formulário sem consumir o passe. Criar 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 ([redirectToRoute('login', ['login' => ...])] adiciona o parâmetro [?login=...]), junto com uma mensagem de sucesso. O cookie do passe é apagado.
11.19.7. src/Controller/PatientAreaController.php
| <?php
// =========================================================================
// src/Controller/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 a consulta futura dele
// POST /my-area/cancel cancela A consulta DELE
// GET /my-account formulário de modificação da conta dele
// 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
// ($this->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 montando as próprias requisições.
//
// Qualquer modificação ou exclusão da conta exige a senha ATUAL:
// alguém que encontrasse uma sessão deixada aberta não poderia nem alterar a
// senha, nem excluir a conta. Os erros de senha atual são
// contados como falhas de login (mesmo limite).
//
// Segurança: todas essas URLs são reservadas ao papel USER (regra ^/my- de
// config/packages/security.yaml).
// =========================================================================
namespace App\Controller;
use App\Entity\Client;
use App\Entity\Appointment;
use App\Form\PersonFieldsType;
use App\Form\MyAccountType;
use App\Business\BusinessException;
use App\Security\AuthService;
use App\Security\AttemptLimiter;
use App\Views\AppointmentView;
use App\Web\ApplicationModel;
use App\Web\BaseController;
use App\Web\Flash;
use App\Web\Message;
use App\Web\Utils;
use Symfony\Component\Form\FormError;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Contracts\Translation\TranslatorInterface;
class PatientAreaController extends BaseController
{
public function __construct(
private ApplicationModel $application,
private AuthService $auth,
private AttemptLimiter $limiter,
private Utils $utils,
private Flash $flash,
private TranslatorInterface $translator,
) {
}
// -----------------------------------------------------------------------
// GET /my-area
// -----------------------------------------------------------------------
#[Route('/my-area', name: 'area', methods: ['GET'])]
public function area(): Response
{
$patient = $this->utils->connectedPatient();
$appointments = array_map(fn (Appointment $a) => new AppointmentView(
$a->getId(),
$this->utils->formatDay($a->getDay()),
$a->getSlot()->time(),
$a->getSlot()->getDoctor()->label(),
// link para a agenda do médico nesse dia: o paciente vê o nome dele ali
$this->generateUrl('schedule', ['doctorId' => $a->getSlot()->getDoctor()->getId(),
'day' => Utils::iso($a->getDay())])),
$this->application->getClientUpcomingAppointments($patient->getId()));
return $this->render('area.html.twig', ['pageTitle' => 'AREA.TITLE',
'patient' => $patient->label(), 'appointments' => $appointments]);
}
// -----------------------------------------------------------------------
// POST /my-area/cancel campo: appointmentId
// -----------------------------------------------------------------------
#[Route('/my-area/cancel', name: 'area_cancel', methods: ['POST'])]
public function cancelAppointment(Request $request): Response
{
$this->checkCsrf($request);
$patient = $this->utils->connectedPatient();
$appointmentId = Utils::positiveInteger($request->request->get('appointmentId'));
$appointment = $appointmentId !== null ? $this->application->getAppointmentById($appointmentId) : null;
// uma consulta que não existe e a de OUTRO paciente recebem a
// mesma resposta: nada é revelado sobre as consultas dos outros
if ($appointment === null || $appointment->getClient()->getId() !== $patient->getId()) {
$this->flash->error('ERRORS.APPOINTMENT_NOT_FOUND');
} else {
$this->application->deleteAppointment($appointment);
$this->flash->success('SCHEDULE.CANCELLED');
}
return $this->redirectToRoute('area');
}
// -----------------------------------------------------------------------
// GET /my-account: o formulário, preenchido com os valores do paciente;
// POST /my-account: a modificação
// -----------------------------------------------------------------------
#[Route('/my-account', name: 'account', methods: ['GET', 'POST'])]
public function account(Request $request): Response
{
$patient = $this->utils->connectedPatient();
$form = $this->createForm(MyAccountType::class, [
'title' => $patient->getTitle(), 'first_name' => $patient->getFirstName(), 'last_name' => $patient->getLastName(),
'login' => $patient->getAccount()->getLogin(), 'version' => $patient->getVersion(),
]);
$form->handleRequest($request);
if (! $form->isSubmitted() || ! $form->isValid()) {
return $this->page($form);
}
// a senha atual; errada: a mensagem vai ABAIXO do campo (um erro
// adicionado ao campo, FormError) e no rodapé da página
$error = $this->checkCurrentPassword($request, $patient,
$form->get('current_password')->getData());
if ($error !== null) {
$form->get('current_password')->addError(
new FormError($this->translator->trans($error->key, $error->params)));
return $this->page($form, $error);
}
try {
$client = $this->application->editClient($patient->getId(),
PersonFieldsType::data($form->getData()));
} catch (BusinessException $e) {
return $this->page($form, new Message($e->key, $e->params),
PersonsController::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
}
// o login e o nome exibido estão NO token: um novo é emitido,
// senão a barra de navegação manteria o nome antigo
$this->flash->success('MY_ACCOUNT.UPDATED');
$response = $this->redirectToRoute('area');
$response->headers->setCookie($this->auth->tokenCookie($client->getAccount()));
return $response;
}
// -----------------------------------------------------------------------
// POST /my-account/delete campo: current_password
// A conta, o cliente e TODAS as consultas dele desaparecem juntos, e depois o
// paciente é deslogado.
// -----------------------------------------------------------------------
#[Route('/my-account/delete', name: 'account_delete', methods: ['POST'])]
public function deleteAccount(Request $request): Response
{
$this->checkCsrf($request);
$patient = $this->utils->connectedPatient();
$error = $this->checkCurrentPassword($request, $patient,
$request->request->getString('current_password'));
if ($error !== null) {
$this->flash->error($error->key, $error->params);
return $this->redirectToRoute('account');
}
$this->application->deleteClient($patient->getId());
$this->flash->success('MY_ACCOUNT.DELETED');
return AuthService::clearCookie($this->redirectToRoute('login'));
}
// funções internas
// a página da conta; um formulário recusado: o código 422
private function page(FormInterface $form, ?Message $error = null, array $invalidFields = []): Response
{
$refused = $error !== null || ($form->isSubmitted() && ! $form->isValid());
return $this->render('account.html.twig', ['pageTitle' => 'MY_ACCOUNT.TITLE',
'form' => $form, 'error' => $error, 'invalidFields' => $invalidFields],
new Response(status: $refused ? 422 : 200));
}
// null se a senha atual estiver correta; caso contrário, a mensagem de erro
private function checkCurrentPassword(Request $request, Client $patient, ?string $password): ?Message
{
$ip = (string) $request->getClientIp();
$login = $patient->getAccount()->getLogin();
$minutes = $this->limiter->loginBlockMinutes($ip, $login);
if ($minutes > 0) {
return new Message('ERRORS.TOO_MANY_ATTEMPTS', ['minutes' => $minutes]);
}
if (! $password || $this->auth->validate($login, $password) === null) {
$this->limiter->loginFailure($ip, $login);
return new Message('ERRORS.WRONG_CURRENT_PASSWORD');
}
return null;
}
}
|
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 nem cancelar informações pertencentes a outro paciente, mesmo construindo suas próprias requisições.
- linhas 64–79: Minha área: o nome do paciente e suas próximas consultas, formatadas ([AppointmentView]), cada uma com um link para a agenda do médico nesse dia;
- linhas 84–100: o cancelamento da sua consulta. Tanto uma consulta inexistente quanto a consulta de outro paciente recebem a mesma resposta: nenhuma informação é revelada sobre as consultas de outros pacientes (nem mesmo sua existência);
- linhas 106–117: o formulário “Gerenciar minha conta”, preenchido previamente com as informações do paciente, e seu envio;
- linhas 119–142: 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. Se a senha atual estiver incorreta, o formulário é exibido novamente, com a mensagem abaixo do campo e na parte inferior da página. [addError(new FormError(...))] adiciona um erro a um campo, como se a validação o tivesse detectado (exemplo 18); sua mensagem é um texto já traduzido, daí o tradutor recebido pelo construtor ([TranslatorInterface], exemplo 22). Após a modificação, um novo token é gerado: o login e o nome exibido estão incluídos no token, e a barra de navegação, caso contrário, manteria o nome antigo até o próximo login;
- linhas 149–163: exclusão da conta, do cliente e de todas as suas consultas, usando o mesmo método da lógica de negócio usado pelo administrador. Este segundo formulário da página é escrito manualmente (um único campo, a senha atual), com o token anti-CSRF da aplicação. O paciente é então desconectado (o cookie do token é apagado);
- linhas 177–190: 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 por meio do formulário “Gerenciar minha conta” e descobrir a correta.
11.20. As views
As views [Twig] na pasta [templates]: um template, fragmentos, macros e páginas.
11.20.1. O template e os fragmentos
11.20.1.1. templates/layout.html.twig
| <!doctype html>
{# =========================================================================
templates/layout.html.twig
- - - - - - - - - - - - - - - - - - - - - - - -
O layout COMUM a todas as páginas (veja o exemplo 15): cada página
(schedule.html.twig, login.html.twig...) o ESTENDE ({% extends %}) e preenche seu
bloco [content].
O Twig ESCAPA tudo o que exibe com {{ ... }} (os caracteres < > & " '
viram < >...): proteção contra injeção de HTML por meio de um
nome digitado, por exemplo. Para inserir HTML como está, é preciso solicitá-lo
explicitamente (filtro raw, veja fragments/captcha.html.twig).
Mensagens: um sucesso é exibido no TOPO da página, um erro no FINAL, sobre um fundo
rosa claro (fragmento errors).
O layout compartilha as variáveis da página: [pageTitle] (a chave do título da
página, passada pela action). O idioma da página é o da requisição
(app.request.locale, veja src/EventListener/SetLanguage.php).
========================================================================= #}
<html lang="{{ app.request.locale }}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
{# pageTitle|trans: a tradução de uma chave; aqui, a chave é uma VARIÁVEL #}
<title>{{ pageTitle|trans }} - {{ 'APP.TITLE'|trans }}</title>
{# asset(): a URL de um arquivo da pasta public #}
<link rel="stylesheet" href="{{ asset('lib/bootstrap/css/bootstrap.min.css') }}">
<link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
<div class="container py-4">
{% include 'fragments/navbar.html.twig' %}
{% include 'fragments/success.html.twig' %}
<main>
{% block content %}{% endblock %}
</main>
{% include 'fragments/errors.html.twig' %}
</div>
{# o diálogo "Tem certeza?", oculto enquanto não for necessário #}
{% include 'fragments/confirmation.html.twig' %}
<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.html.twig' %}]) e preenche seu bloco [content] (linha 36).
- Linha 21: o idioma da página, [fr] ou [en]: o idioma da requisição, definido pelo listener [SetLanguage]. [app] é a variável global que o [Symfony] fornece a todas as views (Exemplo 15);
- linha 26: o título da página, traduzido: [pageTitle|trans] traduz a chave contida na variável [pageTitle], que cada ação passa para sua view;
- linhas 28–29: a função [asset] retorna 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;
- linhas 41–42: a janela “Tem certeza?”, oculta até ser necessária, e o script que a exibe.
O [Twig] faz o escape de tudo o que exibe por meio de [{{ ... }}] (Exemplo 13): um nome digitado que contenha HTML ([<script>]) é exibido como está, sem ser interpretado. Essa é uma proteção contra a injeção descuidada de HTML (XSS) em todas as páginas.
11.20.1.2. templates/fragments/navbar.html.twig
| {# =========================================================================
templates/fragments/navbar.html.twig - a barra de navegação.
Título, FR/EN, papel, nome, logout - e um menu cujas entradas dependem
do papel: "Médicos" e "Pacientes" só aparecem para o ADMIN. É
apenas uma conveniência de exibição: a proteção real são as regras de acesso
(um USER que digita /doctors manualmente recebe uma página 403). Um paciente (USER)
também tem seu menu "Minha área".
user(): o usuário logado, ou null (veja src/Twig/ViewsExtension.php).
O menu da página atual é destacado (classe "active"): isso ocorre se
o caminho da URL (app.request.pathInfo) começa com ([starts with]) um dos
prefixos da entrada. As entradas do menu: uma lista de arrays [nome da
rota, chave do rótulo, prefixos dos caminhos para os quais a entrada está ativa].
========================================================================= #}
{% set user = user() %}
{% set menu = [] %}
{% if user %}
{% if user.isPatient %}
{# ativa para /my-area E /my-account #}
{% set menu = menu|merge([['area', 'APP.MENU_MY_AREA', ['/my-']]]) %}
{% endif %}
{% set menu = menu|merge([['schedule', 'APP.MENU_SCHEDULE', ['/schedule']]]) %}
{% if user.isAdmin %}
{% set menu = menu|merge([['doctors_list', 'APP.MENU_DOCTORS', ['/doctors']],
['clients_list', 'APP.MENU_PATIENTS', ['/clients']]]) %}
{% endif %}
{% endif %}
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
<span class="navbar-brand mb-0">{{ 'APP.TITLE'|trans }}</span>
<ul class="navbar-nav me-auto">
{# entry[0]: o nome da rota; filter mantém os prefixos correspondentes #}
{% for entry in menu %}
{% set active = entry[2]|filter(p => app.request.pathInfo starts with p) is not empty %}
<li class="nav-item">
<a class="nav-link{{ active ? ' active' }}" href="{{ path(entry[0]) }}">{{ entry[1]|trans }}</a>
</li>
{% endfor %}
</ul>
<div class="d-flex align-items-center gap-2">
{# FR / EN: links simples (GET /language/fr), o idioma ativo destacado #}
<div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
{% for code in ['fr', 'en'] %}
<a class="btn {{ app.request.locale == code ? 'btn-light' : 'btn-outline-light' }}"
href="{{ path('language', {code: code}) }}">{{ code|upper }}</a>
{% endfor %}
</div>
{% if user %}
<span class="badge text-bg-light text-primary">{{ user.role.value }}</span>
<span class="text-white">{{ user.name }}</span>
{# logout é um POST: um formulário reduzido ao seu botão (e ao token anti-CSRF) #}
<form method="post" action="{{ path('logout') }}" class="m-0">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<button type="submit" class="btn btn-sm btn-outline-light">{{ 'APP.LOGOUT'|trans }}</button>
</form>
{% endif %}
</div>
</nav>
|
A barra de navegação. Os itens do menu dependem do papel: “Minha área” para um paciente, “Médicos” e “Pacientes” para o administrador. Trata-se apenas de um recurso de conveniência: a proteção real vem das regras [access_control] (um paciente que digitar [/doctors] manualmente receberá uma página 403).
- Linha 16: o usuário logado, ou [null], retornado pela função [user()] de nossa extensão;
- Linhas 17–28: o menu é gerado pelas instruções [{% set %}], que produzem uma lista de entradas: o nome da rota, a chave do rótulo e os prefixos de caminho para os quais a entrada está ativa. O filtro [merge] retorna uma nova lista, composta pelos elementos da primeira lista seguidos pelos da segunda (para dois arrays associativos, ele combina suas chaves). [user.isPatient]: o [Twig] chama o método [isPatient()]. A entrada “Minha área” fica ativa para [/my-area] e [/my-account] (prefixo [/my-]). Isso beira a regra de “nenhuma lógica nas views”: no entanto, essa lógica afeta apenas a exibição e é usada somente aqui;
- Linhas 34–39: para cada entrada, [active] é verdadeiro se o caminho da URL solicitada ([app.request.pathInfo]) começa com ([starts with]) um dos prefixos da entrada. O filtro [filter] retém apenas os elementos de uma lista que satisfazem uma condição, escrita como uma arrow function ([p => ...]);
- linhas 44–49: os botões FR / EN, que são simples links ([/language/fr]), com o idioma ativo destacado;
- linhas 51–59: para um usuário logado, seu papel ([user.role.value]: a string do case 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_token('rdvmedecins')], exemplo 21).
11.20.1.3. templates/fragments/success.html.twig
| {# =========================================================================
templates/fragments/success.html.twig - as mensagens de SUCESSO deixadas pela
action anterior (consulta agendada, médico adicionado...), exibidas somente
uma vez, no topo da página (veja src/Web/Flash.php). Uma mensagem flash de ERRO,
por outro lado, é exibida no final da página, pelo fragmento errors.
app.flashes('success'): as mensagens flash desse tipo (veja o exemplo 20). Cada
mensagem é um objeto Message: message.key|trans(message.params) é o texto
da chave, em que {name}, {login}... são substituídos por seus valores.
========================================================================= #}
{% for message in app.flashes('success') %}
<div class="alert alert-success" role="status">{{ message.key|trans(message.params) }}</div>
{% endfor %}
|
As mensagens flash de sucesso, definidas pela ação anterior ([Flash::success]), são lidas e removidas da sessão por [app.flashes('success')] (Exemplo 20). Cada uma é um objeto [Message], traduzido aqui para o idioma da página: [message.key|trans(message.params)]. [role="status"]: um leitor de tela anuncia a mensagem.
11.20.1.4. templates/fragments/errors.html.twig
| {# =========================================================================
templates/fragments/errors.html.twig - a zona de erros, no FINAL de cada
página, sobre um fundo rosa claro (classe .error-zone, veja public/css/styles.css).
Ela reúne as três fontes possíveis de erro:
- [error]: o erro da página exibida (data inválida, captcha mal
copiado, login já existente...), passado pela action;
- as mensagens flash de erro, deixadas pela action anterior antes de um
redirecionamento (horário já reservado, exclusão recusada...);
- os erros de entrada de um formulário inválido (veja o exemplo 19): suas
mensagens são exibidas ABAIXO dos campos; aqui, se não houver outra
mensagem, uma simples frase "O formulário contém erros.".
error ?? null: a variável não existe em todas as páginas.
role="alert": um leitor de tela anuncia a mensagem assim que a página é exibida,
mesmo que ela esteja no final.
========================================================================= #}
{% set messages = app.flashes('errors') %}
{% if error ?? null %}
{% set messages = [error]|merge(messages) %}
{% endif %}
{% if messages is empty and form is defined and form.vars.submitted and not form.vars.valid %}
{% set messages = [{key: 'ERRORS.INVALID_FORM', params: []}] %}
{% endif %}
{% if messages is not empty %}
<div class="error-zone" role="alert">
{% for message in messages %}
<div>{{ message.key|trans(message.params) }}</div>
{% endfor %}
</div>
{% endif %}
|
A área de erros, na parte inferior de cada página, sobre um fundo rosa-claro. Ela combina as três fontes possíveis de erro:
- as mensagens flash de erro, geradas pela ação anterior (um horário já reservado, uma sessão expirada etc.);
- o erro da página exibida ([error]), transmitido pela ação: uma data inválida, um CAPTCHA digitado incorretamente, um nome de usuário já em uso etc.; colocado no topo da lista. [error ?? null]: essa variável não existe em todas as páginas; o operador [??] não sinaliza uma variável inexistente: ele a substitui por [null];
- Os erros de entrada de um formulário inválido (exemplo 19): suas mensagens são exibidas abaixo dos campos; aqui, se não houver outras mensagens, uma frase simples: “O formulário contém erros.” Em um formulário longo, isso avisa ao usuário que ele precisa rolar de volta para cima. [form.vars]: as propriedades da view do formulário, incluindo [submitted] (enviado?) e [valid] (válido?). A mensagem é escrita como um array associativo com as mesmas chaves das propriedades de um [Message]: para o [Twig], [message.key] refere-se tanto à chave de um array quanto à propriedade de um objeto.
[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 fixa na parte inferior da janela quando a página é longa (veja a folha de estilos abaixo).
11.20.1.5. templates/fragments/confirmation.html.twig
| {# =========================================================================
templates/fragments/confirmation.html.twig - o diálogo modal
"Tem certeza?" (veja o exemplo 21).
Ele substitui a caixa window.confirm() do navegador, que não pode ser
estilizada nem traduzida (seus botões permanecem no idioma do navegador, não
no da página).
UM ÚNICO diálogo para a página inteira, oculto (d-none) no início. Seus rótulos
são traduzidos aqui, pelo servidor, como o restante da página; o pequeno script
public/js/app.js apenas o exibe, coloca nele a mensagem específica do
formulário (atributo data-confirmation) e envia o formulário se
o usuário confirmar.
========================================================================= #}
<div id="confirmation-modal" class="d-none">
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
aria-labelledby="confirmation-modal-title" aria-describedby="confirmation-modal-message">
<div class="modal-dialog modal-dialog-centered">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="confirmation-modal-title">{{ 'CONFIRMATION.TITLE'|trans }}</h5>
<button type="button" class="btn-close" data-action="no" aria-label="{{ 'BOOKING_DIALOG.CLOSE_ARIA'|trans }}"></button>
</div>
<div class="modal-body">
<p class="mb-0" id="confirmation-modal-message"></p>
</div>
<div class="modal-footer">
{# "Não, voltar" em vez de "Cancelar": a pergunta às vezes é
"Cancelar esta consulta?", e um botão "Cancelar" seria ambíguo nesse caso #}
<button type="button" class="btn btn-secondary" data-action="no">{{ 'CONFIRMATION.NO'|trans }}</button>
<button type="button" class="btn btn-danger" data-action="yes">{{ 'CONFIRMATION.YES'|trans }}</button>
</div>
</div>
</div>
</div>
</div>
|
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 nela 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 de recusa é rotulado “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.20.1.6. templates/fragments/booking.html.twig
| {# =========================================================================
templates/fragments/booking.html.twig - o diálogo de agendamento da
agenda.
As classes REAIS do Bootstrap de um diálogo modal (.modal, .modal-backdrop...),
tornadas visíveis "fixas no código" (show d-block) em vez de pelo
JavaScript do Bootstrap. É o SERVIDOR que decide exibi-lo (parâmetro &book=...
da URL), e fechá-lo equivale a seguir um link para a mesma página sem esse
parâmetro.
O fragmento lê diretamente as variáveis da página que o inclui
(booking, doctorId, day, backUrl).
========================================================================= #}
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title">
<div class="modal-dialog modal-dialog-centered">
<form method="post" action="{{ path('schedule_book') }}" class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="booking-title">{{ 'BOOKING_DIALOG.TITLE'|trans }}</h5>
<a class="btn-close" href="{{ backUrl }}" aria-label="{{ 'BOOKING_DIALOG.CLOSE_ARIA'|trans }}"></a>
</div>
<div class="modal-body">
<p>{{ 'BOOKING_DIALOG.SLOT'|trans({time: booking.time}) }}</p>
{# o que o servidor deve saber além do paciente escolhido #}
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<input type="hidden" name="doctorId" value="{{ doctorId }}">
<input type="hidden" name="day" value="{{ day }}">
<input type="hidden" name="slotId" value="{{ booking.slotId }}">
{# um paciente agenda para si mesmo: sem lista para escolher (e o
servidor ignora de qualquer forma um possível clientId) #}
{% if booking.patient %}
<p class="mb-0">
<span>{{ 'BOOKING_DIALOG.PATIENT_LABEL'|trans }}</span>:
<strong>{{ booking.patient }}</strong>
</p>
{% else %}
<label class="form-label" for="clientId">{{ 'BOOKING_DIALOG.PATIENT_LABEL'|trans }}</label>
<select id="clientId" name="clientId" class="form-select" required autofocus>
<option value="">{{ 'BOOKING_DIALOG.CHOOSE_PATIENT'|trans }}</option>
{% for client in booking.clients %}
<option value="{{ client.id }}">{{ client.label }}</option>
{% endfor %}
</select>
{% endif %}
</div>
<div class="modal-footer">
<a class="btn btn-secondary" href="{{ backUrl }}">{{ 'BOOKING_DIALOG.CANCEL'|trans }}</a>
<button type="submit" class="btn btn-primary">{{ 'BOOKING_DIALOG.CONFIRM'|trans }}</button>
</div>
</form>
</div>
</div>
|
A janela de reserva da agenda. Ela usa as classes reais de uma janela modal do [Bootstrap] ([modal], [modal-backdrop]...), mas tornada visível “direto 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 vê seu próprio nome sem selecionar em uma lista (e o servidor ignora qualquer campo [clientId] de qualquer forma). 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.20.1.7. templates/fragments/captcha.html.twig
| {# =========================================================================
templates/fragments/captcha.html.twig - o captcha da página de
login (veja src/Security/CaptchaService.php). Ele protege tanto
o login quanto o acesso à criação de conta (botão "Criar uma conta de
paciente"). Ele lê a variável [captcha] da página.
captcha.svg|raw: a imagem SVG é inserida COMO ESTÁ na página, sem
escape. Isso é inofensivo aqui porque este SVG é construído pelo próprio
servidor e não contém nada que venha do usuário - NUNCA faríamos
isso com uma entrada do usuário.
O campo oculto captchaId informa ao servidor QUAL captcha verificar; a própria
resposta correta nunca é enviada ao navegador. "Outra imagem" simplesmente recarrega
a página (path('login'): a URL da página, sem seus parâmetros).
========================================================================= #}
<div class="mb-3">
<label class="form-label" for="captcha">{{ 'CAPTCHA.LABEL'|trans }}</label>
<div class="d-flex align-items-center gap-3 mb-2">
<div class="captcha-image" role="img" aria-label="{{ 'CAPTCHA.IMAGE_ALT'|trans }}">{{ captcha.svg|raw }}</div>
<a class="small" href="{{ path('login') }}">{{ 'CAPTCHA.NEW_IMAGE'|trans }}</a>
</div>
<input type="hidden" name="captchaId" value="{{ captcha.id }}">
<input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off"
spellcheck="false" required class="form-control">
<div class="form-text">{{ 'CAPTCHA.HELP'|trans }}</div>
</div>
|
O CAPTCHA (exemplo 27). [captcha.svg|raw] 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 de login e, portanto, o CAPTCHA.
11.20.2. Macros: templates/macros.html.twig
| {# =========================================================================
templates/macros.html.twig - as macros dos formulários (veja o exemplo 15).
field(field, invalidFields): um campo de um formulário do componente Form,
com seu rótulo, sua mensagem de erro ou sua ajuda (form_row, desenhado pelo
tema Bootstrap 5, veja o exemplo 18). O campo é contornado em vermelho (classe
is-invalid) se tiver um erro de entrada (o tema cuida disso) ou se um erro de
NEGÓCIO o designar: seu nome está na lista [invalidFields] passada pela
action (um login já existente...), ficando a mensagem no final da página.
Os atributos do campo (maxlength...) são completados, não substituídos: merge.
========================================================================= #}
{% macro field(field, invalidFields = []) %}
{% set attr = field.vars.attr %}
{% if field.vars.name in invalidFields %}
{% set attr = attr|merge({class: (attr.class|default('') ~ ' is-invalid')|trim}) %}
{% endif %}
{{ form_row(field, {attr: attr}) }}
{% endmacro %}
{# os campos de identidade (título, nome, sobrenome), comuns a três formulários:
médico/cliente do ADMIN, "Criar uma conta de paciente" e "Gerenciar minha conta" #}
{% macro identity(form, invalidFields = []) %}
{# import _self: as macros DESTE arquivo, para chamar a macro field #}
{% import _self as m %}
{{ m.field(form.title, invalidFields) }}
<div class="row g-3">
<div class="col-sm-6">{{ m.field(form.first_name, invalidFields) }}</div>
<div class="col-sm-6">{{ m.field(form.last_name, invalidFields) }}</div>
</div>
{% endmacro %}
|
Duas macros (Exemplo 15), usadas pelas três páginas que exibem um formulário de “pessoa”.
- Linhas 12–18: um campo de um formulário do componente Form, gerado por [form_row] (Exemplo 18): seu rótulo, campo de entrada, mensagem de erro ou dica, junto com as classes do tema [Bootstrap] 5 declarado em [config/packages/twig.yaml]. O tema destaca em vermelho um campo com erro de entrada (classe [is-invalid]). A macro também a adiciona a um campo identificado por um erro da camada de negócio: a lista [invalidFields] passada pela ação ([PersonsController::BUSINESS_ERROR_FIELDS]). Um nome de usuário já utilizado não é um erro de entrada (ele tem o formato correto), mas o usuário precisa ver qual campo corrigir. [field.vars]: as propriedades da view do campo, incluindo seu nome ([name]) e seus atributos HTML ([attr]); eles são acrescentados ([merge]), não substituídos: o campo mantém seu [maxlength]. O segundo parâmetro de [form_row] substitui as propriedades da view do campo;
- Linhas 22–30: os campos de identidade, comuns a três formulários: o título, seguido do nome e do sobrenome lado a lado (a grade do [Bootstrap]: [row], [col-sm-6]). Uma macro não enxerga as outras macros de seu arquivo: [{% import _self as m %}] (linha 24) as importa.
11.20.3. As páginas
11.20.3.1. templates/login.html.twig
| {# =========================================================================
templates/login.html.twig - o formulário de login (veja AuthController).
Um <form> HTML comum escrito à mão: o próprio navegador envia login,
senha e resposta do captcha em POST /login, sem JavaScript. Em caso
de falha, o servidor devolve ESTA página, com o login já digitado, um NOVO
captcha e o erro, exibido no final da página pelo layout.
========================================================================= #}
{% extends 'layout.html.twig' %}
{% block content %}
<div class="row justify-content-center">
<div class="col-sm-8 col-md-6 col-lg-5">
<div class="card p-4">
<h5 class="card-title mb-3">{{ 'LOGIN.TITLE'|trans }}</h5>
<form method="post" action="{{ path('login_submit') }}">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<div class="mb-3">
<label class="form-label" for="login">{{ 'LOGIN.LOGIN_LABEL'|trans }}</label>
{# autofocus: um atributo booleano, escrito se a condição for verdadeira, omitido
caso contrário. O cursor vai para o primeiro campo a preencher #}
<input id="login" name="login" type="text" class="form-control" autocomplete="username"
value="{{ login }}" required{{ login == '' ? ' autofocus' }}>
</div>
<div class="mb-3">
<label class="form-label" for="password">{{ 'LOGIN.PASSWORD_LABEL'|trans }}</label>
<input id="password" name="password" type="password" class="form-control"
autocomplete="current-password" required{{ login != '' ? ' autofocus' }}>
</div>
{% include 'fragments/captcha.html.twig' %}
<button type="submit" class="btn btn-primary w-100">{{ 'LOGIN.SUBMIT'|trans }}</button>
{# ainda sem conta: um paciente pode criar uma sozinho. NÃO é
um simples link: é um segundo botão de envio DESTE formulário,
que vai para outro endereço (formaction). O servidor verifica ali o captcha
acima antes de abrir a página de criação de conta (veja
RegistrationController). formnovalidate: o navegador não exige
login e senha (inútil para criar uma conta). Enter em um
campo sempre aciona o PRIMEIRO botão do formulário, "Entrar". #}
<button type="submit" class="btn btn-outline-primary w-100 mt-3"
formaction="{{ path('registration_access') }}" formnovalidate>{{ 'LOGIN.CREATE_ACCOUNT'|trans }}</button>
<div class="form-text text-center">{{ 'LOGIN.CREATE_ACCOUNT_HELP'|trans }}</div>
</form>
<div class="text-muted small mt-3">
<span>{{ 'LOGIN.DEMO_ACCOUNTS'|trans }}</span>
<ul class="mb-0 mt-1">
<li><code>admin</code> - <span>{{ 'LOGIN.DEMO_ADMIN'|trans }}</span></li>
<li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - <span>{{ 'LOGIN.DEMO_DOCTOR'|trans }}</span></li>
<li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - <span>{{ 'LOGIN.DEMO_USER'|trans }}</span></li>
</ul>
</div>
</div>
</div>
</div>
{% endblock %}
|
O formulário de login, um [<form>] escrito manualmente, é enviado via POST para [/login] (o caminho [login_submit]).
- Linhas 22–28: o nome de usuário digitado é exibido novamente 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 criar uma conta). [{{ login == '' ? ' autofocus' }}]: o operador ternário sem “else” retorna uma string vazia se a condição for falsa;
- 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 um endereço diferente (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 um nome de usuário e uma 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.20.3.2. templates/schedule.html.twig
| {# =========================================================================
templates/schedule.html.twig - a página principal (veja ScheduleController).
Três blocos:
1. a escolha do médico e do dia;
2. a agenda;
3. o diálogo de agendamento (fragmento booking).
Um possível erro (data inválida, médico desconhecido) é exibido no final
da página pelo layout (fragmento errors).
========================================================================= #}
{% extends 'layout.html.twig' %}
{% block content %}
{# 1. escolha do médico e do dia: um formulário GET, que simplesmente recarrega
esta página com ?doctorId=...&day=... na URL #}
<form method="get" action="{{ path('schedule') }}" class="card p-3 mb-3">
<div class="row g-2 align-items-end">
<div class="col-sm-5">
<label class="form-label" for="doctorId">{{ 'DOCTOR_DAY_PICKER.DOCTOR_LABEL'|trans }}</label>
<select id="doctorId" name="doctorId" class="form-select" required>
<option value="">{{ 'DOCTOR_DAY_PICKER.CHOOSE_DOCTOR'|trans }}</option>
{% for doctor in doctors %}
<option value="{{ doctor.id }}"{{ doctor.selected ? ' selected' }}>{{ doctor.label }}</option>
{% endfor %}
</select>
</div>
<div class="col-sm-4">
<label class="form-label" for="day">{{ 'DOCTOR_DAY_PICKER.DAY_LABEL'|trans }}</label>
<input id="day" name="day" type="date" class="form-control" value="{{ day }}" required>
</div>
<div class="col-sm-3">
<button type="submit" class="btn btn-primary w-100">{{ 'DOCTOR_DAY_PICKER.VIEW_SCHEDULE'|trans }}</button>
</div>
</div>
</form>
{# paciente que já tem uma consulta futura: por isso não há botão "Agendar" #}
{% if info %}
<div class="alert alert-info">
<span>{{ info|trans }}</span>
<a href="{{ path('area') }}" class="alert-link">{{ 'APP.MENU_MY_AREA'|trans }}</a>
</div>
{% endif %}
{# 2. a agenda #}
{% if schedule %}
<div class="card p-3">
<h5>{{ 'SCHEDULE.TITLE_PREFIX'|trans }} {{ schedule.day }} - {{ schedule.doctor }}</h5>
{% if schedule.rows is not empty %}
<table class="table table-hover align-middle">
<thead>
<tr>
<th>{{ 'SCHEDULE.COLUMN_SLOT'|trans }}</th>
<th>{{ 'SCHEDULE.COLUMN_STATUS'|trans }}</th>
<th></th>
</tr>
</thead>
<tbody>
{% for row in schedule.rows %}
<tr{{ row.bookable ? ' class="free-slot"' }}>
<td>{{ row.time }}</td>
<td>
{# [patient] é definido somente se o usuário tiver o direito de ver este
nome (ADMIN, DOCTOR ou o paciente para SUA consulta) - caso contrário,
simplesmente "Reservado" #}
{% if row.free %}
<span class="badge text-bg-success">{{ 'SCHEDULE.FREE'|trans }}</span>
{% elseif row.patient %}
<span class="badge {{ row.mine ? 'text-bg-primary' : 'text-bg-secondary' }}">{{ row.patient }}</span>
{% else %}
<span class="badge text-bg-secondary">{{ 'SCHEDULE.BOOKED_BY_OTHER'|trans }}</span>
{% endif %}
</td>
<td>
{# os botões exibidos foram decididos pelo controller (bookable,
appointmentId) de acordo com o papel do usuário. "Agendar" é um simples
link: ele reabre esta página com o diálogo de agendamento deste horário #}
{% if row.bookable %}
<a class="btn btn-sm btn-outline-success" href="{{ row.bookUrl }}">{{ 'SCHEDULE.BOOK'|trans }}</a>
{% endif %}
{# "Cancelar" MODIFICA dados: portanto é um POST #}
{% if row.appointmentId %}
<form method="post" action="{{ path('schedule_cancel') }}" class="m-0"
data-confirmation="{{ 'SCHEDULE.CANCEL_CONFIRM'|trans }}">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<input type="hidden" name="appointmentId" value="{{ row.appointmentId }}">
<input type="hidden" name="doctorId" value="{{ doctorId }}">
<input type="hidden" name="day" value="{{ day }}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{ 'SCHEDULE.CANCEL_APPOINTMENT'|trans }}</button>
</form>
{% endif %}
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p class="text-muted mb-0">{{ 'SCHEDULE.NO_SLOTS'|trans }}</p>
{% endif %}
</div>
{% else %}
<p class="text-muted">{{ 'SCHEDULE.EMPTY_STATE'|trans }}</p>
{% endif %}
{# 3. o diálogo de agendamento, somente se a URL contiver &book=... #}
{% if booking %}
{% include 'fragments/booking.html.twig' %}
{% endif %}
{% endblock %}
|
A página principal. Três seções: a seleção de um médico e de um dia, a agenda e a janela de reserva.
- 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 ela é exibida ([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 “Reservar”;
- 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 nos demais casos) 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: “Reservar” é um simples link: ele reabre a página com a janela de reserva desse horário ([row.bookUrl]). Ele 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 confirmação;
- linhas 106–108: a janela de reserva, se solicitada pela URL (e se o horário estiver disponível para reserva).
11.20.3.3. templates/persons/list.html.twig
| {# =========================================================================
templates/persons/list.html.twig - a lista dos médicos OU dos clientes
(ADMIN). Uma única view para ambos: as chaves dos rótulos específicos de cada um
chegam em [keys], e [section] ("doctors" ou "clients") fornece o início dos
nomes das rotas (veja PersonsController): section ~ '_add' -> "doctors_add".
========================================================================= #}
{% extends 'layout.html.twig' %}
{% block content %}
<div class="d-flex justify-content-between align-items-center mb-3">
<h4 class="mb-0">{{ keys.title|trans }}</h4>
<a class="btn btn-primary" href="{{ path(section ~ '_add') }}">{{ keys.add|trans }}</a>
</div>
<div class="card p-3">
{% if persons is not empty %}
<table class="table table-hover align-middle mb-0">
<thead>
<tr>
<th>{{ 'PERSONS.COLUMN_TITLE'|trans }}</th>
<th>{{ 'PERSONS.COLUMN_FIRSTNAME'|trans }}</th>
<th>{{ 'PERSONS.COLUMN_LASTNAME'|trans }}</th>
<th>{{ 'PERSONS.COLUMN_LOGIN'|trans }}</th>
<th></th>
</tr>
</thead>
<tbody>
{# person.title: o Twig chama o getter getTitle() (veja o exemplo 13) #}
{% for person in persons %}
<tr>
<td>{{ person.title }}</td>
<td>{{ person.firstName }}</td>
<td>{{ person.lastName }}</td>
<td><code>{{ person.account.login }}</code></td>
<td class="text-end">
<div class="d-inline-flex gap-2">
<a class="btn btn-sm btn-outline-primary"
href="{{ path(section ~ '_edit', {id: person.id}) }}">{{ 'PERSONS.EDIT'|trans }}</a>
{# data-confirmation: um diálogo de confirmação será aberto antes de
o formulário ser enviado (veja public/js/app.js) #}
<form method="post" action="{{ path(section ~ '_delete', {id: person.id}) }}" class="m-0"
data-confirmation="{{ keys.confirmDelete|trans }}">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{ 'PERSONS.DELETE'|trans }}</button>
</form>
</div>
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p class="text-muted mb-0">{{ keys.empty|trans }}</p>
{% endif %}
</div>
{% endblock %}
|
A lista de médicos ou de clientes: os rótulos específicos de cada um são chaves de tradução ([keys]), e os nomes das rotas são gerados a partir do nome da seção ([path(section ~ '_edit', {id: person.id})]: o operador [~] concatena, resultando em [doctors_edit] ou [clients_edit]). [person.account.login]: o login da conta, preenchido junto com a lista (camada DAO). O botão Excluir é um formulário POST, com confirmação.
| {# =========================================================================
templates/persons/form.html.twig - criação OU modificação de um
médico ou de um cliente (ADMIN), com o formulário PersonType.
Quando a entrada é recusada (campo vazio, login já existente...), a action
exibe ESTA página novamente, e a view mostra:
- os valores já digitados (exceto a senha);
- os campos com problema contornados em vermelho (classe Bootstrap "is-invalid");
- sob um campo recusado pela validação, sua mensagem;
- a mensagem de erro da página, NO FINAL da página (fragmento errors).
form_start escreve a tag <form> (método POST, URL da página); form_end, o
fim do formulário, com os campos que ainda não foram escritos: o
token anti-CSRF e, na modificação, o campo oculto version (o bloqueio otimista).
========================================================================= #}
{% extends 'layout.html.twig' %}
{% import 'macros.html.twig' as m %}
{% block content %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-3">{{ pageTitle|trans }}</h5>
{{ form_start(form) }}
{# form_errors: os erros do próprio formulário (token anti-CSRF incorreto) #}
{{ form_errors(form) }}
{# título, nome, sobrenome: uma macro comum a três formulários #}
{{ m.identity(form, invalidFields) }}
<h6 class="mt-4 text-muted">{{ 'PERSONS.ACCOUNT_SECTION'|trans }}</h6>
{{ m.field(form.login, invalidFields) }}
{# nunca preenchido previamente: a senha nunca volta para o navegador #}
{{ m.field(form.password) }}
<div class="d-flex gap-2 mt-4">
<button type="submit" class="btn btn-primary">{{ 'PERSONS.SAVE'|trans }}</button>
<a class="btn btn-secondary" href="{{ listUrl }}">{{ 'PERSONS.BACK'|trans }}</a>
</div>
{{ form_end(form) }}
</div>
</div>
</div>
{% endblock %}
|
Criação ou edição de um médico ou de um cliente por meio do formulário [PersonType].
- Linha 16: importação das macros sob o nome [m];
- Linha 24: [form_start] escreve a tag [<form>]: o método POST, a URL da página e o atributo [novalidate] (opção [attr] do tipo);
- linha 26: [form_errors(form)] exibe os erros do próprio formulário que não se relacionam a nenhum campo específico: um token anti-CSRF inválido (“A página expirou...”);
- linha 28: título, nome e sobrenome, por meio da macro [identity];
- linhas 31–33: o nome de usuário e a senha, que nunca são preenchidos previamente. Suas dicas diferem entre criação e modificação (opções do tipo);
- linha 39: [form_end] fecha o formulário após escrever os campos que ainda não foram escritos: o token anti-CSRF e, na edição, o campo oculto de versão (o bloqueio otimista).
11.20.3.5. templates/registration.html.twig
| {# =========================================================================
templates/registration.html.twig - "Criar uma conta de paciente" (página pública, veja
RegistrationController), com o formulário RegistrationType. Mesmos campos de
identidade que o formulário do ADMIN (macro identity), mas o login e a
senha são obrigatórios, com confirmação. Sem captcha AQUI: só se
chega a esta página depois de ter copiado o da página de login
(botão "Criar uma conta de paciente").
========================================================================= #}
{% extends 'layout.html.twig' %}
{% import 'macros.html.twig' as m %}
{% block content %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-1">{{ 'REGISTRATION.TITLE'|trans }}</h5>
<p class="text-muted small mb-3">{{ 'REGISTRATION.INTRO'|trans }}</p>
{{ form_start(form) }}
{{ form_errors(form) }}
{{ m.identity(form, invalidFields) }}
<h6 class="mt-4 text-muted">{{ 'PERSONS.ACCOUNT_SECTION'|trans }}</h6>
{{ m.field(form.login, invalidFields) }}
{# o campo repetido: seus dois campos de entrada, lado a lado (first, second) #}
<div class="row g-3">
<div class="col-sm-6">{{ m.field(form.password.first) }}</div>
<div class="col-sm-6">{{ m.field(form.password.second) }}</div>
</div>
<div class="d-flex gap-2 mt-3">
<button type="submit" class="btn btn-primary">{{ 'REGISTRATION.SUBMIT'|trans }}</button>
<a class="btn btn-secondary" href="{{ path('login') }}">{{ 'REGISTRATION.BACK_TO_LOGIN'|trans }}</a>
</div>
{{ form_end(form) }}
</div>
</div>
</div>
{% endblock %}
|
Criação de uma conta de paciente: os campos de identidade, seguidos do nome de usuário, da senha e da confirmação da senha, que são obrigatórios. Os dois campos do campo repetido são [form.password.first] e [form.password.second] (linhas 27–28), colocados lado a lado. O texto de ajuda da senha especifica o comprimento mínimo: “Pelo menos 6 caracteres.” Não há CAPTCHA aqui: só é possível chegar a esta página depois de resolver o CAPTCHA da página de login.
11.20.3.6. templates/area.html.twig
| {# =========================================================================
templates/area.html.twig - "Minha área": a página inicial do paciente (papel
USER), exibida logo após o login.
- duas opções: [Manage my account] e [View a schedule];
- sua consulta futura, se tiver uma, com o meio de cancelá-la.
========================================================================= #}
{% extends 'layout.html.twig' %}
{% block content %}
<h4 class="mb-3">{{ 'AREA.HELLO'|trans({name: patient}) }}</h4>
<div class="row g-3 mb-4">
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="{{ path('account') }}">
<h5 class="mb-1">{{ 'AREA.MANAGE_ACCOUNT'|trans }}</h5>
<span class="text-muted">{{ 'AREA.MANAGE_ACCOUNT_HELP'|trans }}</span>
</a>
</div>
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="{{ path('schedule') }}">
<h5 class="mb-1">{{ 'AREA.VIEW_SCHEDULE'|trans }}</h5>
<span class="text-muted">{{ 'AREA.VIEW_SCHEDULE_HELP'|trans }}</span>
</a>
</div>
</div>
<div class="card p-3">
<h5>{{ 'AREA.MY_APPOINTMENT'|trans }}</h5>
{# normalmente apenas uma (regra "uma consulta futura por vez"), mas a
página pode exibir várias. {% for %} ... {% else %}: um laço e
o que é exibido se a lista estiver vazia; loop.last: último elemento? #}
{% for appointment in appointments %}
<div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2{{ not loop.last ? ' border-bottom' }}">
<div>
<div class="fw-semibold">{{ appointment.day }}, {{ appointment.time }}</div>
<div class="text-muted">
<span>{{ appointment.doctor }}</span> -
<a href="{{ appointment.scheduleUrl }}">{{ 'AREA.SEE_IN_SCHEDULE'|trans }}</a>
</div>
</div>
<form method="post" action="{{ path('area_cancel') }}" class="m-0"
data-confirmation="{{ 'SCHEDULE.CANCEL_CONFIRM'|trans }}">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<input type="hidden" name="appointmentId" value="{{ appointment.id }}">
<button type="submit" class="btn btn-outline-danger">{{ 'AREA.CANCEL_APPOINTMENT'|trans }}</button>
</form>
</div>
{% else %}
<p class="text-muted mb-0">{{ 'AREA.NO_APPOINTMENT'|trans }}</p>
{% endfor %}
</div>
{% endblock %}
|
“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–50: [{% for %}] ... [{% else %}] (Exemplo 14) é um laço, seguido do que exibir se a lista estiver vazia. Normalmente, um paciente tem no máximo uma consulta futura; no entanto, a página é capaz de 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.20.3.7. templates/account.html.twig
| {# =========================================================================
templates/account.html.twig - "Gerenciar minha conta" (papel USER).
Dois formulários independentes na mesma página:
1. a modificação (identidade, login, nova senha opcional), com
o formulário MyAccountType;
2. a exclusão da conta - que também cancela suas consultas: um
formulário escrito à mão.
Ambos exigem a senha ATUAL (campo current_password).
========================================================================= #}
{% extends 'layout.html.twig' %}
{% import 'macros.html.twig' as m %}
{% block content %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
{# 1. modificação #}
<div class="card p-4 mb-4">
<h5 class="card-title mb-3">{{ 'MY_ACCOUNT.TITLE'|trans }}</h5>
{{ form_start(form) }}
{{ form_errors(form) }}
{{ m.identity(form, invalidFields) }}
<h6 class="mt-4 text-muted">{{ 'PERSONS.ACCOUNT_SECTION'|trans }}</h6>
{{ m.field(form.login, invalidFields) }}
<div class="row g-3">
<div class="col-sm-6">{{ m.field(form.password.first) }}</div>
<div class="col-sm-6">{{ m.field(form.password.second) }}</div>
</div>
{{ m.field(form.current_password) }}
<div class="d-flex gap-2 mt-4">
<button type="submit" class="btn btn-primary">{{ 'PERSONS.SAVE'|trans }}</button>
<a class="btn btn-secondary" href="{{ path('area') }}">{{ 'MY_ACCOUNT.BACK'|trans }}</a>
</div>
{{ form_end(form) }}
</div>
{# 2. exclusão. O campo de senha tem o mesmo NOME que o do primeiro
formulário (current_password), mas outro id: dois elementos da mesma
página não podem ter o mesmo id #}
<div class="card p-4 border-danger">
<h5 class="card-title text-danger mb-1">{{ 'MY_ACCOUNT.DELETE_TITLE'|trans }}</h5>
<p class="text-muted small">{{ 'MY_ACCOUNT.DELETE_HELP'|trans }}</p>
<form method="post" action="{{ path('account_delete') }}" class="d-flex flex-wrap gap-2 align-items-end"
data-confirmation="{{ 'MY_ACCOUNT.DELETE_CONFIRM'|trans }}">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<div class="flex-grow-1">
<label class="form-label" for="delete_password">{{ 'MY_ACCOUNT.CURRENT_PASSWORD_LABEL'|trans }}</label>
<input id="delete_password" name="current_password" type="password" maxlength="72"
autocomplete="current-password" required class="form-control">
</div>
<button type="submit" class="btn btn-danger">{{ 'MY_ACCOUNT.DELETE_SUBMIT'|trans }}</button>
</form>
</div>
</div>
</div>
{% endblock %}
|
“Gerenciar minha conta”: dois formulários independentes na mesma página.
- Linhas 18–38: a atualização, usando o formulário [MyAccountType]: os campos de identidade, o login, a nova senha e sua confirmação (opcionais) e a senha atual (obrigatória). A versão (bloqueio otimista) é definida por [form_end];
- Linhas 43–56: exclusão da conta, um formulário escrito à mão com seu próprio campo de senha atual e um campo de confirmação. O campo se chama [current_password] (o campo do primeiro formulário se chama [my_account[current_password]]: o componente Form prefixa os nomes de seus campos com o nome do formulário) e tem seu próprio ID único: dois elementos de uma página não podem ter o mesmo ID, conforme indicado pelo atributo [for] de um label.
11.20.3.8. templates/error.html.twig
| {# =========================================================================
templates/error.html.twig - a página de erro (400, 403, 404, 405, 419,
500...), construída por src/EventListener/ErrorPage.php.
========================================================================= #}
{% extends 'layout.html.twig' %}
{% block content %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4 text-center">
<h1 class="display-4 text-danger">{{ code }}</h1>
<p class="lead">{{ message|trans }}</p>
<div><a class="btn btn-primary" href="{{ path('home') }}">{{ 'ERROR_PAGE.BACK'|trans }}</a></div>
</div>
</div>
</div>
{% endblock %}
|
A página de erro, gerada pelo listener [ErrorPage]: 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.21. Arquivos estáticos
A pasta [public] é o diretório raiz do site: o servidor envia como estão os arquivos que estão ali (exemplo 15). Além de [index.php], ela contém o [Bootstrap] ([lib/bootstrap]), uma folha de estilos e um script.
11.21.1. public/css/styles.css
| /* =========================================================================
public/css/styles.css - alguns ajustes por cima do 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, no rodapé da página, sobre um fundo rosa claro
(veja templates/fragments/errors.html.twig).
position: sticky + bottom: se a página for mais alta que a janela (uma
agenda de 12 horários, por exemplo), a zona permanece fixa 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 do diálogo de agendamento (.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 da agenda fica verde quando o mouse passa sobre ela;
- linhas 23–33: a área de erros na parte inferior da página tem um fundo rosa-claro. [position: sticky] com [bottom: 1rem]: se a página for mais alta que a janela (uma agenda 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 reserva;
- linhas 36–43: os dois cartões grandes de “Minha área”, que se iluminam quando o mouse passa sobre eles;
- linhas 46–50: a imagem do CAPTCHA, com uma borda.
11.21.2. public/js/app.js
| // =========================================================================
// public/js/app.js - o ÚNICO JavaScript da aplicação.
// -------------------------------------------------------------------------
// Toda a aplicação 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: templates/fragments/confirmation.html.twig).
// 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()? A caixa dele não pode ser estilizada, e os
// botões dela 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 por distração 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 fechar)
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 o evento
// 'submit' novamente: 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. A aplicação inteira funciona sem [JavaScript]: esse script acrescenta conveniência ao pedir uma confirmação antes de enviar um formulário que tenha 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–19: 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, caso o usuário confirme, é 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 vai 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–51: o envio de cada formulário a ser confirmado é interceptado ([preventDefault] o impede), e a janela é aberta;
- linhas 54–67: os botões da janela. Um único handler para a janela inteira: [closest('[data-action]')] encontra 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]: nenhuma nova solicitação de confirmação é emitida. 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 com leitores de tela.