Skip to content

11. Fallstudie: Die Anwendung RdvMedecins

11.1. Die Aufgabenstellung

Die Anwendung RdvMedecins verwaltet die Termine einer Arztpraxis. Jeder Arzt hat Zeitfenster (zum Beispiel von 8:00 bis 12:00 Uhr in 20-Minuten-Schritten); ein Termin besteht aus einem Tag, einem Zeitfenster und einem Klienten (einem Patienten). Dies ist die exakte Portierung der [Symfony]-Version der [Laravel]-Anwendung aus der vorherigen Lektion (die ihrerseits aus den Versionen [Flask], [Spring MVC] und [ASP.NET Core MVC] portiert wurde): dieselbe Datenbank, dieselben Geschäftsregeln, dieselben Seiten, dieselben URLs, derselbe Text. Die HTML-Seiten werden vom Server mit [Twig]-Views erzeugt; der Datenbankzugriff erfolgt über [Doctrine].

Drei Benutzerrollen teilen sich die Anwendung:

ADMIN
der Administrator ([admin])
Terminkalender einsehen, Termine für beliebige Patienten buchen und stornieren; Ärzte und Klienten verwalten (auflisten, hinzufügen, bearbeiten, löschen)
DOCTOR
Ärzte
Terminkalender einsehen, Termine buchen und Termine beliebiger Patienten stornieren
USER
Klienten (Patienten)
Terminkalender einsehen, ohne die Namen anderer Patienten zu sehen; einen Termin für sich selbst buchen; ihren Termin stornieren; ihr Konto verwalten; ein Konto erstellen

Wichtige Verwaltungsregeln:

  • keine Termine in der Vergangenheit;
  • ein Zeitfenster kann pro Tag nur einmal gebucht werden;
  • ein Patient kann jeweils nur einen bevorstehenden Termin haben;
  • Zwei Ärzte (oder zwei Klienten) dürfen nicht denselben Vor- und Nachnamen haben, und ein Login gehört zu nur einem Konto;
  • Ein Arzt mit Terminen kann nicht gelöscht werden; ein Klient wird zusammen mit seinen Terminen gelöscht;
  • die Anmeldeseite ist gegen Bots geschützt (CAPTCHA, begrenzte Versuche), und das Erstellen eines Patientenkontos setzt voraus, dass zuvor auf dieser Seite das CAPTCHA gelöst wird.

11.2. Verwendung der Anwendung

11.2.1. Die Anmeldeseite

Image

Die Seite enthält zwei Schaltflächen: Anmelden und Patientenkonto erstellen. Bei beiden müssen die im Bild gezeigten Zeichen eingegeben werden. Die Schaltflächen FR / EN wechseln die Sprache:

Image

Ein Fehler (hier ein falsch eingegebenes CAPTCHA) wird am Seitenende auf hellrosa Hintergrund angezeigt:

Image

11.2.2. Der Kalender aus Sicht des Administrators und der Ärzte

Nach der Anmeldung gelangt der Administrator zur Kalenderseite. Er wählt einen Arzt und einen Tag aus:

Image

Image

Jedes Zeitfenster ist entweder frei (Schaltfläche Buchen) oder belegt (Name des Patienten, Schaltfläche Stornieren). Ein Klick auf Buchen öffnet ein Fenster, das nach den Daten des Patienten fragt. Dieses Fenster wird wie der Rest der Seite vom Server erzeugt: Die URL enthält nun den Parameter [book=4], die Nummer des gewählten Zeitfensters:

Image

Nach der Buchung bestätigt eine Meldung den Termin:

Image

Ein Klick auf „Stornieren“ löst eine Bestätigungsabfrage aus (hier durch Dr. Pélissier, dessen Navigationsleiste die Administrationsmenüs nicht enthält):

Image

11.2.3. Das Patientenportal

Ein Patient (Rolle USER) gelangt zu „Mein Bereich“: seinem bevorstehenden Termin, den er stornieren kann, sowie Links zur Verwaltung seines Kontos und zur Ansicht seines Kalenders. Hier hat er noch keinen Termin:

Image

Im Kalender sieht er die Namen anderer Patienten nicht; sie werden durch „Belegt“ ersetzt: Dieser Name erscheint nicht einmal im Quelltext der Seite. Er kann ein freies Zeitfenster buchen:

Image

Das Buchungsfenster fordert ihn nicht auf, einen Patienten auszuwählen: Er bucht den Termin für sich selbst.

Image

Image

Seine Übersicht zeigt nun seinen bevorstehenden Termin an, den er stornieren kann:

Image

Da er einen bevorstehenden Termin hat, kann er keinen weiteren vereinbaren: Die Schaltfläche „Buchen“ wird nicht angezeigt, und im Kalender eines anderen Tages oder eines anderen Arztes erklärt eine Meldung den Grund:

Image

Kontoverwaltung: seine Daten bearbeiten, sein Passwort ändern oder sein Konto (samt Terminen) löschen. Für jede Änderung ist das aktuelle Passwort erforderlich:

Image

Ein Patient, der versucht, eine dem Administrator vorbehaltene Seite zu öffnen (hier [/doctors], von Hand eingegeben), erhält eine Fehlerseite:

Image

11.2.4. Verwaltung von Ärzten und Patienten

Der Administrator hat zwei zusätzliche Menüs, Ärzte und Patienten:

Image

Image

Das Formular zum Hinzufügen eines Arztes, mit Fehlern abgesendet:

Image

Ein Name, der mit dem eines vorhandenen Arztes übereinstimmt, wird abgelehnt, auch wenn er kleingeschrieben und mit einem Akzent eingegeben wird (die Datenbank selbst vergleicht Namen ohne Unterscheidung von Groß- und Kleinbuchstaben und Akzenten; siehe Beispiel 28):

Image

Das Löschen eines Patienten erfordert eine Bestätigung:

Image

11.2.5. Erstellen eines Patientenkontos

Auf der Anmeldeseite öffnet die Schaltfläche „Patientenkonto erstellen“ das Formular nur, wenn das CAPTCHA korrekt eingegeben wurde:

Image

Sobald das Konto erstellt ist, wird der Benutzer auf die Anmeldeseite umgeleitet, wobei sein Benutzername bereits eingetragen ist:

Image

11.2.6. Abmelden

Das Anmelde-Token ist zwei Stunden gültig. Danach (oder wenn das Token manipuliert wurde) leitet die angeforderte Seite mit der folgenden Meldung auf die Anmeldeseite um:

Image

11.3. Installation und Ausführung

Die Anwendung befindet sich im Ordner [rdvmedecins2-symfony] neben dem Ordner [examples]. Sie ist ein eigenständiges Projekt mit eigenen Dateien [composer.json] und [.env] und einem eigenen Ordner [vendor]. Die Datei [README.md] im Ordner enthält alles Folgende. Die Einleitung dieses Dokuments hat die Installation von [PHP] und [Composer] bereits beschrieben; hier vertiefen wir sie.

11.3.1. Benötigte Software

Drei Softwarekomponenten genügen:

  • [PHP] 8.4 oder höher, mit den Erweiterungen [pdo_mysql] und [intl] ([Symfony] 8 erfordert [PHP] 8.4, und die Anwendung nutzt in dieser Version eingeführte Funktionen wie [array_find]). Überprüfen Sie die Installation in einem Terminal:
php -v
php -m

Der zweite Befehl listet die Erweiterungen auf: [pdo_mysql] und [intl] sollten dort aufgeführt sein;

  • [Composer], der Bibliotheksmanager für [PHP] (siehe Anhänge);
  • ein [MySQL]-8-Server, zum Beispiel der von [Laragon] unter [Windows] (siehe Anhänge). [MariaDB] ist ebenfalls geeignet.

Als Editor wird [Visual Studio Code] mit den Erweiterungen [PHP Intelephense] und [Twig Language 2] empfohlen (siehe Anhänge); alles lässt sich jedoch auch über die Befehlszeile erledigen.

11.3.2. Die Bibliotheken installieren

Der Ordner [vendor] wird nicht mitgeliefert: Erstellen Sie ihn einmalig in einem Terminalfenster, das im Ordner [rdvmedecins2-symfony] geöffnet ist (Sie müssen mit dem Internet verbunden sein):

composer install

[Composer] liest die Datei [composer.json] (wird später besprochen), lädt [Symfony], [Doctrine], [Twig], [firebase/php-jwt] und die Bibliotheken herunter, von denen sie abhängen, und erzeugt den Class Loader [vendor/autoload.php] sowie die Datei [vendor/autoload_runtime.php] für die Komponente [Runtime] (wird weiter unten besprochen).

11.3.3. Die Datenbank erstellen

Die Datenbank [dbrdvmedecins2] wird durch das Skript [database/dbrdvmedecins2.sql] erstellt. Öffnen Sie mit [Laragon] das Tool [HeidiSQL] (Schaltfläche Datenbank) und führen Sie das Skript dann über das Menü Datei / SQL-Datei ausführen aus. In der Befehlszeile, im Anwendungsordner:

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

Die Option [-p] fragt nach dem Passwort für [root]; lassen Sie sie weg, wenn das Konto kein Passwort hat (wie bei [Laragon]). Dies ist dieselbe Datenbank wie in den anderen Versionen der Anwendung: Existiert sie bereits, ist dieser Schritt optional. Das Skript kann jederzeit ausgeführt werden, um zu den ursprünglichen Daten zurückzukehren.

11.3.4. Den Datenbankzugriff konfigurieren

Die gesamte Installationskonfiguration befindet sich in der Datei [.env] (wird weiter unten besprochen). Standardmäßig verbindet sich die Anwendung mit [MySQL] auf [127.0.0.1], Port 3306, mit dem Benutzer [root] ohne Passwort: Dies sind die Standardeinstellungen von [Laragon]. Wenn Ihr [root]-Konto ein Passwort hat, tragen Sie es in dieser Datei in der [DATABASE_URL]-Zeile nach [root:] ein. Eine Umgebungsvariable des Systems hat Vorrang vor der Datei (Beispiel 25): So können Sie die URL der Datenbank angeben, ohne sie in eine Projektdatei zu schreiben.

11.3.5. Die Anwendung starten

In einem Terminalfenster, das im Ordner [rdvmedecins2-symfony] geöffnet ist:

php -S localhost:8081 -t public
[Sun Sep 27 18:40:12 2026] PHP 8.4.21 Development Server (http://localhost:8081) started

Öffnen Sie anschließend die URL [http://localhost:8081] in einem Browser und beenden Sie die Anwendung mit [Ctrl-C]. Der Port 8081 erlaubt es, gleichzeitig ein Beispiel des Kurses (Port 8000) auszuführen. Das Befehlszeilenwerkzeug [symfony] (siehe Anhänge) bietet einen umfassenderen Server, der die Anwendung auch über HTTPS bereitstellen kann: [symfony server:start --port=8081].

11.3.6. Demokonten

Das Passwort jedes Kontos entspricht seinem Benutzernamen; außerdem müssen Sie die Zeichen aus dem Bild eingeben, in Groß- oder Kleinschreibung:

[admin]
ADMIN (der Administrator)
[pelissier], [tatou], [dupont]
DOCTOR (die Ärzte)
[martin], [durand], [bistrou], [german]
USER (Patienten)

Eine Anleitung zum Erkunden der Anwendung:

  • [admin]: Terminkalender, Frau Marie PELISSIER; heute: Ein Zeitfenster ist bereits von Frau Brigitte BISTROU gebucht. Buchen Sie ein Zeitfenster für Herrn Jean MARTIN und versuchen Sie dann, einen zweiten Termin für ihn zu buchen (abgelehnt). Menüs Ärzte und Patienten: hinzufügen, bearbeiten, löschen (Dr. PELISSIER, der Termine hat, kann nicht gelöscht werden);
  • [pelissier]: Sein Tagesterminkalender wird direkt angezeigt; die von Hand eingegebene Adresse [/doctors] liefert eine 403-Fehlerseite;
  • [martin]: Mein Bereich, sein Termin, der Kalender, in dem andere Patienten als „Belegt“ erscheinen; Mein Konto verwalten;
  • Anmeldeseite: Patientenkonto erstellen, dann mit dem neuen Konto anmelden;
  • Schaltflächen FR / EN: Die gesamte Oberfläche wechselt die Sprache, einschließlich der Datumsangaben.

11.3.7. Entwicklungsmodus

Die mitgelieferte Datei [.env] konfiguriert die Anwendung für die Entwicklung ([APP_ENV=dev]):

  • Die Serverkonsole zeigt das Log von [Symfony] an (Beispiel 24): die gewählte Route, die Sicherheitsschritte und jeden an die Datenbank gesendeten SQL-Befehl (Beispiel 28). Zum Beispiel für die Anzeige eines Kalenders (gekürzte Zeilen):
[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

Hier sehen wir das Routing, den Authenticator und dann drei Abfragen: den Arzt und sein Konto, die heutigen Termine und ihre Patienten sowie die freien Zeitfenster des Arztes. Die Liste der Ärzte im Dropdown-Menü wird dagegen nicht gelesen; sie stammt aus dem Cache (wird später besprochen);

  • eine unerwartete Exception zeigt die Debug-Seite von [Symfony] an (Beispiel 03), mit der Meldung der Exception und dem Call Stack. In der Produktion zeigt die Anwendung stattdessen ihre eigene 500-Fehlerseite an;
  • Nach einer Änderung muss nichts neu gestartet werden: Jede Anfrage liest die [PHP]-Dateien neu ein (Beispiel 01), und im Modus [dev] baut [Symfony] seinen eigenen Cache (den Container, die Routen und die kompilierten Views) neu auf, wenn sich eine Datei geändert hat.

Der Debugger [Xdebug] ermöglicht es außerdem, die Anwendung schrittweise aus [Visual Studio Code] (Erweiterung [PHP Debug]) zu durchlaufen: Dies ist eine Erweiterung von [PHP], die separat installiert werden muss (siehe xdebug.org). Die Debug-Leiste von [Symfony] ([WebProfilerBundle], [composer require --dev symfony/web-profiler-bundle]) zeigt am Ende jeder Seite die Details der Anfrage an: die Route, den Benutzer, die SQL-Befehle und ihre Parameter, Übersetzungen, Ausführungszeiten ...

11.3.8. Ein Produktionsserver

Der Entwicklungsserver von [PHP] ist nicht für die Produktion gedacht. In der Produktion wird die Anwendung von einem Webserver ([nginx], [Apache]) bereitgestellt, der Anfragen an [PHP-FPM] weiterleitet, einen Prozessmanager ([PHP]). Das Wurzelverzeichnis der Website ist der Ordner [public]: Nur seine Dateien sind vom Browser aus erreichbar; der Ordner [var] muss für den Server beschreibbar sein. In der Datei [.env] müssen Sie den Produktionsmodus angeben, die geheimen Schlüssel ändern und deklarieren, dass die Website über HTTPS ausgeliefert wird:

1
2
3
4
APP_ENV=prod
APP_SECRET=<a long random string>
JWT_SECRET=<another long random string>
COOKIE_SECURE=1

Eine geeignete Zufallszeichenkette lässt sich von [PHP] selbst erzeugen: [php -r "echo bin2hex(random_bytes(32));"]. Die Anwendung wird dann mit zwei Befehlen vorbereitet:

composer install --no-dev --optimize-autoloader
php bin/console cache:clear

Der zweite Befehl erzeugt den Produktions-Cache (den kompilierten Container, die Routen, die kompilierten Views usw.): Im Modus [prod] prüft [Symfony] nicht mehr, ob sich Dateien geändert haben, was schneller ist; er muss daher nach jeder Änderung erneut ausgeführt werden. Der Befehl [composer dump-env prod] wandelt außerdem die Datei [.env] in eine [PHP] -Datei ([.env.local.php]) um, die schneller gelesen wird.

11.3.9. Häufige Probleme

Eine [PHP]-Anwendung „startet“ nicht: Jede Anfrage baut die Anwendung neu auf (Beispiel 01). Eine nicht erreichbare Datenbank verhindert daher nicht den Start des Servers: Der Fehler erscheint auf der ersten Seite, die die Datenbank abfragt (die Anmeldeseite fragt die Datenbank nicht ab; der Anmeldevorgang tut es). Im Modus [dev] wird der Fehler auf der Debug-Seite von [Symfony] angezeigt; in jedem Fall wird er in der Logdatei protokolliert, die der Entwicklungsserver in der Konsole anzeigt. Zum Beispiel bei einer Datenbank, die nicht existiert:

[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

Die häufigsten Meldungen:

[Failed opening required '.../vendor/autoload_runtime.php']
Der Befehl [composer install] wurde nicht ausgeführt
[Your Composer dependencies require a PHP version ">= 8.4.0"]
Die Version von [PHP] ist älter als 8.4
[could not find driver]
Die Erweiterung [pdo_mysql] für [PHP] ist nicht aktiviert (Datei [php.ini] oder Menü PHP / Erweiterungen in [Laragon])
[SQLSTATE[HY000] [2002] Connection refused]
[MySQL] wurde nicht gestartet oder lauscht nicht auf [127.0.0.1:3306]
[SQLSTATE[HY000] [1045] Access denied for user 'root'@'localhost']
Das Passwort für [MySQL] muss in [DATABASE_URL] eingetragen werden (siehe „Den Datenbankzugriff konfigurieren“)
[SQLSTATE[HY000] [1049] Unknown database 'dbrdvmedecins2']
Das Skript [database/dbrdvmedecins2.sql] wurde nicht ausgeführt
[JWT_SECRET must be at least 32 characters long (see .env).]
Der geheime Schlüssel für die Tokens in [.env] ist zu kurz
[Failed to listen on localhost:8081 (reason: Address already in use)]
Der Port 8081 ist bereits belegt (läuft eine andere Version der Anwendung?): Beenden Sie sie oder wählen Sie einen anderen Port

11.4. Architektur der Anwendung

Image

  • Der Browser sendet seine Anfragen an den Server ([php -S] oder [nginx] + [PHP-FPM]), der sie an [Symfony] weiterleitet, und zwar über die Datei [public/index.php]. Der Kern von [Symfony] veröffentlicht Ereignisse zur Verarbeitung der Anfrage (siehe das Kapitel zum Lebenszyklus), auf die Listener reagieren: die Sprache der Anfrage ([SetLanguage]), das Routing, die Session und dann die Firewall der Security-Komponente: Der Benutzer wird anhand des JWT-Tokens in seinem Cookie identifiziert ([TokenAuthenticator]), und die Regeln [access_control] verweigern nicht berechtigten Besuchern den Zugriff auf geschützte Seiten. Fehler führen zu HTML-Seiten ([ErrorPage]);
  • [Controller]: die Controller der Web-Schicht. Sie laufen alle über ein einziges Objekt, [ApplicationModel] (Ordner [Web]), das die Listen der Ärzte und Clients zwischenspeichert und andere Anfragen an die Geschäftsschicht weiterleitet; [Form]: Formulare und ihre Constraints; [Views]: View-Templates;
  • [Security]: Token, JWT, der Authenticator, das CAPTCHA, die Begrenzung der Versuche und der Pass für die Kontoerstellung;
  • [Web]: Was die Controller gemeinsam haben: der Cache und die Fassade [ApplicationModel], die Elternklasse der Controller, Flash-Nachrichten und einige Hilfsfunktionen;
  • [Business]: Geschäftsregeln und Transaktionen;
  • [Dao]: die DAO-Schicht, eine Klasse pro Tabelle;
  • [Entity]: die Entitäten [Doctrine], die die DAO-Schicht aus der Datenbank liest und in sie schreibt; [Domain]: die Kalenderobjekte, die von der Geschäftsschicht berechnet werden;
  • [templates]: die [Twig]-Views, die die HTML-Seiten erzeugen; [translations]: die Wörterbücher; [public]: das Stylesheet, das Seitenskript und [Bootstrap];
  • der Ordner [config] und die Datei [.env]: die Konfiguration, die alles zusammenführt.

Der Anwendungsordner (ohne [vendor] und [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

Dies ist die Struktur einer standardmäßigen [Symfony]-Anwendung – derjenigen, die der Befehl [composer create-project symfony/skeleton] erzeugt (Beispiel 01) –, ergänzt um die Bundles, die die Anwendung benötigt. Zwei Unterschiede zu den Beispielen: Die Anwendung hat einen eigenen Ordner [vendor] (die Beispiele teilten sich den Ordner im Verzeichnis [examples]), und ihr Einstiegspunkt verwendet die Komponente [Runtime] von [Symfony] (wird später behandelt). Die Klassen der Anwendung sind im Ordner [src] nach der PSR-4-Regel organisiert (Beispiel 01): Die Klasse [App\Business\BusinessService] befindet sich in der Datei [src/Business/BusinessService.php]. [Symfony] verlangt keinen dieser Ordner: [Controller], [Entity], [EventListener], [Form] und [Twig] sind die gebräuchlichen (die von [MakerBundle] verwendeten), während die übrigen ([Dao], [Business], [Security]...) zur Schichtenarchitektur aus Beispiel 28 gehören. [Bootstrap] ist diesmal Teil der Anwendung (Ordner [public/lib/bootstrap]): Die Fallstudie ist in sich geschlossen.

11.5. Die Datenbank

Die Datenbank [dbrdvmedecins2] besteht aus fünf Tabellen:

  • [users]: Benutzer, die sich anmelden dürfen;
  • [doctors] und [clients]: Ärzte und Patienten, jeweils mit ihrem Benutzerkonto verknüpft;
  • [slots]: die verfügbaren Zeitfenster jedes Arztes;
  • [appointments]: Termine, ein Client pro Zeitfenster an einem bestimmten Tag.

11.5.1. database/dbrdvmedecins2.sql

-- =========================================================================
-- Datenbank [dbrdvmedecins2] - MySQL 8
--
-- Weiterentwicklung von [dbrdvmedecins]:
--   1. die Tabellen [doctors] und [clients] erhalten eine Spalte [user],
--      Fremdschlüssel auf users(id): jeder Arzt und jeder Kunde ist
--      nun auch ein Benutzer, der sich anmelden kann;
--   2. eine dritte Rolle kommt hinzu: DOCTOR (zusätzlich zu ADMIN und USER);
--   3. das Skript legt für jeden Arzt (Rolle DOCTOR) und für jeden Kunden
--      (Rolle USER) eine Zeile in [users] an:
--        - login        = Nachname in Kleinbuchstaben
--        - password     = Nachname in Kleinbuchstaben, mit bcrypt gehasht (10 Runden)
--        - display name = Vorname + Nachname
--
--   4. Eindeutigkeits-Constraints, alle BENANNT (die Anwendung erkennt
--      den Namen des verletzten Constraints in der MySQL-Fehlermeldung):
--        - unq_users_login                   : ein Login gehört nur zu einem Konto;
--        - unq_doctors_first_name_last_name  : zwei Ärzte dürfen nicht denselben
--                                              Vor- und Nachnamen haben;
--        - unq_clients_first_name_last_name  : dasselbe für die Kunden.
--      Achtung: die Kollation utf8mb4_unicode_ci vergleicht ohne Beachtung von
--      Groß-/Kleinschreibung und Akzenten - "Hélène DUPONT" und "helene dupont"
--      gelten daher als identisch.
--
-- Die Tabelle [users] muss nun VOR [doctors] und [clients] angelegt
-- (sie verweisen auf sie) und NACH ihnen gelöscht werden.
-- =========================================================================

-- das Skript ist in UTF-8 geschrieben
SET NAMES utf8mb4;

-- wir beginnen bei jeder Ausführung des Skripts mit einer leeren Datenbank (praktisch in der Entwicklung)
CREATE DATABASE IF NOT EXISTS dbrdvmedecins2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbrdvmedecins2;

-- Löschreihenfolge: von den "Kind"-Tabellen zu den "Eltern"-Tabellen
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;

-- -------------------------------------------------------------------------
-- Tabelle [users]: die Benutzer, die sich an der Anwendung anmelden dürfen
-- -------------------------------------------------------------------------
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'
  -- ein Login kann nur zu einem Konto gehören
  CONSTRAINT unq_users_login UNIQUE (login)
);

-- -------------------------------------------------------------------------
-- Tabelle [doctors]: die Ärzte der Praxis
-- -------------------------------------------------------------------------
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),
  -- ein Konto pro Arzt und ein Arzt pro Konto
  CONSTRAINT unq_doctors_user UNIQUE (`user`),
  -- zwei Ärzte dürfen nicht denselben Vor- und Nachnamen haben
  CONSTRAINT unq_doctors_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- Tabelle [clients]: die Patienten der Ärzte
-- -------------------------------------------------------------------------
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),
  -- ein Konto pro Kunde und ein Kunde pro Konto
  CONSTRAINT unq_clients_user UNIQUE (`user`),
  -- zwei Kunden dürfen nicht denselben Vor- und Nachnamen haben
  CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);

-- -------------------------------------------------------------------------
-- Tabelle [slots]: die Zeitfenster jedes Arztes
-- -------------------------------------------------------------------------
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)
);

-- -------------------------------------------------------------------------
-- Tabelle [appointments]: die von den Kunden gebuchten Termine
-- -------------------------------------------------------------------------
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),
  -- dasselbe Zeitfenster darf am selben Tag nur einmal gebucht werden
  CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
);

-- =========================================================================
-- Demodaten
-- =========================================================================

-- die Benutzer: Passwörter mit bcrypt gehasht (10 Salt-Runden)
--   admin/admin (ADMIN)
--   ein Konto DOCTOR pro Arzt, ein Konto USER pro Kunde
--   (das Demokonto user/user gibt es nicht mehr: ein Konto USER ist
--   jetzt IMMER das Konto eines Kunden, der buchen und das Konto verwalten kann)
--   (login = password = Nachname in Kleinbuchstaben)
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');

-- die Ärzte: die Spalte [user] wird anhand des Logins nachgeschlagen,
-- statt die Werte der Primärschlüssel von [users] vorauszusetzen
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'));

-- Zeitfenster des Arztes PELISSIER (doctor_id = 1): von 8:00 bis 12:00 Uhr in 20-Minuten-Schritten
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);

-- Zeitfenster des Arztes TATOU (doctor_id = 2): von 14:00 bis 18:00 Uhr in 20-Minuten-Schritten
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);

-- ein bereits gebuchter Termin, um sofort ein belegtes Zeitfenster im Terminkalender zu sehen
INSERT INTO appointments (day, slot_id, client_id) VALUES
  (CURDATE(), 2, 3);
  • Zeile 33: Die Datenbank wird angelegt, falls sie nicht existiert, mit dem Zeichensatz [utf8mb4] und der Kollation [utf8mb4_unicode_ci], die Zeichenketten ohne Rücksicht auf Groß- und Kleinschreibung und auf Akzente vergleicht (Beispiel 28);
  • Zeilen 37–41: Die Tabellen werden gelöscht und anschließend neu angelegt; das Skript versetzt die Datenbank in ihren Ausgangszustand zurück. Die Reihenfolge ist wichtig: Eine Tabelle kann nicht gelöscht werden, solange eine andere Tabelle sie über einen Fremdschlüssel referenziert;
  • Zeilen 46–55: Benutzer: ein Benutzername und ein mit [bcrypt] gehashtes Passwort (Beispiel 25), der nach der Anmeldung angezeigte Name und die Rolle ([ADMIN], [DOCTOR], oder [USER]). Die Constraint [unq_users_login] stellt sicher, dass ein Benutzername nur zu einem Konto gehört;
  • Zeilen 60–72: Jede Tabelle hat einen Primärschlüssel [id], der von der Datenbank erzeugt wird, und eine Spalte [version], die das optimistische Sperren realisiert (Beispiel 28). Die Spalte [user] ist ein Fremdschlüssel auf [users(id)]: Die Datenbank weist jeden Wert zurück, der nicht die ID eines vorhandenen Benutzers ist. Da [user] in der Sprache SQL ein reserviertes Wort ist, wird es in Backticks (Gravis) gesetzt. Drei Constraints: [fk_doctors_user] (der Fremdschlüssel), [unq_doctors_user] (ein Konto pro Arzt und ein Arzt pro Konto) und [unq_doctors_first_name_last_name] (keine Namensdoppelungen). Alle Constraints sind benannt: Die Anwendung erkennt eine verletzte Constraint an ihrem Namen;
  • Zeilen 77–89: Die Tabelle [clients] hat genau dieselben Spalten;
  • Zeilen 94–103: Ein Zeitfenster gehört zu einem Arzt; Beginn und Ende werden in Stunden und Minuten gespeichert;
  • Zeilen 108–118: Ein Termin besteht aus einem Tag (Typ [DATE], ohne Uhrzeit), einem Zeitfenster und einem Client. Die Constraint [unq1_appointments] verhindert, dass dasselbe Zeitfenster am selben Tag zweimal gebucht wird: Die Datenbank erzwingt diese Regel, selbst wenn zwei Benutzer versuchen, es gleichzeitig zu buchen;
  • Zeilen 130–140: Demo-Benutzer, deren Passwort ihrem Login entspricht. Die Hashes beginnen mit [$2b$10$]: dem Algorithmus ([bcrypt], Variante [2b]) und dem Kostenfaktor (10). Danach folgen das Salt und der Hash. Diese Hashes wurden von der [Flask]-Version der Anwendung berechnet; [PHP] schreibt eigene mit dem Präfix [$2y$], überprüft aber beide gleichermaßen gut;
  • Zeilen 144–147: Die Spalte [user] jedes Arztes wird über eine Unterabfrage anhand des Logins ermittelt, statt die Werte der Primärschlüssel anzunehmen;
  • Zeilen 170–171: Ein für heute ([CURDATE()]) bereits vereinbarter Termin im zweiten Zeitfenster von Dr. PELISSIER für Frau BISTROU: Der Kalender zeigt damit sofort ein gebuchtes Zeitfenster an.

Anders als bei [Symfony] wird die Datenbank nicht von [Doctrine] aus den Entitäten erzeugt, auch nicht über Migrationen (Beispiel 28): Sie wird mit den anderen Versionen der Anwendung geteilt, und das SQL-Skript ist allen gemeinsam. Der Befehl [php bin/console doctrine:schema:validate] prüft, ob die Entitätsbeschreibungen konsistent sind und ob sie den Datenbanktabellen entsprechen.

11.6. Die Projektkonfiguration

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
}
  • Zeilen 6–27: die von der Anwendung benötigten Bibliotheken und die Bedingungen, die sie erfüllen müssen. [^8.1] bedeutet „Version 8.1 oder eine neuere Version derselben Hauptversion 8“: [Composer] akzeptiert Versionen, die Fehler beheben oder Funktionen hinzufügen, aber nicht solche, die die Anwendung beschädigen könnten (Version 9). Die Zeilen [php], [ext-intl] und [ext-pdo_mysql] verweisen nicht auf Bibliotheken, sondern auf Anforderungen an die Umgebung: [Composer] verweigert die Installation, wenn die Version von [PHP] oder seiner Erweiterungen nicht kompatibel ist, statt die Anwendung später scheitern zu lassen. [Symfony] ist keine einzelne Bibliothek: Jede seiner Komponenten (Routing, Formulare, Sicherheit usw.) ist eine Bibliothek, und die Anwendung fordert nur die an, die sie benötigt; [Composer] installiert zusätzlich die Bibliotheken, von denen diese abhängen;
  • Zeilen 28–32: die PSR-4-Regel der Anwendung: Klassen im Namensraum [App] befinden sich im Ordner [src] (Beispiel 01: In den Beispielen meldete die Datei [public/index.php] diese Regel selbst über [addPsr4] beim Class Loader an);
  • Zeilen 34–36: Die Komponente [Runtime] ist ein Plugin (plugin) für [Composer]; es wird während der Installation ausgeführt, um die Datei [vendor/autoload_runtime.php] zu schreiben. [Composer] fragt um Erlaubnis, den Code eines Plugins auszuführen; diese Erlaubnis wird hier erteilt.

[composer install] installiert die Versionen, die diese Bedingungen erfüllen, und hält die exakt installierten Versionen in einer Datei namens [composer.lock] fest. Spätere Installationen (etwa auf einem anderen Rechner) verwenden diese Datei: Sie installieren genau dieselben Versionen. [composer update] dagegen sucht die neuesten Versionen, die [composer.json] erlaubt, und aktualisiert [composer.lock]. Der Befehl [composer show] listet auf, was im Ordner [vendor] installiert ist. In einem typischen Projekt wird diese Datei bei jedem [composer require] von [Symfony Flex] ergänzt (Beispiel 01).

11.6.2. .env

# =========================================================================
# .env: die Einstellungen, die spezifisch für DIESE Installation sind, zu Beginn jeder
# Anfrage von der Komponente Dotenv gelesen (siehe public/index.php). Sie werden zu
# Umgebungsvariablen, die die Konfiguration (Ordner config) über
# %env(NAME)% liest. Eine echte Umgebungsvariable des Systems hat Vorrang vor dieser Datei.
# =========================================================================

# dev: Entwicklung; prod: Produktion (siehe README.md)
APP_ENV=dev
# der geheime Schlüssel von Symfony (Anti-CSRF-Tokens, Signaturen...). In der Produktion:
# ein anderer Wert, lang und zufällig
APP_SECRET=34b2364cc4c93df6e4ee35251a048088

# Die MySQL-Datenbank [dbrdvmedecins2] (Skript: database/dbrdvmedecins2.sql):
# das DBMS, der Benutzer und sein Passwort (die von Laragon: root, ohne
# Passwort), der Server, sein Port, die Datenbank, dann die Serverversion (für MariaDB:
# zum Beispiel serverVersion=10.11.2-MariaDB) und der Zeichensatz
DATABASE_URL="mysql://root:@127.0.0.1:3306/dbrdvmedecins2?serverVersion=8.0.32&charset=utf8mb4"

# Authentifizierung (siehe src/Security/AuthService.php)
# geheimer Schlüssel der JWT-Tokens: mindestens 32 Zeichen (HMAC-SHA256)
JWT_SECRET=ef1cfc9709f10b5b5d183b4deb6d5dbbe69518629c3b12a8
# Gültigkeitsdauer eines Tokens in Minuten (120 min = 2 h)
JWT_DURATION_MINUTES=120
# 1 in der Produktion (über HTTPS ausgelieferte Website): Cookies werden nie unverschlüsselt übertragen
COOKIE_SECURE=0

# Schutz vor Robotern (siehe src/Security/AttemptLimiter.php)
# erlaubte Login-Fehlversuche für dasselbe Login von derselben IP-Adresse, danach
# Sperre für diese Dauer (in Minuten); eine IP-Adresse wird auch gesperrt, wenn sie
# LOGIN_MAX_FAILURES_IP Fehlversuche ansammelt, alle Logins zusammen (ein Roboter, der
# Tausende verschiedener Logins ausprobiert)
LOGIN_MAX_FAILURES=5
LOGIN_MAX_FAILURES_IP=25
LOGIN_BLOCK_MINUTES=15
# höchstens erstellte Kundenkonten pro Stunde und pro IP-Adresse. In einem Klassenraum gehen alle
# Computer oft über dieselbe Adresse nach draußen: bei Bedarf erhöhen
REGISTRATION_MAX_PER_HOUR=10

Die Datei mit den Einstellungen, die für diese Installation spezifisch sind (Beispiel 25): Sie variieren von Rechner zu Rechner (die Datenbank, ihre Zugangsdaten) oder sind vertraulich (die Schlüssel). In einem echten Projekt gehören Produktionsgeheimnisse nicht hierher: Sie werden über echte Umgebungsvariablen, über eine nie veröffentlichte Datei [.env.local] oder über den Secrets-Tresor von [Symfony] bereitgestellt (Beispiel 25).

  • Zeile 9: der Anwendungsmodus: [dev] (Entwicklung: Debug-Modus, Debug-Seite, Cache wird bei jeder Änderung neu aufgebaut) oder [prod];
  • Zeile 12: der geheime Schlüssel für [Symfony], der unter anderem für Anti-CSRF-Token verwendet wird (Beispiel 21);
  • Zeile 18: die Datenbankverbindung (Beispiel 28);
  • Zeilen 20–38: anwendungsspezifische Einstellungen: die JWT-Token (Beispiel 25) und der Bot-Schutz (Beispiel 27).

11.6.3. config/bundles.php und config/packages/framework.yaml

1
2
3
4
5
6
7
8
9
<?php
// config/bundles.php: die Bundles der Anwendung (siehe Beispiel 01): der Kern von
// Symfony, die Twig-Views, die Sicherheit und Doctrine (Datenbankzugriff)
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],
];

Die vier Bundles der Anwendung: der Kern von [Symfony], [Twig] (Beispiel 13), Sicherheit (Beispiel 25) und [Doctrine] (Beispiel 28).

# =========================================================================
# config/packages/framework.yaml: die Konfiguration des FrameworkBundle
# =========================================================================
framework:
    secret: '%env(APP_SECRET)%'

    # Die Sprachen (siehe Beispiel 22): standardmäßig Englisch, dazu Französisch; der
    # Übersetzungs-Service und seine Wörterbücher (Ordner translations)
    default_locale: en
    enabled_locales: ['en', 'fr']
    translator:
        default_path: '%kernel.project_dir%/translations'
        fallbacks: ['en']

    # Formularvalidierung: Ihre Meldungen sind SCHLÜSSEL unserer
    # Wörterbücher (ERRORS.FIRSTNAME_REQUIRED...), übersetzt in der Domain
    # [messages], derselben wie die der Views (standardmäßig: die Domain [validators])
    validation:
        translation_domain: messages

    # Die SESSION (Flash-Meldungen, Anti-CSRF-Tokens): Dateien im Ordner
    # var/sessions. Das Session-Cookie ist nie vom JavaScript der
    # Seite lesbar (httponly), wird nie mit einer POST-Anfrage von einer anderen Website gesendet
    # (samesite lax) und in der Produktion nicht unverschlüsselt gesendet (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

    # Die Locks (siehe Beispiel 20), für die Versuchs-Limiter
    lock: 'flock://%kernel.project_dir%/var/lock'

    # Die Versuchs-LIMITER (siehe Beispiel 27 und src/Security/AttemptLimiter.php).
    # fixed_window: höchstens [limit] Versuche pro Zeitraum [interval], gezählt
    # ab dem ersten Versuch
    rate_limiter:
        # die Login-Fehlversuche eines Logins von einer IP-Adresse
        login:
            policy: fixed_window
            limit: '%env(int:LOGIN_MAX_FAILURES)%'
            interval: '%env(LOGIN_BLOCK_MINUTES)% minutes'
        # die Login-Fehlversuche einer IP-Adresse, alle Logins zusammen
        login_ip:
            policy: fixed_window
            limit: '%env(int:LOGIN_MAX_FAILURES_IP)%'
            interval: '%env(LOGIN_BLOCK_MINUTES)% minutes'
        # die von einer IP-Adresse erstellten Konten pro Stunde
        registration:
            policy: fixed_window
            limit: '%env(int:REGISTRATION_MAX_PER_HOUR)%'
            interval: '1 hour'
  • Zeilen 9–13: Sprachen und der Übersetzer (Beispiel 22);
  • Zeilen 18–19: Die Validierungskomponente übersetzt ihre Meldungen in der Domäne [validators] (Beispiel 09); unsere Constraints verwenden Schlüssel aus unseren Wörterbüchern ([ERRORS.FIRSTNAME_REQUIRED]...) als Meldungsschlüssel, die in der Domäne [messages] liegen: Das teilen wir der Validierungskomponente mit. So genügt ein einziges Wörterbuch pro Sprache für die gesamte Anwendung;
  • Zeilen 25–32: die Session (Beispiel 20): Dateien im Ordner [var/sessions]. Die Anwendung speichert dort sehr wenig: Flash-Nachrichten und Anti-CSRF-Token. Das Session-Cookie heißt [rdvmedecins_session]; es ist niemals für das [JavaScript] der Seite lesbar, wird auch nicht bei einer POST-Anfrage von einer anderen Website mitgesendet und in der Produktion nicht im Klartext übertragen (das Präfix [bool:] wandelt die Variable in einen booleschen Wert um, Beispiel 25);
  • Zeile 35: die Sperren (Beispiel 20), die von den Versuchsbegrenzern und vom CAPTCHA-Service verwendet werden;
  • Zeilen 40–55: die drei Anti-Bot-Limiter (Beispiel 27), deren Einstellungen aus der Datei [.env] stammen. Ein Wert kann Text und eine Variable kombinieren: ['%env(LOGIN_BLOCK_MINUTES)% minutes'].

Der Cache der Anwendung (der Service [cache.app], Beispiel 20) muss nicht konfiguriert werden: Er wird in Dateien im Ordner [var/cache/dev/pools] (oder [prod]) abgelegt. Die Anwendung speichert dort die Listen der Ärzte und Clients, CAPTCHAs, Versuchszähler und Pässe – alles Daten, die von allen Anfragen gemeinsam genutzt werden müssen. Bei mehreren Servern würde man einen gemeinsamen Cache wählen, etwa [Redis] ([framework.cache.app: cache.adapter.redis]).

11.6.4. config/packages/security.yaml

# =========================================================================
# config/packages/security.yaml: Sicherheit (siehe Beispiele 25 und 26)
# =========================================================================
security:
    # das Hashing der Passwörter der Konten: bcrypt, 10 Runden, wie die
    # Hashes des SQL-Skripts. PHP prüft auch die Hashes $2b$ (Python) und $2a$
    # (Java) der anderen Versionen der Anwendung, die dieselbe Datenbank teilen
    password_hashers:
        App\Entity\User:
            algorithm: bcrypt
            cost: 10

    # der User-Provider: hier ohne Bedeutung, denn der angemeldete Benutzer wird
    # durch sein Token beschrieben (siehe src/Security/TokenAuthenticator.php); Symfony
    # verlangt trotzdem einen: eine leere Liste
    providers:
        none:
            memory: ~

    firewalls:
        # EINE Firewall für die gesamte Anwendung, STATELESS: Der Benutzer wird nicht
        # in der Session gespeichert, sondern bei jeder Anfrage anhand des
        # JWT-Tokens seines Cookies wiedergefunden
        main:
            stateless: true
            provider: none
            custom_authenticators:
                - App\Security\TokenAuthenticator

    # ---------------------------------------------------------------------
    # DIE ZUGRIFFSREGEL: Die Regeln werden der Reihe nach geprüft, die erste, deren
    # Pattern (Pfad) zum Pfad der URL passt, gilt:
    #   - einige ÖFFENTLICHE URLs (PUBLIC_ACCESS): die Startseite, das Login, die
    #     Wahl der Sprache, die Erstellung eines Kontos;
    #   - URLs, die bestimmten Rollen vorbehalten sind (eine Liste von Rollen: EINE davon genügt);
    #   - alle ANDEREN erfordern einen authentifizierten Benutzer (letzte Regel).
    # Es ist die Regel „alles ist verboten, außer was erlaubt ist“: Eine später hinzugefügte URL,
    # deren Schutz man vergessen hätte, ist standardmäßig geschützt.
    # Ein abgewiesener anonymer Besucher wird auf die Login-Seite geschickt (den Entry
    # Point der Firewall); ein authentifizierter Benutzer ohne die angeforderte Rolle
    # erhält eine 403-Fehlerseite.
    # ---------------------------------------------------------------------
    access_control:
        - { path: ^/$, roles: PUBLIC_ACCESS }
        - { path: ^/(login|logout)$, roles: PUBLIC_ACCESS }
        - { path: ^/language/, roles: PUBLIC_ACCESS }
        - { path: ^/register, roles: PUBLIC_ACCESS }
        # Ein Patient storniert SEINEN Termin über „Mein Bereich“, nicht über den Terminkalender
        - { path: ^/schedule/cancel$, roles: [ROLE_ADMIN, ROLE_DOCTOR] }
        - { path: ^/(doctors|clients), roles: ROLE_ADMIN }
        - { path: ^/my-, roles: ROLE_USER }
        - { path: ^/, roles: IS_AUTHENTICATED }

Sicherheitskonfiguration (Beispiele 25 und 26):

  • Zeilen 8–11: Passwort-Hashing: [bcrypt], 10 Runden, wie bei den Hashes im SQL-Skript. Um ein Passwort zu überprüfen, liest [PHP] den Algorithmus und den Kostenfaktor aus dem Hash selbst: Die Hashes in der Datenbank, die von [Python] ([$2b$]) oder von [Java] ([$2a$]) geschrieben wurden, werden genauso überprüft wie die von [PHP] ([$2y$]);
  • Zeilen 16–18: der User Provider. Der Authenticator der Anwendung braucht keinen: Der angemeldete Benutzer wird anhand seines Tokens identifiziert, ohne die Datenbank zu lesen (Beispiel 25). Die Sicherheitskomponente verlangt jedoch einen: einen Provider [memory] ohne Benutzer;
  • Zeilen 24–28: eine einzige zustandslose Firewall für die gesamte Anwendung, mit unserem Authenticator. Kein Muster ([pattern]): Sie deckt alle URLs ab. Die Dateien im Ordner [public] ([Bootstrap], das Stylesheet, das Skript) laufen nicht über [Symfony]: Der Webserver liefert sie direkt aus;
  • Zeilen 43–52: die Zugriffsregeln der Anwendung. Die [access_control]-Regeln werden der Reihe nach ausgewertet, und die erste, deren Muster zum URL-Pfad passt, wird angewendet. [PUBLIC_ACCESS] gewährt allen Zugriff auf die URL, auch anonymen Besuchern: die Startseite, die Anmeldung, die Sprachauswahl und die Kontoerstellung. Danach folgen die URL-Regeln, die bestimmten Rollen vorbehalten sind: Eine Liste von Rollen (Zeile 49) bedeutet, dass jede einzelne davon genügt. Die letzte Regel, [^/], gilt für alle übrigen URLs und verlangt einen authentifizierten Benutzer. Das ist die Regel „Alles ist verboten, außer was erlaubt ist“: Eine später hinzugefügte URL ist – selbst wenn man vergessen hat, sie zu schützen – automatisch geschützt. Der umgekehrte Fehler – eine öffentliche URL, die versehentlich ungeschützt blieb – fällt sofort auf; der Fehler einer vergessenen geschützten Seite dagegen weit weniger.

Die Rollen werden hier, in einer einzigen Datei, anhand von URL-Mustern überprüft, statt über [#[IsGranted]]-Attribute an den Actions (Beispiel 26): Beides ist möglich und kann kombiniert werden.

11.6.5. config/packages/doctrine.yaml, twig.yaml, config/routes.yaml

# config/packages/doctrine.yaml: Doctrine, Datenbankzugriff (siehe Beispiel 28)
doctrine:
    # die Verbindung: die DATABASE_URL aus der Datei .env. Im Debug-Modus wird jede SQL-
    # Anweisung ins Log geschrieben, das der Entwicklungsserver anzeigt
    dbal:
        url: '%env(resolve:DATABASE_URL)%'
    # die ENTITÄTEN: die Klassen des Ordners src/Entity, beschrieben durch PHP-Attribute
    orm:
        mappings:
            App:
                type: attribute
                dir: '%kernel.project_dir%/src/Entity'
                prefix: 'App\Entity'

Die Konfiguration von [Doctrine] entspricht der in Beispiel 28 gezeigten.

1
2
3
4
5
# config/packages/twig.yaml: die Twig-Views (Ordner templates)
twig:
    default_path: '%kernel.project_dir%/templates'
    # Die Formulare werden mit den Bootstrap-5-Klassen gezeichnet (siehe Beispiel 18)
    form_themes: ['bootstrap_5_layout.html.twig']

Die Formularfelder werden mit den Klassen von [Bootstrap] 5 dargestellt (Beispiel 18).

1
2
3
4
# config/routes.yaml: Die Routen werden durch die #[Route]-Attribute der
# Controller des Ordners src/Controller beschrieben (siehe Beispiel 01)
controllers:
    resource: routing.controllers

Die Routen werden durch die [#[Route]]-Attribute der Controller beschrieben (Beispiel 01). Der Befehl [php bin/console debug:router] listet sie alle auf (siehe unten, die Web-Schicht).

11.7. Die Anwendung starten

11.7.1. public/index.php und bin/console

<?php
// public/index.php: der Einstiegspunkt ALLER HTTP-Anfragen. Der Ordner
// [public] ist die Wurzel der Website: Nur seine Dateien sind vom
// Browser aus erreichbar (Bootstrap, Stylesheet, Skript), nie der Code der Anwendung.
//
// Die Datei vendor/autoload_runtime.php wird von der Runtime-Komponente von Symfony geschrieben
// (die Bibliothek symfony/runtime): Sie lädt die Klassen, liest die Datei
// .env, aktiviert den Debug-Modus und ruft dann die folgende Funktion auf, die den
// Kernel der Anwendung zurückgibt; schließlich lässt sie ihn die aktuelle Anfrage verarbeiten, sendet die
// Antwort und beendet die Anfrage (siehe die Datei index.php der Beispiele)

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

Der Einstiegspunkt der Beispiele (Beispiel 01) lud die Klassen, las die Datei [.env], aktivierte den Debug-Modus, erzeugte den Kernel, ließ ihn die Anfrage verarbeiten, sendete die Antwort und beendete die Anfrage. All das übernimmt hier die Komponente [Runtime] von [Symfony] (Zeile 14): So sieht die Datei [public/index.php] in einer standardmäßigen [Symfony]-Anwendung aus.

  • Zeile 14: Die Datei [vendor/autoload_runtime.php], von [Composer] geschrieben (siehe [composer.json]), lädt den Class Loader und führt dann das Skript aus, das sie eingebunden hat, hier [public/index.php], um dessen Rückgabewert zu erhalten: Eine eingebundene [PHP]-Datei kann wie eine Funktion einen Wert zurückgeben ([return]);
  • Zeilen 16–18: Dieser Wert ist eine anonyme Funktion, die den Kontext der Anwendung erhält (die Umgebungsvariablen, aus [.env] gelesen von der Komponente [Runtime]) und den Kernel zurückgibt. Die Komponente [Runtime] erledigt den Rest: die Schritte [Request], [handle], [send] und [terminate] .

Der Vorteil dieses Ansatzes ist, dass dieselbe Datei [index.php] auch mit anderen Servern als [PHP-FPM] funktioniert. Mit dem Worker-Modus von [FrankenPHP] (siehe den Abschnitt über Scopes) hält beispielsweise eine andere „Runtime“ den Kernel im Speicher und lässt ihn Anfragen nacheinander verarbeiten, ohne dass sich diese Datei ändert. Die Datei [bin/console] hat denselben Aufbau: Ihre Funktion übernimmt die Ausführung von Befehlen, die um den Kernel herum aufgebaut sind.

11.7.2. src/Kernel.php und config/services.yaml

<?php
// src/Kernel.php: der Kernel der Anwendung (siehe Beispiel 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();
        // die Zeitzone: die der Arztpraxis. Sie legt das heutige Datum fest (kein
        // Termin in der Vergangenheit, siehe src/Business/Dates.php)
        date_default_timezone_set('Europe/Paris');
    }
}

Der Kernel der Beispiele (Beispiel 01), mit einer zusätzlichen Methode:

  • Zeilen 13–19: [boot] wird beim Start des Kernels bei jeder Anfrage aufgerufen. Die Methode legt die Zeitzone für [PHP] fest. Standardmäßig arbeitet [PHP] in der in seiner Konfiguration angegebenen Zeitzone ([date.timezone] in der Datei [php.ini]), die häufig die koordinierte Weltzeit (UTC) ist; das aktuelle Datum wird jedoch für eine Geschäftsregel verwendet: keine Termine in der Vergangenheit. In Paris ist im Sommer zwischen Mitternacht und 2:00 Uhr der Tag in UTC noch der Vortag: Die Zeitzone der Praxis hat Vorrang.
# =========================================================================
# config/services.yaml: die SERVICES der Anwendung (siehe Beispiel 06). Alle
# Klassen des Ordners src/ werden im Container deklariert, der sie bei Bedarf erzeugt und
# jeder die Objekte gibt, die sie benötigt (Dependency Injection): ein
# Controller erhält das ApplicationModel, das die Geschäftsschicht erhält, die
# die DAOs erhält, die den Entity Manager von Doctrine erhalten...
# Nur ein Objekt jeder Klasse während einer Anfrage.
# =========================================================================
services:
    _defaults:
        autowire: true
        autoconfigure: true

    App\:
        resource: '../src/'
        # DATEN-Objekte, vom Code (oder von Doctrine) erzeugt, nie vom
        # Container: Sie sind keine Services
        exclude:
            - '../src/Entity/'
            - '../src/Domain/'
            - '../src/Views/'
            - '../src/Kernel.php'
  • Zeilen 10–15: Alle Klassen im Ordner [src] sind Services, die vom Container erzeugt werden; dieser stellt jedem die Objekte bereit, die er in seinem Konstruktor anfordert (Beispiel 06). Die Services sind geteilt: ein einziges [ApplicationModel], ein einziger [BusinessService]... für die gesamte Anfrage (siehe das Kapitel über Scopes);
  • Zeilen 16–22: ausgenommen die Datenklassen: von [Doctrine] oder von der Geschäftsschicht erzeugte Entitäten, berechnete Kalenderobjekte und von Actions erzeugte View-Modelle. Diese sind ausgeschlossen: Sie sind keine Services. (Andere Datenklassen, etwa [PersonData] oder [Message], werden zwar deklariert, aber da sie niemand beim Container anfordert, verwirft der Container sie von selbst.)

Sonst ist nichts zu deklarieren: Die Listener ([#[AsEventListener]]), die Controller ([#[Route]]), die [Twig]-Erweiterungen, die Formulartypen und der Authenticator werden vom Container anhand ihrer Attribute oder ihrer Elternklasse erkannt ([autoconfigure]) und entsprechend konfiguriert. Der Befehl [php bin/console debug:container App] listet die Services der Anwendung auf.

11.8. Die Entitäten

Die [Doctrine]-Entitäten (Beispiel 28): eine Klasse pro Tabelle, im Ordner [src/Entity].

11.8.1. src/Entity/Role.php

<?php
// src/Entity/Role.php: die drei Rollen eines Benutzers (Spalte users.role):
//   - ADMIN : der Administrator - Termine + Verwaltung der Ärzte und Kunden;
//   - DOCTOR: ein Arzt - bucht und storniert Termine;
//   - USER  : ein Kunde (Patient) - bucht für sich selbst, verwaltet sein Konto.
// Eine „backed“-Enumeration (backed enum): Jeder Fall hat einen Wert, den String, der
// unverändert in der Datenbank gespeichert wird; Role::from('ADMIN') geht den umgekehrten Weg.

namespace App\Entity;

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

    // die Rolle im Sinne von Symfony (siehe config/packages/security.yaml): ROLE_ADMIN...
    public function symfonyRole(): string
    {
        return 'ROLE_'.$this->value;
    }
}

Die drei Rollen, aufgeführt als Aufzählung ([enum], [PHP] 8.1): ein Typ, dessen einzig mögliche Werte seine Cases sind: [Role::ADMIN], [Role::DOCTOR], und [Role::USER]. Eine Variable vom Typ [Role] kann nicht ['ADMINN'] enthalten: Der Tippfehler wird erkannt. [enum Role: string] deklariert eine Backed-Enumeration: Jeder Case hat einen Wert, hier die zugrunde liegende Zeichenkette. [Role::ADMIN->value] ist gleich ['ADMIN']; [Role::from('ADMIN')] liefert den entsprechenden Case (und wirft bei einem unbekannten Wert eine Exception); [Role::tryFrom(...)] liefert in diesem Fall [null] . Eine Enumeration kann Methoden haben: [symfonyRole()] (Zeilen 18–21) liefert die Rolle in der Form, wie sie von [Symfony] definiert wird: [ROLE_ADMIN], [ROLE_DOCTOR] oder [ROLE_USER] (Beispiel 25) – diejenige, die von den Regeln [access_control] überprüft wird. [$this] bezeichnet hier den Case.

11.8.2. src/Entity/User.php

<?php
// =========================================================================
// src/Entity/User.php: ein Benutzer, der sich anmelden darf (Tabelle [users]).
// Jeder Arzt und jeder Kunde hat SEIN Konto (Spalte [user] der Tabellen
// [doctors] und [clients], siehe Person.php).
//
// SQL-Eindeutigkeits-Constraint: unq_users_login (ein Login gehört zu nur einem
// Konto). Sie wird vom Skript database/dbrdvmedecins2.sql erzeugt; die Geschäftsschicht
// erkennt sie an ihrem NAMEN (siehe src/Business/BusinessService.php).
//
// PasswordAuthenticatedUserInterface: ein Benutzer, der ein (gehashtes) Passwort hat;
// das erwartet der Hashing-Service von Symfony (siehe 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;

    // die Versionsnummer der Zeile: das optimistische Sperren (siehe Beispiel 28)
    #[ORM\Version]
    #[ORM\Column(type: Types::INTEGER)]
    private int $version = 0;

    public function __construct(
        #[ORM\Column(length: 30)]
        private string $login,
        // das GEHASHTE Passwort (bcrypt), nie das Passwort selbst
        #[ORM\Column(length: 100)]
        private string $password,
        // der Name, der nach der Anmeldung angezeigt wird: "Marie PELISSIER"
        #[ORM\Column(length: 40)]
        private string $name,
        // enumType: Die Spalte (ein Text) wird zu einer Role und umgekehrt
        #[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;
    }
}
  • Zeilen 21–23: die Entität der Tabelle [users]. Sie implementiert die Schnittstelle [PasswordAuthenticatedUserInterface] der Sicherheitskomponente (Beispiel 25): Das erwartet der Passwort-Hashing-Service;
  • Zeilen 25–33: der Primärschlüssel und die Version, das optimistische Sperren (Beispiel 28);
  • Zeilen 35–48: Die übrigen Spalten werden im Konstruktor mithilfe der Constructor Promotion deklariert (Beispiel 03): Die Attribute [#[ORM\Column]] können sowohl auf einen hochgestuften Parameter als auch auf eine Eigenschaft angewendet werden. [length] legt die Länge der [VARCHAR]-Spalten fest. Zeile 45: Die Option [enumType] wandelt die Spalte [role] (Text) beim Lesen in [Role] um und beim Schreiben umgekehrt: [$user->getRole()] liefert eine [Role], niemals eine Zeichenkette;
  • Zeilen 50–93: die Getter und drei Setter-Methoden. Der Primärschlüssel und die Version haben keine Setter-Methoden: [Doctrine] hält sie aktuell.

11.8.3. src/Entity/Person.php

<?php
// =========================================================================
// src/Entity/Person.php: was die Ärzte (Tabelle [doctors]) und die Kunden
// (Tabelle [clients]) gemeinsam haben: eine Anrede, ein Nachname, ein Vorname - und das
// zugehörige Benutzerkonto (Spalte [user]).
//
// Die beiden Tabellen haben genau dieselben Spalten: Sie werden EINMAL beschrieben,
// in dieser ABSTRAKTEN Klasse (eine „Person“ wird nie erzeugt), von der
// Doctor und Client erben; jede gibt nur den Namen ihrer Tabelle an.
// #[ORM\MappedSuperclass]: eine Elternklasse, deren Spalten die der
// Entitäten sind, die von ihr erben, die aber keine eigene Tabelle hat.
//
// Achtung: [Client] bedeutet hier einen PATIENTEN der Arztpraxis, nicht einen HTTP-Client!
// Es ist das Vokabular der ursprünglichen Fachdomäne, unverändert übernommen.
// =========================================================================

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;

    // optimistisches Sperren (siehe Beispiel 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,
        // -------------------------------------------------------------------
        // Die RELATION zum Benutzerkonto: Eine Person hat EIN Konto,
        // bezeichnet durch den Fremdschlüssel [user]. #[ORM\OneToOne]: ein Konto pro
        // Person, eine Person pro Konto; #[ORM\JoinColumn]: die Spalte des
        // Fremdschlüssels (in Backticks eingefasst: `user` ist ein Wort der SQL-Sprache
        // von MySQL). $doctor->getAccount() gibt ein User-Objekt zurück, beim
        // ersten Zugriff aus der Datenbank gelesen - oder sofort durch die Abfrage, wenn sie es verlangt (siehe 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}";
    }
}

Die Tabellen [doctors] und [clients] haben dieselben Spalten. Ihre gemeinsame Beschreibung steht einmal in einer abstrakten Klasse ([abstract class]): einer Klasse, von der niemals Objekte erzeugt werden und die nur als Basisklasse für die Vererbung dient. Die Klassen [Doctor] und [Client] erben von ihr.

  • Zeile 22: Das Attribut [#[ORM\MappedSuperclass]] macht die Klasse zu einer Superklasse: Ihre Spalten sind die jeder der Entitäten, die von ihr erben, aber sie hat keine eigene Tabelle. ([Doctrine] unterstützt auch echte Entitätshierarchien, die in einer einzigen Tabelle oder in einer Tabelle pro Klasse organisiert sind: Das ist hier nicht der Fall, da die beiden Tabellen unabhängig sind.) Die Eigenschaften sind [protected]: für Kindklassen sichtbar;
  • Zeilen 51–53: Die Beziehung zum Konto. [#[ORM\OneToOne]]: Eine Person hat ein Konto, und ein Konto gehört höchstens zu einer Person. [#[ORM\JoinColumn]] verweist auf die Fremdschlüsselspalte [user] und stellt sicher, dass sie nicht leer ist ([nullable: false]). Der Spaltenname steht in Backticks (Gravis): [user] ist ein Wort der Sprache SQL von [MySQL], und [Doctrine] setzt es in den von ihm geschriebenen SQL-Befehlen auf diese Weise in Backticks (siehe die Konsolenausgabe oben). Die Eigenschaft [account] ist ein [User]-Objekt, keine Zahl: Das ist der Zweck eines ORM. Wenn [Doctrine] eine Person liest, liest es auch ihr Konto, falls die Abfrage dies verlangt (Lazy Loading; siehe die DAO-Schicht); andernfalls legt es ein Lazy-[User]-Objekt (lazy) in der Eigenschaft ab, das erst beim ersten Zugriff auf eine seiner Eigenschaften aus der Datenbank gelesen wird – mit Ausnahme seiner ID, die es bereits kennt;
  • Zeilen 87–92: Änderung der drei Identitätsspalten;
  • Zeilen 95–98: der Name einer Person, „Frau Alice DURAND“, der von allen Seiten verwendet wird. In einer in Anführungszeichen stehenden Zeichenkette fügt [{$this->title}] den Wert einer Eigenschaft ein.

11.8.4. src/Entity/Doctor.php und Client.php

<?php
// src/Entity/Doctor.php: ein Arzt (Tabelle [doctors]).
// SQL-Eindeutigkeits-Constraint: unq_doctors_first_name_last_name (zwei Ärzte können nicht
// denselben Vor- und Nachnamen haben).

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ORM\Table(name: 'doctors')]
class Doctor extends Person
{
}
<?php
// src/Entity/Client.php: ein Kunde, also ein PATIENT (Tabelle [clients]).
// SQL-Eindeutigkeits-Constraint: 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
{
}

Zwei Entitäten, die nur ihre Tabelle festlegen: Alles andere wird geerbt. Ein [Client] ist ein Patient der Praxis, kein HTTP-Client: Es ist das ursprüngliche Vokabular der Fachdomäne, das in allen Versionen der Anwendung beibehalten wird.

11.8.5. src/Entity/Slot.php

<?php
// src/Entity/Slot.php: ein Zeitfenster eines Arztes (Tabelle [slots]):
// 8:00 - 8:20 usw. Die Zeitfenster werden vom SQL-Skript erzeugt: Die Anwendung
// liest sie nur.

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;

    // mehrere Zeitfenster für denselben Arzt: #[ORM\ManyToOne], über den Fremdschlüssel
    // [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" statt "8:5"
    public function time(): string
    {
        return sprintf('%d:%02d - %d:%02d', $this->startHour, $this->startMinute, $this->endHour, $this->endMinute);
    }
}
  • Zeilen 26–28: die Beziehung zum Arzt für das Zeitfenster. [#[ORM\ManyToOne]]: mehrere Zeitfenster für denselben Arzt über den Fremdschlüssel [doctor_id];
  • Zeilen 30–40: die Start- und Endstunden und -minuten. Die Zeitfenster werden vom SQL-Skript erzeugt: Die Klasse hat keinen Konstruktor, und [Doctrine] füllt ihre Eigenschaften selbst;
  • Zeilen 53–56: der Zeitraum, „8:00 – 8:20“. Das Format [%02d] von [sprintf] schreibt eine zweistellige, mit Nullen aufgefüllte Ganzzahl: [8:05] statt [8:5].

11.8.6. src/Entity/Appointment.php

<?php
// src/Entity/Appointment.php: ein Termin (Tabelle [appointments]): ein Kunde, in einem Zeitfenster,
// an einem bestimmten Tag.
// SQL-Eindeutigkeits-Constraint: unq1_appointments (day, slot_id) - ein Zeitfenster wird
// pro Tag nur einmal gebucht. Vom SQL-Skript erzeugt, in der Geschäftsschicht an
// seinem Namen erkannt.

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(
        // der Typ date_immutable: Die Spalte [day] (SQL-Typ DATE) wird zu einem Datum
        // DateTimeImmutable, um Mitternacht; es wird im Format yyyy-mm-dd in die Datenbank geschrieben
        #[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;
    }
}
  • Zeilen 30–31: Die Spalte [day] (SQL-Typ [DATE]) wird in [DateTimeImmutable] um Mitternacht umgewandelt (Typ [Doctrine] [date_immutable]). Unveränderlich: Seine Methoden verändern das Objekt nie; sie geben ein neues zurück ([$day->modify('+1 day')] liefert den nächsten Tag, [$day] bleibt unverändert). Die gesamte Anwendung arbeitet mit unveränderlichen Datumsobjekten: Ein von mehreren Objekten gemeinsam genutztes Datum kann nicht von einem von ihnen verändert werden, ohne dass die anderen es merken;
  • Zeilen 32–37: zwei Beziehungen, eine zum Zeitfenster und eine zum Client des Termins.

11.9. Die Domäne: der Kalender

11.9.1. src/Domain/DoctorDaySlot.php und DoctorDaySchedule.php

<?php
// src/Domain/DoctorDaySlot.php: ein Zeitfenster und der Termin, der möglicherweise
// in diesem Zeitfenster an einem bestimmten Tag gebucht ist (null, wenn das Zeitfenster frei ist).
// Ein berechnetes „Geschäftsobjekt“, das zu keiner Tabelle gehört.
//
// readonly: Die Eigenschaften werden vom Konstruktor ein für alle Mal gesetzt -
// genau das, was für ein berechnetes Objekt nötig ist, das danach niemand ändert.

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: der vollständige Terminkalender eines Arztes für einen bestimmten
// Tag, die Liste seiner Zeitfenster, jedes frei oder belegt. Berechnet von
// BusinessService::getDoctorDaySchedule, von
// ScheduleController in eine HTML-Tabelle umgewandelt.

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

Zwei berechnete Objekte, die keiner Tabelle entsprechen: ein Zeitfenster und sein möglicher Termin an einem bestimmten Tag; der Kalender eines Arztes für einen einzelnen Tag, der seine verfügbaren Zeitfenster auflistet. Es sind [readonly]-Klassen (Beispiel 03), deren Eigenschaften im Konstruktor deklariert werden. Der Kommentar [/** @param list<DoctorDaySlot> ... */] gibt den Inhalt des Arrays an: [PHP] kann den Typ des Inhalts eines Arrays nicht bestimmen, aber Editoren ([PHP Intelephense]) und Analysewerkzeuge lesen diese Kommentare, bekannt als [PHPDoc].

11.10. Die DAO-Schicht

Die DAO-Schicht (Beispiel 28) bündelt die Abfragen: eine Klasse pro Tabelle, ohne Geschäftslogik. Ihre Methoden starten keine Transaktion; die Geschäftsschicht ruft sie innerhalb ihrer eigenen Transaktionen auf. Sie sind in DQL (Beispiel 28) geschrieben oder mit dem Query Builder von [Doctrine], der durch Methodenaufrufe eine DQL-Abfrage erzeugt; die Werte sind Abfrageparameter: SQL-Injection ist nicht möglich.

11.10.1. src/Dao/PersonDao.php

<?php
// =========================================================================
// src/Dao/PersonDao.php: die DAO-Schicht, die Ärzten und Kunden gemeinsam ist.
//
// Die DAOs der Ärzte und der Kunden wären identisch: Diese ABSTRAKTE Klasse
// schreibt sie nur einmal. $this->entityClass ist die Klasse der betroffenen Entität
// (Doctor::class oder Client::class): Die DQL-Abfragen beziehen sich auf DEREN Tabelle.
//
// Die Abfragen sind in DQL geschrieben, der Abfragesprache von Doctrine (siehe
// Beispiel 28), die Doctrine in SQL übersetzt. Die Werte (Vorname, Nachname...) sind
// PARAMETER der Abfrage (:firstName): keine String-Verkettung, daher keine
// SQL-Injection. Diese Methoden öffnen keine Transaktion: Die Geschäftsschicht ruft sie
// auf, innerhalb ihrer eigenen.
// =========================================================================

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

    // -----------------------------------------------------------------------
    // eine Abfrage auf der Tabelle der Klasse, Benutzerkonto eingeschlossen. Der
    // QUERY BUILDER von Doctrine (createQueryBuilder) baut die DQL-Abfrage
    // durch Methodenaufrufe:
    //   SELECT p, a FROM App\Entity\Doctor p JOIN p.account a
    // JOIN p.account a: der SQL-Join mit der Tabelle [users]; SELECT p, a: Die
    // Konten werden von DERSELBEN Abfrage geladen. Ohne das würde jeder Zugriff auf
    // $person->getAccount() eine eigene Abfrage auslösen
    // -----------------------------------------------------------------------
    protected function query(): QueryBuilder
    {
        return $this->em->createQueryBuilder()
            ->select('p', 'a')
            ->from($this->entityClass, 'p')
            ->join('p.account', 'a');
    }

    // nach Nachname, dann Vorname sortierte Liste
    /** @return list<Person> */
    public function list(): array
    {
        return $this->query()->orderBy('p.lastName')->addOrderBy('p.firstName')->getQuery()->getResult();
    }

    // eine Person und ihr Konto; null, wenn sie nicht existiert
    public function read(int $id): ?Person
    {
        return $this->query()->where('p.id = :id')->setParameter('id', $id)
            ->getQuery()->getOneOrNullResult();
    }

    // die Person, deren Benutzerkonto [$userId] ist
    public function readByUser(int $userId): ?Person
    {
        return $this->query()->where('a.id = :userId')->setParameter('userId', $userId)
            ->getQuery()->getOneOrNullResult();
    }

    // die Person, die diesen Vor- und Nachnamen hat, falls es eine gibt. Der Vergleich wird
    // von MySQL durchgeführt, also mit der Collation der Datenbank (utf8mb4_unicode_ci: ohne
    // Beachtung von Groß-/Kleinschreibung und Akzenten) - genau dieselbe Regel wie die
    // der SQL-Eindeutigkeits-Constraint
    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();
    }

    // Die Person wird vom nächsten flush eingefügt (dem der Transaktion der
    // Geschäftsschicht); die Datenbank erzeugt ihre id, die Doctrine im Objekt speichert
    public function add(Person $person): void
    {
        $this->em->persist($person);
    }

    // Die Person wird vom nächsten flush gelöscht
    public function remove(Person $person): void
    {
        $this->em->remove($person);
    }
}

Die DAO-Schicht, die Ärzten und Clients gemeinsam ist, einmal in einer abstrakten Klasse implementiert.

  • Zeile 25: Der Konstruktor erhält den Entity Manager (Beispiel 28) und die jeweilige Klasse, [Doctor::class] oder [Client::class] (eine Zeichenkette, die den vollständigen Klassennamen darstellt). Der Kommentar [@param class-string<Person>] stellt dies für Entwickler klar. Der Service-Container weiß nicht, welche Zeichenkette er liefern soll: Es sind die Kindklassen, die diesen Konstruktor aufrufen;
  • Zeilen 38–44: eine Abfrage, die auch die Konten der gelesenen Benutzer lädt. [createQueryBuilder] erzeugt einen Query Builder; [select('p', 'a')], [from($this->entityClass, 'p')], und [join('p.account', 'a')] schreiben die DQL-Abfrage [SELECT p, a FROM App\Entity\Doctor p JOIN p.account a]. Der Join ([JOIN]) folgt der Beziehung [account] der Entität: [Doctrine] leitet die SQL-Bedingung ab ([ON d0_.user = u1_.id]). Das [SELECT] für beide Aliasse erfordert Eager Loading der Konten: Eine einzige Abfrage ruft die Personen und ihre Konten ab. Ohne sie würde die vom Administrator angezeigte Liste der Ärzte beim ersten Zugriff auf [$doctor->getAccount()->getLogin()] eine Abfrage pro Arzt auslösen: Das ist das sogenannte „N+1-Abfragen“-Problem. Ein weiterer Grund: Die Listen der Ärzte und Clients werden im Cache gespeichert ([ApplicationModel], wird später behandelt); die in den Cache gelegten Objekte müssen vollständig sein;
  • Zeilen 48–51: die Liste, sortiert nach Nachname, dann Vorname ([orderBy], dann [addOrderBy]: ein zweites Kriterium; ein zweites [orderBy] würde das erste ersetzen). [getQuery()] liefert die DQL-Abfrage; [getResult()] führt sie aus und liefert das Array der Entitäten;
  • Zeilen 54–58: [where] fügt eine Bedingung mit einem benannten Parameter hinzu ([:id]), dessen Wert von [setParameter] geliefert wird. [getOneOrNullResult] liefert die einzige gefundene Entität oder [null];
  • Zeilen 61–65: die Person, deren Konto [$userId] ist, Bedingung auf Basis der ID des verknüpften Kontos;
  • Zeilen 71–76: die Person mit demselben Vor- und Nachnamen. [andWhere] fügt eine zweite Bedingung hinzu (ein zweites [where] würde die erste ersetzen). Der Vergleich wird von [MySQL] mit der Kollation der Datenbank durchgeführt: ohne Beachtung der Groß- und Kleinschreibung und ohne Akzente, genau wie die Eindeutigkeits-Constraint (Beispiel 28);
  • Zeilen 80–89: das Einfügen und das Löschen, die im Rahmen der Transaktion der Geschäftsschicht von [flush] an die Datenbank gesendet werden (Beispiel 28).

Es gibt keine Update-Methode: Die Geschäftsschicht verändert die gelesene Entität, und [Doctrine] sendet [UPDATE] bei [flush] (Change Tracking, Beispiel 28) unter Verwendung des optimistischen Sperrens.

11.10.2. src/Dao/DoctorDao.php und ClientDao.php

<?php
// src/Dao/DoctorDao.php: das DAO der Ärzte - alles wird von PersonDao geerbt.

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

Alles wird geerbt: Der Konstruktor erhält den Entity Manager des Containers und reicht ihn zusammen mit der Entitätsklasse an [PersonDao] weiter ([parent::__construct] ruft den Konstruktor der Elternklasse auf).

<?php
// src/Dao/ClientDao.php: das DAO der Kunden - das der Personen, plus eine
// Sperrmethode.

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

    // -----------------------------------------------------------------------
    // setzt einen LOCK auf die Zeile eines Kunden bis zum Ende der aktuellen Transaktion
    // (SELECT ... FOR UPDATE) und gibt dessen id zurück (null, wenn der Kunde nicht
    // existiert). Eine zweite Transaktion, die denselben Lock anfordert, WARTET, bis die
    // erste beendet ist. LockMode::PESSIMISTIC_WRITE: der „pessimistische“
    // Lock von Doctrine, der eine offene Transaktion erfordert.
    // Verwendet für die Buchung (siehe BusinessService::addAppointment): zwei
    // gleichzeitige Buchungen für denselben Patienten werden so eine
    // NACH der anderen verarbeitet, und die zweite sieht den von der ersten erstellten Termin.
    // -----------------------------------------------------------------------
    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;
    }
}
  • Zeilen 28–35: eine pessimistische Sperre, die andere Art von Sperre. [setLockMode(LockMode::PESSIMISTIC_WRITE)] fügt [FOR UPDATE] an die Abfrage an: [SELECT c0_.id AS id_0 FROM clients c0_ WHERE c0_.id = ? FOR UPDATE]. Die gelesene Zeile wird gesperrt , bis die aktuelle Transaktion endet: Eine andere Transaktion, die dieselbe Sperre anfordert, wartet , bis die erste abgeschlossen ist. [Doctrine] verweigert diese Sperre außerhalb einer Transaktion. Die Abfrage liest nur die ID ([SELECT c.id]): Ihr Ergebnis ist keine Entität, sondern ein assoziatives Array ([['id' => 3]]) oder [null]. Wozu diese Sperre dient, sehen wir in der Geschäftsschicht.

11.10.3. src/Dao/SlotDao.php

<?php
// src/Dao/SlotDao.php: DAO-Schicht der Zeitfenster.

namespace App\Dao;

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

class SlotDao
{
    public function __construct(private EntityManagerInterface $em)
    {
    }

    // ein Zeitfenster und sein Arzt
    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();
    }

    // die Zeitfenster eines Arztes in chronologischer Reihenfolge. s.doctor = :doctorId:
    // eine Assoziation, verglichen mit einer id, der des Fremdschlüssels
    /** @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();
    }

    // löscht alle Zeitfenster eines Arztes (Löschen eines Arztes): eine
    // DQL-DELETE-Abfrage, sofort ausgeführt:
    //   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();
    }
}

Ein Terminzeitfenster und sein Arzt (vorab geladen); die Terminzeitfenster eines Arztes in chronologischer Reihenfolge: [s.doctor = :doctorId] vergleicht eine Beziehung mit einer ID – der des Fremdschlüssels; und ein als DQL geschriebenes [DELETE] , das sofort ausgeführt wird ([execute()]), ohne die Zeilen zuvor zu lesen.

11.10.4. src/Dao/AppointmentDao.php

<?php
// =========================================================================
// src/Dao/AppointmentDao.php: DAO-Schicht der Termine.
//
// Die Tabelle [appointments] verweist nicht direkt auf den Arzt: Wir gehen über das Zeitfenster
// (JOIN a.slot s ... WHERE s.doctor = ...).
// Die Daten werden mit ihrem Typ übergeben (Types::DATE_IMMUTABLE): Doctrine
// schreibt sie im Format der Datenbank, 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)
    {
    }

    // ein Termin, sein Kunde und sein Zeitfenster
    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();
    }

    // die Termine eines Arztes an einem bestimmten Tag, mit ihrem Kunden
    /** @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();
    }

    // -----------------------------------------------------------------------
    // die Termine eines Kunden ab dem Tag [$since] (eingeschlossen), in chronologischer
    // Reihenfolge, mit dem Zeitfenster UND dem Arzt dieses Zeitfensters (zwei Joins:
    // JOIN a.slot s JOIN s.doctor d und 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();
    }

    // Anzahl der Termine eines Kunden ab dem Tag [$since] (eingeschlossen);
    // getSingleScalarResult: der einzige Wert der einzigen Zeile des Ergebnisses
    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();
    }

    // Anzahl der Termine (vergangene oder künftige) eines Arztes
    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();
    }

    // der Termin wird beim nächsten Flush eingefügt
    public function add(Appointment $appointment): void
    {
        $this->em->persist($appointment);
    }

    public function remove(Appointment $appointment): void
    {
        $this->em->remove($appointment);
    }

    // löscht sofort ALLE Termine (vergangene und künftige) eines Clients
    public function deleteByClient(int $clientId): void
    {
        $this->em->createQuery('DELETE FROM App\Entity\Appointment a WHERE a.client = :clientId')
            ->setParameter('clientId', $clientId)->execute();
    }
}

Die Tabelle [appointments] verweist nicht direkt auf den Arzt: Sie geht über das Zeitfenster.

  • Zeilen 34–42: die Termine eines Arztes an einem bestimmten Tag und ihre Clients. Zwei Joins: einer ([a.client c]), um die Clients zu laden ([SELECT a, c]), der andere ([a.slot s]) für den Filter auf den Arzt. Der dritte Parameter von [setParameter] gibt [Doctrine] den Werttyp an: Ein [DateTimeImmutable] wird dann im Spaltenformat [DATE] geschrieben, [yyyy-mm-dd];
  • Zeilen 50–59: die kommenden Termine eines Patienten, mit ihrem Zeitfenster und dem Arzt, dem dieses Zeitfenster zugeordnet ist: [JOIN s.doctor d] folgt einer Beziehung der Relation. Die Sortierung erfolgt ebenfalls nach dem Zeitfenster, einer Spalte aus einer anderen Tabelle: Das ermöglicht der Join;
  • Zeilen 63–79: Zählungen. [COUNT(a.id)] zählt die Termine; [getSingleScalarResult] liefert den einzigen Wert der einzigen Zeile des Ergebnisses (eine Zeichenkette, die durch [(int)] in eine Ganzzahl umgewandelt wird);
  • Zeilen 93–97: Löschen aller Termine eines Clients mithilfe von DQL.

11.10.5. src/Dao/UserDao.php

<?php
// src/Dao/UserDao.php: DAO-Schicht der Benutzerkonten. Das Anlegen (oder Löschen)
// eines Arztes oder Clients legt auch dessen Konto an (oder löscht es) - siehe src/Business.
// Ein geändertes Konto wird über seine Methoden (setLogin...) geändert: Doctrine sendet
// das UPDATE beim nächsten Flush (Change Tracking, siehe Beispiel 28).

namespace App\Dao;

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

class UserDao
{
    public function __construct(private EntityManagerInterface $em)
    {
    }

    // null, wenn kein Benutzer dieses Login hat; findOneBy: das Repository der Entität
    // sucht die Zeile, deren Spalten diese Werte haben
    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);
    }
}

Konten: Abruf über das Login, mit Entitätsspeicherung (Beispiel 28): [findOneBy(criteria)] liefert die einzige Entität, die den Kriterien entspricht, oder [null]; Hinzufügen und Löschen.

11.11. Die Geschäftsschicht

Die Geschäftsschicht vereint Geschäftsregeln und Transaktionen (Beispiel 28). Sie wird durch eine Schnittstelle beschrieben, die von zwei Klassen implementiert wird: [BusinessService], der Geschäftsschicht selbst, und [ApplicationModel], dem Cache der Web-Schicht (wird später behandelt).

11.11.1. src/Business/Dates.php

<?php
// src/Business/Dates.php: das heutige Datum. Es wird von GESCHÄFTSREGELN verwendet (keine
// Buchung in der Vergangenheit, nur ein BEVORSTEHENDER Termin pro Patient): es
// gehört daher in die Geschäftsschicht. Die Web-Schicht verwendet es mit.

namespace App\Business;

use DateTimeImmutable;

class Dates
{
    // heute um Mitternacht, in der Zeitzone der Anwendung (siehe src/Kernel.php)
    public static function today(): DateTimeImmutable
    {
        return new DateTimeImmutable('today');
    }
}

Das aktuelle Datum um Mitternacht (['today']) in der Zeitzone der Anwendung (siehe [src/Kernel.php]). Es wird für Geschäftsregeln verwendet (keine Buchungen in der Vergangenheit, nur ein kommender Termin): Es gehört daher in die Geschäftsschicht. Eine statische Methode ([static]) wird aufgerufen, ohne ein Objekt zu erzeugen: [Dates::today()].

11.11.2. src/Business/BusinessException.php

<?php
// =========================================================================
// src/Business/BusinessException.php: die Exception, die die Geschäftsschicht auslöst, wenn eine
// GESCHÄFTSREGEL verletzt wird (Login bereits vergeben, Arzt, der noch
// Termine hat, Zeitfenster bereits gebucht...). Sie trägt keinen Text, sondern einen
// Übersetzungs-SCHLÜSSEL (z. B. "ERRORS.LOGIN_TAKEN"): Die Web-Schicht
// übersetzt ihn beim Anzeigen der Seite ins Französische oder Englische (siehe Übersetzungen).
//
// Eine BusinessException ist keine Anomalie: Sie ist eine normale Antwort ("dieses Login
// ist bereits vergeben"), die dem Benutzer angezeigt wird. Jede andere Exception ist eine echte
// Anomalie und landet auf der Fehlerseite 500.
// =========================================================================

namespace App\Business;

use RuntimeException;
use Throwable;

class BusinessException extends RuntimeException
{
    public function __construct(
        // Übersetzungsschlüssel der Nachricht
        public readonly string $key,
        // mögliche Parameter der Nachricht ({minutes}...)
        public readonly array $params = [],
        ?Throwable $previous = null,
    ) {
        parent::__construct($key, 0, $previous);
    }
}

Die Exception, die bei der Verletzung einer Geschäftsregel geworfen wird. Sie trägt keinen Text, sondern einen Übersetzungsschlüssel ([ERRORS.LOGIN_TAKEN]) und dessen Parameter: Die Web-Schicht übersetzt sie in die Sprache der Seite (Beispiel 22). Die Geschäftsschicht weiß nichts über die Sprachen der Oberfläche. [RuntimeException] ist eine Unterklasse von [PHP]. Die Konstruktoreigenschaften [public readonly] werden durch die Constructor Promotion deklariert und initialisiert (Beispiel 03); [parent::__construct($key, 0, $previous)] ruft den Konstruktor von [RuntimeException] auf und übergibt die Meldung, den Code und die vorherige Exception (diejenige, die diese ausgelöst hat – etwa ein Datenbankfehler: Sie erscheint zusammen mit der neuen im Log).

11.11.3. src/Business/PersonData.php

<?php
// src/Business/PersonData.php: die in einem Formular "Arzt" oder "Client" eingegebenen Daten,
// so wie die Web-Schicht sie an die Geschäftsschicht übergibt.

namespace App\Business;

readonly class PersonData
{
    public function __construct(
        public string $title,        // Mr, Mme, Melle
        public string $lastName,
        public string $firstName,
        // Anlegen: optional (null), standardmäßig der Nachname in Kleinbuchstaben
        // Ändern: optional, das Login bleibt unverändert, wenn es fehlt
        public ?string $login = null,
        // Anlegen: optional, standardmäßig das Login
        // Ändern: optional, das Passwort bleibt unverändert, wenn es fehlt
        public ?string $password = null,
        // Ändern: die Version des Datensatzes zum Zeitpunkt der Anzeige des
        // Formulars (optimistisches Sperren)
        public ?int $version = null,
    ) {
    }
}

Daten aus einem „Personen“-Formular, wie sie von der Web-Schicht an die Geschäftsschicht übergeben werden: eine Klasse namens [readonly]. Login, Passwort und Version sind optional ([?string], [?int], Standardwert [null]); die Kommentare erläutern, was ihr Fehlen bedeutet.

11.11.4. src/Business/Business.php

<?php
// =========================================================================
// src/Business/Business.php: der VERTRAG der Geschäftsschicht: Lesezugriffe, Terminkalender,
// Termine, Verwaltung von Ärzten und Clients.
//
// Ein INTERFACE beschreibt die Methoden, die eine Klasse haben muss, ohne zu sagen, wie
// sie geschrieben sind. BusinessService (die Geschäftsschicht) und ApplicationModel (der Cache
// der Web-Schicht) implementieren es beide; PHP prüft beim Laden
// der Klasse, dass keine Methode fehlt.
//
// ?Type: ein Ergebnis, das fehlen darf (null: ein Arzt, der nicht existiert...).
// list<Doctor> (in einem /** */-Kommentar): ein Array von Ärzten, indiziert mit 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
{
    // ———————————————————————————————— Lesezugriffe
    /** @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;

    // der Client (Patient), dessen Benutzerkonto [$userId] ist
    public function getClientByUserId(int $userId): ?Client;

    // die Termine eines Clients, heutige oder künftige, mit Zeitfenster und Arzt
    /** @return list<Appointment> */
    public function getClientUpcomingAppointments(int $clientId): array;

    // ———————————————————————————————— Termine (ADMIN, DOCTOR, USER)
    // löst eine BusinessException aus, wenn:
    //  - der Tag in der Vergangenheit liegt ("ERRORS.PAST_DATE");
    //  - der Patient bereits einen bevorstehenden Termin hat ("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
    //  - das Zeitfenster an diesem Tag bereits belegt ist ("ERRORS.SLOT_ALREADY_BOOKED").
    public function addAppointment(DateTimeImmutable $day, Slot $slot, Client $client): Appointment;

    public function deleteAppointment(Appointment $appointment): void;

    // ———————————————————————————————— Ärzte (ADMIN)
    // legt den Arzt UND dessen Benutzerkonto an (Rolle DOCTOR)
    public function addDoctor(PersonData $data): Doctor;

    // ändert den Arzt UND dessen Benutzerkonto
    public function editDoctor(int $id, PersonData $data): Doctor;

    // löscht den Arzt, seine Zeitfenster UND sein Konto - abgelehnt, wenn er Termine hat
    public function deleteDoctor(int $id): void;

    // ———————————————————————————————— Clients
    // (der ADMIN; addClient wird auch für die Registrierung eines Patienten verwendet,
    // editClient und deleteClient vom Patienten für sein eigenes Konto)
    // legt den Client UND dessen Benutzerkonto an (Rolle USER)
    public function addClient(PersonData $data): Client;

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

    // löscht den Client, sein Konto UND alle seine Termine (vergangene und künftige)
    public function deleteClient(int $id): void;
}

Der Vertrag der Geschäftsschicht: eine Schnittstelle (Beispiel 06), die Liste der Methoden ohne ihren Code. Lesende Operationen liefern Entitäten oder Arrays von Entitäten (der Kommentar [@return list<Client>] gibt deren Inhalt an); [?Client]: ein Client oder [null] , wenn er nicht existiert. Die Kommentare legen die Regeln jeder schreibenden Operation fest sowie die Schlüssel der [BusinessException] , die sie auslösen kann.

11.11.5. src/Business/Descriptor.php

<?php
// src/Business/Descriptor.php: alles, was einen Arzt von einem Client für die
// Geschäftsregeln unterscheidet (siehe BusinessService). Ärzte und Clients folgen denselben
// Regeln: Der gemeinsame Code wird EINMAL geschrieben und durch einen Deskriptor parametrisiert.

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 oder USER
        // die Klasse der Entität, um eine Person anzulegen: Doctor::class oder Client::class
        public string $entityClass,
        public string $notFoundKey,     // Nachricht, wenn die Person nicht existiert
        public string $alreadyExistsKey, // Nachricht, wenn derselbe Vor- und Nachname bereits existiert
        // optional (null): falls vorhanden, wird das Löschen ABGELEHNT, solange die
        // Person Termine hat (countAppointments(id) > 0), mit der Nachricht hasAppointmentsKey
        public ?Closure $countAppointments,
        public ?string $hasAppointmentsKey,
        // optional: was VOR der Person gelöscht werden muss (die Zeilen, die sie
        // über einen Fremdschlüssel referenzieren); erhält ihre id
        public ?Closure $beforeDelete,
    ) {
    }
}

Ärzte und Clients folgen denselben Verwaltungsregeln, mit einigen kleinen Unterschieden: dem DAO, der Rolle des Kontos, der Klasse der zu erzeugenden Entität, den Fehlermeldungen und der Löschregel. Dieser Descriptor fasst diese Details zusammen; der gemeinsame Code liest sie aus. Zwei Eigenschaften sind Funktionen ([?Closure]: eine Funktion oder [null]): die Zählung der Termine, die das Löschen verhindert (nur bei Ärzten), und das Löschen der Verweise auf die Person.

11.11.6. src/Business/BusinessService.php

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
<?php
// =========================================================================
// src/Business/BusinessService.php: die Implementierung der Geschäftsschicht.
//
// Die Verwaltung von Ärzten und Clients folgt drei Geschäftsregeln:
//
//   1. Eine Person (Arzt oder Client) und ihr Benutzerkonto gehören IMMER
//      zusammen: Sie werden gemeinsam in derselben
//      TRANSAKTION angelegt, geändert und gelöscht - entweder gelingt alles, oder es wird nichts geschrieben;
//   2. Das Login ist in der gesamten Anwendung eindeutig, und zwei Ärzte (oder zwei
//      Clients) dürfen nicht denselben Vor- und Nachnamen haben;
//   3. Löschen:
//      - Ein ARZT mit Terminen kann nicht gelöscht werden (seine Patienten
//        würden ihren Termin verlieren, ohne benachrichtigt zu werden): Die Termine müssen zuerst
//        storniert werden. Seine Zeitfenster verschwinden mit ihm;
//      - Ein CLIENT hingegen verschwindet mit ALLEN seinen Terminen (vergangene und künftige) -
//        ganz gleich, ob das Löschen vom ADMIN oder vom Patienten selbst ausgeht.
//
// Dazu zwei Regeln für die Buchung, unabhängig von der Rolle der Person, die
// bucht (ADMIN, DOCTOR oder der Patient selbst):
//   4. kein Termin in der Vergangenheit;
//   5. ein Patient hat jeweils nur EINEN bevorstehenden Termin.
//
// Ärzte und Clients folgen genau denselben Regeln: Der gemeinsame Code wird
// EINMAL geschrieben (private Methoden xxxPerson) und durch einen Deskriptor parametrisiert,
// der angibt, mit welcher Art von Person wir es zu tun haben.
//
// Die TRANSAKTIONEN werden von der Methode transaction geöffnet (am Ende der Datei),
// die außerdem die von der Datenbank gemeldeten Fehler in BusinessException übersetzt.
// =========================================================================

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
{
    // -----------------------------------------------------------------------
    // Datenbankfehler -> BusinessException
    //
    // Wenn eine UNIQUE-Constraint einen Schreibzugriff ablehnt, löst Doctrine eine
    // UniqueConstraintViolationException aus, deren Meldung die von MySQL ist. Sie nennt den
    // NAMEN der Constraint:
    //   Duplicate entry 'Marie-PELISSIER' for key 'doctors.unq_doctors_first_name_last_name'
    // (MySQL 8 stellt dem Namen den der Tabelle voran, MariaDB nicht). Deshalb
    // BENENNT das SQL-Skript alle seine Constraints.
    // -----------------------------------------------------------------------
    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;

    // das Hashen der Passwörter (bcrypt, siehe config/packages/security.yaml)
    private PasswordHasherInterface $hasher;

    // alle Abhängigkeiten werden vom Service-Container von Symfony bereitgestellt
    // (Dependency Injection, siehe Beispiel 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(...): die Methode selbst als Closure
            // (sogenannte "First-Class-Callable"-Syntax)
            countAppointments: $appointments->countByDoctor(...),
            hasAppointmentsKey: 'ERRORS.DOCTOR_HAS_APPOINTMENTS',
            // ein Arzt ohne Termine kann dennoch Zeitfenster haben:
            // Sie ergeben ohne ihn keinen Sinn und werden mit ihm gelöscht (sonst würde der
            // Fremdschlüssel slots.doctor_id das Löschen verbieten)
            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',
            // kein countAppointments: Das Löschen eines Clients wird nie abgelehnt;
            // seine Termine (vergangene und künftige) werden mit ihm gelöscht (sonst würde der
            // Fremdschlüssel appointments.client_id das Löschen verbieten)
            countAppointments: null,
            hasAppointmentsKey: null,
            beforeDelete: $appointments->deleteByClient(...));
    }

    // =======================================================================
    // Lesezugriffe
    // =======================================================================

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

    // der Terminkalender eines Arztes an einem bestimmten Tag: seine Zeitfenster und für jedes
    // der an diesem Tag gebuchte Termin (null, wenn es frei ist)
    public function getDoctorDaySchedule(int $doctorId, DateTimeImmutable $day): ?DoctorDaySchedule
    {
        $doctor = $this->getDoctorById($doctorId);
        if ($doctor === null) {
            return null;
        }
        // Nummer des Zeitfensters -> an diesem Zeitfenster gebuchter Termin
        $bookings = [];
        foreach ($this->getDoctorDayAppointments($doctorId, $day) as $appointment) {
            $bookings[$appointment->getSlot()->getId()] = $appointment;
        }
        // array_map: wendet die Funktion auf jedes Zeitfenster an und gibt das Array der Ergebnisse zurück
        $doctorDaySlots = array_map(
            fn (Slot $slot) => new DoctorDaySlot($slot, $bookings[$slot->getId()] ?? null),
            $this->getAllSlots($doctorId));
        return new DoctorDaySchedule($doctor, $day, $doctorDaySlots);
    }

    // =======================================================================
    // Termine
    // =======================================================================

    // -----------------------------------------------------------------------
    // Buchung in einer Transaktion:
    //   1. kein Termin in der Vergangenheit;
    //   2. wir SPERREN die Zeile des Patienten (SELECT ... FOR UPDATE): Wenn derselbe
    //      Patient zwei Zeitfenster gleichzeitig bucht (zwei Tabs, Doppelklick...),
    //      wartet die zweite Transaktion das Ende der ersten ab - und sieht dann den
    //      Termin, den diese soeben angelegt hat;
    //   3. nur ein bevorstehender Termin pro Patient;
    //   4. schließlich das Einfügen. Wenn das Zeitfenster gerade von einem ANDEREN Patienten belegt wurde,
    //      lehnt die SQL-Constraint unq1_appointments (day, slot_id) das Einfügen ab -
    //      von transaction() in BusinessException übersetzt.
    // -----------------------------------------------------------------------
    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));
    }

    // =======================================================================
    // Ärzte und Clients - die öffentlichen Methoden delegieren mit dem passenden Deskriptor
    // an die gemeinsamen privaten Methoden
    // =======================================================================

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

    // der Client, sein Konto UND alle seine Termine (ADMIN oder der Patient selbst
    // über "Mein Konto verwalten": dieselbe Methode, dieselbe Regel)
    public function deleteClient(int $id): void
    {
        $this->deletePerson($this->client, $id);
    }

    // -----------------------------------------------------------------------
    // Anlegen: das Benutzerkonto UND die Person (die darauf verweist) in EINER
    // Transaktion. Doctrine fügt zuerst das Konto ein, dann die Person, deren
    // Fremdschlüssel [user] die id erhält, die die Datenbank soeben für das Konto erzeugt hat.
    // -----------------------------------------------------------------------
    private function addPerson(Descriptor $d, PersonData $data): Person
    {
        $lastName = mb_strtoupper(trim($data->lastName));
        $firstName = trim($data->firstName);
        // die Regeln der Datenbank dbrdvmedecins2: Login = Nachname in Kleinbuchstaben,
        // Passwort = Login - es sei denn, der ADMIN (oder der Patient) hat andere eingegeben
        $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: der bcrypt-Hash des Passworts
            $user = new User($login, $this->hasher->hash($password), "$firstName $lastName", $d->role);
            $this->users->add($user);
            // new ($d->entityClass)(...): eine Instanz der Klasse, deren Name in der
            // Eigenschaft [entityClass] des Deskriptors steht (Doctor oder Client)
            $person = new ($d->entityClass)($data->title, $lastName, $firstName, $user);
            $d->dao->add($person);
            return $person;
        });
    }

    // -----------------------------------------------------------------------
    // Ändern: die Person UND ihr Konto (der angezeigte Name "firstName LASTNAME" muss
    // mitgeführt werden; Login und Passwort ändern sich nur, wenn sie eingegeben wurden).
    // -----------------------------------------------------------------------
    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);

            // optimistisches Sperren: Entspricht die Version in der Datenbank nicht mehr der des
            // Formulars, hat jemand diesen Datensatz in der Zwischenzeit geändert - wir lehnen ab,
            // statt seine Änderungen stillschweigend zu überschreiben
            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);

            // sein Konto: der angezeigte Name und, falls eingegeben, das Login und das
            // Passwort
            $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));
            }
            // sonst ist nichts zu tun: Am Ende der Transaktion sendet Doctrine die
            // UPDATEs der geänderten Zeilen mit ihrem optimistischen Sperren
            //   UPDATE ... SET ..., version = version + 1 WHERE id = ? AND version = ?
            // Wurde der Datensatz NACH dem obigen Lesen geändert, wird keine Zeile
            // geändert, und Doctrine löst eine OptimisticLockException aus
            return $person;
        });
    }

    // -----------------------------------------------------------------------
    // Löschen in EINER Transaktion, in der von den Fremdschlüsseln vorgegebenen
    // Reihenfolge:
    //   1. ggf. Ablehnung, wenn noch Termine existieren (Arzt);
    //   2. was auf die Person verweist (Zeitfenster eines Arztes, Termine eines
    //      Clients), sofort;
    //   3. die Person (sie verweist auf ihr Konto), dann ihr Konto: Doctrine
    //      löscht sie am Ende der Transaktion in dieser Reihenfolge.
    // -----------------------------------------------------------------------
    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());
        });
    }

    // lehnt Vor- und Nachnamen ab, die bereits von einer ANDEREN Person desselben Typs verwendet werden
    // ($currentId: die Person, die gerade geändert wird und natürlich das Recht hat,
    // ihren eigenen Vor- und Nachnamen zu behalten; null beim Anlegen)
    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');
        }
    }

    // -----------------------------------------------------------------------
    // führt [$work] in einer Transaktion aus (wrapInTransaction, siehe Beispiel 28):
    // Endet die Funktion normal, sendet Doctrine die ausstehenden Schreibzugriffe
    // an die Datenbank (Flush) und bestätigt dann die Transaktion (COMMIT); kommt
    // eine Exception heraus (auch BusinessException), erfolgt ROLLBACK: Es wird nichts geschrieben.
    //
    // Die Prüfungen "Login frei" und "eindeutiger Vor- und Nachname" erfolgen VOR dem
    // Schreiben, um eine klare Meldung zu geben. Aber zwei ADMINs könnten
    // im selben Moment dasselbe Login (oder denselben Arzt) speichern: In diesem
    // seltenen Fall lehnt eine SQL-Eindeutigkeitsconstraint den zweiten Schreibzugriff ab.
    // Ebenso werden zwei gleichzeitige Änderungen desselben Datensatzes durch das
    // optimistische Sperren entschieden. Wir fangen diese Fehler daher UM die Transaktion herum ab,
    // um sie in BusinessException zu übersetzen. Jeder andere Fehler ist eine echte
    // Anomalie: Wir lassen ihn nach oben durchgehen.
    // Nach einer Exception SCHLIESST Doctrine den Entity Manager: Die aktuelle Anfrage
    // darf nichts mehr schreiben (die Controller leiten um oder zeigen
    // ein Formular erneut an).
    // -----------------------------------------------------------------------
    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);
        }
    }
}

Die wichtigste Datei der Anwendung. Wir gehen sie thematisch durch.

11.11.6.1. Abhängigkeiten und Descriptors

Zeilen 86–124: Der Konstruktor erhält vom Container den Entity Manager (für Transaktionen), die fünf DAO-Instanzen und die Hasher-Service-Factory ([PasswordHasherFactoryInterface]), die um denjenigen für Konten gebeten wird: [getPasswordHasher(User::class)] liefert den Service, der den für die Klasse [User] in [security.yaml] gewählten Algorithmus anwendet ([bcrypt], 10 Iterationen). Danach folgen die beiden Descriptors. Benannte Argumente ([dao: $doctors], Beispiel 01) machen den Aufruf lesbar. [$appointments->countByDoctor(...)] (mit drei Punkten in Klammern) hat keine besondere Bedeutung: Es ist die Syntax von [PHP] 8.1, die aus einer Methode eine [Closure] erzeugt – eine Funktion, die später aufgerufen wird ([($d->countAppointments)($id)], Zeile 359). Ein Arzt wird zusammen mit seinen Zeitfenstern entfernt ([deleteByDoctor]), aber nicht, wenn er Termine hat; ein Client wird zusammen mit allen seinen Terminen entfernt ([deleteByClient]).

11.11.6.2. Lesende Operationen und der Kalender

Die lesenden Operationen (Zeilen 130–178) delegieren an die DAO-Schicht. Der Terminkalender eines Arztes (Zeilen 182–198) wird berechnet: der Arzt, seine Zeitfenster und die Termine des Tages. Die Termine werden in einem Array abgelegt, das nach der Nummer des Zeitfensters indiziert ist: [$bookings[$slot->getId()] ?? null] liefert den Termin für ein Zeitfenster oder [null] , wenn das Zeitfenster frei ist. [array_map] wandelt jedes Zeitfenster in [DoctorDaySlot] um.

11.11.6.3. Einen Termin vereinbaren

Zeilen 216–232: vier Schritte in einer einzigen Transaktion.

  • Keine Termine in der Vergangenheit: Die [DateTimeImmutable]-Werte unterstützen die üblichen Operatoren ([<], [>=]...);
  • der Datensatz des Patienten wird gesperrt ([lock], [SELECT ... FOR UPDATE]). Warum? Die Regel „nur ein kommender Termin pro Patient“ wird durch eine Zählung überprüft (dritter Schritt), danach erfolgt das Einfügen (vierter Schritt). Bucht derselbe Patient zwei Zeitfenster gleichzeitig (zwei Tabs, ein Doppelklick), könnten beide Transaktionen null Termine zählen und anschließend jeweils ihren eigenen einfügen: Die Regel wäre verletzt. Mit der Sperre wartet die zweite Transaktion, bis die erste abgeschlossen ist, und zählt dann ... einen Termin. [?? throw new BusinessException(...)]: Wenn der Client nicht mehr existiert, liefert [lock] den Wert [null], und der Operator [??] wertet seinen zweiten Operanden aus, der die Exception auslöst (denn seit [PHP] 8 ist [throw] ein Ausdruck);
  • Zählen der kommenden Termine;
  • Einfügen am Ende der Transaktion. Wurde das Zeitfenster gerade von einem anderen Patienten belegt, weist die Datenbank-Constraint [unq1_appointments] das Einfügen zurück: Die Methode [transaction] übersetzt diesen Fehler in eine [BusinessException].

11.11.6.4. Ärzte und Patienten verwalten

Die öffentlichen Methoden (Zeilen 244–274) rufen die gemeinsamen privaten Methoden auf und verwenden dabei den passenden Descriptor.

  • Zeilen 281–302: das Anlegen. Der Nachname wird in Großbuchstaben umgewandelt ([mb_strtoupper]: die Version von [strtoupper] , die Buchstaben mit Akzenten unterstützt), und von Vor- und Nachname werden überflüssige Leerzeichen entfernt ([trim]). Standardmäßig ist das Login der Nachname in Kleinbuchstaben und das Passwort das Login (gemäß den Regeln für Demokonten): [$a ?: $b] entspricht [$a] , wenn es „wahr“ ist (weder [null] noch eine leere Zeichenkette), und [$b] andernfalls. In der Transaktion: die Validierungen (Vor- und Nachname beliebig, Login beliebig), dann das Konto, dessen Passwort gehasht wird ([hash]), dann die Person, die auf das Konto verweist. [new ($d->entityClass)(...)] erzeugt ein Objekt der Klasse, deren Name in der Eigenschaft [entityClass] des Descriptors steht (um einen Ausdruck sind Klammern erforderlich). [Doctrine] fügt das Konto vor der Person ein: Es kennt die Beziehungen zwischen den Entitäten und leitet die Reihenfolge der [INSERT]-Anweisungen daraus ab. [use (...)]: Eine gewöhnliche anonyme Funktion ([function () use ($d, ...)]) kann die Variablen der Methode, die sie enthält, nicht sehen; [use] übergibt sie ihr (eine Arrow Function, [fn () =>], sieht sie von selbst, kann aber nur einen Ausdruck enthalten);
  • Zeilen 308–344: die Aktualisierung, mit zwei optimistischen Sperren. Die erste ist ein Vergleich (Zeilen 316–318): Die Version des Formulars (verstecktes Feld, Beispiel 28) muss mit der des Datensatzes in der Datenbank übereinstimmen; andernfalls hat jemand den Datensatz zwischen der Anzeige des Formulars und seiner Übermittlung geändert. Die zweite ist die von [Doctrine]: Die am Ende der Transaktion gesendeten [UPDATE]-Anweisungen enthalten die Bedingung [WHERE version = ?], die eine Änderung erkennt, die zwischen Lesen und Schreiben erfolgt ist ([OptimisticLockException]). Es folgt das Konto: Sein angezeigter Name („Vorname NACHNAME“) wird stets aktualisiert; Login und Passwort nur, wenn sie eingegeben wurden; seine eigene optimistische Sperre schützt zudem die Zeile in der Tabelle [users]. Es gibt nichts zu „speichern“: Die gelesene Entität wird vom Entity Manager verfolgt, der ihre Änderungen schreibt. Am Ende der Transaktion [Doctrine] speichert es die neuen Versionen der Entitäten: Der Aufrufer erhält die aktualisierte Person;
  • Zeilen 355–368: das Löschen, in der von den Fremdschlüsseln vorgegebenen Reihenfolge: zuerst die Datensätze, die auf die Person verweisen (Zeitfenster oder Termine), unmittelbar gefolgt von einem [DELETE] des DAO; dann die Person, dann ihr Konto, die [Doctrine] am Ende der Transaktion in dieser Reihenfolge löscht. Die umgekehrte Reihenfolge würde von der Datenbank zurückgewiesen: Eine Zeile, auf die noch ein Fremdschlüssel verweist, kann nicht gelöscht werden;
  • Zeilen 373–387: Die Person, die geändert wird, darf ihren eigenen Vor- und Nachnamen behalten; [$currentId] entspricht [null] bei einer Neuanlage.

11.11.6.5. Datenbanktransaktionen und Fehler

Zeilen 406–419: Alle Schreibvorgänge verwenden diese Methode. [wrapInTransaction] führt die Funktion innerhalb einer Transaktion aus (Beispiel 28): [flush], dann [COMMIT] , wenn sie normal endet, und [ROLLBACK] , wenn eine Exception auftritt – einschließlich einer [BusinessException]: Eine Regelverletzung mitten in einer Operation hinterlässt keine Spuren. Die Prüfungen „Login verfügbar“ und „Vor- und Nachname verfügbar“ werden vor dem Schreiben durchgeführt, um eine klare Meldung zu liefern. Zwei Administratoren könnten jedoch gleichzeitig versuchen, dasselbe Login zu registrieren: Beide finden es verfügbar, und das zweite [INSERT] wird von der Constraint [unq_users_login] zurückgewiesen. [Doctrine] löst dann eine [UniqueConstraintViolationException] aus (Beispiel 28), deren Meldung die von [MySQL] ist; sie enthält den Namen der verletzten Constraint:

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

Der reguläre Ausdruck in Zeile 75 extrahiert diesen Namen ([MySQL] 8 stellt ihm den Tabellennamen voran, [users.unq_users_login], [MariaDB] dagegen nicht: Der Teil [(?:[^'.]*\.)?] akzeptiert beide Formen), und die Tabelle in den Zeilen 68–73 liefert den Meldungsschlüssel. Eine andere Constraint-Verletzung ist eine echte Anomalie: Sie wird erneut geworfen ([throw $e]) und führt zu einer 500-Fehlerseite. Schließlich wird der von der optimistischen Sperre von [Doctrine] erkannte Konflikt ([OptimisticLockException]) zu derselben [BusinessException] wie der, der beim Versionsvergleich erkannt wird.

Erinnern wir uns an eine Folge von [wrapInTransaction] (Beispiel 28): Nach einer Exception ist der Entity Manager geschlossen und kann während der aktuellen Anfrage nicht mehr schreiben. Die Controller berücksichtigen das: Nach einer [BusinessException] leiten sie um oder zeigen ein Formular erneut an, ohne etwas anderes zu schreiben.

11.12. Authentifizierung

Der Ordner [src/Security] enthält die Beispiele 25 bis 27 mit Datenbankbenutzern und einigen zusätzlichen Sicherheitsmaßnahmen. Rufen wir uns das Prinzip in Erinnerung (Beispiel 25): Die Firewall [main] aus [config/packages/security.yaml] ist zustandslos ([stateless]); bei jeder Anfrage liest ein Authenticator eigener Bauart das JWT-Token aus dem Cookie [rdvmedecins_jwt] und identifiziert den Benutzer; die Regeln [access_control] bestimmen dann den Zugriff auf die Seiten.

11.12.1. src/Security/ConnectedUser.php

<?php
// =========================================================================
// src/Security/ConnectedUser.php: der angemeldete Benutzer, wie sein JWT-Token ihn
// beschreibt (siehe Beispiel 25). UserInterface: das Interface, das Symfony von
// authentifizierten Benutzern erwartet ($this->getUser() in einem Controller, #[CurrentUser],
// app.user und is_granted() in einer View...).
//
// Die Claims unserer Tokens (siehe AuthService::tokenCookie):
//   sub   : die id des Benutzerkontos (JWT-Konvention: "Subject"), als Text
//   login : das Login
//   name  : der angezeigte Name ("Marie PELISSIER"), für die Navigationsleiste
//   role  : ADMIN, DOCTOR oder USER
//   iat, exp : Erstellungs- und Ablaufdatum des Tokens
//
// Dieses Objekt stammt NICHT aus der Datenbank: Es wird bei jeder Anfrage aus dem
// Token neu aufgebaut, dessen Signatur den Inhalt garantiert.
// =========================================================================

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

    // der Benutzer, der durch die Claims eines bereits geprüften Tokens beschrieben wird; null, wenn ein Claim
    // fehlt oder nicht die erwartete Form hat. Role::tryFrom: null für eine unbekannte Rolle
    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;
    }

    // ———— das Interface UserInterface: die Kennung des Benutzers (sein Login)
    // und seine Rollen im Sinne von Symfony (ROLE_ADMIN, ROLE_DOCTOR oder ROLE_USER, siehe
    // die Enumeration Role), geprüft durch die access_control-Regeln von
    // config/packages/security.yaml
    public function getUserIdentifier(): string
    {
        return $this->login;
    }

    public function getRoles(): array
    {
        return [$this->role->symfonyRole()];
    }
}

Der angemeldete Benutzer, wie ihn sein Token beschreibt: seine Konto-ID, sein Benutzername, sein Name und seine Rolle. Wie [User] in Beispiel 25 implementiert er die Schnittstelle [UserInterface], die [Symfony] von authentifizierten Benutzern erwartet. Dieses Objekt stammt nicht aus der Datenbank: Es wird bei jeder Anfrage anhand des Tokens rekonstruiert, dessen Signatur seinen Inhalt garantiert. Die Anwendung liest das Konto daher nicht bei jeder Anfrage aus der Datenbank. Die Klasse ist [readonly] (Beispiel 08): Ihre öffentlichen Eigenschaften können nach der Konstruktion nicht mehr verändert werden.

  • Zeilen 36–44: Der Benutzer wird durch die Claims (Claims) eines Tokens beschrieben, das bereits verifiziert wurde, oder durch [null] , wenn einer der Claims fehlt oder nicht das erwartete Format hat. Ein ordnungsgemäß signiertes Token sollte nie fehlerhaft sein; der geheime Schlüssel könnte jedoch mit einer anderen Anwendung geteilt werden, die andere Token erzeugen könnte: Vorsicht kostet nichts. [Role::tryFrom] liefert die Rolle oder [null] bei einem unbekannten Wert; [ctype_digit] prüft, ob eine Zeichenkette ausschließlich aus Ziffern besteht;
  • Zeilen 46–54: zwei Fragen, die Views und Controller häufig stellen;
  • Zeilen 60–68: die Schnittstelle [UserInterface]. Die Kennung des Benutzers ist sein Login; seine Rollen im Sinne von [Symfony] beschränken sich auf eine einzige Rolle, [ROLE_ADMIN], [ROLE_DOCTOR] oder [ROLE_USER], die von der Enumeration [Role] berechnet wird. Diese werden von den Regeln [access_control], dem Attribut [#[IsGranted]], und der Funktion [is_granted] der Views überprüft. (Die Methode [eraseCredentials], die nach der Anmeldung das Klartextpasswort löschte, wurde mit [Symfony] 8 aus der Schnittstelle entfernt.)

11.12.2. src/Security/AuthService.php

<?php
// =========================================================================
// src/Security/AuthService.php: die Authentifizierungslogik:
//   - validate()       : prüft ein Paar aus Login und Passwort;
//   - tokenCookie()    : erstellt das JWT-Token eines validierten Benutzers und das
//                        Cookie, das es trägt;
//   - currentUser()    : der durch ein Token beschriebene Benutzer.
//
// Wo wird das JWT-Token transportiert? In einem COOKIE (siehe Beispiel 25): Ein Browser,
// der gewöhnliche HTML-Seiten anzeigt, liefert es so bei jeder
// Anfrage von selbst mit. Die Optionen dieses Cookies sind für die Sicherheit wichtig:
//   - HttpOnly: Das JavaScript der Seite kann das Cookie nicht lesen (ein eingeschleustes
//     Skript könnte das Token also nicht stehlen);
//   - SameSite=Lax: Der Browser sendet das Cookie NICHT bei einem POST von einer anderen
//     Website (erster Schutz gegen den sogenannten CSRF-Angriff; der zweite ist
//     das Anti-CSRF-Token der Formulare);
//   - Secure: In der Produktion (HTTPS) wird das Cookie nie unverschlüsselt übertragen;
//   - Lebensdauer: Das Cookie verschwindet zeitgleich mit dem Ablauf des Tokens.
// =========================================================================

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
{
    // der Name des Cookies, das das Token trägt
    public const COOKIE = 'rdvmedecins_jwt';

    // die Einstellungen der Datei .env: #[Autowire(env: ...)] (siehe Beispiel 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 erfordert einen Schlüssel von mindestens 256 Bit: Wir sagen es deutlich,
        // statt die Bibliothek erst später scheitern zu lassen
        if (strlen($this->secret) < 32) {
            throw new RuntimeException('JWT_SECRET must be at least 32 characters long (see .env).');
        }
    }

    // null, wenn das Login nicht existiert oder das Passwort falsch ist. verify hasht das
    // eingegebene Passwort mit dem im gespeicherten Hash enthaltenen "Salt" und
    // vergleicht dann die beiden Ergebnisse
    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;
    }

    // -----------------------------------------------------------------------
    // das JWT-Token von [$user], im Cookie, das es trägt. Das Token wird mit dem geheimen Schlüssel
    // SIGNIERT (HMAC-SHA256): Der Browser kann es lesen (es ist nicht
    // verschlüsselt), aber nicht ändern - jede Änderung würde die Signatur
    // ungültig machen.
    // -----------------------------------------------------------------------
    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);
    }

    // löscht das Token-Cookie: Die Antwort trägt ein Cookie desselben Namens, leer und bereits abgelaufen
    public static function clearCookie(Response $response): Response
    {
        $response->headers->clearCookie(self::COOKIE);
        return $response;
    }

    // -----------------------------------------------------------------------
    // der durch ein Token beschriebene Benutzer; null, wenn das Token abgelaufen, gefälscht oder
    // fehlerhaft ist. JWT::decode prüft die Signatur UND das Ablaufdatum (Claim exp).
    // -----------------------------------------------------------------------
    public function currentUser(string $token): ?ConnectedUser
    {
        try {
            // decode gibt ein Objekt zurück; (array) wandelt es in ein assoziatives Array um
            $claims = (array) JWT::decode($token, new Key($this->secret, 'HS256'));
        } catch (Throwable) {
            return null;
        }
        return ConnectedUser::of($claims);
    }
}
  • Zeile 37: der Name des Token-Cookies, eine Klassenkonstante, gelesen über [AuthService::COOKIE];
  • Zeilen 40–52: Der Service erhält die DAO-Schicht für Konten; die Hasher-Service-Factory (die zur Klasse [User] gehörende, bcrypt, wird in [security.yaml] deklariert) und drei Einstellungen aus der Datei [.env] über das Attribut [#[Autowire(env: ...)]] (Beispiel 25). Die Präfixe [int:] und [bool:] wandeln den Text der Umgebungsvariablen um. Ist ein Schlüssel zu kurz, wird dies sofort beim Start des Services mit einer klaren Meldung gemeldet (siehe „Häufige Probleme“);
  • Zeilen 57–65: Überprüfung von Benutzername und Passwort (Beispiel 25), wobei das Konto von der DAO-Schicht aus der Datenbank abgerufen wird. Beachten Sie, dass dieser Service die DAO-Schicht direkt verwendet, ohne die Geschäftsschicht zu durchlaufen: Die Passwortprüfung ist keine Geschäftsregel;
  • Zeilen 73–90: das Token des Benutzers und das Cookie, das es trägt. Die Claims sind dieselben wie in Beispiel 25, mit der Konto-ID ([sub], eine Zeichenkette, wie es der Standard verlangt) und dem Benutzernamen. [Cookie::create] erzeugt ein Cookie, das die [with...]-Methoden ergänzen (jede liefert ein neues Cookie: Das Objekt ist unveränderlich): sein Ablaufdatum (das des Tokens), [Secure] (in der Produktion über HTTPS), [HttpOnly], und [SameSite=Lax] (siehe den Kommentar in den Zeilen 9–18);
  • Zeilen 93–97: Löschen des Cookies. [clearCookie(name)] fügt der Antwort ein Cookie mit demselben Namen hinzu – leer und bereits abgelaufen –, sodass der Browser es löscht. Die Methode ist statisch: Sie benötigt keine Konfiguration, und die Klassen, die sie aufrufen, müssen den Service nicht erhalten;
  • Zeilen 103–112: Token-Überprüfung (Beispiel 25).

11.12.3. src/Security/TokenAuthenticator.php

<?php
// =========================================================================
// src/Security/TokenAuthenticator.php: der AUTHENTICATOR der Firewall (siehe
// config/packages/security.yaml und Beispiel 25): Bei jeder Anfrage stellt er anhand des JWT-Tokens
// aus dem Cookie [rdvmedecins_jwt] fest, wer der Benutzer ist.
//
// Er lehnt selbst nichts ab: Ein fehlendes oder ungültiges Token lässt den Besucher
// ANONYM. Erst die access_control-Regeln verweigern dann den Zugriff auf die geschützten
// Seiten; ein abgewiesener anonymer Besucher wird dann an den ENTRY POINT
// (die Methode start) übergeben, der ihn zur Login-Seite zurückschickt.
// =========================================================================

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
{
    // das Request-Attribut, das ein ungültiges Token signalisiert und das gelöscht werden soll
    private const INVALID_TOKEN = '_invalid_token';

    public function __construct(
        private AuthService $auth,
        private Flash $flash,
        private UrlGeneratorInterface $urls,
    ) {
    }

    // der Authenticator wird nur aktiv, wenn die Anfrage das Token-Cookie enthält
    public function supports(Request $request): ?bool
    {
        return $request->cookies->getString(AuthService::COOKIE) !== '';
    }

    // das von AuthService geprüfte Token beschreibt den Benutzer: Der Passport
    // validiert sich selbst, und das Badge liefert diesen Benutzer direkt (ohne
    // ihn in der Datenbank zu suchen, siehe Beispiel 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;
    }

    // ein ungültiges Token (abgelaufen, gefälscht): Der Besucher bleibt anonym (null), und das
    // Cookie wird aus der Antwort gelöscht, was auch immer sie ist (siehe clearInvalidToken)
    public function onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response
    {
        $request->attributes->set(self::INVALID_TOKEN, true);
        return null;
    }

    // -----------------------------------------------------------------------
    // der ENTRY POINT: Ein anonymer Besucher fordert eine geschützte Seite an. Ab
    // zur Login-Seite. Hatte er ein Token-Cookie, bedeutet das, dass sein Token
    // nicht mehr gültig ist (abgelaufen, gefälscht): Seine Sitzung ist abgelaufen, das teilen wir ihm mit
    // -----------------------------------------------------------------------
    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'));
    }

    // -----------------------------------------------------------------------
    // ein kernel.response-Listener (siehe Beispiel 24), in derselben Klasse geschrieben:
    // Er löscht das Cookie eines ungültigen Tokens bei allen Antworten
    // -----------------------------------------------------------------------
    #[AsEventListener(event: KernelEvents::RESPONSE)]
    public function clearInvalidToken(ResponseEvent $event): void
    {
        if ($event->getRequest()->attributes->get(self::INVALID_TOKEN)) {
            AuthService::clearCookie($event->getResponse());
        }
    }
}

Der Authenticator aus Beispiel 25, deklariert in [security.yaml] ([custom_authenticators]). Er dient auch als Entry Point der Firewall: Er implementiert die Schnittstelle [AuthenticationEntryPointInterface], und [Symfony] wählt ihn automatisch aus, da er der einzige Authenticator der Firewall ist.

  • Zeilen 45–48: [supports] legt fest, ob der Authenticator eingreifen soll: nur, wenn die Anfrage das Token-Cookie enthält. Ohne Cookie ist der Besucher anonym, und es geschieht nichts weiter;
  • Zeilen 53–58: [authenticate] überprüft das Token. Ein ungültiges Token löst eine [AuthenticationException] aus (ihre Unterklasse [CustomUserMessageAuthenticationException], trägt eine frei wählbare Meldung). Andernfalls wird ein selbstvalidierender Passport ([SelfValidatingPassport]: Es gibt kein Passwort zu überprüfen; die Signatur des Tokens dient als Passwort) zurückgegeben, dessen Benutzer aus dem Token aufgebaut wird, ohne ihn in der Datenbank nachzuschlagen;
  • Zeilen 60–63: nach einer erfolgreichen Authentifizierung [null]: Die Anfrage wird mit der angeforderten Action fortgesetzt;
  • Zeilen 67–71: nach einem Fehlschlag (abgelaufenes oder gefälschtes Token) ebenfalls [null] : Der Besucher bleibt anonym. Die Regeln [access_control] leiten den Besucher auf die Anmeldeseite um, wenn er eine geschützte Seite anfordert, aber er kann öffentliche Seiten (einschließlich der Anmeldeseite selbst!) aufrufen. Der einzige Hinweis steht in einem Request-Attribut, das besagt, dass das Cookie gelöscht werden soll;
  • Zeilen 78–84: der Entry Point, den die Firewall aufruft, wenn ein anonymer Besucher eine geschützte Seite anfordert: eine Umleitung auf die Anmeldeseite. Enthielt die Anfrage ein Token-Cookie, bedeutet das, dass dieses Token nicht mehr gültig ist: Es wird die Meldung „Ihre Sitzung ist abgelaufen: Bitte melden Sie sich erneut an.“ angezeigt (eine Pop-up-Meldung, wird später behandelt);
  • Zeilen 90–96: ein Listener für das Ereignis [kernel.response] (Beispiel 24), definiert innerhalb derselben Klasse: Das Attribut [#[AsEventListener]] wird auf eine Methode angewendet, und der Authenticator – ein Service wie jeder andere – wird zugleich zum Listener. Er löscht das Cookie bei einem ungültigen Token, unabhängig von der Antwort: der Anmeldeseite, einer öffentlichen Seite oder einer Umleitung vom Entry Point. Ein ungültiges Cookie ist nutzlos und würde die Meldung der nächsten Anfrage verfälschen.

11.12.4. src/Security/InvalidSession.php

<?php
// src/Security/InvalidSession.php: Das Token ist gültig, aber das Konto, auf das es verweist,
// existiert nicht mehr: Es wurde seit dem Login gelöscht (vom Patienten
// selbst in einem anderen Tab oder vom ADMIN). Wir behandeln diesen Fall wie eine
// abgelaufene Sitzung: Der ErrorPage-Listener löscht das Cookie und leitet zur
// Login-Seite um.

namespace App\Security;

use RuntimeException;

class InvalidSession extends RuntimeException
{
}

Ein in Beispiel 25 nicht behandeltes Szenario: Das Token ist gültig, aber das Konto, auf das es verweist, existiert nicht mehr. Ein Patient hat sein Konto in einem Tab gelöscht, das Token ist aber noch in einem anderen Tab vorhanden; oder der Administrator hat das Konto eines angemeldeten Patienten gelöscht. Die Signatur des Tokens gibt keinen Hinweis auf die Existenz des Kontos; erst wenn die Anwendung den dem Konto zugeordneten Patienten sucht ([Utils::connectedPatient], wird später behandelt), stellt sie fest, dass das Konto nicht mehr existiert. Sie wirft dann diese Exception, die der Listener [ErrorPage] (wird später behandelt) als abgelaufene Sitzung behandelt. Die Klasse ist leer: Nur ihr Typ ist von Bedeutung, den der Listener erkennt ([instanceof]).

11.12.5. src/Security/CaptchaService.php, Captcha.php und CaptchaDrawing.php

[CaptchaDrawing.php] und [Captcha.php] stammen aus Beispiel 27. Der Service ist fast derselbe:

<?php
// =========================================================================
// src/Security/CaptchaService.php: ein CAPTCHA ("Test, um Mensch und
// Roboter zu unterscheiden"), vom Server selbst erzeugt, ohne externen Dienst (siehe Beispiel 27).
//
// So funktioniert es:
//   1. generate() zieht einen zufälligen Text, erstellt daraus ein Bild und speichert die richtige
//      Antwort IM CACHE des Servers unter einer zufälligen Kennung;
//   2. Die Seite zeigt das Bild an und legt die Kennung in einem versteckten Feld des
//      Formulars ab (die Antwort selbst verlässt den Server nie);
//   3. verify(id, typed) vergleicht die Eingabe mit der erwarteten Antwort und VERGISST dann
//      dieses Captcha: Jedes Bild wird nur einmal verwendet, ein Roboter kann
//      eine bereits gefundene Antwort nicht wiederverwenden.
//
// Warum der Cache? Eine PHP-Anwendung behält von einer Anfrage zur nächsten NICHTS im Speicher:
// Jede Anfrage beginnt bei null. Was über eine Anfrage hinaus bestehen muss,
// kommt daher in den Cache (hier Dateien in var/cache), der von allen
// Anfragen gemeinsam genutzt wird, bei einem Cache wie Redis sogar von mehreren Servern.
// =========================================================================

namespace App\Security;

use Psr\Cache\CacheItemPoolInterface;
use Symfony\Component\Lock\LockFactory;

class CaptchaService
{
    // Gültigkeitsdauer eines Bildes in Sekunden: 10 Minuten, um das Formular auszufüllen
    private const LIFETIME = 600;

    public function __construct(private CacheItemPoolInterface $cache, private LockFactory $locks)
    {
    }

    public function generate(): Captcha
    {
        $text = CaptchaDrawing::randomText(5);        // 5 Zeichen
        $id = bin2hex(random_bytes(12));              // eine nicht zu erratende Kennung
        // der Cache vergisst die Antwort nach 10 Minuten von selbst
        $item = $this->cache->getItem("captcha.$id");
        $this->cache->save($item->set($text)->expiresAfter(self::LIFETIME));
        return new Captcha($id, CaptchaDrawing::svg($text));
    }

    // true, wenn [$typed] die richtige Antwort auf das Captcha [$id] ist (unabhängig von
    // Groß-/Kleinschreibung). Das Captcha wird in jedem Fall verbraucht.
    public function verify(?string $id, ?string $typed): bool
    {
        // die Kennung kommt vom Browser: hexadezimale Ziffern oder nichts
        if ($id === null || ! ctype_xdigit($id) || $typed === null) {
            return false;
        }
        // Legen zwei Anfragen im selben Moment dasselbe Captcha vor, erhält nur eine
        // die Sperre (acquire(false): ohne Warten) - die andere scheitert
        $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;
    }
}
  • Zeilen 35–43: eine zufällig erzeugte Zeichenkette mit 5 Zeichen, eine zufällige Kennung ([random_bytes], ein kryptografischer Generator, dessen Bytes mit [bin2hex] hexadezimal geschrieben werden) und die korrekte Antwort, die 10 Minuten lang im Cache gespeichert wird (Beispiel 20) ([expiresAfter], in Sekunden);
  • Zeilen 47–66: ein Unterschied zu Beispiel 27. Die Antwort wird gelesen und dann aus dem Cache entfernt. Zwischen Lesen und Entfernen könnte eine zweite Anfrage, die dasselbe CAPTCHA vorlegt, sie ebenfalls lesen: zwei Versuche für ein einziges gelöstes Bild. Eine Sperre (Beispiel 20), die für dieses CAPTCHA spezifisch ist, schützt daher sowohl das Lesen als auch das Entfernen. [acquire(false)] erwirbt sie sofort: Es liefert [false] , wenn eine andere Anfrage sie bereits hält, und diese Anfrage, die das Rennen verliert, schlägt fehl. Der Block [finally] gibt die Sperre in jedem Fall frei. Der Vergleich ignoriert Groß- und Kleinschreibung ([strcasecmp] liefert 0 für zwei Zeichenketten, die sich nur in der Groß- und Kleinschreibung unterscheiden) und Leerzeichen um die Eingabe ([trim]).

11.12.6. src/Security/AttemptLimiter.php

<?php
// =========================================================================
// src/Security/AttemptLimiter.php: zweites Bollwerk gegen Roboter (das erste
// ist das Captcha): Wir ZÄHLEN die Versuche und SPERREN ab einem Schwellenwert
// für eine gewisse Zeit (siehe Beispiel 27).
//
//   - Login: Nach LOGIN_MAX_FAILURES Fehlschlägen (falsches Captcha oder falsches
//     Passwort) für dasselbe Login von derselben IP-Adresse wird dieses Paar
//     bis zum Ende eines Zeitfensters von LOGIN_BLOCK_MINUTES Minuten gesperrt, gerechnet
//     ab dem ersten Fehlschlag. Dieselbe IP-Adresse wird auch gesperrt, wenn sie LOGIN_MAX_FAILURES_IP
//     Fehlschläge ansammelt, alle Logins zusammen (ein Roboter, der
//     Tausende verschiedener Logins ausprobiert);
//   - Kontoerstellung: höchstens REGISTRATION_MAX_PER_HOUR erstellte Konten pro
//     Stunde von derselben IP-Adresse.
//
// Vorsicht im Unterrichtsraum: Alle Rechner gehen oft über dieselbe
// IP-Adresse ins Internet. Deshalb gilt die Login-Sperre zuerst für das
// Paar (IP, Login) - ein Student, der sich beim Passwort vertippt, sperrt seine
// Nachbarn nicht - und deshalb lassen sich die Schwellenwerte anpassen (Datei .env).
//
// Die Zähler sind die der drei Limiter der RateLimiter-Komponente, deklariert
// in config/packages/framework.yaml und im Cache gespeichert.
// =========================================================================

namespace App\Security;

use Symfony\Component\RateLimiter\LimiterInterface;
use Symfony\Component\RateLimiter\RateLimiterFactoryInterface;

class AttemptLimiter
{
    // die Factories der Limiter [login], [login_ip] und [registration]: Der Name
    // des Parameters bezeichnet den Limiter (siehe Beispiel 27)
    public function __construct(
        private RateLimiterFactoryInterface $loginLimiter,
        private RateLimiterFactoryInterface $loginIpLimiter,
        private RateLimiterFactoryInterface $registrationLimiter,
    ) {
    }

    // ———————————————————————————————————————————————— Login

    // Anzahl der verbleibenden Sperrminuten (0 = der Versuch ist erlaubt)
    public function loginBlockMinutes(string $ip, string $login): int
    {
        return max(self::remainingMinutes($this->ipLoginLimiter($ip, $login)),
            self::remainingMinutes($this->loginIpLimiter->create($ip)));
    }

    // consume(): ein weiterer Fehlschlag; der erste öffnet ein Zeitfenster von
    // LOGIN_BLOCK_MINUTES Minuten, an dessen Ende der Zähler wieder bei null beginnt
    public function loginFailure(string $ip, string $login): void
    {
        $this->ipLoginLimiter($ip, $login)->consume();
        $this->loginIpLimiter->create($ip)->consume();
    }

    // ein erfolgreiches Login setzt den Zähler DIESES Logins zurück
    public function loginSuccess(string $ip, string $login): void
    {
        $this->ipLoginLimiter($ip, $login)->reset();
    }

    // ———————————————————————————————————————————————— Registrierung

    public function registrationBlockMinutes(string $ip): int
    {
        return self::remainingMinutes($this->registrationLimiter->create($ip));
    }

    public function registrationSuccess(string $ip): void
    {
        $this->registrationLimiter->create($ip)->consume();
    }

    // ———————————————————————————————————————————————— gemeinsame Mechanik

    // der Limiter des Paares (IP, Login): create(key) gibt einen Limiter zurück, der unter diesem Schlüssel
    // einen eigenen Zähler hat
    private function ipLoginLimiter(string $ip, string $login): LimiterInterface
    {
        return $this->loginLimiter->create("$ip|".mb_strtolower(trim($login)));
    }

    // consume(0) fragt den Limiter ab, ohne etwas zu verbrauchen: Ist kein "Token" mehr übrig?
    // getRetryAfter: das Datum des Endes des aktuellen Zeitfensters; die Sekunden, die
    // bis dahin verbleiben, werden auf die Minute AUFGERUNDET: 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));
    }
}

Die zweite Verteidigungslinie gegen Bots nach dem CAPTCHA: Wir zählen die Versuche und sperren den Zugriff, sobald ein Schwellenwert überschritten ist. Beispiel 27 stellte die Komponente [RateLimiter] von [Symfony] vor. Die drei Limiter werden in [config/packages/framework.yaml] deklariert (Policy [fixed_window]: ein Fenster fester Dauer, das vom ersten verbrauchten Token geöffnet wird); der Service erhält ihre Factories, identifiziert durch die Parameternamen (Zeilen 34–38): [$loginLimiter] für den Limiter [login], [$loginIpLimiter] für [login_ip], [$registrationLimiter] für [registration]. Eine Factory erzeugt mit ihrer Methode [create(key)] einen Limiter, der unter diesem Schlüssel einen eigenen Zähler hat. Zwei Regeln:

  • die Anmeldung (Zeilen 44–62): Jeder Fehlschlag (falsches CAPTCHA oder falsches Passwort) wird doppelt gezählt: für das Paar (IP-Adresse, Login) und für die IP-Adresse allein. Das Paar wird nach 5 fehlgeschlagenen Versuchen gesperrt (Einstellung [LOGIN_MAX_FAILURES]) und die IP-Adresse nach 25 (Einstellung [LOGIN_MAX_FAILURES_IP]), über alle Logins hinweg: Das ist der Bot, der Tausende verschiedener Logins ausprobiert. Warum nicht zuerst die IP-Adresse sperren? In einem Klassenraum (oder in einem Unternehmen) greifen oft alle Rechner über dieselbe gleiche IP-Adresse auf das Internet zu: Ein Schüler, der ein falsches Passwort eingibt, soll seine Nachbarn nicht sperren. [consume()] verbraucht ein Token (zählt als fehlgeschlagener Versuch); der erste Versuch öffnet ein 15-Minuten-Fenster (Einstellung [LOGIN_BLOCK_MINUTES]), an dessen Ende der Zähler auf null zurückgesetzt wird. Eine erfolgreiche Anmeldung setzt den Zähler für diesen Benutzer zurück ([reset]);
  • Kontoerstellung (Zeilen 66–74): höchstens 10 Konten pro Stunde und IP-Adresse (Einstellung [REGISTRATION_MAX_PER_HOUR]);
  • Zeilen 80–83: der Schlüssel für einen Limiter. Das Login steht in Kleinbuchstaben: [Admin] und [admin] gelten als gleich (wie bei der Datenbank; siehe deren Kollation);
  • Zeilen 88–95: [consume(0)] befragt den Limiter, ohne Token zu verbrauchen (Beispiel 27): Sind noch Token übrig, ist der Versuch erlaubt; andernfalls [getRetryAfter] liefert das Ende des aktuellen Fensters, und die bis dahin verbleibenden Sekunden werden auf die nächste Minute aufgerundet ([ceil]): Bleiben 30 Sekunden übrig, wird „1 Minute“ angezeigt. Die angezeigte Meldung hängt davon ab: „Zu viele fehlgeschlagene Versuche. Versuchen Sie es in 15 Minuten erneut.“

Die Zähler der Limiter werden im Cache gespeichert: Sie werden von allen Anfragen gemeinsam genutzt und überstehen einen Neustart des Servers. Der Befehl [php bin/console cache:pool:clear cache.rate_limiter] setzt sie alle auf null zurück (nützlich während der Entwicklung, wenn man sich selbst ausgesperrt hat); [php bin/console cache:clear], der das gesamte Verzeichnis [var/cache] leert, bewirkt dasselbe.

11.12.7. src/Security/RegistrationPass.php und RegistrationPassRequired.php

<?php
// =========================================================================
// src/Security/RegistrationPass.php: der "Pass" für die Kontoerstellung.
//
// Um die Seite "Patientenkonto erstellen" zu öffnen, muss man zuvor das
// Captcha der Login-Seite korrekt abgeschrieben haben (siehe RegistrationController, POST
// /register/access). Der Server stellt dann einen Pass aus:
//   - eine zufällige Kennung, gespeichert in einem HttpOnly-Cookie;
//   - 15 Minuten gültig (Zeit, um das Formular auszufüllen, auch bei mehreren
//     Versuchen nach Eingabefehlern);
//   - verbraucht, sobald ein Konto erstellt wird: EIN gelöstes Captcha = höchstens EIN Konto.
//     Ein Roboter kann keine Konten in Serie erstellen.
//
// Ohne gültigen Pass leiten GET und POST /register zur Login-Seite um
// (siehe das Attribut #[RegistrationPassRequired] und den Listener
// CheckRegistrationPass): Die direkte Eingabe der URL /register erlaubt es nicht,
// das Captcha zu umgehen.
//
// Wie die Captchas leben auch die Pässe im 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';

    // das Cookie wird vom Browser nur an die Adressen /register... gesendet
    private const PATH = '/register';

    // Lebensdauer eines Passes in Minuten
    private const LIFETIME = 15;

    public function __construct(
        private CacheItemPoolInterface $cache,
        #[Autowire(env: 'bool:COOKIE_SECURE')] private bool $cookieSecure,
    ) {
    }

    // stellt einen neuen Pass aus; gibt das Cookie zurück, das ihn trägt
    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, wenn [$id] ein vorhandener, nicht abgelaufener Pass ist; hasItem: Hat der
    // Cache dieses Element?
    public function isValid(?string $id): bool
    {
        return $id !== null && ctype_xdigit($id) && $this->cache->hasItem("pass.$id");
    }

    // der Pass wurde verwendet: Wir vergessen ihn...
    public function consume(?string $id): void
    {
        if ($id !== null && ctype_xdigit($id)) {
            $this->cache->deleteItem("pass.$id");
        }
    }

    // ... und sein Cookie wird durch ein Cookie desselben Namens und desselben Pfads gelöscht, das bereits abgelaufen ist
    public static function clearCookie(Response $response): Response
    {
        $response->headers->clearCookie(self::COOKIE, self::PATH);
        return $response;
    }
}

Das Anlegen eines Patientenkontos ist durch das CAPTCHA auf der Anmeldeseite geschützt. Das Formular zur Kontoerstellung befindet sich jedoch auf einer anderen Seite ([/register]): Woher soll das System beim Abruf des Formulars wissen, dass das CAPTCHA kurz zuvor gelöst wurde? Durch ein Token: Wenn das CAPTCHA gelöst ist, erzeugt der Server eine zufällige Kennung, speichert sie 15 Minuten lang im Cache und sendet sie in einem Cookie an den Browser. Das Formular wird nur mit einem gültigen Token angezeigt – und das Konto nur mit einem gültigen Token angelegt; das Token wird bei der Kontoerstellung verbraucht. Ein gelöstes CAPTCHA erlaubt somit das Anlegen eines Kontos, und die direkte Eingabe der Adresse [/register] führt ins Leere.

  • Zeilen 46–57: Das Cookie hat den Pfad [/register] ([withPath]): Der Browser sendet es nur an Adressen, die mit diesem Pfad beginnen. Es enthält nur eine zufällige Kennung – unmöglich zu erraten –, und nur der Cache des Servers weiß, ob sie gültig ist: Das Cookie muss nicht signiert werden;
  • Zeilen 61–64: [hasItem] gibt an, ob der Cache einen (nicht abgelaufenen) Eintrag unter diesem Schlüssel enthält;
  • Zeilen 75–79: Um ein Cookie zu löschen, müssen Sie denselben Namen und denselben Pfad angeben: Für den Browser sind zwei Cookies mit demselben Namen, aber unterschiedlichen Pfaden zwei verschiedene Cookies.
<?php
// src/Security/RegistrationPassRequired.php: ein eigenes PHP-ATTRIBUT (siehe
// Beispiel 24), das an Actions gesetzt wird, die einen Pass für die Kontoerstellung verlangen
// (siehe RegistrationPass und den Listener CheckRegistrationPass).

namespace App\Security;

use Attribute;

#[Attribute(Attribute::TARGET_METHOD)]
class RegistrationPassRequired
{
}

Ein [PHP] -Attribut eigener Erfindung, wie das [#[Timed]] in Beispiel 24, wird auf Actions angewendet, die einen Pass erfordern. Es wird vom Listener [CheckRegistrationPass] gelesen.

11.13. Die Listener: src/EventListener

Drei Kernel-Event-Listener (Beispiel 24), abgelegt im Ordner [src/EventListener], wie üblich. Das auf die Klasse gesetzte Attribut [#[AsEventListener]] legt das Ereignis und die Priorität fest; die aufgerufene Methode ist dann [__invoke].

11.13.1. src/EventListener/SetLanguage.php

<?php
// =========================================================================
// src/EventListener/SetLanguage.php: die Sprache der Anfrage (siehe Beispiel 22):
// die des Cookies [rdvmedecins_language], wenn es eine unterstützte Sprache ist, sonst Englisch.
//
// Priorität 40: Der Listener läuft VOR dem Routing von Symfony (Priorität 32). Er
// läuft somit für ALLE Anfragen, auch für solche, die zu keiner
// Route führen (Seite 404, 405...): Ihre Fehlerseite erscheint in der richtigen Sprache. Aus demselben
// Grund setzt er auch die Sprache des Translators selbst, was sonst von
// einem Symfony-Listener (Priorität 15) erledigt würde, den ein Routing-Fehler
// am Laufen hindern würde.
// =========================================================================

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
{
    // das Cookie, das die gewählte Sprache speichert (siehe LanguageController)
    public const COOKIE = 'rdvmedecins_language';

    // die unterstützten Sprachen (Ordner translations); die erste ist die Standardsprache
    public const LANGUAGES = ['en', 'fr'];

    // LocaleAwareInterface: ein Service, der eine Sprache hat, hier der 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);
    }
}

Die Sprache der Anfrage (Beispiel 22): die Sprache des Cookies, sofern es eine unterstützte Sprache ist; andernfalls die Standardsprache (Englisch). Ein Unterschied zu Beispiel 22: Priorität 40 (Zeile 21), die höher ist als die Priorität des Routings (32). Der Listener aus Beispiel 22 (Priorität 20) lief nach dem Routing; bei einer URL, die zu keiner Route passt, wirft das Routing vor dem Listener eine Exception, und die 404-Seite wäre selbst für einen französischsprachigen Benutzer englisch gewesen. Aus demselben Grund legt der Listener selbst die Sprache des Übersetzers fest (Zeile 41), was üblicherweise ein Listener von [Symfony] ([LocaleAwareListener]) übernimmt, der ebenfalls nach dem Routing platziert ist. [LocaleAwareInterface] ist die Schnittstelle für Services, die eine Sprache haben; der Übersetzer ist einer davon, und genau diesen Übersetzer injiziert [Symfony] hier.

11.13.2. src/EventListener/CheckRegistrationPass.php

<?php
// =========================================================================
// src/EventListener/CheckRegistrationPass.php: Die mit dem Attribut
// #[RegistrationPassRequired] markierten Actions (GET und POST /register) verlangen einen
// gültigen Pass (siehe src/Security/RegistrationPass.php); andernfalls zurück zur
// Login-Seite, mit einer Nachricht. Die direkte Eingabe der URL
// /register erlaubt es daher nicht, das Captcha zu umgehen.
//
// Ein kernel.controller-Listener (siehe Beispiel 24): Die Action ist gewählt, aber
// noch nicht aufgerufen. Um abzulehnen, ERSETZT er sie (setController) durch eine
// Funktion, die eine Weiterleitung zurückgibt.
// =========================================================================

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

Ein Listener für [kernel.controller] (Beispiel 24): Die Action ist ausgewählt, aber noch nicht aufgerufen.

  • Zeilen 37–39: [getAttributes(class)] liefert die Attribute dieser Klasse, die die Action trägt: eine leere Liste; die Action erfordert kein Token; der Listener unternimmt nichts;
  • Zeilen 40–44: kein gültiges Token: Es wird eine Meldung angezeigt, und die Action wird ersetzt ([setController]) durch eine Funktion, die auf die Anmeldeseite umleitet. Der Kernel ruft diese Funktion anstelle der Action auf. Die URL wird außerhalb der Arrow Function berechnet, die dadurch nur eine Variable benötigt.

Der Listener erhält seine Services über seinen Konstruktor: Ein Listener ist ein Service, der vom Container erzeugt wird, genau wie Controller.

11.13.3. src/EventListener/ErrorPage.php

<?php
// =========================================================================
// src/EventListener/ErrorPage.php: wie Fehler zu HTML-Seiten werden
// (siehe Beispiel 24). Drei Fälle:
//   1. eine InvalidSession (seit dem Login gelöschtes Konto) -> zurück zur
//      Login-Seite, wie bei einer abgelaufenen Sitzung;
//   2. ein HTTP-Fehler: ungültige Anfrage (400), unzureichende Rolle (403), unbekannte
//      Seite (404), nicht unterstützte Methode (405), fehlendes oder falsches Anti-CSRF-Token
//      (419)... -> die Fehlerseite, mit dem ursprünglichen Code;
//   3. jede andere Exception (eine echte Anomalie): Symfony hat sie bereits mit
//      ihrem Call Stack ins Log geschrieben; in der Produktion (APP_ENV=prod)
//      sieht der Benutzer die Fehlerseite 500 - nie den Call Stack; in
//      der Entwicklung die Debug-Seite von Symfony.
//
// Priorität -10: nach dem Listener von Symfony, der die Exception ins Log schreibt
// (0), und nach dem der Sicherheit (1), der eine Zugriffsverweigerung in eine
// Weiterleitung zur Login-Seite (anonymer Besucher) oder in einen Fehler 403
// (authentifizierter Benutzer) umwandelt; vor dem Listener, der die Fehlerseite von Symfony
// erstellt (-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,
        // der Debug-Modus (APP_ENV=dev): der Parameter kernel.debug des Containers
        #[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;
        }

        // eine echte Anomalie: in der Entwicklung die Debug-Seite von Symfony
        if (! $this->debug) {
            $event->setResponse($this->page(500));
        }
    }

    // die Fehlerseite, mit dem HTTP-Code des Fehlers und seiner Meldung
    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);
    }
}

Wie Fehler zu HTML-Seiten werden: Das ist der Listener [ErrorPage] aus Beispiel 24, erweitert. Er lauscht auf das Ereignis [kernel.exception] mit Priorität -10 (Zeile 37): nach dem Listener von [Symfony], der die Exception protokolliert (Priorität 0), und nach dem Listener der Sicherheitskomponente (Priorität 1), der eine Zugriffsverweigerung entweder in einen Aufruf des Entry Points (anonymer Besucher) oder in einen 403-Fehler (authentifizierter Benutzer mit ungeeigneter Rolle) umwandelt; vor dem Handler, der die Fehlerseite erzeugt, [Symfony] (-128). Drei Fälle:

  • Zeilen 53–57: eine [InvalidSession] (das Konto wurde gelöscht): die Meldung „Sitzung abgelaufen“, Löschen des Token-Cookies und die Anmeldeseite;
  • Zeilen 59–62: ein HTTP-Fehler: [HttpExceptionInterface] ist der Handler für Exceptions mit einem HTTP-Code ([NotFoundHttpException], [AccessDeniedHttpException], [HttpException(419)]...), der von [getStatusCode] geliefert wird. Die Fehlerseite wird mit diesem Code angezeigt;
  • Zeilen 65–67: Jede andere Exception ist ein echter Fehler. In der Entwicklung ([kernel.debug], Beispiel 24) unternimmt der Listener nichts: Es wird die Debug-Seite von [Symfony] mit dem Call Stack angezeigt. In der Produktion erscheint die 500-Fehlerseite: Der Benutzer sieht nie den Call Stack, den das Log bereits erfasst hat;
  • Zeilen 71–82: die Fehlerseite, View [error.html.twig], die den Code und den Meldungsschlüssel anzeigt. [match] ([PHP] 8) wählt anhand strikter Gleichheit einen Wert in Abhängigkeit von einem anderen aus; [404, 405 =>] deckt zwei Fälle ab; [default] behandelt alle übrigen. Der Code 405 (Method Not Allowed: ein GET auf eine Adresse, die nur POST akzeptiert) wird als Fehler „Seite nicht gefunden“ angezeigt.

11.14. Der Anmelde-Controller

11.14.1. src/Controller/AuthController.php

<?php
// =========================================================================
// src/Controller/AuthController.php: die ÖFFENTLICHEN Routen des Logins:
//   GET  /        leitet zur Startseite der Rolle weiter (oder zu /login)
//   GET  /login   zeigt das Login-Formular an (mit seinem Captcha)
//   POST /login   prüft Versuchslimit, Captcha, Login / Passwort
//   POST /logout  das Abmelden
//
// Schutz vor Robotern, in dieser Reihenfolge:
//   1. Zu viele aktuelle Fehlschläge für dieses Login von dieser IP-Adresse?
//      -> sofortige Ablehnung, ohne das Passwort auch nur anzusehen;
//   2. Falsche Antwort auf das Captcha? -> Ablehnung (als Fehlschlag gezählt);
//   3. erst dann die Prüfung des Passworts.
// Wir prüfen NIE das Passwort eines in Schritt 1 oder 2 abgelehnten Versuchs:
// Ein Roboter kann daher nichts lernen, wenn er hartnäckig weitermacht.
// =========================================================================

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

    // die Startseite jeder Rolle direkt nach dem Login: der Name ihrer Route
    public static function homePage(Role $role): string
    {
        return $role === Role::USER ? 'area' : 'schedule';
    }

    // -----------------------------------------------------------------------
    // GET /
    // Die Route ist öffentlich: Der Benutzer ist, falls vorhanden, bekannt
    // ($this->getUser()), aber es wird nichts verlangt.
    // -----------------------------------------------------------------------
    #[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]: Der optionale Parameter füllt das Login-Feld vor
    // (verwendet direkt nach dem Anlegen eines Kontos, siehe RegistrationController)
    // -----------------------------------------------------------------------
    #[Route('/login', name: 'login', methods: ['GET'])]
    public function form(Request $request): Response
    {
        // bereits angemeldet (Token noch gültig): direkt zur Startseite
        $user = $this->getUser();
        if ($user instanceof ConnectedUser) {
            return $this->redirectToRoute(self::homePage($user->role));
        }
        // mb_substr: höchstens 30 Zeichen
        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. zu viele aktuelle Fehlschläge?
        $minutes = $this->limiter->loginBlockMinutes($ip, $login);
        if ($minutes > 0) {
            return $this->page($login, new Message('ERRORS.TOO_MANY_ATTEMPTS', ['minutes' => $minutes]));
        }

        // 2. das 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. das Passwort
        $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: das Token-Cookie löschen, dann zur Login-Seite.
    // Nur POST: Ein einfacher Link (GET) auf einer anderen Website kann den
    // Benutzer nicht ohne sein Wissen abmelden.
    // -----------------------------------------------------------------------
    #[Route('/logout', name: 'logout', methods: ['POST'])]
    public function logOut(Request $request): Response
    {
        $this->checkCsrf($request);
        return AuthService::clearCookie($this->redirectToRoute('login'));
    }

    // das Formular, immer mit einem NEUEN Captcha (jedes Bild wird nur einmal
    // verwendet); das eingegebene Login wird erneut angezeigt, nie das Passwort. Bei einem Fehler:
    // der Code 422, wie bei einem ungültigen Formular (siehe Beispiel 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));
    }
}

Der Anmelde-Controller, der auf Beispiel 27 beruht. Er erbt von der Klasse [BaseController] der Anwendung (wird später behandelt), die ihrerseits eine Unterklasse von [AbstractController] ist.

  • Zeilen 41–44: die Startseite jeder Rolle samt Routennamen: „Mein Bereich“ für einen Patienten und der Kalender für die übrigen;
  • Zeilen 51–57: Die Adresse [/] leitet zur Startseite der Rolle oder zur Anmeldeseite weiter. Die Route ist öffentlich (Regel [access_control] in [security.yaml]): [getUser()] liefert den vom Authenticator ermittelten Benutzer, falls es einen gibt, ohne irgendetwas zu verlangen. [redirectToRoute] (Beispiel 04) erzeugt eine Umleitung auf eine benannte Route;
  • Zeilen 63–73: Ein bereits angemeldeter Benutzer gelangt direkt zu seiner Startseite. Der optionale Parameter [login] der URL füllt das Feld vorab aus (nach der Kontoerstellung); [mb_substr] kürzt es auf 30 Zeichen;
  • Zeilen 78–110: der Anmeldevorgang in der Reihenfolge aus Beispiel 27: das Anti-CSRF-Token (wird später behandelt), etwaige Sperren, das CAPTCHA und das Passwort. Ein Passwort wird bei einem vom Limiter oder vom CAPTCHA abgelehnten Versuch nie überprüft: Ein Bot lernt durch Beharrlichkeit nichts. [getClientIp] liefert die IP-Adresse des Clients. Schlägt der Versuch fehl, wird die Seite direkt gerendert (keine Umleitung): Das erneut angezeigte Formular hat stets ein neues CAPTCHA und das eingegebene Login. Der Fehler ist ein Objekt [Message] (siehe unten), bestehend aus einem Schlüssel und seinen Parametern, das am Seitenende angezeigt wird. Bei Erfolg wird der Anmeldezähler auf null zurückgesetzt, und der Browser wird mit dem Token-Cookie ([headers->setCookie]) auf die Startseite der Rolle umgeleitet;
  • Zeilen 117–122: Das Abmelden löscht das Token-Cookie (Beispiel 25). Es akzeptiert nur POST, zusammen mit dem Anti-CSRF-Token: Ein einfacher Link auf einer anderen Website kann den Benutzer nicht ohne sein Wissen abmelden;
  • Zeilen 127–132: die Anmeldeseite. Der dritte Parameter von [render] ist die zu füllende Antwort: Ein Fehler wird mit dem Code 422 (Unprocessable Content) zurückgegeben, wie bei einem ungültigen Formular (Beispiel 19). [new Response(status: ...)] verwendet ein benanntes Argument ([PHP] 8): Die ersten beiden Parameter des Konstruktors behalten ihre Standardwerte.

Die Anmeldeseite erhält die Variable [pageTitle], den Übersetzungsschlüssel für den Seitentitel: Alle Actions übergeben sie an ihre View für das Template (siehe unten).

11.15. Die Web-Schicht: gemeinsame Services

Der Ordner [src/Web] enthält die Elemente, die die Controller gemeinsam nutzen.

11.15.1. src/Web/ApplicationModel.php

<?php
// =========================================================================
// src/Web/ApplicationModel.php: der Cache / die Fassade der Geschäftsschicht (das Pendant zur
// Klasse [ApplicationModel] der anderen Versionen der Anwendung): die
// Listen der Ärzte und Clients werden einmal aus der Datenbank gelesen und dann aus
// dem Cache bereitgestellt.
//
// Warum der CACHE von Symfony und nicht einfach eine Eigenschaft dieses Objekts? Weil
// eine PHP-Anwendung von einer Anfrage zur nächsten nichts im Speicher behält: Dieses
// Objekt ist ein gemeinsam genutzter Service, aber ein Service lebt nur für EINE Anfrage.
// Der Cache dagegen wird von allen Anfragen gemeinsam genutzt (siehe Beispiele 20 und 23).
//
// Diese Listen können sich ÄNDERN (der ADMIN fügt Ärzte und
// Clients hinzu, ändert und löscht sie): Jeder Schreibzugriff läuft daher über diese Fassade, die die
// betroffene Liste anschließend VERGISST; die nächste Anfrage, die sie braucht, liest sie erneut aus der Datenbank. Genau darin liegt
// der Sinn eines EINZIGEN Einstiegspunkts in die Geschäftsschicht: Die Regel
// "Schreiben => Cache aktualisieren" steht nur hier.
// =========================================================================

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;

// derselbe Vertrag wie die Geschäftsschicht
class ApplicationModel implements Business
{
    private const DOCTORS = 'rdvmedecins.doctors';

    private const CLIENTS = 'rdvmedecins.clients';

    // CacheInterface: der Cache der Anwendung (der Service cache.app), gesehen über
    // das Interface der "Contracts" von Symfony, einfacher als das von PSR-6
    public function __construct(private BusinessService $business, private CacheInterface $cache)
    {
    }

    // ———————————————————————————————— Lesezugriffe aus dem Cache

    // get(key, function): der Wert aus dem Cache, wenn er existiert; andernfalls wird die Funktion
    // aufgerufen und ihr Ergebnis im Cache gespeichert (ohne Zeitlimit), bevor
    // es zurückgegeben wird. Die Entitäten werden dort serialisiert gespeichert (siehe serialize): Jede
    // Anfrage, die sie liest, erhält Kopien davon, die Doctrine nicht verfolgt
    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());
    }

    // der Arzt, dessen Benutzerkonto [$userId] ist - dient dazu, für einen angemeldeten Arzt
    // seinen eigenen Terminkalender vorauszuwählen. array_find: das erste Element
    // des Arrays, das die Bedingung erfüllt (null, wenn es keines gibt)
    public function getDoctorByUserId(int $userId): ?Doctor
    {
        return array_find($this->getAllDoctors(), fn (Doctor $d) => $d->getAccount()->getId() === $userId);
    }

    // ———————————————————————————————— einfache Delegationen

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

    // hier kein Cache: Es kommt auf die aktuellsten Daten an (ein Patient, der
    // soeben sein Konto geändert oder gelöscht hat)
    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);
    }

    // ———————————————————————————————— Schreibzugriffe => Cache vergessen
    // (delete: das Element wird aus dem Cache entfernt)

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

Alle Versionen der Anwendung haben eine Klasse namens [ApplicationModel]: einen einzigen Einstiegspunkt von der Web-Schicht in die Geschäftsschicht, der die Listen der Ärzte und Clients im Speicher hält. Auf diese Listen greifen fast alle Seiten zu (die Dropdown-Liste der Ärzte im Kalender, die Liste der Patienten im Buchungsfenster und die Verwaltungsseiten), und sie ändern sich selten.

Was sich in [PHP] ändert, ist die Bedeutung von „im Speicher“. Eine Anwendung wie [Java], [C#] oder [Python] bleibt zwischen den Anfragen im Speicher; die [Flask]-Version speicherte diese Listen in den Eigenschaften eines einzigen, beim Start erzeugten Objekts. Eine [PHP] -Anwendung wird bei jeder Anfrage neu erzeugt (Beispiel 01): Das Objekt [ApplicationModel] ist zwar ein geteilter Service, existiert aber nur für die Dauer einer einzigen Anfrage (Beispiel 23). Die Listen werden daher im Cache von [Symfony] gespeichert (Beispiel 20), der von allen Anfragen gemeinsam genutzt wird.

  • Zeile 34: Die Klasse implementiert die [Business]-Schnittstelle, genau wie [BusinessService]: Die Controller rufen dieselben Methoden auf, unabhängig davon, welche Klasse sie bereitstellt;
  • Zeile 42: Diesmal wird der Cache über die [CacheInterface]-Schnittstelle der „Contracts“ von [Symfony] (derselbe [cache.app]-Service) bezogen, die einfacher ist als die PSR-6-Schnittstelle in den Beispielen;
  • Zeilen 52–60: [get(key, function)] liefert den unter diesem Schlüssel gespeicherten Wert; existiert er nicht, ruft sie die Funktion auf (die die Liste aus der Datenbank liest), speichert deren Ergebnis unbegrenzt im Cache und gibt es zurück. Die erste Abfrage, die die Liste benötigt, liest sie direkt aus der Datenbank; nachfolgende Abfragen finden sie im Cache. Der Cache speichert das Array der Entitäten in serialisierter Form (Beispiel 20) und rekonstruiert es beim Lesen, zusammen mit den geladenen Beziehungen (dem Konto jeder Person). Die rekonstruierten Entitäten sind Kopien, die der [Doctrine]-Entity-Manager nicht verfolgt: Sie dienen der Anzeige, niemals dem Schreiben (die Geschäftsschicht liest, was sie ändert, stets erneut aus der Datenbank);
  • Zeilen 65–68: der mit einem Konto verknüpfte Arzt, der mit [array_find] (Beispiel 06) aus der Cache-Liste abgerufen wird;
  • Zeilen 72–127: Die übrigen Methoden des [Business]-Vertrags delegieren einfach an die Geschäftsschicht. Der Client eines Kontos ([getClientByUserId]) wird stets aus der Datenbank abgerufen, nicht aus dem Cache: Die aktuellsten Daten haben Vorrang (ein Patient, der soeben sein Konto geändert oder gelöscht hat);
  • Zeilen 132–170: die Aktualisierungen. Jede Aktualisierung durch einen Arzt oder einen Client speichert die betroffene Liste nicht ([delete]): Die nächste Abfrage, die sie benötigt, ruft sie aus der Datenbank ab. Darin liegt der Sinn eines einzigen Einstiegspunkts: Die Regel „Ein Schreibvorgang aktualisiert den Cache“ ist nur hier implementiert. Schlägt das Schreiben fehl (z. B. durch eine [BusinessException]), wird die Liste nicht überschrieben – sie hat sich nicht geändert. Eine Anwendung, die über einen anderen Weg in die Datenbank schreibt (ein anderes Programm, eine andere Version der Anwendung mit derselben Datenbank), würde den Cache veraltet zurücklassen: [php bin/console cache:pool:clear cache.app] würde ihn leeren.

11.15.2. src/Web/Message.php und Flash.php

<?php
// src/Web/Message.php: eine zu übersetzende Nachricht: ihr Schlüssel und ihre Parameter.
// Die Views zeigen sie mit {{ message.key|trans(message.params) }} an.

namespace App\Web;

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

Eine zu übersetzende Nachricht: ein Schlüssel und seine Parameter. Fehler in der Geschäftsschicht ([BusinessException]) und solche in den Controllern werden zu [Message], die die Views in die Sprache der Seite übersetzen.

<?php
// =========================================================================
// src/Web/Flash.php: die "Flash"-Nachrichten: eine Nachricht, die EINMAL angezeigt wird, auf der
// NÄCHSTEN Seite (siehe Beispiel 20). Sie ergänzt auf natürliche Weise das
// Muster "Post / Redirect / Get", das alle Formulare der Anwendung verwenden: Ein
// erfolgreicher POST baut keine Seite auf, sondern leitet (302) auf eine GET-Seite um; die
// Nachricht muss dagegen die Weiterleitung überstehen.
//
// Symfony speichert sie in der SESSION (Dateien im Ordner var/sessions, siehe
// config/packages/framework.yaml).
//
// Eine Nachricht enthält keinen Text, sondern einen Übersetzungs-SCHLÜSSEL und seine Parameter
// (ein Message-Objekt): Sie wird beim Anzeigen übersetzt, in der Sprache
// der Seite (siehe templates/fragments). Zwei Listen: die Erfolgsmeldungen (oben auf
// der Seite angezeigt) und die Fehlermeldungen (unten angezeigt).
// =========================================================================

namespace App\Web;

use Symfony\Component\HttpFoundation\RequestStack;

class Flash
{
    // der Request-Stack, um die Session der aktuellen Anfrage zu erreichen
    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: der "Bag" der Flash-Nachrichten der Session; add(type, message)
    // fügt der Liste dieses Typs eine Nachricht hinzu (siehe Beispiel 20)
    private function add(string $type, string $key, array $params): void
    {
        $this->requests->getSession()->getFlashBag()->add($type, new Message($key, $params));
    }
}

Flash-Nachrichten (Beispiel 20): eine Nachricht, die von einer Aktion in der Session abgelegt, von der nächsten Seite angezeigt und anschließend verworfen wird. Dies ergänzt das Post/Redirect/Get-Muster, dem alle Formulare der Anwendung folgen. Es gibt zwei Typen: Erfolgsmeldungen werden oben auf der Seite angezeigt, Fehlermeldungen unten.

  • Zeile 25: der Request-Stack ([RequestStack]), ein Service von [Symfony] , der den aktuellen Request und damit dessen Session kennt. Ein gemeinsam genutzter Service kann den Request nicht selbst über seinen Konstruktor erhalten: Er wird einmal erzeugt und kann für mehrere Requests verwendet werden (einen Hauptrequest und seine Unterrequests);
  • Zeilen 41–44: der „Bag“ der Flash-Nachrichten der Session ([getFlashBag]), dessen Methode [add(type, message)] die Liste dieses Typs ergänzt. Dasselbe leistet die Methode [addFlash] von [AbstractController] (Beispiel 20); als Service ermöglicht er es, eine Nachricht außerhalb eines Controllers abzulegen – etwa im Authenticator oder in Listenern.

Die [Message]-Objekte werden unverändert in der Session gespeichert: [PHP] serialisiert die Sitzungsdaten (Beispiel 20) und rekonstruiert sie beim nächsten Request. In den Views [app.flashes('errors')] liefert die Liste der Nachrichten dieses Typs und entfernt sie aus der Session.

11.15.3. src/Web/BaseController.php

<?php
// =========================================================================
// src/Web/BaseController.php: die Elternklasse der Controller der Anwendung. Sie
// erbt von AbstractController (siehe Beispiel 03) und fügt die Prüfung des
// Anti-CSRF-Tokens der handgeschriebenen Formulare hinzu (siehe Beispiel 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
{
    // die Kennung des Anti-CSRF-Tokens der handgeschriebenen Formulare: nur eine
    // für die gesamte Anwendung (in den Views: csrf_token('rdvmedecins')). Die
    // Formulare der Form-Komponente haben jeweils ihr eigenes
    public const CSRF = 'rdvmedecins';

    // -----------------------------------------------------------------------
    // ein fehlendes oder falsches Anti-CSRF-Token: Die Seite wurde wahrscheinlich vor dem
    // Ablauf der Session angezeigt, die das Token enthielt. Fehler 419, der (inoffizielle,
    // aber weit verbreitete) Code für eine abgelaufene Seite: Der ErrorPage-Listener zeigt
    // "The page has expired: reload it, then try again." an.
    // -----------------------------------------------------------------------
    protected function checkCsrf(Request $request): void
    {
        if (! $this->isCsrfTokenValid(self::CSRF, $request->request->getString('_token'))) {
            throw new HttpException(419, 'invalid anti-CSRF token');
        }
    }
}

Die Elternklasse der Controller. Manuell geschriebene Formulare in den Views (Anmeldung, Abmeldung, Löschungen, Reservierungen usw.) enthalten ein Anti-CSRF-Token (Beispiel 21) mit dem Bezeichner [rdvmedecins]: Ein einziger Bezeichner genügt hier, da alle diese Aktionen bereits einen angemeldeten Benutzer oder ein CAPTCHA voraussetzen. Jedes Formular der Form-Komponente hat ein eigenes Token, das von der Komponente validiert wird.

Ein fehlendes oder ungültiges Token beendet die Aktion mit einem Fehler 419 (Zeilen 27–32), dem (inoffiziellen, aber weit verbreiteten) Code für eine abgelaufene Seite: Das Token wird in der Session gespeichert, und eine vor Ablauf der Session angezeigte Seite enthält ein Token, das der Server nicht mehr kennt. Der [ErrorPage]-Listener zeigt dann „Die Seite ist abgelaufen: Laden Sie sie neu und versuchen Sie es erneut.“ an. [HttpException] ist die generische HTTP-Exception: Ihr Konstruktor erhält den Code und eine Nachricht (für das Log bestimmt, nicht für den Benutzer).

11.15.4. src/Web/Utils.php

<?php
// =========================================================================
// src/Web/Utils.php: kleine Hilfsfunktionen der Web-Schicht:
//   - Daten: "yyyy-mm-dd", Tage "Wednesday 23 September 2026";
//   - Eingaben: Lesen einer positiven ganzen Zahl und eines Datums, die vom Browser gesendet werden;
//   - Benutzer: der angemeldete Benutzer und sein Patient (Entität Client).
// Die STATISCHEN Methoden werden ohne Objekt aufgerufen (Utils::iso($day)); die anderen
// benötigen Services (die aktuelle Anfrage, die Sicherheit...): Die Klasse ist ein
// Service, den die Controller über ihren Konstruktor erhalten.
// =========================================================================

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: der Sicherheits-Service von Symfony, der den Benutzer der
    // aktuellen Anfrage kennt (den vom Authenticator festgestellten)
    public function __construct(
        private RequestStack $requests,
        private Security $security,
        private ApplicationModel $application,
    ) {
    }

    // ————————————————————————————————————————————————————————————————— Daten

    // das Datum, wenn [$text] ein im Format yyyy-mm-dd existierendes Datum ist; sonst null.
    // createFromFormat akzeptiert "2026-02-30" (das zum 2. März wird): Wir
    // prüfen daher, dass das zurückgelesene Datum genau so geschrieben wird wie der empfangene Text
    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": Das Ausrufezeichen setzt die Uhrzeit auf Mitternacht
        $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", je nach Sprache
    // der Anfrage (siehe Beispiel 16). Das ICU-Muster: EEEE der ausgeschriebene Wochentag,
    // d der Tag, MMMM der ausgeschriebene Monat, y das Jahr
    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);
    }

    // ————————————————————————————————————————————————————————————————— Eingaben

    // "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;
    }

    // ————————————————————————————————————————————————————————————————— Benutzer

    // der angemeldete Benutzer. Die geschützten Actions werden nur aufgerufen, wenn er existiert;
    // vorsorglich wird sein Fehlen wie eine abgelaufene Sitzung behandelt
    public function user(): ConnectedUser
    {
        $user = $this->security->getUser();
        return $user instanceof ConnectedUser ? $user : throw new InvalidSession();
    }

    // -----------------------------------------------------------------------
    // Der Patient (Entität Client), der dem angemeldeten Benutzer entspricht.
    //
    // Das JWT-Token enthält nur die id des KONTOS (users.id). Für eine Rolle USER
    // finden wir den passenden Client über die Spalte clients.user.
    //
    // Gibt es keinen, bedeutet das, dass das Konto seit dem Login gelöscht wurde,
    // während sein Token noch gültig ist: Wir behandeln es wie eine abgelaufene
    // Sitzung (siehe InvalidSession).
    // -----------------------------------------------------------------------
    public function connectedPatient(): Client
    {
        return $this->application->getClientByUserId($this->user()->userId)
            ?? throw new InvalidSession();
    }
}

Einige Hilfsfunktionen. Die statischen Methoden werden ohne Objekt aufgerufen ([Utils::iso($day)]); die anderen benötigen Services: Die Klasse ist daher zugleich ein Service, den die Controller über ihren Konstruktor erhalten.

  • Zeilen 38–46: das Datum eines Parameters [yyyy-mm-dd] oder [null]. Zwei Prüfungen: das Format (ein regulärer Ausdruck), dann die Existenz des Datums. [createFromFormat] ist tolerant: Der 30. Februar wird zum 2. März. Wir lesen daher das resultierende Datum erneut aus und prüfen, ob es genau so geschrieben wird wie der empfangene Text. Das [!] im Format setzt die Uhrzeit auf Mitternacht (ohne es wäre es die aktuelle Uhrzeit). [mixed]: ein beliebiger Typ;
  • Zeilen 56–61: „Saturday 26 September 2026“ oder „samedi 26 septembre 2026“, je nach Sprache des Requests. [IntlDateFormatter] (Beispiel 16) mit einem Pattern statt eines Stils: Die Codes stammen aus der ICU-Bibliothek, [EEEE] für den ausgeschriebenen Wochentag, [d] für den Tag, [MMMM] für den ausgeschriebenen Monat und [y] für das Jahr. Der Parameter [pattern] wird per Namen übergeben: Die ihm in der Signatur vorangehenden Parameter, für die kein Wert angegeben wird, behalten ihre Standardwerte;
  • Zeilen 66–73: Ein Request-Parameter kann ein String sein, etwa [null], oder sogar ein Array ([?doctorId[]=1], Beispiel 10). Es werden nur Ziffern akzeptiert (bis zu neun, um einen Überlauf zu vermeiden), und die Zahl muss streng positiv sein;
  • Zeilen 79–83: der angemeldete Benutzer, ermittelt vom Authenticator, der vom [Security]-Service von [Symfony] geliefert wird. Geschützte Aktionen werden nur für einen authentifizierten Benutzer aufgerufen, dennoch wird das Fehlen des Benutzers wie eine abgelaufene Session behandelt. [throw] ist ein Ausdruck ([PHP] 8): Er kann im Operator [? :] stehen;
  • Zeilen 95–99: der Patient (der [Client]) des angemeldeten Benutzers. Das Token enthält nur die Konto-ID; der Client wird über die Spalte [clients.user] identifiziert. Existiert er nicht, wurde das Konto seit der Anmeldung des Benutzers gelöscht: [InvalidSession].

11.15.5. src/Twig/ViewsExtension.php

<?php
// =========================================================================
// src/Twig/ViewsExtension.php: eine Twig-Erweiterung (siehe Beispiel 16), die den
// Views die Funktionen hinzufügt, die ALLE Seiten brauchen:
//   - user()   : der angemeldete Benutzer (oder null), für die Navigationsleiste;
//   - titles() : die möglichen Anreden einer Person (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),
        ];
    }

    // -----------------------------------------------------------------------
    // der von der Firewall festgestellte Benutzer. Eine Fehlerseite 404 oder 405 wird
    // VOR der Firewall aufgebaut (das Routing, das scheitert, kommt vor ihr, siehe
    // Beispiel 24): Der Benutzer wird dann direkt aus dem Token gelesen, damit
    // die Navigationsleiste der Fehlerseite vollständig ist
    // -----------------------------------------------------------------------
    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;
    }
}

Eine Erweiterung von [Twig] (Beispiel 16), die den Views zwei Funktionen hinzufügt, die alle Seiten benötigen:

  • [user()]: der angemeldete Benutzer oder [null], für die Navigationsleiste. Normalerweise stammt er aus dem [Security]-Service (Zeile 44). Eine 404- oder 405-Fehlerseite wird jedoch erzeugt, bevor die Firewall den Request geprüft hat: Das fehlschlagende Routing kommt ihr zuvor (Beispiel 24). Der Benutzer wird dann direkt aus dem Token abgerufen (Zeilen 48–49), damit die Navigationsleiste der Fehlerseite vollständig ist. [getMainRequest] liefert den Hauptrequest; der Operator [?->] gibt [null] zurück, ohne die Methode aufzurufen, wenn das Objekt [null] ist;
  • [titles()]: die möglichen Anreden einer Person ([Mr], [Mme], [Melle]), eine Konstante in der Formularklasse der Person (siehe unten).

[$this->user(...)] (Zeile 31) ist die Syntax für First-Class-Funktionen ([PHP] 8.1): Sie erzeugt eine Funktion, die die Methode [user] dieses Objekts aufruft. Die Erweiterung wird automatisch als [Twig]-Erweiterung deklariert, genau wie in Beispiel 16: Der Container erkennt eine Klasse, die von [AbstractExtension] erbt.

11.16. Wörterbücher

Die Texte der Oberfläche sind dieselben wie in den anderen Versionen der Anwendung, die sie in verschachtelten JSON-Dateien speicherten:

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

Die [Flask]-Version „flachte“ sie beim Start ab: [LOGIN.TITLE] verwies auf den Text [Login]. Die YAML-Wörterbücher von [Symfony] tun dasselbe (Beispiel 22): Verschachtelte Schlüssel werden durch Punkte getrennt. Wir haben daher die JSON-Dateien einfach in YAML umgewandelt und die Parameter [{{name}}] der anderen Versionen durch die der ICU-Syntax ersetzt, [{name}] (das Suffix [+intl-icu] in den Dateinamen, Beispiel 22):

1
2
3
4
5
6
7
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}}.'

Die Dateien [translations/messages+intl-icu.fr.yaml] und [messages+intl-icu.en.yaml] werden hier nicht wiedergegeben. Ein Schlüssel wird in einer View durch [{{ 'APP.LOGOUT'|trans }}] dargestellt, ein parametrisierter Text durch [{{ 'DOCTORS.ADDED'|trans({name: ..., login: ...}) }}]. Ein im Wörterbuch fehlender Schlüssel wird unverändert angezeigt, was ein Versäumnis sofort sichtbar macht (und der Befehl [php bin/console debug:translation fr] listet die von den Views verwendeten Schlüssel auf, die im Wörterbuch fehlen). ICU ermöglicht etwas, das frühere Versionen nicht konnten: den Plural („1 minute“, „15 minutes“) mit dem Format [plural] (Beispiel 22). Ein Texteintrag wurde hinzugefügt: [ERRORS.PAGE_EXPIRED], die Meldung der Seite 419, die in den anderen Versionen nicht vorhanden ist.

Auch die Fehlermeldungen der Formulare sind Schlüssel in diesen Wörterbüchern ([ERRORS.FIRSTNAME_REQUIRED] ...): Die Validierungskomponente übersetzt sie in der Domain [messages] mithilfe der Zeile [translation_domain: messages] aus [framework.yaml]. Ihre Parameter entsprechen den Constraints: [{limit}] für die Mindestlänge des Passworts.

11.17. Formulare

Die „Person“-Formulare sind Formulare der Form-Komponente (Beispiele 18 und 19): Eine Type-Klasse beschreibt die Felder und ihre Constraints; die Aktion erstellt das Formular ([createForm]), übergibt ihm den Request ([handleRequest]) und prüft dann, ob es abgeschickt wurde und gültig ist ([isSubmitted], [isValid]). Ein ungültiges Formular wird erneut angezeigt, mit den Eingaben des Benutzers und den Fehlermeldungen unter den Feldern (ausgenommen Passwörter: Ein [PasswordType]-Feld wird nie erneut angezeigt). Das Anti-CSRF-Token jedes Formulars wird von der Komponente selbst geprüft.

11.17.1. src/Form/PersonFieldsType.php

<?php
// =========================================================================
// src/Form/PersonFieldsType.php: die Felder der Formulare "Person" und ihre
// Constraints (siehe Beispiele 18 und 19). Drei Formulare teilen dieselben
// Identitätsfelder (Anrede, Vorname, Nachname):
//
//   PersonFieldsType            Anrede, Vorname, Nachname
//    ├─ PersonType              + OPTIONALES Login / Passwort, Version
//    │                            (der ADMIN fügt einen Arzt / Client hinzu oder ändert ihn)
//    ├─ RegistrationType        + ERFORDERLICHES Login / Passwort / Bestätigung
//    │                            (ein Patient erstellt sein Konto)
//    └─ MyAccountType           + Login, optionales neues Passwort, ERFORDERLICHES
//                                 AKTUELLES Passwort, Version
//                                 (ein Patient ändert sein Konto)
//
// Die Kindklassen ERBEN von dieser (im Sinne von PHP): Ihr buildForm ruft zuerst
// das der Elternklasse auf und fügt dann ihre Felder hinzu.
//
// Die Formulare haben keine Datenklasse (data_class, siehe Beispiel 19): Die
// validierte Eingabe ist ein assoziatives Array, das die Methode data() in
// PersonData für die Geschäftsschicht umwandelt.
//
// Die Labels, die Hilfetexte und die Fehlermeldungen sind SCHLÜSSEL der
// Wörterbücher: Die Form-Komponente übersetzt die Labels und die Hilfetexte, die
// Validator-Komponente die Meldungen (siehe config/packages/framework.yaml).
// Sequenziell: Die Constraints werden der Reihe nach geprüft, und die Prüfung
// endet bei der ersten, die nicht erfüllt ist - nur eine Meldung pro Feld.
// Die Maximallängen entsprechen denen der SQL-Spalten.
// =========================================================================

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: Kleinbuchstaben, Ziffern, Punkt, Bindestrich, Unterstrich - höchstens 30 Zeichen
    public const LOGIN_FORMAT = '/^[a-z0-9._-]{1,30}$/';

    // Mindestlänge eines von einem Patienten GEWÄHLTEN Passworts
    public const PASSWORD_MIN = 6;

    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            // array_combine: ['Mr' => 'Mr', ...], das Label und der Wert jeder
            // Option; choice_translation_domain false: Die Anreden werden nicht übersetzt
            ->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'),
                ])],
            ]);
    }

    // die gemeinsamen Optionen: Ein ungültiges Formular wird unverändert an den Browser zurückgesendet,
    // ohne Validierung durch den Browser selbst (siehe Beispiel 19: Der SERVER
    // ist maßgeblich); die Meldung bei einem falschen Anti-CSRF-Token
    public function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->setDefaults([
            'attr' => ['novalidate' => 'novalidate'],
            'csrf_message' => 'ERRORS.PAGE_EXPIRED',
        ]);
    }

    // -----------------------------------------------------------------------
    // das Login-Feld, den Kindformularen gemeinsam. Ein Login steht immer in
    // Kleinbuchstaben: Ein TRANSFORMER (CallbackTransformer) wandelt die Eingabe VOR
    // ihrer Validierung um. Seine erste Funktion wandelt den Wert des Formulars in
    // angezeigten Text um (hier ist nichts zu tun), die zweite die Eingabe in den Wert des Formulars
    // -----------------------------------------------------------------------
    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)));
    }

    // die validierte Eingabe -> die von der Geschäftsschicht erwarteten Daten. Die leeren
    // Felder sind null (die Form-Komponente wandelt sie so um)
    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);
    }
}

Drei Formulare teilen sich dieselben Identitätsfelder (Anrede, Vorname, Nachname): das Administratorformular (für einen Arzt oder einen Client), das Formular zur Erstellung eines Patientenkontos und „Mein Konto verwalten“. Ihre gemeinsame Elternklasse ist abstrakt; jede ihrer Kindklassen erweitert diese Felder. Keines dieser Formulare hat eine Datenklasse (die Option [data_class] aus Beispiel 19): Ihre Daten bestehen aus einem assoziativen Array mit einem Element pro Feld.

  • Zeilen 44–50: die Eingaberegeln in Form von Konstanten, die auch von den Views gelesen werden (die Liste der Anreden über die Funktion [titles()] der [Twig]-Erweiterung);
  • Zeilen 57–63: die Anrede, eine Liste ([ChoiceType], Beispiel 18). [array_combine] erzeugt das Array [['Mr' => 'Mr', ...]]: das Label jeder Option und ihren Wert. [choice_translation_domain: false]: Die Anreden sind keine Übersetzungsschlüssel. [invalid_message]: Die Meldung für einen Wert, der nicht zur Liste gehört (ein manuell konstruierter Request);
  • Zeilen 64–79: Vorname und Nachname. Der Constraint [Sequentially] (Beispiel 09) prüft seine Constraints der Reihe nach und stoppt beim ersten nicht erfüllten: nur eine Meldung pro Feld. [Length(max: 20)]: maximal 20 Zeichen; die Spaltenlänge ist SQL; das HTML-Attribut [maxlength] verhindert die Eingabe weiterer Zeichen. Leerzeichen am Anfang und Ende einer Eingabe werden von der Form-Komponente selbst entfernt (die Option [trim] eines Textfelds steht auf [true]), und eine leere Eingabe wird zu [null]; ein Feld mit der Option [PasswordType] wird dagegen nicht bereinigt: Leerzeichen können Teil eines Passworts sein;
  • Zeilen 85–91: gemeinsame Optionen. [novalidate] deaktiviert beim Absenden des Formulars die Browser-Validierungen ([required], [maxlength] ...): Der Server führt die Validierung durch, und deren Ergebnis ist endgültig (Beispiel 19). [csrf_message]: die Meldung für ein ungültiges Anti-CSRF-Token, die der 419-Seite;
  • Zeilen 99–106: der Login, den alle drei Formulare gemeinsam haben und dem jedes seine eigenen Optionen hinzufügt (der Operator [...] fügt die Elemente eines Arrays einem anderen hinzu; ein in beiden vorhandener Schlüssel erhält den letzten Wert). Ein Login steht immer in Kleinbuchstaben: Ein Transformer wandelt die Eingabe um, bevor sie validiert wird. Ein Model-Transformer ([addModelTransformer]) hat zwei Funktionen: Die erste wandelt die Formulardaten in einen angezeigten Wert um (hier ist keine Aktion erforderlich), die zweite wandelt den eingegebenen Wert in Formulardaten um. [CallbackTransformer] erzeugt einen Transformer auf Basis dieser beiden Funktionen;
  • Zeilen 110–116: Die validierte Eingabe wird für die Geschäftsschicht in [PersonData] umgewandelt: Die Geschäftsschicht kennt die Formulare nicht. Ein leeres Passwort ist [null] (unverändert oder der Standardwert); die Version (das versteckte Feld der optimistischen Sperre, z. B. 28) ist eine Ganzzahl oder [null].

11.17.2. src/Form/PersonType.php, RegistrationType.php, MyAccountType.php

<?php
// src/Form/PersonType.php: das Formular eines Arztes oder eines Clients (ADMIN):
// OPTIONALES Login und Passwort (siehe 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'];
        // ein leeres Feld wird akzeptiert: Die Constraints gelten nur für einen eingegebenen Wert
        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'],
            // höchstens 72 Zeichen: Darüber hinaus ignoriert bcrypt den Rest
            'constraints' => [new Assert\Length(max: 72, maxMessage: 'ERRORS.PASSWORD_TOO_LONG')],
        ]);
        // Ändern: die Version des angezeigten Datensatzes in einem versteckten Feld (das
        // optimistische Sperren)
        if (! $creation) {
            $builder->add('version', HiddenType::class);
        }
    }

    // eine eigene Option (siehe Beispiel 28): Formular zum Anlegen oder zum Ändern
    public function configureOptions(OptionsResolver $resolver): void
    {
        parent::configureOptions($resolver);
        $resolver->setDefaults(['creation' => true]);
    }
}

Das Administratorformular. [parent::buildForm] (Zeile 17) fügt die Felder der Elternklasse hinzu; danach folgen Benutzername und Passwort, die optional sind: Ein Constraint gilt nur für einen eingegebenen Wert (außer [NotBlank]), sodass ein leeres Feld akzeptiert wird. [Regex] validiert das Login-Format; [Length(max: 72)] begrenzt die Passwortlänge: [bcrypt] berücksichtigt nur die ersten 72 Bytes (Beispiel 25). Die Option [creation] (Zeilen 40–44), eine von uns entworfene Option, die mit ihrem Standardwert deklariert wird (Beispiel 28), unterscheidet zwischen Erstellung und Änderung: Die Tooltips unterscheiden sich („Optional: Standardmäßig der Nachname in Kleinbuchstaben“, „Leer lassen, um es unverändert zu lassen“), und nur die Änderung hat das versteckte Versionsfeld.

<?php
// src/Form/RegistrationType.php: "Patientenkonto erstellen": ERFORDERLICHES Login, Passwort und
// Bestätigung.

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

    // -----------------------------------------------------------------------
    // das Passwort und seine Bestätigung: ein REPEATED-Feld (siehe Beispiel 19), dessen
    // beide Eingaben identisch sein müssen (andernfalls: invalid_message). Gemeinsam für
    // die Registrierung (erforderlich) und das Konto des Patienten (optional).
    // {limit}: in der Meldung PASSWORD_TOO_SHORT die Mindestlänge;
    // help_translation_parameters: die Parameter des Hilfetexts
    // -----------------------------------------------------------------------
    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],
        ];
    }
}

Erstellung eines Patientenkontos: Login und Passwort sind erforderlich, und das Passwort muss bestätigt werden. Das Passwort ist ein wiederholtes Feld ([RepeatedType], Beispiel 19): zwei [PasswordType]-Felder, deren Eingaben identisch sein müssen (andernfalls wird die Meldung [invalid_message] unter dem ersten Feld angezeigt). Ihre Optionen werden von einer statischen Methode erzeugt, die mit „Mein Konto verwalten“ geteilt wird (Zeilen 36–55):

  • [first_options] und [second_options]: die Optionen der beiden Felder; [options]: die Optionen, die sie gemeinsam haben;
  • [help_translation_parameters]: die Parameter für den Hilfetext „Mindestens {min} Zeichen.“;
  • die Mindestlänge wird nur für das von einem Patienten gewählte Passwort verlangt (6 Zeichen). Die Meldung [ERRORS.PASSWORD_TOO_SHORT] enthält [{limit}], den Parameter, den der Constraint [Length] seiner Meldung übergibt;
  • [autocomplete="new-password"]: Der Browser bietet an, ein Passwort zu generieren, anstatt das Feld mit dem gespeicherten Passwort auszufüllen.
<?php
// src/Form/MyAccountType.php: "Mein Konto verwalten" (ein Patient): erforderliches Login,
// optionales neues Passwort, ERFORDERLICHES AKTUELLES Passwort.

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'),
            ])],
        ]);
        // optional: leer = Passwort unverändert
        $builder->add('password', RepeatedType::class, RegistrationType::repeatedPassword(false));
        // das AKTUELLE Passwort, für jede Änderung des Kontos erforderlich; mapped
        // false: Es gehört nicht zu den Daten des Formulars, es wird separat gelesen
        $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);
    }
}

„Mein Konto verwalten“: Das neue Passwort ist optional (leer: unverändert), das aktuelle Passwort ist erforderlich. [mapped: false] (Zeile 33): Das aktuelle Passwort gehört nicht zu den Formulardaten ([getData()] enthält es nicht); die Aktion liest es separat über [$form->get('current_password')->getData()]. Es wird hier nicht validiert, sondern von der Aktion: Ein falsches Passwort muss vom Versuchsbegrenzer als fehlgeschlagene Anmeldung gezählt werden. ([Symfony] hat einen Constraint, [UserPassword], der das eingegebene Passwort mit dem des angemeldeten Benutzers vergleicht; dieser Constraint ist hier nicht anwendbar: Unser angemeldeter Benutzer, [ConnectedUser], enthält nicht den Hash seines Passworts.)

11.18. View-Templates

Der Ordner [src/Views] enthält die View-Templates: von einer Aktion erzeugte Objekte, die die View einfach nur liest. Die Regel, der alle Seiten folgen: keine Logik in den Views. Die Aktionen bereiten bereits formatierte Daten („Ms. Marie PELISSIER“, „8:00 – 8:20“) vor, die bereits nach der Rolle des Benutzers gefiltert sind; die Views setzen diese Daten ins HTML ein. Alle diese Klassen sind vom Typ [readonly] und haben nur Eigenschaften, die von ihrem Konstruktor initialisiert werden. Der Ordner ist von den Services ausgenommen ([config/services.yaml]): Es handelt sich um Daten, nicht um Services.

<?php
// src/Views/OptionView.php: eine Option einer Dropdown-Liste (Arzt, Patient).
//
// Der Ordner src/Views enthält die "View Models": Objekte, die
// eine Action in einem Zug aufbaut und die die View nur liest. Regel,
// der alle Seiten folgen: keine Logik in den Views. Die Actions
// bereiten BEREITS formatierte Daten ("Mme Marie PELISSIER",
// "8:00 - 8:20", selected = true...) vor, die bereits nach der Rolle
// des Benutzers gefiltert sind; die Views setzen sie nur noch in das HTML ein.

namespace App\Views;

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

Eine Option in einer Dropdown-Liste: die ID, das Label und ob die Option ausgewählt ist.

<?php
// src/Views/ScheduleRow.php: eine Zeile des angezeigten Terminkalenders (ein Zeitfenster).

namespace App\Views;

readonly class ScheduleRow
{
    public function __construct(
        public int $slotId,
        public string $time,         // "8:00 - 8:20"
        public bool $free,
        // angezeigter Name für ein belegtes Zeitfenster; null = "Booked"
        public ?string $patient,
        public bool $mine,           // der Termin des angemeldeten Patienten
        public bool $bookable,       // Schaltfläche "Book" anzeigen?
        public string $bookUrl,
        // nur gesetzt, wenn die Schaltfläche "Cancel" angezeigt wird
        public ?int $appointmentId,
    ) {
    }
}

Ein Kalendereintrag: ein Zeitfenster und das, was der angemeldete Benutzer dazu sehen und tun darf. [patient] wird nur gefüllt, wenn der Benutzer den Namen des Patienten sehen darf; [bookable] gibt an, ob die Schaltfläche „Buchen“ angezeigt werden soll; [appointmentId] gibt an, ob die Schaltfläche „Stornieren“ angezeigt werden soll.

<?php
// src/Views/ScheduleView.php: der angezeigte Terminkalender: der Arzt, der Tag, die Zeilen.

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: der Buchungsdialog eines Zeitfensters.

namespace App\Views;

readonly class BookingView
{
    /** @param list<OptionView> $clients */
    public function __construct(
        public int $slotId,
        public string $time,
        // ADMIN / DOCTOR: die Patienten zur Auswahl
        public array $clients,
        // USER: der Patient ist er selbst
        public ?string $patient,
    ) {
    }
}

Der angezeigte Kalender und das Buchungsfenster: für den Administrator und die Ärzte die Liste der auswählbaren Patienten, für einen Patienten sein eigener Name. Der Kommentar [/** @param list<ScheduleRow> $rows */] gibt für Editoren und Analysewerkzeuge den Inhalt des Arrays an: [PHP] kann nur den Typ [array] deklarieren.

<?php
// src/Views/PersonKeys.php: die für jede Art von Person (Ärzte oder Clients) spezifischen
// Übersetzungsschlüssel für die gemeinsamen Views persons/list und
// 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,
    ) {
    }

    // die acht Schlüssel eines Abschnitts des Wörterbuchs ("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");
    }
}

Übersetzungsschlüssel speziell für Ärzte oder Clients, für die beiden Views, die sie gemeinsam haben. Die statische Methode [of] (Zeilen 23–27) erzeugt die acht Schlüssel eines Abschnitts der Wörterbücher: [PersonKeys::of('DOCTORS')] ergibt [DOCTORS.TITLE], [DOCTORS.ADD] ... [new self(...)] erzeugt ein Objekt der Klasse selbst.

<?php
// src/Views/AppointmentView.php: ein bevorstehender Termin im Bereich des Patienten.

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,  // der Terminkalender des Arztes an diesem Tag
    ) {
    }
}

Ein bevorstehender Termin im Patientenbereich.

11.19. Die Web-Schicht: Routen und Controller

11.19.1. Routen

Routen werden durch die [#[Route]]-Attribute der Controller beschrieben (Beispiel 02), die von der Datei [config/routes.yaml] geladen werden. Der Befehl [debug:router] listet sie alle samt Namen, Methoden und Pfaden auf:

$ 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
 --------------------- ---------- ----------------------

Die URLs entsprechen denen der anderen Versionen der Anwendung: Das Ändern und Löschen eines Arztes sind POST-Requests ([/doctors/{id}/edit], [/doctors/{id}/delete]), nicht PUT und DELETE wie in Beispiel 28. Der Code erzeugt die URL stets anhand der Routennamen ([redirectToRoute('login')], [path('schedule')] in den Views, Beispiel 04): Um eine URL zu ändern, muss nur ihr [#[Route]]-Attribut angepasst werden.

Zugriffsregeln stehen nicht in den Controllern, sondern in den [access_control]-Regeln von [config/packages/security.yaml], wie oben gezeigt: eine Regel pro URL-Präfix ([^/(doctors|clients)] für den Administrator, [^/my-] für Patienten ...) und eine abschließende Regel, die für alle übrigen URLs einen authentifizierten Benutzer verlangt. Die URL-Pfade der Anwendung wurden zu diesem Zweck gewählt: Alle Seiten derselben Rolle beginnen gleich. Ein URL-Pfad, der zu keiner Route passt, liefert eine 404-Seite, selbst für einen anonymen Besucher; ein GET-Request an eine URL, die nur als POST existiert ([/logout]), führt zu einer 405-Seite, die als „Seite nicht gefunden“ dargestellt wird (Handler [ErrorPage]).

11.19.2. src/Controller/LanguageController.php

<?php
// =========================================================================
// src/Controller/LanguageController.php: GET /language/fr, GET /language/en: die beiden
// Schaltflächen FR / EN der Navigationsleiste. Öffentliche Route: Man muss die Sprache
// vor dem Login wechseln können.
//
// Die Wahl wird in einem Cookie gespeichert: Bei jeder folgenden Anfrage liest der Listener
// SetLanguage es erneut und setzt die Sprache der Anfrage. Dann geht es zurück zu der
// Seite, von der wir kamen (siehe Beispiel 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} ist auf die unterstützten Sprachen beschränkt (requirements): /language/de ergibt eine Seite 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;
    }

    // -----------------------------------------------------------------------
    // die vorherige Seite, gemäß dem HTTP-Header "Referer", den der Browser sendet.
    // Nur ihr Pfad wird behalten (/schedule?...): Eine Weiterleitung auf eine vollständige
    // Adresse, die von der Anfrage geliefert wird, würde es erlauben, den Benutzer auf
    // eine andere Website zu schicken (sogenannte "Open-Redirect"-Schwachstelle).
    // -----------------------------------------------------------------------
    private function originPage(Request $request): string
    {
        $referer = $request->headers->get('Referer');
        $url = $referer ? parse_url($referer) : false;
        $path = $url['path'] ?? '';
        // "//site.com/..." würde vom Browser als Adresse auf einer
        // ANDEREN Website verstanden: ebenfalls abgelehnt
        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;
    }
}

Die Schaltflächen FR / EN in der Navigationsleiste: Die Sprachauswahl wird ein Jahr lang in einem Cookie gespeichert (Beispiel 22), dann kehrt der Browser zur Seite zurück, von der er kam. Das Cookie ist [HttpOnly]: Das [JavaScript] der Seite muss es nicht lesen. Es ist nicht signiert: Der Listener [SetLanguage] prüft seinen Wert, und ein unbekannter Wert führt zu Englisch (siehe das Kapitel über die Bereiche).

  • Zeile 29: [requirements: ['code' => 'fr|en']] akzeptiert für den Parameter [{code}] nur diese beiden Werte: [/language/de] entspricht keiner Route (404-Seite);
  • Zeilen 47–59: Die vorherige Seite wird durch den Header HTTP ***[Referer] angegeben, den der Browser mit dem Request sendet. Diese Angabe stammt vom Client und ist daher verdächtig: Eine Weiterleitung auf eine vollständige URL aus dem Request würde es einem Angreifer erlauben, den Benutzer über einen Link auf [/language/fr] , der einen gefälschten ***[Referer] enthält, auf seine eigene Website zu schicken (die sogenannte „Open-Redirect“-Schwachstelle). Daher behalten wir nur den Pfad und die Parameter ([/schedule?doctorId=1&...]), die von der [parse_url]-Funktion aus [PHP] extrahiert werden, die eine URL in ihre Bestandteile zerlegt ([scheme], [host], [path], [query] ...). Ein Pfad, der mit [//] beginnt, wird ebenfalls abgelehnt: Ein Browser interpretiert [//site.com/page] als Adresse auf einer anderen Website. Schließlich dürfen wir nicht zu [/language/...] zurückkehren: eine Endlosschleife.

11.19.3. src/Controller/ScheduleController.php

<?php
// =========================================================================
// src/Controller/ScheduleController.php: die Terminkalender-Seite: Wahl eines Arztes und
// eines Tages, Terminkalender dieses Arztes an diesem Tag, Buchung und Stornierung von
// Terminen.
//
//   GET  /schedule?doctorId=1&day=2026-09-23               die Seite
//   GET  /schedule?doctorId=1&day=2026-09-23&book=7        dieselbe Seite, mit geöffnetem
//                                                          Buchungsdialog
//                                                          für Zeitfenster 7
//   POST /schedule/book                                    legt einen Termin an
//   POST /schedule/cancel                                  storniert einen Termin
//
// Die gesamte Seite wird durch ihre URL beschrieben: Sie kann neu geladen und als Lesezeichen gespeichert werden,
// die Schaltfläche "Zurück" des Browsers ist nutzbar - ohne eine einzige Zeile
// JavaScript.
//
// Was jeder sieht und tun kann:
//
//   | Rolle         | belegtes Zeitfenster angezeigt    | Book               | Cancel  |
//   |———————————————|———————————————————————————————————|————————————————————|—————————|
//   | ADMIN, DOCTOR | Name des Patienten                | für einen Patienten| ja      |
//   |               |                                   | aus einer Liste    |         |
//   | USER (Patient)| "Booked", oder IHR Name, wenn es  | für sich selbst,   | nein (*)|
//   |               | der eigene Termin ist             | wenn kein bevor-   |         |
//   |               |                                   | stehender existiert|         |
//
//   (*) Der Patient storniert seinen Termin auf seiner Seite "My area".
//
// VERTRAULICHKEIT: Bei einem Patienten wird der Name der ANDEREN Patienten nicht
// einfach von der View ausgeblendet - er wird der View nie übergeben. Das an den Browser
// gesendete HTML enthält ihn daher nicht, auch nicht versteckt (ein einfaches "Seitenquelltext
// anzeigen" würde ihn sonst verraten).
//
// Keine Buchung in der Vergangenheit: Die Schaltfläche "Book" erscheint nur für
// heute und die folgenden Tage (und die Geschäftsschicht würde sie
// ohnehin ablehnen).
//
// Sicherheit: Alle URLs unter /schedule erfordern einen authentifizierten Benutzer, und
// /schedule/cancel die Rolle ADMIN oder DOCTOR (siehe 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
    // Die Parameter der URL werden roh gelesen ($request->query), um einen
    // FEHLENDEN Parameter (null) von einem LEEREN Parameter (?doctorId=) zu unterscheiden.
    // -----------------------------------------------------------------------
    #[Route('', name: 'schedule', methods: ['GET'])]
    public function show(Request $request): Response
    {
        $error = null;
        $user = $this->utils->user();
        $rights = $this->rights();

        // der Tag: der aus der URL, wenn er gültig ist, sonst heute
        $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();

        // der Arzt: der aus der URL; ersatzweise bei einem angemeldeten Arzt er selbst
        $rawDoctorId = $request->query->get('doctorId');
        $doctorId = Utils::positiveInteger($rawDoctorId);
        if ($rawDoctorId === null && $user->role === Role::DOCTOR) {
            $doctorId = $this->application->getDoctorByUserId($user->userId)?->getId();
        }

        // die Dropdown-Liste der Ärzte
        $doctors = array_map(fn (Person $d) => self::option($d, $d->getId() === $doctorId),
            $this->application->getAllDoctors());

        // der Terminkalender, wenn ein Arzt gewählt ist (und das Datum gültig)
        $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);
            }
        }

        // der Buchungsdialog: nur, wenn das angeforderte Zeitfenster von diesem Benutzer
        // gebucht werden kann. array_find: das erste Element, das die
        // Bedingung erfüllt (null, wenn es keines gibt)
        $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,
            // der angezeigte Terminkalender, ohne Buchungsdialog
            'backUrl' => $doctorId !== null ? $this->scheduleUrl($doctorId, $day) : $this->generateUrl('schedule'),
            'info' => $this->patientInfo($rights, $schedule),
        ]);
    }

    // -----------------------------------------------------------------------
    // POST /schedule/book   Felder: doctorId, day, slotId, clientId
    //
    // Für einen Patienten (USER) wird das Feld clientId IGNORIERT: Er bucht immer
    // für sich selbst. Einem vom Browser gesendeten Feld zu vertrauen,
    // würde es einem gerissenen Patienten erlauben, im Namen eines anderen zu buchen.
    //
    // Muster "Post / Redirect / Get": Ganz gleich, wie das Ergebnis ausfällt, hier wird keine Seite aufgebaut
    // - es wird eine Flash-Nachricht hinterlassen und zum Terminkalender umgeleitet
    // (siehe Beispiel 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) {
            // -> Seite "ungültige Anfrage" (siehe 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) {
                // kein Patient gewählt: Der Buchungsdialog wird erneut geöffnet
                $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 {
                // die Regeln (nicht in der Vergangenheit, nur ein bevorstehender Termin pro
                // Patient, freies Zeitfenster) werden von der Geschäftsschicht geprüft
                $this->application->addAppointment($day, $slot, $client);
                $this->flash->success('SCHEDULE.BOOKED');
            } catch (BusinessException $e) {
                // dieselbe Regel, aber eine Nachricht in der 2. Person, wenn der
                // Patient selbst bucht ("You already have..." statt
                // "This patient..."). Die anderen Exceptions (echte Anomalien) werden nicht
                // abgefangen: Seite 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   Felder: appointmentId, doctorId, day
    // (ein Patient storniert SEINEN Termin auf "My area", nicht hier)
    // -----------------------------------------------------------------------
    #[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) {
            // bereits storniert (von jemand anderem oder durch Doppelklick)
            $this->flash->error('ERRORS.APPOINTMENT_NOT_FOUND');
        } else {
            $this->application->deleteAppointment($appointment);
            $this->flash->success('SCHEDULE.CANCELLED');
        }
        return $this->redirect($this->scheduleUrl($doctorId, $day));
    }

    // -----------------------------------------------------------------------
    // Wer ist angemeldet, und was darf er auf dieser Seite tun?
    //   manager: ADMIN oder DOCTOR;
    //   patient: der angemeldete Client (Rolle USER), sonst null;
    //   patientCanBook: ein USER ohne bevorstehenden Termin.
    // -----------------------------------------------------------------------
    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 === []];
    }

    // -----------------------------------------------------------------------
    // der Terminkalender des Arztes, für die View formatiert - und nach den Rechten gefiltert
    // -----------------------------------------------------------------------
    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;
            // der Termin des angemeldeten Patienten?
            $mine = $appointment !== null && $rights['patient'] !== null
                && $appointment->getClient()->getId() === $rights['patient']->getId();
            $rows[] = new ScheduleRow(
                slotId: $slot->getId(),
                time: $slot->time(),
                free: $free,
                // DER Vertraulichkeitspunkt: Ein Patient erhält nur den Namen
                // SEINES Termins; für die anderen null (die View zeigt "Booked" an)
                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);
    }

    // ————————————————————————————————————————————————————————————————— Hilfsfunktionen

    // die versteckten Felder doctorId / day der POST-Formulare; [null, null], wenn sie
    // ungültig sind
    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 hängt an das Ende
    // der URL die Parameter an, die keine Parameter des Pfads sind (siehe Beispiel 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);
    }

    // -----------------------------------------------------------------------
    // die Informationsnachricht für einen Patienten, der bereits einen bevorstehenden Termin hat
    // (warum es keine Schaltfläche "Book" gibt), oder null. Überflüssig, wenn SEIN
    // Termin im angezeigten Terminkalender erscheint (in Blau): Das ist der Fall direkt
    // nachdem er ihn gebucht hat, wenn die Nachricht fehl am Platz wäre.
    // array_any: Erfüllt mindestens ein Element die Bedingung?
    // -----------------------------------------------------------------------
    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';
    }
}

Die Hauptseite der Anwendung. Der Kommentar im Kopf fasst zusammen, was jeder Benutzer sieht und tun kann. Das [#[Route('/schedule')]]-Attribut der Klasse (Zeile 66) legt den Pfadanfang für alle ihre Routen fest (Beispiel 02): Die Route [''] ist [/schedule] selbst.

11.19.3.1. Die URL der Seite

Die gesamte Seite wird durch ihre URL beschrieben: [/schedule?doctorId=1&day=2026-09-26] zeigt den Terminkalender von Arzt 1 für diesen Tag an; [&book=4] öffnet zusätzlich das Buchungsfenster für das Zeitfenster 4. Sie können die Seite neu laden, als Lesezeichen speichern oder die Zurück-Schaltfläche des Browsers verwenden, ohne eine einzige Zeile [JavaScript]. Das Formular oben auf der Seite (zur Auswahl von Arzt und Tag) ist ein GET-Formular (Beispiel 17): Es lädt die Seite mit neuen Parametern. Das Fenster zur Terminbuchung wird durch einen einfachen Link geöffnet und durch einen Link auf dieselbe Seite ohne den Parameter [book] geschlossen.

11.19.3.2. GET /schedule

Zeilen 81–154:

  • die URL-Parameter werden unverändert gelesen ([$request->query->get('day')]), ohne Validierung durch [Symfony]: Ein fehlender Parameter ([null]) ist kein Fehler (standardmäßig gilt heute bzw. „kein Arzt“); ein ungültiges Datum ist ein Fehler, der am Seitenende angezeigt wird (die Auswahl von Arzt und Tag bleibt sichtbar, der Kalender wird jedoch nicht angezeigt); eine Arzt- oder Zeitfensternummer, die keine positive Ganzzahl ist, wird einfach ignoriert;
  • ein angemeldeter Benutzer, der keinen Arzt ausgewählt hat, sieht seinen Terminkalender: Sein Arzt wird über sein Konto abgerufen ([getDoctorByUserId]). [?->getId()]: Der Nullsafe-Operator gibt [null] zurück, wenn das Objekt [null] ist, anstatt einen Fehler auszulösen;
  • die Dropdown-Liste der Ärzte: [array_map] wandelt jeden Arzt in [OptionView] um;
  • der Kalender, formatiert und nach den Berechtigungen des Benutzers gefiltert ([scheduleView], siehe unten);
  • das Buchungsfenster, nur wenn das angeforderte Zeitfenster für diesen Benutzer buchbar ist: Ein Patient, der versucht, die URL [&book=2] für ein bereits gebuchtes Zeitfenster zu erzeugen, erhielte nichts. [array_find] (Beispiel 06) liefert das erste Element eines Arrays, das eine Bedingung erfüllt, oder [null]. Die Patientenliste wird nur dem Administrator und den Ärzten bereitgestellt; ein Patient erhält nur seinen eigenen Namen;
  • die View erhält ihre Variablen ([render], Beispiel 13), darunter [pageTitle] und [error], die vom Template gelesen werden.

11.19.3.3. POST /schedule/book

Zeilen 167–215:

  • das Anti-CSRF-Token, gefolgt von den versteckten Feldern des Buchungsformulars (Arzt, Tag, Zeitfenster). Sind diese ungültig, muss es sich um einen manuell erzeugten Request handeln: [BadRequestHttpException], die Seite „Ungültige Anfrage“ (400);
  • Bei einem Patienten wird das Feld [clientId] ignoriert: Der Patient bucht stets einen Termin für sich selbst ([Utils::connectedPatient]). Sich auf ein vom Browser gesendetes Feld zu verlassen, würde es einem böswilligen Patienten erlauben, eine Reservierung im Namen eines anderen vorzunehmen. Für den Administrator und die Ärzte muss ein Patient ausgewählt worden sein; andernfalls öffnet sich das Buchungsfenster erneut mit einer Meldung;
  • das Zeitfenster muss zu dem auf der Seite angegebenen Arzt gehören;
  • die Geschäftsregeln (nicht in der Vergangenheit, nur ein bevorstehender Termin, verfügbares Zeitfenster) werden von der Geschäftsschicht geprüft. Eine [BusinessException] wird zu einer Flash-Fehlermeldung; ihre öffentlichen Eigenschaften [key] und [params] liefern die Nachricht. Dieselbe Ablehnung – „ein bevorstehender Termin“ – wird für den Patienten selbst in der zweiten Person formuliert („Sie haben bereits ...“). Jede andere Exception wird nicht abgefangen: Das ist ein echter Fehler (500-Seite);
  • in jedem Fall das Post/Redirect/Get-Muster (Beispiel 20): eine Pop-up-Meldung und eine Weiterleitung zum Kalender.

11.19.3.4. POST /schedule/cancel

Zeilen 221–239: Stornierung eines Termins durch den Administrator oder einen Arzt (Regel [^/schedule/cancel$] abgeleitet aus [security.yaml]). Ein Termin, der nicht mehr existiert (bereits von jemand anderem storniert oder durch einen Doppelklick), ist kein Fehler: Es erscheint nur eine Meldung.

11.19.3.5. Berechtigungen, formatierter Kalender und Hilfsfunktionen

  • Zeilen 247–255: was der Benutzer auf der Seite tun darf, in einem assoziativen Array: Ist der Benutzer ein Administrator (ADMIN oder DOCTOR)? Ein Patient (und welcher)? Kann dieser Patient eine Reservierung vornehmen (keine bevorstehenden Termine)?
  • Zeilen 260–285: Der Terminkalender des Arztes, umgewandelt in Zeilen für die View. Der Datenschutzaspekt steht in Zeile 278: Ein Patient sieht nur den Namen, der zu seinem eigenen Termin gehört. Bei den anderen wird die Eigenschaft [patient] auf [null] gesetzt, und die View zeigt „Gebucht“ an. Der Name wird nicht von der View verborgen: Er wird der View nie übergeben und erscheint daher nicht im Quelltext der Seite, wo er leicht zu lesen wäre. Die Schaltfläche „Buchen“ wird für ein freies Zeitfenster an einem Tag angezeigt, der noch nicht vorbei ist, und zwar für einen Administrator oder einen Patienten, der eine Reservierung vornehmen kann; die Schaltfläche „Stornieren“ wird nur Administratoren angezeigt. Die benannten Argumente ([slotId: $slot->getId()]) machen die Konstruktion eines Objekts mit acht Eigenschaften lesbar;
  • Zeilen 291–296: die versteckten Felder der POST-Formulare. [[$doctorId, $day] = ...] (Zeilen 171 und 225) zerlegt das gerenderte Array in zwei Variablen;
  • Zeilen 300–307: die URL für den Terminkalender eines Arztes an einem bestimmten Tag. [generateUrl('schedule', [...])] hängt die Werte, die keine Pfadparameter sind, als Query-Parameter an das Ende der URL an: [/schedule?doctorId=1&day=2026-09-26];
  • Zeilen 321–328: die Meldung, die einem Patienten erklärt, warum es keine Schaltfläche „Buchen“ gibt (er hat bereits einen bevorstehenden Termin), es sei denn, dieser Termin steht im angezeigten Kalender (unmittelbar nach der Buchung würde die Meldung verschoben). [array_any] ([PHP] 8.4): Erfüllt mindestens ein Element die Bedingung?

11.19.4. src/Controller/PersonsController.php

<?php
// =========================================================================
// src/Controller/PersonsController.php: Die Verwaltung der Ärzte und die der
// Clients (dem ADMIN vorbehalten) sind IDENTISCH: gleiche Liste, gleiches Formular,
// gleiche Regeln. Statt dieselben Actions zweimal zu schreiben, schreiben wir sie
// einmal in dieser ABSTRAKTEN Klasse; DoctorsController und ClientsController
// erben von ihr und legen nur fest, was sie unterscheidet: den Namen des Abschnitts
// (Ärzte oder Clients), die Übersetzungsschlüssel und die Methoden
// des ApplicationModel, die aufzurufen sind.
//
// Auch die #[Route]-Attribute der Actions werden vererbt: Das #[Route]-Attribut
// JEDER Kindklasse gibt ihnen den Anfang ihres Pfads (/doctors oder
// /clients) und ihres Namens (doctors_ oder clients_). So erhalten wir für jede:
//
//   GET  /doctors                    Liste                     doctors_list
//   GET  /doctors/add                leeres Formular           doctors_add
//   POST /doctors/add                Anlegen                   doctors_add
//   GET  /doctors/{id}/edit          vorausgefülltes Formular  doctors_edit
//   POST /doctors/{id}/edit          Ändern                    doctors_edit
//   POST /doctors/{id}/delete        Löschen                   doctors_delete
//
// (und dieselben URLs unter /clients). Auch die Views sind gemeinsam:
// templates/persons/list.html.twig und persons/form.html.twig.
//
// SICHERHEIT: Die Regel access_control ^/(doctors|clients) von
// config/packages/security.yaml reserviert alle diese URLs für den ADMIN - auch solche,
// die später hinzukommen würden.
// =========================================================================

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
{
    // die von jedem "Eingabe"-Geschäftsfehler (einem Duplikat) betroffenen Formularfelder: Sie werden
    // rot umrandet, die Nachricht steht unten auf der Seite
    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)
    {
    }

    // ———— was jede Art von Person liefern muss

    // "doctors" oder "clients": der Anfang der Namen der Routen
    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 (oder /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: das leere Formular; POST: das Anlegen
    // -------------------------------------------------------------------
    #[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: das vorausgefüllte Formular; POST: das Ändern.
    // {id<\d+>}: ein aus Ziffern bestehender Parameter (siehe Beispiel 02):
    // /doctors/abc/edit passt auf keine Route (Seite 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();
        // das Formular, vorausgefüllt mit den Werten der Person (das
        // Passwort dagegen wird nie angezeigt)
        $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
    // (die Bestätigung "Are you sure?" wird vor dem Absenden des Formulars abgefragt,
    // siehe 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');
    }

    // ————————————————————————————————————————————————————————————————— interne Funktionen

    // $person null: Formular zum Anlegen; andernfalls: Formular zum Ändern.
    // Ein abgelehntes Formular (ungültige Eingabe oder Geschäftsregel): der Code 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));
    }

    // eine Geschäftsregel hat das Schreiben abgelehnt: Das Formular wird erneut angezeigt, mit
    // der Eingabe des Benutzers (ohne das Passwort), der Nachricht der Geschäftsschicht
    // (unten auf der Seite) und gegebenenfalls den betroffenen Feldern, rot
    // umrandet, damit der Benutzer sofort sieht, was zu korrigieren ist
    private function businessError(BusinessException $e, FormInterface $form, ?Person $person): Response
    {
        if (in_array($e->key, ['ERRORS.DOCTOR_NOT_FOUND', 'ERRORS.PATIENT_NOT_FOUND'], true)) {
            // in der Zwischenzeit von einem anderen ADMIN gelöscht: zurück zur Liste
            $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} und {login} der Nachrichten "added / updated / deleted"
    private static function params(?Person $person): array
    {
        return $person === null ? ['name' => '', 'login' => '']
            : ['name' => "{$person->getFirstName()} {$person->getLastName()}",
                'login' => $person->getAccount()->getLogin()];
    }
}

Die Verwaltung von Ärzten und Clients ist identisch: dieselbe Liste, dasselbe Formular, dieselben Regeln. Die Aktionen werden einmal in einer abstrakten Klasse geschrieben; [DoctorsController] und [ClientsController] erben von ihr. Jeder muss liefern, was ihn auszeichnet: Das ist die Aufgabe der abstrakten Methoden in den Zeilen 64–77, die ohne Code deklariert sind; eine Kindklasse, die sie nicht implementiert, würde von [PHP] abgelehnt. Dies ist das Entwurfsmuster, das als „Template Method“ bekannt ist: Die Elternklasse definiert den Algorithmus, die Kindklassen liefern die Details.

Auch die [#[Route]]-Attribute der Aktionen werden vererbt. [Symfony] ignoriert die abstrakte Klasse, untersucht aber die Methoden jeder Kindklasse, einschließlich der geerbten; das [#[Route]]-Attribut der Kindklasse legt den Anfang ihres Pfads und Namens fest: Die Aktion [list] wird zu den Routen [doctors_list] ([/doctors]) und [clients_list] ([/clients]). Um der Arzt-oder Client-Verwaltung eine Aktion hinzuzufügen, genügt es, sie hier zu schreiben.

  • Zeilen 51–55: die Felder, die von jedem Eingabefehler der Geschäftsschicht betroffen sind: Ein doppeltes Login betrifft das Feld „Login“; eine Namensübereinstimmung betrifft die Felder „Vorname“ und „Nachname“. Diese Felder werden rot hervorgehoben;
  • Zeile 57: der Konstruktor, der von den Kindklassen geerbt wird. Seine Eigenschaften sind [protected]: für die Kindklassen sichtbar;
  • Zeilen 82–87: die Liste. Diese View ist beiden Bereichen gemeinsam: Sie erhält die Übersetzungsschlüssel des Bereichs ([keys]) und seinen Namen ([section]), der zur Erzeugung der Routennamen dient ([section ~ '_add'] in der View);
  • Zeilen 92–107: Hinzufügen. Eine einzige Aktion für GET (das leere Formular mit ausgewählter Anrede [Mr] ) und POST (Erstellung), wie in Beispiel 19. Eine ungültige Eingabe lädt das Formular neu. Eine gültige Eingabe geht an die Geschäftsschicht, die den Schreibvorgang ablehnen kann (z. B. wegen eines Namensvetters oder eines bereits vergebenen Logins); andernfalls erscheint eine Erfolgsmeldung, und der Benutzer kehrt zur Liste zurück (PRG-Schema);
  • Zeilen 114–136: die Aktualisierung einer bestehenden Person: [?? throw $this->createNotFoundException()] (die 404-Seite; [throw] ist ein Ausdruck, der rechts von [??] verwendet werden kann). [{id<\d+>}] (Zeile 114) akzeptiert für den Parameter [{id}] nur Ziffern (Beispiel: 02). Das Formular wird mit den Werten der Person und ihrer Version vorausgefüllt; [handleRequest] ersetzt sie bei einem POST durch die eingegebenen Daten;
  • Zeilen 143–155: Löschen. Das Formular forderte im Browser eine Bestätigung an (Beispiel 21). Die Daten der Person werden vor dem Löschen abgerufen, um die Erfolgsmeldung zu erzeugen („Arzt Paul TATOU wurde gelöscht.“);
  • Zeilen 161–173: das Formular, entweder für die Erstellung ([$person] ist gleich [null]) oder für die Änderung. Ein abgelehntes Formular (ungültige Eingabe oder Verletzung einer Geschäftsregel) wird mit dem Statuscode 422 zurückgegeben (Beispiel 19). Die View erhält das Formular selbst ([render] wandelt es in eine „Form-View“ um, Beispiel 18);
  • Zeilen 179–188: Die Geschäftsschicht hat den Schreibvorgang abgelehnt. Wurde eine Person inzwischen gelöscht (von einem anderen Administrator), wird der Benutzer zur Liste zurückgeführt. Andernfalls wird das Formular direkt (ohne Weiterleitung) erneut angezeigt, wie bei einem Eingabefehler: Es enthält bereits die Eingaben des Benutzers. Hinzu kommen die Meldung der Geschäftsschicht (am Seitenende im Fehlerbereich angezeigt) und die rot hervorzuhebenden Felder. Beachten Sie, dass der Entity-Manager nach der Exception geschlossen ist (von der Geschäftsschicht, wie oben erwähnt): Die Aktion zeigt jetzt nur noch an;
  • Zeilen 191–196: die Parameter [{name}] und [{login}] für die Erfolgsmeldungen.

11.19.5. src/Controller/DoctorsController.php und ClientsController.php

<?php
// src/Controller/DoctorsController.php: die Verwaltung der Ärzte (nur Rolle
// ADMIN). Alle Actions werden von PersonsController geschrieben: Hier bleibt nur noch
// zu sagen, WAS aufzurufen ist und WELCHE Labels anzuzeigen sind.

namespace App\Controller;

use App\Entity\Person;
use App\Business\PersonData;
use App\Views\PersonKeys;
use Symfony\Component\Routing\Attribute\Route;

// der Anfang des Pfads und des Namens aller von PersonsController geerbten Routen
#[Route('/doctors', name: 'doctors_')]
class DoctorsController extends PersonsController
{
    protected function section(): string
    {
        return 'doctors';
    }

    // DOCTORS.TITLE, DOCTORS.ADD... (siehe Übersetzungen)
    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);
    }
}

Hier muss nur noch angegeben werden, welche Methoden aufzurufen sind (die Methoden von [ApplicationModel]) und welche Labels anzuzeigen sind (die [DOCTORS.xxx]-Schlüssel in den Wörterbüchern), sowie die Pfadanfänge und Routennamen (Zeile 14). [ApplicationModel] befindet sich in der Eigenschaft [$this->application], die vom Konstruktor der Elternklasse deklariert wird. [ClientsController] ist identisch, mit den Client-Methoden und den [CLIENTS.xxx]-Schlüsseln.

11.19.6. src/Controller/RegistrationController.php

<?php
// =========================================================================
// src/Controller/RegistrationController.php: "Patientenkonto erstellen": Ein Patient,
// der noch kein Konto hat, erstellt es selbst. ÖFFENTLICHE Routen (man hat
// per Definition noch kein Konto):
//
//   POST /register/access     Schaltfläche "Patientenkonto erstellen" der Login-Seite:
//                             prüft das Captcha DIESER
//                             Seite und öffnet dann das Formular
//   GET  /register            das Formular
//   POST /register            das Anlegen, dann zurück zur Login-Seite
//
// Der Weg ist durch EIN Captcha gegen Roboter geschützt, das der
// Login-Seite:
//   1. Die Schaltfläche "Patientenkonto erstellen" sendet das Login-Formular an
//      /register/access; wird das Captcha korrekt abgeschrieben, stellt der Server einen
//      Pass aus (siehe src/Security/RegistrationPass.php);
//   2. ohne gültigen Pass leitet /register zur Login-Seite um
//      (Attribut #[RegistrationPassRequired], siehe
//      src/EventListener/CheckRegistrationPass.php);
//   3. der Pass wird beim Anlegen verbraucht: Ein gelöstes Captcha erlaubt es,
//      EIN Konto anzulegen;
//   4. zusätzlich ist die Anzahl der pro Stunde und IP-Adresse erstellten Konten begrenzt
//      (siehe src/Security/AttemptLimiter.php).
//
// Das erstellte Konto ist genau das, das der ADMIN auf der Seite "Patienten" anlegen würde
// (dieselbe Methode der Geschäftsschicht: addClient), nur dass der Patient
// sein Login und sein Passwort WÄHLT (erforderlich, mit Bestätigung).
// =========================================================================

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   Felder: captchaId, captcha (die der Login-Seite;
    // Login und Passwort, die ebenfalls gesendet werden, werden ignoriert)
    // -----------------------------------------------------------------------
    #[Route('/access', name: 'registration_access', methods: ['POST'])]
    public function access(Request $request): Response
    {
        $this->checkCsrf($request);
        $ip = (string) $request->getClientIp();

        // zu viele kürzlich von dieser Adresse erstellte Konten: Es lohnt sich nicht, weiterzumachen
        $minutes = $this->limiter->registrationBlockMinutes($ip);
        if ($minutes > 0) {
            $this->flash->error('ERRORS.TOO_MANY_ACCOUNTS', ['minutes' => $minutes]);
            return $this->redirectToRoute('login');
        }

        // fehlendes oder falsches Captcha: zurück zur Login-Seite, mit einem
        // neuen Bild (ein Fehlschlag zählt als Login-Fehlschlag)
        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');
        }

        // richtiges Captcha: Der Pass wird ausgestellt und das Formular geöffnet
        $response = $this->redirectToRoute('registration');
        $response->headers->setCookie($this->passes->issue());
        return $response;
    }

    // -----------------------------------------------------------------------
    // GET /register: das Formular; POST /register: das Anlegen. Der
    // Pass wurde VOR dem Aufruf der Action geprüft (#[RegistrationPassRequired]).
    // Das Formular validiert ALLE Eingaben (Felder und Passwortbestätigung):
    // Der Benutzer korrigiert alle seine Fehler in einem Zug
    // -----------------------------------------------------------------------
    #[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. zu viele kürzlich von dieser Adresse erstellte Konten?
        $minutes = $this->limiter->registrationBlockMinutes($ip);
        if ($minutes > 0) {
            return $this->page($form, new Message('ERRORS.TOO_MANY_ACCOUNTS', ['minutes' => $minutes]));
        }

        // 2. das Anlegen (Client + USER-Konto, in einer Transaktion)
        $data = PersonFieldsType::data($form->getData());
        try {
            $this->application->addClient($data);
        } catch (BusinessException $e) {
            // Login oder Vor- + Nachname bereits vergeben: Der Pass bleibt gültig
            return $this->page($form, new Message($e->key, $e->params),
                PersonsController::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
        }

        // 3. der Pass wurde verwendet: Er erlaubt kein Anlegen eines 2. Kontos
        $this->passes->consume($request->cookies->get(RegistrationPass::COOKIE));
        $this->limiter->registrationSuccess($ip);

        // 4. zurück zur Login-Seite, Login vorausgefüllt
        $this->flash->success('REGISTRATION.DONE', ['login' => $data->login]);
        return RegistrationPass::clearCookie($this->redirectToRoute('login', ['login' => $data->login]));
    }

    // das Formular; ein abgelehntes Formular: der Code 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));
    }
}

Der Patient legt sein Patientenkonto selbst an. Der Ablauf wird durch ein CAPTCHA geschützt, dasselbe wie auf der Anmeldeseite.

  • Zeilen 65–91: Die Schaltfläche „Patientenkonto erstellen“ auf der Anmeldeseite sendet das Anmeldeformular an diese Adresse (später die View [login]). Wurden von dieser Adresse (IP) zuletzt zu viele Konten erstellt, ist ein Weitermachen nicht nötig. Fehlt das CAPTCHA oder ist es falsch: Rückkehr zur Anmeldeseite mit einem neuen Bild und einer Meldung; der Fehlschlag zählt als fehlgeschlagener Anmeldeversuch (mit leerem Benutzernamen). Ist das CAPTCHA korrekt: Ein Token wird in einem Cookie gespeichert, und der Benutzer wird zum Formular weitergeleitet;
  • Zeilen 99–107: das Formular. Das Attribut [#[RegistrationPassRequired]] (Zeile 100) bewirkt, dass das Token vom Listener [CheckRegistrationPass] geprüft wird, bevor die Aktion aufgerufen wird. Das Formular validiert alle Eingaben einschließlich der Passwortbestätigung: Der Benutzer sieht alle Fehler auf einmal;
  • Zeilen 108–132: Erstellung. Der Client und sein Konto werden mit derselben Methode der Geschäftsschicht erstellt wie beim Administrator ([addClient]); nur Benutzername und Passwort werden vom Patienten gewählt. Ist ein Benutzername oder ein Namensvetter bereits vergeben: Rückkehr zum Formular ohne den Pass zu verbrauchen. Die Erstellung eines Kontos verbraucht das Token (ein gelöstes CAPTCHA entspricht einem Konto), zählt für das Stundenlimit und leitet mit vorausgefülltem Benutzernamen zur Anmeldeseite weiter ([redirectToRoute('login', ['login' => ...])] fügt den Parameter [?login=...] hinzu), zusammen mit einer Erfolgsmeldung. Das Pass-Cookie wird gelöscht.

11.19.7. src/Controller/PatientAreaController.php

<?php
// =========================================================================
// src/Controller/PatientAreaController.php: die PERSÖNLICHEN Seiten des Patienten (Rolle
// USER), die er direkt nach dem Login sieht:
//
//   GET  /my-area                  Startseite: [Manage my account], [View a
//                                  schedule] und sein bevorstehender Termin
//   POST /my-area/cancel           storniert SEINEN Termin
//   GET  /my-account               Formular zum Ändern seines Kontos
//   POST /my-account               Ändern
//   POST /my-account/delete        Löschen des Kontos (und seiner Termine)
//
// Goldene Regel dieses Controllers: Der betroffene Patient ist IMMER der aus dem Token
// ($this->utils->connectedPatient()), nie eine vom
// Browser gesendete Kennung. Ein Patient kann daher weder sehen noch ändern noch stornieren, was
// einem anderen Patienten gehört, auch nicht, indem er seine Anfragen selbst baut.
//
// Jede Änderung oder Löschung des Kontos erfordert das AKTUELLE Passwort:
// Wer eine offen gelassene Sitzung gefunden hat, könnte weder das
// Passwort ändern noch das Konto löschen. Fehler beim aktuellen Passwort werden
// als Login-Fehlschläge gezählt (dasselbe Limit).
//
// Sicherheit: Alle diese URLs sind der Rolle USER vorbehalten (Regel ^/my- von
// 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 zum Terminkalender des Arztes an diesem Tag: Der Patient sieht dort seinen Namen
            $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   Feld: 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;
        // Ein nicht existierender Termin und der eines ANDEREN Patienten erhalten dieselbe
        // Antwort: Über die Termine der anderen wird nichts verraten
        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: das Formular, vorausgefüllt mit den Werten des Patienten;
    // POST /my-account: das Ändern
    // -----------------------------------------------------------------------
    #[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);
        }

        // das aktuelle Passwort; falsch: Die Nachricht steht UNTER dem Feld (ein dem Feld
        // hinzugefügter Fehler, FormError) und unten auf der Seite
        $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] ?? []);
        }
        // das Login und der angezeigte Name stehen IM Token: Es wird ein neues ausgestellt,
        // sonst würde die Navigationsleiste den alten Namen behalten
        $this->flash->success('MY_ACCOUNT.UPDATED');
        $response = $this->redirectToRoute('area');
        $response->headers->setCookie($this->auth->tokenCookie($client->getAccount()));
        return $response;
    }

    // -----------------------------------------------------------------------
    // POST /my-account/delete   Feld: current_password
    // Das Konto, der Client und ALLE seine Termine verschwinden gemeinsam, dann wird der
    // Patient abgemeldet.
    // -----------------------------------------------------------------------
    #[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'));
    }

    // ————————————————————————————————————————————————————————————————— interne Funktionen

    // die Kontoseite; ein abgelehntes Formular: der Code 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, wenn das aktuelle Passwort korrekt ist; andernfalls die Fehlermeldung
    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;
    }
}

Die persönlichen Seiten des Patienten. Die goldene Regel für diesen Controller: Der betreffende Patient ist immer derjenige, der mit dem Token verknüpft ist ([Utils::connectedPatient]), niemals ein vom Browser gesendeter Bezeichner. Ein Patient kann daher Informationen eines anderen Patienten weder einsehen noch ändern oder stornieren, selbst wenn er eigene Requests konstruiert.

  • Zeilen 64–79: Mein Bereich: der Name des Patienten und seine bevorstehenden Termine, formatiert ([AppointmentView]), jeweils mit einem Link zum Terminkalender des Arztes für diesen Tag;
  • Zeilen 84–100: die Stornierung seines Termins. Sowohl ein nicht existierender Termin als auch der Termin eines anderen Patienten erhalten dieselbe Antwort: Über die Termine anderer Patienten wird keine Information preisgegeben (nicht einmal ihre Existenz);
  • Zeilen 106–117: das Formular „Mein Konto verwalten“, mit den Daten des Patienten vorausgefüllt, und sein Absenden;
  • Zeilen 119–142: die Änderung. Jede Änderung erfordert das aktuelle Passwort: Jemand, der eine offen gebliebene Session findet, könnte weder das Passwort ändern noch sonst etwas tun. Ist das aktuelle Passwort falsch, wird das Formular erneut angezeigt, mit der Meldung unter dem Feld und am Seitenende. [addError(new FormError(...))] fügt einem Feld einen Fehler hinzu, als hätte die Validierung ihn erkannt (Beispiel 18); seine Meldung ist ein bereits übersetzter Text, daher der vom Builder erhaltene Übersetzer ([TranslatorInterface], Beispiel 22). Nach der Änderung wird ein neues Token erzeugt: Login und angezeigter Name sind im Token enthalten, und die Navigationsleiste würde sonst bis zur nächsten Anmeldung den alten Namen behalten;
  • Zeilen 149–163: Löschung des Kontos, des Clients und aller seiner Termine mit derselben Methode der Geschäftsschicht wie beim Administrator. Dieses zweite Formular auf der Seite ist von Hand geschrieben (ein einziges Feld, das aktuelle Passwort) und enthält das Anti-CSRF-Token der Anwendung. Der Patient wird anschließend abgemeldet (das Token-Cookie wird gelöscht);
  • Zeilen 177–190: Prüfung des aktuellen Passworts. Diese unterliegt dem Versuchsbegrenzer, genau wie eine Anmeldung: Ohne ihn könnte jemand mit einer offenen Session über das Formular „Mein Konto verwalten“ Tausende von Passwörtern ausprobieren und das richtige herausfinden.

11.20. Die Views

Die [Twig]-Views im Ordner [templates]: ein Template, Fragmente, Makros und Seiten.

11.20.1. Das Template und die Fragmente

11.20.1.1. templates/layout.html.twig

<!doctype html>
{# =========================================================================
   templates/layout.html.twig
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
   Das für alle Seiten GEMEINSAME Layout (siehe Beispiel 15): Jede Seite
   (schedule.html.twig, login.html.twig ...) ERWEITERT es ({% extends %}) und füllt ihren
   Block [content].

   Twig MASKIERT alles, was es mit {{ ... }} ausgibt (die Zeichen < > & " '
   werden zu &lt; &gt; ...): Schutz vor HTML-Injection zum Beispiel durch einen eingegebenen
   Namen. Um HTML unverändert einzufügen, muss dies
   ausdrücklich angefordert werden (Filter raw, siehe fragments/captcha.html.twig).

   Meldungen: Ein Erfolg wird am ANFANG der Seite angezeigt, ein Fehler am ENDE, auf hellrosa
   Hintergrund (Fragment errors).

   Das Layout teilt die Variablen der Seite: [pageTitle] (der Schlüssel des Titels von
   der Seite, von der Action übergeben). Die Sprache der Seite ist die der Anfrage
   (app.request.locale, siehe 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: die Übersetzung eines Schlüssels; hier ist der Schlüssel eine VARIABLE #}
  <title>{{ pageTitle|trans }} - {{ 'APP.TITLE'|trans }}</title>
  {# asset(): die URL einer Datei des Ordners 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>
  {# der Dialog "Are you sure?", versteckt, solange er nicht benötigt wird #}
  {% include 'fragments/confirmation.html.twig' %}
  <script src="{{ asset('js/app.js') }}"></script>
</body>
</html>

Das allen Seiten gemeinsame Template (Beispiel 15): Jede Seite erweitert es ([{% extends 'layout.html.twig' %}]) und füllt seinen [content]-Block (Zeile 36).

  • Zeile 21: die Sprache der Seite, [fr] oder [en]: die Sprache des Requests, festgelegt vom Listener [SetLanguage]. [app] ist die globale Variable, die [Symfony] allen Views bereitstellt (Beispiel 15);
  • Zeile 26: der übersetzte Seitentitel: [pageTitle|trans] übersetzt den in der Variablen [pageTitle] enthaltenen Schlüssel, den jede Aktion ihrer View übergibt;
  • Zeilen 28–29: die Funktion [asset] liefert die URL einer Datei im Ordner [public] (Beispiel 15);
  • Zeilen 33–38: die Navigationsleiste, die Erfolgsmeldungen oben auf der Seite, der Seiteninhalt und der Fehlerbereich am Seitenende. Diese Fragmente werden mit [{% include %}] eingefügt (Beispiel 15): Sie haben Zugriff auf die Variablen der Seite;
  • Zeilen 41–42: das Fenster „Sind Sie sicher?“, das bis zum Bedarfsfall verborgen ist, und das Skript, das es anzeigt.

[Twig] maskiert alles, was es mit [{{ ... }}] ausgibt (Beispiel 13): Ein eingegebener Name, der HTML enthält ([<script>]), wird unverändert angezeigt, ohne interpretiert zu werden. Das schützt mühelos auf allen Seiten vor der Einschleusung von HTML (XSS).

11.20.1.2. templates/fragments/navbar.html.twig

{# =========================================================================
   templates/fragments/navbar.html.twig - die Navigationsleiste.

   Titel, FR/EN, Rolle, Name, Abmelden - und ein Menü, dessen Einträge von
   der Rolle abhängen: "Doctors" und "Patients" erscheinen nur für den ADMIN. Es ist
   nur eine Anzeigehilfe: Der eigentliche Schutz sind die Zugriffsregeln
   (ein USER, der /doctors von Hand eingibt, erhält eine 403-Seite). Ein Patient (USER)
   hat außerdem sein Menü "My area".

   user(): der angemeldete Benutzer oder null (siehe src/Twig/ViewsExtension.php).
   Das Menü der aktuellen Seite wird hervorgehoben (Klasse "active"): Das ist der Fall, wenn
   der Pfad der URL (app.request.pathInfo) mit ([starts with]) einem der
   Präfixe des Eintrags beginnt. Die Einträge des Menüs: eine Liste von Arrays [Name der
   Route, Schlüssel des Labels, Präfixe der Pfade, für die der Eintrag aktiv ist].
   ========================================================================= #}
{% set user = user() %}
{% set menu = [] %}
{% if user %}
  {% if user.isPatient %}
    {# aktiv für /my-area UND /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]: der Name der Route; filter behält die passenden Präfixe #}
    {% 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: einfache Links (GET /language/fr), die aktive Sprache hervorgehoben #}
    <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 ist ein POST: ein Formular, reduziert auf seinen Button (und das Anti-CSRF-Token) #}
    <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>

Die Navigationsleiste. Die Menüeinträge hängen von der Rolle ab: „Mein Bereich“ für einen Patienten, „Ärzte“ und „Patienten“ für den Administrator. Das ist lediglich eine Komfortfunktion: Der eigentliche Schutz kommt von den Regeln [access_control] (ein Patient, der [/doctors] manuell eingibt, erhält eine 403-Seite).

  • Zeile 16: der angemeldete Benutzer oder [null], geliefert von der Funktion [user()] in unserer Erweiterung;
  • Zeilen 17–28: Das Menü wird von den Anweisungen [{% set %}] erzeugt, die eine Liste von Einträgen bilden: den Routennamen, den Label-Schlüssel und die Pfadpräfixe, für die der Eintrag aktiv ist. Der Filter [merge] liefert eine neue Liste, bestehend aus den Elementen der ersten Liste gefolgt von denen der zweiten (bei zwei assoziativen Arrays kombiniert er deren Schlüssel). [user.isPatient]: [Twig] ruft die Methode [isPatient()] auf. Der Eintrag „Mein Bereich“ ist für [/my-area] und [/my-account] aktiv (Präfix [/my-]). Das grenzt an die Regel „keine Logik in den Views“: Diese Logik betrifft jedoch nur die Anzeige und wird nur hier verwendet;
  • Zeilen 34–39: Für jeden Eintrag ist [active] wahr, wenn der Pfad der angeforderten URL ([app.request.pathInfo]) mit ([starts with]) einem der Präfixe des Eintrags beginnt. Der Filter [filter] behält nur die Elemente einer Liste, die eine Bedingung erfüllen, geschrieben als Pfeilfunktion ([p => ...]);
  • Zeilen 44–49: die Schaltflächen FR / EN, die einfache Links sind ([/language/fr]), wobei die aktive Sprache hervorgehoben ist;
  • Zeilen 51–59: für einen angemeldeten Benutzer seine Rolle ([user.role.value]: der String des Enum-Cases), sein Name und die Abmelden-Schaltfläche. Die Abmeldung ist ein POST-Request: ein auf seine Schaltfläche reduziertes Formular mit seinem Anti-CSRF-Token ([csrf_token('rdvmedecins')], Beispiel 21).

11.20.1.3. templates/fragments/success.html.twig

{# =========================================================================
   templates/fragments/success.html.twig - die ERFOLGSMELDUNGEN, die von
   der vorherigen Action hinterlegt wurden (Termin gebucht, Arzt hinzugefügt ...), nur
   einmal angezeigt, am Seitenanfang (siehe src/Web/Flash.php). Eine ERROR-Flash-Nachricht
   wird dagegen am Seitenende vom Fragment errors angezeigt.

   app.flashes('success'): die Flash-Nachrichten dieses Typs (siehe Beispiel 20). Jede
   Nachricht ist ein Objekt Message: message.key|trans(message.params) ist der Text
   des Schlüssels, in dem {name}, {login} ... durch ihre Werte ersetzt werden.
   ========================================================================= #}
{% for message in app.flashes('success') %}
<div class="alert alert-success" role="status">{{ message.key|trans(message.params) }}</div>
{% endfor %}

Die Flash-Erfolgsmeldungen, die von der vorherigen Aktion gesetzt wurden ([Flash::success]), werden von [app.flashes('success')] aus der Session gelesen und entfernt (Beispiel 20). Jede ist ein [Message]-Objekt, das hier in die Sprache der Seite übersetzt wird: [message.key|trans(message.params)]. [role="status"]: Ein Screenreader liest die Meldung vor.

11.20.1.4. templates/fragments/errors.html.twig

{# =========================================================================
   templates/fragments/errors.html.twig - der Fehlerbereich am ENDE jeder
   Seite, auf hellrosa Hintergrund (Klasse .error-zone, siehe public/css/styles.css).

   Er fasst die drei möglichen Fehlerquellen zusammen:
     - [error]: der Fehler der angezeigten Seite (ungültiges Datum, falsch
       abgeschriebenes Captcha, bereits vergebener Login ...), von der Action übergeben;
     - die Fehler-Flash-Nachrichten, von der vorherigen Action vor einer
       Weiterleitung hinterlegt (Slot bereits gebucht, Löschung abgelehnt ...);
     - die Eingabefehler eines ungültigen Formulars (siehe Beispiel 19): ihre
       Meldungen werden UNTER den Feldern angezeigt; hier, wenn es keine andere
       Meldung gibt, ein einfacher Satz "The form contains errors.".

   error ?? null: die Variable existiert nicht in allen Seiten.
   role="alert": Ein Screenreader kündigt die Meldung an, sobald die Seite angezeigt wird,
   auch wenn sie am Seitenende steht.
   ========================================================================= #}
{% 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 %}

Der Fehlerbereich am Ende jeder Seite auf hellrosa Hintergrund. Er vereint die drei möglichen Fehlerquellen:

  • Flash-Fehlermeldungen, die von der vorherigen Aktion erzeugt wurden (ein bereits reserviertes Zeitfenster, eine abgelaufene Session usw.);
  • der Fehler der angezeigten Seite ([error]), von der Aktion übermittelt: ein ungültiges Datum, ein falsch eingegebenes CAPTCHA, ein bereits verwendeter Benutzername usw.; oben in der Liste platziert. [error ?? null]: Diese Variable existiert nicht auf allen Seiten; der Operator [??] meldet eine nicht vorhandene Variable nicht, sondern ersetzt sie durch [null];
  • Eingabefehler in einem ungültigen Formular (Beispiel 19): Ihre Meldungen werden unter den Feldern angezeigt; hier erscheint, wenn es keine anderen Meldungen gibt, ein einfacher Satz: „Das Formular enthält Fehler.“ Bei einem langen Formular weiß der Benutzer so, dass er nach oben scrollen muss. [form.vars]: die Eigenschaften der Form-View, darunter [submitted] (abgeschickt?) und [valid] (gültig?). Die Meldung wird als assoziatives Array mit denselben Schlüsseln wie die Eigenschaften einer [Message] geschrieben: Für [Twig] bezeichnet [message.key] sowohl den Schlüssel eines Arrays als auch die Eigenschaft eines Objekts.

[role="alert"]: Ein Screenreader liest die Meldung vor, sobald die Seite angezeigt wird, selbst wenn sie am Seitenende steht. Der Bereich bleibt bei einer langen Seite am unteren Fensterrand fixiert (siehe das Stylesheet unten).

11.20.1.5. templates/fragments/confirmation.html.twig

{# =========================================================================
     templates/fragments/confirmation.html.twig - der modale Dialog
     "Are you sure?" (siehe Beispiel 21).

     Er ersetzt das Fenster window.confirm() des Browsers, das sich weder gestalten
     noch übersetzen lässt (seine Buttons bleiben in der Sprache des Browsers, nicht
     in der der Seite).

     EIN EINZIGER Dialog für die ganze Seite, zunächst versteckt (d-none). Seine Labels
     werden hier vom Server übersetzt, wie der Rest der Seite; das kleine Skript
     public/js/app.js zeigt ihn lediglich an, setzt die für das Formular spezifische Nachricht
     ein (Attribut data-confirmation) und sendet das Formular, wenn
     der Benutzer bestätigt.
     ========================================================================= #}
<div id="confirmation-modal" class="d-none">
  <div class="modal-backdrop fade show"></div>
  <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
       aria-labelledby="confirmation-modal-title" aria-describedby="confirmation-modal-message">
    <div class="modal-dialog modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-header">
          <h5 class="modal-title" id="confirmation-modal-title">{{ 'CONFIRMATION.TITLE'|trans }}</h5>
          <button type="button" class="btn-close" data-action="no" aria-label="{{ 'BOOKING_DIALOG.CLOSE_ARIA'|trans }}"></button>
        </div>
        <div class="modal-body">
          <p class="mb-0" id="confirmation-modal-message"></p>
        </div>
        <div class="modal-footer">
          {# "No, go back" statt "Cancel": Die Frage lautet manchmal
               "Cancel this appointment?", und ein Button "Cancel" wäre dort mehrdeutig #}
          <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>

Das modale Fenster „Sind Sie sicher?“ aus Beispiel 21, das das [window.confirm()]-Dialogfeld des Browsers ersetzt: Dieses Dialogfeld lässt sich nicht richtig formatieren, und seine Schaltflächen bleiben in der Sprache des Browsers statt in der der Seite. Ein einziges Fenster für die gesamte Seite, anfangs verborgen (Klasse [d-none] aus [Bootstrap]); seine Beschriftungen werden wie der Rest der Seite vom Server übersetzt. Das Skript [public/js/app.js] zeigt es an, legt die Meldung des zu bestätigenden Formulars darin ab (dessen Attribut [data-confirmation]) und sendet das Formular ab, wenn der Benutzer bestätigt. Die Schaltfläche „Ablehnen“ trägt die Beschriftung „Nein, zurück“ statt „Abbrechen“: Die Frage lautet mitunter „Diesen Termin stornieren?“, und eine Schaltfläche „Abbrechen“ wäre in diesem Zusammenhang mehrdeutig.

11.20.1.6. templates/fragments/booking.html.twig

{# =========================================================================
   templates/fragments/booking.html.twig - der Buchungsdialog des
   Terminkalenders.

   Die ECHTEN Bootstrap-Klassen eines modalen Dialogs (.modal, .modal-backdrop ...),
   "fest codiert" sichtbar gemacht (show d-block) statt durch das JavaScript von Bootstrap.
   Der SERVER entscheidet, ihn anzuzeigen (Parameter &book=...
   der URL), und ihn zu schließen bedeutet, einem Link zur selben Seite ohne diesen
   Parameter zu folgen.

   Das Fragment liest direkt die Variablen der Seite, die es einbindet
   (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>

        {# was der Server zusätzlich zum gewählten Patienten wissen muss #}
        <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 }}">

        {# ein Patient bucht für sich selbst: keine Liste zur Auswahl (und der
           Server ignoriert ein mögliches clientId ohnehin) #}
        {% 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>

Das Buchungsfenster des Kalenders. Es verwendet die tatsächlichen Klassen eines modalen Fensters von [Bootstrap] ([modal], [modal-backdrop] ...), macht es aber fest im Code sichtbar ([show d-block]), statt über das [JavaScript] von [Bootstrap]: Es ist der Server, der entscheidet, es anzuzeigen, wenn die URL [&book=...] enthält. Es zu schließen (mit dem X oder der Schaltfläche „Abbrechen“) ist gleichbedeutend damit, einem Link auf dieselbe Seite ohne diesen Parameter zu folgen ([backUrl]).

  • Zeilen 27–30: das Anti-CSRF-Token und das, was der Server wissen muss: der Arzt, der Tag und das Zeitfenster;
  • Zeilen 34–47: Ein Patient gibt seinen eigenen Namen ein, ohne ihn aus einer Liste auszuwählen (und der Server ignoriert ein [clientId]-Feld ohnehin). Der Administrator und die Ärzte wählen den Patienten aus einer Liste aus; [required] und [autofocus]: Der Browser verlangt eine Auswahl und setzt den Cursor in die Liste.

11.20.1.7. templates/fragments/captcha.html.twig

{# =========================================================================
   templates/fragments/captcha.html.twig - das Captcha der Login-Seite
   (siehe src/Security/CaptchaService.php). Es schützt sowohl
   den Login als auch den Zugang zur Kontoerstellung (Button
   "Create a patient account"). Es liest die Variable [captcha] der Seite.

   captcha.svg|raw: Das SVG-Bild wird UNVERÄNDERT in die Seite eingefügt, ohne
   Maskierung. Das ist hier harmlos, weil dieses SVG vom Server selbst erstellt wird
   und nichts enthält, was vom Benutzer stammt - bei Benutzereingaben würden wir das NIEMALS
   tun.

   Das versteckte Feld captchaId teilt dem Server mit, WELCHES Captcha zu prüfen ist; die richtige
   Antwort selbst wird nie an den Browser gesendet. "Another image" lädt einfach
   die Seite neu (path('login'): die URL der Seite ohne ihre Parameter).
   ========================================================================= #}
<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>

Das CAPTCHA (Beispiel 27). [captcha.svg|raw] fügt das SVG-Bild unverändert ein, ohne es zu maskieren: Andernfalls würde der Browser seinen XML-Code anzeigen. Das ist hier unbedenklich, weil dieses SVG vom Server erzeugt wird und nichts vom Benutzer Geliefertes enthält: Mit Benutzereingaben würden wir das niemals tun. Das versteckte Feld [captchaId] teilt dem Server mit, welches CAPTCHA zu prüfen ist; die Antwort selbst wird nie an den Browser gesendet. Der Link „Anderes Bild“ lädt die Anmeldeseite – und damit das CAPTCHA – neu.

11.20.2. Makros: templates/macros.html.twig

{# =========================================================================
   templates/macros.html.twig - die Makros der Formulare (siehe Beispiel 15).

   field(field, invalidFields): ein Feld eines Formulars der Form-Komponente,
   mit seinem Label, seiner Fehlermeldung oder seiner Hilfe (form_row, vom
   Bootstrap-5-Theme gezeichnet, siehe Beispiel 18). Das Feld wird rot umrandet (Klasse
   is-invalid), wenn es einen Eingabefehler hat (das Theme übernimmt das) oder wenn ein
   FACHLICHER Fehler es bezeichnet: sein Name steht in der Liste [invalidFields], die von
   der Action übergeben wird (ein bereits vergebener Login ...), wobei die Meldung am Seitenende steht.
   Die Attribute des Feldes (maxlength ...) werden ergänzt, nicht ersetzt: 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 %}

{# die Identitätsfelder (Anrede, Vorname, Nachname), drei Formularen gemeinsam:
   Arzt/Client des ADMIN, "Create a patient account" und "Manage my account" #}
{% macro identity(form, invalidFields = []) %}
  {# import _self: die Makros DIESER Datei, um das Makro field aufzurufen #}
  {% 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 %}

Zwei Makros (Beispiel 15), die von den drei Seiten verwendet werden, die ein „Person“-Formular anzeigen.

  • Zeilen 12–18: ein Feld eines Formulars der Form-Komponente, erzeugt von [form_row] (Beispiel 18): sein Label, sein Eingabefeld, seine Fehlermeldung oder sein Tooltip, zusammen mit den Klassen des [Bootstrap]-5-Themes, das in [config/packages/twig.yaml] deklariert ist. Das Theme hebt ein Feld mit einem Eingabefehler rot hervor (Klasse [is-invalid]). Das Makro fügt sie außerdem einem Feld hinzu, das durch einen Fehler der Geschäftsschicht gekennzeichnet ist: die von der Aktion übergebene Liste [invalidFields] ([PersonsController::BUSINESS_ERROR_FIELDS]). Ein bereits vergebener Benutzername ist kein Eingabefehler (er hat das richtige Format), aber der Benutzer muss sehen, welches Feld er korrigieren muss. [field.vars]: die Eigenschaften der Feld-View, darunter ihr Name ([name]) und ihre HTML-Attribute ([attr]); diese werden ergänzt ([merge]), nicht ersetzt: Das Feld behält sein [maxlength]. Der zweite Parameter von [form_row] ersetzt die Eigenschaften der Feld-View;
  • Zeilen 22–30: die Identitätsfelder, die drei Formularen gemeinsam sind: die Anrede, gefolgt von Vorname und Nachname nebeneinander (das Raster von [Bootstrap]: [row], [col-sm-6]). Ein Makro kann die anderen Makros seiner Datei nicht sehen: [{% import _self as m %}] (Zeile 24) importiert sie.

11.20.3. Die Seiten

11.20.3.1. templates/login.html.twig

{# =========================================================================
   templates/login.html.twig - das Login-Formular (siehe AuthController).
   Ein gewöhnliches handgeschriebenes HTML-<form>: Der Browser selbst sendet Login,
   Passwort und Captcha-Antwort per POST /login, ohne JavaScript. Bei
   einem Fehlschlag sendet der Server DIESE Seite zurück, mit dem bereits eingegebenen Login, einem NEUEN
   Captcha und dem Fehler, der vom Layout am Seitenende angezeigt wird.
   ========================================================================= #}
{% 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: ein boolesches Attribut, geschrieben, wenn die Bedingung wahr ist, sonst
             weggelassen. Der Cursor springt in das erste auszufüllende Feld #}
          <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>

        {# noch kein Konto: Ein Patient kann selbst eines erstellen. Es ist KEIN
           einfacher Link: Es ist ein zweiter Submit-Button DIESES Formulars,
           der zu einer anderen Adresse führt (formaction). Der Server prüft dort das
           Captcha oben, bevor er die Seite zur Kontoerstellung öffnet (siehe
           RegistrationController). formnovalidate: Der Browser verlangt
           Login und Passwort nicht (nutzlos, um ein Konto zu erstellen). Enter in einem
           Feld löst immer den ERSTEN Button des Formulars aus, "Log in". #}
        <button type="submit" class="btn btn-outline-primary w-100 mt-3"
                formaction="{{ path('registration_access') }}" formnovalidate>{{ 'LOGIN.CREATE_ACCOUNT'|trans }}</button>
        <div class="form-text text-center">{{ 'LOGIN.CREATE_ACCOUNT_HELP'|trans }}</div>
      </form>

      <div class="text-muted small mt-3">
        <span>{{ 'LOGIN.DEMO_ACCOUNTS'|trans }}</span>
        <ul class="mb-0 mt-1">
          <li><code>admin</code> - <span>{{ 'LOGIN.DEMO_ADMIN'|trans }}</span></li>
          <li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - <span>{{ 'LOGIN.DEMO_DOCTOR'|trans }}</span></li>
          <li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - <span>{{ 'LOGIN.DEMO_USER'|trans }}</span></li>
        </ul>
      </div>
    </div>
  </div>
</div>
{% endblock %}

Das Anmeldeformular, ein von Hand geschriebenes [<form>], wird per POST an [/login] gesendet (den Pfad [login_submit]).

  • Zeilen 22–28: Der eingegebene Benutzername wird nach einem fehlgeschlagenen Anmeldeversuch erneut angezeigt ([login]). Das Attribut [autofocus] setzt den Cursor in das erste auszufüllende Feld: den Benutzernamen, wenn er leer ist, andernfalls das Passwort (nach einem fehlgeschlagenen Versuch oder nach der Erstellung eines Kontos). [{{ login == '' ? ' autofocus' }}]: Der ternäre Operator ohne „else“ liefert einen leeren String, wenn die Bedingung falsch ist;
  • Zeile 31: das CAPTCHA;
  • Zeilen 42–43: Die Schaltfläche „Patientenkonto erstellen“ ist kein Link; es ist eine zweite Schaltfläche, die dasselbe Formular an eine andere Adresse sendet (Schaltflächenattribut [formaction]). Der Server prüft dort das CAPTCHA, bevor er die Seite zur Kontoerstellung öffnet ([RegistrationController::access]). [formnovalidate]: Der Browser verlangt keinen Benutzernamen und kein Passwort (Attribute [required]), da sie zur Kontoerstellung nicht nötig sind. Das Drücken der Eingabetaste in einem Feld löst stets die erste Absenden-Schaltfläche des Formulars aus: Anmelden.

11.20.3.2. templates/schedule.html.twig

{# =========================================================================
   templates/schedule.html.twig - die Hauptseite (siehe ScheduleController).
   Drei Blöcke:
     1. die Wahl des Arztes und des Tages;
     2. der Terminkalender;
     3. der Buchungsdialog (Fragment booking).
   Ein möglicher Fehler (ungültiges Datum, unbekannter Arzt) wird am Ende
   der Seite vom Layout angezeigt (Fragment errors).
   ========================================================================= #}
{% extends 'layout.html.twig' %}

{% block content %}
  {# 1. Wahl des Arztes und des Tages: ein GET-Formular, das diese Seite einfach
        mit ?doctorId=...&day=... in der URL neu lädt #}
  <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>

  {# Patient, der bereits einen bevorstehenden Termin hat: darum gibt es keinen Button "Book" #}
  {% if info %}
  <div class="alert alert-info">
    <span>{{ info|trans }}</span>
    <a href="{{ path('area') }}" class="alert-link">{{ 'APP.MENU_MY_AREA'|trans }}</a>
  </div>
  {% endif %}

  {# 2. der Terminkalender #}
  {% 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] wird nur gesetzt, wenn der Benutzer das Recht hat, diesen
               Namen zu sehen (ADMIN, DOCTOR oder der Patient für SEINEN Termin) - andernfalls
               einfach "Booked" #}
            {% if row.free %}
            <span class="badge text-bg-success">{{ 'SCHEDULE.FREE'|trans }}</span>
            {% elseif row.patient %}
            <span class="badge {{ row.mine ? 'text-bg-primary' : 'text-bg-secondary' }}">{{ row.patient }}</span>
            {% else %}
            <span class="badge text-bg-secondary">{{ 'SCHEDULE.BOOKED_BY_OTHER'|trans }}</span>
            {% endif %}
          </td>
          <td>
            {# die angezeigten Buttons wurden vom Controller (bookable,
               appointmentId) entsprechend der Rolle des Benutzers festgelegt. "Book" ist ein einfacher
               Link: Er öffnet diese Seite erneut mit dem Buchungsdialog dieses Slots #}
            {% if row.bookable %}
            <a class="btn btn-sm btn-outline-success" href="{{ row.bookUrl }}">{{ 'SCHEDULE.BOOK'|trans }}</a>
            {% endif %}
            {# "Cancel" ÄNDERT Daten: Es ist daher ein 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. der Buchungsdialog, nur wenn die URL &book=... enthält #}
  {% if booking %}
  {% include 'fragments/booking.html.twig' %}
  {% endif %}
{% endblock %}

Die Hauptseite. Drei Bereiche: die Auswahl von Arzt und Tag, der Kalender und das Buchungsfenster.

  • Zeilen 15–34: Auswahl von Arzt und Tag: ein GET-Formular (Beispiel 17), das die Seite mit [?doctorId=...&day=...] in der URL neu lädt. Der Tag ist ein [type="date"]-Feld: Der Browser zeigt einen Kalender an und sendet das Datum im Format [yyyy-mm-dd], unabhängig davon, wie es angezeigt wird ([26/09/2026] auf Französisch);
  • Zeilen 37–42: für einen Patienten, der bereits einen bevorstehenden Termin hat, der Grund, warum es keine Schaltfläche „Buchen“ gibt;
  • Zeilen 66–72: der Status des Zeitfensters: Frei (grün), der Name des Patienten (blau beim Termin des angemeldeten Patienten, sonst grau) oder „Gebucht“. Die View trifft keine Entscheidungen: [row.patient] wird nur gefüllt, wenn der Benutzer diesen Namen sehen darf;
  • Zeilen 78–80: „Buchen“ ist ein einfacher Link: Er öffnet die Seite erneut mit dem Buchungsfenster für dieses Zeitfenster ([row.bookUrl]). Er ändert nichts: Ein GET genügt;
  • Zeilen 82–91: „Stornieren“ ändert Daten: Es ist ein POST-Formular (Beispiel 21) mit seinem Anti-CSRF-Token, dem zu stornierenden Termin und den Angaben, um zur selben Seite zurückzukehren (der Arzt, der Tag). Das Attribut [data-confirmation] veranlasst das Skript der Seite, eine Bestätigung anzufordern;
  • Zeilen 106–108: das Buchungsfenster, wenn es per URL angefordert wird (und wenn das Zeitfenster buchbar ist).

11.20.3.3. templates/persons/list.html.twig

{# =========================================================================
   templates/persons/list.html.twig - die Liste der Ärzte ODER der Clients
   (ADMIN). Eine einzige View für beide: Die für jeden spezifischen Label-Schlüssel
   kommen in [keys] an, und [section] ("doctors" oder "clients") liefert den Anfang der
   Namen der Routen (siehe PersonsController): section ~ '_add' -> "doctors_add".
   ========================================================================= #}
{% extends 'layout.html.twig' %}

{% block content %}
  <div class="d-flex justify-content-between align-items-center mb-3">
    <h4 class="mb-0">{{ keys.title|trans }}</h4>
    <a class="btn btn-primary" href="{{ path(section ~ '_add') }}">{{ keys.add|trans }}</a>
  </div>

  <div class="card p-3">
    {% if persons is not empty %}
    <table class="table table-hover align-middle mb-0">
      <thead>
        <tr>
          <th>{{ 'PERSONS.COLUMN_TITLE'|trans }}</th>
          <th>{{ 'PERSONS.COLUMN_FIRSTNAME'|trans }}</th>
          <th>{{ 'PERSONS.COLUMN_LASTNAME'|trans }}</th>
          <th>{{ 'PERSONS.COLUMN_LOGIN'|trans }}</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        {# person.title: Twig ruft den Getter getTitle() auf (siehe Beispiel 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: Ein Bestätigungsdialog öffnet sich, bevor
                 das Formular gesendet wird (siehe 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 %}

Die Liste der Ärzte oder Clients: Die jeweils spezifischen Labels sind Übersetzungsschlüssel ([keys]), und die Routennamen werden aus dem Bereichsnamen erzeugt ([path(section ~ '_edit', {id: person.id})]: Der Operator [~] verkettet und ergibt [doctors_edit] oder [clients_edit]). [person.account.login]: das Login des Kontos, das mit der Liste befüllt wird (DAO-Schicht). Die Schaltfläche „Löschen“ ist ein POST-Formular mit Bestätigung.

11.20.3.4. templates/persons/form.html.twig

{# =========================================================================
   templates/persons/form.html.twig - Erstellung ODER Änderung eines
   Arztes oder eines Clients (ADMIN), mit dem Formular PersonType.

   Wenn die Eingabe abgelehnt wird (leeres Feld, bereits vergebener Login ...), zeigt die Action
   DIESE Seite erneut an, und die View zeigt:
     - die bereits eingegebenen Werte (außer dem Passwort);
     - die fehlerhaften Felder rot umrandet (Bootstrap-Klasse "is-invalid");
     - unter einem von der Validierung abgelehnten Feld seine Meldung;
     - die Fehlermeldung der Seite, AM ENDE der Seite (Fragment errors).
   form_start schreibt das Tag <form> (Methode POST, URL der Seite); form_end das
   Ende des Formulars, mit den noch nicht geschriebenen Feldern: dem
   Anti-CSRF-Token und, bei der Änderung, dem versteckten Feld version (die optimistische Sperre).
   ========================================================================= #}
{% 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: die Fehler des Formulars selbst (falsches Anti-CSRF-Token) #}
        {{ form_errors(form) }}
        {# Anrede, Vorname, Nachname: ein Makro, drei Formularen gemeinsam #}
        {{ m.identity(form, invalidFields) }}

        <h6 class="mt-4 text-muted">{{ 'PERSONS.ACCOUNT_SECTION'|trans }}</h6>
        {{ m.field(form.login, invalidFields) }}
        {# nie vorbelegt: Das Passwort geht nie an den Browser zurück #}
        {{ 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 %}

Erstellung oder Bearbeitung eines Arztes oder Clients mit dem Formular [PersonType].

  • Zeile 16: Import der Makros unter dem Namen [m];
  • Zeile 24: [form_start] schreibt das Tag [<form>]: die Methode POST, die URL der Seite und das Attribut [novalidate] (Type-Option [attr]);
  • Zeile 26: [form_errors(form)] zeigt Fehler des Formulars selbst an, die sich auf kein bestimmtes Feld beziehen: ein ungültiges Anti-CSRF-Token („Die Seite ist abgelaufen ...“);
  • Zeile 28: Anrede, Vorname und Nachname über das Makro [identity];
  • Zeilen 31–33: der Benutzername und das Passwort, die nie vorausgefüllt werden. Ihre Tooltips unterscheiden sich bei Erstellung und Änderung (Type-Optionen);
  • Zeile 39: [form_end] schließt das Formular, nachdem es die noch nicht geschriebenen Felder ausgegeben hat: das Anti-CSRF-Token und beim Bearbeiten das versteckte Versionsfeld (die optimistische Sperre).

11.20.3.5. templates/registration.html.twig

{# =========================================================================
   templates/registration.html.twig - "Create a patient account" (öffentliche Seite, siehe
   RegistrationController), mit dem Formular RegistrationType. Dieselben
   Identitätsfelder wie im Formular des ADMIN (Makro identity), aber Login und
   Passwort sind erforderlich, mit Bestätigung. Hier KEIN Captcha: Man
   gelangt nur auf diese Seite, nachdem man das der Login-Seite abgeschrieben hat
   (Button "Create a patient account").
   ========================================================================= #}
{% extends 'layout.html.twig' %}
{% import 'macros.html.twig' as m %}

{% block content %}
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4">
      <h5 class="card-title mb-1">{{ 'REGISTRATION.TITLE'|trans }}</h5>
      <p class="text-muted small mb-3">{{ 'REGISTRATION.INTRO'|trans }}</p>

      {{ form_start(form) }}
        {{ form_errors(form) }}
        {{ m.identity(form, invalidFields) }}

        <h6 class="mt-4 text-muted">{{ 'PERSONS.ACCOUNT_SECTION'|trans }}</h6>
        {{ m.field(form.login, invalidFields) }}
        {# das wiederholte Feld: seine beiden Eingabefelder nebeneinander (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 %}

Erstellung eines Patientenkontos: die Identitätsfelder, gefolgt von Benutzername, Passwort und Passwortbestätigung, die erforderlich sind. Die beiden Felder des wiederholten Felds sind [form.password.first] und [form.password.second] (Zeilen 27–28), nebeneinander platziert. Der Hilfetext des Passworts gibt die Mindestlänge an: „Mindestens 6 Zeichen.“ Hier gibt es kein CAPTCHA: Diese Seite erreichen Sie nur, nachdem Sie das CAPTCHA der Anmeldeseite eingegeben haben.

11.20.3.6. templates/area.html.twig

{# =========================================================================
   templates/area.html.twig - "My area": die Startseite des Patienten (Rolle
   USER), direkt nach dem Login angezeigt.
     - zwei Optionen: [Manage my account] und [View a schedule];
     - sein bevorstehender Termin, falls vorhanden, mit den Mitteln zum Absagen.
   ========================================================================= #}
{% 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>
    {# normalerweise nur einer (Regel "ein bevorstehender Termin zur Zeit"), aber die
       Seite kann mehrere anzeigen. {% for %} ... {% else %}: eine Schleife und
       das, was bei einer leeren Liste angezeigt wird; loop.last: letztes Element? #}
    {% 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 %}

„Mein Bereich“, die Startseite des Patienten: zwei große Karten („Mein Konto verwalten“, „Terminkalender ansehen“) und sein bevorstehender Termin.

  • Zeilen 32–50: [{% for %}] ... [{% else %}] (Beispiel 14) ist eine Schleife, gefolgt von dem, was angezeigt wird, wenn die Liste leer ist. Normalerweise hat ein Patient höchstens einen bevorstehenden Termin; die Seite kann jedoch mehrere Termine anzeigen. [loop.last] (Beispiel 14): Das letzte Element hat kein Trennzeichen;
  • jeder Termin hat ein Stornierungsformular (POST, mit Bestätigung), das nur seine ID sendet: Der Server prüft, ob er zum angemeldeten Patienten gehört.

11.20.3.7. templates/account.html.twig

{# =========================================================================
   templates/account.html.twig - "Manage my account" (Rolle USER).
   Zwei unabhängige Formulare auf derselben Seite:
     1. die Änderung (Identität, Login, optionales neues Passwort), mit
        dem Formular MyAccountType;
     2. die Löschung des Kontos - die auch seine Termine absagt: ein
        handgeschriebenes Formular.
   Beide verlangen das AKTUELLE Passwort (Feld 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. Änderung #}
    <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. Löschung. Das Passwortfeld hat denselben NAMEN wie das des ersten
       Formulars (current_password), aber eine andere id: Zwei Elemente derselben
       Seite können nicht dieselbe id haben #}
    <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 %}

„Mein Konto verwalten“: zwei voneinander unabhängige Formulare auf derselben Seite.

  • Zeilen 18–38: die Aktualisierung mit dem Formular [MyAccountType]: die Identitätsfelder, das Login, das neue Passwort und seine Bestätigung (optional) und das aktuelle Passwort (erforderlich). Die Version (optimistische Sperre) wird von [form_end] gesetzt;
  • Zeilen 43–56: Löschung des Kontos, ein von Hand geschriebenes Formular mit eigenem Feld für das aktuelle Passwort und einem Bestätigungsfeld. Das Feld heißt [current_password] (das Feld im ersten Formular heißt [my_account[current_password]]: Die Form-Komponente stellt ihren Feldnamen den Formularnamen voran) und hat eine eigene eindeutige ID: Zwei Elemente einer Seite dürfen nicht dieselbe ID haben, wie das Attribut [for] eines Labels zeigt.

11.20.3.8. templates/error.html.twig

{# =========================================================================
   templates/error.html.twig - die Fehlerseite (400, 403, 404, 405, 419,
   500 ...), erstellt von 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 %}

Die Fehlerseite, erzeugt vom Listener [ErrorPage]: der HTTP-Code, die Meldung und ein Link zur Startseite ([/], der zur Startseite der Rolle oder zur Anmeldeseite weiterleitet).

11.21. Statische Dateien

Der Ordner [public] ist das Stammverzeichnis der Website: Der Server sendet die dort liegenden Dateien unverändert (Beispiel 15). Neben [index.php] enthält er [Bootstrap] ([lib/bootstrap]), ein Stylesheet und ein Skript.

11.21.1. public/css/styles.css

/* =========================================================================
   public/css/styles.css - einige Einstellungen zusätzlich zu Bootstrap
   (dieselben wie in den anderen Versionen dieser Anwendung).
   ========================================================================= */

body {
  background-color: #f5f7fa;
}

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

/* -------------------------------------------------------------------------
   .error-zone: die Fehlermeldungen, unten auf der Seite, auf hellrosa Hintergrund
   (siehe templates/fragments/errors.html.twig).
   position: sticky + bottom: Ist die Seite höher als das Fenster (ein
   Terminkalender mit 12 Zeitfenstern zum Beispiel), bleibt die Zone am unteren Rand des
   Fensters haften, statt unterhalb des sichtbaren Bereichs zu verschwinden - ohne jemals
   den Inhalt zu verdecken, wenn die Seite kurz ist.
   z-index: über dem grauen Hintergrund des Buchungsdialogs (.modal-backdrop).
   ------------------------------------------------------------------------- */
.error-zone {
  position: sticky;
  bottom: 1rem;
  z-index: 1060;
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef; /* hellrosa */
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

/* die beiden großen Optionen der Seite "My area" des Patienten */
.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);
}

/* das Captcha-Bild (SVG von 150 x 50 Pixeln) */
.captcha-image svg {
  display: block;
  border: 1px solid #dee2e6;
  border-radius: 0.375rem;
}

Einige zusätzliche Einstellungen für [Bootstrap], dieselben wie in den anderen Versionen der Anwendung.

  • Zeilen 10–12: Eine buchbare Zeile im Kalender wird grün, wenn die Maus darüber fährt;
  • Zeilen 23–33: Der Fehlerbereich am Seitenende hat einen hellrosa Hintergrund. [position: sticky] mit [bottom: 1rem]: Ist die Seite höher als das Fenster (ein Kalender mit 12 Zeitfenstern), bleibt der Bereich am unteren Fensterrand verankert, statt unter der Bildlaufleiste zu verschwinden; ist die Seite kurz, bleibt er an Ort und Stelle, ohne etwas zu verdecken. [z-index]: Er erscheint über dem grauen Hintergrund des Buchungsfensters;
  • Zeilen 36–43: die beiden großen Karten von „Mein Bereich“, die aufleuchten, wenn die Maus darüber fährt;
  • Zeilen 46–50: das CAPTCHA-Bild mit einem Rahmen.

11.21.2. public/js/app.js

// =========================================================================
// public/js/app.js - das EINZIGE JavaScript der Anwendung.
// -------------------------------------------------------------------------
// Die gesamte Anwendung funktioniert ohne JavaScript. Dieses Skript fügt eine
// Annehmlichkeit hinzu: Vor dem Absenden eines Formulars mit dem Attribut
// data-confirmation="..." fragt ein modaler Dialog "Are you sure?" ab
// (der Dialog selbst steht in der Seite: templates/fragments/confirmation.html.twig).
// Ist JavaScript deaktiviert, wird das Formular einfach ohne
// Bestätigung gesendet - nichts geht kaputt (Prinzip der "Progressive Enhancement").
//
// Warum nicht window.confirm()? Sein Fenster lässt sich nicht gestalten, und seine
// Schaltflächen bleiben in der Sprache des Browsers, nicht in der der Seite.
// =========================================================================

(() => {
  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; // das Formular, das gesendet wird, wenn der Benutzer bestätigt
  let previousFocus = null; // das Element, das beim Schließen den Fokus zurückerhält

  function open(form) {
    pendingForm = form;
    previousFocus = document.activeElement;
    // textContent (und nicht innerHTML): Die Nachricht wird als TEXT angezeigt,
    // nie als HTML interpretiert
    message.textContent = form.dataset.confirmation;
    modal.classList.remove('d-none');
    // der Fokus geht auf "No": Ein unbedachter Druck auf die Eingabetaste löscht nichts
    noButton.focus();
  }

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

  // 1. wir fangen das Absenden der zu bestätigenden Formulare ab
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault();
      open(form);
    });
  });

  // 2. die Schaltflächen des Dialogs (Yes / No / Schließen-Kreuz)
  modal.addEventListener('click', (event) => {
    const action = event.target.closest('[data-action]')?.dataset.action;
    if (action === 'yes') {
      const form = pendingForm;
      close();
      // form.submit() sendet das Formular, OHNE das Ereignis
      // 'submit' erneut auszulösen: keine neue Bestätigungsabfrage
      form.submit();
    } else if (action === 'no') {
      close();
    } else if (event.target.classList.contains('modal')) {
      close(); // Klick auf den grauen Hintergrund, außerhalb des Dialogs
    }
  });

  // 3. Tastatur: Escape schließt den Dialog; Tab bleibt IM Dialog
  //    (sonst würde der Fokus auf die ausgegraute Seite dahinter gehen)
  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();
      }
    }
  });
})();

Das einzige [JavaScript] der Anwendung – das aus Beispiel 21 – mit einigen Ergänzungen. Die gesamte Anwendung funktioniert ohne [JavaScript]: Dieses Skript erhöht den Komfort, indem es vor dem Absenden eines Formulars mit dem Attribut [data-confirmation] eine Bestätigung einholt. Ist [JavaScript] deaktiviert, wird das Formular ohne Bestätigung abgesendet: Nichts geht kaputt (Prinzip der Progressive Enhancement).

  • Zeilen 15–19: Das Skript ist eine Funktion, die sofort nach ihrer Definition aufgerufen wird ([(() => { ... })()]); ihre Variablen sind für den Rest der Seite nicht sichtbar. Gibt es kein Bestätigungsfenster auf der Seite, tut es nichts;
  • Zeilen 26–35: Öffnen des Fensters: Das Formular, das bei Bestätigung durch den Benutzer abgesendet werden soll, wird gespeichert, und die Meldung des Formulars wird im Fenster angezeigt. [textContent], nicht [innerHTML]: Die Meldung wird als Text angezeigt und nie als HTML interpretiert. Der Fokus wechselt zur Schaltfläche „Nein“: Ein versehentliches Drücken der Eingabetaste löscht nichts;
  • Zeilen 37–43: Schließen des Fensters; der Fokus kehrt zu dem Element zurück, das ihn zuvor hatte;
  • Zeilen 46–51: Das Absenden jedes zu bestätigenden Formulars wird abgefangen ([preventDefault] verhindert es), und das Fenster öffnet sich;
  • Zeilen 54–67: die Schaltflächen des Fensters. Ein einziger Handler für das gesamte Fenster: [closest('[data-action]')] findet die angeklickte Schaltfläche oder das Element, das sie enthält. „Ja“ sendet das Formular über [form.submit()] ab, was das Ereignis [submit] nicht auslöst: Es wird keine erneute Bestätigung angefordert. Ein Klick auf den ausgegrauten Hintergrund außerhalb des Fensters schließt es;
  • Zeilen 71–86: die Tastatur. Esc schließt das Fenster; die Tabulatortaste bewegt den Fokus von einer Schaltfläche zur anderen ohne das Fenster zu verlassen (sonst würde er auf die ausgegraute Seite dahinter wechseln): Das erwarten Benutzer, die mit der Tastatur navigieren, und Screenreader.