Skip to content

9. Schichtenarchitektur und Datenzugriff

Die bisherigen Beispiele speicherten ihre Daten im Speicher oder im Cache. Eine reale Anwendung speichert sie in einer Datenbank und ist in Schichten organisiert (siehe das Diagramm in der Einleitung):

  • die Web-Schicht (Controller, Views): liest die Anfrage, ruft die Geschäftsschicht auf, wählt die View aus;
  • die Geschäftsschicht: Geschäftsregeln;
  • die DAO-Schicht (*Data Access Object*): Datenbankabfragen.

Jede Schicht kennt nur die Schicht unter ihr, und von dieser möglichst wenige Details: Die Web-Schicht weiß nichts von der SQL-Schicht, und die Geschäftsschicht weiß nichts von der HTML-Schicht. Diese Trennung macht jede Schicht leichter verständlich, testbar und weiterentwickelbar. Beispiel 28 wendet dies auf die Verwaltung einer Personenliste an: Es ist, in kleinerem Maßstab, die Verwaltung der Ärzte und Klienten aus der Fallstudie.

In [PHP] ist der Datenbankzugriff über mehrere Schichten organisiert:

  • die Erweiterung PDO (*PHP Data Objects*) von [PHP] definiert eine für alle DBMS-Module gemeinsame Schnittstelle: eine Verbindung öffnen, einen SQL-Befehl ausführen und Zeilen lesen. Jedes DBMS hat seinen eigenen Treiber: [pdo_mysql] für [MySQL] (und [MariaDB]), der mit [PHP] mitgeliefert wird;
  • der Query Builder (*query builder*) von [Laravel] (Fassade [DB]) erstellt die SQL-Befehle aus Methodenaufrufen ([where], [orderBy] ...), unabhängig vom DBMS, und verwaltet Verbindungen und Transaktionen;
  • Eloquent, der ORM (*Object-Relational Mapper*) von [Laravel], bildet Klassen (Modelle, wie sie von [Eloquent] definiert werden) auf Datenbanktabellen ab und wandelt die abgerufenen Zeilen in Objekte um. Er folgt dem sogenannten *Active-Record*-Muster: Jedes Objekt weiß, wie es sich selbst liest und speichert ([Person::find(1)], [$person->save()]).

Das entspricht [JDBC], [JPA] und [Hibernate] in [Java], [Entity Framework Core] in [C#] oder [SQLAlchemy] in [Python]. Beachten Sie eine Folge der Funktionsweise von [PHP]: Da nichts über die Anfrage hinaus erhalten bleibt, öffnet jede Anfrage ihre eigene Verbindung zur Datenbank (bei ihrer ersten SQL-Abfrage) und schließt sie am Ende. Es gibt keinen Verbindungspool wie in [Java] oder [Python]; das Öffnen einer Verbindung zu [MySQL] auf demselben Rechner dauert nur den Bruchteil einer Millisekunde.

Dieses Beispiel erfordert einen laufenden [MySQL] -Server (oder [MariaDB]-Server): Der Anhang erklärt, wie Sie einen mit [Laragon] installieren.

9.1. Beispiel 28: Eine Personalverwaltung in drei Schichten

28-layers/
├── app/
│   ├── Dao/
│   │   └── PersonsDao.php
│   ├── Http/
│   │   ├── Controllers/
│   │   │   └── PersonsController.php
│   │   └── Requests/
│   │       └── PersonRequest.php
│   ├── Business/
│   │   ├── PersonData.php
│   │   ├── BusinessException.php
│   │   └── PersonsBusiness.php
│   └── Models/
│       └── Person.php
├── bootstrap/
│   └── app.php
├── database/
│   └── dbpersons.sql
├── public/
│   ├── css/
│   │   └── styles.css
│   └── js/
│       └── app.js
├── resources/
│   └── views/
│       ├── components/
│       │   └── field.blade.php
│       ├── fragments/
│       │   └── confirmation.blade.php
│       ├── layout.blade.php
│       └── persons/
│           ├── form.blade.php
│           └── list.blade.php
├── routes/
│   └── web.php
└── ...

9.1.1. Die Datenbank

Die Datenbank [dbpersons] wird durch das SQL-Skript erstellt. Mit [Laragon] können Sie es zum Beispiel im Werkzeug [HeidiSQL] ausführen (Menü Datei / SQL-Datei ausführen) oder auf der Kommandozeile im Ordner des Beispiels:

mysql -u root < database/dbpersons.sql

Die Datei [database/dbpersons.sql]:

-- Datenbank von Beispiel 28: eine einzige Tabelle, [persons]
-- das Skript ist in UTF-8 geschrieben
SET NAMES utf8mb4;
DROP DATABASE IF EXISTS dbpersons;
CREATE DATABASE dbpersons CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbpersons;

CREATE TABLE persons (
  id INT NOT NULL AUTO_INCREMENT,
  -- die Version der Zeile, bei jeder Änderung erhöht (siehe DAO-Schicht)
  version INT NOT NULL DEFAULT 0,
  first_name VARCHAR(30) NOT NULL,
  last_name VARCHAR(30) NOT NULL,
  age INT NOT NULL,
  PRIMARY KEY (id),
  -- zwei Personen können nicht denselben Vor- und Nachnamen haben
  CONSTRAINT unq_persons_first_name_last_name UNIQUE (first_name, last_name)
) ENGINE = InnoDB;

INSERT INTO persons (first_name, last_name, age) VALUES
  ('Marie', 'Pélissier', 42),
  ('Jacques', 'Bromard', 35),
  ('Philippe', 'Jandot', 58);
  • Zeile 3: Das Skript ist in [UTF-8] geschrieben; dies wird dem Server mitgeteilt, damit die Akzente in den Daten ([Pélissier]) erhalten bleiben;
  • Zeile 5: Der Zeichensatz [utf8mb4] akzeptiert alle Zeichen (Akzente, Emojis usw.). Die Kollation [utf8mb4_unicode_ci] vergleicht Zeichenketten ohne Rücksicht auf Groß- und Kleinschreibung oder Akzente: Für [MySQL] sind [pelissier], und [Pélissier] gleich;
  • Zeile 11: eine Versionsnummer, die bei jeder Änderung der Zeile erhöht wird (siehe „optimistisches Sperren“ weiter unten);
  • Zeile 17: eine benannte Eindeutigkeitsbedingung: Die Datenbank lässt nicht zwei Personen mit demselben Vor- und Nachnamen zu. Der Name wird dazu dienen, den Fehler zu identifizieren.

[Laravel] kann die Tabellen auch selbst mithilfe von Migrationen erstellen: [PHP]-Klassen, die Schritt für Schritt die Erstellung und die Änderungen jeder Tabelle beschreiben (Befehl [php artisan migrate]). Wir pflegen ein SQL-Skript, das allen Versionen der Fallstudie gemeinsam ist und genau zeigt, was die Datenbank enthält.

9.1.2. Konfiguration

Die Datenbankverbindung wird in der Datei [.env] definiert:

# die Datenbankverbindung: das DBMS MySQL auf diesem Rechner (127.0.0.1), Port 3306,
# die Datenbank dbpersons, der Benutzer root ohne Passwort (Einstellungen von Laragon)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=dbpersons
DB_USERNAME=root
DB_PASSWORD=
# true: die an die Datenbank gesendeten SQL-Anweisungen werden in der Konsole angezeigt
DB_LOG=false

[DB_CONNECTION] verweist auf eine der Verbindungen, die in der Konfiguration von [Laravel] beschrieben sind ([mysql], [mariadb], [pgsql], [sqlite], [sqlsrv]); die folgenden Zeilen konfigurieren sie. Hat Ihr Server ein Passwort, tragen Sie es in [DB_PASSWORD] ein. Die Verbindung [mysql] kommuniziert mit dem Server über [utf8mb4], den Zeichensatz der Datenbank. [DB_LOG] ist eine Variable, die wir definieren und die von [bootstrap/app.php] gelesen wird:

<?php
// bootstrap/app.php: die Anwendung von Beispiel 28

use Illuminate\Database\Events\QueryExecuted;
use Illuminate\Database\Events\TransactionBeginning;
use Illuminate\Database\Events\TransactionCommitted;
use Illuminate\Database\Events\TransactionRolledBack;
use Illuminate\Foundation\Application;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Event;

(require __DIR__.'/../../vendor/autoload.php')->addPsr4('App\\', __DIR__.'/../app/');

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        // die Route, die Bootstrap ausliefert (siehe Beispiel 15)
        then: fn () => require __DIR__.'/../../common/bootstrap.php')
    ->withMiddleware()
    ->withExceptions()
    ->booted(function () {
        // DB_LOG=true (Datei .env): jede SQL-Anweisung und jeder Schritt einer
        // Transaktion wird in der Konsole des Servers angezeigt
        if (env('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'));
        }
    })
    ->create();
  • Zeilen 24–30: Ist [DB_LOG] gleich [true], wird jeder SQL-Befehl in der Konsole angezeigt. [DB::listen] registriert eine Funktion, die nach jedem SQL-Befehl mit einem [QueryExecuted]-Objekt aufgerufen wird (Text des Befehls, seine Parameter und seine Dauer). [Event::listen] registriert eine Funktion, die für jedes Ereignis eines bestimmten Typs aufgerufen wird: [Laravel] meldet so unter anderem den Beginn, die Bestätigung und den Abbruch von Transaktionen. Ereignisse sind – neben der Middleware – eine weitere Möglichkeit, in die Arbeitsweise des Frameworks einzugreifen. (Wir lesen [env] der Kürze halber direkt; eine typische Anwendung würde eine Konfigurationsdatei verwenden; siehe Beispiel 25.)

Sonst ist nichts zu konfigurieren: Die Klassen der drei Schichten werden vom Container von [Laravel] erstellt, der in jede die darunterliegende Schicht injiziert (der Controller erhält die Geschäftsschicht, und die Geschäftsschicht erhält die DAO-Schicht).

9.1.3. Das Modell Person

<?php
// app/Models/Person.php: eine Zeile der Tabelle [persons], ein Eloquent-"Modell"

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

// Model: die Elternklasse der Entitäten von Eloquent, dem ORM von Laravel. Die Spalten
// der Tabelle werden ohne jede Deklaration zu Eigenschaften des Objekts ($p->last_name)
class Person extends Model
{
    // der Name der Tabelle (Eloquent würde ihn aus dem Namen der Klasse ableiten: people)
    protected $table = 'persons';

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

    // die Spalten, die per Mass Assignment befüllt werden können: new Person([...]), update([...])
    protected $fillable = ['first_name', 'last_name', 'age'];

    // die Typumwandlungen, Spalte für Spalte
    protected function casts(): array
    {
        return ['age' => 'integer', 'version' => 'integer'];
    }
}
  • Zeile 10: Ein Modell mit dem Namen [Eloquent] erbt von der Klasse [Model]. Die Spalten der Tabelle werden nicht deklariert: [Eloquent] liest die Zeile, und jede Spalte wird zu einer Eigenschaft des Objekts ([$p->last_name], [$p->version]). Der Primärschlüssel ist standardmäßig die Spalte [id], die von der Datenbank erzeugt wird ([AUTO_INCREMENT]);
  • Zeile 13: die der Klasse zugeordnete Tabelle. [Eloquent] würde sie selbst aus dem Klassennamen ableiten, indem es ihn in den Plural setzt (im Englischen);
  • Zeile 16: Standardmäßig pflegt [Eloquent] zwei Spalten, [created_at] und [updated_at], von denen es annimmt, dass sie in jeder Tabelle vorhanden sind. Unsere hat sie nicht;
  • Zeile 19: die Spalten, die „gesammelt“ aus einem Array befüllt werden können ([Person::create([...])]). Das ist eine Vorsichtsmaßnahme: Ein Array aus einem Formular könnte andere Spalten enthalten ([version], [id] ...), die wir auf diese Weise nicht befüllen lassen wollen;
  • Zeilen 22–25: Typumwandlungen: Der Treiber wandelt bestimmte numerische Spalten in Zeichenketten um; [casts] stellt sicher, dass es ganze Zahlen sind. Es gibt Umwandlungen für Boolesche Werte, Datumswerte ([Carbon]-Objekte), Dezimalzahlen, Arrays (eine JSON-Spalte) ...

9.1.4. Die DAO-Schicht

<?php
// app/Dao/PersonsDao.php: die DAO-Schicht, Abfragen, keine Geschäftsregel

namespace App\Dao;

use App\Business\PersonData;
use App\Models\Person;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Support\Facades\DB;

class PersonsDao
{
    // SELECT * FROM persons ORDER BY last_name, first_name
    public function list(): Collection
    {
        return Person::orderBy('last_name')->orderBy('first_name')->get();
    }

    // SELECT * FROM persons WHERE id = ? LIMIT 1; null, falls die Person nicht existiert
    public function read(int $id): ?Person
    {
        return Person::find($id);
    }

    // eine Person mit denselben Vor- und Nachnamen, außer [$exceptId]:
    // SELECT * FROM persons WHERE first_name = ? AND last_name = ? AND id <> ? LIMIT 1
    public function namesake(string $firstName, string $lastName, int $exceptId = 0): ?Person
    {
        return Person::where('first_name', $firstName)->where('last_name', $lastName)
            ->where('id', '<>', $exceptId)->first();
    }

    // INSERT INTO persons (first_name, last_name, age) VALUES (?, ?, ?); die Datenbank erzeugt
    // die id, die Eloquent im Objekt speichert
    public function add(PersonData $data): Person
    {
        return Person::create(['first_name' => $data->firstName, 'last_name' => $data->lastName,
            'age' => $data->age]);
    }

    // das OPTIMISTISCHE SPERREN: UPDATE ... SET ..., version = version + 1
    // WHERE id = ? AND version = ?; liefert die Anzahl der geänderten Zeilen (0: die
    // Zeile wurde seit dem Lesen geändert oder gelöscht)
    public function edit(int $id, int $version, PersonData $data): int
    {
        return Person::where('id', $id)->where('version', $version)->update([
            'first_name' => $data->firstName, 'last_name' => $data->lastName, 'age' => $data->age,
            // DB::raw: ein SQL-Ausdruck, der unverändert in die SQL-Anweisung geschrieben wird
            'version' => DB::raw('version + 1'),
        ]);
    }

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

Die DAO-Schicht enthält nur Abfragen, keine Geschäftslogik. Jede Methode verwendet die Verbindung der aktuellen Anfrage und nimmt an der geöffneten Transaktion teil, falls es eine gibt, die von der Geschäftsschicht begonnen wurde.

  • Zeilen 14–17: [Person::orderBy(...)] beginnt eine Abfrage auf der Tabelle der Personen; die Methoden werden verkettet ([orderBy] fügt eine Sortierung hinzu), und [get()] führt die Abfrage aus. Das Ergebnis ist eine [Eloquent]-Collection (Beispiel 03) von [Person]-Objekten;
  • Zeilen 20–23: [find]: Abruf über den Primärschlüssel oder [null];
  • Zeilen 27–31: [where(column, value)] fügt eine Gleichheitsbedingung hinzu; [where(column, operator, value)] fügt eine beliebige Bedingung hinzu. Die Werte werden der Datenbank als Parameter des SQL-Befehls übergeben (die [?]-Platzhalter) und nie in dessen Text kopiert, was SQL-Injection unmöglich macht. [first()] gibt die erste Zeile zurück ([LIMIT 1]) oder [null];
  • Zeilen 35–39: [Person::create] erstellt das Objekt aus einem Array (im Rahmen von [$fillable]) und fügt es in die Datenbank ein; [Eloquent] speichert die von der Datenbank erzeugte ID im Objekt;
  • Zeilen 44–51: die Aktualisierung mit einem optimistischen Sperren. Der Befehl [UPDATE] hat zwei Bedingungen: die ID der Person und die Version, die beim Anzeigen des Formulars gelesen wurde. Er erhöht die Version um 1: [DB::raw] fügt einen SQL-Ausdruck unverändert ein ([version + 1]), statt eines Wertes. Hat eine andere Anfrage die Zeile in der Zwischenzeit geändert, hat sich ihre Version geändert, und [UPDATE] ändert keine Zeile: [update] gibt die Anzahl der geänderten Zeilen zurück, die in diesem Fall 0 ist. Das ist das Prinzip des optimistischen Sperrens: Nichts wird gesperrt, aber gleichzeitige Änderungen werden erkannt. ([Eloquent] verwaltet im Gegensatz zu [Hibernate] oder [SQLAlchemy] selbst keine Versionsnummer: Die Bedingung wird von Hand geschrieben.);
  • Zeilen 54–57: ein [DELETE], auf dieselbe Weise aufgebaut ([whereKey]: eine Bedingung auf dem Primärschlüssel).

9.1.5. Die Geschäftsschicht

<?php
// app/Business/PersonData.php: die Daten einer Person, wie die Web-Schicht sie weitergibt

namespace App\Business;

readonly class PersonData
{
    public function __construct(
        public string $firstName,
        public string $lastName,
        public int $age,
    ) {
    }
}

Die Daten einer Person, wie sie von der Web-Schicht an die Geschäftsschicht übergeben werden: ein einfaches Objekt ohne Bezug zu [Laravel].

<?php
// app/Business/BusinessException.php: eine Geschäftsregel lehnt die Operation ab; die
// Meldung ist für den Benutzer bestimmt

namespace App\Business;

use RuntimeException;

class BusinessException extends RuntimeException
{
}

Eine Exception-Klasse, die für die Geschäftsschicht spezifisch ist: Eine Geschäftsregel lehnt den Vorgang ab, und die Exception-Meldung ist für den Benutzer bestimmt. Sie erbt von [RuntimeException] , ohne etwas hinzuzufügen – nur ihr Name zählt.

<?php
// app/Business/PersonsBusiness.php: die GESCHÄFTSSCHICHT, die Geschäftsregeln und nur
// sie. Jede schreibende Operation ist eine TRANSAKTION: bestätigt (COMMIT), wenn die
// Funktion normal endet, verworfen (ROLLBACK), wenn eine Exception aus ihr herauskommt

namespace App\Business;

use App\Dao\PersonsDao;
use App\Models\Person;
use Exception;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\QueryException;
use Illuminate\Support\Facades\DB;

class PersonsBusiness
{
    private const NAMESAKE = 'A person already has these first and last names.';

    private const MODIFIED = 'This record has been modified meanwhile: reload it.';

    private const UNKNOWN = 'This person does not exist (anymore).';

    public function __construct(private PersonsDao $dao)
    {
    }

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

    public function read(int $id): Person
    {
        return $this->dao->read($id) ?? throw new BusinessException(self::UNKNOWN);
    }

    public function add(PersonData $data): Person
    {
        try {
            // DB::transaction: die Funktion wird in einer Transaktion ausgeführt
            return DB::transaction(function () use ($data) {
                // Regel 1: keine zwei Personen mit denselben Vor- und Nachnamen
                if ($this->dao->namesake($data->firstName, $data->lastName)) {
                    throw new BusinessException(self::NAMESAKE);
                }
                return $this->dao->add($data);
            });
        } catch (QueryException $e) {
            throw self::translate($e);
        }
    }

    public function edit(int $id, int $version, PersonData $data): Person
    {
        try {
            return DB::transaction(function () use ($id, $version, $data) {
                $person = $this->read($id);
                // Regel 2: wir ändern keinen Datensatz, der zwischenzeitlich von jemand anderem geändert wurde
                if ($person->version !== $version) {
                    throw new BusinessException(self::MODIFIED);
                }
                if ($this->dao->namesake($data->firstName, $data->lastName, $id)) {
                    throw new BusinessException(self::NAMESAKE);
                }
                // das UPDATE "WHERE id = ... AND version = ..." hat keine Zeile geändert:
                // eine andere Anfrage hat den Datensatz seit dem Lesen geändert
                if ($this->dao->edit($id, $version, $data) === 0) {
                    throw new BusinessException(self::MODIFIED);
                }
                // der erneut gelesene Datensatz: seine neuen Werte und seine neue Version
                return $this->read($id);
            });
        } catch (QueryException $e) {
            throw self::translate($e);
        }
    }

    public function delete(int $id): Person
    {
        return DB::transaction(function () use ($id) {
            $person = $this->read($id);
            $this->dao->delete($id);
            return $person;
        });
    }

    // zwei gleichzeitige Hinzufügungen: die Eindeutigkeitsbedingung der Datenbank hat die
    // zweite abgelehnt; getMessage() enthält die Meldung von MySQL mit dem Namen der Bedingung
    private static function translate(QueryException $e): Exception
    {
        if (str_contains($e->getMessage(), 'unq_persons_first_name_last_name')) {
            return new BusinessException(self::NAMESAKE, previous: $e);
        }
        return $e;
    }
}
  • Zeilen 17–21: die Meldungen der Geschäftsregeln;
  • Zeilen 32–35: Eine nicht vorhandene Person ist ein Geschäftsfehler. Der Operator [??] akzeptiert auf der rechten Seite einen [throw]-Ausdruck: Ist die Person [null], wird die Exception ausgelöst;
  • Zeilen 37–51: Regel Nr. 1: Keine zwei Personen dürfen denselben Vor- und Nachnamen haben. [DB::transaction] führt die Funktion innerhalb einer Transaktion aus: Wird die Funktion normal beendet, wird die Transaktion bestätigt ([COMMIT]), und [DB::transaction] gibt den Wert der Funktion zurück; wird eine Exception ausgelöst, wird die Transaktion zurückgerollt ([ROLLBACK]): Keine der innerhalb der Funktion vorgenommenen Änderungen bleibt erhalten, und die Exception wird weitergereicht. Die Geschäftsschicht bestimmt so den Umfang der Transaktionen: ein Geschäftsvorgang, eine Transaktion. Die Regel wird vor dem Schreiben überprüft, und eine [BusinessException] wird ausgelöst, wenn sie nicht eingehalten wird. Diese Prüfung genügt aber nicht: Zwei gleichzeitige Anfragen könnten beide feststellen, dass es kein Duplikat gibt, und dann beide die Daten einfügen. Die Eindeutigkeitsbedingung der Datenbank lehnt dann das zweite [INSERT] ab, und [Laravel] löst eine [QueryException] aus, die die Methode [translate] in dieselbe [BusinessException] umwandelt. Die Datenbank ist die letzte Verteidigungslinie;
  • Zeilen 53–76: Regel Nr. 2: Ein Datensatz, der in der Zwischenzeit von jemand anderem geändert wurde, darf nicht geändert werden. Das Änderungsformular trägt die Version des gelesenen Datensatzes (in einem versteckten Feld); weicht sie von der aktuellen Version ab, hat sich der Datensatz seit seiner Anzeige geändert. Auch hier erkennt die Datenbank (über das optimistische Sperren in der DAO-Schicht), wenn eine gleichzeitige Änderung zwischen dem Lesen und dem [UPDATE]-Vorgang auftritt: der [UPDATE]-Vorgang ändert dann keine Zeile. Der Datensatz wird dann mit seinen neuen Werten erneut gelesen;
  • Zeilen 78–85: Beim Löschen wird die Person für die Bestätigungsmeldung als gelöscht markiert;
  • Zeilen 89–95: [getMessage()] enthält die Meldung von [MySQL], einschließlich des Namens der verletzten Bedingung. Ein anderer Fehler wird unverändert weitergegeben: Das ist kein Geschäftsfehler, sondern ein Programmierfehler. Der Parameter mit dem Namen [previous] hängt die ursprüngliche Exception für das Log an die neue an.

9.1.6. Die Web-Schicht

<?php
// app/Http/Requests/PersonRequest.php: die Felder des Formulars und ihre Einschränkungen (siehe Beispiel 19)

namespace App\Http\Requests;

use App\Business\PersonData;
use Illuminate\Foundation\Http\FormRequest;

class PersonRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'first_name' => 'required|max:30',
            'last_name' => 'required|max:30',
            'age' => 'required|integer|between:0,150',
            // die Version des Datensatzes, getragen von einem versteckten Feld (nur beim Bearbeiten)
            'version' => 'nullable|integer',
        ];
    }

    public function messages(): array
    {
        return [
            'first_name.required' => 'The first name is required.',
            'first_name.max' => '30 characters at most.',
            'last_name.required' => 'The last name is required.',
            'last_name.max' => '30 characters at most.',
            'age.required' => 'The age is required.',
            'age.integer' => 'The age must be an integer.',
            'age.between' => 'The age must be between 0 and 150.',
        ];
    }

    // die validierten Daten für die Geschäftsschicht
    public function personData(): PersonData
    {
        return new PersonData($this->validated('first_name'), $this->validated('last_name'),
            (int) $this->validated('age'));
    }
}

Der Form Request (Beispiel 19). Das versteckte Feld [version] ist optional (Formular zum Hinzufügen). Die Methode [personData] gibt die validierten Daten in dem Format zurück, das die Geschäftsschicht erwartet.

<?php
// app/Http/Controllers/PersonsController.php: die WEB-Schicht; sie kennt nur die Geschäftsschicht

namespace App\Http\Controllers;

use App\Http\Requests\PersonRequest;
use App\Business\BusinessException;
use App\Business\PersonsBusiness;
use Illuminate\Http\RedirectResponse;
use Illuminate\View\View;

class PersonsController
{
    public function __construct(private PersonsBusiness $business)
    {
    }

    public function home(): RedirectResponse
    {
        return redirect()->route('persons.list');
    }

    public function list(): View
    {
        return view('persons.list', ['persons' => $this->business->list()]);
    }

    public function addForm(): View
    {
        return view('persons.form', ['title' => 'Add a person',
            'action' => route('persons.add'), 'person' => null]);
    }

    // PersonRequest: ein ungültiges Formular kommt nicht bis hierher (siehe Beispiel 19)
    public function add(PersonRequest $request): RedirectResponse
    {
        try {
            $p = $this->business->add($request->personData());
        } catch (BusinessException $e) {
            // eine Geschäftsregel lehnt ab: zurück zum Formular, mit der Eingabe und der
            // Meldung am Seitenende
            return back()->withInput()->with('error', $e->getMessage());
        }
        return redirect()->route('persons.list')->with('success', "$p->first_name $p->last_name has been added.");
    }

    public function editForm(int $id): View|RedirectResponse
    {
        try {
            $p = $this->business->read($id);
        } catch (BusinessException $e) {
            return redirect()->route('persons.list')->with('error', $e->getMessage());
        }
        return view('persons.form', ['title' => 'Edit a person',
            'action' => route('persons.edit', $id), 'person' => $p]);
    }

    public function edit(PersonRequest $request, int $id): RedirectResponse
    {
        try {
            $p = $this->business->edit($id, (int) $request->validated('version'), $request->personData());
        } catch (BusinessException $e) {
            return back()->withInput()->with('error', $e->getMessage());
        }
        return redirect()->route('persons.list')->with('success', "$p->first_name $p->last_name has been edited.");
    }

    public function delete(int $id): RedirectResponse
    {
        try {
            $p = $this->business->delete($id);
        } catch (BusinessException $e) {
            // kein Formular, das erneut anzuzeigen wäre: der Fehler wird auch als Flash-Meldung weitergereicht
            return redirect()->route('persons.list')->with('error', $e->getMessage());
        }
        return redirect()->route('persons.list')->with('success', "$p->first_name $p->last_name has been deleted.");
    }
}
  • Zeile 14: die Geschäftsschicht, die einzige Schicht, die der Controller kennt;
  • Zeilen 35–45: der Ablauf beim Hinzufügen in drei Schritten: Formularvalidierung (Eingabefehler), die vor dem Aufruf der Action durch den Form Request erfolgt; der Aufruf der Geschäftsschicht (Geschäftsregeln); dann das PRG-Schema mit einer Erfolgsmeldung als Flash-Nachricht. Eine [BusinessException] führt zurück zum Formular: [back()] leitet auf die vorherige Seite (die Formularseite) um, [withInput()] bewahrt die Eingaben für [old] auf (Beispiel 19), und [with('error', ...)] gibt die Fehlermeldung weiter, die das Template am Ende der Seite anzeigen wird. Genau das tut [Laravel] bei einem ungültigen Formular: Eingabefehler und Fehler der Geschäftslogik werden auf dieselbe Weise behandelt;
  • Zeilen 47–56: das Bearbeitungsformular, mit der abgerufenen Person vorausgefüllt. Existiert die Person nicht, wird der Benutzer mit einer Fehlermeldung in einem Pop-up auf die Liste umgeleitet;
  • Zeilen 58–66: die Aktualisierung nach demselben Muster wie das Hinzufügen;
  • Zeilen 68–77: das Löschen. Es gibt kein Formular, das erneut angezeigt werden müsste: Jeder Fehler wird ebenfalls in einer Pop-up-Meldung übermittelt, [error].

Die Web-Schicht enthält weder SQL noch irgendwelche Geschäftsregeln: Sie übersetzt die Anfrage in einen Aufruf der Geschäftsschicht und das Ergebnis in eine Seite. Die Routing-Tabelle:

<?php
// routes/web.php: die Routen von Beispiel 28

use App\Http\Controllers\PersonsController;
use Illuminate\Support\Facades\Route;

Route::controller(PersonsController::class)->name('persons.')->group(function () {
    Route::get('/', 'home');
    Route::get('persons', 'list')->name('list');
    Route::get('persons/add', 'addForm')->name('addForm');
    Route::post('persons/add', 'add')->name('add');
    Route::get('persons/{id}/edit', 'editForm')->whereNumber('id')->name('editForm');
    Route::put('persons/{id}', 'edit')->whereNumber('id')->name('edit');
    Route::delete('persons/{id}', 'delete')->whereNumber('id')->name('delete');
});
  • Zeile 7: Innerhalb einer Gruppe liefert [name] ein Präfix für Routennamen: Die Route mit dem Namen [list] heißt tatsächlich [persons.list];
  • Zeilen 13–14: Die Änderung ist eine PUT-Anfrage und das Löschen eine DELETE-Anfrage, simuliert durch POST-Formulare (Beispiel 21).

Die Views:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Persons</title>
  <link rel="stylesheet" href="{{ route('bootstrap', 'css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3" style="max-width: 40rem">
    {{-- the success message ([success] flash message): at the top --}}
    @session('success')
      <div class="alert alert-success" role="status">{{ $value }}</div>
    @endsession
    <main>
      @yield('content')
    </main>
    {{-- the error ([error] flash message): at the bottom --}}
    @session('error')
      <div class="error-area" role="alert">{{ $value }}</div>
    @endsession
  </div>
  @include('fragments.confirmation')
  <script src="{{ asset('js/app.js') }}"></script>
</body>
</html>
  • Zeilen 12–14: die Erfolgsmeldung am Seitenanfang (Beispiel 20);
  • Zeilen 19–21: die Fehlermeldung am Seitenende.
@extends('layout')

@section('content')
  <h1 class="h3">Persons</h1>
  <table class="table align-middle">
    <thead><tr><th>First name</th><th>Last name</th><th>Age</th><th></th></tr></thead>
    <tbody>
      @foreach ($persons as $p)
        <tr>
          <td>{{ $p->first_name }}</td>
          <td>{{ $p->last_name }}</td>
          <td>{{ $p->age }}</td>
          <td class="text-end">
            <a class="btn btn-sm btn-outline-primary" href="{{ route('persons.editForm', $p->id) }}">Edit</a>
            <form method="post" class="d-inline" action="{{ route('persons.delete', $p->id) }}"
                  data-confirmation="Delete {{ $p->first_name }} {{ $p->last_name }}?">
              @csrf
              @method('DELETE')
              <button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
            </form>
          </td>
        </tr>
      @endforeach
    </tbody>
  </table>
  <a class="btn btn-primary" href="{{ route('persons.addForm') }}">Add a person</a>
@endsection

Die Liste enthält die Links und Schaltflächen aus Beispiel 21 samt ihrem Bestätigungsfenster (die Dateien [fragments/confirmation.blade.php] und [public/js/app.js] sind die aus Beispiel 21).

@extends('layout')

@section('content')
  <h1 class="h3">{{ $title }}</h1>
  <form method="post" action="{{ $action }}" novalidate>
    @csrf
    {{-- an edit: the PUT method, and the version of the record read --}}
    @if ($person)
      @method('PUT')
      <input type="hidden" name="version" value="{{ old('version', $person->version) }}">
    @endif
    <x-field name="first_name" label="First name" :value="$person?->first_name" required maxlength="30" />
    <x-field name="last_name" label="Last name" :value="$person?->last_name" required maxlength="30" />
    <x-field name="age" label="Age" type="number" :value="$person?->age" required min="0" max="150" />
    <button class="btn btn-primary" type="submit">Save</button>
    <a class="btn btn-link" href="{{ route('persons.list') }}">Cancel</a>
  </form>
@endsection
  • Zeilen 8–11: Eine View, die sowohl für das Hinzufügen als auch für das Ändern von Datensätzen gilt: bei einer Änderung ([$person] ist nicht [null]) die Methode PUT und das versteckte Feld, das die Version des gelesenen Datensatzes trägt. [old('version', $person->version)]: die zuvor eingegebene Version (nach der Rückkehr zum Formular) oder die Version des Datensatzes;
  • Zeilen 12–14: die Komponente aus Beispiel 19, die zusätzlich den Anfangswert des Feldes erhält ([$person?->first_name]: [null] beim Hinzufügen).
{{-- an input field, with its label and its FIRST error message (see
     example 19); [value]: the initial value of the field, displayed if the form
     has not been sent yet --}}
@props(['name', 'label', 'type' => 'text', 'value' => null])
<div class="mb-2">
  <label class="form-label" for="{{ $name }}">{{ $label }}</label>
  <input {{ $attributes->class(['form-control', 'is-invalid' => $errors->has($name)]) }}
         type="{{ $type }}" id="{{ $name }}" name="{{ $name }}"
         @if ($type !== 'password') value="{{ old($name, $value) }}" @endif>
  {{-- @error: the block is displayed only if the field has an error, whose
       first message is in the $message variable --}}
  @error($name)
    <div class="invalid-feedback">{{ $message }}</div>
  @enderror
</div>
  • Zeile 4: Die Komponente hat einen zusätzlichen Parameter, [value];
  • Zeile 9: [old] akzeptiert einen Standardwert, der verwendet wird, wenn das Formular noch nicht abgesendet wurde: der Anfangswert des Feldes.

9.1.7. Ausführung

Die Liste der Personen:

Image

Ein falsch ausgefülltes Formular zum Hinzufügen: Eingabefehler werden von der Web-Schicht erkannt.

Image

Ein Namensvetter: Die Eingabe ist korrekt, aber die Geschäftsschicht lehnt das Hinzufügen ab. Da der Vergleich von der Datenbank durchgeführt wird, ignoriert er sowohl Groß- und Kleinschreibung als auch Akzente: [marie pelissier] ist ein Namensvetter von [Marie Pélissier].

Image

Ein erfolgreiches Hinzufügen:

Image

Um Regel Nr. 2 zu testen, öffnen wir denselben Datensatz in zwei Tabs. Im ersten Tab ändern wir das Alter und speichern. Im zweiten Tab, der noch die alte Version anzeigt, ändern wir den Datensatz ebenfalls:

Image

Das Löschen mit seiner Bestätigung:

Image

Image

9.1.8. Die SQL-Befehle

Starten wir die Anwendung mit der Umgebungsvariablen [DB_LOG=true] neu (unter [Linux] und [macOS]: [DB_LOG=true php artisan serve]; für [Windows]: [$env:DB_LOG="true"] vor [php artisan serve]; oder durch Ändern der Datei [.env]) und verfolgen dann in der Konsole die SQL-Befehle einer Änderung. Die Anzeige des Änderungsformulars für Person Nr. 1:

  select * from `persons` where `persons`.`id` = ? limit 1 [1]

Ein Lesevorgang über den Primärschlüssel, dessen Wert als Parameter übergeben wird ([?]), ohne Transaktion: Ein einzelner Lesevorgang benötigt keine. Das Speichern des Datensatzes mit einem neuen Alter:

1
2
3
4
5
6
  BEGIN
  select * from `persons` where `persons`.`id` = ? limit 1 [1]
  select * from `persons` where `first_name` = ? and `last_name` = ? and `id` <> ? limit 1 ["Marie","Pélissier",1]
  update `persons` set `first_name` = ?, `last_name` = ?, `age` = ?, `version` = version + 1 where `id` = ? and `version` = ? ["Marie","Pélissier",44,1,1]
  select * from `persons` where `persons`.`id` = ? limit 1 [1]
  COMMIT

In einer einzigen Transaktion sehen wir: das Lesen des Stammdatensatzes, die Suche nach einem Namensvetter, das [UPDATE] und das erneute Lesen. Das [UPDATE] erhöht die Version ([version + 1], dank [DB::raw] unverändert geschrieben), und legt die Bedingung des optimistischen Sperrens fest ([and version = ?], mit der gelesenen Version, hier 1). [Laravel] umgibt Tabellen- und Spaltennamen mit Graviszeichen ([persons]), wie diese Namen in [MySQL] geschrieben werden. Senden wir nun dasselbe Formular ein zweites Mal ab, weiterhin mit Version 1:

1
2
3
  BEGIN
  select * from `persons` where `persons`.`id` = ? limit 1 [1]
  ROLLBACK

Die gelesene Version (2) ist nicht dieselbe wie die im Formular (1): Die Geschäftsschicht hat eine [BusinessException] ausgelöst, die die Transaktion zurückgerollt hat ([ROLLBACK]), und die Seite zeigt „Dieser Datensatz wurde inzwischen geändert: Laden Sie ihn neu.“ an. Ebenso endet das Hinzufügen eines Namensvetters nach der Suche nach dem Namensvetter, ohne ein [INSERT].