Skip to content

3. Das Modell einer Action

Eine Action benötigt Informationen, die der Browser sendet: die Parameter der URL ([?name=martin&age=42]), Formularfelder, den JSON-Body der Anfrage und manchmal einen HTTP-Header. Der Originalkurs bezeichnet alle diese Informationen als das Modell der Action. Dieses Kapitel zeigt, wie eine [Laravel]-Action diese Informationen abruft, in den richtigen Typ umwandelt und validiert. Dieser Vorgang heißt Data Binding.

[Laravel] stellt die Informationen der Anfrage über das Objekt [Request] (Beispiel 05) bereit, in Form von Zeichenketten, zusammen mit einigen Konvertierungsmethoden. Zur Überprüfung der Daten bietet es ein umfassendes Validierungssystem: Die erwarteten Daten werden durch Regeln („erforderlich“, „eine ganze Zahl zwischen 0 und 150“ usw.) beschrieben, und [Laravel] prüft, ob die Daten ihnen entsprechen. Zunächst lesen wir die Parameter manuell (Beispiel 07) und validieren sie dann mit diesen Regeln (Beispiele 08 bis 12). Im nächsten Kapitel validiert dasselbe System die HTML-Formulare.

Hinweis zur Terminologie: Im nächsten Kapitel bezeichnet das Wort „Modell“ vor allem die Daten, die eine Action ihrer View übergibt. Das Modell einer Action im Sinne dieses Kapitels ist das, was sie empfängt. [Laravel] verwendet das Wort *Modell* außerdem für die Klassen, die Datenbanktabellen repräsentieren (Kapitel 9): Das ist eine dritte Bedeutung.

Die Beispiele 07 bis 12 werden auf dieselbe Weise ausgeführt wie die des vorherigen Kapitels: ein Terminal im Beispielverzeichnis öffnen, [php artisan serve]; [Ctrl-C] beendet den Server. Ihre Dateien [bootstrap/app.php] sind alle ähnlich: Sie fügen die Middleware [ReadableJson] aus Beispiel 03 hinzu, was ein gut lesbares JSON ergibt. Wir kommentieren sie nur, wenn sie etwas Neues einführen.

3.1. Beispiel 07: Die Parameter der URL

Die Parameter der URL sind der Teil, der auf [?] folgt: [?name=martin&age=42]. Dieser Teil heißt Query-String (*query string*). Jeder Parameter ist ein Paar der Form [name=value]; die Paare werden durch [&] getrennt. Der Controller [ParametersController]:

<?php
// app/Http/Controllers/ParametersController.php: die Parameter der URL (der "Query-String")

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class ParametersController
{
    // /parameters/action01?name=martin: query liefert den Wert des Parameters oder
    // null, falls er fehlt
    public function action01(Request $request): string
    {
        $name = $request->query('name');
        return "name = [$name], of type ".get_debug_type($name);
    }

    // /parameters/action02?age=42: integer WANDELT den Wert (einen String) in eine
    // Ganzzahl um; ein fehlender Parameter oder einer, der keine Ganzzahl ist, ergibt 0
    public function action02(Request $request): string
    {
        $age = $request->integer('age');
        return "age = [$age], of type ".get_debug_type($age);
    }

    // /parameters/action03?age=42: ein ERFORDERLICHER Parameter; sein Fehlen oder ein
    // Wert, der keine Ganzzahl ist, beendet die Action mit einer 400-Antwort (Bad Request)
    public function action03(Request $request): string
    {
        $text = $request->query('age');
        if ($text === null) {
            // abort löst eine Exception aus, die Laravel in eine Fehlerantwort umwandelt
            abort(400, 'the [age] parameter is required');
        }
        // die Umwandlung liegt bei uns: filter_var liefert die Ganzzahl oder false
        $age = filter_var($text, FILTER_VALIDATE_INT);
        if ($age === false) {
            abort(400, "[$text] is not an integer");
        }
        return "age = [$age], of type ".get_debug_type($age);
    }

    // /parameters/action04?page=2: ein Standardwert, falls der Parameter fehlt
    public function action04(Request $request): string
    {
        $page = $request->integer('page', 1);
        return "page = [$page]";
    }

    // /parameters/action05?q=laravel: der Name des URL-Parameters ist nicht unbedingt
    // der der PHP-Variablen
    public function action05(Request $request): string
    {
        $search = $request->query('q');
        return "search = [$search]";
    }

    // /parameters/action06?name=martin&age=42: alle Parameter auf einmal, als Array
    public function action06(Request $request): array
    {
        return $request->query();
    }
}
  • Zeile 14: Die Methode [query] der Anfrage gibt den bereits decodierten Wert eines Parameters der URL zurück, oder [null] , wenn er fehlt; sie löst nie einen Fehler aus;
  • Zeile 15: Die Action zeigt den Wert und seinen Typ an: Die Funktion [get_debug_type] gibt den Namen des Typs eines Werts zurück. Ein aus der URL abgerufener Wert ist immer eine Zeichenkette ([string]). Der Operator [.] verkettet die interpolierte Zeichenkette und den Typ;
  • Zeile 22: Die Methode [integer] liest den Parameter und wandelt ihn in eine ganze Zahl um. Schlägt die Umwandlung fehl ([abc]) oder fehlt der Parameter, liefert sie 0: Die Action kann diese Fälle nicht von einem tatsächlich eingegebenen Alter von 0 unterscheiden, und der Eingabefehler bleibt unbemerkt. Ebenso gibt es [float], [boolean] ([1], [true], [on], [yes] sind gültig), [string], [date] (Beispiel 12), [enum];
  • Zeilen 30–40: ein erforderlicher Parameter und eine manuelle Umwandlung, die die beiden möglichen Fehler unterscheidet. [abort(400, message)] beendet die Action mit einer 400-Antwort (*Bad Request*, die Anfrage ist ungültig) samt der Meldung (siehe Beispiel 03). Die Funktion [filter_var] von [PHP] gibt mit dem Filter [FILTER_VALIDATE_INT] die in der Zeichenkette enthaltene ganze Zahl zurück oder [false] , wenn die Zeichenkette keine ganze Zahl ist;
  • Zeile 46: Der zweite Parameter von [integer] ist ein Standardwert, der verwendet wird, wenn der Parameter fehlt. Das ist typischerweise bei der Seitennummer einer Liste der Fall;
  • Zeile 54: Die [PHP]-Variable muss nicht denselben Namen tragen wie der Parameter der URL. Suchmaschinen verwenden oft einen kurzen Parameter wie [q] (*query*);
  • Zeile 61: Ohne Parameter gibt [query] alle Parameter der URL in einem assoziativen Array zurück, das die Action zurückgibt: [Laravel] wandelt es in JSON um (siehe Beispiel 03).

Die Routing-Tabelle deklariert die sechs Routen mithilfe einer Schleife:

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

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

Route::prefix('parameters')->controller(ParametersController::class)->group(function () {
    foreach (['action01', 'action02', 'action03', 'action04', 'action05', 'action06'] as $action) {
        Route::get($action, $action);
    }
});
  • Zeile 8: Die Schleife [foreach] durchläuft ein Array: Bei jedem Durchlauf nimmt die Variable [$action] den Wert des nächsten Elements an. Jede Route ist nach ihrer Action benannt: [Route::get('action01', 'action01')] ... Die Routing-Tabelle ist nur eine weitere [PHP]-Datei: Sie können darin beliebigen Code schreiben.

Testen wir jede Action mit [curl]. Zunächst mit vorhandenem, dann mit fehlendem Parameter:

curl -i "http://localhost:8000/parameters/action01?name=martin"
curl http://localhost:8000/parameters/action01
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

name = [martin], of type string
name = [], of type null

Die Anführungszeichen um „URL“ sind in einem Terminal notwendig: Ohne sie würde die Shell [&] (das unter [Linux] einen Befehl im Hintergrund ausführt) und [?] interpretieren. Der Wert [null] wird beim Einfügen in eine Zeichenkette zu einer leeren Zeichenkette. Ein Wert mit Leerzeichen oder Sonderzeichen muss in der URL codiert werden: Ein Leerzeichen wird zu [%20], und [&] wird zu [%26] (sonst würde es zwei Parameter trennen). Der Browser erledigt das automatisch; mit [curl] müssen Sie es selbst schreiben. [PHP] decodiert den Wert, bevor die Action ihn liest:

curl "http://localhost:8000/parameters/action01?name=jean%20dupont%20%26%20sons"
name = [jean dupont & sons], of type string

Umwandlung mit [integer] – erfolgreich, fehlgeschlagen, dann ohne Parameter:

1
2
3
curl "http://localhost:8000/parameters/action02?age=42"
curl "http://localhost:8000/parameters/action02?age=abc"
curl http://localhost:8000/parameters/action02
1
2
3
age = [42], of type int
age = [0], of type int
age = [0], of type int

Der erforderliche Parameter der Action 03 fehlt, dann ist er ungültig. Wir fordern eine JSON-Antwort an (Header [Accept], siehe Beispiel 03), die die Meldung von [abort] enthält:

curl -i -H "Accept: application/json" http://localhost:8000/parameters/action03
curl -H "Accept: application/json" "http://localhost:8000/parameters/action03?age=abc"
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "the [age] parameter is required",
    "exception": "Symfony\\Component\\HttpKernel\\Exception\\HttpException",
    ...
}
{
    "message": "[abc] is not an integer",
    "exception": "Symfony\\Component\\HttpKernel\\Exception\\HttpException",
    ...
}

In einem Browser zeigt eine 400-Antwort im Debug-Modus die Fehlerseite von [Laravel] mit der Meldung an:

Image

Der Standardwert und der umbenannte Parameter:

1
2
3
curl http://localhost:8000/parameters/action04
curl "http://localhost:8000/parameters/action04?page=3"
curl "http://localhost:8000/parameters/action05?q=laravel"
1
2
3
page = [1]
page = [3]
search = [laravel]

Schließlich alle Parameter auf einmal. Der Parameter [name] kommt zweimal vor:

curl "http://localhost:8000/parameters/action06?name=martin&age=42&name=durand"
1
2
3
4
{
    "name": "durand",
    "age": "42"
}

Der Parameter [name] behält nur seinen letzten Wert: Das ist eine Regel von [PHP], der wir in Beispiel 10 erneut begegnen. Das Alter blieb eine Zeichenkette (["42"], in JSON von Anführungszeichen umschlossen): Es wurde keine Umwandlung angefordert. In einem Browser (hier [Chromium]) wird das JSON genau so angezeigt, wie der Server es formatiert hat; das Kontrollkästchen „Pretty-print“ würde es einrücken, wenn es nicht bereits eingerückt wäre. Die Adressleiste zeigt außerdem die Codierung von Umlauten und Akzentzeichen in der URL ([é] wird zu [%C3%A9], mit seinen zwei Bytes in [UTF-8]):

Image

Dieses erste Beispiel zeigt die Grenzen des manuellen Ansatzes: Für jeden Parameter müssen Sie das Lesen, die Umwandlung sowie den Umgang mit fehlenden Werten und Fehlern schreiben. Bei zehn Parametern würde der Code der Action von diesen Prüfungen überwuchert. Besser ist es, zu beschreiben, was erwartet wird, und das Framework die Prüfung übernehmen zu lassen. Das ist das Ziel des folgenden Beispiels.

3.2. Beispiel 08: Ein durch eine Klasse beschriebenes Modell einer Action

[Laravel] validiert die Daten einer Anfrage mithilfe von Validierungsregeln. Eine Regel hat einen Namen ([required], [integer], [email] ...) und manchmal Parameter ([min:2], [between:0,150]); die Regeln eines Felds werden als Zeichenkette, getrennt durch [|], oder als Array geschrieben. [Laravel] bietet etwa hundert davon an. Der natürliche Ort, um das Modell einer Action zu beschreiben, ist eine Form Request (*form request*): eine Klasse, die von [FormRequest] erbt und deren Methode [rules] die Regeln für jeden Parameter zurückgibt.

3.2.1. Das Modell: app/Http/Requests/PersonRequest.php

<?php
// app/Http/Requests/PersonRequest.php: das Modell der Action, eine Klasse, die
// die erwarteten Parameter und ihre Einschränkungen beschreibt

namespace App\Http\Requests;

use App\Models\Person;
use Illuminate\Foundation\Http\FormRequest;

class PersonRequest extends FormRequest
{
    // die Validierungs-REGELN, Parameter für Parameter
    public function rules(): array
    {
        return [
            // erforderlich, ein String mit 2 bis 20 Zeichen
            'name' => 'required|string|min:2|max:20',
            // erforderlich, eine Ganzzahl zwischen 0 und 150
            'age' => 'required|integer|between:0,150',
            // nur einer dieser drei Werte
            'title' => 'required|in:Mr,Mme,Melle',
            // optional (nullable); falls vorhanden, eine gültige E-Mail-Adresse
            'email' => 'nullable|email',
        ];
    }

    // die validierten Parameter in Form eines typisierten Objekts
    public function person(): Person
    {
        $values = $this->validated();
        return new Person($values['name'], (int) $values['age'], $values['title'],
            $values['email'] ?? null);
    }
}
  • Zeile 10: Die Klasse erbt ([extends]) von [FormRequest], die ihrerseits von [Request] erbt: Ein [PersonRequest]-Objekt ist eine Anfrage mit allen Methoden aus Beispiel 07 sowie Validierungsregeln;
  • Zeilen 13–24: die Regeln in einem assoziativen Array: für jeden Parameter die Zeichenkette mit seinen Regeln;
  • Zeile 17: [required]: Der Parameter ist erforderlich (fehlt er oder ist er leer, wird er abgelehnt); [string]: eine Zeichenkette; [min:2] und [max:20]: Bei einer Zeichenkette muss ihre Länge zwischen 2 und 20 Zeichen liegen;
  • Zeile 19: [integer]: Der Wert muss eine ganze Zahl sein (["42"] ist gültig, ["abc"] nicht); [between:0,150]: Bei einer Zahl muss ihr Wert zwischen 0 und 150 liegen. Die Regeln [min], [max] und [between] passen sich somit dem Typ des Werts an: eine Länge bei einer Zeichenkette, ein Wert bei einer Zahl und eine Anzahl von Elementen bei einem Array (z. B. 10);
  • Zeile 21: [in:Mr,Mme,Melle]: einer der drei aufgeführten Werte, und nur diese;
  • Zeile 23: [nullable]: Der Parameter ist optional (er wird akzeptiert, wenn er fehlt oder leer ist); [email]: falls vorhanden, eine gültige E-Mail-Adresse;
  • Zeilen 28–33: eine der Klasse hinzugefügte Methode: Sie gibt die validierten Daten in Form eines [Person]-Objekts zurück (siehe unten). [$this->validated()] gibt nur die Daten zurück, die validiert wurden: Ein Parameter ohne Regel ist nicht enthalten. Die von [Laravel] durchgeführte Validierung prüft die Daten, wandelt sie aber nicht um: Das validierte Alter ist weiterhin die Zeichenkette ["42"]. Erst der Umwandlungsoperator [(int)] macht daraus eine ganze Zahl. Der Operator [??] gibt seinen linken Operanden zurück, wenn er existiert und nicht [null] ist; andernfalls gibt er den rechten Operanden zurück: [$values['email'] ?? null] ergibt [null] , wenn die Adresse nicht im Array enthalten ist.

Dieses Modell beschreibt die erwarteten Daten; es enthält keine Validierungsanweisungen. Man spricht von einem deklarativen Stil. Die Klasse [Person] ist eine unveränderliche Klasse nach dem Vorbild der aus Beispiel 03:

<?php
// app/Models/Person.php: eine Person

namespace App\Models;

readonly class Person
{
    public function __construct(
        public string $name,
        public int $age,
        public string $title,
        public ?string $email,
    ) {
    }
}
  • Zeile 12: [?string]: eine Zeichenkette oder [null].

3.2.2. Die Action: app/Http/Controllers/PersonsController.php

<?php
// app/Http/Controllers/PersonsController.php: eine Action, deren Modell eine FormRequest-Klasse ist

namespace App\Http\Controllers;

use App\Http\Requests\PersonRequest;

class PersonsController
{
    // /persons/action01?name=martin&age=42&title=Mr
    // Der Parameter vom Typ PersonRequest wird von Laravel VOR dem Aufruf
    // der Action VALIDIERT: ein ungültiges Modell löst eine ValidationException aus, die von bootstrap/app.php in eine
    // 400-Antwort umgewandelt wird, und die Action wird nie aufgerufen
    public function action01(PersonRequest $request): array
    {
        $person = $request->person();
        return [
            'received' => $request->validated(),
            'person' => $person,
            'ageType' => get_debug_type($person->age),
        ];
    }
}
  • Zeile 14: Die Action verlangt einen Parameter vom Typ [PersonRequest], während Beispiel 07 einen [Request] verlangte. [Laravel] erstellt dann aus der aktuellen Anfrage ein [PersonRequest]-Objekt und validiert es, bevor es die Action aufruft: Es prüft jede Regel für jeden Parameter. Sind alle Regeln erfüllt, wird die Action aufgerufen. Andernfalls löst [Laravel] eine Exception vom Typ [ValidationException] aus, die eine Liste aller Fehler enthält (nicht nur des ersten), und die Action wird nie aufgerufen: Sie muss sich daher nicht mit ungültigen Daten befassen;
  • Zeilen 16–20: Die Action gibt die validierten Daten unverändert zurück, dann als [Person]-Objekt, zusammen mit dem Typ des Alters, um den Unterschied zu veranschaulichen.

Wer behandelt die Exception [ValidationException]? Standardmäßig [Laravel] selbst, und seine Antwort hängt vom Client ab. Bei einer Anfrage, die JSON erwartet (Header [Accept: application/json]), lautet die Antwort 422 (*Unprocessable Content*) und beschreibt die Fehler in JSON. Bei einer gewöhnlichen Anfrage aus einem HTML-Formular ist die Antwort eine Weiterleitung auf die vorherige Seite, wobei die Fehler für das erneut angezeigte Formular erhalten bleiben (dazu mehr im nächsten Kapitel). Hier wollen wir in jedem Fall eine Fehlerantwort in JSON mit dem Code 400. Das ist die Aufgabe von [bootstrap/app.php].

3.2.3. Fehlerbehandlung: bootstrap/app.php

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

use App\Http\Middleware\ReadableJson;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Validation\ValidationException;

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

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(web: __DIR__.'/../routes/web.php')
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->append(ReadableJson::class);
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        // ein ungültiges Modell: die Exception ValidationException wird für
        // die GESAMTE Anwendung zu einer 400-Antwort, die die Fehler auflistet
        $exceptions->render(function (ValidationException $e) {
            $errors = [];
            // errors(): Feld -> Liste seiner Fehlermeldungen
            foreach ($e->errors() as $field => $messages) {
                foreach ($messages as $message) {
                    $errors[] = ['field' => $field, 'message' => $message];
                }
            }
            return response()->json(['status' => 400, 'errors' => $errors], 400);
        });
    })
    ->create();
  • Zeilen 17–30: Der Methode [withExceptions] wird nun eine Funktion übergeben, die das Objekt [$exceptions] erhält, das die Exception-Behandlung der Anwendung beschreibt;
  • Zeilen 20–29: Die Methode [render] registriert einen Exception-Handler: eine Funktion, die [Laravel] aufruft, wenn eine Action eine Exception desselben Typs wie ihr Parameter auslöst (hier [ValidationException] oder eine abgeleitete Klasse) und deren Rückgabewert die gesendete Antwort ist. [Laravel] erkennt den Typ der zu behandelnden Exception anhand des Parametertyps der Funktion. Der in [bootstrap/app.php] deklarierte Handler gilt für alle Actions der Anwendung: Jede Action, die ein Modell validiert, profitiert davon, ohne eine einzige Zeile Fehlerbehandlungscode schreiben zu müssen;
  • Zeilen 23–27: [$e->errors()] gibt die Fehler in einem assoziativen Array zurück: für jedes fehlerhafte Feld die Liste seiner Fehlermeldungen. Die Schleife [foreach ($array as $key => $value)] durchläuft sowohl die Schlüssel als auch die Werte. [$errors[] = ...] fügt dem Array [$errors] am Ende ein Element hinzu;
  • Zeile 28: eine JSON-Antwort mit dem Statuscode 400.

3.2.4. Ausführung

Ein gültiges Modell:

curl -i "http://localhost:8000/persons/action01?name=martin&age=42&title=Mr"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "received": {
        "name": "martin",
        "age": "42",
        "title": "Mr"
    },
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mr",
        "email": null
    },
    "ageType": "int"
}

Die validierten Daten enthalten nur die empfangenen Parameter; das Alter liegt als Zeichenkette vor; das [Person]-Objekt enthält das Alter als ganze Zahl (in JSON ohne Anführungszeichen), und die fehlende Adresse ist [null]. Ein von Leerzeichen umgebener Name ([%20]) und eine vorhandene Adresse:

curl "http://localhost:8000/persons/action01?name=%20%20martin%20&age=42&title=Mme&email=martin@example.com"
{
    "received": {
        "name": "martin",
        "age": "42",
        "title": "Mme",
        "email": "martin@example.com"
    },
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mme",
        "email": "martin@example.com"
    },
    "ageType": "int"
}

Die den Namen umgebenden Leerzeichen sind verschwunden, ohne dass wir das verlangt hätten: Zwei Middleware-Komponenten, die [Laravel] für alle Anfragen ausführt, wandeln die empfangenen Parameter um, bevor eine Action sie liest. [TrimStrings] entfernt die Leerzeichen um jede Zeichenkette; [ConvertEmptyStringsToNull] ersetzt jede leere Zeichenkette durch [null]. Jetzt gibt es keine Parameter mehr: Die drei Pflichtfelder fehlen.

curl -i http://localhost:8000/persons/action01
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "The name field is required."
        },
        {
            "field": "age",
            "message": "The age field is required."
        },
        {
            "field": "title",
            "message": "The title field is required."
        }
    ]
}

Vier ungültige Felder auf einmal:

curl "http://localhost:8000/persons/action01?name=m&age=abc&title=Mlle&email=xx"
{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "The name field must be at least 2 characters."
        },
        {
            "field": "age",
            "message": "The age field must be an integer."
        },
        {
            "field": "title",
            "message": "The selected title is invalid."
        },
        {
            "field": "email",
            "message": "The email field must be a valid email address."
        }
    ]
}

Alle Fehler werden auf einmal gemeldet, sodass der Benutzer alles in einem Zug korrigieren kann. Beim Altersfeld [abc] wird nur die Regel [integer] beanstandet: Die Regel [between] ist auf einen Wert, der keine Zahl ist, nicht anwendbar. Die Meldungen sind auf Englisch, der Standardsprache von [Laravel]. Das folgende Beispiel ersetzt sie durch eigene Meldungen.

3.3. Beispiel 09: Von der Action durchgeführte Validierung

In Beispiel 08 beendet ein ungültiges Modell die Action, und der Handler der Anwendung antwortet. Das ist bequem für eine API, deren Clients Programme sind, die eine standardisierte Fehlerantwort erwarten. Eine Webseite zieht es jedoch oft vor, das Formular mit den Fehlermeldungen erneut anzuzeigen: In diesem Fall muss die Action entscheiden, wie sie mit einem ungültigen Modell umgeht. Die Klassen [PersonRequest] and [Person] sind die aus Beispiel 08.

09-action-validation/
├── app/
│   ├── Http/
│   │   ├── Controllers/
│   │   │   └── PersonsController.php
│   │   └── Requests/
│   │       └── PersonRequest.php
│   └── Models/
│       └── Person.php
├── lang/
│   └── en/
│       └── validation.php
└── ...

3.3.1. Eigene Meldungen: lang/en/validation.php

Die Fehlermeldungen von [Laravel] sind nicht fest codiert: Jede Meldung wird durch einen Schlüssel identifiziert, und eine Sprachdatei ordnet jedem Schlüssel einen Text zu. Die englischen Dateien werden mit dem Framework geliefert; die Anwendung kann im Ordner [lang] eigene Dateien bereitstellen, mit einem Unterordner pro Sprache, um diese Meldungen zu ersetzen oder weitere Sprachen hinzuzufügen. Die Sprache der Anwendung wird durch die Datei [.env] festgelegt:

APP_LOCALE=en

Die Datei mit den Validierungsmeldungen heißt [validation.php]:

<?php
// lang/en/validation.php: die Meldungen der Validierungsfehler, auf Englisch.
// Jede Meldung wird durch den Namen ihrer REGEL bezeichnet (required, min...). Die Platzhalter
// :attribute, :min, :max... werden durch den Namen des Feldes und durch die
// Parameter der Regel ersetzt
return [
    'required' => 'the field is required',
    'string' => 'a string is expected',
    'integer' => 'an integer is expected',
    'email' => 'invalid email address',
    'in' => 'unknown value',
    // manche Regeln haben je Werttyp eine Meldung: bei einem String bezieht sich min
    // auf seine Länge; bei einer Zahl auf ihren Wert; bei einem Array auf
    // die Anzahl seiner Elemente
    'min' => [
        'string' => ':min character(s) at least',
        'numeric' => 'the value must be greater than or equal to :min',
        'array' => ':min item(s) at least',
    ],
    'max' => [
        'string' => ':max character(s) at most',
        'numeric' => 'the value must be less than or equal to :max',
    ],
    'between' => [
        'numeric' => 'the value must be between :min and :max',
    ],
    'array' => 'a list is expected',
];
  • Zeile 6: Eine Sprachdatei ist eine [PHP]-Datei, die ein assoziatives Array zurückgibt: für jeden Schlüssel den zugehörigen Text;
  • Zeilen 7–11: Der Schlüssel einer Validierungsmeldung ist der Name der Regel, die fehlgeschlagen ist. Diese Technik (Übersetzen anhand des Fehlernamens statt anhand seines englischen Textes) wird auch in der Fallstudie verwendet: Die Texte dort werden durch Schlüssel identifiziert, die in die Sprache des Benutzers übersetzt werden;
  • Zeilen 15–19: Regeln, die sich dem Typ des Werts anpassen (z. B. 08), haben für jeden Typ eine Meldung: [string], [numeric], [array]. Die Platzhalter [:min] und [:max] werden durch die Parameter der Regel ersetzt ([min:2] bedeutet „mindestens 2 Zeichen“). Der Platzhalter [:attribute], den wir nicht verwenden, würde durch den Feldnamen ersetzt.

Ein in dieser Datei fehlender Schlüssel behält die englische Meldung des Frameworks: [Laravel] führt die Datei der Anwendung mit seiner eigenen zusammen. Bei einer anderen Sprache greift ein fehlender Schlüssel auf die Ausweichsprache zurück, [APP_FALLBACK_LOCALE], die standardmäßig Englisch ist. Vollständige Übersetzungen der Meldungen von [Laravel] in zahlreiche Sprachen werden von der Community veröffentlicht (das Paket [laravel-lang]).

3.3.2. Die Action: app/Http/Controllers/PersonsController.php

<?php
// app/Http/Controllers/PersonsController.php: die Action entscheidet, was bei einem ungültigen Modell zu tun ist

namespace App\Http\Controllers;

use App\Http\Requests\PersonRequest;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Validator;

class PersonsController
{
    public function action01(Request $request): string
    {
        // ein VALIDATOR: die zu validierenden Daten und die Regeln (die der
        // Klasse PersonRequest aus Beispiel 08)
        $validator = Validator::make($request->query(), (new PersonRequest())->rules());
        if ($validator->fails()) {
            // die Fehler, Feld für Feld: errors()->messages() liefert ihre Liste
            $items = '';
            foreach ($validator->errors()->messages() as $field => $messages) {
                $items .= "<li>$field: $messages[0]</li>";
            }
            return "<p>The form contains errors:</p><ul>$items</ul>";
        }
        // die validierten Daten
        $person = $validator->validated();
        // e(): der eingegebene Name wird in HTML eingefügt; seine Zeichen < > & " '
        // werden durch &lt; &gt;... ersetzt (andernfalls könnte eine Eingabe HTML einschleusen)
        return "<p>Welcome {$person['title']} ".e($person['name'])
            ." ({$person['age']} years old)</p>";
    }
}
  • Zeile 16: Die Fassade [Validator] erstellt einen Validator – ein Objekt, das Regeln auf Daten anwendet. Die Daten bestehen aus den Parametern der URL; die Regeln sind die der Klasse [PersonRequest] aus Beispiel 08. Ein Form Request ist eine Klasse wie jede andere: Man kann über [new] eine Instanz davon erstellen, um ihre Regeln zu lesen;
  • Zeile 17: [fails()] führt die Validierung durch und gibt [true] zurück, wenn mindestens eine Regel fehlschlägt. Die Action selbst bestimmt, was danach geschieht: Es wird keine Exception ausgelöst;
  • Zeilen 19–23: die Fehler, Feld für Feld. [errors()] gibt ein [MessageBag]-Objekt (eine „Tasche“ voller Meldungen) zurück, dessen Methode [messages()] das assoziative Array Feld → Liste der Meldungen liefert. Für jedes Feld wird die erste Meldung, [$messages[0]], in ein [<li>]-Tag eingefügt. Der Operator [.=] hängt eine Zeichenkette an das Ende einer anderen an;
  • Zeile 26: die validierten Daten in einem assoziativen Array;
  • Zeilen 29–30: Bei Erfolg eine Willkommensnachricht. In einer von Anführungszeichen umschlossenen Zeichenkette fügt [{$person['title']}] ein Array-Element ein (geschweifte Klammern begrenzen den Ausdruck). Der Name wird durch die Funktion [e] von [Laravel] geleitet (für *escape*), die Zeichen mit besonderer Bedeutung in HTML ([<], [>], [&], ["], [']) durch ihre Entitäten ersetzt ([&lt;], [&gt;] ...): Sie werden unverändert angezeigt, statt interpretiert zu werden. Ohne diese Vorsichtsmaßnahme könnte ein Benutzer einen „Namen“ eingeben, der HTML oder sogar [JavaScript] enthält, das im Browser jedes Besuchers der Seite ausgeführt würde. Das ist die häufigste Sicherheitslücke im Web: Skript-Injektion (*XSS*, *Cross-Site-Scripting*). Titel und Alter benötigen diesen Schutz nicht: Ihre Werte wurden durch die Regeln validiert (einer von drei erlaubten Werten, eine ganze Zahl). Im nächsten Kapitel übernimmt die View-Engine [Blade] dieses Escaping automatisch für jeden in eine Seite eingefügten Wert.

Eine gültige Eingabe, gefolgt von einer Eingabe mit vier Fehlern:

Image

Image

Die unverarbeitete Antwort auf die zweite Anfrage und die Antwort für einen Namen, der HTML enthält:

curl "http://localhost:8000/persons/action01?name=m&age=abc&title=Mx&email=xx"
curl "http://localhost:8000/persons/action01?name=%3Cb%3Emartin%3C/b%3E&age=42&title=Mr"
<p>The form contains errors:</p><ul><li>name: 2 character(s) at least</li><li>age: an integer is expected</li><li>title: unknown value</li><li>email: invalid email address</li></ul>
<p>Welcome Mr &lt;b&gt;martin&lt;/b&gt; (42 years old)</p>

Der Name [<b>martin</b>] (in der URL als [%3Cb%3E...] codiert) wird unverändert angezeigt, ohne fett dargestellt zu werden: Seine Tags wurden unschädlich gemacht. Beachten Sie, dass die Antwort diesmal den Statuscode 200 hat: Die Action hat sich dafür entschieden, eine normale Seite mit den Fehlern zurückzugeben.

3.4. Beispiel 10: Mehrfache Parameter

Derselbe Parameter kann mehrmals in einer URL vorkommen: [?color=red&color=green]. Das sendet ein Browser bei einer Gruppe von Kontrollkästchen mit demselben Namen oder bei einer Mehrfachauswahlliste (siehe nächstes Kapitel). [PHP] behandelt diesen Fall auf seine eigene Weise. Der Controller [ArraysController]:

<?php
// app/Http/Controllers/ArraysController.php: ein Parameter, der mehrfach in der URL vorkommt

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Validator;

class ArraysController
{
    // /arrays/action01?color=red&color=green: für PHP ERSETZT der zweite Parameter
    // den ersten: nur der LETZTE Wert bleibt erhalten
    public function action01(Request $request): array
    {
        return ['color' => $request->query('color'), 'raw' => $request->server('QUERY_STRING')];
    }

    // /arrays/action02?color[]=red&color[]=green: die eckigen Klammern weisen
    // PHP an, ALLE Werte in einem Array zu speichern
    public function action02(Request $request): array
    {
        // array: der Parameter in Form eines Arrays (leer, falls er fehlt)
        $colors = $request->array('color');
        return ['color' => $colors, 'count' => count($colors)];
    }

    // /arrays/action03?color[]=red: ein Array, Element für Element validiert
    public function action03(Request $request): array
    {
        $colors = $request->array('color');
        $validator = Validator::make(['color' => $colors], [
            // eine Liste mit mindestens einem Element
            'color' => 'array|min:1',
            // jedes Element (*): "red", "green" oder "blue"
            'color.*' => 'in:red,green,blue',
        ]);
        $errors = [];
        foreach ($validator->errors()->messages() as $field => $messages) {
            $errors[] = "$field: $messages[0]";
        }
        return ['colors' => $colors, 'valid' => ! $errors, 'errors' => $errors];
    }
}
  • Zeile 15: Für [PHP] bilden die Parameter der URL ein assoziatives Array, in dem jeder Schlüssel nur einen Wert hat: Ein wiederholter Parameter ersetzt den vorherigen, und nur der letzte Wert bleibt erhalten. Zum Vergleich gibt die Action außerdem die unverarbeitete Parameterzeichenkette so zurück, wie der Browser sie gesendet hat: [$request->server(...)] liest die Variablen, die der Webserver an [PHP] übermittelt, darunter [QUERY_STRING];
  • Zeilen 20–24: Um alle Werte abzurufen, muss der Parametername mit eckigen Klammern enden: [?color[]=red&color[]=green]. [PHP] speichert die Werte dann in einem Array, und zwar unter dem Wert des Parameters [color]. Die Methode [array] der Anfrage gibt den Parameter als Array zurück: leer, wenn er fehlt, mit einem einzigen Element, wenn er nur einen Wert ohne eckige Klammern hat;
  • Zeilen 31–36: Das Array wird anhand von Regeln validiert. [array|min:1]: ein Array mit mindestens einem Element (die Regel [min] gilt für die Anzahl der Elemente eines Arrays; siehe Beispiel 08). Der Schlüssel [color.*] bezeichnet jedes Element des Arrays: Jedes muss eine der drei Farben sein;
  • Zeile 41: Der Operator [!] (nicht) ergibt [true] für ein leeres Array, das in einer Bedingung als „false“ ausgewertet wird.

Die Datei [lang/en/validation.php] ist die aus Beispiel 09. Die Ergebnisse:

1
2
3
curl "http://localhost:8000/arrays/action01?color=red&color=green"
curl -g "http://localhost:8000/arrays/action02?color[]=red&color[]=green"
curl http://localhost:8000/arrays/action02
{
    "color": "green",
    "raw": "color=red&color=green"
}
{
    "color": [
        "red",
        "green"
    ],
    "count": 2
}
{
    "color": [],
    "count": 0
}

Die Option [-g] von [curl] verhindert, dass es die eckigen Klammern in der URL selbst interpretiert. Ein Browser hingegen codiert sie ([color%5B%5D=red]), was [PHP] ebenfalls versteht. In HTML genügt es, die Kontrollkästchen einer Gruppe [color[]] zu nennen: Das tut Beispiel 18. Diese Regel gilt speziell für [PHP]: Frameworks für andere Sprachen ([Flask], [Spring MVC], [ASP.NET Core]) behalten alle Werte eines wiederholten Parameters, ohne eckige Klammern.

Validierung: erfolgreich, dann fehlgeschlagen wegen einer unbekannten Farbe, dann wegen einer leeren Liste:

1
2
3
curl -g "http://localhost:8000/arrays/action03?color[]=red&color[]=blue"
curl -g "http://localhost:8000/arrays/action03?color[]=red&color[]=yellow"
curl http://localhost:8000/arrays/action03
{
    "colors": [
        "red",
        "blue"
    ],
    "valid": true,
    "errors": []
}
{
    "colors": [
        "red",
        "yellow"
    ],
    "valid": false,
    "errors": [
        "color.1: unknown value"
    ]
}
{
    "colors": [],
    "valid": false,
    "errors": [
        "color: 1 item(s) at least"
    ]
}

Der Fehler zur unbekannten Farbe verweist auf [color.1]: das Feld und den Index des problematischen Elements im Array (das zweite, da die Indizes bei 0 beginnen).

3.5. Beispiel 11: Parameter einer POST-Anfrage

Die vorherigen Beispiele verwendeten GET-Anfragen, deren Parameter in der URL enthalten sind. Eine POST-Anfrage überträgt ihre Daten in ihrem Body, hauptsächlich in zwei Formen:

  • Felder eines HTML-Formulars: Der Body hat dieselbe Syntax wie ein Query-String ([name=martin&age=42]), und sein Typ (Header [Content-Type]) ist [application/x-www-form-urlencoded];
  • ein JSON-Dokument, das von einem Programm gesendet wird ([JavaScript] auf einer Seite, Client einer API ...): Der Typ ist [application/json].

Der Controller [PostController]:

<?php
// app/Http/Controllers/PostController.php: die Parameter einer POST-Anfrage

namespace App\Http\Controllers;

use App\Http\Requests\PersonRequest;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Validator;
use JsonException;

class PostController
{
    // die Felder eines HTML-Formulars (Body vom Typ application/x-www-form-urlencoded):
    // post() liefert die Parameter des Anfrage-BODYS in Form eines Arrays
    public function action01(Request $request): array
    {
        return [
            'receivedType' => $request->header('Content-Type'),
            'fields' => $request->post(),
        ];
    }

    // ein JSON-Body: json() deserialisiert ihn; isJson() prüft den angekündigten Typ
    public function action02(Request $request): array
    {
        if (! $request->isJson()) {
            abort(415, 'the body of the request must be JSON');
        }
        // json_decode mit JSON_THROW_ON_ERROR: ein fehlerhaftes JSON löst eine Exception aus
        try {
            $body = json_decode($request->getContent(), true, flags: JSON_THROW_ON_ERROR);
        } catch (JsonException $e) {
            abort(400, 'Malformed JSON: '.$e->getMessage());
        }
        return ['receivedType' => $request->header('Content-Type'), 'body' => $body,
            'name' => $request->input('name')];
    }

    // ein einzelnes Feld des Formulars
    public function action03(Request $request): string
    {
        $name = $request->input('name');
        return "name = [$name]";
    }

    // die Felder des Formulars, validiert mit den Regeln der Klasse PersonRequest
    public function action04(Request $request): array
    {
        $validator = Validator::make($request->post(), (new PersonRequest())->rules());
        $errors = [];
        foreach ($validator->errors()->messages() as $field => $messages) {
            $errors[] = "$field: $messages[0]";
        }
        sort($errors);
        return ['person' => $errors ? null : $validator->validated(),
            'valid' => ! $errors, 'errors' => $errors];
    }
}
  • Zeile 18: der Header [Content-Type] der Anfrage;
  • Zeile 19: Die Methode [post] gibt die Parameter aus dem Body der Anfrage in einem assoziativen Array zurück; [post('name')] würde einen einzelnen Parameter zurückgeben. Für Formularfelder gelten die Regeln aus Beispiel 10: Ein wiederholtes Feld muss einen Namen haben, der auf [[]] endet;
  • Zeilen 26–27: [isJson()] prüft den vom Header [Content-Type] deklarierten Typ. Ein Body, der nicht als JSON deklariert ist, wird mit einem 415-Fehler (*Unsupported Media Type*) abgelehnt;
  • Zeilen 30–34: [getContent()] gibt den unverarbeiteten Body der Anfrage zurück, eine Zeichenkette; die Funktion [json_decode] von [PHP] deserialisiert sie: Der JSON-Text wird zu einem [PHP] -Wert (der zweite Parameter, [true], verlangt assoziative Arrays für JSON-Objekte). Mit der Option [JSON_THROW_ON_ERROR] (einem benannten Parameter) löst fehlerhafter Text eine Exception vom Typ [JsonException] aus, die der Block [try] / [catch] abfängt, um einen 400-Fehler zurückzugeben. Die Methode [json()] der Anfrage würde dasselbe tun, bei fehlerhaftem JSON aber einfach ein leeres Ergebnis liefern;
  • Zeile 36: Die Methode [input] sucht einen Parameter überall: im Body der Anfrage – ob Formular oder JSON – und danach in der URL. Das ist die am häufigsten verwendete Methode, weil sie nicht vom Format der Anfrage abhängt;
  • Zeile 42: ein Formularfeld, gelesen mit [input];
  • Zeilen 49–56: die Regeln der Klasse [PersonRequest] aus Beispiel 08, diesmal auf die Formularfelder angewendet. Der Code ist derselbe wie bei den Parametern der URL: Nur die Datenquelle ändert sich. [sort] sortiert die Meldungen, um eine gleichbleibende Antwort zu gewährleisten. Der ternäre Operator [condition ? a : b] gibt [a] zurück, wenn die Bedingung wahr ist, und andernfalls [b].

Die Routing-Tabelle deklariert POST-Routen, und [bootstrap/app.php] deaktiviert den CSRF-Schutz für diese URLs, wie in Beispiel 02 gezeigt:

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

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

Route::prefix('post')->controller(PostController::class)->group(function () {
    Route::post('action01', 'action01');
    Route::post('action02', 'action02');
    Route::post('action03', 'action03');
    Route::post('action04', 'action04');
});
<?php
// bootstrap/app.php: die Anwendung von Beispiel 11

use App\Http\Middleware\ReadableJson;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;

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

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(web: __DIR__.'/../routes/web.php')
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->append(ReadableJson::class);
        // die von curl gesendeten POST-Anfragen würden den CSRF-Schutz
        // (Beispiel 21) nicht passieren
        $middleware->preventRequestForgery(except: ['post/*']);
    })
    ->withExceptions()
    ->create();

Mit [curl] sendet die Option [-d] (*data*) einen Body; die Anfrage wird dann zu einer POST-Anfrage vom Typ [application/x-www-form-urlencoded], es sei denn, die Option [-H] (*header*) gibt einen anderen Typ an. Die Option [-X POST] legt die Methode ausdrücklich fest (hier ist sie optional). Die Felder eines Formulars, einschließlich eines wiederholten Felds:

curl -i -g -X POST -d "name=martin&age=42&hobby[]=tennis&hobby[]=piano" http://localhost:8000/post/action01
HTTP/1.1 200 OK
Content-Type: application/json

{
    "receivedType": "application/x-www-form-urlencoded",
    "fields": {
        "name": "martin",
        "age": "42",
        "hobby": [
            "tennis",
            "piano"
        ]
    }
}

Ein JSON-Body, der eine ganze Zahl und ein Array enthält:

curl -i -H "Content-Type: application/json" -d "{\"name\": \"martin\", \"age\": 42, \"children\": [\"léa\", \"tom\"]}" http://localhost:8000/post/action02
HTTP/1.1 200 OK
Content-Type: application/json

{
    "receivedType": "application/json",
    "body": {
        "name": "martin",
        "age": 42,
        "children": [
            "léa",
            "tom"
        ]
    },
    "name": "martin"
}

Den Anführungszeichen in JSON wird [\] vorangestellt, damit die Befehlszeichenkette nicht endet; unter [Linux] und [macOS] können Sie das JSON auch in Apostrophe einschließen: [-d '{"name": "martin"}']. Anders als Formularfelder überträgt JSON Datentypen: Das Alter ist bereits eine ganze Zahl. Ein Body, der kein JSON ist, gefolgt von einem fehlerhaften JSON (wir fordern eine JSON-Antwort an, um die Meldung zu sehen):

curl -i -H "Accept: application/json" -d "name=martin" http://localhost:8000/post/action02
curl -i -H "Accept: application/json" -H "Content-Type: application/json" -d "{\"name\": " http://localhost:8000/post/action02
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json

{
    "message": "the body of the request must be JSON",
    ...
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "Malformed JSON: Syntax error",
    ...
}

Ein einzelnes Feld, dann dieselbe URL als GET angefordert:

curl -d "name=jean%20dupont" http://localhost:8000/post/action03
curl -i "http://localhost:8000/post/action03?name=martin"
1
2
3
4
5
name = [jean dupont]
HTTP/1.1 405 Method Not Allowed
allow: POST
Content-Type: text/html; charset=utf-8
...

Die URL existiert, aber nicht für die Methode GET: [Laravel] gibt eine 405 (*Method Not Allowed*) zurück, und sein Header [allow] listet die akzeptierten Methoden auf. Schließlich die auf die Formularfelder angewendeten Regeln, die zunächst erfüllt und dann nicht erfüllt waren:

curl -d "name=martin&age=42&title=Mr" http://localhost:8000/post/action04
curl -d "name=m&age=200" http://localhost:8000/post/action04
{
    "person": {
        "name": "martin",
        "age": "42",
        "title": "Mr"
    },
    "valid": true,
    "errors": []
}
{
    "person": null,
    "valid": false,
    "errors": [
        "age: the value must be between 0 and 150",
        "name: 2 character(s) at least",
        "title: the field is required"
    ]
}

3.6. Beispiel 12: Eigenes Binding und eigene Validierung

Standardtypen und Standardregeln reichen nicht immer aus. Dieses Beispiel zeigt drei Möglichkeiten, Binding und Validierung zu erweitern:

  • ein an einen Routenparameter gebundener Typ: ein Datum im französischen Format, [23-09-2026], im Pfad der URL;
  • eine Middleware, die der Action einen Parameter bereitstellt, der nicht aus der URL, sondern aus einem HTTP-Header stammt;
  • eine eigene Validierungsregel (keine Leerzeichen) und die Umwandlung eines Datums im Format [dd/mm/yyyy].
12-custom-binding/
├── app/
│   ├── Http/
│   │   ├── Controllers/
│   │   │   └── ExamplesController.php
│   │   └── Requests/
│   │       └── SearchRequest.php
│   └── Binding/
│       ├── DetectLanguage.php
│       ├── DayFr.php
│       └── NoSpace.php
├── lang/
│   └── en/
│       └── validation.php
└── ...

3.6.1. Ein an einen Routenparameter gebundener Typ: app/Binding/DayFr.php

Wir haben in Beispiel 02 gesehen, dass ein Routenparameter als Zeichenkette an die Action übergeben wird, oder als ganze Zahl, wenn der Parameter der Action den Typ [int] hat. [Laravel] kann einen Routenparameter auch in ein Objekt umwandeln, wenn die Action einen Parameter verlangt, dessen Klasse das Interface [UrlRoutable] implementiert. Das ist das Route Binding (*route model binding*), das [Laravel] hauptsächlich für Datenbankentitäten verwendet (ein Bezeichner in der URL wird zum entsprechenden Objekt; siehe Kapitel 9). Wir verwenden es hier für ein Datum.

<?php
// app/Binding/DayFr.php: ein französisches Datum "23-09-2026" im Pfad der URL

namespace App\Binding;

use Carbon\CarbonImmutable;
use Illuminate\Contracts\Routing\UrlRoutable;

// ein Typ, der sich an einen Routenparameter BINDEN (resolveRouteBinding) und
// wieder zu einem Teil der URL werden kann (getRouteKey): das Interface UrlRoutable
class DayFr implements UrlRoutable
{
    public function __construct(public ?CarbonImmutable $date = null)
    {
    }

    // Text des Pfads -> DayFr-Objekt; null: der Wert ist ungeeignet (Fehler 404)
    public function resolveRouteBinding($value, $field = null): ?static
    {
        // das ! in "!d-m-Y" setzt die Uhrzeit auf null (andernfalls wäre es die aktuelle Uhrzeit)
        $date = CarbonImmutable::createFromFormat('!d-m-Y', $value);
        // createFromFormat akzeptiert "31-02-2026" (und macht daraus den 3. März): wir prüfen,
        // ob das erneut formatierte Datum den empfangenen Text ergibt
        if ($date === null || $date->format('d-m-Y') !== $value) {
            return null;
        }
        return new static($date);
    }

    // DayFr-Objekt -> Text des Pfads (von der Funktion route verwendet)
    public function getRouteKey(): string
    {
        return $this->date->format('d-m-Y');
    }

    public function getRouteKeyName(): string
    {
        return 'day';
    }

    public function resolveChildRouteBinding($childType, $value, $field): ?static
    {
        return null;
    }
}
  • Zeile 11: Die Klasse implementiert das Interface [UrlRoutable], dessen vier Methoden folgen;
  • Zeile 13: das Datum, ein [CarbonImmutable]-Objekt. [Carbon] ist die Datumsbibliothek von [Laravel]; sie erweitert die Klasse [DateTime] von [PHP] um Hunderte von Methoden. Die [Immutable]-Variante erzeugt bei jeder Änderung ein neues Objekt ([$date->addDay()] gibt ein neues Datum zurück), statt das bestehende Objekt zu verändern. Der Konstruktor hat den Standardwert [null]: [Laravel] muss ein leeres [DayFr]-Objekt erstellen können, dessen Methode [resolveRouteBinding] es anschließend aufruft;
  • Zeilen 18–27: [resolveRouteBinding] wandelt den Pfadtext in ein Objekt um: Es gibt das gebundene Objekt zurück oder [null] , wenn der Wert ungültig ist. [CarbonImmutable::createFromFormat] liest eine Zeichenkette anhand eines Formats ein: [d] für den Tag, [m] für den Monat und [Y] für das vierstellige Jahr; das vorangestellte [!] setzt die Uhrzeit auf null. [createFromFormat] ist tolerant: Es akzeptiert [31-02-2026] und interpretiert es als 3. März. Die Prüfung in Zeile 24 weist diesen Fall zurück: Das Datum muss nach der Neuformatierung exakt dem empfangenen Text entsprechen. [new static(...)] erstellt ein Objekt der aktuellen Klasse. Gibt die Methode [null] zurück, [Laravel] antwortet mit einem 404-Fehler: Die URL verweist auf nichts;
  • Zeilen 31–34: die Umkehroperation, die von der Funktion [route] verwendet wird, um aus einem [DayFr]-Objekt eine URL zu erzeugen. [format] formatiert ein Datum;
  • Zeilen 36–41: Die letzten beiden Methoden des Interfaces, die für Datenbankentitäten verwendet werden, spielen hier keine Rolle.

3.6.2. Ein von einer Middleware bereitgestellter Parameter: app/Binding/DetectLanguage.php

Eine [Laravel]-Action erhält als Parameter die Routenparameter und die Objekte, die der Container bereitstellen kann (die Anfrage, die Services). Um ihr zusätzliche, aus der Anfrage berechnete Informationen zu liefern, können wir sie von einer Middleware berechnen lassen (Beispiel 03), die sie vor der Action in die Anfrage aufnimmt:

<?php
// app/Binding/DetectLanguage.php: eine Middleware, die eine Information für die Action BERECHNET

namespace App\Binding;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class DetectLanguage
{
    public function handle(Request $request, Closure $next): Response
    {
        // der Header "Accept-Language: fr-FR,fr;q=0.9,en;q=0.8" -> "fr": die bevorzugte
        // Sprache des Browsers unter den angebotenen (standardmäßig die erste)
        $language = $request->getPreferredLanguage(['fr', 'en']);
        // die ATTRIBUTE der Anfrage: Informationen, die die Anwendung dort ablegt
        // für die Funktionen, die die Anfrage danach bearbeiten
        $request->attributes->set('language', $language);
        return $next($request);
    }
}
  • Zeile 16: Der Anfrage-Header [Accept-Language] gibt die Sprachen des Benutzers in der Reihenfolge ihrer Präferenz an: [fr-FR,fr;q=0.9,en;q=0.8] (der Koeffizient [q] misst die Präferenz auf einer Skala von 0 bis 1). [getPreferredLanguage] wählt aus den von der Anwendung angebotenen Sprachen diejenige aus, die der Benutzer bevorzugt; ist kein Header vorhanden, ist es die erste der Liste;
  • Zeile 19: Die Anfrage besitzt Attribute – ein Array von Informationen, die die Anwendung dort für die Funktionen ablegt, die die Anfrage anschließend verarbeiten. Die Sprache wird dort unter dem Namen [language] abgelegt;
  • Zeile 20: Die Anfrage läuft weiter zur Action.

Die Action erhält diese Information über ein [PHP]-Attribut , das vor ihrem Parameter steht (siehe Controller).

3.6.3. Eine „eigene“ Regel und eine Umwandlung: NoSpace.php und SearchRequest.php

<?php
// app/Binding/NoSpace.php: eine "selbstgeschriebene" Validierungsregel

namespace App\Binding;

use Closure;
use Illuminate\Contracts\Validation\ValidationRule;

class NoSpace implements ValidationRule
{
    // der Wert ist ungeeignet: wir rufen $fail mit der Fehlermeldung auf
    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        if (str_contains((string) $value, ' ')) {
            $fail('the field must not contain a space');
        }
    }
}
  • Zeile 9: Eine „eigene“ Validierungsregel ist eine Klasse, die das Interface [ValidationRule] implementiert;
  • Zeilen 12–17: Ihre Methode [validate] erhält den Feldnamen, seinen Wert und eine Funktion, [$fail], die sie mit der Fehlermeldung aufruft, wenn der Wert ungültig ist. [str_contains] prüft, ob ein Text in einer Zeichenkette vorkommt; [(string)] wandelt den Wert in eine Zeichenkette um. Der Typ [mixed] steht für einen beliebigen Typ.

Die Regel wird von der Anfrage des Suchformulars verwendet:

<?php
// app/Http/Requests/SearchRequest.php: das Modell der Suche

namespace App\Http\Requests;

use App\Binding\NoSpace;
use Carbon\CarbonImmutable;
use Illuminate\Contracts\Validation\Validator;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Http\Exceptions\HttpResponseException;

class SearchRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            // eine "selbstgeschriebene" Regel: ein Objekt in einer Liste von Regeln
            'keyword' => ['nullable', new NoSpace()],
            // date_format: ein Datum im Format dd/mm/yyyy
            'since' => 'nullable|date_format:d/m/Y',
        ];
    }

    // das Datum, in ein Datumsobjekt UMGEWANDELT (null, falls es fehlt)
    public function since(): ?CarbonImmutable
    {
        return $this->date('since', 'd/m/Y')?->toImmutable();
    }

    // die Antwort auf eine fehlgeschlagene Validierung, nur für DIESE Klasse: die Meldung
    // des ersten Fehlers als Klartext, mit dem Code 400
    protected function failedValidation(Validator $validator): never
    {
        throw new HttpResponseException(response($validator->errors()->first(), 400,
            ['Content-Type' => 'text/plain; charset=utf-8']));
    }
}
  • Zeile 18: Die Regeln eines Felds können in einem Array statt als Zeichenkette angegeben werden; das ist für eine „eigene“ Regel, die ein Objekt ist, unerlässlich;
  • Zeile 20: Die Regel [date_format:d/m/Y] prüft, ob der Wert ein Datum im angegebenen Format ist und ob dieses Datum existiert;
  • Zeilen 25–28: Umwandlung des Datums: Die Methode [date] einer Anfrage liest einen Parameter und wandelt ihn gemäß dem angegebenen Format in ein Datum ([Carbon]) um; sie gibt [null] zurück, wenn der Parameter fehlt. Der Operator [?->] ruft eine Methode auf, wenn das Objekt nicht [null] ist, und gibt andernfalls [null] zurück; [toImmutable] wandelt das Datum in [CarbonImmutable] um;
  • Zeilen 32–36: Die Methode [failedValidation], geerbt von [FormRequest], wird aufgerufen, wenn die Validierung fehlschlägt; die Methode in [FormRequest] löst die Exception [ValidationException] aus (Beispiel 08). Wir überschreiben sie, nur für diese Klasse: Sie löst eine [HttpResponseException] aus, eine Exception, die eine vorgefertigte Antwort transportiert, die [Laravel] unverändert sendet. Die Antwort enthält die erste Fehlermeldung ([first()]) als Klartext mit dem Statuscode 400. So lassen sich die Validierungsfehler einer Action anders behandeln als die im Rest der Anwendung.

Die Meldung zur Regel [date_format] wird durch die Datei [lang/en/validation.php] angepasst:

1
2
3
4
5
6
<?php
// lang/en/validation.php: die Meldungen der Validierungsfehler, auf Englisch
return [
    // :input: der empfangene Wert
    'date_format' => '[:input] is not a valid dd/mm/yyyy date',
];
  • Zeile 5: Der Platzhalter [:input] wird durch den empfangenen Wert ersetzt.

3.6.4. Der Controller: app/Http/Controllers/ExamplesController.php

<?php
// app/Http/Controllers/ExamplesController.php: benutzerdefiniertes Binding und Validierung

namespace App\Http\Controllers;

use App\Http\Requests\SearchRequest;
use App\Binding\DayFr;
use Illuminate\Container\Attributes\RequestAttribute;

class ExamplesController
{
    // /examples/schedule/23-09-2026: der Routenparameter {day} wird an ein DayFr-
    // Objekt GEBUNDEN, weil die Action einen Parameter dieses Typs anfordert
    public function schedule(DayFr $day): string
    {
        // route() verwendet die Methode getRouteKey von DayFr: Objekt -> "23-09-2026"
        return "schedule for the day [{$day->date->toDateString()}], of type "
            .get_debug_type($day->date).', URL: '.route('schedule', $day, false);
    }

    // /examples/hello: ein Parameter, der nicht aus der URL stammt, sondern aus einem Header,
    // von der Middleware DetectLanguage berechnet und in den Attributen der Anfrage gespeichert
    public function hello(#[RequestAttribute('language')] string $language): string
    {
        return $language === 'en' ? 'Hello!' : 'Bonjour !';
    }

    // /examples/search?keyword=laravel&since=01/09/2026
    public function search(SearchRequest $request): string
    {
        $keyword = $request->validated('keyword');
        $since = $request->since()?->toDateString();
        return "search for [$keyword] since [$since]";
    }
}
  • Zeilen 14–18: Der Parameter [$day] hat den Typ [DayFr]: [Laravel] bindet den Routenparameter [{day}] mithilfe seiner Methode [resolveRouteBinding] an ein [DayFr]-Objekt. [toDateString()] schreibt das Datum im internationalen Format ([2026-09-23]). Die Funktion [route] erzeugt die URL für dieselbe Action aus dem Objekt, mithilfe seiner Methode [getRouteKey]; ihr dritter Parameter, [false], verlangt eine relative URL (ohne Protokoll und Rechnername);
  • Zeilen 23–25: Dem Parameter [$language] geht ein [PHP]-Attribut voraus, geschrieben als [#[...]]: eine dem Code beigefügte Information, die [PHP] ignoriert, die aber Bibliotheken lesen (das Äquivalent der Annotationen in [Java]). Das Attribut [RequestAttribute('language')] weist den Container an, für diesen Parameter das Attribut [language] der Anfrage bereitzustellen, das von der Middleware [DetectLanguage] berechnet wurde;
  • Zeilen 29–33: Die Action erhält den bereits validierten Form Request (Beispiel 08). [validated('keyword')] gibt ein einzelnes validiertes Feld zurück; [since()] gibt das umgewandelte Datum zurück.

Die Routing-Tabelle:

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

use App\Http\Controllers\ExamplesController;
use App\Binding\DetectLanguage;
use Illuminate\Support\Facades\Route;

Route::prefix('examples')->controller(ExamplesController::class)->group(function () {
    // where: nur ein Pfadstück der Form dd-mm-yyyy wird an DayFr weitergegeben
    Route::get('schedule/{day}', 'schedule')->name('schedule')
        ->where('day', '[0-9]{2}-[0-9]{2}-[0-9]{4}');
    // middleware: DetectLanguage läuft vor der Action
    Route::get('hello', 'hello')->middleware(DetectLanguage::class);
    Route::get('search', 'search');
});
  • Zeilen 10–11: Die Kalenderroute hat einen Namen (für die Funktion [route]), und ihr Parameter wird durch einen regulären Ausdruck eingeschränkt: [[0-9]] steht für eine einzelne Ziffer, [{2}] steht für die Wiederholung des vorangehenden Musters: zwei Ziffern, ein Bindestrich, zwei Ziffern, ein Bindestrich, vier Ziffern. Ein Pfadsegment mit einem anderen Format passt nicht zur Route (404), ohne dass [DayFr] überhaupt befragt wird;
  • Zeile 13: Die Methode [middleware] ordnet einer Route eine Middleware zu: Sie wird nur für diese Route ausgeführt, und zwar vor der Action. Diesem Vorgehen begegnen wir im gesamten Kurs wieder: Middlewares, die einen angemeldeten Benutzer verlangen, werden im Kapitel über die Authentifizierung auf dieselbe Weise Routen zugeordnet.

3.6.5. Ausführung

Der an den Routenparameter gebundene Typ:

curl "http://localhost:8000/examples/schedule/23-09-2026"
curl -i "http://localhost:8000/examples/schedule/31-02-2026"
1
2
3
4
schedule for the day [2026-09-23], of type Carbon\CarbonImmutable, URL: /examples/schedule/23-09-2026
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8
...

Das Datum wird im internationalen Format angezeigt, aber die von [route] erzeugte URL ist zum französischen Format zurückgekehrt. Den 31. Februar gibt es nicht: 404. Ein Datum im internationalen Format, [2026-09-23], entspricht nicht dem durch den regulären Ausdruck beschriebenen Muster: ebenfalls 404.

Die Middleware. Die Option [-H] von [curl] setzt den Header [Accept-Language]:

1
2
3
curl -H "Accept-Language: en-US,en;q=0.9,fr;q=0.8" http://localhost:8000/examples/hello
curl -H "Accept-Language: fr-FR,fr;q=0.9" http://localhost:8000/examples/hello
curl http://localhost:8000/examples/hello
1
2
3
Hello!
Bonjour !
Bonjour !

Ohne den Header [Accept-Language] ([curl] sendet keinen) ist es die erste Sprache der Liste. Das Kapitel über die Internationalisierung greift diese Frage wieder auf, wobei der Benutzer die Sprache auswählt.

Die „eigene“ Regel und die Datumsumwandlung:

1
2
3
4
5
curl "http://localhost:8000/examples/search?keyword=laravel&since=01/09/2026"
curl "http://localhost:8000/examples/search"
curl -i "http://localhost:8000/examples/search?keyword=laravel%20mvc"
curl "http://localhost:8000/examples/search?since=2026-09-01"
curl "http://localhost:8000/examples/search?since=31/02/2026"
1
2
3
4
5
6
7
8
search for [laravel] since [2026-09-01]
search for [] since []
HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8

the field must not contain a space
[2026-09-01] is not a valid dd/mm/yyyy date
[31/02/2026] is not a valid dd/mm/yyyy date

3.6.6. Fazit

Fassen wir die Möglichkeiten zusammen, die einer Action zur Verfügung stehen, um ihr Modell zu erhalten:

Routenparameter
die Parameter der Action, die denselben Namen tragen; umgewandelt anhand ihres Typs ([int $id]), eingeschränkt durch [whereNumber], [where] ...; gebunden an ein Objekt durch [UrlRoutable]
Parameter der URL
[$request->query(...)], [integer], [array], [date] ...; ein wiederholter Parameter wird als [name[]] geschrieben
Felder eines POST-Formulars
[$request->post(...)] oder [$request->input(...)], das überall sucht
JSON-Body
[$request->input(...)], [$request->json()] oder [json_decode($request->getContent())]
Header
[$request->header(...)] und Methoden, die sie auswerten, wie [getPreferredLanguage]
Validierung
von Regeln: ein [FormRequest] (Validierung vor der Action) oder [Validator::make] (Validierung durch die Action); „eigene“ Regeln ([ValidationRule])
Meldungen
die Dateien [lang/xx/validation.php] und die Sprachdatei [APP_LOCALE]
Häufige Fehler
[$exceptions->render(...)] in [bootstrap/app.php] (gesamte Anwendung), [failedValidation] (ein Form Request)
Berechneter Parameter
Eine Middleware, die Informationen in den Attributen der Anfrage ablegt, [#[RequestAttribute]]

HTML-Formulare benötigen dagegen mehr als nur Validierung: Sie müssen angezeigt werden, mit den Eingaben des Benutzers und etwaigen Fehlern erneut angezeigt werden und vor gefälschten Anfragen geschützt sein. Das ist das Thema des nächsten Kapitels, nachdem die Views eingeführt wurden.