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). Das ist die exakte Portierung der [Flask]-Anwendung der vorherigen Lektion nach [Laravel] (die ihrerseits aus den Versionen [Spring MVC] und [ASP.NET Core MVC] portiert wurde): dieselbe Datenbank, dieselben Geschäftsregeln, dieselben Seiten, dieselben URLs, dieselben Texte. Die HTML-Seiten werden vom Server mithilfe von [Blade]-Views erzeugt; der Datenbankzugriff erfolgt über [Eloquent].

Drei Benutzerrollen teilen sich die Anwendung:

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

Wichtige Verwaltungsregeln:

  • Keine Termine in der Vergangenheit;
  • Ein Zeitfenster kann pro Tag nur einmal reserviert werden;
  • Ein Patient hat jeweils nur einen bevorstehenden Termin;
  • Zwei Ärzte (oder zwei Clients) 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 Client wird zusammen mit seinen Terminen gelöscht;
  • Die Anmeldeseite ist gegen Bots geschützt (CAPTCHA, begrenzte Versuche), und das Anlegen eines Patientenkontos setzt voraus, dass zuvor auf dieser Seite das CAPTCHA gelöst wurde.

11.2. Die Anwendung verwenden

11.2.1. Die Anmeldeseite

Image

Die Seite enthält zwei Schaltflächen: Anmelden und Patientenkonto anlegen. Bei beiden müssen Sie die im Bild angezeigten Zeichen eingeben. Mit den Schaltflächen FR / EN wechseln Sie die Sprache:

Image

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

Image

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

Nach der Anmeldung gelangt der Administrator auf die 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, in dem die Patientendaten abgefragt werden. Dieses Fenster wird wie die übrige 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 Rückfrage aus (hier bei Dr. Pélissier, dessen Navigationsleiste die Verwaltungsmenüs nicht enthält):

Image

11.2.3. Das Patientenportal

Ein Patient (Rolle USER) gelangt zu „Mein Bereich“: Dort sieht er seinen 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 steht nicht einmal im Quellcode 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

Sein Dashboard 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 für einen anderen Tag oder einen anderen Arzt erklärt eine Meldung den Grund:

Image

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

Image

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

Image

11.2.4. Ärzte und Patienten verwalten

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

Image

Image

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

Image

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

Image

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

Image

11.2.5. Ein Patientenkonto anlegen

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

Image

Nach dem Anlegen des Kontos wird der Benutzer zur Anmeldeseite weitergeleitet, wobei sein Benutzername bereits ausgefüllt 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 zur Anmeldeseite um:

Image

11.3. Installation und Ausführung

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

11.3.1. Erforderliche Software

Sie benötigen lediglich drei Programme:

  • [PHP] 8.4 oder höher, mit der Erweiterung [pdo_mysql] (die Anwendung nutzt Funktionen, die in Version 8.4 eingeführt wurden, etwa [array_find]). Prüfen Sie die Installation in einem Terminal:
php -v
php -m

Der zweite Befehl listet die Erweiterungen auf: [pdo_mysql] sollte 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: Die Anwendung wurde damit getestet.

Als Editor empfehlen wir [Visual Studio Code] mit den Erweiterungen [PHP Intelephense] und [Laravel] (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-laravel] geöffnet ist (Sie müssen mit dem Internet verbunden sein):

composer install

[Composer] liest die Datei [composer.json] (siehe unten), lädt [Laravel], [firebase/php-jwt] und die Bibliotheken herunter, von denen sie abhängen, und erzeugt den Klassenlader [vendor/autoload.php].

11.3.3. Die Datenbank erstellen

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

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

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

11.3.4. Den Datenbankzugriff konfigurieren

Die gesamte Installationskonfiguration steht in der Datei [.env] (siehe weiter unten). 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 Konto [root] ein Passwort hat, tragen Sie es in dieser Datei in der Zeile [DB_PASSWORD=] ein. Eine Systemumgebungsvariable hat Vorrang vor der Datei (Beispiel 25): So können Sie das Passwort angeben, ohne es in eine Projektdatei zu schreiben.

11.3.5. Die Anwendung starten

Geben Sie in einem Terminalfenster, das im Ordner [rdvmedecins2-laravel] geöffnet ist, Folgendes ein:

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

  Press Ctrl+C to stop the server

Öffnen Sie anschließend die URL [http://localhost:8081] in einem Browser und beenden Sie die Anwendung mit [Ctrl-C]. Port 8081 erlaubt es, gleichzeitig ein Kursbeispiel (Port 8000) auszuführen.

11.3.6. Demokonten

Das Passwort jedes Kontos ist sein Benutzername; zusätzlich 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 von Frau Marie PELISSIER; heute ist ein Zeitfenster bereits von Frau Brigitte BISTROU gebucht. Buchen Sie ein Zeitfenster für Herrn Jean MARTIN und versuchen Sie dann, für ihn einen zweiten Termin zu buchen (wird abgelehnt). Menüs Ärzte und Patienten: hinzufügen, bearbeiten, löschen (Dr. PELISSIER, der Termine hat, kann nicht gelöscht werden);
  • [pelissier]: Sein Tageskalender wird direkt angezeigt; die Adresse [/doctors], von Hand eingegeben, liefert eine 403-Fehlerseite;
  • [martin]: Mein Bereich, sein Termin, der Kalender, in dem andere Patienten als „Belegt“ erscheinen; Mein Konto verwalten;
  • Anmeldeseite: Patientenkonto anlegen, 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:

  • [DB_LOG=true]: Die Serverkonsole zeigt jeden an die Datenbank gesendeten SQL-Befehl sowie jeden Schritt der Transaktionen an (Beispiel 28). Zum Beispiel beim Anzeigen eines Kalenders:
1
2
3
4
5
6
7
8
  select * from `doctors` order by `last_name` asc, `first_name` asc []
  select * from `users` where `users`.`id` in (2, 3, 4) []
  select * from `doctors` where `doctors`.`id` = ? limit 1 [1]
  select * from `users` where `users`.`id` in (2) []
  select * from `appointments` where `day` = ? and exists (select * from `slots` where `appointments`.`slot_id` = `slots`.`id` and `doctor_id` = ?) ["2026-09-26",1]
  select * from `clients` where `clients`.`id` in (3) []
  select * from `slots` where `doctor_id` = ? order by `start_hour` asc, `start_minute` asc [1]
  2026-09-26 18:50:14 /schedule .................................... ~ 0.10ms
  • [APP_DEBUG=true]: Eine unerwartete Ausnahme zeigt die [Laravel] Debug-Seite (Beispiel 03) mit der Ausnahmemeldung und dem Aufrufstapel an. 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 eine geänderte View wird bei der nächsten Anfrage neu kompiliert.

Der [Xdebug] Debugger erlaubt es außerdem, die Anwendung schrittweise aus [Visual Studio Code] heraus zu durchlaufen (Erweiterung [PHP Debug]): Er ist eine Erweiterung von [PHP], die separat installiert werden muss (siehe xdebug.org).

11.3.8. Ein Produktionsserver

Der Server [php artisan serve] ist nicht für den Produktionseinsatz gedacht. In der Produktion wird die Anwendung von einem Webserver ([nginx], [Apache]) ausgeliefert, der Anfragen an [PHP-FPM] weiterleitet, einen Prozessmanager ([PHP]). Das Wurzelverzeichnis der Site ist der Ordner [public]: Nur seine Dateien sind vom Browser aus erreichbar; die Ordner [storage] und [bootstrap/cache] müssen für den Server beschreibbar sein. Wir richten die Anwendung mit einigen Befehlen ein:

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

[key:generate] schreibt einen neuen Verschlüsselungsschlüssel in die Datei [.env]; die folgenden drei Befehle fassen die Konfiguration, die Routen und die kompilierten Views in wenigen Dateien zusammen, die schneller geladen werden als die Originale (dieser Vorgang muss nach jeder Änderung wiederholt werden). In der Datei [.env] müssen Sie außerdem den Produktionsmodus angeben, den geheimen Token-Schlüssel ändern und deklarieren, dass die Site über HTTPS ausgeliefert wird:

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

Eine geeignete Zufallszeichenfolge lässt sich mit [PHP] selbst erzeugen: [php -r "echo bin2hex(random_bytes(32));"].

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 den Start des Servers nicht: Der Fehler tritt auf der ersten Seite auf, die die Datenbank abfragt (die Anmeldeseite fragt die Datenbank nicht ab; der Anmeldevorgang selbst tut es). Mit [APP_DEBUG=true] wird der Fehler auf der [Laravel]-Debug-Seite angezeigt; in jedem Fall wird er im Protokoll [storage/logs/laravel.log] aufgezeichnet. Zum Beispiel bei einer nicht vorhandenen Datenbank:

[2026-09-26 18:55:12] local.ERROR: SQLSTATE[HY000] [1049] Unknown database 'dbunknown' (Connection: mysql, Host: 127.0.0.1, Port: 3306, Database: dbunknown, SQL: select * from `users` where `login` = admin limit 1) {"exception":"[object] (Illuminate\\Database\\QueryException(code: 1049): ...

Die häufigsten Meldungen:

[Failed opening required '.../vendor/autoload.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] von [PHP] ist nicht aktiviert (Datei [php.ini] oder Menü PHP / Erweiterungen von [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 [.env] eingetragen werden (siehe „Den Datenbankzugriff konfigurieren“)
[SQLSTATE[HY000] [1049] Unknown database 'dbrdvmedecins2']
Das Skript [database/dbrdvmedecins2.sql] wurde nicht ausgeführt
[No application encryption key has been specified.]
Die Variable [APP_KEY] in der Datei [.env] ist leer: [php artisan key:generate]
[JWT_SECRET must be at least 32 characters long (see .env).]
Der geheime Schlüssel für die Token in [.env] ist zu kurz
[Failed to listen on 127.0.0.1:8081 (reason: Address already in use)]
Port 8081 wird bereits verwendet (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 artisan serve] oder [nginx] + [PHP-FPM]), der sie an [Laravel] über die Datei [public/index.php] weiterleitet. Jede Anfrage durchläuft zunächst die Middleware-Schichten (siehe das Kapitel über den Lebenszyklus): die Sprache der Anfrage ([SetLanguage]), die Cookies, die Sitzung, den CSRF-Schutz und anschließend die Authentifizierung: Der Benutzer wird anhand des JWT-Tokens in seinem Cookie identifiziert, und geschützte Seiten werden Besuchern ohne Zugriffsrecht verweigert ([Authenticate], [RequireRoles]);
  • [Http/Controllers]: 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; [Http/Requests]: Formularvalidierung;
  • [Auth]: Token, JWT, CAPTCHA, Versuchsbegrenzung und der Pass für die Kontoerstellung;
  • [Web]: was den Controllern gemeinsam ist: der Cache und die Fassade [ApplicationModel], Flash-Meldungen und einige Hilfsfunktionen; [Views]: View-Templates;
  • [Business]: Geschäftsregeln und Transaktionen;
  • [Dao]: die DAO-Schicht, eine Klasse pro Tabelle;
  • [Models]: die [Eloquent]-Modelle, die die DAO-Schicht aus der Datenbank liest und in sie schreibt; [Domain]: die Kalenderobjekte, die von der Geschäftsschicht berechnet werden;
  • [resources/views]: die [Blade]-Views, die die HTML-Seiten erzeugen; [lang]: die Wörterbücher; [public]: das Stylesheet, das Seitenskript und [Bootstrap];
  • [bootstrap/app.php] und [app/Providers/AppServiceProvider.php] fügen alles zusammen; [.env] und der Ordner [config]: die Konfiguration.

Der Anwendungsordner (ohne [vendor] und den Inhalt von [storage]):

rdvmedecins2-laravel/
├── app/
│   ├── Auth/
│   │   ├── AttemptLimiter.php
│   │   ├── AuthService.php
│   │   ├── Captcha.php
│   │   ├── CaptchaDrawing.php
│   │   ├── CaptchaService.php
│   │   ├── ConnectedUser.php
│   │   ├── InvalidSession.php
│   │   ├── README.md
│   │   └── RegistrationPass.php
│   ├── Business/
│   │   ├── Business.php
│   │   ├── BusinessException.php
│   │   ├── BusinessService.php
│   │   ├── Dates.php
│   │   ├── Descriptor.php
│   │   ├── PersonData.php
│   │   └── README.md
│   ├── Dao/
│   │   ├── AppointmentDao.php
│   │   ├── ClientDao.php
│   │   ├── DoctorDao.php
│   │   ├── PersonDao.php
│   │   ├── README.md
│   │   ├── SlotDao.php
│   │   └── UserDao.php
│   ├── Domain/
│   │   ├── DoctorDaySchedule.php
│   │   ├── DoctorDaySlot.php
│   │   └── README.md
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── AuthController.php
│   │   │   ├── ClientsController.php
│   │   │   ├── DoctorsController.php
│   │   │   ├── LanguageController.php
│   │   │   ├── PatientAreaController.php
│   │   │   ├── PersonsController.php
│   │   │   ├── RegistrationController.php
│   │   │   └── ScheduleController.php
│   │   ├── Middleware/
│   │   │   ├── CheckRegistrationPass.php
│   │   │   ├── RequireRoles.php
│   │   │   └── SetLanguage.php
│   │   ├── README.md
│   │   └── Requests/
│   │       ├── MyAccountRequest.php
│   │       ├── PersonFieldsRequest.php
│   │       ├── PersonRequest.php
│   │       └── RegistrationRequest.php
│   ├── Models/
│   │   ├── Appointment.php
│   │   ├── Client.php
│   │   ├── Doctor.php
│   │   ├── Person.php
│   │   ├── README.md
│   │   ├── Role.php
│   │   ├── Slot.php
│   │   └── User.php
│   ├── Providers/
│   │   └── AppServiceProvider.php
│   ├── Views/
│   │   ├── AppointmentView.php
│   │   ├── BookingView.php
│   │   ├── OptionView.php
│   │   ├── PersonKeys.php
│   │   ├── README.md
│   │   ├── ScheduleRow.php
│   │   └── ScheduleView.php
│   └── Web/
│       ├── ApplicationModel.php
│       ├── Flash.php
│       ├── Message.php
│       ├── README.md
│       └── Utils.php
├── artisan
├── bootstrap/
│   ├── app.php
│   ├── cache/
│   └── providers.php
├── composer.json
├── config/
│   ├── app.php
│   ├── auth.php
│   ├── hashing.php
│   ├── rdvmedecins.php
│   └── session.php
├── database/
│   ├── dbrdvmedecins2.sql
│   └── README.md
├── .env
├── .env.example
├── lang/
│   ├── en.json
│   └── fr.json
├── public/
│   ├── css/
│   │   └── styles.css
│   ├── index.php
│   ├── js/
│   │   └── app.js
│   └── lib/
│       └── bootstrap/
├── README.md
├── resources/
│   └── views/
│       ├── account.blade.php
│       ├── area.blade.php
│       ├── components/
│       │   ├── captcha.blade.php
│       │   ├── field.blade.php
│       │   └── person-fields.blade.php
│       ├── error.blade.php
│       ├── fragments/
│       │   ├── booking.blade.php
│       │   ├── confirmation.blade.php
│       │   ├── errors.blade.php
│       │   ├── navbar.blade.php
│       │   └── success.blade.php
│       ├── layout.blade.php
│       ├── login.blade.php
│       ├── persons/
│       │   ├── form.blade.php
│       │   └── list.blade.php
│       ├── README.md
│       ├── registration.blade.php
│       └── schedule.blade.php
├── routes/
│   └── web.php
└── storage/

Dies ist die Struktur einer Standardanwendung [Laravel] – derjenigen, die der Befehl [composer create-project laravel/laravel] (Beispiel 01) erzeugt –, bereinigt um hier nicht benötigte Elemente (Tests, Migrationen, [JavaScript]-Build-Tools usw.). Es gibt zwei Unterschiede zu den Beispielen: Die Anwendung hat ihren eigenen Ordner [vendor] (die Beispiele teilten sich den Ordner [examples]), und es gibt einen Service Provider ([app/Providers/AppServiceProvider.php]), der weiter unten besprochen wird. Die Klassen der Anwendung sind im Ordner [app] nach der PSR-4-Regel organisiert (Beispiel 01): Die Klasse [App\Business\BusinessService] liegt in der Datei [app/Business/BusinessService.php]. [Laravel] schreibt keinen dieser Ordner vor (Beispiel 06): [Http], [Models], und [Providers] sind die gebräuchlichen; die anderen ([Auth], [Dao], [Business] ...) gehören zur Schichtenarchitektur aus Beispiel 28. [Bootstrap] ist diesmal Teil der Anwendung (Ordner [public/lib/bootstrap]): Die Fallstudie ist eigenständig.

11.5. Die Datenbank

Die Datenbank [dbrdvmedecins2] hat 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 der einzelnen Ärzte;
  • [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 Client 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 erstellt eine Zeile in [users] für jeden Arzt (Rolle DOCTOR)
--      und für jeden Client (Rolle USER):
--        - login        = Nachname in Kleinbuchstaben
--        - password     = Nachname in Kleinbuchstaben, mit bcrypt gehasht (10 Runden)
--        - Anzeigename = Vorname + Nachname
--
--   4. Eindeutigkeitsbedingungen, alle BENANNT (die Anwendung erkennt
--      den Namen der verletzten Bedingung in der MySQL-Fehlermeldung):
--        - unq_users_login                   : ein Login gehört nur zu einem Konto;
--        - unq_doctors_first_name_last_name  : zwei Ärzte können nicht denselben
--                                              Vor- und Nachnamen haben;
--        - unq_clients_first_name_last_name  : dasselbe für die Clients.
--      Achtung: die Kollation utf8mb4_unicode_ci vergleicht ohne Rücksicht auf
--      Groß-/Kleinschreibung und Akzente - "Hélène DUPONT" und "helene dupont"
--      gelten daher als identisch.
--
-- Die Tabelle [users] muss nun VOR [doctors] und [clients] erstellt werden
-- (diese 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;

-- Reihenfolge beim Löschen: 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 können 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 Client und ein Client pro Konto
  CONSTRAINT unq_clients_user UNIQUE (`user`),
  -- zwei Clients können 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 Clients 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 kann am selben Tag nur einmal gebucht werden
  CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
);

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

-- die Benutzer: mit bcrypt gehashte Passwörter (10 Salt-Runden)
--   admin/admin (ADMIN)
--   ein Konto DOCTOR pro Arzt, ein Konto USER pro Client
--   (das Demokonto user/user entfällt: ein Konto USER ist
--   nun IMMER das Konto eines Clients, der buchen und das Konto verwalten kann)
--   (Login = Passwort = 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 ermittelt,
-- 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 von Arzt PELISSIER (doctor_id = 1): von 8:00 bis 12:00 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 von Arzt TATOU (doctor_id = 2): von 14:00 bis 18:00 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, damit ein belegtes Zeitfenster sofort im Terminkalender zu sehen ist
INSERT INTO appointments (day, slot_id, client_id) VALUES
  (CURDATE(), 2, 3);
  • Zeile 33: Die Datenbank wird erstellt, 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 erstellt; 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: users: ein Login, ein Passwort, gehasht mit [bcrypt] (Beispiel 25), der Anzeigename nach der Anmeldung und die Rolle ([ADMIN], [DOCTOR], oder [USER]). Der 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 darstellt (Beispiel 28). Die Spalte [user] ist ein Fremdschlüssel , der auf [users(id)] verweist: Die Datenbank weist jeden Wert zurück, der nicht die ID eines vorhandenen Benutzers ist. Da [user] in SQL ein reserviertes Wort ist, steht es in Backticks. 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 Namensvettern). Alle Constraints sind benannt: Die Anwendung erkennt einen verletzten Constraint an seinem Namen;
  • Zeilen 77–89: Die Tabelle [clients] hat exakt 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. Der Constraint [unq1_appointments] verhindert, dass dasselbe Zeitfenster am selben Tag zweimal gebucht wird: Die Datenbank erzwingt diese Regel, selbst wenn zwei Benutzer gleichzeitig versuchen, es zu buchen;
  • Zeilen 130–140: Demo-Benutzer, deren Passwort ihr Login ist. Die Hashes beginnen mit [$2b$10$]: dem Algorithmus ([bcrypt], Variante [2b]) und dem Kostenfaktor (10). Es folgen das Salt und der Hash. Diese Hashes wurden von der [Flask]-Version der Anwendung berechnet; [PHP] schreibt eigene mit dem Präfix [$2y$], prüft aber beide gleichermaßen (siehe [config/hashing.php], unten);
  • Zeilen 144–147: Die Spalte [user] jedes Arztes wird über eine Unterabfrage anhand des Logins ermittelt, statt die Werte der Primärschlüssel vorauszusetzen;
  • Zeilen 170–171: ein bereits für heute ([CURDATE()]) vereinbarter Termin im zweiten Zeitfenster von Dr. PELISSIER für Frau BISTROU: Der Kalender zeigt somit sofort ein gebuchtes Zeitfenster.

Anders als bei [Laravel] üblich wird die Datenbank nicht über Migrationen ([PHP]-Klassen, die die Erstellung und Weiterentwicklung der Tabellen beschreiben und von [php artisan migrate] ausgeführt werden) erstellt: Sie wird mit den anderen Versionen der Anwendung geteilt, und das SQL-Skript ist allen gemeinsam.

11.6. Die Projektkonfiguration

11.6.1. composer.json

{
    "name": "rdvmedecins/rdvmedecins2-laravel",
    "description": "RdvMedecins: medical appointment booking, HTML pages built by the server (Laravel + Blade)",
    "type": "project",
    "license": "MIT",
    "require": {
        "php": "^8.4",
        "ext-pdo_mysql": "*",
        "laravel/framework": "^13.33",
        "firebase/php-jwt": "^7.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "app/"
        }
    },
    "scripts": {
        "post-autoload-dump": [
            "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
            "@php artisan package:discover --ansi"
        ]
    },
    "config": {
        "optimize-autoloader": true,
        "sort-packages": true
    },
    "minimum-stability": "stable",
    "prefer-stable": true
}
  • Zeilen 6–11: die von der Anwendung benötigten Bibliotheken und die Einschränkungen, die sie erfüllen müssen. [^13.33] bedeutet „Version 13.33 oder eine neuere Version derselben Hauptversion 13“: [Composer] akzeptiert Versionen, die Fehler beheben oder Funktionen hinzufügen, nicht aber solche, die die Anwendung beschädigen könnten (Version 14). Die Zeilen [php] und [ext-pdo_mysql] beziehen sich nicht auf Bibliotheken, sondern auf Anforderungen an die Umgebung: [Composer] verhindert die Installation, wenn die Version von [PHP] oder die Erweiterung nicht passt, statt die Anwendung später scheitern zu lassen;
  • Zeilen 12–16: die PSR-4-Regel der Anwendung: Klassen im Namespace [App] liegen im Ordner [app] (Beispiel 01: In den Beispielen deklarierte [bootstrap/app.php] diese Regel selbst gegenüber dem Klassenlader über [addPsr4]);
  • Zeilen 18–21: Befehle, die [Composer] nach dem Erstellen des Klassenladers ausführt: [Laravel] listet die Service Provider der installierten Bibliotheken auf ([package:discover], in [bootstrap/cache]).

[composer install] installiert die Versionen, die diese Einschränkungen 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] sucht dagegen die neuesten Versionen, die [composer.json] zulässt, und aktualisiert [composer.lock]. Der Befehl [composer show] listet auf, was im Ordner [vendor] installiert ist.

11.6.2. .env

# =========================================================================
# .env: die Einstellungen, die für DIESE Installation spezifisch sind (gelesen mit env('NAME') in den
# Dateien des Ordners config). Diese Datei wird nie veröffentlicht: sie enthält
# Geheimnisse. Eine Systemumgebungsvariable hat Vorrang vor ihr.
# =========================================================================
APP_NAME=RdvMedecins
# local: Entwicklung; production: in Produktion
APP_ENV=local
# Verschlüsselungsschlüssel von Laravel (Cookies, Session). In Produktion:
# php artisan key:generate (schreibt einen neuen Schlüssel in diese Datei)
APP_KEY=base64:+UmYSB3+TOKSr/f/fiqPCyo5IXFgXOLrvO1II52r+q4=
# true: eine unerwartete Exception zeigt die Debug-Seite von Laravel mit ihrem
# Aufrufstapel (NIEMALS in Produktion); false: die 500-Fehlerseite der Anwendung
APP_DEBUG=true
APP_URL=http://localhost:8081

# ––– die MySQL-Datenbank [dbrdvmedecins2] (Skript: database/dbrdvmedecins2.sql):
# der Server, sein Port, die Datenbank, der Benutzer und sein Passwort (die von
# Laragon: root, ohne Passwort)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=dbrdvmedecins2
DB_USERNAME=root
DB_PASSWORD=
# true: die an die Datenbank gesendeten SQL-Anweisungen werden in der Konsole angezeigt
DB_LOG=true

# ––– die Session von Laravel (Flash-Meldungen, CSRF-Token, Eingaben zur
# erneuten Anzeige): in einem VERSCHLÜSSELTEN Cookie gespeichert, der Server behält nichts
SESSION_DRIVER=cookie
SESSION_LIFETIME=120
# ––– der Cache (Listen von Ärzten und Clients, CAPTCHAs, Versuchs-
# zähler, Pässe): Dateien in storage/framework/cache
CACHE_STORE=file
# das Log: storage/logs/laravel.log
LOG_CHANNEL=single

# ––– Authentifizierung (siehe config/rdvmedecins.php)
# geheimer Schlüssel der JWT-Token: mindestens 32 Zeichen (HMAC-SHA256)
JWT_SECRET=ef1cfc9709f10b5b5d183b4deb6d5dbbe69518629c3b12a8
# Gültigkeitsdauer eines Tokens in Minuten (120 min = 2 h)
JWT_DURATION_MINUTES=120
# true in Produktion (über HTTPS bereitgestellte Website): Cookies reisen nie unverschlüsselt
COOKIE_SECURE=false

# ––– Schutz vor Robotern (siehe app/Auth/AttemptLimiter.php)
LOGIN_MAX_FAILURES=5
LOGIN_BLOCK_MINUTES=15
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 geheim (die Schlüssel). Sie wird nie veröffentlicht; die Datei [.env.example], die keine Geheimnisse enthält, dient als Vorlage.

  • Zeile 11: der Verschlüsselungsschlüssel von [Laravel]: Er verschlüsselt die Cookies (Beispiel 20), einschließlich des Sitzungs-Cookies. Der Befehl [php artisan key:generate] schreibt einen neuen;
  • Zeile 14: In der Entwicklung zeigt eine unerwartete Ausnahme die [Laravel]-Debug-Seite an; in der Produktion ([false]) die 500-Fehlerseite der Anwendung;
  • Zeilen 20–25: die Verbindung zur Datenbank (Beispiel 28);
  • Zeile 31: Die [Laravel] -Sitzung (Beispiel 23) wird in einem verschlüsselten Cookie statt in Dateien auf dem Server gespeichert. Die Anwendung legt dort sehr wenige Informationen ab (Flash-Meldungen, das CSRF-Token, erneut anzuzeigende Formulardaten): Ein einziges Cookie genügt, und der Server muss zwischen Anfragen nichts mehr speichern. [Laravel] verwendet zwei Cookies: [rdvmedecins_session] enthält die Sitzungs-ID, und ein zweites Cookie – benannt nach dieser ID – enthält die Sitzungsdaten;
  • Zeile 35: Der Cache (Beispiel 20) wird in Dateien im Ordner [storage/framework/cache] gespeichert. Die Anwendung legt dort Listen der Ärzte und Clients, CAPTCHAs, Versuchszähler und Zugriffstoken ab – Informationen, die von allen Anfragen gemeinsam genutzt werden müssen. Bei mehreren Servern würde ein gemeinsamer Cache wie [Redis] verwendet;
  • Zeilen 41–48: anwendungsspezifische Einstellungen: die JWT-Token (Beispiel 25) und der Bot-Schutz (Beispiel 27).

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

Die Dateien im Ordner [config] ergänzen die Standardkonfiguration von [Laravel] (Beispiel 25): Nur die Schlüssel, die sie schreiben, werden geändert.

<?php
// config/app.php: diese Datei ERGÄNZT die Standardkonfiguration von Laravel
// (vendor/laravel/framework/config/app.php): nur die hier geschriebenen Schlüssel ändern sich
return [
    // die Standardsprache der Oberfläche (siehe lang/fr.json, lang/en.json) und die
    // Fallback-Sprache (sie wird nur von den PHP-Dateien des Ordners lang verwendet: ein
    // in einem JSON-Wörterbuch fehlender Schlüssel wird unverändert angezeigt)
    'locale' => 'en',
    'fallback_locale' => 'en',

    // die Zeitzone: die der Arztpraxis. Sie legt das aktuelle Datum fest
    // (kein Termin in der Vergangenheit, siehe app/Business/Dates.php)
    'timezone' => 'Europe/Paris',
];
  • Zeilen 8–9: die Standardsprache der Oberfläche (Beispiel 22) und die Ersatzsprache (die nur für die [PHP]-Dateien im Ordner [lang] verwendet wird; siehe Beispiel 22);
  • Zeile 13: die Zeitzone. Standardmäßig arbeitet [Laravel] in Koordinierter Weltzeit (UTC); 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.
1
2
3
4
5
6
7
8
9
<?php
// config/session.php: die Session von Laravel (ergänzt die Standardkonfiguration).
// Treiber [cookie] (siehe .env, SESSION_DRIVER): die Sitzungsdaten (Flash-
// Meldungen, CSRF-Token, erneut anzuzeigende Eingaben) reisen in einem VERSCHLÜSSELTEN Cookie
return [
    'cookie' => 'rdvmedecins_session',
    // die Cookies der Anwendung reisen in Produktion nur über HTTPS
    'secure' => (bool) env('COOKIE_SECURE', false),
];

Der Name des Sitzungs-Cookies und die Option [secure] für Sitzungs-Cookies, aus der Datei [.env] gelesen ([(bool)] wandelt den Wert in einen booleschen Wert um; [env] versteht bereits [false] und [true]).

<?php
// config/hashing.php: Passwort-Hashing (ergänzt die Standardkonfiguration)
return [
    'driver' => 'bcrypt',
    'bcrypt' => [
        // 10 Runden, wie die Hashes des SQL-Skripts
        'rounds' => 10,
        // Standardmäßig prüft Laravel, dass ein gespeicherter Hash tatsächlich ein bcrypt-
        // Hash ist... so wie PHP ihn schreibt ($2y$). Aber die Datenbank dbrdvmedecins2 wird
        // mit den Python- ($2b$) und Java-Versionen ($2a$) der Anwendung geteilt,
        // deren Hashes PHP sehr wohl verifiziert, ohne sie als
        // "bcrypt" zu erkennen. Daher ist diese Prüfung deaktiviert
        'verify' => false,
    ],
];

Passwort-Hashing: [bcrypt], 10 Runden, wie die Hashes im SQL-Skript. Zeile 13 deaktiviert eine Prüfung, die [Laravel] standardmäßig durchführt: Bevor ein Passwort mit einem Hash verglichen wird, wird geprüft, ob der Hash tatsächlich mit dem konfigurierten Algorithmus erzeugt wurde, wie ihn [PHP] schreibt ([$2y$]). Die Hashes in der Datenbank, die von [Python] ([$2b$]) oder von [Java] ([$2a$]) erzeugt wurden, würden diese Prüfung nicht bestehen, obwohl [PHP] sie problemlos verifizieren kann. Das ist der Preis dafür, eine Datenbank mit anderen Anwendungen zu teilen.

<?php
// config/auth.php: Authentifizierung (ergänzt die Standardkonfiguration)
return [
    // der standardmäßig verwendete "Guard": der, der das JWT-Token aus dem Cookie liest
    'defaults' => [
        'guard' => 'jwt',
    ],
    'guards' => [
        // ein Guard mit dem Treiber [jwt], definiert durch AppServiceProvider (Auth::viaRequest)
        'jwt' => [
            'driver' => 'jwt',
        ],
    ],
];

Der Guard [jwt], der Standard-Guard für den Treiber [jwt]: genau wie in Beispiel 25.

11.6.4. config/rdvmedecins.php

<?php
// config/rdvmedecins.php: die für die Anwendung spezifischen Einstellungen, gelesen mit
// config('rdvmedecins.xxx'). Die Werte stammen aus der Datei .env; der zweite
// Parameter von env() ist der Standardwert
return [
    'jwt' => [
        // geheimer Schlüssel der JWT-Token: mindestens 32 Zeichen (HMAC-SHA256)
        'secret' => env('JWT_SECRET', ''),
        // Gültigkeitsdauer eines Tokens in Minuten; das Cookie, das es trägt,
        // hat dieselbe Lebensdauer
        'duration' => (int) env('JWT_DURATION_MINUTES', 120),
    ],

    // true: die an die Datenbank gesendeten SQL-Anweisungen werden in der Konsole angezeigt
    'db_log' => (bool) env('DB_LOG', false),

    // true in Produktion (HTTPS): die Cookies werden nie unverschlüsselt gesendet
    'cookie_secure' => (bool) env('COOKIE_SECURE', false),

    // Schutz vor Robotern (siehe app/Auth/AttemptLimiter.php):
    // login: erlaubte Fehlschläge für denselben Login von derselben IP-Adresse,
    // danach Sperre für diese Dauer (die gesamte IP-Adresse wird ebenfalls gesperrt,
    // wenn sie 5-mal mehr Fehlschläge ansammelt, alle Logins zusammen)
    'login_max_failures' => (int) env('LOGIN_MAX_FAILURES', 5),
    'login_block_minutes' => (int) env('LOGIN_BLOCK_MINUTES', 15),
    // Erstellung von Client-Konten: maximal erstellte Konten pro Stunde und pro IP-
    // Adresse. In einem Kursraum gehen oft alle Rechner über dieselbe Adresse nach außen:
    // bei Bedarf erhöhen
    'registration_max_per_hour' => (int) env('REGISTRATION_MAX_PER_HOUR', 10),
];

Anwendungsspezifische Einstellungen, gelesen von [config('rdvmedecins.jwt.secret')], [config('rdvmedecins.login_max_failures')] ... Jeder Wert stammt aus der Datei [.env], mit einem Standardwert. Zur Erinnerung die Regel (Beispiel 25): [env] wird nur in Dateien im Ordner [config] aufgerufen; der restliche Code liest [config(...)]. Sobald die Konfiguration zwischengespeichert ist ([php artisan config:cache]), wird die Datei [.env] überhaupt nicht mehr gelesen.

11.7. Beim Start der Anwendung

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

Die Datei [public/index.php] ist die aus den Beispielen (Beispiel 01), mit dem Pfad zum Ordner [vendor] der Anwendung:

<?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), niemals der Code der Anwendung

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

// Class Loader von Composer
require __DIR__.'/../vendor/autoload.php';

// die Anwendung, erstellt von bootstrap/app.php, verarbeitet die aktuelle Anfrage
/** @var Application $app */
$app = require_once __DIR__.'/../bootstrap/app.php';
$app->handleRequest(Request::capture());

Die Datei [bootstrap/providers.php] ist neu:

1
2
3
4
5
6
7
8
9
<?php
// bootstrap/providers.php: die Service Provider der
// Anwendung, die zu Beginn jeder Anfrage geladen werden (siehe app/Providers)

use App\Providers\AppServiceProvider;

return [
    AppServiceProvider::class,
];

Sie gibt die Liste der Service Provider der Anwendung zurück. Ein Service Provider ist eine Klasse, von der [Laravel] zu Beginn jeder Anfrage zwei Methoden aufruft: [register], die Services im Container registriert (Beispiel 06), und anschließend, sobald alle Provider registriert sind, [boot], die jeden Service verwenden kann. [Laravel] selbst besteht aus Service Providern (einer für die Sitzung, einer für Views, einer für die Datenbank usw.), ebenso die meisten dafür geschriebenen Bibliotheken. In den Beispielen haben wir diese Deklarationen in [bootstrap/app.php] ([withSingletons], [booted]) geschrieben: Das ist für ein paar Zeilen praktisch; eine vollständige Anwendung fasst sie in einem Service Provider zusammen, per Konvention [AppServiceProvider].

11.7.2. app/Providers/AppServiceProvider.php

<?php
// =========================================================================
// app/Providers/AppServiceProvider.php: der SERVICE PROVIDER der Anwendung
// (deklariert in bootstrap/providers.php). Er ist in einer
// Laravel-Anwendung der übliche Ort für das, was die Beispiele in bootstrap/app.php geschrieben haben:
//   - $singletons: die gemeinsam genutzten Services (siehe Beispiel 06);
//   - boot(): was zu Beginn jeder Anfrage getan werden muss, sobald alle
//     Services registriert sind: der JWT-Authentifizierungstreiber, die allen Views
//     gemeinsamen Variablen, die Anzeige der SQL-Anweisungen.
// =========================================================================

namespace App\Providers;

use App\Auth\AuthService;
use App\Auth\CaptchaService;
use App\Auth\AttemptLimiter;
use App\Auth\RegistrationPass;
use App\Dao\ClientDao;
use App\Dao\SlotDao;
use App\Dao\DoctorDao;
use App\Dao\AppointmentDao;
use App\Dao\UserDao;
use App\Business\BusinessService;
use App\Web\ApplicationModel;
use Illuminate\Database\Events\QueryExecuted;
use Illuminate\Database\Events\TransactionBeginning;
use Illuminate\Database\Events\TransactionCommitted;
use Illuminate\Database\Events\TransactionRolledBack;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Cookie;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\View;
use Illuminate\Support\ServiceProvider;
use Illuminate\View\View as TheView;

class AppServiceProvider extends ServiceProvider
{
    // -----------------------------------------------------------------------
    // die gemeinsam genutzten Services: für jede dieser Klassen erstellt der Container von Laravel
    // nur EIN Objekt (pro Anfrage), das allen gegeben wird, die es anfordern - den
    // Controllern über ihren Konstruktor. Der Container baut die
    // Abhängigkeiten jedes Objekts selbst (BusinessService erhält so seine fünf DAOs): das ist
    // Dependency Injection.
    // -----------------------------------------------------------------------
    public array $singletons = [
        DoctorDao::class => DoctorDao::class,
        ClientDao::class => ClientDao::class,
        SlotDao::class => SlotDao::class,
        AppointmentDao::class => AppointmentDao::class,
        UserDao::class => UserDao::class,
        BusinessService::class => BusinessService::class,
        ApplicationModel::class => ApplicationModel::class,
        AuthService::class => AuthService::class,
        CaptchaService::class => CaptchaService::class,
        AttemptLimiter::class => AttemptLimiter::class,
        RegistrationPass::class => RegistrationPass::class,
    ];

    public function boot(): void
    {
        // ––– der Guard-Treiber [jwt] (siehe config/auth.php, Beispiel 25): eine
        // Funktion, die die Anfrage erhält und den authentifizierten Benutzer zurückgibt, oder null
        // für einen anonymen Besucher. Laravel ruft sie beim ersten Auth::user() der
        // Anfrage auf; wenn sie einen Benutzer gefunden hat, behält Laravel ihn für den Rest der
        // Anfrage (andernfalls ruft es die Funktion bei jedem Auth::user() erneut auf)
        Auth::viaRequest('jwt', function (Request $request) {
            $token = $request->cookie(AuthService::COOKIE);
            if (! is_string($token) || $token === '') {
                return null;
            }
            $user = app(AuthService::class)->currentUser($token);
            if ($user === null) {
                // ein vorhandenes, aber ungültiges Cookie (abgelaufenes oder gefälschtes Token): wir löschen es
                Cookie::queue(AuthService::clearingCookie());
            }
            return $user;
        });

        // ––– die Variablen, die ALLEN Views gemeinsam sind (siehe Beispiel 15): ein
        // "View Composer" wird vor dem Aufbau jeder View ausgeführt ('*')
        //   - user     : der angemeldete Benutzer (oder null) für die Navigationsleiste;
        //   - language : "fr" oder "en".
        View::composer('*', function (TheView $view) {
            $view->with(['user' => Auth::user(), 'language' => App::getLocale()]);
        });

        // ––– DB_LOG=true (Datei .env): jede SQL-Anweisung und jeder Schritt einer
        // Transaktion wird in der Serverkonsole angezeigt (siehe Beispiel 28)
        if (config('rdvmedecins.db_log')) {
            DB::listen(fn (QueryExecuted $q) => error_log($q->sql.' '.json_encode($q->bindings, JSON_UNESCAPED_UNICODE)));
            Event::listen(TransactionBeginning::class, fn () => error_log('BEGIN'));
            Event::listen(TransactionCommitted::class, fn () => error_log('COMMIT'));
            Event::listen(TransactionRolledBack::class, fn () => error_log('ROLLBACK'));
        }
    }
}
  • Zeilen 48–60: gemeinsam genutzte Services. Die Eigenschaft [$singletons] eines Service Providers wird von [Laravel] gelesen, das jedes ihrer Paare [interface => class] als Singleton deklariert (Beispiel 06): Das entspricht [withSingletons]. Hier wird jede Klasse einzeln deklariert. Denken Sie daran, dass ein Singleton nur für die Dauer einer einzelnen Anfrage existiert (Beispiel 06): Der Vorteil hier ist, dass alle Controller, Middleware und Services derselben Anfrage dasselbe [ApplicationModel], denselben [BusinessService] nutzen ... Die DAO-Instanzen müssten nicht einmal deklariert werden: Der Container weiß, wie er eine nicht deklarierte Klasse erzeugt (Beispiel 06), würde dafür aber für jede Anforderung ein neues Objekt anlegen;
  • Zeilen 69–80: der Guard-Treiber [jwt] (Beispiel 25). Das Token wird aus dem Cookie [rdvmedecins_jwt] gelesen (der Name ist eine Konstante von [AuthService]) und von [AuthService::currentUser] verifiziert. Ein Cookie, das existiert, dessen Token aber nicht mehr gültig ist, wird gelöscht. [Laravel] behält den gefundenen Benutzer für die gesamte Anfrage; solange es keinen gefunden hat (ein anonymer Besucher), ruft es die Funktion bei jeder Anfrage auf, was keine Auswirkungen hat: Ein Cookie zu lesen und gegebenenfalls eine Signatur zu prüfen, ist sehr schnell;
  • Zeilen 86–88: für alle Views gemeinsame Variablen (Beispiel 15): der angemeldete Benutzer (oder [null]) für die Navigationsleiste und die Sprache der Anfrage. Das Muster ['*'] trifft auf alle Views zu: Der Composer wird für jede aufgerufen, einschließlich Fragmenten und Komponenten;
  • Zeilen 92–99: Anzeige der SQL-Befehle und Transaktionen in der Konsole (Beispiel 28), wenn [DB_LOG=true]. [error_log] schreibt in das Fehlerprotokoll von [PHP] – also zusammen mit [php artisan serve] in die Serverkonsole.

11.7.3. bootstrap/app.php

<?php
// =========================================================================
// bootstrap/app.php: der Aufbau der Anwendung (siehe Beispiel 01):
//   1. die Routen (routes/web.php);
//   2. die Middlewares: Sprache, Cookies, Authentifizierung, Rollen;
//   3. die Exceptions: wie Fehler zu HTML-Seiten werden.
// Die gemeinsam genutzten Services werden von app/Providers/AppServiceProvider.php deklariert.
// =========================================================================

use App\Auth\AuthService;
use App\Auth\InvalidSession;
use App\Http\Middleware\RequireRoles;
use App\Http\Middleware\SetLanguage;
use App\Http\Middleware\CheckRegistrationPass;
use App\Web\Flash;
use Illuminate\Auth\AuthenticationException;
use Illuminate\Auth\Middleware\Authenticate;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Http\Exceptions\HttpResponseException;
use Illuminate\Http\Request;
use Illuminate\Support\ViewErrorBag;
use Illuminate\Validation\ValidationException;
use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(web: __DIR__.'/../routes/web.php')

    ->withMiddleware(function (Middleware $middleware): void {
        // die Sprache der Anfrage: eine GLOBALE Middleware, für alle Anfragen
        // vor denen der Gruppe [web] ausgeführt (siehe app/Http/Middleware/SetLanguage.php)
        $middleware->append(SetLanguage::class);

        // Laravel VERSCHLÜSSELT alle Cookies, die es setzt. Zwei Ausnahmen: das
        // JWT-Token, das bereits signiert ist; die Sprache, die gelesen wird, bevor die Cookies entschlüsselt werden
        $middleware->encryptCookies(except: [AuthService::COOKIE, SetLanguage::COOKIE]);

        // -------------------------------------------------------------------
        // DIE ZUGRIFFSREGEL: alle Routen der Gruppe [web] erfordern einen
        // authentifizierten Benutzer (Middleware Authenticate, Alias [auth]) - außer
        // denen, die sie ausdrücklich entfernen (withoutMiddleware, siehe
        // routes/web.php: Login, Kontoerstellung, Sprachwahl).
        // Das ist die Regel "alles ist verboten, außer was erlaubt ist": eine später
        // hinzugefügte Route, deren Schutz man vergessen hätte, ist trotzdem geschützt.
        // -------------------------------------------------------------------
        $middleware->web(append: [Authenticate::class]);

        // ein nicht authentifizierter Besucher, der eine geschützte Seite anfordert: ab zur
        // Login-Seite. Hatte er ein Token-Cookie, ist sein Token nicht mehr
        // gültig (abgelaufen, gefälscht): seine Sitzung ist abgelaufen, das teilen wir ihm mit
        $middleware->redirectGuestsTo(function (Request $request) {
            if ($request->cookie(AuthService::COOKIE)) {
                Flash::error('ERRORS.SESSION_EXPIRED');
            }
            return route('login');
        });

        // Kurznamen (Aliase) für die in routes/web.php verwendeten Middlewares
        $middleware->alias([
            'role' => RequireRoles::class,
            'registration.pass' => CheckRegistrationPass::class,
        ]);
    })

    // -----------------------------------------------------------------------
    // 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: abort(400), abort(403) (unzureichende Rolle), unbekannte
    //      Seite (404), nicht unterstützte Methode (405), fehlendes oder falsches
    //      CSRF-Token (419)... -> die Fehlerseite mit dem ursprünglichen Code;
    //   3. jede andere Exception (eine echte Anomalie): Laravel schreibt sie in das
    //      Log (storage/logs/laravel.log) mit ihrem Aufrufstapel; in
    //      Produktion (APP_DEBUG=false) sieht der Benutzer die 500-Fehlerseite -
    //      niemals den Aufrufstapel; in der Entwicklung die Debug-Seite von Laravel.
    // Eine render-Funktion, die null zurückgibt, überlässt die Behandlung der Exception Laravel
    // auf seine eigene Weise.
    // -----------------------------------------------------------------------
    ->withExceptions(function (Exceptions $exceptions): void {
        // die Fehlerseite. $errors: die Variable der Eingabefehler, die alle
        // Views lesen können, existiert noch nicht, wenn der Fehler vor der
        // Middleware aufgetreten ist, die sie erstellt (zum Beispiel bei einer 405-Seite)
        $errorPage = function (int $code) {
            $message = match ($code) {
                400 => 'ERRORS.BAD_REQUEST',
                403 => 'ERRORS.FORBIDDEN',
                404 => 'ERRORS.NOT_FOUND',
                419 => 'ERRORS.PAGE_EXPIRED',
                default => 'ERRORS.SERVER_ERROR',
            };
            return response()->view('error', ['pageTitle' => 'ERROR_PAGE.TITLE', 'code' => $code,
                'message' => $message, 'errors' => new ViewErrorBag], $code);
        };

        $exceptions->render(function (InvalidSession $e) {
            Flash::error('ERRORS.SESSION_EXPIRED');
            return redirect()->route('login')->withCookie(AuthService::clearingCookie());
        });

        $exceptions->render(fn (HttpExceptionInterface $e) => $errorPage($e->getStatusCode()));

        $exceptions->render(function (Throwable $e) use ($errorPage) {
            // diese Exceptions haben ihre eigene Behandlung: Weiterleitung zur
            // Login-Seite (AuthenticationException), zurück zum Formular mit den
            // Eingabefehlern (ValidationException)...
            if (config('app.debug') || $e instanceof AuthenticationException
                || $e instanceof ValidationException || $e instanceof HttpResponseException) {
                return null;
            }
            return $errorPage(500);
        });
    })
    ->create();

Die Datei, die die Anwendung aufbaut (Beispiel 01). Sie enthält alles rund um die Anfrageverarbeitung: Routen, Middleware und Ausnahmen.

  • Zeile 28: die Routen ([routes/web.php], siehe später);
  • Zeile 33: Die Sprache der Anfrage wird von einer globalen Middleware (Beispiel 24) festgelegt, die für alle Anfragen ausgeführt wird, noch vor dem Routing;
  • Zeile 37: [Laravel] verschlüsselt alle Cookies (Beispiel 20), außer den ausgenommenen: dem JWT-Token, das bereits signiert ist (Beispiel 25), und der Sprache. Das Sprach-Cookie wird von einer globalen Middleware gelesen, die vor der [EncryptCookies]-Middleware in der Gruppe [web] läuft: Es muss daher ohne Entschlüsselung lesbar sein. Warum eine globale Middleware statt einer Middleware aus der Gruppe [web]? Damit auch Anfragen, die zu keiner Route führen (eine 405-Seite), ihre Fehlerseite in der richtigen Sprache anzeigen;
  • Zeile 47: die Zugriffsregel der Anwendung. Die Middleware [Authenticate] (der Alias [auth] aus Beispiel 25) wird der Gruppe [web] hinzugefügt, also allen Routen. Eine öffentliche Route (die Anmeldeseite, die Kontoerstellung, die Sprachauswahl) muss sie ausdrücklich mit [withoutMiddleware] (in [routes/web.php]) entfernen. Das folgt der Regel „Alles ist verboten, sofern nicht ausdrücklich erlaubt“: Eine später hinzugefügte Route ist – auch wenn man vergessen hat, sie zu schützen – automatisch geschützt. Der umgekehrte Fehler (eine öffentliche Route, die man zu öffnen vergessen hat) fällt sofort auf; der Fehler einer vergessenen geschützten Seite dagegen kaum;
  • Zeilen 52–57: Ein nicht authentifizierter Besucher, der eine geschützte Seite anfordert, wird zur Anmeldeseite umgeleitet. Hat der Browser des Besuchers ein Token-Cookie gesendet, bedeutet das, dass dieses Token nicht mehr gültig ist (abgelaufen oder manipuliert): Der Besucher wird durch eine Pop-up-Meldung benachrichtigt ([Flash::error], siehe später). [redirectGuestsTo] akzeptiert eine URL oder eine Funktion, die die Anfrage erhält und die URL zurückgibt;
  • Zeilen 60–63: Aliase (Kurznamen) für Route-Middleware: [role] und [registration.pass], verwendet in [routes/web.php].

Die Zeilen 80–113 wandeln Fehler in HTML-Seiten um (Beispiel 24):

  • Zeilen 84–91: die Funktion, die die Fehlerseite für einen HTTP-Code erzeugt: die View [error], der Code, der Meldungsschlüssel und der HTTP-Antwortcode. Ein subtiler Punkt: Die Views der Anwendung lesen die Variable [$errors] (Eingabefehler, Beispiel 19), die die Middleware [ShareErrorsFromSession] der Gruppe [web] mit allen Views teilt. Ein Fehler, der vor dieser Middleware auftritt (eine nicht unterstützte HTTP-Methode, 405, wird vom Router erkannt), würde eine View ohne [$errors] erreichen: Ihr wird daher eine leere Variable ([new ViewErrorBag]) bereitgestellt;
  • Zeilen 96–99: die Ausnahme [InvalidSession] (das Konto des Tokens existiert nicht mehr; siehe unten): Rückkehr zur Anmeldeseite, Token-Cookie gelöscht, mit der Meldung „Sitzung abgelaufen“;
  • Zeile 101: alle HTTP-Fehler – [abort(403)], [abort(404)], eine unbekannte Route, eine nicht unterstützte Methode, ein fehlendes oder ungültiges CSRF-Token (419, Beispiel 18) ... – werden samt ihren Codes zur Fehlerseite;
  • Zeilen 103–112: Jede andere Ausnahme ist eine echte Anomalie (die Datenbank ist nicht erreichbar, ein Programmierfehler ...). [Laravel] protokolliert sie immer im Protokoll [storage/logs/laravel.log] samt Aufrufstapel. In der Produktion ([APP_DEBUG=false]) sieht der Benutzer die 500-Fehlerseite – niemals den Aufrufstapel, der dem Code der Anwendung einem Angreifer offenlegen würde; in der Entwicklung gibt die Funktion [null] zurück: [Laravel] zeigt seine Debug-Seite an. Achtung: [Throwable] fängt alle Ausnahmen ab, auch die, die [Laravel] selbst behandelt und die ihm überlassen bleiben sollten: [AuthenticationException] (ein nicht authentifizierter Besucher, umgeleitet nach [/login]), [ValidationException] (eine ungültige Eingabe, zurück zum Formular, Beispiel 19), [HttpResponseException] (eine Ausnahme, die ihre eigene Antwort mitbringt). Die Rendering-Funktionen werden in der Reihenfolge ihrer Deklaration ausprobiert: HTTP-Fehler wurden bereits von der vorherigen behandelt.

11.8. Die Modelle

Die [Eloquent]-Modelle (Beispiel 28): eine Klasse pro Tabelle.

11.8.1. app/Models/Role.php

<?php
// app/Models/Role.php: die drei Rollen eines Benutzers (Spalte users.role):
//   - ADMIN  : der Administrator - Termine + Verwaltung von Ärzten und Clients;
//   - DOCTOR : ein Arzt - bucht und storniert Termine;
//   - USER   : ein Client (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\Models;

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

Die drei Rollen in Form einer Enumeration ([enum], [PHP] 8.1): ein Typ, dessen einzige mögliche Werte seine Fälle 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 Fall hat einen Wert, hier den in der Datenbank gespeicherten String. [Role::ADMIN->value] ist gleich ['ADMIN']; [Role::from('ADMIN')] gibt den entsprechenden Fall zurück (und wirft bei einem unbekannten Wert eine Ausnahme); [Role::tryFrom(...)] gibt in diesem Fall [null] zurück.

11.8.2. app/Models/User.php

<?php
// app/Models/User.php: ein Benutzer, der sich anmelden darf (Tabelle [users]).
// Jeder Arzt und jeder Client besitzt SEIN Konto (Spalte [user] der Tabellen
// [doctors] und [clients], siehe Person.php).
//
// SQL-Eindeutigkeitsbedingung: unq_users_login (ein Login gehört nur zu einem
// Konto). Sie wird vom Skript database/dbrdvmedecins2.sql erstellt; die Geschäfts-
// schicht erkennt sie an ihrem NAMEN (siehe app/Business/BusinessService.php).

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

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

    // die Tabelle hat nicht die Spalten created_at / updated_at, die Eloquent standardmäßig verwaltet
    public $timestamps = false;

    // die Spalten, die per Mass Assignment befüllt werden können (User::create([...]), new User([...]))
    protected $fillable = ['login', 'password', 'name', 'role'];

    // das GEHASHTE Passwort (bcrypt) verlässt das Objekt nie, wenn es in ein
    // Array oder in JSON umgewandelt wird
    protected $hidden = ['password'];

    // die Umwandlungen: die Spalte [role] (ein Text) wird zu einer Role und umgekehrt
    protected function casts(): array
    {
        return ['role' => Role::class, 'version' => 'integer'];
    }
}
  • Zeile 16: die Tabelle. [Eloquent] hätte sie erraten (der Klassenname, kleingeschrieben, im englischen Plural: [users]); wir schreiben sie der Klarheit halber überall aus;
  • Zeile 19: Keine Tabelle der Datenbank hat die Spalten [created_at] und [updated_at], die [Eloquent] standardmäßig befüllt (Beispiel 28);
  • Zeile 22: die Spalten, die per [User::create([...])] gesammelt befüllt werden können (Beispiel 28);
  • Zeile 26: Der Passwort-Hash erscheint nicht, wenn das Objekt in ein Array oder in JSON umgewandelt wird ([$user->toArray()]): eine Vorsichtsmaßnahme;
  • Zeilen 29–32: die Umwandlungen (Beispiel 28): Die Spalte [role] (Text) wird beim Lesen zu [Role] und beim Schreiben umgekehrt: [$user->role] ist [Role], niemals ein String. Die Spalte [version] wird als Ganzzahl gelesen: Der [PDO]-Treiber für [MySQL] kann Zahlen als Strings liefern, und der strikte Vergleich [$version !== $person->version] der Geschäftsschicht würde fehlschlagen.

11.8.3. app/Models/Person.php

<?php
// app/Models/Person.php: was die Ärzte (Tabelle [doctors]) und
// die Clients (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 nur EINMAL
// in dieser ABSTRAKTEN Klasse beschrieben (wir erstellen nie eine "Person"), von der
// Doctor und Client erben; jede gibt nur den Namen ihrer Tabelle an.
//
// Achtung: [Client] bezeichnet hier einen PATIENTEN der Arztpraxis, keinen HTTP-
// Client! Es ist das Vokabular der ursprünglichen Geschäftsdomäne, unverändert beibehalten.

namespace App\Models;

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

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

    // [user] ist der Name der Fremdschlüsselspalte -> users(id): eine einfache
    // Zahl, die id des Kontos ($doctor->user)
    protected $fillable = ['title', 'last_name', 'first_name', 'user'];

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

    // -----------------------------------------------------------------------
    // Die RELATION zum Benutzerkonto: eine Person hat EIN Konto, bezeichnet
    // durch den Fremdschlüssel [user]. belongsTo: "gehört zu" - der Fremdschlüssel
    // liegt in DIESER Tabelle. $doctor->account ist dann ein User-Objekt, beim
    // ersten Zugriff aus der Datenbank gelesen, oder sofort mit der Abfrage über with('account') (siehe app/Dao).
    // Die Relation kann nicht [user] heißen: dieser Name ist bereits der der
    // Spalte, und $doctor->user bezeichnet die Spalte.
    // -----------------------------------------------------------------------
    public function account(): BelongsTo
    {
        return $this->belongsTo(User::class, 'user');
    }

    // "Mme Alice DURAND"
    public function label(): string
    {
        return "{$this->title} {$this->first_name} {$this->last_name}";
    }
}

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

  • Zeile 24: [user] ist die Fremdschlüsselspalte; [$doctor->user] ist eine einfache Zahl, die ID des Kontos;
  • Zeilen 39–42: die Beziehung zum Konto. Eine [Eloquent]-Beziehung ist eine Methode, die die Verknüpfung zwischen zwei Tabellen beschreibt; [belongsTo] („gehört zu“) beschreibt einen Fremdschlüssel in dieser Tabelle: [belongsTo(User::class, 'user')] legt fest, dass die Spalte [user] die ID eines [User] enthält. Sie wird wie eine Eigenschaft verwendet: [$doctor->account] ist das Objekt [User]. [Eloquent] liest sie beim ersten Zugriff aus der Datenbank (das nennt man *Lazy Loading*) oder sobald die Abfrage, die den Arzt abruft, sie anfordert (bei Bedarf; *Eager Loading*, siehe [with('account')] in der DAO-Schicht). Die Beziehung kann nicht [user] heißen: [$doctor->user] bezeichnet bereits die Spalte, und [Eloquent] gibt den Spalten Vorrang;
  • Zeilen 45–48: der Name einer Person, „Frau Alice DURAND“, der von allen Seiten verwendet wird. In einem in Anführungszeichen stehenden String fügt [{$this->title}] den Wert einer Eigenschaft ein.

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

<?php
// app/Models/Doctor.php: ein Arzt (Tabelle [doctors]).
// SQL-Eindeutigkeitsbedingung: unq_doctors_first_name_last_name (zwei Ärzte dürfen nicht
// dieselben Vor- und Nachnamen haben).

namespace App\Models;

class Doctor extends Person
{
    protected $table = 'doctors';
}
<?php
// app/Models/Client.php: ein Client, also ein PATIENT (Tabelle [clients]).
// SQL-Eindeutigkeitsbedingung: unq_clients_first_name_last_name.

namespace App\Models;

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

Ein [Client] ist ein Patient der Praxis, kein HTTP-Client: Das ist das ursprüngliche Vokabular der Fachdomäne, das in allen Versionen der Anwendung beibehalten wurde.

11.8.5. app/Models/Slot.php

<?php
// app/Models/Slot.php: ein Zeitfenster eines Arztes (Tabelle [slots]):
// 8:00 - 8:20 usw.

namespace App\Models;

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

class Slot extends Model
{
    protected $table = 'slots';

    public $timestamps = false;

    protected function casts(): array
    {
        return ['doctor_id' => 'integer', 'start_hour' => 'integer', 'start_minute' => 'integer',
            'end_hour' => 'integer', 'end_minute' => 'integer', 'version' => 'integer'];
    }

    // mehrere Zeitfenster für denselben Arzt: der Fremdschlüssel [doctor_id]
    public function doctor(): BelongsTo
    {
        return $this->belongsTo(Doctor::class, 'doctor_id');
    }

    // "8:00 - 8:20"; sprintf('%02d'): "8:05" statt "8:5"
    public function time(): string
    {
        return sprintf('%d:%02d - %d:%02d', $this->start_hour, $this->start_minute, $this->end_hour, $this->end_minute);
    }
}
  • Zeilen 23–26: die Beziehung zum Arzt für das Terminzeitfenster (Fremdschlüssel [doctor_id]);
  • Zeilen 29–32: das Zeitfenster, „8:00 – 8:20“. Das Format [%02d] von [sprintf] schreibt eine Ganzzahl mindestens zweistellig, mit Nullen aufgefüllt: [8:05] statt [8:5].

11.8.6. app/Models/Appointment.php

<?php
// app/Models/Appointment.php: ein Termin (Tabelle [appointments]): ein Client in einem Zeitfenster an einem
// bestimmten Tag.
// SQL-Eindeutigkeitsbedingung: unq1_appointments (day, slot_id) - ein Zeitfenster wird
// pro Tag nur einmal gebucht. Vom SQL-Skript erstellt, in der Geschäftsschicht
// an ihrem Namen erkannt.

namespace App\Models;

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

class Appointment extends Model
{
    protected $table = 'appointments';

    public $timestamps = false;

    protected $fillable = ['day', 'slot_id', 'client_id'];

    // immutable_date: die Spalte [day] (SQL-Typ DATE) wird zu einem
    // Datum vom Typ CarbonImmutable um Mitternacht; sie wird im Format yyyy-mm-dd in die Datenbank geschrieben
    protected function casts(): array
    {
        return ['day' => 'immutable_date', 'slot_id' => 'integer', 'client_id' => 'integer',
            'version' => 'integer'];
    }

    public function client(): BelongsTo
    {
        return $this->belongsTo(Client::class, 'client_id');
    }

    public function slot(): BelongsTo
    {
        return $this->belongsTo(Slot::class, 'slot_id');
    }
}
  • Zeilen 23–27: Die Spalte [day] (SQL-Typ [DATE]) wird in [CarbonImmutable] umgewandelt, die Datumsklasse von [Laravel] (Beispiel 12), um Mitternacht. Immutable: Ihre Methoden verändern das Objekt nie, sondern geben ein neues zurück ([$day->addDay()] gibt den nächsten Tag zurück, [$day] bleibt unverändert). Die gesamte Anwendung verwendet unveränderliche Datumsobjekte: Ein Datum, das von mehreren Objekten geteilt wird, kann von einem davon nicht verändert werden, ohne dass die anderen es merken;
  • Zeilen 29–34: zwei Beziehungen, eine zum Client und eine zum Zeitfenster des Termins.

11.9. Die Domäne: der Kalender

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

<?php
// app/Domain/DoctorDaySlot.php: ein Zeitfenster und der Termin, der
// an einem bestimmten Tag möglicherweise in diesem Zeitfenster gebucht ist (null, wenn das Zeitfenster frei ist).
// Ein berechnetes "fachliches" Objekt, das keiner Tabelle entspricht.
//
// 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\Models\Slot;
use App\Models\Appointment;

readonly class DoctorDaySlot
{
    public function __construct(
        public Slot $slot,
        public ?Appointment $appointment,
    ) {
    }
}
<?php
// app/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\Models\Doctor;
use Carbon\CarbonImmutable;

readonly class DoctorDaySchedule
{
    /** @param list<DoctorDaySlot> $doctorDaySlots */
    public function __construct(
        public Doctor $doctor,
        public CarbonImmutable $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 mit seinen verfügbaren Zeitfenstern. Es sind Klassen vom Typ [readonly] (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 Transaktionen; die Geschäftsschicht ruft sie innerhalb ihrer eigenen Transaktionen auf. Sie verwenden den Query Builder von [Eloquent]: [where], [orderBy], [first], [get] ... ; die Werte in diesen Abfragen werden zu Parametern der SQL-Abfrage: Eine SQL-Injection ist nicht möglich.

11.10.1. app/Dao/PersonDao.php

<?php
// app/Dao/PersonDao.php: die DAO-Schicht, die Ärzten und Clients gemeinsam ist.
//
// Die DAOs der Ärzte und der Clients wären identisch: diese ABSTRAKTE Klasse
// schreibt sie nur einmal. $this->model ist die betroffene Eloquent-Klasse
// (Doctor::class oder Client::class): $this->model::query() startet eine Abfrage
// auf IHRE Tabelle.
//
// Die Abfragen sind mit dem Query Builder von Eloquent geschrieben (where,
// orderBy...); Eloquent übersetzt sie in SQL. Die Werte (Vorname, Nachname...)
// werden zu PARAMETERN der Abfrage: 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\Models\Person;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Support\Facades\DB;

abstract class PersonDao
{
    /** @param class-string<Person> $model */
    public function __construct(protected string $model)
    {
    }

    // eine Abfrage auf der Tabelle der Klasse, einschließlich des Benutzerkontos
    protected function query(): Builder
    {
        // with('account'): lädt ZUSÄTZLICH die Konten, mit einer zweiten Abfrage
        // (SELECT * FROM users WHERE id IN (...)). Ohne sie würde jeder Zugriff auf
        // $person->account eine eigene Abfrage auslösen
        return $this->model::query()->with('account');
    }

    // nach Nachname, dann Vorname sortierte Liste
    public function list(): Collection
    {
        return $this->query()->orderBy('last_name')->orderBy('first_name')->get();
    }

    // eine Person und ihr Konto; null, falls sie nicht existiert
    public function read(int $id): ?Person
    {
        return $this->query()->find($id);
    }

    // die Person, deren Benutzerkonto [$userId] ist
    public function readByUser(int $userId): ?Person
    {
        return $this->query()->where('user', $userId)->first();
    }

    // die Person mit diesen Vor- und Nachnamen, falls es eine gibt. Der Vergleich wird
    // von MySQL durchgeführt, also mit der Kollation der Datenbank (utf8mb4_unicode_ci: unabhängig
    // von Groß-/Kleinschreibung und Akzenten) - genau dieselbe Regel wie
    // die der SQL-Eindeutigkeitsbedingung
    public function namesake(string $firstName, string $lastName): ?Person
    {
        return $this->model::query()->where('first_name', $firstName)->where('last_name', $lastName)->first();
    }

    // INSERT: die Datenbank erzeugt die id, die Eloquent im Objekt speichert
    public function add(array $columns): Person
    {
        return $this->model::query()->create($columns);
    }

    // -----------------------------------------------------------------------
    // das OPTIMISTISCHE SPERREN (siehe Beispiel 28):
    //   UPDATE ... SET ..., version = version + 1 WHERE id = ? AND version = ?
    // liefert die Anzahl der geänderten Zeilen: 0, wenn die Zeile seit dem Lesen geändert (oder
    // gelöscht) wurde
    // -----------------------------------------------------------------------
    public function edit(int $id, int $version, array $columns): int
    {
        return $this->model::query()->whereKey($id)->where('version', $version)
            ->update([...$columns, 'version' => DB::raw('version + 1')]);
    }

    // ein direkt an die Datenbank gesendetes DELETE, ohne die Person vorher zu lesen
    public function remove(int $id): void
    {
        $this->model::query()->whereKey($id)->delete();
    }
}

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

  • Zeile 25: die betreffende [Eloquent]-Klasse, [Doctor::class], oder [Client::class] (ein String, der vollständige Name der Klasse). Der Kommentar [@param class-string<Person>] verdeutlicht dies für Entwickler. [$this->model::query()] ruft die statische Methode [query] dieser Klasse auf: [PHP] akzeptiert eine Variable anstelle eines Klassennamens. [query()] startet eine Abfrage auf der Tabelle des Modells; [Doctor::where(...)] ist eine Abkürzung dafür;
  • Zeilen 30–36: eine Abfrage, die auch die Konten der abgerufenen Personen lädt: [with('account')] fordert das Vorabladen der Beziehung [account] an. [Eloquent] führt dann zwei Abfragen aus: eine für die Personen und eine für alle ihre Konten auf einmal ([select * from users where id in (2, 3, 4)]; siehe die Konsolenausgabe oben). Ohne dies würde die vom Administrator angezeigte Liste der Ärzte beim ersten Zugriff auf [$doctor->account->login] eine Abfrage pro Arzt auslösen: das sogenannte „N+1-Abfragen“-Problem. Ein weiterer Grund: Die Listen der Ärzte und Clients werden im Cache gespeichert ([ApplicationModel], siehe später); die aus dem Cache abgerufenen Objekte müssen vollständig sein;
  • Zeilen 39–42: die Liste, sortiert nach Nachname und dann Vorname; [get()] gibt eine [Collection] und ein [Eloquent] zurück (Beispiel 28);
  • Zeilen 45–48: [find] liest eine Zeile anhand ihres Primärschlüssels; [null] , wenn sie nicht existiert;
  • Zeilen 51–54: die Person, deren Konto [$userId] ist: [first()] gibt die erste Zeile zurück oder [null];
  • Zeilen 60–63: die Person mit demselben Vor- und Nachnamen. Der Vergleich wird von [MySQL] mit der Kollation der Datenbank durchgeführt: ohne Rücksicht auf Groß- und Kleinschreibung und Akzente, genau wie beim Eindeutigkeits-Constraint (Beispiel 28);
  • Zeilen 66–69: [create] fügt eine Zeile ein (Spalten aus [$fillable]) und gibt das Objekt samt der von der Datenbank erzeugten ID zurück;
  • Zeilen 77–81: das optimistische Sperren aus Beispiel 28: [UPDATE ... SET ..., version = version + 1 WHERE id = ? AND version = ?]. Die Methode gibt die Anzahl der geänderten Zeilen zurück: 0, wenn die Zeile seit dem Lesen geändert oder gelöscht wurde. [[...$columns, 'version' => ...]] erzeugt ein Array mit den Elementen von [$columns] plus der Version (der Operator [...] entpackt ein Array). [whereKey($id)]: die Bedingung auf den Primärschlüssel;
  • Zeilen 84–87: ein [DELETE] , das direkt an die Datenbank gesendet wird, ohne die Zeile zuvor zu lesen.

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

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

namespace App\Dao;

use App\Models\Doctor;

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

Alles wird geerbt: Der Konstruktor übergibt lediglich die Klasse [Eloquent] an [PersonDao] ([parent::__construct] ruft den Konstruktor der Elternklasse auf).

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

namespace App\Dao;

use App\Models\Client;

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

    // -----------------------------------------------------------------------
    // setzt eine SPERRE auf die Zeile eines Clients bis zum Ende der aktuellen
    // Transaktion (SELECT ... FOR UPDATE) und liefert seine id (null, falls der Client
    // nicht existiert). Eine zweite Transaktion, die dieselbe Sperre anfordert, WARTET,
    // bis die erste beendet ist.
    // Verwendet für die Buchung (siehe BusinessService::addAppointment): zwei
    // gleichzeitige Buchungen für denselben Patienten werden so nacheinander
    // verarbeitet, und die zweite sieht den von der ersten erstellten Termin.
    // -----------------------------------------------------------------------
    public function lock(int $id): ?int
    {
        return Client::query()->whereKey($id)->lockForUpdate()->value('id');
    }
}
  • Zeilen 25–28: eine pessimistische Sperre, die andere Art von Sperre. [lockForUpdate()] fügt [FOR UPDATE] an die Abfrage an: [SELECT id FROM clients WHERE id = ? FOR UPDATE]. Die gelesene Zeile wird gesperrt bis zum Ende der aktuellen Transaktion: Eine andere Transaktion, die dieselbe Sperre anfordert, wartet , bis die erste abgeschlossen ist. [value('id')] gibt den Wert einer Spalte der ersten Zeile zurück ([null] , falls es keine gibt). Wozu diese Sperre dient, sehen wir in der Geschäftsschicht.

11.10.3. app/Dao/SlotDao.php

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

namespace App\Dao;

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

class SlotDao
{
    // ein Zeitfenster und sein Arzt
    public function read(int $id): ?Slot
    {
        return Slot::with('doctor')->find($id);
    }

    // die Zeitfenster eines Arztes in chronologischer Reihenfolge
    public function listByDoctor(int $doctorId): Collection
    {
        return Slot::where('doctor_id', $doctorId)->orderBy('start_hour')->orderBy('start_minute')->get();
    }

    // löscht alle Zeitfenster eines Arztes (Löschen eines Arztes):
    //   DELETE FROM slots WHERE doctor_id = ?
    public function deleteByDoctor(int $doctorId): void
    {
        Slot::where('doctor_id', $doctorId)->delete();
    }
}

[Slot::with('doctor')->find($id)]: ein Zeitfenster und sein Arzt (vorab geladen); [Slot::where(...)->delete()]: ein [DELETE] für alle Zeilen, die die Bedingung erfüllen.

11.10.4. app/Dao/AppointmentDao.php

<?php
// app/Dao/AppointmentDao.php: DAO-Schicht der Termine.
//
// Die Tabelle [appointments] verweist nicht direkt auf den Arzt: wir gehen über das Zeitfenster.
// whereHas('slot', ...): die Termine, deren Zeitfenster eine Bedingung erfüllt
// (Eloquent schreibt es in SQL mit einer EXISTS-Unterabfrage).

namespace App\Dao;

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

class AppointmentDao
{
    // ein Termin, sein Client und sein Zeitfenster
    public function read(int $id): ?Appointment
    {
        return Appointment::with(['client', 'slot'])->find($id);
    }

    // die Termine eines Arztes an einem bestimmten Tag, mit ihrem Client
    public function doctorDayAppointments(int $doctorId, CarbonImmutable $day): Collection
    {
        return Appointment::with('client')
            ->where('day', $day->toDateString())
            ->whereHas('slot', fn (Builder $q) => $q->where('doctor_id', $doctorId))
            ->get();
    }

    // -----------------------------------------------------------------------
    // die Termine eines Clients ab dem Tag [$since] (einschließlich) in chronologischer
    // Reihenfolge, mit dem Zeitfenster UND dem Arzt dieses Zeitfensters ('slot.doctor':
    // eine Relation der Relation). Die Sortierung verwendet Spalten der
    // Tabelle [slots]: ein SQL-JOIN ist nötig; select('appointments.*'): wir behalten nur die
    // Spalten von [appointments], um die Appointment-Objekte zu füllen
    // -----------------------------------------------------------------------
    public function clientUpcomingAppointments(int $clientId, CarbonImmutable $since): Collection
    {
        return Appointment::with('slot.doctor')
            ->select('appointments.*')
            ->join('slots', 'slots.id', '=', 'appointments.slot_id')
            ->where('appointments.client_id', $clientId)
            ->where('appointments.day', '>=', $since->toDateString())
            ->orderBy('appointments.day')->orderBy('slots.start_hour')->orderBy('slots.start_minute')
            ->get();
    }

    // Anzahl der Termine eines Clients ab dem Tag [$since] (einschließlich)
    public function countClientUpcoming(int $clientId, CarbonImmutable $since): int
    {
        return Appointment::where('client_id', $clientId)->where('day', '>=', $since->toDateString())->count();
    }

    // Anzahl der Termine (vergangene oder zukünftige) eines Arztes
    public function countByDoctor(int $doctorId): int
    {
        return Appointment::whereHas('slot', fn (Builder $q) => $q->where('doctor_id', $doctorId))->count();
    }

    public function add(CarbonImmutable $day, int $slotId, int $clientId): Appointment
    {
        return Appointment::create(['day' => $day, 'slot_id' => $slotId, 'client_id' => $clientId]);
    }

    // DELETE FROM appointments WHERE id = ?
    public function remove(int $id): void
    {
        Appointment::whereKey($id)->delete();
    }

    // löscht ALLE Termine (vergangene und zukünftige) eines Clients
    public function deleteByClient(int $clientId): void
    {
        Appointment::where('client_id', $clientId)->delete();
    }
}

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

  • Zeilen 24–30: die Termine eines Arztes an einem bestimmten Tag. [whereHas('slot', function)] behält die Termine, für die die Beziehung [slot] die von der Funktion definierte Bedingung erfüllt: [Eloquent] übersetzt dies in eine Unterabfrage [EXISTS] (siehe die Konsolenausgabe oben). [fn (Builder $q) => ...] ist eine Arrow-Funktion (Beispiel 03); sie erhält die Abfrage auf die Tabelle [slots]. Das Datum wird in seinem Format [yyyy-mm-dd] verglichen ([toDateString()]), das dem der Spalten vom Typ [DATE] entspricht;
  • Zeilen 39–48: die bevorstehenden Termine eines Clients samt Zeitfenster und dem diesem Zeitfenster zugeordneten Arzt: [with('slot.doctor')] lädt eine Beziehung der Beziehung. Die Sortierung erfolgt nach der Uhrzeit des Zeitfensters, einer Spalte der Tabelle [slots]: Ein Join ist erforderlich ([join]). [select('appointments.*')] behält nur die Spalten der Tabelle [appointments], um die Objekte [Appointment] zu befüllen (sonst würde die ID des Zeitfensters die ID des Termins überschreiben: Beide Spalten heißen [id]);
  • Zeilen 51–54: [count()] führt ein [SELECT COUNT(*)] aus;
  • Zeilen 62–65: Das Objekt [CarbonImmutable] wird mithilfe der vom Modell deklarierten Umwandlung im Format der Spalte in die Datenbank geschrieben.

11.10.5. app/Dao/UserDao.php

<?php
// app/Dao/UserDao.php: DAO-Schicht der Benutzerkonten. Das Erstellen (oder Löschen)
// eines Arztes oder Clients erstellt (oder löscht) auch sein Konto - siehe app/Business.

namespace App\Dao;

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

class UserDao
{
    // null, falls kein Benutzer diesen Login hat
    public function readByLogin(string $login): ?User
    {
        return User::where('login', $login)->first();
    }

    public function add(string $login, string $hashed, string $name, Role $role): User
    {
        return User::create(['login' => $login, 'password' => $hashed, 'name' => $name, 'role' => $role]);
    }

    // optimistisches Sperren, wie PersonDao::edit
    public function edit(int $id, int $version, array $columns): int
    {
        return User::whereKey($id)->where('version', $version)
            ->update([...$columns, 'version' => DB::raw('version + 1')]);
    }

    public function remove(int $id): void
    {
        User::whereKey($id)->delete();
    }
}

Konten: Abruf per Login, Hinzufügen, Ändern mit optimistischem Sperren, Löschen.

11.11. Die Geschäftsschicht

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

11.11.1. app/Business/Dates.php

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

namespace App\Business;

use Carbon\CarbonImmutable;

class Dates
{
    // heute um Mitternacht in der Zeitzone der Anwendung (config/app.php)
    public static function today(): CarbonImmutable
    {
        return CarbonImmutable::today();
    }
}

Das aktuelle Datum um Mitternacht in der Zeitzone der Anwendung ([config/app.php]). Es wird für Geschäftsregeln verwendet (keine Reservierungen in der Vergangenheit, nur ein bevorstehender Termin): Daher liegt es in der Geschäftsschicht. Eine statische Methode ([static]) wird aufgerufen, ohne ein Objekt zu erzeugen: [Dates::today()].

11.11.2. app/Business/BusinessException.php

<?php
// app/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 lang/*.json).
//
// Eine BusinessException ist keine Anomalie: sie ist eine normale Antwort ("dieser Login
// ist bereits vergeben"), die dem Benutzer angezeigt wird. Jede andere Exception ist eine echte
// Anomalie, die auf der 500-Fehlerseite landet.

namespace App\Business;

use RuntimeException;
use Throwable;

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

Die Ausnahme, die bei einem Verstoß gegen eine Geschäftsregel geworfen wird. Sie trägt keinen Text, sondern einen Übersetzungsschlüssel ([ERRORS.LOGIN_TAKEN]) und dessen Parameter: Die Web-Schicht übersetzt ihn 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 (Beispiel 03) deklariert und initialisiert; [parent::__construct($key, 0, $previous)] ruft den Konstruktor von [RuntimeException] auf und übergibt die Meldung, den Code und die vorherige Ausnahme (die, die diese ausgelöst hat – zum Beispiel ein Datenbankfehler: Sie erscheint zusammen mit der neuen im Protokoll).

11.11.3. app/Business/PersonData.php

<?php
// app/Business/PersonData.php: die in einem Formular "Arzt" oder "Client" eingegebenen Daten,
// 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,
        // Erstellung: optional (null), standardmäßig der Nachname in Kleinbuchstaben
        // Änderung: optional, der Login bleibt unverändert, wenn er fehlt
        public ?string $login = null,
        // Erstellung: optional, standardmäßig der Login
        // Änderung: optional, das Passwort bleibt unverändert, wenn es fehlt
        public ?string $password = null,
        // Änderung: die Version des Datensatzes, als das Formular
        // angezeigt wurde (optimistisches Sperren)
        public ?int $version = null,
    ) {
    }
}

Daten eines „Personen“-Formulars, wie sie die Web-Schicht an die Geschäftsschicht übergibt: eine Klasse vom Typ [readonly]. Login, Passwort und Version sind optional ([?string], [?int], Standardwert [null]); die Kommentare erklären, was ihr Fehlen bedeutet.

11.11.4. app/Business/Business.php

<?php
// app/Business/Business.php: der VERTRAG der Geschäftsschicht: Lesen, 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 kann (null: ein Arzt, der nicht existiert...).

namespace App\Business;

use App\Domain\DoctorDaySchedule;
use App\Models\Client;
use App\Models\Slot;
use App\Models\Doctor;
use App\Models\Appointment;
use Carbon\CarbonImmutable;
use Illuminate\Database\Eloquent\Collection;

interface Business
{
    // ––––––––––––––––––––––––––––––––––––––––––––––––– Lesen
    public function getAllClients(): Collection;

    public function getAllDoctors(): Collection;

    public function getAllSlots(int $doctorId): Collection;

    public function getDoctorDayAppointments(int $doctorId, CarbonImmutable $day): Collection;

    public function getClientById(int $id): ?Client;

    public function getDoctorById(int $id): ?Doctor;

    public function getAppointmentById(int $id): ?Appointment;

    public function getSlotById(int $id): ?Slot;

    public function getDoctorDaySchedule(int $doctorId, CarbonImmutable $day): ?DoctorDaySchedule;

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

    // die Termine eines Clients, heutige oder zukünftige, mit Zeitfenster und Arzt
    public function getClientUpcomingAppointments(int $clientId): Collection;

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

    public function deleteAppointment(Appointment $appointment): void;

    // ––––––––––––––––––––––––––––––––––––––––––––––––– Ärzte (ADMIN)
    // erstellt den Arzt UND sein Benutzerkonto (Rolle DOCTOR)
    public function addDoctor(PersonData $data): Doctor;

    // ändert den Arzt UND sein 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)
    // erstellt den Client UND sein Benutzerkonto (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 zukü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 geben [Eloquent]- oder [Collection]-Objekte zurück; [?Client]: ein Client oder [null] , wenn er nicht existiert. Die Kommentare legen die Regeln jeder schreibenden Operation und die Schlüssel der [BusinessException]-Objekte fest, die sie erzeugen kann.

11.11.5. app/Business/Descriptor.php

<?php
// app/Business/Descriptor.php: alles, was einen Arzt für die
// Geschäftsregeln von einem Client 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\Models\Role;
use Closure;

readonly class Descriptor
{
    public function __construct(
        public PersonDao $dao,
        public Role $role,              // DOCTOR oder USER
        public string $notFoundKey,     // Meldung, falls die Person nicht existiert
        public string $alreadyExistsKey, // Meldung, falls dieselben Vor- und Nachnamen bereits existieren
        // optional (null): falls vorhanden, wird das Löschen ABGELEHNT, solange die
        // Person Termine hat (countAppointments(id) > 0), mit der Meldung 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, den Fehlermeldungen und der Löschregel. Dieser Descriptor bündelt diese Details; der gemeinsame Code liest sie aus. Zwei Eigenschaften sind Funktionen ([?Closure]: eine Funktion oder [null]): die Anzahl der Termine, die das Löschen verhindert (nur bei Ärzten), und das Löschen dessen, was auf die Person verweist.

11.11.6. app/Business/BusinessService.php

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
<?php
// =========================================================================
// app/Business/BusinessService.php: 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 zusammen erstellt, geändert und gelöscht, in derselben
//      TRANSAKTION - entweder gelingt alles, oder nichts wird geschrieben;
//   2. der Login ist in der gesamten Anwendung eindeutig, und zwei Ärzte (oder zwei
//      Clients) dürfen nicht dieselben Vor- und Nachnamen haben;
//   3. Löschen:
//      - ein ARZT, der Termine hat, kann nicht gelöscht werden (seine Patienten
//        würden ihren Termin verlieren, ohne gewarnt zu werden): sie müssen zuerst
//        storniert werden. Seine Zeitfenster verschwinden mit ihm;
//      - ein CLIENT dagegen verschwindet mit ALLEN seinen Terminen (vergangenen und zukünftigen) -
//        egal ob das Löschen vom ADMIN oder vom Patienten selbst kommt.
//
// Und zwei Regeln für die Buchung, egal welche Rolle derjenige hat, der
// bucht (ADMIN, DOCTOR oder der Patient selbst):
//   4. kein Termin in der Vergangenheit;
//   5. ein Patient hat immer nur EINEN zukünftigen 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 welchem Personentyp 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\Models\Client;
use App\Models\Slot;
use App\Models\Doctor;
use App\Models\Person;
use App\Models\Role;
use App\Models\Appointment;
use Carbon\CarbonImmutable;
use Closure;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\QueryException;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Str;

class BusinessService implements Business
{
    // -----------------------------------------------------------------------
    // Datenbankfehler -> BusinessException
    //
    // Wenn eine UNIQUE-Bedingung einen Schreibvorgang ablehnt, löst Laravel eine
    // QueryException aus, deren Meldung die von MySQL ist. Sie nennt den NAMEN der
    // Bedingung:
    //   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 Bedingungen.
    // -----------------------------------------------------------------------
    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;

    // alle Abhängigkeiten werden vom Service Container von Laravel bereitgestellt
    // (Dependency Injection, siehe Beispiel 06)
    public function __construct(
        private DoctorDao $doctors,
        private ClientDao $clients,
        private SlotDao $slots,
        private AppointmentDao $appointments,
        private UserDao $users,
    ) {
        $this->doctor = new Descriptor(
            dao: $doctors,
            role: Role::DOCTOR,
            notFoundKey: 'ERRORS.DOCTOR_NOT_FOUND',
            alreadyExistsKey: 'ERRORS.DOCTOR_ALREADY_EXISTS',
            // $appointments->countByDoctor(...): die Methode selbst als Closure
            // (sogenannte "First-Class-Callable"-Syntax)
            countAppointments: $appointments->countByDoctor(...),
            hasAppointmentsKey: 'ERRORS.DOCTOR_HAS_APPOINTMENTS',
            // ein Arzt ohne Termine kann noch Zeitfenster haben:
            // sie ergeben ohne ihn keinen Sinn, sie werden mit ihm gelöscht (andernfalls würde der
            // Fremdschlüssel slots.doctor_id das Löschen verbieten)
            beforeDelete: $slots->deleteByDoctor(...));

        $this->client = new Descriptor(
            dao: $clients,
            role: Role::USER,
            notFoundKey: 'ERRORS.PATIENT_NOT_FOUND',
            alreadyExistsKey: 'ERRORS.PATIENT_ALREADY_EXISTS',
            // kein countAppointments: das Löschen eines Clients wird nie abgelehnt;
            // seine Termine (vergangene und zukünftige) werden mit ihm gelöscht (andernfalls würde
            // der Fremdschlüssel appointments.client_id das Löschen verbieten)
            countAppointments: null,
            hasAppointmentsKey: null,
            beforeDelete: $appointments->deleteByClient(...));
    }

    // =======================================================================
    // Lesen
    // =======================================================================

    public function getAllClients(): Collection
    {
        return $this->clients->list();
    }

    public function getAllDoctors(): Collection
    {
        return $this->doctors->list();
    }

    public function getAllSlots(int $doctorId): Collection
    {
        return $this->slots->listByDoctor($doctorId);
    }

    public function getDoctorDayAppointments(int $doctorId, CarbonImmutable $day): Collection
    {
        return $this->appointments->doctorDayAppointments($doctorId, $day);
    }

    public function getClientById(int $id): ?Client
    {
        return $this->clients->read($id);
    }

    public function getDoctorById(int $id): ?Doctor
    {
        return $this->doctors->read($id);
    }

    public function getAppointmentById(int $id): ?Appointment
    {
        return $this->appointments->read($id);
    }

    public function getSlotById(int $id): ?Slot
    {
        return $this->slots->read($id);
    }

    public function getClientByUserId(int $userId): ?Client
    {
        return $this->clients->readByUser($userId);
    }

    public function getClientUpcomingAppointments(int $clientId): Collection
    {
        return $this->appointments->clientUpcomingAppointments($clientId, Dates::today());
    }

    // der Terminkalender eines Arztes an einem bestimmten Tag: seine Zeitfenster und für jedes
    // der an diesem Tag gebuchte Termin (null, falls es frei ist)
    public function getDoctorDaySchedule(int $doctorId, CarbonImmutable $day): ?DoctorDaySchedule
    {
        $doctor = $this->getDoctorById($doctorId);
        if ($doctor === null) {
            return null;
        }
        // Nr. des Zeitfensters -> in diesem Zeitfenster gebuchter Termin (keyBy: eine
        // nach dem Wert einer Spalte indizierte Collection)
        $bookings = $this->getDoctorDayAppointments($doctorId, $day)->keyBy('slot_id');
        $doctorDaySlots = $this->getAllSlots($doctorId)
            ->map(fn (Slot $slot) => new DoctorDaySlot($slot, $bookings->get($slot->id)))
            ->all();
        return new DoctorDaySchedule($doctor, $day, $doctorDaySlots);
    }

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

    // -----------------------------------------------------------------------
    // Buchung eines Termins in einer Transaktion:
    //   1. kein Termin in der Vergangenheit;
    //   2. wir SPERREN die Zeile des Patienten (SELECT ... FOR UPDATE): wenn derselbe
    //      Patient im selben Moment zwei Zeitfenster bucht (zwei Tabs, Doppel-
    //      klick...), wartet die zweite Transaktion auf das Ende der ersten - und sieht dann
    //      den Termin, den sie gerade erstellt hat;
    //   3. nur ein zukünftiger Termin pro Patient;
    //   4. schließlich das Einfügen. Wurde das Zeitfenster gerade von einem ANDEREN Patienten belegt,
    //      lehnt die SQL-Bedingung unq1_appointments (day, slot_id) das Einfügen ab
    //      - von transaction() in BusinessException übersetzt.
    // -----------------------------------------------------------------------
    public function addAppointment(CarbonImmutable $day, Slot $slot, Client $client): Appointment
    {
        return $this->transaction(function () use ($day, $slot, $client) {
            $today = Dates::today();
            if ($day->lt($today)) {
                throw new BusinessException('ERRORS.PAST_DATE');
            }
            $patientId = $this->clients->lock($client->id)
                ?? throw new BusinessException('ERRORS.PATIENT_NOT_FOUND');
            if ($this->appointments->countClientUpcoming($patientId, $today) > 0) {
                throw new BusinessException('ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT');
            }
            return $this->appointments->add($day, $slot->id, $patientId);
        });
    }

    public function deleteAppointment(Appointment $appointment): void
    {
        $this->transaction(fn () => $this->appointments->remove($appointment->id));
    }

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

    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 "Manage my account": gleiche Methode, gleiche Regel)
    public function deleteClient(int $id): void
    {
        $this->deletePerson($this->client, $id);
    }

    // -----------------------------------------------------------------------
    // Anlegen: das Benutzerkonto, DANN die Person (die darauf verweist), in
    // EINER Transaktion.
    // -----------------------------------------------------------------------
    private function addPerson(Descriptor $d, PersonData $data): Person
    {
        $lastName = Str::upper(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 = Str::lower($data->login ?: $lastName);
        $password = $data->password ?: $login;

        return $this->transaction(function () use ($d, $data, $lastName, $firstName, $login, $password) {
            $this->checkPersonUnique($d, $firstName, $lastName, null);
            $this->checkLoginFree($login);
            // Hash::make: der bcrypt-Hash des Passworts (siehe config/hashing.php)
            $user = $this->users->add($login, Hash::make($password), "$firstName $lastName", $d->role);
            $person = $d->dao->add(['title' => $data->title, 'last_name' => $lastName,
                'first_name' => $firstName, 'user' => $user->id]);
            // setRelation: das bereits im Speicher befindliche Konto wird in der Relation
            // [account] der Person abgelegt (kein erneutes Lesen aus der Datenbank nötig)
            return $person->setRelation('account', $user);
        });
    }

    // -----------------------------------------------------------------------
    // Änderung: die Person UND ihr Konto (der angezeigte Name "Vorname NACHNAME" muss
    // nachgefü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);

            // optimistische Sperre: Entspricht die Version in der Datenbank nicht mehr der des
            // Formulars, hat jemand diesen Datensatz zwischenzeitlich geändert - wir lehnen ab,
            // statt seine Änderungen stillschweigend zu überschreiben
            $version = $data->version ?? $person->version;
            if ($version !== $person->version) {
                throw new BusinessException('ERRORS.CONCURRENT_UPDATE');
            }

            $lastName = Str::upper(trim($data->lastName));
            $firstName = trim($data->firstName);
            $this->checkPersonUnique($d, $firstName, $lastName, $id);

            // die Person: UPDATE ... WHERE id = ? AND version = ? (wurde der Datensatz
            // NACH dem obigen Lesen geändert, wird keine Zeile geändert)
            if ($d->dao->edit($id, $version, ['title' => $data->title, 'last_name' => $lastName,
                'first_name' => $firstName]) === 0) {
                throw new BusinessException('ERRORS.CONCURRENT_UPDATE');
            }

            // ihr Konto: der angezeigte Name und, falls eingegeben, Login und
            // Passwort
            $account = $person->account;
            $columns = ['name' => "$firstName $lastName"];
            $login = $data->login ? Str::lower($data->login) : null;
            if ($login !== null && $login !== $account->login) {
                $this->checkLoginFree($login);
                $columns['login'] = $login;
            }
            if ($data->password) {
                $columns['password'] = Hash::make($data->password);
            }
            if ($this->users->edit($account->id, $account->version, $columns) === 0) {
                throw new BusinessException('ERRORS.CONCURRENT_UPDATE');
            }

            // die erneut gelesene Person: ihre neuen Werte, ihre neuen Versionen
            return $d->dao->read($id);
        });
    }

    // -----------------------------------------------------------------------
    // Löschen, in EINER Transaktion, in der durch die Fremdschlüssel vorgegebenen
    // Reihenfolge:
    //   1. mögliche Ablehnung, wenn noch Termine vorhanden sind (Arzt);
    //   2. was auf die Person verweist (Zeitfenster eines Arztes, Termine eines
    //      Clients);
    //   3. die Person (die auf ihr Konto verweist);
    //   4. ihr Konto.
    // -----------------------------------------------------------------------
    private function deletePerson(Descriptor $d, int $id): void
    {
        $this->transaction(function () use ($d, $id) {
            $person = $d->dao->read($id) ?? throw new BusinessException($d->notFoundKey);
            if ($d->countAppointments !== null && ($d->countAppointments)($id) > 0) {
                throw new BusinessException($d->hasAppointmentsKey);
            }
            if ($d->beforeDelete !== null) {
                ($d->beforeDelete)($id);
            }
            $d->dao->remove($id);
            $this->users->remove($person->user);
        });
    }

    // lehnt Vor- und Nachnamen ab, die bereits von einer ANDEREN Person desselben Typs verwendet werden
    // ($currentId: die gerade geänderte Person, die selbstverständlich 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->id !== $currentId) {
            throw new BusinessException($d->alreadyExistsKey);
        }
    }

    private function checkLoginFree(string $login): void
    {
        if ($this->users->readByLogin($login) !== null) {
            throw new BusinessException('ERRORS.LOGIN_TAKEN');
        }
    }

    // -----------------------------------------------------------------------
    // führt [$work] in einer Transaktion aus (DB::transaction, siehe Beispiel 28):
    // COMMIT, wenn die Funktion normal endet; kommt eine Ausnahme heraus
    // (auch BusinessException), ROLLBACK: nichts wird geschrieben.
    //
    // Die Prüfungen "Login frei" und "Vor- und Nachname eindeutig" erfolgen VOR
    // dem Schreiben, um eine klare Meldung zu liefern. Aber zwei ADMINs könnten
    // im selben Moment denselben Login (oder denselben Arzt)
    // speichern: In diesem seltenen Fall lehnt eine SQL-Eindeutigkeitsbedingung den zweiten Schreibvorgang ab. Wir
    // fangen die Datenbankfehler daher RUND UM die Transaktion ab,
    // um sie in dieselbe BusinessException zu übersetzen. Jeder andere Fehler ist eine echte
    // Anomalie: Wir lassen ihn weiterlaufen.
    // -----------------------------------------------------------------------
    private function transaction(Closure $work): mixed
    {
        try {
            return DB::transaction($work);
        } catch (QueryException $e) {
            if (preg_match(self::CONSTRAINT, $e->getMessage(), $m)
                && isset(self::CONSTRAINT_MESSAGES[$m[1]])) {
                throw new BusinessException(self::CONSTRAINT_MESSAGES[$m[1]], previous: $e);
            }
            throw $e;
        }
    }
}

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

11.11.6.1. Die Descriptors

Zeilen 89–113: die beiden Descriptors, einmal vom Konstruktor erzeugt. Die benannten Argumente ([dao: $doctors], Beispiel 01) machen den Aufruf lesbar. [$appointments->countByDoctor(...)] (mit drei Punkten in Klammern) zählt nichts: 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 349). Ein Arzt wird samt seinen Zeitfenstern entfernt ([deleteByDoctor]), aber nicht, wenn er Termine hat; ein Client wird samt allen seinen Terminen entfernt ([deleteByClient]).

11.11.6.2. Lesezugriffe und der Kalender

Die Lesezugriffe (Zeilen 120–165) werden an die DAO-Schicht delegiert. Der Kalender eines Arztes (Zeilen 172–185) wird berechnet: der Arzt, seine Zeitfenster und die Termine des Tages. [keyBy('slot_id')] wandelt die Terminsammlung in eine nach Zeitfensternummer indizierte Sammlung um: [$bookings->get($slot->id)] gibt den Termin für ein bestimmtes Zeitfenster zurück oder [null]. [map] wandelt jedes Zeitfenster in ein [DoctorDaySlot] um; [all()] gibt das [PHP] -Array zurück, das die Sammlung enthält.

11.11.6.3. Einen Termin vereinbaren

Zeilen 203–217: vier Schritte in einer einzigen Transaktion.

  • Keine Termine in der Vergangenheit: [$day->lt($today)] (*less than*) vergleicht zwei Datumsangaben;
  • Der Datensatz des Patienten wird gesperrt ([lock], [SELECT ... FOR UPDATE]). Warum? Die Regel „nur ein bevorstehender Termin pro Patient“ wird durch eine Zählung geprüft (dritter Schritt), danach erfolgt das Einfügen (vierter Schritt). Wenn derselbe Patient zwei Zeitfenster gleichzeitig bucht (zwei Tabs, ein Doppelklick), könnten beide Transaktionen null Termine zählen und dann jeweils einen 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, gibt [lock] [null] zurück, und der Operator [??] wertet seinen zweiten Operanden aus, der die Ausnahme auslöst (denn seit [PHP] 8 ist [throw] ein Ausdruck);
  • Zählen der bevorstehenden Termine;
  • Einfügen. Wurde das Zeitfenster gerade von einem anderen Patienten belegt, weist der 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 229–256) rufen die gemeinsamen privaten Methoden mit dem passenden Descriptor auf.

  • Zeilen 265–285: das Anlegen. Der Nachname wird großgeschrieben ([Str::upper]), und Vor- und Nachname werden von überflüssigen Leerzeichen befreit ([trim]). Standardmäßig ist das Login der kleingeschriebene Nachname und das Passwort das Login (gemäß den Regeln für die Demokonten): [$a ?: $b] entspricht [$a] , wenn es „gültig“ ist (weder [null] noch ein leerer String), und [$b] andernfalls. In der Transaktion: die Validierungen (Vor- und Nachname sowie Login verfügbar), dann das Konto, gehasht mit [Hash::make] (Beispiel 25), dann die Person, die auf das Konto verweist. [setRelation('account', $user)] speichert das bereits im Speicher befindliche Konto im Datensatz der Person: [$person->account] löst keine Abfrage aus. [use (...)]: Eine gewöhnliche anonyme Funktion ([function () use ($d, ...)]) sieht die Variablen der umschließenden Methode nicht; [use] reicht sie ihr weiter (eine Arrow-Funktion, [fn () =>], sieht sie von selbst, kann aber nur einen Ausdruck enthalten);
  • Zeilen 291–334: das Ändern, mit zwei optimistischen Sperren. Die erste ist ein Vergleich: 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 seinem Absenden geändert. Die zweite ist die Klausel [WHERE version = ?] des [UPDATE] ([PersonDao::edit]), die eine Änderung erkennt, die zwischen Lesen und Schreiben erfolgt ist. Das Konto wird wie folgt behandelt: Sein Anzeigename („Vorname NACHNAME“) wird immer aktualisiert; Login und Passwort nur, wenn sie eingegeben wurden; seine eigene optimistische Sperre schützt außerdem die Zeile in der Tabelle [users]. Die Person wird schließlich erneut gelesen: Der Aufrufer erhält ihre neuen Werte und neuen Versionen;
  • Zeilen 345–358: das Löschen, in der durch die Fremdschlüssel vorgegebenen Reihenfolge: zuerst das, was auf die Person verweist (Zeitfenster oder Termine), dann die Person, dann ihr Konto. Die umgekehrte Reihenfolge würde von der Datenbank abgewiesen: Eine Zeile, auf die noch ein Fremdschlüssel verweist, kann nicht gelöscht werden;
  • Zeilen 363–369: Die Person, die geändert wird, darf ihren eigenen Vor- und Nachnamen behalten; [$currentId] entspricht [null] bei einem neuen Datensatz.

11.11.6.5. Transaktionen und Eindeutigkeits-Constraints

Zeilen 391–402: Alle Schreibvorgänge laufen über diese Methode. [DB::transaction] führt die Funktion in einer Transaktion aus (Beispiel 28): [COMMIT] , wenn sie normal endet, [ROLLBACK] , wenn eine Ausnahme auftritt – einschließlich [BusinessException]: Ein Regelverstoß mitten in einer Operation hinterlässt keine Spuren. Die Prüfungen „Login verfügbar“ und „Vor- und Nachname verfügbar“ erfolgen vor dem Schreiben in die Datenbank, um eine klare Meldung zu liefern. Zwei Administratoren könnten jedoch gleichzeitig versuchen, dasselbe Login zu registrieren: Jeder findet es verfügbar, und das zweite [INSERT] wird vom Constraint [unq_users_login] zurückgewiesen. [Laravel] löst dann eine [QueryException] aus, deren Meldung die von [MySQL] ist; sie enthält den Namen des verletzten Constraints:

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

Der reguläre Ausdruck in Zeile 74 extrahiert diesen Namen ([MySQL] 8 stellt ihm den Tabellennamen voran, [users.unq_users_login], [MariaDB] dagegen nicht: Der Teil "[(?:[^'.]*\.)?]" akzeptiert beide Formen), und das Array in den Zeilen 67–72 liefert den Meldungsschlüssel. Jeder andere Datenbankfehler ist eine echte Anomalie: Er wird erneut geworfen ([throw $e]) und führt zu einer 500-Fehlerseite.

11.12. Authentifizierung

Der Ordner [app/Auth] umfasst die Beispiele 25 bis 27 mit Datenbankbenutzern und einigen zusätzlichen Sicherheitsmaßnahmen.

11.12.1. app/Auth/ConnectedUser.php

<?php
// =========================================================================
// app/Auth/ConnectedUser.php: der angemeldete Benutzer, wie er durch sein
// JWT-Token beschrieben wird (siehe Beispiel 25). Authenticatable: die Schnittstelle, die Laravel von
// authentifizierten Benutzern erwartet (Auth::user(), auth()->user(), @auth in einer View ...).
//
// Die Claims unserer Token (siehe AuthService::tokenCookie):
//   sub   : die ID des Benutzerkontos (JWT-Konvention: "subject"), als Text
//   login : der Login
//   name  : der angezeigte Name ("Marie PELISSIER") für die Navigationsleiste
//   role  : ADMIN, DOCTOR oder USER
//   iat, exp : Erstellungs- und Ablaufzeitpunkt 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\Auth;

use App\Models\Role;
use Illuminate\Contracts\Auth\Authenticatable;

readonly class ConnectedUser implements Authenticatable
{
    public function __construct(
        public int $userId,
        public string $login,
        public string $name,
        public Role $role,
    ) {
    }

    // der durch die Claims eines bereits verifizierten Tokens beschriebene Benutzer; null, wenn ein Claim
    // fehlt oder nicht die erwartete Form hat. Role::tryFrom: null bei unbekannter 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;
    }

    // ---- die Schnittstelle Authenticatable: der Bezeichner des Benutzers ist die ID
    // seines Kontos; das Passwort und das "Remember-me"-Token der Laravel-
    // Sessions spielen hier keine Rolle
    public function getAuthIdentifierName(): string
    {
        return 'userId';
    }

    public function getAuthIdentifier(): int
    {
        return $this->userId;
    }

    public function getAuthPasswordName(): string
    {
        return '';
    }

    public function getAuthPassword(): string
    {
        return '';
    }

    public function getRememberToken(): ?string
    {
        return null;
    }

    public function setRememberToken($value): void
    {
    }

    public function getRememberTokenName(): string
    {
        return '';
    }
}

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 [Authenticatable], die [Laravel] von authentifizierten Benutzern erwartet. Dieses Objekt stammt nicht aus der Datenbank: Es wird für jede Anfrage anhand des Tokens rekonstruiert, dessen Signatur seinen Inhalt garantiert. Die Anwendung liest das Konto daher nicht bei jeder Anfrage aus der Datenbank.

  • Zeilen 35–43: Der Benutzer wird durch die Claims eines bereits verifizierten Tokens beschrieben, oder durch [null] , wenn einer der Claims fehlt oder nicht das erwartete Format hat. Ein korrekt signiertes Token sollte nie fehlerhaft sein; der geheime Schlüssel könnte jedoch mit einer anderen Anwendung geteilt werden, die andere Token erzeugt: Vorsicht kostet nichts. [Role::tryFrom] gibt die Rolle zurück oder [null] bei einem unbekannten Wert; [ctype_digit] prüft, ob ein String nur aus Ziffern besteht;
  • Zeilen 45–50: zwei Fragen, die Views und Controller häufig stellen;
  • Zeilen 58–61 und folgende: die Schnittstelle [Authenticatable]. Der Bezeichner des Benutzers ist seine Konto-ID; das Passwort und das „Angemeldet bleiben“-Token sind ohne Bedeutung.

11.12.2. app/Auth/AuthService.php

<?php
// =========================================================================
// app/Auth/AuthService.php: die Authentifizierungslogik:
//   - validate()       : prüft ein Login-/Passwort-Paar;
//   - tokenCookie()    : erstellt das JWT-Token eines validierten Benutzers und das
//                        Cookie, das es transportiert;
//   - 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 von selbst bei jeder
// Anfrage mit. Die Optionen dieses Cookies sind sicherheitsrelevant:
//   - HttpOnly: Das JavaScript der Seite kann das Cookie nicht lesen (ein eingeschleustes
//     Skript könnte das Token somit nicht stehlen);
//   - SameSite=Lax: Der Browser sendet das Cookie NICHT bei einem POST, der von
//     einer anderen Site kommt (erster Schutz gegen den sogenannten CSRF-Angriff; der zweite ist
//     das Anti-CSRF-Token der Formulare, siehe @csrf);
//   - Secure: In der Produktion (HTTPS) wird das Cookie nie unverschlüsselt übertragen;
//   - Lebensdauer: Das Cookie verschwindet zugleich mit dem Ablauf des Tokens.
// =========================================================================

namespace App\Auth;

use App\Dao\UserDao;
use App\Models\User;
use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use Illuminate\Support\Facades\Hash;
use RuntimeException;
use Symfony\Component\HttpFoundation\Cookie;
use Throwable;

class AuthService
{
    // der Name des Cookies, das das Token trägt
    public const COOKIE = 'rdvmedecins_jwt';

    private string $secret;

    private int $duration;

    public function __construct(private UserDao $users)
    {
        $this->secret = config('rdvmedecins.jwt.secret');
        $this->duration = config('rdvmedecins.jwt.duration');
        // HMAC-SHA256 erfordert einen Schlüssel von mindestens 256 Bit: Wir sagen das deutlich,
        // statt die Bibliothek 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 der Login nicht existiert oder das Passwort falsch ist. Hash::check
    // 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 || ! Hash::check($password, $user->password)) {
            return null;
        }
        return $user;
    }

    // -----------------------------------------------------------------------
    // das JWT-Token von [$user] im Cookie, das es transportiert. 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->id,
            'login' => $user->login,
            'name' => $user->name,
            'role' => $user->role->value,
            'iat' => $now,
            'exp' => $now + $this->duration * 60,
        ];
        $token = JWT::encode($claims, $this->secret, 'HS256');
        // cookie(name, value, duration in minutes, path, domain, secure, httpOnly,
        // raw, sameSite): die Laravel-Funktion, die ein Cookie erstellt
        return cookie(self::COOKIE, $token, $this->duration, '/', null,
            config('rdvmedecins.cookie_secure'), true, false, 'lax');
    }

    // das Cookie, das das Token LÖSCHT: derselbe Name, leer, bereits abgelaufen
    public static function clearingCookie(): Cookie
    {
        return cookie()->forget(self::COOKIE);
    }

    // -----------------------------------------------------------------------
    // 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 liefert ein Objekt; (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 35: der Name des Token-Cookies, eine Klassenkonstante, gelesen über [AuthService::COOKIE]. Warum nicht in [config/rdvmedecins.php] konfigurieren, wie den geheimen Schlüssel? Weil [bootstrap/app.php] ihn benötigt, um das Cookie von der Verschlüsselung auszunehmen, zu einem Zeitpunkt, an dem die Konfiguration noch nicht geladen ist: Der Code von [withMiddleware] läuft, bevor [Laravel] die Dateien im Ordner [config] gelesen hat;
  • Zeilen 41–50: der Schlüssel und die Lebensdauer des Tokens, aus der Konfiguration gelesen. Ist der Schlüssel zu kurz, wird dies bereits beim Erzeugen des Services mit einer klaren Meldung angezeigt (siehe „Häufige Probleme“);
  • Zeilen 55–62: Ü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 70–86: das Token des Benutzers und das Cookie, das es trägt. Die Claims sind dieselben wie in Beispiel 25, einschließlich der Konto-ID ([sub], ein String, wie vom Standard gefordert) und des Benutzernamens. Die Funktion [cookie] von [Laravel] erzeugt ein Cookie: Name, Wert, Lebensdauer in Minuten (die des Tokens), Pfad, Domain ([null]: die der Site), [secure] (in der Produktion über HTTPS), [httpOnly], [raw] ([false]: Der Wert wird für eine URL kodiert) und [sameSite];
  • Zeilen 89–92: das Cookie, das das Token löscht: [cookie()->forget(name)] erzeugt ein leeres Cookie mit demselben Namen, das bereits abgelaufen ist;
  • Zeilen 98–107: Überprüfung des Tokens (Beispiel 25).

11.12.3. app/Auth/InvalidSession.php

<?php
// app/Auth/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: bootstrap/app.php löscht das Cookie und leitet zur Login-Seite weiter.

namespace App\Auth;

use RuntimeException;

class InvalidSession extends RuntimeException
{
}

Ein in Beispiel 25 nicht behandelter Fall: 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 in einem anderen Tab noch 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], siehe später), stellt sie fest, dass das Konto nicht mehr existiert. Sie wirft dann diese Ausnahme, die [bootstrap/app.php] als abgelaufene Sitzung behandelt. Die Klasse ist leer: Nur ihr Typ zählt, was es erlaubt, ihr eine eigene Rendering-Funktion zuzuordnen.

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

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

<?php
// =========================================================================
// app/Auth/CaptchaService.php: ein CAPTCHA ("Test zur Unterscheidung von Mensch und
// Roboter"), vom Server selbst erzeugt, ohne externen Dienst (siehe Beispiel 27).
//
// Funktionsweise:
//   1. generate() zieht einen zufälligen Text, erzeugt daraus ein Bild und legt die richtige
//      Antwort IM CACHE des Servers unter einer zufälligen Kennung ab;
//   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 NICHTS im Speicher von einer Anfrage zur
// nächsten: Jede Anfrage beginnt bei null. Was über eine Anfrage hinaus bestehen soll,
// kommt daher in den Cache (hier Dateien, siehe CACHE_STORE in .env), der von
// allen Anfragen geteilt wird, und mit einem Cache wie Redis sogar von mehreren Servern.
// =========================================================================

namespace App\Auth;

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

class CaptchaService
{
    // Gültigkeitsdauer eines Bilds in Sekunden: 10 Minuten zum Ausfüllen des Formulars
    private const LIFETIME = 600;

    public function generate(): Captcha
    {
        $text = CaptchaDrawing::randomText(5);        // 5 Zeichen
        $id = Str::random(24);                        // eine nicht zu erratende Kennung
        // der Cache vergisst die Antwort nach 10 Minuten von selbst
        Cache::put("captcha:$id", $text, self::LIFETIME);
        return new Captcha($id, CaptchaDrawing::svg($text));
    }

    // true, wenn [$typed] die richtige Antwort auf das CAPTCHA [$id] ist (unabhängig von
    // der Groß-/Kleinschreibung). Das CAPTCHA wird in jedem Fall verbraucht.
    public function verify(?string $id, ?string $typed): bool
    {
        if (! $id || $typed === null) {
            return false;
        }
        $expected = Cache::get("captcha:$id");
        // forget liefert nur für die Anfrage true, die den Eintrag TATSÄCHLICH entfernt hat:
        // Legen zwei Anfragen im selben Moment dasselbe CAPTCHA vor, entfernt es nur eine -
        // die andere scheitert
        if ($expected === null || ! Cache::forget("captcha:$id")) {
            return false;
        }
        return strcasecmp($expected, trim($typed)) === 0;
    }
}
  • Zeilen 31–38: ein zufällig erzeugter String mit 5 Zeichen, ein zufälliger Bezeichner ([Str::random], der einen kryptografischen Generator verwendet) und die richtige Antwort, 10 Minuten lang im Cache gespeichert (Beispiel 27);
  • Zeilen 42–55: ein Unterschied zu Beispiel 27, das [Cache::pull] verwendete (lesen, dann entfernen). Zwischen Lesen und Entfernen könnte eine zweite Anfrage, die dasselbe CAPTCHA anzeigt, es ebenfalls lesen: zwei Versuche für ein einziges gelöstes Bild. Hier wird die Antwort gelesen und dann mit [Cache::forget] entfernt, das [true] nur zurückgibt, wenn es den Eintrag tatsächlich entfernt hat: Beim Datei-Cache bedeutet das, eine Datei zu löschen, was das Betriebssystem nur einem der beiden Prozesse erlaubt. Die Anfrage, die das Rennen verliert, schlägt fehl. Das entspricht der Sperre in der Version [Flask], in der die CAPTCHAs im Speicher gehalten wurden.

11.12.5. app/Auth/AttemptLimiter.php

<?php
// =========================================================================
// app/Auth/AttemptLimiter.php: zweite Verteidigungslinie gegen Roboter (die erste ist
// das CAPTCHA): Wir ZÄHLEN die Versuche und SPERREN oberhalb eines Schwellenwerts für
// eine gewisse Zeit (siehe Beispiel 27).
//
//   - Login: Nach LOGIN_MAX_FAILURES Fehlversuchen (falsches CAPTCHA oder falsches
//     Passwort) für denselben Login von derselben IP-Adresse wird dieses Paar
//     bis zum Ende eines Fensters von LOGIN_BLOCK_MINUTES Minuten gesperrt, gerechnet
//     ab dem ersten Fehlversuch. Dieselbe IP-Adresse wird auch gesperrt, wenn sie 5-mal
//     mehr Fehlversuche 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 ein falsches Passwort eingibt, sperrt seine
// Nachbarn nicht - und deshalb sind die Schwellenwerte einstellbar (Datei .env).
//
// Die Zähler stammen vom Limiter von Laravel (RateLimiter) und liegen im Cache.
// =========================================================================

namespace App\Auth;

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

class AttemptLimiter
{
    private int $maxFailures;

    private int $block;    // in Sekunden

    private int $maxRegistrations;

    public function __construct()
    {
        $this->maxFailures = config('rdvmedecins.login_max_failures');
        $this->block = config('rdvmedecins.login_block_minutes') * 60;
        $this->maxRegistrations = config('rdvmedecins.registration_max_per_hour');
    }

    // ---------------------------------------------------------------- Login

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

    // RateLimiter::hit: +1 auf den Zähler; der erste Hit öffnet ein Fenster von
    // [$this->block] Sekunden, an dessen Ende der Zähler wieder bei null beginnt
    public function loginFailure(string $ip, string $login): void
    {
        RateLimiter::hit(self::loginKey($ip, $login), $this->block);
        RateLimiter::hit(self::ipKey($ip), $this->block);
    }

    // ein erfolgreicher Login setzt den Zähler DIESES Logins zurück
    public function loginSuccess(string $ip, string $login): void
    {
        RateLimiter::clear(self::loginKey($ip, $login));
    }

    // ---------------------------------------------------------------- Registrierung

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

    // Fenster von einer Stunde
    public function registrationSuccess(string $ip): void
    {
        RateLimiter::hit("registration|$ip", 3600);
    }

    // ---------------------------------------------------------------- gemeinsame Mechanik

    // tooManyAttempts: Hat der Zähler im aktuellen Fenster [$maximum] erreicht?
    // availableIn: verbleibende Sekunden bis zum Ende dieses Fensters,
    // AUFGERUNDET auf die Minute: 30 s verbleibend -> "1 minute"
    private function remainingMinutes(string $key, int $maximum): int
    {
        if (! RateLimiter::tooManyAttempts($key, $maximum)) {
            return 0;
        }
        return max(1, (int) ceil(RateLimiter::availableIn($key) / 60));
    }

    private static function loginKey(string $ip, string $login): string
    {
        return "login|$ip|".Str::lower(trim($login));
    }

    private static function ipKey(string $ip): string
    {
        return "ip|$ip";
    }
}

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 den Limiter von [Laravel] vor, die Fassade [RateLimiter]. Diese Klasse verwendet ihn für zwei Regeln:

  • Anmeldung (Zeilen 47–62): Jeder fehlgeschlagene Versuch (falsches CAPTCHA oder Passwort) wird doppelt gezählt – einmal für das Paar (IP-Adresse, Login) und einmal für die IP-Adresse allein. Das Paar wird nach 5 fehlgeschlagenen Versuchen gesperrt (Einstellung [LOGIN_MAX_FAILURES]), und die IP-Adresse nach 25 ü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 IP-Adresse auf das Internet zu: Ein Schüler, der das falsche Passwort eingibt, soll seine Nachbarn nicht blockieren. [RateLimiter::hit(key, duration)] erhöht den Zähler um 1; der erste [hit] öffnet ein Zeitfenster von 15 Minuten (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 ([RateLimiter::clear]);
  • Kontoerstellung (Zeilen 69–75): höchstens 10 Konten pro Stunde und IP-Adresse (Einstellung [REGISTRATION_MAX_PER_HOUR]);
  • Zeilen 85–91: [tooManyAttempts(key, maximum)] gibt an, ob der Zähler im aktuellen Zeitfenster das Maximum erreicht hat; [availableIn(key)] gibt die in diesem Zeitfenster verbleibenden Sekunden zurück, auf die nächste Minute aufgerundet ([ceil]): Es bleiben 30 Sekunden, aber es wird „1 Minute“ angezeigt. Davon hängt die angezeigte Meldung ab: „Zu viele fehlgeschlagene Versuche. Versuchen Sie es in 15 Minute(n) erneut.“;
  • Zeilen 93–96: die Zähler-Schlüssel. Das Login wird in Kleinbuchstaben umgewandelt: [Admin] und [admin] gelten als gleich (wie bei der Datenbank; siehe deren Kollation).

Die Zähler von [RateLimiter] werden im Cache gespeichert: Sie werden von allen Anfragen geteilt und überstehen einen Neustart des Servers. Der Befehl [php artisan cache:clear] leert den Cache und setzt damit alle Zähler auf null zurück (nützlich in der Entwicklung, wenn man sich selbst ausgesperrt hat).

11.12.6. app/Auth/RegistrationPass.php

<?php
// =========================================================================
// app/Auth/RegistrationPass.php: der "Pass" für die Kontoerstellung.
//
// Um die Seite "Create a client account" zu öffnen, muss man zuvor das
// CAPTCHA der Login-Seite abgeschrieben haben (siehe RegistrationController, POST
// /register/access). Der Server stellt dann einen Pass aus:
//   - eine zufällige Kennung, abgelegt in einem HttpOnly-Cookie;
//   - gültig für 15 Minuten (die Zeit zum Ausfüllen des Formulars, 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
// weiter (Middleware CheckRegistrationPass): Die direkte Eingabe der URL /register
// umgeht das CAPTCHA nicht.
//
// Wie die CAPTCHAs leben auch die Pässe im Cache.
// =========================================================================

namespace App\Auth;

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

class RegistrationPass
{
    public const COOKIE = 'rdvmedecins_registration';

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

    // stellt einen neuen Pass aus; liefert seine Kennung
    public function issue(): string
    {
        $id = Str::random(24);
        Cache::put("pass:$id", true, self::LIFETIME * 60);
        return $id;
    }

    // true, wenn [$id] ein vorhandener, nicht abgelaufener Pass ist
    public function isValid(?string $id): bool
    {
        return $id !== null && $id !== '' && Cache::has("pass:$id");
    }

    // der Pass wurde verwendet: Wir vergessen ihn
    public function consume(?string $id): void
    {
        if ($id) {
            Cache::forget("pass:$id");
        }
    }

    // der Browser sendet das Cookie nur an die Adressen /register ...
    public static function cookie(string $id): Cookie
    {
        return cookie(self::COOKIE, $id, self::LIFETIME, '/register', null,
            config('rdvmedecins.cookie_secure'), true, false, 'lax');
    }

    // ... und es wird durch ein Cookie mit demselben Namen und Pfad gelöscht, das bereits abgelaufen ist
    public static function clearingCookie(): Cookie
    {
        return cookie()->forget(self::COOKIE, '/register');
    }
}

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]): Woran erkennt man beim Aufruf des Formulars, dass das CAPTCHA kurz zuvor gelöst wurde? Durch ein Token: Wird das CAPTCHA gelöst, erzeugt der Server einen zufälligen Bezeichner, speichert ihn 15 Minuten lang im Cache und sendet ihn in einem Cookie an den Browser. Das Formular wird nur angezeigt und das Konto nur angelegt, wenn ein gültiges Token vorliegt; das Token wird beim Anlegen des Kontos verbraucht. Ein gelöstes CAPTCHA erlaubt es somit, ein Konto anzulegen, und die direkte Eingabe der Adresse [/register] funktioniert nicht.

  • Zeilen 57–61: Das Cookie hat den Pfad [/register]; der Browser sendet es nur an Adressen, die mit diesem Pfad beginnen. Es wird von [Laravel] verschlüsselt, wie alle Cookies der Anwendung bis auf zwei (siehe [bootstrap/app.php]): Ohne den Schlüssel der Anwendung kann niemand ein gültiges Cookie erzeugen oder auch nur den Bezeichner lesen;
  • Zeilen 64–67: Um ein Cookie zu löschen, müssen Sie denselben Namen und denselben Pfad angeben: Für den Browser gelten zwei Cookies mit demselben Namen, aber unterschiedlichen Pfaden als zwei verschiedene Cookies.

11.12.7. Middleware: app/Http/Middleware

Drei Middleware-Komponenten im Ordner [app/Http/Middleware], wie üblich.

<?php
// app/Http/Middleware/SetLanguage.php: die Sprache der Anfrage (siehe Beispiel 22):
// die des Cookies [rdvmedecins_language], wenn es eine unterstützte Sprache ist, sonst Englisch.
//
// Eine GLOBALE Middleware (siehe bootstrap/app.php): Sie läuft für ALLE
// Anfragen, auch für solche, die zu keiner Route führen (Seite 405 ...). Sie läuft daher
// VOR der Middleware EncryptCookies der Gruppe [web], die die Cookies entschlüsselt:
// Deshalb ist das Sprach-Cookie von der Verschlüsselung ausgenommen.

namespace App\Http\Middleware;

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

class SetLanguage
{
    // das Cookie, das die gewählte Sprache speichert (siehe LanguageController)
    public const COOKIE = 'rdvmedecins_language';

    // die unterstützten Sprachen (lang/fr.json, lang/en.json); standardmäßig Englisch
    // (config/app.php, Schlüssel locale)
    public const LANGUAGES = ['fr', 'en'];

    public function handle(Request $request, Closure $next): Response
    {
        $language = $request->cookie(self::COOKIE);
        if (in_array($language, self::LANGUAGES, true)) {
            App::setLocale($language);
        }
        return $next($request);
    }
}

Die Sprache der Anfrage (Beispiel 22): die im Cookie angegebene Sprache, sofern sie unterstützt wird; andernfalls die Standardsprache der Konfiguration (Englisch). Die Sprachen und der Cookie-Name sind aus demselben Grund Konstanten wie der Name des Token-Cookies. Diese Middleware ist global (siehe [bootstrap/app.php]).

<?php
// app/Http/Middleware/RequireRoles.php: Die Rolle des Benutzers muss eine der
// von der Route aufgeführten sein; andernfalls Antwort 403 (eine Fehlerseite, siehe
// bootstrap/app.php). Eine Middleware MIT PARAMETERN: In routes/web.php ruft
//   ->middleware('role:ADMIN,DOCTOR')
// handle($request, $next, 'ADMIN', 'DOCTOR') auf; ...$roles nimmt sie alle entgegen.
//
// Sie läuft NACH der Authentifizierungs-Middleware (siehe bootstrap/app.php):
// Der Benutzer ist also bekannt.

namespace App\Http\Middleware;

use App\Web\Utils;
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class RequireRoles
{
    public function handle(Request $request, Closure $next, string ...$roles): Response
    {
        if (! in_array(Utils::user()->role->value, $roles, true)) {
            abort(403);
        }
        return $next($request);
    }
}

Eine Middleware mit Parametern. In [routes/web.php] verweist [->middleware('role:ADMIN,DOCTOR')] auf die Alias-Middleware [role] (siehe [bootstrap/app.php]), und zwar mit zwei Parametern: [Laravel] ruft [handle($request, $next, 'ADMIN', 'DOCTOR')] auf. Der variadische Parameter [string ...$roles] erhält alle übrigen Parameter in einem Array (Zeile 20). Fehlt eine Rolle in der Liste, folgt eine 403-Antwort ([abort(403)], Beispiel 24). Das entspricht der Middleware [can:admin] aus Beispiel 26, nur ohne die Definition eines [Gate]: Die Anwendung kennt nur Rollenregeln. Diese Middleware steht stets auf Routen, die durch [Authenticate] geschützt sind und vor ihr ausgeführt werden: [Authenticate] gehört zur Gruppe [web], deren Middleware vor der Middleware der Route läuft. Der Benutzer ist somit bekannt.

<?php
// app/Http/Middleware/CheckRegistrationPass.php: GET und POST /register
// erfordern einen gültigen Pass (siehe app/Auth/RegistrationPass.php); andernfalls
// zurück zur Login-Seite, mit einer Meldung. Die direkte Eingabe der URL
// /register umgeht das CAPTCHA somit nicht.

namespace App\Http\Middleware;

use App\Auth\RegistrationPass;
use App\Web\Flash;
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class CheckRegistrationPass
{
    public function __construct(private RegistrationPass $passes)
    {
    }

    public function handle(Request $request, Closure $next): Response
    {
        if (! $this->passes->isValid($request->cookie(RegistrationPass::COOKIE))) {
            Flash::error('ERRORS.CAPTCHA_BEFORE_ACCOUNT');
            return redirect()->route('login');
        }
        return $next($request);
    }
}

Kein gültiges Token: Weiterleitung zur Login-Seite mit einer Meldung. Die Middleware erhält den Token-Service über ihren Konstruktor: [Laravel] erstellt die Middleware mithilfe des Containers, der ihr ihre Abhängigkeiten bereitstellt, genau wie bei den Controllern.

11.12.8. app/Http/Controllers/AuthController.php

<?php
// =========================================================================
// app/Http/Controllers/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 gegen Roboter, in dieser Reihenfolge:
//   1. zu viele kürzliche Fehlversuche für diesen Login von dieser IP-Adresse?
//      -> sofortige Ablehnung, ohne das Passwort auch nur anzusehen;
//   2. falsche Antwort auf das CAPTCHA? -> Ablehnung (zählt als Fehlversuch);
//   3. erst dann die Prüfung des Passworts.
// Das Passwort eines in Schritt 1 oder 2 abgelehnten Versuchs prüfen wir NIE:
// Ein Roboter kann daher durch Beharrlichkeit nichts lernen.
// =========================================================================

namespace App\Http\Controllers;

use App\Auth\AuthService;
use App\Auth\CaptchaService;
use App\Auth\AttemptLimiter;
use App\Models\Role;
use App\Web\Message;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Str;
use Illuminate\View\View;

class AuthController
{
    public function __construct(
        private AuthService $auth,
        private CaptchaService $captchas,
        private AttemptLimiter $limiter,
    ) {
    }

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

    // -----------------------------------------------------------------------
    // GET /
    // Die Route ist öffentlich: Der Benutzer, falls vorhanden, ist bekannt (Auth::user()),
    // aber es wird nichts verlangt.
    // -----------------------------------------------------------------------
    public function home(): RedirectResponse
    {
        $user = Auth::user();
        return redirect($user ? self::homePage($user->role) : route('login'));
    }

    // -----------------------------------------------------------------------
    // GET /login[?login=xxx]: Der optionale Parameter füllt das Login-Feld vor
    // (verwendet direkt nach dem Anlegen eines Kontos, siehe RegistrationController)
    // -----------------------------------------------------------------------
    public function showLogin(Request $request): View|RedirectResponse
    {
        // bereits angemeldet (Token noch gültig): direkt zur Startseite
        if ($user = Auth::user()) {
            return redirect(self::homePage($user->role));
        }
        return $this->page(Str::limit((string) $request->query('login', ''), 30, ''), null);
    }

    // -----------------------------------------------------------------------
    // POST /login
    // -----------------------------------------------------------------------
    public function logIn(Request $request): View|RedirectResponse
    {
        $login = (string) $request->input('login', '');
        $password = (string) $request->input('password', '');
        $ip = (string) $request->ip();

        // 1. zu viele kürzliche Fehlversuche?
        $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->input('captchaId'), $request->input('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);
        return redirect(self::homePage($user->role))->withCookie($this->auth->tokenCookie($user));
    }

    // -----------------------------------------------------------------------
    // POST /logout: das Token-Cookie löschen, dann zur Login-Seite weiterleiten.
    // Nur POST: Ein einfacher Link (GET), der auf einer anderen Site platziert ist, kann
    // den Benutzer nicht ohne sein Wissen abmelden.
    // -----------------------------------------------------------------------
    public function logOut(): RedirectResponse
    {
        return redirect()->route('login')->withCookie(AuthService::clearingCookie());
    }

    // das Formular, immer mit einem NEUEN CAPTCHA (jedes Bild wird nur einmal
    // verwendet); wir zeigen den eingegebenen Login erneut an, nie das Passwort
    private function page(string $login, ?Message $error): View
    {
        return view('login', ['pageTitle' => 'LOGIN.TITLE', 'error' => $error, 'login' => $login,
            'captcha' => $this->captchas->generate()]);
    }
}

Der Login-Controller, der auf Beispiel 27 basiert.

  • Zeilen 41–44: die Startseite je Rolle: „Mein Bereich“ für einen Patienten, der Terminkalender für die anderen. [route('area')] erzeugt die URL der Route mit dem Namen [area] (Beispiel 04);
  • Zeilen 51–55: Die Adresse [/] leitet zur Startseite der Rolle oder zur Login-Seite weiter. Die Route ist öffentlich: [Auth::user()] liefert den Benutzer, sofern vorhanden, ohne dass dafür eine Eingabe erforderlich ist;
  • Zeilen 61–68: Ein bereits angemeldeter Benutzer gelangt direkt zu seiner Startseite. Der optionale URL-Parameter [login] füllt das Feld vor (nach der Erstellung eines Kontos); [Str::limit] kürzt ihn auf 30 Zeichen, ohne etwas anzuhängen (der dritte Parameter [''] ersetzt die übliche Auslassung „...“);
  • Zeilen 73–100: der Login-Ablauf in der Reihenfolge aus Beispiel 27: mögliche Sperre, CAPTCHA, Passwort. Das Passwort wird nie für einen Versuch geprüft, den der Limiter oder das CAPTCHA abgelehnt hat: Ein Bot lernt nichts, wenn er beharrlich weitermacht. Im Fehlerfall wird die Seite direkt gerendert (keine Weiterleitung): Das erneut angezeigte Formular enthält stets ein neues CAPTCHA und den eingegebenen Benutzernamen. Der Fehler ist ein Objekt [Message] (siehe unten), also ein Schlüssel mit seinen Parametern, der am Seitenende angezeigt wird. Bei Erfolg wird der Login-Zähler auf null zurückgesetzt, und der Browser wird mit dem Token-Cookie zur Startseite der Rolle weitergeleitet ([withCookie]);
  • Zeilen 107–110: Die Abmeldung löscht das Token-Cookie (Beispiel 25).

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

11.13. Die Web-Schicht: gemeinsame Services

Der Ordner [app/Web] enthält die Elemente, die sich die Controller teilen.

11.13.1. app/Web/ApplicationModel.php

<?php
// =========================================================================
// app/Web/ApplicationModel.php: der Cache / die Fassade der Geschäftsschicht (das Äquivalent
// der Klasse [ApplicationModel] der anderen Versionen der Anwendung): die
// Listen der Ärzte und Clients werden einmal aus der Datenbank gelesen und dann
// aus dem Cache geliefert.
//
// Warum der CACHE von Laravel 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 Singleton (siehe AppServiceProvider), aber ein Singleton lebt nur
// für die Dauer EINER Anfrage. Der Cache hingegen wird von allen Anfragen geteilt (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 Schreibvorgang 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. Darin liegt
// der ganze 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\Business\PersonData;
use App\Business\Business;
use App\Business\BusinessService;
use App\Models\Client;
use App\Models\Slot;
use App\Models\Doctor;
use App\Models\Appointment;
use Carbon\CarbonImmutable;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Support\Facades\Cache;

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

    private const CLIENTS = 'rdvmedecins.clients';

    public function __construct(private BusinessService $business)
    {
    }

    // ------------------------------------------------ Lesezugriffe aus dem Cache

    // rememberForever: der Wert aus dem Cache, falls vorhanden; andernfalls wird die Funktion
    // aufgerufen und ihr Ergebnis (ohne Zeitlimit) im Cache abgelegt, bevor es
    // zurückgegeben wird
    public function getAllDoctors(): Collection
    {
        return Cache::rememberForever(self::DOCTORS, fn () => $this->business->getAllDoctors());
    }

    public function getAllClients(): Collection
    {
        return Cache::rememberForever(self::CLIENTS, fn () => $this->business->getAllClients());
    }

    // der Arzt, dessen Benutzerkonto [$userId] ist - dient dazu, bei einem angemeldeten Arzt
    // seinen eigenen Terminkalender vorauszuwählen. firstWhere: das erste Element
    // der Collection, dessen Eigenschaft [user] gleich $userId ist
    public function getDoctorByUserId(int $userId): ?Doctor
    {
        return $this->getAllDoctors()->firstWhere('user', $userId);
    }

    // ------------------------------------------------ einfache Delegationen

    public function getAllSlots(int $doctorId): Collection
    {
        return $this->business->getAllSlots($doctorId);
    }

    public function getDoctorDayAppointments(int $doctorId, CarbonImmutable $day): Collection
    {
        return $this->business->getDoctorDayAppointments($doctorId, $day);
    }

    public function getClientById(int $id): ?Client
    {
        return $this->business->getClientById($id);
    }

    public function getDoctorById(int $id): ?Doctor
    {
        return $this->business->getDoctorById($id);
    }

    public function getAppointmentById(int $id): ?Appointment
    {
        return $this->business->getAppointmentById($id);
    }

    public function getSlotById(int $id): ?Slot
    {
        return $this->business->getSlotById($id);
    }

    public function getDoctorDaySchedule(int $doctorId, CarbonImmutable $day): ?DoctorDaySchedule
    {
        return $this->business->getDoctorDaySchedule($doctorId, $day);
    }

    // kein Cache hier: Es zählen die aktuellsten Daten (ein Patient, der
    // gerade sein Konto geändert oder gelöscht hat)
    public function getClientByUserId(int $userId): ?Client
    {
        return $this->business->getClientByUserId($userId);
    }

    public function getClientUpcomingAppointments(int $clientId): Collection
    {
        return $this->business->getClientUpcomingAppointments($clientId);
    }

    public function addAppointment(CarbonImmutable $day, Slot $slot, Client $client): Appointment
    {
        return $this->business->addAppointment($day, $slot, $client);
    }

    public function deleteAppointment(Appointment $appointment): void
    {
        $this->business->deleteAppointment($appointment);
    }

    // ------------------------------------------------ Schreibzugriffe => Cache vergessen

    public function addDoctor(PersonData $data): Doctor
    {
        return tap($this->business->addDoctor($data), fn () => Cache::forget(self::DOCTORS));
    }

    public function editDoctor(int $id, PersonData $data): Doctor
    {
        return tap($this->business->editDoctor($id, $data), fn () => Cache::forget(self::DOCTORS));
    }

    public function deleteDoctor(int $id): void
    {
        $this->business->deleteDoctor($id);
        Cache::forget(self::DOCTORS);
    }

    public function addClient(PersonData $data): Client
    {
        return tap($this->business->addClient($data), fn () => Cache::forget(self::CLIENTS));
    }

    public function editClient(int $id, PersonData $data): Client
    {
        return tap($this->business->editClient($id, $data), fn () => Cache::forget(self::CLIENTS));
    }

    public function deleteClient(int $id): void
    {
        $this->business->deleteClient($id);
        Cache::forget(self::CLIENTS);
    }
}

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

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

  • Zeilen 51–54: [Cache::rememberForever(key, function)] liefert den unter diesem Schlüssel gespeicherten Wert; existiert er nicht, ruft die Methode die Funktion auf (die die Liste aus der Datenbank liest), speichert deren Ergebnis unbegrenzt im Cache und gibt es zurück. Die erste Anfrage, die die Liste benötigt, liest sie aus der Datenbank; die folgenden Anfragen finden sie im Cache. Der Cache speichert die Collection der [Eloquent]-Objekte in serialisierter Form (Beispiel 20) und rekonstruiert sie beim Lesen zusammen mit den geladenen Beziehungen (dem Konto jeder Person);
  • Zeilen 64–67: der einem Konto zugeordnete Arzt, aus der Cache-Liste abgerufen: [firstWhere('user', $userId)] liefert das erste Element der Collection, dessen Eigenschaft [user] gleich [$userId] ist;
  • Zeilen 71–123: Die übrigen Methoden des [Business]-Vertrags delegieren einfach an die Geschäftsschicht. Der Kunde eines Kontos ([getClientByUserId]) wird stets aus der Datenbank abgerufen, nicht aus dem Cache: Es kommt auf die aktuellsten Daten an (ein Patient, der sein Konto gerade geändert oder gelöscht hat);
  • Zeilen 130–133 und folgende: die Aktualisierungen. Jede Schreiboperation für einen Arzt oder Kunden leert die betroffene Liste ([Cache::forget]): Die nächste Anfrage, die sie braucht, liest sie erneut aus der Datenbank. [tap(value, function)] ruft die Funktion auf und gibt dann den Wert zurück: hier den neu angelegten Arzt, nachdem der Cache geleert wurde. Genau darin liegt der Sinn eines einzigen Einstiegspunkts: Die Regel „Eine Schreiboperation aktualisiert den Cache“ ist nur hier definiert. 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 artisan cache:clear] würde ihn leeren.

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

<?php
// app/Web/Message.php: eine zu übersetzende Meldung: ihr Schlüssel und ihre Parameter.
// Die Views zeigen sie mit {{ __($message->key, $message->params) }} an.

namespace App\Web;

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

Eine zu übersetzende Meldung: ein Schlüssel mit seinen Parametern. Fehler der Geschäftsschicht ([BusinessException]) und solche der Controller werden zu [Message], die die Views in die Sprache der Seite übersetzen.

<?php
// =========================================================================
// app/Web/Flash.php: die "Flash"-Meldungen: eine Meldung, die EINMAL auf der
// NÄCHSTEN Seite angezeigt wird (siehe Beispiel 20). Sie ist die natürliche Ergänzung des
// Musters "Post / Redirect / Get", das alle Formulare der Anwendung verwenden: Ein
// erfolgreicher POST baut keine Seite auf, sondern leitet (302) auf eine GET-Seite weiter; die
// Meldung muss die Weiterleitung hingegen überleben.
//
// Laravel legt sie in der SESSION ab, hier in einem VERSCHLÜSSELTEN Cookie (Treiber [cookie],
// siehe .env): Der Server behält zwischen zwei Anfragen nichts.
//
// Eine Meldung enthält keinen Text, sondern einen Übersetzungsschlüssel und seine Parameter:
// Sie wird erst bei der Anzeige in der Sprache der Seite übersetzt (siehe
// resources/views/fragments). Zwei Listen: die Erfolgsmeldungen (oben auf der
// Seite angezeigt) und die Fehler (unten auf der Seite angezeigt).
// =========================================================================

namespace App\Web;

class Flash
{
    public static function success(string $key, array $params = []): void
    {
        self::add('flash_success', $key, $params);
    }

    public static function error(string $key, array $params = []): void
    {
        self::add('flash_errors', $key, $params);
    }

    // session()->flash(key, value): ein Wert, der nur während der NÄCHSTEN Anfrage
    // lesbar ist; wir ergänzen ihn, falls die aktuelle Anfrage bereits einen abgelegt hat
    private static function add(string $list, string $key, array $params): void
    {
        $messages = session($list, []);
        $messages[] = new Message($key, $params);
        session()->flash($list, $messages);
    }
}

Flash-Meldungen (Beispiel 20): Eine Meldung, die eine Action in der Session ablegt, wird von der nächsten Seite angezeigt und anschließend verworfen. Das ergänzt das Post/Redirect/Get-Muster, dem alle Formulare der Anwendung folgen. Zwei Listen, die in der Session unter den Schlüsseln [flash_success] und [flash_errors] abgelegt werden: Erfolgsmeldungen erscheinen oben auf der Seite, Fehlermeldungen unten.

  • Zeilen 34–39: Eine Action kann mehrere Meldungen ablegen: Wir hängen sie an die Liste an, die die aktuelle Anfrage bereits abgelegt hat ([session($list, [])] liest sie, standardmäßig mit einer leeren Liste), und speichern sie dann erneut. [session()->flash(key, value)] speichert einen Wert, der nur bis zum Ende der nächsten Anfrage erhalten bleibt (Beispiel 20).

[Message]-Objekte werden unverändert in der Session abgelegt: [Laravel] serialisiert die Sessiondaten (Beispiel 20) und rekonstruiert sie bei der nächsten Anfrage. Beim [cookie]-Treiber (Datei [.env]) werden sie in einem verschlüsselten Cookie übertragen.

11.13.3. app/Web/Utils.php

<?php
// =========================================================================
// app/Web/Utils.php: kleine Hilfsfunktionen der Web-Schicht:
//   - Datumsangaben: "yyyy-mm-dd", Tage "Wednesday 23 September 2026";
//   - Eingabe: Lesen einer positiven ganzen Zahl, eines vom Browser gesendeten Datums;
//   - Benutzer: der angemeldete Benutzer und sein Patient (Entität Client).
// STATISCHE Methoden: Sie werden ohne Erzeugen eines Objekts aufgerufen (Utils::iso($day)).
// =========================================================================

namespace App\Web;

use App\Auth\InvalidSession;
use App\Auth\ConnectedUser;
use App\Models\Client;
use Carbon\CarbonImmutable;
use Illuminate\Support\Facades\App;
use Illuminate\Support\Facades\Auth;

class Utils
{
    // ----------------------------------------------------------------- Datumsangaben

    // 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 wieder ausgelesene Datum genau so geschrieben wird wie der empfangene Text
    public static function validDate(?string $text): ?CarbonImmutable
    {
        if ($text === null || ! preg_match('/^\d{4}-\d{2}-\d{2}$/', $text)) {
            return null;
        }
        // "!Y-m-d": Das Ausrufezeichen setzt die Uhrzeit auf Mitternacht
        $date = CarbonImmutable::createFromFormat('!Y-m-d', $text);
        return $date !== null && $date->format('Y-m-d') === $text ? $date : null;
    }

    public static function iso(CarbonImmutable $day): string
    {
        return $day->format('Y-m-d');
    }

    // "mercredi 23 septembre 2026" / "Wednesday 23 September 2026", je nach Sprache
    // der Anfrage. isoFormat: dddd der Wochentag ausgeschrieben, D der
    // Tag, MMMM der Monat ausgeschrieben, YYYY das Jahr (siehe Beispiel 16)
    public static function formatDay(CarbonImmutable $day): string
    {
        return $day->locale(App::getLocale())->isoFormat('dddd D MMMM YYYY');
    }

    // ----------------------------------------------------------------- Eingabe

    // "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 Aktionen werden nur aufgerufen, wenn er existiert;
    // vorsichtshalber wird sein Fehlen wie eine abgelaufene Sitzung behandelt
    public static function user(): ConnectedUser
    {
        return Auth::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 entsprechenden Client über die Spalte clients.user.
    //
    // Gibt es keinen, wurde das Konto seit dem Login gelöscht,
    // während sein Token noch gültig ist: Wir behandeln das wie eine abgelaufene
    // Sitzung (siehe InvalidSession).
    // -----------------------------------------------------------------------
    public static function connectedPatient(ApplicationModel $application): Client
    {
        return $application->getClientByUserId(self::user()->userId)
            ?? throw new InvalidSession();
    }
}

Einige Hilfsfunktionen in Form von statischen Methoden.

  • Zeilen 26–34: 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 nachsichtig: Aus dem 30. Februar wird der 2. März. Wir lesen daher das resultierende Datum erneut ein und prüfen, ob es exakt so geschrieben wird wie der empfangene Text. Das [!] im Format setzt die Uhrzeit auf Mitternacht (ohne es wäre es die aktuelle Uhrzeit);
  • Zeilen 44–47: „samedi 26 septembre 2026“ oder „Saturday 26 September 2026“, je nach Sprache der Anfrage. [isoFormat] (Beispiel 16) verwendet die Formatcodes der [JavaScript] [Moment.js]-Bibliothek: [dddd], der ausgeschriebene Wochentag; [D], der Tag; [MMMM], der ausgeschriebene Monat; [YYYY], das Jahr. [locale(...)] liefert eine Kopie des Datums, die auf eine bestimmte Sprache eingestellt ist;
  • Zeilen 52–59: Ein Query-Parameter ist ein String, oder [null], oder sogar ein Array ([?doctorId[]=1], Beispiel 10). Akzeptiert werden nur Ziffern (bis zu neun: kein Überlauf), und die Zahl muss strikt positiv sein. [mixed]: ein beliebiger Typ;
  • Zeilen 65–68: der angemeldete Benutzer. [Auth::user()] liefert [null] für einen anonymen Besucher; geschützte Actions werden nur für einen authentifizierten Benutzer aufgerufen, aber das Fehlen eines Benutzers wird dennoch wie eine abgelaufene Session behandelt;
  • Zeilen 80–84: der Patient ([Client]) des angemeldeten Benutzers. Das Token enthält nur die Konto-ID; der Kunde wird über die Spalte [clients.user] identifiziert. Existiert er nicht, wurde das Konto seit der Anmeldung des Benutzers gelöscht: [InvalidSession].

11.14. Die Wörterbücher

Die Oberflächentexte entsprechen denen der anderen Versionen der Anwendung, die sie in verschachtelten JSON-Dateien abgelegt haben:

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

Die [Flask]-Version hat sie beim Start „abgeflacht“: [LOGIN.TITLE] verwies auf den Text in [Login]. [Laravel] liest flache JSON-Wörterbücher (Beispiel 22), in denen der Schlüssel der zu übersetzende Text oder ein Bezeichner ist: Wir haben die Wörterbücher ein für alle Mal abgeflacht und die Parameter [{name}] der anderen Versionen durch die Notation von [Laravel] ersetzt, nämlich [:name]:

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

Die Dateien [lang/fr.json] und [lang/en.json] enthalten jeweils 153 Texte; sie werden hier nicht abgedruckt. Ein Schlüssel wird durch [__('APP.LOGOUT')] dargestellt und ein parametrisierter Text durch [__('DOCTORS.ADDED', ['name' => ..., 'login' => ...])]. [Laravel] sucht zunächst den vollständigen Schlüssel im JSON-Wörterbuch der Sprache; findet es ihn nicht, sucht es ihn in den [PHP]-Dateien im Ordner [lang/en] (Beispiel 09); schlägt auch das fehl, zeigt es den Schlüssel selbst an, was sofort auf eine Lücke hinweist. Ein Texteintrag wurde hinzugefügt: [ERRORS.PAGE_EXPIRED], die Meldung der Seite 419, die in den anderen Versionen nicht vorhanden ist.

11.15. Formulare

Die „Personen“-Formulare werden durch Form Requests ([FormRequest], Beispiel 19) validiert: Klassen, die die Validierungsregeln für eine Anfrage beschreiben. Rufen wir das Prinzip in Erinnerung: Eine Action, die einen [FormRequest] als Parameter erhält, wird nur aufgerufen, wenn die Eingabe gültig ist; andernfalls leitet [Laravel] den Browser zusammen mit Fehlermeldungen ([$errors] in der View) und den erneut anzuzeigenden Eingaben ([old('field')]) zur Formularseite zurück, Passwörter ausgenommen.

11.15.1. app/Http/Requests/PersonFieldsRequest.php

<?php
// =========================================================================
// app/Http/Requests/PersonFieldsRequest.php: die Felder der "Personen"-
// Formulare und ihre Validierungsregeln (siehe Beispiel 19). Drei Formulare
// teilen sich dieselben Identitätsfelder (Anrede, Vorname, Nachname):
//
//   PersonFieldsRequest            Anrede, Vorname, Nachname
//    ├─ PersonRequest              + OPTIONALER Login / OPTIONALES Passwort, Version
//    │                               (der ADMIN fügt einen Arzt / Client hinzu oder ändert ihn)
//    ├─ RegistrationRequest        + ERFORDERLICHER Login / ERFORDERLICHES Passwort / Bestätigung
//    │                               (ein Patient erstellt sein Konto)
//    └─ MyAccountRequest           + Login, optionales neues Passwort, ERFORDERLICHES
//                                    AKTUELLES Passwort, Version
//                                    (ein Patient ändert sein Konto)
//
// Eine ABSTRAKTE Klasse: Sie wird nie allein verwendet; ihre Kindklassen ergänzen
// ihre Regeln (array_merge) und ihre Meldungen.
//
// Erinnerung (Beispiel 19): Eine Aktion, die einen FormRequest als Parameter erhält, wird
// nur aufgerufen, wenn die Eingabe gültig ist; andernfalls schickt Laravel den Browser
// zur Formularseite zurück (Weiterleitung), mit den Fehlermeldungen ($errors in der
// View) und der erneut anzuzeigenden Eingabe (old('field')) - NIEMALS den Passwörtern.
// Die Meldungen sind die Texte der Wörterbücher lang/*.json: __('ERRORS...').
// =========================================================================

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Support\Str;
use Illuminate\Validation\Rule;

abstract class PersonFieldsRequest extends FormRequest
{
    public const TITLES = ['Mr', 'Mme', 'Melle'];

    // Login: 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;

    // vor der Validierung: Ein Login ist immer in Kleinbuchstaben. Überflüssige
    // Leerzeichen hat die Middleware TrimStrings von Laravel bereits aus allen Feldern entfernt
    // - außer aus den Passwörtern (password,
    // password_confirmation, current_password), zu denen sie gehören dürfen; ein
    // leeres Feld ist zu null geworden (Middleware ConvertEmptyStringsToNull)
    protected function prepareForValidation(): void
    {
        if (is_string($this->input('login'))) {
            $this->merge(['login' => Str::lower($this->input('login'))]);
        }
    }

    // bail: Die Validierung eines Feldes endet bei der ersten verletzten Regel -
    // eine einzige Meldung pro Feld. Maximale Längen = die der SQL-Spalten
    public function rules(): array
    {
        return [
            'title' => ['bail', 'required', Rule::in(self::TITLES)],
            'first_name' => ['bail', 'required', 'string', 'max:20'],
            'last_name' => ['bail', 'required', 'string', 'max:20'],
        ];
    }

    // field.rule -> message
    public function messages(): array
    {
        return [
            'title' => __('ERRORS.INVALID_TITLE'),
            'first_name.required' => __('ERRORS.FIRSTNAME_REQUIRED'),
            'first_name' => __('ERRORS.FIRSTNAME_TOO_LONG'),
            'last_name.required' => __('ERRORS.LASTNAME_REQUIRED'),
            'last_name' => __('ERRORS.LASTNAME_TOO_LONG'),
            'login.required' => __('ERRORS.LOGIN_REQUIRED'),
            'login' => __('ERRORS.INVALID_LOGIN'),
            'password.required' => __('ERRORS.PASSWORD_REQUIRED'),
            'password.min' => __('ERRORS.PASSWORD_TOO_SHORT', ['min' => self::PASSWORD_MIN]),
            'password' => __('ERRORS.PASSWORD_TOO_LONG'),
            'password_confirmation.required' => __('ERRORS.CONFIRMATION_REQUIRED'),
            'password_confirmation' => __('ERRORS.PASSWORDS_DIFFER'),
            'current_password' => __('ERRORS.CURRENT_PASSWORD_REQUIRED'),
            'version' => __('ERRORS.INVALID_FORM'),
        ];
    }

    // die Version (optimistische Sperre), falls das Formular eine hat
    public function version(): ?int
    {
        return $this->filled('version') ? (int) $this->input('version') : null;
    }
}

Drei Formulare teilen sich dieselben Identitätsfelder (Anrede, Vorname, Nachname): das Administratorformular (für einen Arzt oder einen Kunden), das Formular zur Erstellung eines Patientenkontos und „Mein Konto verwalten“. Ihre gemeinsame Elternklasse ist abstrakt; jede ihrer Kindklassen erweitert ihre Regeln.

  • Zeilen 34–40: die Eingaberegeln in Form von Konstanten, die auch von den Views gelesen werden (die Liste der Anreden);
  • Zeilen 47–52: [prepareForValidation] wird vor der Validierung aufgerufen: Dort können die Eingaben umgewandelt werden. Ein Login steht immer in Kleinbuchstaben: [merge] ersetzt den Feldwert in der Anfrage. Die übrigen Aufbereitungen erledigen bereits zwei globale Middleware-Komponenten von [Laravel] (siehe das Kapitel zum Lebenszyklus): [TrimStrings] entfernt führende und nachgestellte Leerzeichen aus allen Werten, außer denen der Felder [password], [password_confirmation] und [current_password] (Leerzeichen können Teil eines Passworts sein); [ConvertEmptyStringsToNull] ersetzt einen leeren String durch [null]. Deshalb tragen die Passwortfelder der Anwendung diese Namen, die der Konvention von [Laravel] entsprechen;
  • Zeilen 56–63: die Regeln für die drei Felder. [bail] beendet die Validierung eines Felds, sobald die erste Regel verletzt ist: nur eine Meldung pro Feld. [Rule::in(...)]: Der Wert muss einer der Werte in der Liste sein. [max:20]: maximal 20 Zeichen; die Länge der Spalte ist in SQL festgelegt;
  • Zeilen 66–84: Fehlermeldungen, die den Wörterbüchern entnommen werden. Der Schlüssel ['first_name.required'] verweist auf die Meldung zur Regel [required] im Feld [first_name]; der Schlüssel ['first_name'] allein verweist auf die Meldung für alle anderen Regeln dieses Felds. Die Meldung zu einer Regel wird zuerst unter dem Schlüssel [field.rule] gesucht, dann unter dem Schlüssel [rule] (die Meldung zu dieser Regel für alle Felder) und schließlich unter dem Schlüssel [field]. Die Regeln der Kindklassen (Login, Passwörter) haben hier ihre Meldungen: Eine ungenutzte Meldung verursacht keine Probleme. Die Methode [messages] wird während der Validierung in der Sprache der Anfrage aufgerufen;
  • Zeilen 87–90: die Version (das versteckte Feld für das optimistische Sperren) als Ganzzahl oder [null] , wenn das Feld leer oder nicht vorhanden ist. [filled]: Das Feld ist vorhanden und nicht leer.

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

<?php
// app/Http/Requests/PersonRequest.php: das Formular eines Arztes oder eines Clients
// (ADMIN): Login und Passwort OPTIONAL (siehe app/Business/PersonData.php).

namespace App\Http\Requests;

use App\Business\PersonData;

class PersonRequest extends PersonFieldsRequest
{
    // nullable: Ein leeres Feld (null) wird akzeptiert, ohne die übrigen Regeln zu prüfen
    public function rules(): array
    {
        return array_merge(parent::rules(), [
            'login' => ['bail', 'nullable', 'string', 'regex:'.self::LOGIN_FORMAT],
            // höchstens 72 Zeichen: Darüber hinaus ignoriert bcrypt den Rest
            'password' => ['bail', 'nullable', 'string', 'max:72'],
            // verstecktes Feld des Änderungsformulars (optimistische Sperre)
            'version' => ['nullable', 'integer'],
        ]);
    }

    // die validierte Eingabe -> die von der Geschäftsschicht erwarteten Daten
    public function personData(): PersonData
    {
        return new PersonData($this->input('title'), $this->input('last_name'), $this->input('first_name'),
            $this->input('login'), $this->input('password'), $this->version());
    }
}

Das Administratorformular. [array_merge] fügt den Regeln der Elternklasse drei Regeln hinzu: Benutzername und Passwort sind optional ([nullable]: Der Wert [null] wird akzeptiert, und die übrigen Regeln werden dann nicht geprüft); [regex:...] validiert das Format des Benutzernamens; [max:72] begrenzt die Länge eines Passworts: [bcrypt] berücksichtigt nur die ersten 72 Bytes (Beispiel 25). Die Methode [personData] (Zeilen 24–28) wandelt die validierten Eingaben für die Geschäftsschicht in [PersonData] um: Die Geschäftsschicht kennt keine HTTP-Anfragen.

<?php
// app/Http/Requests/RegistrationRequest.php: "Create a client account": Login, Passwort
// und Bestätigung ERFORDERLICH.

namespace App\Http\Requests;

use App\Business\PersonData;

class RegistrationRequest extends PersonFieldsRequest
{
    public function rules(): array
    {
        return array_merge(parent::rules(), [
            'login' => ['bail', 'required', 'string', 'regex:'.self::LOGIN_FORMAT],
            'password' => ['bail', 'required', 'string', 'min:'.self::PASSWORD_MIN, 'max:72'],
            // same:password: Die Bestätigung muss mit dem Passwort identisch sein
            'password_confirmation' => ['bail', 'required', 'same:password'],
        ]);
    }

    public function personData(): PersonData
    {
        return new PersonData($this->input('title'), $this->input('last_name'), $this->input('first_name'),
            $this->input('login'), $this->input('password'));
    }
}

Erstellung eines Patientenkontos: Login und Passwort sind erforderlich, und das Passwort muss bestätigt werden. Die Regel [same:password] verlangt, dass das Feld [password_confirmation] denselben Wert wie das Feld [password] hat; ihre Meldung („Die Bestätigung stimmt nicht mit dem Passwort überein.“) erscheint unter dem Bestätigungsfeld. [Laravel] kennt außerdem eine Regel [confirmed], die dasselbe prüft, jedoch ausgehend vom Feld [password]; ihre Meldung würde unter dem Passwortfeld erscheinen.

<?php
// app/Http/Requests/MyAccountRequest.php: "Manage my account" (ein Patient): Login
// erforderlich, neues Passwort optional, AKTUELLES Passwort erforderlich.

namespace App\Http\Requests;

use App\Business\PersonData;

class MyAccountRequest extends PersonFieldsRequest
{
    public function rules(): array
    {
        return array_merge(parent::rules(), [
            'login' => ['bail', 'required', 'string', 'regex:'.self::LOGIN_FORMAT],
            // optional: leer = Passwort unverändert
            'password' => ['bail', 'nullable', 'string', 'min:'.self::PASSWORD_MIN, 'max:72'],
            'password_confirmation' => ['same:password'],
            // das AKTUELLE Passwort, erforderlich für jede Änderung des Kontos
            'current_password' => ['required'],
            'version' => ['nullable', 'integer'],
        ]);
    }

    public function personData(): PersonData
    {
        return new PersonData($this->input('title'), $this->input('last_name'), $this->input('first_name'),
            $this->input('login'), $this->input('password'), $this->version());
    }
}

„Mein Konto verwalten“: Das neue Passwort ist optional (leer lassen, um das aktuelle Passwort zu behalten), und das aktuelle Passwort ist erforderlich. Die Regel [same:password] gilt auch für ein leeres Bestätigungsfeld: Wird ein neues Passwort eingegeben, muss auch die Bestätigung eingegeben werden. Das aktuelle Passwort wird hier nicht geprüft, sondern von der Action: Ein falsches Passwort muss vom Versuchslimiter als fehlgeschlagener Login gezählt werden. [Laravel] kennt eine Regel [current_password], die das eingegebene Passwort mit dem des angemeldeten Benutzers vergleicht; diese Regel ist hier nicht geeignet: Unser angemeldeter Benutzer ([ConnectedUser]) enthält nicht den Hash seines Passworts.

11.16. View-Templates

Der Ordner [app/Views] enthält die View-Templates: von einer Action erzeugte Objekte, die die View lediglich liest. Die Regel, der alle Seiten folgen, lautet: keine Logik in den Views. Die Actions bereiten bereits formatierte Daten („Frau Marie PELISSIER“, „8:00 – 8:20“) auf, die zudem schon nach der Rolle des Benutzers gefiltert sind; die Views setzen sie ins HTML ein. Alle diese Klassen sind [readonly] und haben nur Eigenschaften, die über ihren Konstruktor gesetzt werden (Constructor Promotion).

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

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, die Beschriftung und die Angabe, ob die Option ausgewählt ist.

<?php
// app/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,       // den Button "Book" anzeigen?
        public string $bookUrl,
        // nur gesetzt, wenn der Button "Cancel" angezeigt wird
        public ?int $appointmentId,
    ) {
    }
}

Ein Eintrag im Terminkalender: ein Zeitfenster und das, was der angemeldete Benutzer dazu einsehen und tun darf. [patient] wird nur gesetzt, wenn der Benutzer den Namen des Patienten einsehen darf; [bookable] gibt an, ob die Schaltfläche „Buchen“ angezeigt wird; [appointmentId] gibt an, ob die Schaltfläche „Absagen“ angezeigt wird.

<?php
// app/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
// app/Views/BookingView.php: das Buchungsfenster 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 Terminkalender und das Buchungsfenster: für den Administrator und die Ärzte die Liste der auswählbaren Patienten, für einen Patienten sein eigener Name.

<?php
// app/Views/PersonKeys.php: die für jeden Personentyp (Ä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");
    }
}

Die Übersetzungsschlüssel, die für Ärzte oder Kunden spezifisch sind, 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')] liefert [DOCTORS.TITLE], [DOCTORS.ADD] ... [new self(...)] erzeugt ein Objekt der Klasse selbst.

<?php
// app/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 anstehender Termin im Patientenbereich.

11.17. Die Web-Schicht: Routen und Controller

11.17.1. routes/web.php

<?php
// =========================================================================
// routes/web.php: alle URLs der Anwendung.
//
// Erinnerung (siehe bootstrap/app.php): Alle diese Routen erfordern einen authentifizierten
// Benutzer, AUSSER denen der ersten Gruppe, die die Authentifizierungs-Middleware
// entfernen (withoutMiddleware). Die Middleware [role:...] verlangt zudem
// eine der aufgeführten Rollen; sie gilt für eine Route oder für alle Routen einer
// Gruppe.
//
// ->name(...): der NAME der Route, mit dem der Code seine URLs aufbaut
// (route('schedule', [...]), redirect()->route('login') ...): Eine URL zu ändern
// erfordert dann nur noch, diese Datei anzupassen
// =========================================================================

use App\Http\Controllers\ScheduleController;
use App\Http\Controllers\AuthController;
use App\Http\Controllers\ClientsController;
use App\Http\Controllers\PatientAreaController;
use App\Http\Controllers\RegistrationController;
use App\Http\Controllers\LanguageController;
use App\Http\Controllers\DoctorsController;
use App\Http\Middleware\SetLanguage;
use Illuminate\Auth\Middleware\Authenticate;
use Illuminate\Support\Facades\Route;

// ---------------------------------------------------------------- die ÖFFENTLICHEN Routen
Route::withoutMiddleware(Authenticate::class)->group(function () {
    // der Login (siehe AuthController)
    Route::controller(AuthController::class)->group(function () {
        Route::get('/', 'home')->name('home');
        Route::get('login', 'showLogin')->name('login');
        Route::post('login', 'logIn');
        Route::post('logout', 'logOut')->name('logout');
    });

    // die Sprachauswahl: /language/fr, /language/en; jeder andere Wert: 404
    Route::get('language/{code}', [LanguageController::class, 'change'])
        ->whereIn('code', SetLanguage::LANGUAGES)->name('language');

    // das Anlegen eines Client-Kontos (siehe RegistrationController); das Formular
    // erfordert einen Pass (Middleware registration.pass)
    Route::controller(RegistrationController::class)->prefix('register')->group(function () {
        Route::post('access', 'access')->name('registration.access');
        Route::middleware('registration.pass')->group(function () {
            Route::get('', 'form')->name('registration');
            Route::post('', 'create');
        });
    });

    // keine andere Route passt zur angeforderten URL: 404-Seite. Eine "Fallback"-
    // Route statt des automatischen 404 von Laravel: Die Anfrage durchläuft so
    // die Middlewares der Gruppe [web] (Session, Benutzer ...), und die
    // Fehlerseite hat ihre vollständige Navigationsleiste
    Route::fallback(fn () => abort(404));
});

// ---------------------------------------------------------------- der Terminkalender (alle Rollen)
Route::controller(ScheduleController::class)->prefix('schedule')->group(function () {
    Route::get('', 'show')->name('schedule');
    Route::post('book', 'book')->middleware('role:ADMIN,DOCTOR,USER')->name('schedule.book');
    // ein Patient storniert SEINEN Termin über "My area", nicht von hier aus
    Route::post('cancel', 'cancel')->middleware('role:ADMIN,DOCTOR')->name('schedule.cancel');
});

// ---------------------------------------------------------------- Ärzte und Clients (ADMIN)
// Die beiden Abschnitte haben DIESELBEN Routen (siehe PersonsController): Eine Schleife
// deklariert sie für jeden. Die Routennamen haben den Abschnitt als Präfix:
// doctors.list, clients.list ...
foreach (['doctors' => DoctorsController::class, 'clients' => ClientsController::class] as $section => $controller) {
    Route::controller($controller)->prefix($section)->name("$section.")->middleware('role:ADMIN')
        ->group(function () {
            Route::get('', 'list')->name('list');
            Route::get('add', 'addForm')->name('addForm');
            Route::post('add', 'add')->name('add');
            // whereNumber: {id} muss aus Ziffern bestehen
            Route::get('{id}/edit', 'editForm')->whereNumber('id')->name('editForm');
            Route::post('{id}/edit', 'edit')->whereNumber('id')->name('edit');
            Route::post('{id}/delete', 'delete')->whereNumber('id')->name('delete');
        });
}

// ---------------------------------------------------------------- der Bereich des Patienten (USER)
Route::controller(PatientAreaController::class)->middleware('role:USER')->group(function () {
    Route::get('my-area', 'patientArea')->name('area');
    Route::post('my-area/cancel', 'cancelAppointment')->name('area.cancel');
    Route::get('my-account', 'accountForm')->name('account');
    Route::post('my-account', 'editAccount')->name('account.edit');
    Route::post('my-account/delete', 'deleteAccount')->name('account.delete');
});

Alle URL-Routen der Anwendung. Beachten Sie, dass alle diese Routen einen authentifizierten Benutzer voraussetzen (die Middleware [Authenticate], die [web] durch [bootstrap/app.php] hinzugefügt wird), außer denen, die diese Anforderung aufheben.

  • Zeilen 28–56: die öffentlichen Routen. [withoutMiddleware] entfernt eine Middleware-Komponente von den Routen der Gruppe: hier die Authentifizierung. Dazu gehören der Login ([AuthController]), die Sprachauswahl und die Erstellung von Patientenkonten;
  • Zeilen 30–35: [Route::controller] (Beispiel 02) legt den Controller für die Routen der Gruppe fest: Jede Route nennt nun nur noch ihre Methode. [->name('login')] weist der Route einen Namen zu (Beispiel 04): Der Code erzeugt ihre URLs über diesen Namen ([route('login')], [redirect()->route('login')]), und die Änderung einer URL erfordert nur die Anpassung an dieser einen Stelle. Der Name [login] hat auch für [Laravel] eine Bedeutung: Er bezeichnet die Seite, zu der die Middleware [Authenticate] einen anonymen Besucher weiterleitet, wenn keine andere Seite angegeben ist;
  • Zeilen 38–39: [whereIn('code', [...])] akzeptiert für den Parameter [{code}] nur die Werte aus der Liste: [/language/de] entspricht keiner Route (404-Seite);
  • Zeilen 43–49: Kontoerstellung. [prefix('register')] stellt den URL-Einträgen der Gruppe [/register] voran: [Route::get('', ...)] ist die Route [/register] selbst. Das Formular (GET und POST) erfordert außerdem einen Pass: die Alias-Middleware [registration.pass];
  • Zeile 55: die Fallback-Route, die ausgewählt wird, wenn keine andere Route zu einer GET-Anfrage passt. Ohne sie erzeugt [Laravel] selbst einen 404-Fehler, bevor die Middleware der Gruppe [web] ausgeführt wird: keine Session, keine entschlüsselten Cookies ... Die Fehlerseite hätte weder den Namen des Benutzers in ihrer Navigationsleiste noch ein Anti-CSRF-Token für die Abmelde-Schaltfläche. Mit der Fallback-Route durchläuft die Anfrage die Gruppe [web], und anschließend löst die Action einen 404-Fehler aus. Die Route ist öffentlich: Eine unbekannte Adresse liefert eine 404-Seite, auch für einen anonymen Besucher. Nebeneffekt: Eine GET-Anfrage an eine URL, die nur als POST existiert ([/logout]), liefert ebenfalls eine 404-Seite, nicht 405;
  • Zeilen 59–64: der Terminkalender. Seine Seite ist für alle authentifizierten Benutzer zugänglich; die Buchung steht den drei Rollen offen (das heißt jedem authentifizierten Benutzer; die Liste der Rollen dokumentiert diese Regel); die Absage steht dem Administrator und den Ärzten offen: [->middleware('role:ADMIN,DOCTOR')];
  • Zeilen 70–81: Die Routen für Ärzte und Kunden sind dieselben: Eine Schleife deklariert sie für jeden der beiden Abschnitte. Die Routendatei ist eine gewöhnliche [PHP]-Datei: Sie können darin Schleifen, Bedingungen und Funktionen schreiben. Für jeden Abschnitt gibt es eine Gruppe: den Controller, das URL-Präfix ([/doctors]), das Namenspräfix ([->name("$section.")]: Die Route mit dem Namen [list] heißt [doctors.list]) und die Middleware [role:ADMIN], die alle Routen der Gruppe schützt – auch später hinzugefügte. [whereNumber('id')] akzeptiert für den Parameter [{id}] nur Zahlen (z. B. 02);
  • Zeilen 84–90: der Patientenbereich, der der Rolle USER vorbehalten ist.

Die URL-Codes entsprechen anderen Versionen der Anwendung: Das Ändern und Löschen eines Arztes sind POST-Anfragen ([/doctors/{id}/edit], [/doctors/{id}/delete]), nicht PUT und DELETE wie in Beispiel 28. Der Befehl [php artisan route:list] zeigt die Liste der Routen samt ihren Namen und Actions an.

11.17.2. app/Http/Controllers/LanguageController.php

<?php
// =========================================================================
// app/Http/Controllers/LanguageController.php: GET /language/fr, GET /language/en: die
// beiden Buttons FR / EN der Navigationsleiste. Öffentliche Route: Man muss die Sprache
// vor dem Login ändern können.
//
// Die Wahl wird in einem Cookie gespeichert: Bei jeder folgenden Anfrage liest die Middleware
// SetLanguage es wieder aus und setzt die Sprache der Anfrage. Dann gehen wir zur
// Seite zurück, von der wir kamen (siehe Beispiel 22).
// =========================================================================

namespace App\Http\Controllers;

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

class LanguageController
{
    // {code} wird von der Route (whereIn) auf die unterstützten Sprachen beschränkt: /language/de ergibt eine 404-Seite
    public function change(Request $request, string $code): RedirectResponse
    {
        // ein Jahr: 60 * 24 * 365 Minuten
        return redirect($this->originPage($request))->withCookie(cookie(
            SetLanguage::COOKIE, $code, 60 * 24 * 365, '/', null,
            config('rdvmedecins.cookie_secure'), true, false, 'lax'));
    }

    // -----------------------------------------------------------------------
    // die vorherige Seite, gemäß dem HTTP-Header "Referer", den der Browser sendet.
    // Wir behalten nur ihren Pfad (/schedule?...): Eine Weiterleitung auf eine vollständige
    // Adresse aus der Anfrage würde es erlauben, den Benutzer auf
    // eine andere Site 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 Site 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), danach kehrt der Browser zu der Seite zurück, von der er kam. Das Cookie ist nicht verschlüsselt (siehe [bootstrap/app.php]); es ist [httpOnly]: Das [JavaScript] der Seite muss es nicht lesen.

  • Zeilen 35–47: Die vorherige Seite wird durch den HTTP-Header [Referer] angegeben, den der Browser mit der Anfrage sendet. Das sind vom Client gelieferte Daten und daher verdächtig: Eine Weiterleitung auf eine vollständige URL aus der Anfrage würde es einem Angreifer erlauben, den Benutzer über einen Link auf [/language/fr] mit einem gefälschten [Referer] auf seine eigene Website zu schicken (die sogenannte *Open-Redirect*-Schwachstelle). Daher behalten wir nur den Pfad und die Parameter ([/schedule?doctorId=1&...]), die die Funktion [parse_url] aus [PHP]extrahiert, welche 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: Das ergäbe eine Schleife.

11.17.3. app/Http/Controllers/ScheduleController.php

<?php
// =========================================================================
// app/Http/Controllers/ScheduleController.php: die Seite des Terminkalenders: Auswahl 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 dem
//                                                          Buchungsfenster
//                                                          von Zeitfenster 7 geöffnet
//   POST /schedule/book                                    legt einen Termin an
//   POST /schedule/cancel                                  storniert einen Termin
//
// Die ganze Seite wird durch ihre URL beschrieben: Sie kann neu geladen und mit einem Lesezeichen versehen werden,
// die Schaltfläche "Back" des Browsers ist nutzbar - ohne eine einzige Zeile
// JavaScript.
//
// Was jeder sieht und tun kann:
//
//   | role          | taken slot displayed              | Book               | Cancel  |
//   |---------------|-----------------------------------|--------------------|---------|
//   | ADMIN, DOCTOR | name of the patient               | for a patient      | yes     |
//   |               |                                   | chosen in a list   |         |
//   | USER (patient)| "Booked", or THEIR name if it is  | for themselves, if | no (*)  |
//   |               | their own appointment             | they have no       |         |
//   |               |                                   | upcoming appt.     |         |
//
//   (*) der Patient storniert seinen Termin über seine Seite "My area".
//
// VERTRAULICHKEIT: Für einen Patienten wird der Name der ANDEREN Patienten nicht
// einfach von der View verborgen - er wird der View nie übergeben. Das an den
// Browser gesendete HTML enthält ihn daher nicht, nicht einmal versteckt (ein einfaches "Seitenquelltext
// anzeigen" würde ihn sonst verraten).
//
// Keine Buchung in der Vergangenheit: Der Button "Book" erscheint nur für
// heute und die folgenden Tage (und die Geschäftsschicht würde sie
// ohnehin ablehnen).
//
// Sicherheit: Alle /schedule-URLs erfordern einen authentifizierten Benutzer (allgemeine
// Regel, siehe bootstrap/app.php); die Middleware [role] der POST-Routen verlangt zudem
// eine der aufgeführten Rollen (siehe routes/web.php).
// =========================================================================

namespace App\Http\Controllers;

use App\Domain\DoctorDaySchedule;
use App\Business\Dates;
use App\Business\BusinessException;
use App\Models\Client;
use App\Models\Person;
use App\Models\Role;
use App\Views\ScheduleView;
use App\Views\ScheduleRow;
use App\Views\OptionView;
use App\Views\BookingView;
use App\Web\ApplicationModel;
use App\Web\Flash;
use App\Web\Message;
use App\Web\Utils;
use Carbon\CarbonImmutable;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\View\View;

class ScheduleController
{
    public function __construct(private ApplicationModel $application)
    {
    }

    // -----------------------------------------------------------------------
    // GET /schedule
    // Die URL-Parameter werden roh gelesen ($request->query), um einen
    // FEHLENDEN Parameter (null) von einem LEEREN Parameter (?doctorId=) zu unterscheiden.
    // -----------------------------------------------------------------------
    public function show(Request $request): View
    {
        $error = null;
        $user = Utils::user();
        $rights = $this->rights();

        // der Tag: der aus der URL, wenn er gültig ist, sonst heute
        $day = Dates::today();
        $rawDay = $request->query('day');
        if ($rawDay !== null) {
            $requestedDay = Utils::validDate(is_string($rawDay) ? $rawDay : null);
            if ($requestedDay !== null) {
                $day = $requestedDay;
            } else {
                $error = 'ERRORS.INVALID_DATE';
            }
        }
        $dayBookable = $day->gte(Dates::today());

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

        // die Dropdown-Liste der Ärzte
        $doctors = $this->application->getAllDoctors()
            ->map(fn (Person $m) => self::option($m, $m->id === $doctorId))->all();

        // der Terminkalender, falls 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, $dayBookable);
            }
        }

        // das Buchungsfenster: nur wenn das angeforderte Zeitfenster von diesem Benutzer
        // buchbar ist. array_find: das erste Element, das die
        // Bedingung erfüllt (null, wenn es keines gibt)
        $booking = null;
        $slotId = Utils::positiveInteger($request->query('book'));
        if ($schedule !== null && $slotId !== null) {
            $row = array_find($schedule->rows,
                fn (ScheduleRow $r) => $r->slotId === $slotId && $r->bookable);
            if ($row !== null) {
                $booking = new BookingView(
                    $row->slotId,
                    $row->time,
                    $rights['manager']
                        ? $this->application->getAllClients()->map(fn (Client $c) => self::option($c, false))->all()
                        : [],
                    $rights['patient']?->label());
            }
        }

        return view('schedule', [
            'pageTitle' => 'SCHEDULE.PAGE_TITLE',
            'error' => $error ? new Message($error) : null,
            'doctors' => $doctors,
            'doctorId' => $doctorId,
            'day' => Utils::iso($day),
            'schedule' => $schedule,
            'booking' => $booking,
            // der angezeigte Terminkalender, ohne Buchungsfenster
            'backUrl' => $doctorId !== null ? self::scheduleUrl($doctorId, $day) : route('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 einem gerissenen Patienten erlauben, im Namen eines anderen zu buchen.
    //
    // Muster "Post / Redirect / Get": Was auch immer das Ergebnis ist, hier wird keine Seite
    // aufgebaut - wir setzen eine Flash-Meldung und leiten zum Terminkalender weiter
    // (siehe Beispiel 20).
    // -----------------------------------------------------------------------
    public function book(Request $request): RedirectResponse
    {
        [$doctorId, $day] = $this->readScheduleRequest($request);
        $slotId = Utils::positiveInteger($request->input('slotId'));
        if ($doctorId === null || $slotId === null) {
            abort(400);    // -> Seite "bad request" (siehe bootstrap/app.php)
        }
        $user = Utils::user();

        if ($user->isPatient()) {
            $client = Utils::connectedPatient($this->application);
        } else {
            $clientId = Utils::positiveInteger($request->input('clientId'));
            if ($clientId === null) {
                // kein Patient gewählt: wir öffnen das Buchungsfenster erneut
                Flash::error('ERRORS.CHOOSE_PATIENT');
                return redirect(self::scheduleUrl($doctorId, $day, $slotId));
            }
            $client = $this->application->getClientById($clientId);
        }

        $slot = $this->application->getSlotById($slotId);
        if ($client === null) {
            Flash::error('ERRORS.PATIENT_NOT_FOUND');
        } elseif ($slot === null || $slot->doctor_id !== $doctorId) {
            Flash::error('ERRORS.SLOT_NOT_FOUND');
        } else {
            try {
                // die Regeln (nicht in der Vergangenheit, nur ein bevorstehender Termin pro
                // Patient, freies Zeitfenster) prüft die Geschäftsschicht
                $this->application->addAppointment($day, $slot, $client);
                Flash::success('SCHEDULE.BOOKED');
            } catch (BusinessException $e) {
                // dieselbe Regel, aber eine Meldung in der 2. Person, wenn der
                // Patient selbst bucht ("You already have ..." statt
                // "This patient ..."). Die übrigen Ausnahmen (echte Anomalien) werden
                // nicht abgefangen: 500-Seite.
                if ($e->key === 'ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT' && $user->isPatient()) {
                    Flash::error('SCHEDULE.ALREADY_BOOKED_INFO');
                } else {
                    Flash::error($e->key, $e->params);
                }
            }
        }
        return redirect(self::scheduleUrl($doctorId, $day));
    }

    // -----------------------------------------------------------------------
    // POST /schedule/cancel   Felder: appointmentId, doctorId, day
    // (ein Patient storniert SEINEN Termin über "My area", nicht von hier aus)
    // -----------------------------------------------------------------------
    public function cancel(Request $request): RedirectResponse
    {
        [$doctorId, $day] = $this->readScheduleRequest($request);
        $appointmentId = Utils::positiveInteger($request->input('appointmentId'));
        if ($doctorId === null || $appointmentId === null) {
            abort(400);
        }
        $appointment = $this->application->getAppointmentById($appointmentId);
        if ($appointment === null) {
            // bereits storniert (von jemand anderem oder durch Doppelklick)
            Flash::error('ERRORS.APPOINTMENT_NOT_FOUND');
        } else {
            $this->application->deleteAppointment($appointment);
            Flash::success('SCHEDULE.CANCELLED');
        }
        return redirect(self::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 (! Utils::user()->isPatient()) {
            return ['manager' => true, 'patient' => null, 'patientCanBook' => false];
        }
        $patient = Utils::connectedPatient($this->application);
        $upcoming = $this->application->getClientUpcomingAppointments($patient->id);
        return ['manager' => false, 'patient' => $patient, 'patientCanBook' => $upcoming->isEmpty()];
    }

    // -----------------------------------------------------------------------
    // der Terminkalender des Arztes, für die View formatiert - und nach den Rechten gefiltert
    // -----------------------------------------------------------------------
    private function scheduleView(DoctorDaySchedule $doctorSchedule, array $rights, bool $dayBookable): ScheduleView
    {
        $doctorId = $doctorSchedule->doctor->id;
        $day = $doctorSchedule->day;
        $rows = [];
        foreach ($doctorSchedule->doctorDaySlots as $dds) {
            $slot = $dds->slot;
            $appointment = $dds->appointment;
            $free = $appointment === null;
            // der Termin des angemeldeten Patienten?
            $mine = $appointment !== null && $rights['patient'] !== null && $appointment->client_id === $rights['patient']->id;
            $rows[] = new ScheduleRow(
                slotId: $slot->id,
                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->client->label() : null,
                mine: $mine,
                bookable: $free && $dayBookable && ($rights['manager'] || $rights['patientCanBook']),
                bookUrl: self::scheduleUrl($doctorId, $day, $slot->id),
                appointmentId: $appointment !== null && $rights['manager'] ? $appointment->id : null);
        }
        return new ScheduleView($doctorSchedule->doctor->label(), Utils::formatDay($day), $rows);
    }

    // ----------------------------------------------------------------- Hilfsfunktionen

    // die versteckten Felder doctorId / day der POST-Formulare; [null, null], wenn sie
    // ungültig sind
    private function readScheduleRequest(Request $request): array
    {
        $doctorId = Utils::positiveInteger($request->input('doctorId'));
        $day = Utils::validDate(is_string($request->input('day')) ? $request->input('day') : null);
        return $doctorId === null || $day === null ? [null, null] : [$doctorId, $day];
    }

    // /schedule?doctorId=1&day=2026-09-23[&book=7]: route() hängt die Parameter, die keine Pfadparameter sind,
    // ans Ende der URL an
    private static function scheduleUrl(int $doctorId, CarbonImmutable $day, ?int $book = null): string
    {
        $params = ['doctorId' => $doctorId, 'day' => Utils::iso($day)];
        if ($book !== null) {
            $params['book'] = $book;
        }
        return route('schedule', $params);
    }

    private static function option(Person $p, bool $selected): OptionView
    {
        return new OptionView($p->id, $p->label(), $selected);
    }

    // -----------------------------------------------------------------------
    // die Informationsmeldung für einen Patienten, der bereits einen bevorstehenden Termin hat
    // (warum es keinen Button "Book" gibt), oder null. Überflüssig, wenn SEIN
    // Termin im angezeigten Terminkalender erscheint (in Blau): Das ist direkt
    // nach der Buchung der Fall, wo die Meldung fehl am Platz wäre.
    // -----------------------------------------------------------------------
    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 Kopfkommentar fasst zusammen, was jeder Benutzer sieht und tun kann.

11.17.3.1. Die URL-Elemente 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 Fenster zur Buchung von Zeitfenster 4. Sie können die Seite neu laden, ein Lesezeichen setzen oder die Zurück-Schaltfläche des Browsers verwenden, ohne eine einzige Zeile [JavaScript]. Das Formular oben auf der Seite (zur Auswahl des Arztes und des Tages) ist ein GET-Formular (Beispiel 17): Es lädt die Seite mit neuen Parametern neu. Das Fenster zur Terminbuchung wird über einen einfachen Link geöffnet und über einen Link auf dieselbe Seite ohne den Parameter [book] geschlossen.

11.17.3.2. GET /schedule

Zeilen 76–148:

  • Die URL-Parameter werden unverändert gelesen ([$request->query('day')]), ohne Validierung durch [Laravel]: 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, ohne die Anzeige des übrigen Inhalts zu verhindern; die Nummer eines Arztes oder Zeitfensters, die keine positive Ganzzahl ist, wird einfach ignoriert;
  • Ein angemeldeter Patient, der keinen Arzt ausgewählt hat, kann seinen Terminkalender einsehen: Das System sucht seinen Arzt anhand seines Kontos ([getDoctorByUserId]). [?->id]: Der Null-Safe-Operator liefert [null] , wenn das Objekt [null] ist, statt einen Fehler auszulösen;
  • die Dropdown-Liste der Ärzte: Jeder Arzt wird zu einer [OptionView]; [map(...)->all()] liefert ein Array;
  • der Terminkalender, formatiert und nach den Berechtigungen des Benutzers gefiltert ([scheduleView], 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 gebuchtes Zeitfenster zu erzeugen, erhielte nichts. [array_find] ([PHP] 8.4) liefert das erste Element eines Arrays, das eine Bedingung erfüllt, oder [null]. Die Liste der Patienten wird nur dem Administrator und den Ärzten bereitgestellt; ein Patient erhält nur seinen eigenen Namen;
  • die View erhält ihre Variablen ([view('schedule', [...])], Beispiel 13), darunter [pageTitle] und [error], die vom Template gelesen werden.

11.17.3.3. POST /schedule/book

Zeilen 161–206:

  • Die versteckten Felder im Terminformular (Arzt, Tag, Zeitfenster) werden geprüft; sind sie ungültig, muss es sich um eine manuell erstellte Anfrage handeln: [abort(400)], die Seite „Ungültige Anfrage“;
  • Bei einem Patienten wird das Feld [clientId] ignoriert: Der Patient bucht immer für sich selbst ([Utils::connectedPatient]). Würde man einem vom Browser gesendeten Feld vertrauen, könnte ein böswilliger Patient eine Reservierung im Namen eines anderen vornehmen. Für den Administrator und die Ärzte muss ein Patient ausgewählt worden sein; andernfalls öffnet sich das Reservierungsfenster erneut mit einer Meldung;
  • das Zeitfenster muss zu dem auf der Seite genannten Arzt gehören;
  • die Geschäftsregeln (nicht in der Vergangenheit, nur ein anstehender Termin, verfügbares Zeitfenster) werden von der Geschäftsschicht geprüft. Eine [BusinessException] wird zu einer Flash-Fehlermeldung. Dieselbe Ablehnung, „ein anstehender Termin“, wird der zweiten Person im Namen des Patienten selbst angezeigt („Sie haben bereits ...“). Jede andere Exception wird nicht abgefangen: Das ist ein echter Fehler (Seite 500);
  • in allen Fällen gilt das Post/Redirect/Get-Muster (Beispiel 20): eine Flash-Meldung und eine Weiterleitung zum Terminkalender.

11.17.3.4. POST /schedule/cancel

Zeilen 212–228: Absage eines Termins durch den Administrator oder einen Arzt (die Middleware [role:ADMIN,DOCTOR] in der Route). Ein Termin, der nicht mehr existiert (bereits von jemand anderem abgesagt oder wegen eines Doppelklicks), ist keine Exception: Es gibt lediglich eine Meldung.

11.17.3.5. Berechtigungen, der formatierte Terminkalender und Hilfsfunktionen

  • Zeilen 236–244: 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 anstehenden Termine)?
  • Zeilen 249–273: der Terminkalender des Arztes, in Zeilen für die View umgewandelt. Der entscheidende Punkt für die Vertraulichkeit ist Zeile 266: Ein Patient sieht nur den Namen, der zu seinem eigenen Termin gehört. Bei den anderen ist 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, der noch nicht vergangen ist, einem Administrator oder einem Patienten angezeigt, der eine Buchung vornehmen kann; die Schaltfläche „Absagen“ wird nur Administratoren angezeigt. Die benannten Argumente ([slotId: $slot->id]) machen die Konstruktion eines Objekts mit acht Eigenschaften lesbar;
  • Zeilen 288–295: die URL für den Terminkalender eines Arztes an einem bestimmten Tag. [route('schedule', [...])] hängt am Ende der URL als Query-Parameter die Werte an, die keine Pfadparameter sind: [/schedule?doctorId=1&day=2026-09-26];
  • Zeilen 308–315: die Meldung, die einem Patienten erklärt, warum es keine Schaltfläche „Buchen“ gibt (er hat bereits einen anstehenden Termin), es sei denn, dieser Termin steht im angezeigten Terminkalender (unmittelbar nach der Buchung würde die Meldung sonst verschoben). [array_any] ([PHP] 8.4): Erfüllt mindestens ein Element die Bedingung?

11.17.4. app/Http/Controllers/PersonsController.php

<?php
// =========================================================================
// app/Http/Controllers/PersonsController.php: Die Verwaltung der Ärzte und
// die der Clients (dem ADMIN vorbehalten) sind IDENTISCH: gleiche Liste, gleiches Formular,
// gleiche Regeln. Statt dieselben Aktionen 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
// (doctors oder clients), die Übersetzungsschlüssel und die aufzurufenden Methoden
// des ApplicationModel. So erhalten wir für jeden (siehe routes/web.php):
//
//   GET  /doctors                    Liste
//   GET  /doctors/add                leeres Formular
//   POST /doctors/add                Anlegen
//   GET  /doctors/{id}/edit          vorausgefülltes Formular
//   POST /doctors/{id}/edit          Änderung
//   POST /doctors/{id}/delete        Löschen
//
// (und dieselben URLs unter /clients). Auch die Views sind gemeinsam:
// resources/views/persons/list.blade.php und persons/form.blade.php.
//
// SICHERHEIT: Die Middleware [role:ADMIN] liegt auf der GRUPPE der Routen jedes
// Abschnitts (siehe routes/web.php): Sie schützt alle seine Aktionen - auch die,
// die ihm später hinzugefügt würden.
// =========================================================================

namespace App\Http\Controllers;

use App\Http\Requests\PersonRequest;
use App\Business\PersonData;
use App\Business\BusinessException;
use App\Models\Person;
use App\Views\PersonKeys;
use App\Web\ApplicationModel;
use App\Web\Flash;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Http\RedirectResponse;
use Illuminate\View\View;

abstract class PersonsController
{
    // die von jedem "Eingabe"-Geschäftsfehler betroffenen Formularfelder (ein
    // Duplikat): Sie werden rot umrandet, die Meldung 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)
    {
    }

    // ---- was jeder Personentyp liefern muss

    // "doctors" oder "clients": der Anfang der URLs und der Routennamen
    abstract protected function section(): string;

    abstract protected function keys(): PersonKeys;

    abstract protected function listAll(): Collection;

    abstract protected function find(int $id): ?Person;

    abstract protected function create(PersonData $data): Person;

    abstract protected function update(int $id, PersonData $data): Person;

    abstract protected function remove(int $id): void;

    // -------------------------------------------------------------------
    // GET /doctors (oder /clients)
    // -------------------------------------------------------------------
    public function list(): View
    {
        return view('persons.list', ['pageTitle' => $this->keys()->title, 'keys' => $this->keys(),
            'section' => $this->section(), 'persons' => $this->listAll()]);
    }

    // -------------------------------------------------------------------
    // GET /doctors/add
    // -------------------------------------------------------------------
    public function addForm(): View
    {
        return $this->form(null);
    }

    // -------------------------------------------------------------------
    // POST /doctors/add
    // PersonRequest hat die Eingabe bereits validiert: Eine ungültige Eingabe kommt nicht
    // bis hierher (Laravel hat mit den Fehlern zum Formular zurückgeschickt)
    // -------------------------------------------------------------------
    public function add(PersonRequest $request): RedirectResponse
    {
        try {
            $person = $this->create($request->personData());
        } catch (BusinessException $e) {
            return $this->businessError($e);
        }
        Flash::success($this->keys()->added, self::params($person));
        return redirect()->route($this->section().'.list');
    }

    // -------------------------------------------------------------------
    // GET /doctors/{id}/edit
    // {id} muss aus Ziffern bestehen (whereNumber, siehe routes/web.php):
    // /doctors/abc/edit passt zu keiner Route (404-Seite)
    // -------------------------------------------------------------------
    public function editForm(int $id): View
    {
        $person = $this->find($id) ?? abort(404);
        return $this->form($person);
    }

    // -------------------------------------------------------------------
    // POST /doctors/{id}/edit
    // -------------------------------------------------------------------
    public function edit(PersonRequest $request, int $id): RedirectResponse
    {
        try {
            $person = $this->update($id, $request->personData());
        } catch (BusinessException $e) {
            return $this->businessError($e);
        }
        Flash::success($this->keys()->edited, self::params($person));
        return redirect()->route($this->section().'.list');
    }

    // -------------------------------------------------------------------
    // POST /doctors/{id}/delete
    // (die Bestätigung "Are you sure?" wird vor dem Absenden des Formulars abgefragt,
    // siehe public/js/app.js)
    // -------------------------------------------------------------------
    public function delete(int $id): RedirectResponse
    {
        $person = $this->find($id);
        try {
            $this->remove($id);
            Flash::success($this->keys()->deleted, self::params($person));
        } catch (BusinessException $e) {
            Flash::error($e->key, $e->params);
        }
        return redirect()->route($this->section().'.list');
    }

    // ----------------------------------------------------------------- interne Funktionen

    // $person null: Formular zum Anlegen; andernfalls Änderungsformular,
    // mit ihren Werten vorausgefüllt (es sei denn, die View hat eine erneut anzuzeigende Eingabe: old())
    private function form(?Person $person): View
    {
        $creating = $person === null;
        $keys = $this->keys();
        return view('persons.form', [
            'pageTitle' => $creating ? $keys->add : $keys->edit,
            'creating' => $creating,
            'person' => $person,
            'action' => $creating ? route($this->section().'.add')
                : route($this->section().'.edit', ['id' => $person->id]),
            'listUrl' => route($this->section().'.list'),
        ]);
    }

    // eine Geschäftsregel hat das Schreiben abgelehnt: zurück zum Formular (back), mit
    // der Eingabe des Benutzers (withInput, ohne die Passwörter), der Meldung der
    // Geschäftsschicht (unten auf der Seite) und den betroffenen Feldern, falls vorhanden,
    // rot umrandet, damit der Benutzer sofort sieht, was zu korrigieren ist
    private function businessError(BusinessException $e): RedirectResponse
    {
        Flash::error($e->key, $e->params);
        if (in_array($e->key, ['ERRORS.DOCTOR_NOT_FOUND', 'ERRORS.PATIENT_NOT_FOUND'], true)) {
            // zwischenzeitlich von einem anderen ADMIN gelöscht: zurück zur Liste
            return redirect()->route($this->section().'.list');
        }
        return back()->withInput(request()->except('password'))
            ->with('invalidFields', self::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
    }

    // :name und :login der Meldungen "added / edited / deleted"
    private static function params(?Person $person): array
    {
        return $person === null ? ['name' => '', 'login' => '']
            : ['name' => "{$person->first_name} {$person->last_name}", 'login' => $person->account?->login ?? ''];
    }
}

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

  • Zeilen 43–47: die Felder, die von jedem Eingabefehler der Geschäftslogik betroffen sind: Ein doppelter Benutzername betrifft das Feld „Login“; ein Namenskonflikt betrifft die Felder „Vorname“ und „Nachname“. Diese Felder werden rot hervorgehoben;
  • Zeilen 73–77: die Liste. Die View ist beiden Abschnitten gemeinsam: Sie erhält die Übersetzungsschlüssel des Abschnitts ([keys]) und seinen Namen ([section]), die zur Erzeugung der URL dienen ([route("$section.addForm")]);
  • Zeilen 92–101: das Hinzufügen. Die Eingabe wurde bereits von [PersonRequest] validiert: Eine ungültige Eingabe gelangt nicht bis hierher ([Laravel] hat den Browser samt den Fehlern zum Formular zurückgeleitet). Es bleibt die Geschäftslogikschicht, die das Speichern ablehnen kann (wegen eines Namensvetters oder eines bereits vergebenen Logins); andernfalls erscheint eine Erfolgsmeldung, und der Benutzer kehrt zur Liste zurück (PRG-Schema);
  • Zeilen 108–112: das Änderungsformular für einen vorhandenen Benutzer: [?? abort(404)] ([abort] löst eine Exception aus: Es ist ein Ausdruck, der rechts von [??] verwendet werden kann);
  • Zeilen 117–126: die Änderung; die ID stammt aus dem Pfad der URL ([{id}]), die Daten aus dem Formular;
  • Zeilen 133–143: das Löschen. Das Formular hat im Browser eine Bestätigung angefordert (Beispiel 21). Die Person wird vor dem Löschen für die Erfolgsmeldung abgerufen („Arzt Paul TATOU wurde gelöscht.“);
  • Zeilen 149–161: das Formular für die Erstellung ([$person] ist gleich [null]) oder die Änderung. Die View erhält die Person und zeigt ihre Werte an – außer nach einer Ablehnung, bei der sie die eingegebenen Daten erneut anzeigt ([old], Beispiel 19);
  • Zeilen 167–176: Die Geschäftsschicht hat die Schreiboperation abgelehnt. Wurde die Person zwischenzeitlich gelöscht (von einem anderen Administrator): Rückkehr zur Liste. Andernfalls Rückkehr zum Formular ([back()], die vorherige Seite, Beispiel 19), wie bei einem Eingabefehler: die erneut anzuzeigende Eingabe ([withInput], ohne das Passwort), die Meldung der Geschäftsschicht (eine Flash-Fehlermeldung, die am Seitenende angezeigt wird) und die rot hervorzuhebenden Felder ([with('invalidFields', ...)], ein Flash-Datenwert, den die View liest). [request()]: die aktuelle Anfrage, überall zugänglich;
  • Zeilen 179–183: die Parameter [:name] und [:login] der Erfolgsmeldungen.

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

<?php
// app/Http/Controllers/DoctorsController.php: die Verwaltung der Ärzte (nur Rolle
// ADMIN). Alle Aktionen sind von PersonsController geschrieben: Hier
// bleibt nur noch zu sagen, WAS aufzurufen ist und WELCHE Beschriftungen anzuzeigen sind.

namespace App\Http\Controllers;

use App\Business\PersonData;
use App\Models\Person;
use App\Views\PersonKeys;
use Illuminate\Database\Eloquent\Collection;

class DoctorsController extends PersonsController
{
    protected function section(): string
    {
        return 'doctors';
    }

    // DOCTORS.TITLE, DOCTORS.ADD ... (siehe lang/*.json)
    protected function keys(): PersonKeys
    {
        return PersonKeys::of('DOCTORS');
    }

    protected function listAll(): Collection
    {
        return $this->application->getAllDoctors();
    }

    protected function find(int $id): ?Person
    {
        return $this->application->getDoctorById($id);
    }

    protected function create(PersonData $data): Person
    {
        return $this->application->addDoctor($data);
    }

    protected function update(int $id, PersonData $data): Person
    {
        return $this->application->editDoctor($id, $data);
    }

    protected function remove(int $id): void
    {
        $this->application->deleteDoctor($id);
    }
}

Hier bleibt nur noch festzulegen, was aufzurufen ist (die Methoden von [ApplicationModel]) und welche Beschriftungen anzuzeigen sind (die Schlüssel [DOCTORS.xxx] in den Wörterbüchern). Der Konstruktor wird von [PersonsController] geerbt: [ApplicationModel] steckt in der Eigenschaft [$this->application], die als [protected] (für Kindklassen sichtbar) deklariert ist. [ClientsController] ist identisch, mit den Kundenmethoden und den Schlüsseln aus [CLIENTS.xxx].

11.17.6. app/Http/Controllers/RegistrationController.php

<?php
// =========================================================================
// app/Http/Controllers/RegistrationController.php: "Create a client account": Ein
// Patient, der noch kein Konto hat, legt es selbst an. ÖFFENTLICHE Routen (man hat
// per Definition noch kein Konto):
//
//   POST /register/access     Button "Create a client account" 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. der Button "Create a client account" sendet das Login-Formular an
//      /register/access; wird das CAPTCHA korrekt abgeschrieben, stellt der Server einen
//      Pass aus (siehe app/Auth/RegistrationPass.php);
//   2. ohne gültigen Pass leitet /register zur Login-
//      Seite zurück (Middleware CheckRegistrationPass);
//   3. der Pass wird beim Anlegen verbraucht: Ein gelöstes CAPTCHA erlaubt das
//      Anlegen EINES Kontos;
//   4. zusätzlich ist die Anzahl der pro Stunde und IP-Adresse erstellten Konten begrenzt
//      (siehe app/Auth/AttemptLimiter.php).
//
// Das angelegte Konto ist genau das, das der ADMIN über die Seite "Clients" anlegen würde
// (gleiche Methode der Geschäftsschicht: addClient), nur dass der Patient
// seinen Login und sein Passwort WÄHLT (erforderlich, mit Bestätigung).
// =========================================================================

namespace App\Http\Controllers;

use App\Auth\CaptchaService;
use App\Auth\AttemptLimiter;
use App\Auth\RegistrationPass;
use App\Http\Requests\RegistrationRequest;
use App\Business\BusinessException;
use App\Web\ApplicationModel;
use App\Web\Flash;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\View\View;

class RegistrationController
{
    // die Felder, die NIE an den Browser zurückgesendet werden
    private const PASSWORDS = ['password', 'password_confirmation'];

    public function __construct(
        private ApplicationModel $application,
        private CaptchaService $captchas,
        private AttemptLimiter $limiter,
        private RegistrationPass $passes,
    ) {
    }

    // -----------------------------------------------------------------------
    // POST /register/access   Felder: captchaId, captcha (die der Login-
    // Seite; login und password, ebenfalls gesendet, werden ignoriert)
    // -----------------------------------------------------------------------
    public function access(Request $request): RedirectResponse
    {
        $ip = (string) $request->ip();

        // zu viele kürzlich von dieser Adresse erstellte Konten: kein Grund weiterzumachen
        $minutes = $this->limiter->registrationBlockMinutes($ip);
        if ($minutes > 0) {
            Flash::error('ERRORS.TOO_MANY_ACCOUNTS', ['minutes' => $minutes]);
            return redirect()->route('login');
        }

        // CAPTCHA fehlt oder ist falsch: zurück zur Login-Seite, mit einem
        // neuen Bild (ein Fehlversuch zählt als Login-Fehlversuch)
        if (! $this->captchas->verify($request->input('captchaId'), $request->input('captcha'))) {
            $this->limiter->loginFailure($ip, '');
            Flash::error('ERRORS.CAPTCHA_BEFORE_ACCOUNT');
            return redirect()->route('login');
        }

        // korrektes CAPTCHA: wir stellen den Pass aus und öffnen das Formular
        return redirect()->route('registration')
            ->withCookie(RegistrationPass::cookie($this->passes->issue()));
    }

    // -----------------------------------------------------------------------
    // GET /register (der Pass wurde von der Middleware geprüft)
    // -----------------------------------------------------------------------
    public function form(): View
    {
        return view('registration', ['pageTitle' => 'REGISTRATION.TITLE']);
    }

    // -----------------------------------------------------------------------
    // POST /register. RegistrationRequest hat bereits die GESAMTE Eingabe validiert (Felder
    // und Passwortbestätigung): Der Benutzer korrigiert alle seine Fehler
    // in einem Zug
    // -----------------------------------------------------------------------
    public function create(RegistrationRequest $request): RedirectResponse
    {
        $ip = (string) $request->ip();

        // 1. zu viele kürzlich von dieser Adresse erstellte Konten?
        $minutes = $this->limiter->registrationBlockMinutes($ip);
        if ($minutes > 0) {
            Flash::error('ERRORS.TOO_MANY_ACCOUNTS', ['minutes' => $minutes]);
            return back()->withInput($request->except(self::PASSWORDS));
        }

        // 2. das Anlegen (Client + USER-Konto, in einer Transaktion)
        try {
            $this->application->addClient($request->personData());
        } catch (BusinessException $e) {
            // Login oder Vor- + Nachname bereits vergeben: Der Pass bleibt gültig
            Flash::error($e->key, $e->params);
            return back()->withInput($request->except(self::PASSWORDS))
                ->with('invalidFields', PersonsController::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
        }

        // 3. der Pass wurde verwendet: Er erlaubt nicht, ein 2. Konto anzulegen
        $this->passes->consume($request->cookie(RegistrationPass::COOKIE));
        $this->limiter->registrationSuccess($ip);

        // 4. zurück zur Login-Seite, Login vorausgefüllt
        $login = $request->input('login');
        Flash::success('REGISTRATION.DONE', ['login' => $login]);
        return redirect()->route('login', ['login' => $login])
            ->withCookie(RegistrationPass::clearingCookie());
    }
}

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

  • Zeilen 60–82: Die Schaltfläche „Patientenkonto erstellen“ auf der Login-Seite sendet das Login-Formular an diese Adresse (später die View [login]). Wurden von dieser Adresse (IP) in letzter Zeit zu viele Konten erstellt, ist ein Fortfahren nicht nötig. Fehlt das CAPTCHA oder ist es falsch: Rückkehr zur Login-Seite mit einem neuen Bild und einer Meldung; der Fehlschlag zählt als fehlgeschlagener Login-Versuch (mit leerem Benutzernamen). Ist das CAPTCHA korrekt: Ein Token wird in einem Cookie gespeichert, und der Benutzer wird zum Formular weitergeleitet;
  • Zeilen 87–90: das Formular. Das Token wurde von der Middleware [registration.pass] der Route geprüft;
  • Zeilen 97–127: die Erstellung. [RegistrationRequest] hat alle eingegebenen Daten validiert, einschließlich der Passwortbestätigung: Der Benutzer sieht alle seine Fehler auf einmal. Der Kunde und sein Konto werden mit derselben Methode der Geschäftsschicht erstellt wie beim Administrator ([addClient]); nur Benutzername und Passwort wählt der Patient. Ist ein Benutzername oder ein Namensvetter bereits vergeben: Rückkehr zum Formular, ohne das Token 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 Login-Seite weiter ([route('login', ['login' => $login])] fügt den Parameter [?login=...] hinzu), zusammen mit einer Erfolgsmeldung. Das Pass-Cookie wird gelöscht.

Die Konstante [PASSWORDS] (Zeile 46) listet die Felder auf, die nie an den Browser zurückgesendet werden sollten: [back()->withInput()] würde ohne Parameter alle Eingaben für das nächste Formular behalten, auch die Passwörter; [$request->except([...])] übergibt das Formular ohne diese Felder. Wenn [Laravel] (wegen eines Validierungsfehlers) zum Formular zurückkehrt, schließt es die Felder [password], [password_confirmation] und [current_password] automatisch aus.

11.17.7. app/Http/Controllers/PatientAreaController.php

<?php
// =========================================================================
// app/Http/Controllers/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               Änderungsformular seines Kontos
//   POST /my-account               Änderung
//   POST /my-account/delete        Löschen des Kontos (und seiner Termine)
//
// Goldene Regel dieses Controllers: Der betroffene Patient ist IMMER der aus dem Token
// (Utils::connectedPatient), nie eine vom Browser gesendete Kennung. Ein
// Patient kann daher weder sehen noch ändern noch stornieren, was einem anderen
// Patienten gehört, selbst wenn er seine Anfragen selbst zusammenbaut.
//
// 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. Die Fehler beim aktuellen Passwort werden
// als Login-Fehlversuche gezählt (gleiches Limit).
// =========================================================================

namespace App\Http\Controllers;

use App\Auth\AuthService;
use App\Auth\AttemptLimiter;
use App\Http\Requests\MyAccountRequest;
use App\Business\BusinessException;
use App\Models\Client;
use App\Models\Appointment;
use App\Views\AppointmentView;
use App\Web\ApplicationModel;
use App\Web\Flash;
use App\Web\Message;
use App\Web\Utils;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\View\View;

class PatientAreaController
{
    public function __construct(
        private ApplicationModel $application,
        private AuthService $auth,
        private AttemptLimiter $limiter,
    ) {
    }

    // -----------------------------------------------------------------------
    // GET /my-area
    // -----------------------------------------------------------------------
    public function patientArea(): View
    {
        $patient = Utils::connectedPatient($this->application);
        $appointments = $this->application->getClientUpcomingAppointments($patient->id)->map(fn (Appointment $a) => new AppointmentView(
            $a->id,
            Utils::formatDay($a->day),
            $a->slot->time(),
            $a->slot->doctor->label(),
            // Link zum Terminkalender des Arztes an diesem Tag: Der Patient sieht dort seinen Namen
            route('schedule', ['doctorId' => $a->slot->doctor_id, 'day' => Utils::iso($a->day)])))
            ->all();
        return view('area', ['pageTitle' => 'AREA.TITLE', 'patient' => $patient->label(),
            'appointments' => $appointments]);
    }

    // -----------------------------------------------------------------------
    // POST /my-area/cancel   Feld: appointmentId
    // -----------------------------------------------------------------------
    public function cancelAppointment(Request $request): RedirectResponse
    {
        $patient = Utils::connectedPatient($this->application);
        $appointmentId = Utils::positiveInteger($request->input('appointmentId'));
        $appointment = $appointmentId !== null ? $this->application->getAppointmentById($appointmentId) : null;
        // Ein nicht existierender Termin und der eines ANDEREN Patienten erhalten
        // dieselbe Antwort: Wir verraten nichts über die Termine der anderen
        if ($appointment === null || $appointment->client_id !== $patient->id) {
            Flash::error('ERRORS.APPOINTMENT_NOT_FOUND');
        } else {
            $this->application->deleteAppointment($appointment);
            Flash::success('SCHEDULE.CANCELLED');
        }
        return redirect()->route('area');
    }

    // -----------------------------------------------------------------------
    // GET /my-account: das mit den Werten des Patienten vorausgefüllte Formular
    // -----------------------------------------------------------------------
    public function accountForm(): View
    {
        $patient = Utils::connectedPatient($this->application);
        return view('account', ['pageTitle' => 'MY_ACCOUNT.TITLE', 'patient' => $patient]);
    }

    // -----------------------------------------------------------------------
    // POST /my-account (MyAccountRequest hat die Eingabe validiert)
    // -----------------------------------------------------------------------
    public function editAccount(MyAccountRequest $request): RedirectResponse
    {
        $patient = Utils::connectedPatient($this->application);

        // das aktuelle Passwort; falsch: Die Meldung steht UNTER dem Feld und unten auf der Seite
        $error = $this->checkCurrentPassword($request, $patient, $request->input('current_password'));
        if ($error !== null) {
            Flash::error($error->key, $error->params);
            return back()->withInput($request->except(['password', 'password_confirmation', 'current_password']))
                ->withErrors(['current_password' => __($error->key, $error->params)]);
        }

        try {
            $client = $this->application->editClient($patient->id, $request->personData());
        } catch (BusinessException $e) {
            Flash::error($e->key, $e->params);
            return back()->withInput($request->except(['password', 'password_confirmation', 'current_password']))
                ->with('invalidFields', PersonsController::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
        }
        // Login und angezeigter Name stehen IM Token: Wir stellen ein neues aus,
        // sonst würde die Navigationsleiste den alten Namen behalten
        Flash::success('MY_ACCOUNT.UPDATED');
        return redirect()->route('area')->withCookie($this->auth->tokenCookie($client->account));
    }

    // -----------------------------------------------------------------------
    // POST /my-account/delete   Feld: current_password
    // Das Konto, der Client und ALLE seine Termine verschwinden gemeinsam, dann wird der
    // Patient abgemeldet.
    // -----------------------------------------------------------------------
    public function deleteAccount(Request $request): RedirectResponse
    {
        $patient = Utils::connectedPatient($this->application);
        $error = $this->checkCurrentPassword($request, $patient, $request->input('current_password'));
        if ($error !== null) {
            Flash::error($error->key, $error->params);
            return redirect()->route('account');
        }
        $this->application->deleteClient($patient->id);
        Flash::success('MY_ACCOUNT.DELETED');
        return redirect()->route('login')->withCookie(AuthService::clearingCookie());
    }

    // ----------------------------------------------------------------- interne Funktionen

    // null, wenn das aktuelle Passwort korrekt ist; andernfalls die Fehlermeldung
    private function checkCurrentPassword(Request $request, Client $patient, ?string $password): ?Message
    {
        $ip = (string) $request->ip();
        $login = $patient->account->login;
        $minutes = $this->limiter->loginBlockMinutes($ip, $login);
        if ($minutes > 0) {
            return new Message('ERRORS.TOO_MANY_ATTEMPTS', ['minutes' => $minutes]);
        }
        if (! $password || $this->auth->validate($login, $password) === null) {
            $this->limiter->loginFailure($ip, $login);
            return new Message('ERRORS.WRONG_CURRENT_PASSWORD');
        }
        return null;
    }
}

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

  • Zeilen 53–66: Mein Bereich: der Name des Patienten und seine anstehenden Termine, formatiert ([AppointmentView]), jeweils mit einem Link zum Terminkalender des Arztes an diesem Tag;
  • Zeilen 71–85: Absage des Termins des Patienten. Ein nicht vorhandener Termin und der Termin eines anderen Patienten erhalten dieselbe Antwort: Es werden keine Informationen über die Termine anderer Patienten preisgegeben (nicht einmal ihre Existenz);
  • Zeilen 90–94: das Formular „Mein Konto verwalten“, mit den Angaben des Patienten vorausgefüllt;
  • Zeilen 99–122: die Änderung. Jede Änderung erfordert das aktuelle Passwort: Jemand, der eine offen gebliebene Session gefunden hat, könnte weder das Passwort ändern noch sonst etwas tun. Bei einem falschen aktuellen Passwort: Rückkehr zum Formular, mit einer Meldung unter dem Feld ([withErrors] fügt einen Eingabefehler hinzu, als hätte ihn die Validierung erkannt) und am Seitenende (Flash-Meldung). Nach der Änderung wird ein neues Token erzeugt: Login und Anzeigename sind im Token enthalten; andernfalls würde die Navigationsleiste bis zur nächsten Anmeldung den alten Namen behalten;
  • Zeilen 129–140: Löschen des Kontos, des Kunden und aller seiner Termine mit derselben Methode der Geschäftslogik wie beim Administrator. Das aktuelle Passwort ist erforderlich; der Patient wird anschließend abgemeldet (Token-Cookie gelöscht);
  • Zeilen 145–158: Prüfung des aktuellen Passworts. Sie unterliegt dem Versuchslimiter, genau wie ein Login: 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.18. Die Views

Die [Blade]-Views im Ordner [resources/views]: ein Template, Fragmente, Komponenten und Seiten.

11.18.1. Das Template und die Fragmente

11.18.1.1. resources/views/layout.blade.php

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

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

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

     The layout shares the variables of the page: [pageTitle] (the key of the title of
     the page, passed by the action); [language] and [user], added to all
     the views by AppServiceProvider.
     ========================================================================= --}}
<html lang="{{ $language }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {{-- __($key): the translation of a key; here, the key is a VARIABLE --}}
  <title>{{ __($pageTitle) }} - {{ __('APP.TITLE') }}</title>
  {{-- asset(): the URL of a file of the public folder --}}
  <link rel="stylesheet" href="{{ asset('lib/bootstrap/css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-4">
    @include('fragments.navbar')
    @include('fragments.success')
    <main>
      @yield('content')
    </main>
    @include('fragments.errors')
  </div>
  {{-- the "Are you sure?" dialog, hidden as long as it is not needed --}}
  @include('fragments.confirmation')
  <script src="{{ asset('js/app.js') }}"></script>
</body>
</html>

Das Template, das allen Seiten gemeinsam ist (Beispiel 15): Jede Seite erweitert es ([@extends('layout')]) und füllt seinen Abschnitt [content] (Zeile 36).

  • Zeile 21: die Sprache der Seite, [fr] oder [en], die allen Views vom View Composer [AppServiceProvider] bereitgestellt wird;
  • Zeile 26: der übersetzte Seitentitel: [__($pageTitle)] übersetzt den Schlüssel in der Variablen [$pageTitle], die jede Action 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 unten auf der Seite. Diese Fragmente werden mit [@include] eingefügt (Beispiel 15): Sie greifen auf die Variablen der Seite zu;
  • Zeile 41: das Fenster „Sind Sie sicher?“, das bis zum Bedarfsfall verborgen ist, und das Skript, das es anzeigt.

[Blade] maskiert alles, was es mit [{{ ... }}] ausgibt (Beispiel 14): Ein eingegebener Name, der HTML enthält ([<script>]), wird unverändert angezeigt, ohne interpretiert zu werden. Das verhindert, dass mühelos HTML (XSS) in alle Seiten eingeschleust wird.

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

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

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

     The menu of the current page is highlighted ("active" class):
     request()->is('schedule*') is true if the path of the URL starts with "schedule".
     The menu entries: an array [URL, label key, pattern of the paths for
     which the entry is active], traversed by @foreach.
     ========================================================================= --}}
@php
  $menu = [];
  if ($user) {
      if ($user->isPatient()) {
          // aktiv für /my-area UND /my-account
          $menu[] = [route('area'), 'APP.MENU_MY_AREA', 'my-*'];
      }
      $menu[] = [route('schedule'), 'APP.MENU_SCHEDULE', 'schedule*'];
      if ($user->isAdmin()) {
          $menu[] = [route('doctors.list'), 'APP.MENU_DOCTORS', 'doctors*'];
          $menu[] = [route('clients.list'), 'APP.MENU_PATIENTS', 'clients*'];
      }
  }
@endphp
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
  <span class="navbar-brand mb-0">{{ __('APP.TITLE') }}</span>

  <ul class="navbar-nav me-auto">
    @foreach ($menu as [$href, $key, $pattern])
    <li class="nav-item">
      {{-- @class: the classes whose condition is true --}}
      <a @class(['nav-link', 'active' => request()->is($pattern)]) href="{{ $href }}">{{ __($key) }}</a>
    </li>
    @endforeach
  </ul>

  <div class="d-flex align-items-center gap-2">
    {{-- FR / EN: simple links (GET /language/fr), the active language highlighted --}}
    <div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
      @foreach (['fr', 'en'] as $code)
      <a class="btn {{ $language === $code ? 'btn-light' : 'btn-outline-light' }}"
         href="{{ route('language', ['code' => $code]) }}">{{ strtoupper($code) }}</a>
      @endforeach
    </div>

    @if ($user)
    <span class="badge text-bg-light text-primary">{{ $user->role->value }}</span>
    <span class="text-white">{{ $user->name }}</span>
    {{-- the logout is a POST: a form reduced to its button (and to the anti-CSRF token) --}}
    <form method="post" action="{{ route('logout') }}" class="m-0">
      @csrf
      <button type="submit" class="btn btn-sm btn-outline-light">{{ __('APP.LOGOUT') }}</button>
    </form>
    @endif
  </div>
</nav>

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 der Middleware der Routen (ein Patient, der manuell [/doctors] eingibt, erhält eine 403-Seite).

  • Zeilen 15–28: Das Menü ist in einem [@php]-Block (Beispiel 14) definiert, einem Array von Einträgen: URL (der Beschriftungsschlüssel) und das Muster der Pfade, für die der Eintrag aktiv ist. [request()->is('schedule*')] ist wahr, wenn der Pfad der angeforderten URL zum Muster passt ([*]: eine beliebige Zeichenfolge). Der Eintrag „Mein Bereich“ ist aktiv für [/my-area] und [/my-account] (Muster [my-*]). Das grenzt an die Regel „keine Logik in den Views“: Diese Logik betrifft jedoch nur die Anzeige und wird nur hier verwendet;
  • Zeilen 33–38: [@foreach] zerlegt jeden Eintrag des Arrays in drei Variablen (Beispiel 25). [@class([...])] (Beispiel 16) schreibt das Attribut [class] mit den Klassen, für die die Bedingung wahr ist;
  • Zeilen 44–47: die Schaltflächen FR / EN, einfache Links ([/language/fr]) mit hervorgehobener aktiver Sprache;
  • Zeilen 50–58: für einen angemeldeten Benutzer seine Rolle ([$user->role->value]: der String, der den Enum-Fall darstellt), sein Name und die Abmelde-Schaltfläche. Die Abmeldung ist eine POST-Anfrage: ein auf seine Schaltfläche reduziertes Formular mit seinem Anti-CSRF-Token ([@csrf], Beispiel 18).

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

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

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

Die Erfolgs-Flash-Meldungen, die von der vorherigen Action gesetzt wurden ([Flash::success]), werden mit [session('flash_success', [])] aus der Session gelesen (standardmäßig eine leere Liste). Jede ist ein [Message]-Objekt, das hier in die Sprache der Seite übersetzt wird: [__($message->key, $message->params)]. [role="status"]: Ein Screenreader kündigt die Meldung an.

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

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

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

     $error ?? null: the variable does not exist in all the pages.
     role="alert": a screen reader announces the message as soon as the
     page is displayed, even if it is at the bottom.
     ========================================================================= --}}
@php
  $messages = session('flash_errors', []);
  if ($error ?? null) {
      array_unshift($messages, $error);
  }
  if (! $messages && $errors->any()) {
      $messages[] = new App\Web\Message('ERRORS.INVALID_FORM');
  }
@endphp
@if ($messages)
<div class="error-zone" role="alert">
  @foreach ($messages as $message)
  <div>{{ __($message->key, $message->params) }}</div>
  @endforeach
</div>
@endif

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

  • der Fehler der angezeigten Seite ([$error]), ausgelöst durch die Action: ein ungültiges Datum, ein falsch eingegebenes CAPTCHA usw. [$error ?? null]: Die Variable existiert nicht auf allen Seiten; der Operator [??] meldet keine nicht vorhandene Variable, sondern ersetzt sie durch [null];
  • Flash-Fehlermeldungen, ausgelöst durch die vorherige Action (ein bereits reserviertes Zeitfenster, ein bereits verwendeter Benutzername usw.);
  • Eingabefehler ([$errors], Beispiel 19): Ihre Meldungen werden unter den Feldern angezeigt; gibt es hier keine anderen Meldungen, erscheint ein einfacher Satz: „Das Formular enthält Fehler.“ Bei einem langen Formular erfährt der Benutzer so, dass er wieder nach oben gehen muss.

[array_unshift] fügt ein Element am Anfang eines Arrays ein. [role="alert"]: Ein Screenreader kündigt die Meldung an, sobald die Seite angezeigt wird, auch wenn sie sich am Seitenende befindet. Das Feld bleibt am unteren Rand des Fensters verankert, wenn die Seite lang ist (siehe Stylesheet, unten).

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

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

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

     ONE SINGLE dialog for the whole page, hidden (d-none) at first. Its labels
     are translated here, by the server, like the rest of the page; the small script
     public/js/app.js merely displays it, puts in it the message specific to the
     form (data-confirmation attribute), and sends the form if
     the user confirms.
     ========================================================================= --}}
<div id="confirmation-modal" class="d-none">
  <div class="modal-backdrop fade show"></div>
  <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
       aria-labelledby="confirmation-modal-title" aria-describedby="confirmation-modal-message">
    <div class="modal-dialog modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-header">
          <h5 class="modal-title" id="confirmation-modal-title">{{ __('CONFIRMATION.TITLE') }}</h5>
          <button type="button" class="btn-close" data-action="no" aria-label="{{ __('BOOKING_DIALOG.CLOSE_ARIA') }}"></button>
        </div>
        <div class="modal-body">
          <p class="mb-0" id="confirmation-modal-message"></p>
        </div>
        <div class="modal-footer">
          {{-- "No, go back" rather than "Cancel": the question is sometimes
               "Cancel this appointment?", and a "Cancel" button would be ambiguous there --}}
          <button type="button" class="btn btn-secondary" data-action="no">{{ __('CONFIRMATION.NO') }}</button>
          <button type="button" class="btn btn-danger" data-action="yes">{{ __('CONFIRMATION.YES') }}</button>
        </div>
      </div>
    </div>
  </div>
</div>

Das modale Fenster „Sind Sie sicher?“ aus Beispiel 21, das den Dialog [window.confirm()] des Browsers ersetzt: Dieser Dialog 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, setzt die Meldung des zu bestätigenden Formulars hinein (sein Attribut [data-confirmation]) und sendet das Formular ab, wenn der Benutzer bestätigt. Die Schaltfläche „Abbrechen“ trägt die Beschriftung „Nein, zurück“ statt „Abbrechen“: Die Frage lautet manchmal „Diesen Termin absagen?“, und eine Schaltfläche „Abbrechen“ wäre in diesem Zusammenhang mehrdeutig.

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

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

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

     The fragment directly reads the variables of the page that includes it
     ($booking, $doctorId, $day, $backUrl).
     ========================================================================= --}}
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title">
  <div class="modal-dialog modal-dialog-centered">
    <form method="post" action="{{ route('schedule.book') }}" class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="booking-title">{{ __('BOOKING_DIALOG.TITLE') }}</h5>
        <a class="btn-close" href="{{ $backUrl }}" aria-label="{{ __('BOOKING_DIALOG.CLOSE_ARIA') }}"></a>
      </div>

      <div class="modal-body">
        <p>{{ __('BOOKING_DIALOG.SLOT', ['time' => $booking->time]) }}</p>

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

        {{-- a patient books for themselves: no list to choose from (and the
             server ignores a possible clientId anyway) --}}
        @if ($booking->patient)
        <p class="mb-0">
          <span>{{ __('BOOKING_DIALOG.PATIENT_LABEL') }}</span>:
          <strong>{{ $booking->patient }}</strong>
        </p>
        @else
        <label class="form-label" for="clientId">{{ __('BOOKING_DIALOG.PATIENT_LABEL') }}</label>
        <select id="clientId" name="clientId" class="form-select" required autofocus>
          <option value="">{{ __('BOOKING_DIALOG.CHOOSE_PATIENT') }}</option>
          @foreach ($booking->clients as $client)
          <option value="{{ $client->id }}">{{ $client->label }}</option>
          @endforeach
        </select>
        @endif
      </div>

      <div class="modal-footer">
        <a class="btn btn-secondary" href="{{ $backUrl }}">{{ __('BOOKING_DIALOG.CANCEL') }}</a>
        <button type="submit" class="btn btn-primary">{{ __('BOOKING_DIALOG.CONFIRM') }}</button>
      </div>
    </form>
  </div>
</div>

Das Buchungsfenster des Terminkalenders. Es verwendet die tatsächlichen Klassen eines modalen Fensters aus [Bootstrap] ([modal], [modal-backdrop] ...), wird aber „fest verdrahtet“ sichtbar gemacht ([show d-block]), statt über das [JavaScript] von [Bootstrap]: Der Server entscheidet, es anzuzeigen, wenn die URL [&book=...] enthält. Das Schließen (über das X oder die Schaltfläche „Abbrechen“) entspricht dem Aufruf eines Links auf dieselbe Seite ohne diesen Parameter ([$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 reserviert für sich selbst: sein Name, ohne Auswahlliste (und der Server ignoriert ohnehin jedes Feld [clientId]). 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.18.2. Die Komponenten

Drei anonyme Komponenten (Beispiel 15) im Ordner [resources/views/components], die von den Seiten in Form eines [<x-name>]-Tags verwendet werden.

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

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

     @props: the attributes expected by the component, with their default value.
     The displayed value: old($name, $value), the input to redisplay after a refusal,
     otherwise the given value. A password is NEVER redisplayed.
     The field is outlined in red (Bootstrap class is-invalid) if it has an input
     error ($errors), or if a business error designates it (invalidFields, see
     PersonsController::businessError); the error message then replaces the help.
     ========================================================================= --}}
@props(['name', 'label', 'type' => 'text', 'value' => null, 'help' => null, 'max' => null,
        'autocomplete' => null, 'required' => false])
@php
  $invalid = $errors->has($name) || in_array($name, session('invalidFields', []), true);
@endphp
<label class="form-label" for="{{ $name }}">{{ $label }}</label>
<input id="{{ $name }}" name="{{ $name }}" type="{{ $type }}" @class(['form-control', 'is-invalid' => $invalid])
       @if ($type !== 'password') value="{{ old($name, $value) }}" @endif
       @if ($max) maxlength="{{ $max }}" @endif
       @if ($autocomplete) autocomplete="{{ $autocomplete }}" @endif
       @required($required)>
@error($name)
<div class="invalid-feedback">{{ $message }}</div>
@else
@if ($help)
<div class="form-text">{{ $help }}</div>
@endif
@enderror

Ein Eingabefeld mit Label, Fehlermeldung oder Tooltip: die Komponente [x-field] aus Beispiel 19, vollständig konfiguriert.

  • Zeile 12: die Attribute der Komponente und ihre Standardwerte. Auf einer Seite: [<x-field name="login" :label="__('PERSONS.LOGIN_LABEL')" max="30" required />]: Einem Attribut mit vorangestelltem [:] wird der Wert eines [PHP]-Ausdrucks zugewiesen, den anderen ein String; ein Attribut ohne Wert ([required]) wird auf [true] gesetzt;
  • Zeilen 14–16: Das Feld ist ungültig, wenn es einen Eingabefehler enthält ([$errors->has($name)]) oder wenn ein Fehler der Geschäftsschicht es als solches kennzeichnet: die Liste [invalidFields], die von der Action in der Session abgelegt wird ([PersonsController::businessError]). Ein bereits vergebener Benutzername ist kein Eingabefehler (er hat das richtige Format), aber der Benutzer muss sehen, welches Feld er korrigieren muss;
  • Zeilen 18–22: Der angezeigte Wert ist [old($name, $value)]: die nach einer Ablehnung erneut anzuzeigende Eingabe; andernfalls der von der Seite übergebene Wert (der des geänderten Datensatzes). Ein Passwort wird nie erneut angezeigt: Ein Feld vom Typ [password] hat kein Attribut [value]. [@required($required)] setzt das boolesche Attribut [required] , wenn die Bedingung wahr ist;
  • Zeilen 23–29: die Fehlermeldung des Felds ([$message], Beispiel 19), sonst ein eventuell vorhandener Hilfetext. Die Klasse [invalid-feedback] von [Bootstrap] ist nur nach einem Feld der Klasse [is-invalid] sichtbar.

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

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

     :person: the person whose values are displayed (null for an empty
     form). $person?->title: null if $person is null ("nullsafe" operator).
     The list of titles comes from the class that validates them (PersonFieldsRequest).
     ========================================================================= --}}
@props(['person' => null])
@php
  $chosenTitle = old('title', $person?->title ?? 'Mr');
@endphp
<div class="mb-3">
  <label class="form-label" for="title">{{ __('PERSONS.TITLE_LABEL') }}</label>
  <select id="title" name="title" @class(['form-select', 'is-invalid' => $errors->has('title')])>
    @foreach (App\Http\Requests\PersonFieldsRequest::TITLES as $title)
    <option value="{{ $title }}" @selected($title === $chosenTitle)>{{ $title }}</option>
    @endforeach
  </select>
  @error('title')
  <div class="invalid-feedback">{{ $message }}</div>
  @enderror
</div>

<div class="row g-3 mb-3">
  <div class="col-sm-6">
    <x-field name="first_name" :label="__('PERSONS.FIRSTNAME_LABEL')" :value="$person?->first_name" max="20" required />
  </div>
  <div class="col-sm-6">
    <x-field name="last_name" :label="__('PERSONS.LASTNAME_LABEL')" :value="$person?->last_name" max="20" required />
  </div>
</div>

Identitätsfelder, die drei Formulare gemeinsam haben: Anrede (eine Liste), Vorname und Nachname (zwei [x-field]-Felder: Eine Komponente kann eine andere Komponente verwenden). Das Attribut [person] ist die Person, deren Werte angezeigt werden, oder [null] für ein leeres Formular. [$person?->title]: Der Null-Safe-Operator liefert [null] , wenn [$person] null ist. Die Liste der Anreden stammt aus der Klasse, die sie validiert ([PersonFieldsRequest::TITLES]): Die Regel wird nur einmal geschrieben. [@selected(...)] schreibt das Attribut [selected] der ausgewählten Option.

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

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

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

     The hidden field captchaId tells the server WHICH captcha to verify; the right
     answer, for its part, is never sent to the browser. "Another image" simply
     reloads the page (url()->current(): the URL of the page, without its parameters).
     ========================================================================= --}}
@props(['captcha'])
<div class="mb-3">
  <label class="form-label" for="captcha">{{ __('CAPTCHA.LABEL') }}</label>
  <div class="d-flex align-items-center gap-3 mb-2">
    <div class="captcha-image" role="img" aria-label="{{ __('CAPTCHA.IMAGE_ALT') }}">{!! $captcha->svg !!}</div>
    <a class="small" href="{{ url()->current() }}">{{ __('CAPTCHA.NEW_IMAGE') }}</a>
  </div>
  <input type="hidden" name="captchaId" value="{{ $captcha->id }}">
  <input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off"
         spellcheck="false" required class="form-control">
  <div class="form-text">{{ __('CAPTCHA.HELP') }}</div>
</div>

Das CAPTCHA (Beispiel 27). [{!! $captcha->svg !!}] fügt das SVG-Bild unverändert ein, ohne es zu maskieren; andernfalls würde der Browser seinen XML-Code anzeigen. Das ist hier sicher, weil dieses SVG vom Server erzeugt wird und nichts vom Benutzer Geliefertes enthält: Bei 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 Seite neu ([url()->current()]: die URL der Seite ohne ihre Parameter) und damit das CAPTCHA.

11.18.3. Die Seiten

11.18.3.1. resources/views/login.blade.php

{{-- =========================================================================
     resources/views/login.blade.php - the login form (see
     AuthController). An ordinary HTML <form>: the browser itself sends
     login, password and captcha answer in POST /login, without JavaScript. In
     case of failure, the server sends back THIS page, with the login already typed, a
     NEW captcha and the error, displayed at the bottom of the page by the layout.
     ========================================================================= --}}
@extends('layout')

@section('content')
<div class="row justify-content-center">
  <div class="col-sm-8 col-md-6 col-lg-5">
    <div class="card p-4">
      <h5 class="card-title mb-3">{{ __('LOGIN.TITLE') }}</h5>

      <form method="post" action="{{ route('login') }}">
        @csrf
        <div class="mb-3">
          <label class="form-label" for="login">{{ __('LOGIN.LOGIN_LABEL') }}</label>
          {{-- autofocus: a boolean attribute, written if the condition is true, omitted
               otherwise. The cursor goes to the first field to fill in --}}
          <input id="login" name="login" type="text" class="form-control" autocomplete="username"
                 value="{{ $login }}" required @if ($login === '') autofocus @endif>
        </div>
        <div class="mb-3">
          <label class="form-label" for="password">{{ __('LOGIN.PASSWORD_LABEL') }}</label>
          <input id="password" name="password" type="password" class="form-control"
                 autocomplete="current-password" required @if ($login !== '') autofocus @endif>
        </div>

        <x-captcha :captcha="$captcha" />

        <button type="submit" class="btn btn-primary w-100">{{ __('LOGIN.SUBMIT') }}</button>

        {{-- no account yet: a patient can create one themselves. It is NOT
             a simple link: it is a second submit button of THIS form,
             which goes to another address (formaction). There the server checks the
             captcha above before opening the account creation page (see
             RegistrationController). formnovalidate: the browser does not require
             login and password (useless to create an account). Enter in a
             field always triggers the FIRST button of the form, "Log in". --}}
        <button type="submit" class="btn btn-outline-primary w-100 mt-3"
                formaction="{{ route('registration.access') }}" formnovalidate>{{ __('LOGIN.CREATE_ACCOUNT') }}</button>
        <div class="form-text text-center">{{ __('LOGIN.CREATE_ACCOUNT_HELP') }}</div>
      </form>

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

Das Login-Formular, ein gewöhnliches [<form>], wird per POST an [/login] gesendet.

  • Zeilen 22–23: Der eingegebene Benutzername wird nach einem fehlgeschlagenen Login-Versuch 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);
  • Zeile 31: das CAPTCHA;
  • Zeilen 42–43: Die Schaltfläche „Patientenkonto erstellen“ ist kein Link, sondern 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 für die Erstellung eines Kontos nicht nötig sind. Das Drücken der Eingabetaste in einem Feld löst immer die erste Absende-Schaltfläche des Formulars aus: Anmelden.

11.18.3.2. resources/views/schedule.blade.php

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

@section('content')
  {{-- 1. choice of the doctor and of the day: a GET form, which simply reloads
          this page with ?doctorId=...&day=... in the URL --}}
  <form method="get" action="{{ route('schedule') }}" class="card p-3 mb-3">
    <div class="row g-2 align-items-end">
      <div class="col-sm-5">
        <label class="form-label" for="doctorId">{{ __('DOCTOR_DAY_PICKER.DOCTOR_LABEL') }}</label>
        <select id="doctorId" name="doctorId" class="form-select" required>
          <option value="">{{ __('DOCTOR_DAY_PICKER.CHOOSE_DOCTOR') }}</option>
          @foreach ($doctors as $doctor)
          <option value="{{ $doctor->id }}" @selected($doctor->selected)>{{ $doctor->label }}</option>
          @endforeach
        </select>
      </div>
      <div class="col-sm-4">
        <label class="form-label" for="day">{{ __('DOCTOR_DAY_PICKER.DAY_LABEL') }}</label>
        <input id="day" name="day" type="date" class="form-control" value="{{ $day }}" required>
      </div>
      <div class="col-sm-3">
        <button type="submit" class="btn btn-primary w-100">{{ __('DOCTOR_DAY_PICKER.VIEW_SCHEDULE') }}</button>
      </div>
    </div>
  </form>

  {{-- patient who already has an upcoming appointment: why there is no "Book" button --}}
  @if ($info)
  <div class="alert alert-info">
    <span>{{ __($info) }}</span>
    <a href="{{ route('area') }}" class="alert-link">{{ __('APP.MENU_MY_AREA') }}</a>
  </div>
  @endif

  {{-- 2. the schedule --}}
  @if ($schedule)
  <div class="card p-3">
    <h5>{{ __('SCHEDULE.TITLE_PREFIX') }} {{ $schedule->day }} - {{ $schedule->doctor }}</h5>

    @if ($schedule->rows)
    <table class="table table-hover align-middle">
      <thead>
        <tr>
          <th>{{ __('SCHEDULE.COLUMN_SLOT') }}</th>
          <th>{{ __('SCHEDULE.COLUMN_STATUS') }}</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        @foreach ($schedule->rows as $row)
        <tr @class(['free-slot' => $row->bookable])>
          <td>{{ $row->time }}</td>
          <td>
            {{-- [patient] is only set if the user has the right to see this
                 name (ADMIN, DOCTOR, or the patient for THEIR appointment) - otherwise,
                 simply "Booked" --}}
            @if ($row->free)
            <span class="badge text-bg-success">{{ __('SCHEDULE.FREE') }}</span>
            @elseif ($row->patient)
            <span class="badge {{ $row->mine ? 'text-bg-primary' : 'text-bg-secondary' }}">{{ $row->patient }}</span>
            @else
            <span class="badge text-bg-secondary">{{ __('SCHEDULE.BOOKED_BY_OTHER') }}</span>
            @endif
          </td>
          <td>
            {{-- the displayed buttons have been decided by the controller (bookable,
                 appointmentId) according to the user's role. "Book" is a simple
                 link: it reopens this page with the booking window of this slot --}}
            @if ($row->bookable)
            <a class="btn btn-sm btn-outline-success" href="{{ $row->bookUrl }}">{{ __('SCHEDULE.BOOK') }}</a>
            @endif
            {{-- "Cancel" MODIFIES data: it is therefore a POST --}}
            @if ($row->appointmentId)
            <form method="post" action="{{ route('schedule.cancel') }}" class="m-0"
                  data-confirmation="{{ __('SCHEDULE.CANCEL_CONFIRM') }}">
              @csrf
              <input type="hidden" name="appointmentId" value="{{ $row->appointmentId }}">
              <input type="hidden" name="doctorId" value="{{ $doctorId }}">
              <input type="hidden" name="day" value="{{ $day }}">
              <button type="submit" class="btn btn-sm btn-outline-danger">{{ __('SCHEDULE.CANCEL_APPOINTMENT') }}</button>
            </form>
            @endif
          </td>
        </tr>
        @endforeach
      </tbody>
    </table>
    @else
    <p class="text-muted mb-0">{{ __('SCHEDULE.NO_SLOTS') }}</p>
    @endif
  </div>
  @else
  <p class="text-muted">{{ __('SCHEDULE.EMPTY_STATE') }}</p>
  @endif

  {{-- 3. the booking window, only if the URL contains &book=... --}}
  @if ($booking)
  @include('fragments.booking')
  @endif
@endsection

Die Hauptseite. Drei Bereiche: die Auswahl eines Arztes und eines Tages, der Terminkalender und das Buchungsfenster.

  • Zeilen 15–34: Auswahl eines Arztes und eines Tages: ein GET-Formular (Beispiel 17), das die Seite mit [?doctorId=...&day=...] in der URL neu lädt. Der Tag ist ein Feld vom Typ [type="date"]: Der Browser zeigt einen Kalender an und sendet das Datum im Format [yyyy-mm-dd], unabhängig davon, wie er es anzeigt ([26/09/2026] im Französischen);
  • Zeilen 37–42: für einen Patienten, der bereits einen anstehenden 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 gesetzt, wenn der Benutzer diesen Namen einsehen 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: „Absagen“ ändert Daten: Es ist ein POST-Formular (Beispiel 21) mit seinem Anti-CSRF-Token, dem abzusagenden 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 über die URL angefordert wird (und wenn das Zeitfenster buchbar ist).

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

{{-- =========================================================================
     resources/views/persons/list.blade.php - the list of the doctors OR of the
     clients (ADMIN). A single view for both: the keys of the labels specific to
     each one arrive in $keys, and $section ("doctors" or "clients") gives the
     start of the route names (see PersonsController).
     ========================================================================= --}}
@extends('layout')

@section('content')
  <div class="d-flex justify-content-between align-items-center mb-3">
    <h4 class="mb-0">{{ __($keys->title) }}</h4>
    <a class="btn btn-primary" href="{{ route("$section.addForm") }}">{{ __($keys->add) }}</a>
  </div>

  <div class="card p-3">
    @if ($persons->isNotEmpty())
    <table class="table table-hover align-middle mb-0">
      <thead>
        <tr>
          <th>{{ __('PERSONS.COLUMN_TITLE') }}</th>
          <th>{{ __('PERSONS.COLUMN_FIRSTNAME') }}</th>
          <th>{{ __('PERSONS.COLUMN_LASTNAME') }}</th>
          <th>{{ __('PERSONS.COLUMN_LOGIN') }}</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        @foreach ($persons as $person)
        <tr>
          <td>{{ $person->title }}</td>
          <td>{{ $person->first_name }}</td>
          <td>{{ $person->last_name }}</td>
          <td><code>{{ $person->account?->login }}</code></td>
          <td class="text-end">
            <div class="d-inline-flex gap-2">
              <a class="btn btn-sm btn-outline-primary"
                 href="{{ route("$section.editForm", ['id' => $person->id]) }}">{{ __('PERSONS.EDIT') }}</a>
              {{-- data-confirmation: a confirmation dialog will open before
                   the form is sent (see public/js/app.js) --}}
              <form method="post" action="{{ route("$section.delete", ['id' => $person->id]) }}" class="m-0"
                    data-confirmation="{{ __($keys->confirmDelete) }}">
                @csrf
                <button type="submit" class="btn btn-sm btn-outline-danger">{{ __('PERSONS.DELETE') }}</button>
              </form>
            </div>
          </td>
        </tr>
        @endforeach
      </tbody>
    </table>
    @else
    <p class="text-muted mb-0">{{ __($keys->empty) }}</p>
    @endif
  </div>
@endsection

Die Liste der Ärzte oder Kunden: Die jeweils spezifischen Beschriftungen sind Übersetzungsschlüssel ([$keys]), und die URL-Werte werden aus dem Namen des Abschnitts erzeugt ([route("$section.editForm", ['id' => ...])]: In einem von Anführungszeichen umschlossenen String wird [$section] durch seinen Wert ersetzt, [doctors] oder [clients]). [$person->account?->login]: das Login des Kontos, das mit der Liste geladen wurde ([with('account')], DAO-Schicht). [isNotEmpty()]: Die Collection ist nicht leer. Die Schaltfläche „Löschen“ ist ein POST-Formular mit Bestätigung.

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

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

     When the input is refused (empty field, login already taken...), the action sends
     the browser back to THIS page (redirection), and the view displays:
       - the values already typed (old(), in the x-field components);
       - the faulty fields outlined in red (Bootstrap class "is-invalid");
       - under a field refused by the validation, its message;
       - the error message of the page, AT THE BOTTOM of the page (errors fragment).
     ========================================================================= --}}
@extends('layout')

@section('content')
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4">
      <h5 class="card-title mb-3">{{ __($pageTitle) }}</h5>

      {{-- novalidate: we let the SERVER validate (it is the one that is authoritative); the
           browser's checks (required...) are only a convenience, that a
           user can always bypass --}}
      <form method="post" action="{{ $action }}" novalidate>
        @csrf
        @unless ($creating)
        {{-- the version of the displayed record: the optimistic lock --}}
        <input type="hidden" name="version" value="{{ old('version', $person->version) }}">
        @endunless

        {{-- title, first name, last name: component common to three forms --}}
        <x-person-fields :person="$person" />

        <h6 class="mt-4 text-muted">{{ __('PERSONS.ACCOUNT_SECTION') }}</h6>

        <div class="mb-3">
          <x-field name="login" :label="__('PERSONS.LOGIN_LABEL')" :value="$person?->account?->login"
                   max="30" autocomplete="off"
                   :help="__($creating ? 'PERSONS.LOGIN_HELP_CREATE' : 'PERSONS.LOGIN_HELP_EDIT')" />
        </div>

        <div class="mb-4">
          {{-- never pre-filled: the password never goes back to the browser --}}
          <x-field name="password" type="password" :label="__('PERSONS.PASSWORD_LABEL')" max="72"
                   autocomplete="new-password"
                   :help="__($creating ? 'PERSONS.PASSWORD_HELP_CREATE' : 'PERSONS.PASSWORD_HELP_EDIT')" />
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary">{{ __('PERSONS.SAVE') }}</button>
          <a class="btn btn-secondary" href="{{ $listUrl }}">{{ __('PERSONS.BACK') }}</a>
        </div>
      </form>
    </div>
  </div>
</div>
@endsection

Erstellen oder Bearbeiten eines Arztes oder eines Kunden.

  • Zeile 24: Das Attribut [novalidate] deaktiviert beim Absenden des Formulars die Browserprüfungen ([required], [maxlength] ...): Der Server validiert das Formular, und seine Validierung ist maßgeblich. Die Validatoren des Browsers sind lediglich eine Komfortfunktion, die jeder umgehen kann; ihre Deaktivierung ermöglicht es hier, die Meldungen des Servers zu sehen;
  • Zeilen 26–29: [@unless] („es sei denn“) ist das Gegenteil von [@if]. Bei einer Änderung wird die Version des Datensatzes (das optimistische Sperren) in einem versteckten Feld abgelegt;
  • Zeile 32: Anrede, Vorname und Nachname, mit den Werten der Person vorausgefüllt;
  • Zeilen 37–44: der Benutzername, mit dem Benutzernamen des Kontos vorausgefüllt ([$person?->account?->login]: zwei verkettete Null-Safe-Operatoren) und das Passwort, das nie vorausgefüllt wird. Ihre Tooltips unterscheiden sich bei der Erstellung („Standardmäßig der Nachname in Kleinbuchstaben“) und bei der Bearbeitung („Leer lassen, um es unverändert zu behalten“).

11.18.3.5. resources/views/registration.blade.php

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

@section('content')
@php($min = App\Http\Requests\PersonFieldsRequest::PASSWORD_MIN)
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4">
      <h5 class="card-title mb-1">{{ __('REGISTRATION.TITLE') }}</h5>
      <p class="text-muted small mb-3">{{ __('REGISTRATION.INTRO') }}</p>

      <form method="post" action="{{ route('registration') }}" novalidate>
        @csrf
        <x-person-fields />

        <h6 class="mt-4 text-muted">{{ __('PERSONS.ACCOUNT_SECTION') }}</h6>

        <div class="mb-3">
          <x-field name="login" :label="__('PERSONS.LOGIN_LABEL')" max="30" autocomplete="username" required
                   :help="__('REGISTRATION.LOGIN_HELP')" />
        </div>

        <div class="row g-3 mb-3">
          <div class="col-sm-6">
            <x-field name="password" type="password" :label="__('PERSONS.PASSWORD_LABEL')" max="72"
                     autocomplete="new-password" required :help="__('REGISTRATION.PASSWORD_HELP', ['min' => $min])" />
          </div>
          <div class="col-sm-6">
            <x-field name="password_confirmation" type="password" :label="__('ACCOUNT.CONFIRMATION_LABEL')"
                     max="72" autocomplete="new-password" required />
          </div>
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary">{{ __('REGISTRATION.SUBMIT') }}</button>
          <a class="btn btn-secondary" href="{{ route('login') }}">{{ __('REGISTRATION.BACK_TO_LOGIN') }}</a>
        </div>
      </form>
    </div>
  </div>
</div>
@endsection

Erstellung eines Patientenkontos: die Identitätsfelder (ein leeres Formular), gefolgt von Benutzername, Passwort und Passwortbestätigung, die erforderlich sind. [@php($min = ...)]: die Kurzform von [@php] für eine einzelne Anweisung. Der Hilfetext zum Passwort gibt die Mindestlänge an: [__('REGISTRATION.PASSWORD_HELP', ['min' => $min])], „Mindestens 6 Zeichen.“ Hier gibt es kein CAPTCHA: Diese Seite erreichen Sie nur nach Eingabe des CAPTCHAs auf der Login-Seite.

11.18.3.6. resources/views/area.blade.php

{{-- =========================================================================
     resources/views/area.blade.php - "My area": the home page of the patient
     (USER role), displayed right after their login.
       - two options: [Manage my account] and [View a schedule];
       - their upcoming appointment, if they have one, with the means to cancel it.
     ========================================================================= --}}
@extends('layout')

@section('content')
  <h4 class="mb-3">{{ __('AREA.HELLO', ['name' => $patient]) }}</h4>

  <div class="row g-3 mb-4">
    <div class="col-sm-6">
      <a class="card p-4 h-100 text-decoration-none option-card" href="{{ route('account') }}">
        <h5 class="mb-1">{{ __('AREA.MANAGE_ACCOUNT') }}</h5>
        <span class="text-muted">{{ __('AREA.MANAGE_ACCOUNT_HELP') }}</span>
      </a>
    </div>
    <div class="col-sm-6">
      <a class="card p-4 h-100 text-decoration-none option-card" href="{{ route('schedule') }}">
        <h5 class="mb-1">{{ __('AREA.VIEW_SCHEDULE') }}</h5>
        <span class="text-muted">{{ __('AREA.VIEW_SCHEDULE_HELP') }}</span>
      </a>
    </div>
  </div>

  <div class="card p-3">
    <h5>{{ __('AREA.MY_APPOINTMENT') }}</h5>
    {{-- normally only one (rule "one upcoming appointment at a time"), but the
         page can display several. @forelse ... @empty: a loop, and what
         is displayed if the list is empty; $loop->last: last element? --}}
    @forelse ($appointments as $appointment)
    <div @class(['d-flex flex-wrap justify-content-between align-items-center gap-2 py-2',
                 'border-bottom' => ! $loop->last])>
      <div>
        <div class="fw-semibold">{{ $appointment->day }}, {{ $appointment->time }}</div>
        <div class="text-muted">
          <span>{{ $appointment->doctor }}</span> -
          <a href="{{ $appointment->scheduleUrl }}">{{ __('AREA.SEE_IN_SCHEDULE') }}</a>
        </div>
      </div>
      <form method="post" action="{{ route('area.cancel') }}" class="m-0"
            data-confirmation="{{ __('SCHEDULE.CANCEL_CONFIRM') }}">
        @csrf
        <input type="hidden" name="appointmentId" value="{{ $appointment->id }}">
        <button type="submit" class="btn btn-outline-danger">{{ __('AREA.CANCEL_APPOINTMENT') }}</button>
      </form>
    </div>
    @empty
    <p class="text-muted mb-0">{{ __('AREA.NO_APPOINTMENT') }}</p>
    @endforelse
  </div>
@endsection

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

  • Zeilen 32–51: [@forelse] (Beispiel 14) ist eine Schleife, gefolgt ([@empty]) von dem, was bei einer leeren Liste angezeigt wird. Normalerweise hat ein Patient höchstens einen anstehenden Termin; die Seite ist jedoch so konzipiert, dass sie mehrere Termine anzeigen kann. [$loop->last] (Beispiel 14): Das letzte Element hat kein Trennzeichen;
  • jeder Termin hat ein Absageformular (POST, mit Bestätigung), das nur seine ID sendet: Der Server prüft, ob er zum angemeldeten Patienten gehört.

11.18.3.7. resources/views/account.blade.php

{{-- =========================================================================
     resources/views/account.blade.php - "Manage my account" (USER role).
     Two independent forms on the same page:
       1. the modification (identity, login, optional new password);
       2. the deletion of the account - which also cancels its appointments.
     Both require the CURRENT password (current_password field).
     ========================================================================= --}}
@extends('layout')

@section('content')
@php($min = App\Http\Requests\PersonFieldsRequest::PASSWORD_MIN)
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">

    {{-- 1. modification --}}
    <div class="card p-4 mb-4">
      <h5 class="card-title mb-3">{{ __('MY_ACCOUNT.TITLE') }}</h5>

      <form method="post" action="{{ route('account.edit') }}" novalidate>
        @csrf
        <input type="hidden" name="version" value="{{ old('version', $patient->version) }}">

        <x-person-fields :person="$patient" />

        <h6 class="mt-4 text-muted">{{ __('PERSONS.ACCOUNT_SECTION') }}</h6>

        <div class="mb-3">
          <x-field name="login" :label="__('PERSONS.LOGIN_LABEL')" :value="$patient->account->login"
                   max="30" autocomplete="username" required />
        </div>

        <div class="row g-3 mb-3">
          <div class="col-sm-6">
            <x-field name="password" type="password" :label="__('MY_ACCOUNT.NEW_PASSWORD_LABEL')" max="72"
                     autocomplete="new-password" :help="__('PERSONS.PASSWORD_HELP_EDIT')" />
          </div>
          <div class="col-sm-6">
            <x-field name="password_confirmation" type="password" :label="__('ACCOUNT.CONFIRMATION_LABEL')"
                     max="72" autocomplete="new-password" />
          </div>
        </div>

        <div class="mb-4">
          <x-field name="current_password" type="password" :label="__('MY_ACCOUNT.CURRENT_PASSWORD_LABEL')"
                   max="72" autocomplete="current-password" required
                   :help="__('MY_ACCOUNT.CURRENT_PASSWORD_HELP')" />
        </div>

        <div class="d-flex gap-2">
          <button type="submit" class="btn btn-primary">{{ __('PERSONS.SAVE') }}</button>
          <a class="btn btn-secondary" href="{{ route('area') }}">{{ __('MY_ACCOUNT.BACK') }}</a>
        </div>
      </form>
    </div>

    {{-- 2. deletion. The password field has the same NAME as that of the first
         form (current_password), but another id: two elements of the same
         page cannot have the same id --}}
    <div class="card p-4 border-danger">
      <h5 class="card-title text-danger mb-1">{{ __('MY_ACCOUNT.DELETE_TITLE') }}</h5>
      <p class="text-muted small">{{ __('MY_ACCOUNT.DELETE_HELP') }}</p>
      <form method="post" action="{{ route('account.delete') }}" class="d-flex flex-wrap gap-2 align-items-end"
            data-confirmation="{{ __('MY_ACCOUNT.DELETE_CONFIRM') }}">
        @csrf
        <div class="flex-grow-1">
          <label class="form-label" for="delete_password">{{ __('MY_ACCOUNT.CURRENT_PASSWORD_LABEL') }}</label>
          <input id="delete_password" name="current_password" type="password" maxlength="72"
                 autocomplete="current-password" required class="form-control">
        </div>
        <button type="submit" class="btn btn-danger">{{ __('MY_ACCOUNT.DELETE_SUBMIT') }}</button>
      </form>
    </div>

  </div>
</div>
@endsection

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

  • Zeilen 19–53: die Bearbeitung: die Version (optimistisches Sperren), Identitätsfelder, Benutzername, neues Passwort und seine Bestätigung (optional) sowie das aktuelle Passwort (erforderlich);
  • Zeilen 62–71: Löschen des Kontos, mit eigenem Feld für das aktuelle Passwort und mit Bestätigung. Das Feld hat denselben Namen wie das im ersten Formular ([current_password]: Es wird immer nur ein Formular gesendet), aber nicht dieselbe ID: Zwei Elemente einer Seite dürfen nicht dieselbe ID haben, wie das Attribut [for] eines Labels zeigt.

11.18.3.8. resources/views/error.blade.php

{{-- =========================================================================
     resources/views/error.blade.php - the error page (400, 403, 404, 419,
     500...), built by bootstrap/app.php (withExceptions).
     ========================================================================= --}}
@extends('layout')

@section('content')
<div class="row justify-content-center">
  <div class="col-md-8 col-lg-6">
    <div class="card p-4 text-center">
      <h1 class="display-4 text-danger">{{ $code }}</h1>
      <p class="lead">{{ __($message) }}</p>
      <div><a class="btn btn-primary" href="{{ route('home') }}">{{ __('ERROR_PAGE.BACK') }}</a></div>
    </div>
  </div>
</div>
@endsection

Die Fehlerseite, erzeugt von [bootstrap/app.php]: der HTTP-Code, die Meldung und ein Link zur Startseite ([/], die zur Startseite der Rolle oder zur Login-Seite weiterleitet).

11.19. 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.19.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 am Seitenende auf hellrosa Hintergrund
   (siehe resources/views/fragments/errors.blade.php).
   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 je
   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 mit 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 Terminkalender 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 Terminkalender mit 12 Zeitfenstern), bleibt der Bereich am unteren Fensterrand verankert, statt unter der Bildlaufleiste zu verschwinden; ist die Seite kurz, bleibt er an seinem Platz, 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.19.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
// Komfortfunktion hinzu: Vor dem Absenden eines Formulars mit dem Attribut
// data-confirmation="..." fragt ein modaler Dialog "Are you sure?" ab
// (der Dialog selbst liegt in der Seite: resources/views/fragments/confirmation.blade.php).
// Ist JavaScript deaktiviert, wird das Formular einfach ohne
// Bestätigung abgesendet - nichts geht kaputt (Prinzip "Progressive Enhancement").
//
// Warum nicht window.confirm()? Sein Fenster lässt sich nicht gestalten, und seine
// Buttons 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, dem beim Schließen der Fokus zurückgegeben wird

  function open(form) {
    pendingForm = form;
    previousFocus = document.activeElement;
    // textContent (und nicht innerHTML): Die Meldung wird als TEXT angezeigt,
    // nie als HTML interpretiert
    message.textContent = form.dataset.confirmation;
    modal.classList.remove('d-none');
    // der Fokus geht auf "No": Ein unbedachtes Drücken der 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 Buttons 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 ab, OHNE das Ereignis
      // 'submit' erneut auszulösen: keine neue Bestätigungsanfrage
      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 INNERHALB des Dialogs
  //    (sonst ginge der Fokus auf die ausgegraute Seite dahinter)
  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 bietet zusätzlichen 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 gesendet: Nichts geht kaputt (Prinzip der progressiven Verbesserung).

  • Zeilen 15–21: 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 auf der Seite kein Bestätigungsfenster, tut es nichts;
  • Zeilen 26–35: Öffnen des Fensters: Das Formular, das bei Bestätigung gesendet 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–50: 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 ganze Fenster: [closest('[data-action]')] identifiziert die angeklickte Schaltfläche oder das Element, das sie enthält. „Ja“ sendet das Formular über [form.submit()] ab, was das Ereignis nicht [submit] 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 und mit Screenreadern navigieren.