Skip to content

3. Das Action-Modell

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 Anfrage. Der Originalkurs bezeichnet all diese Informationen als das Modell der Action. Dieses Kapitel zeigt, wie eine [Symfony]-Action diese Informationen abruft, in den richtigen Typ umwandelt und validiert. Dieser Vorgang heißt Datenbindung (Data Binding).

[Symfony] bietet Zugriff auf die Informationen der Anfrage über das [Request]-Objekt (Beispiel 05), in Form von Zeichenketten, samt einigen Konvertierungsmethoden. Es kann diese Informationen außerdem binden (an die Parameter einer Action anhand von Attributen ([#[MapQueryParameter]], [#[MapQueryString]], [#[MapRequestPayload]]) und validieren mit seiner Validator-Komponente: Wir beschreiben die erwarteten Daten mithilfe von Constraints („erforderlich“, „eine ganze Zahl zwischen 0 und 150“ usw.), die als Attribute wie [PHP] geschrieben werden, und der Validator prüft, ob die Daten ihnen entsprechen. Wir lesen die Parameter zunächst manuell (Beispiel 07) und überlassen dann dem Framework ihre Konvertierung und Validierung (Beispiele 08 bis 12). Im nächsten Kapitel validieren dieselben Constraints die HTML-Formulare.

Beachten Sie die Terminologie: Im nächsten Kapitel bezeichnet das Wort „Modell“ vor allem die Daten, die eine Action an ihre View übergibt. Das Modell einer Action im Sinne dieses Kapitels ist das, was sie empfängt.

Die Beispiele 07 bis 12 werden auf dieselbe Weise ausgeführt wie die des vorigen Kapitels: ein im Beispielordner geöffnetes Terminal, [php -S localhost:8000 -t public]; [Ctrl-C] beendet den Server. Die meisten verwenden den Listener [ReadableJson] aus Beispiel 03, der ein lesbares JSON liefert. Ihre Konfigurationsdateien kommentieren wir nur dann, wenn sie etwas Neues einführen.

3.1. Beispiel 07: Die Parameter der URL

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

<?php
// src/Controller/ParametersController.php: die Parameter der URL (der „Query-String“)

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\MapQueryParameter;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/parameters', name: 'parameters_', methods: ['GET'])]
class ParametersController extends AbstractController
{
    // /parameters/action01?name=martin: $request->query enthält die Parameter der
    // URL; get gibt den Wert eines Parameters zurück oder null, wenn er fehlt
    #[Route('/action01', name: 'action01')]
    public function action01(Request $request): Response
    {
        $name = $request->query->get('name');
        return new Response("name = [$name], of type ".get_debug_type($name));
    }

    // /parameters/action02?age=42: getInt WANDELT den Wert (einen String) in eine
    // Ganzzahl um; ein fehlender Parameter ergibt 0, ein Wert, der keine Ganzzahl ist,
    // einen Fehler 400
    #[Route('/action02', name: 'action02')]
    public function action02(Request $request): Response
    {
        $age = $request->query->getInt('age');
        return new Response("age = [$age], of type ".get_debug_type($age));
    }

    // /parameters/action03?age=42: ein ERFORDERLICHER Parameter, von Hand umgewandelt;
    // sein Fehlen oder ein Wert, der keine Ganzzahl ist, erzeugt eine 400-Antwort
    #[Route('/action03', name: 'action03')]
    public function action03(Request $request): Response
    {
        $text = $request->query->get('age');
        if ($text === null) {
            // eine HTTP-Exception: Symfony wandelt sie in eine 400-Antwort um (Bad Request)
            throw new BadRequestHttpException('the [age] parameter is required');
        }
        // filter_var gibt die im String enthaltene Ganzzahl zurück oder false
        $age = filter_var($text, FILTER_VALIDATE_INT);
        if ($age === false) {
            throw new BadRequestHttpException("[$text] is not an integer");
        }
        return new Response("age = [$age], of type ".get_debug_type($age));
    }

    // /parameters/action04?page=2: ein Standardwert, falls der Parameter fehlt
    #[Route('/action04', name: 'action04')]
    public function action04(Request $request): Response
    {
        $page = $request->query->getInt('page', 1);
        return new Response("page = [$page]");
    }

    // /parameters/action05?q=symfony: Der Name des URL-Parameters ist nicht zwingend
    // der Name der PHP-Variablen
    #[Route('/action05', name: 'action05')]
    public function action05(Request $request): Response
    {
        $search = $request->query->get('q');
        return new Response("search = [$search]");
    }

    // /parameters/action06?name=martin&age=42: alle Parameter auf einmal als Array
    #[Route('/action06', name: 'action06')]
    public function action06(Request $request): JsonResponse
    {
        return $this->json($request->query->all());
    }

    // /parameters/action07?age=42&page=2: Das Attribut #[MapQueryParameter] BINDET einen
    // URL-Parameter an den gleichnamigen Parameter der Action und wandelt ihn in
    // dessen Typ um. Ein Parameter ohne Standardwert ist erforderlich
    #[Route('/action07', name: 'action07')]
    public function action07(#[MapQueryParameter] int $age, #[MapQueryParameter] int $page = 1): Response
    {
        return new Response("age = [$age], page = [$page]");
    }
}
  • Zeile 22: Die Eigenschaft [query] der Anfrage enthält die Parameter der URL in einer Parameter-„Bag“ (einem [InputBag]-Objekt), deren Methode [get] den – bereits dekodierten – Wert eines Parameters zurückgibt oder [null] , falls er fehlt;
  • Zeile 23: 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 32: Die Methode [getInt] liest den Parameter und konvertiert ihn in eine ganze Zahl. Ein fehlender Parameter ergibt 0; ein Wert, der keine ganze Zahl ist ([abc]), führt zu einem 400-Fehler (Bad Request). Ebenso gibt es [getBoolean] ([1], [true], [on] und [yes] gelten als wahr), [getString], [getAlpha] (nur Buchstaben), [getDigits] (nur Ziffern), [getEnum] (eine Aufzählung);
  • Zeilen 41–51: ein erforderlicher Parameter und eine manuelle Konvertierung, die zwischen den beiden möglichen Fehlern unterscheidet. [throw new BadRequestHttpException(message)] beendet den Vorgang mit einer 400-Antwort samt der Meldung (siehe Beispiel 03, in dem auch eine 404-Exception ausgelöst wurde). 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 58: Der zweite Parameter von [getInt] ist ein Standardwert, der verwendet wird, wenn der Parameter fehlt. Das ist typischerweise bei einer Seitennummer in einer Liste der Fall;
  • Zeile 67: Die [PHP] -Variable muss nicht denselben Namen wie der Parameter der URL tragen. Suchmaschinen verwenden oft einen kurzen Parameter, [q] (query);
  • Zeile 75: [all()] gibt alle Parameter der URL in einem assoziativen Array zurück, das die Action in JSON umwandelt (siehe Beispiel 03);
  • Zeilen 81–85: der deklarative Ansatz. Das Attribut [#[MapQueryParameter]], das vor einen Action-Parameter gesetzt wird, verknüpft diesen Parameter mit dem gleichnamigen Parameter der URL und konvertiert ihn in den deklarierten Typ ([int]). Ein Parameter ohne Standardwert ist erforderlich: Fehlt er oder lässt er sich nicht konvertieren, führt das zu einem 404-Fehler (die URL verweist, wie geschrieben, auf keine gültige Seite). Ein Standardwert ([$page = 1]) macht ihn optional. Genau das leisten die Zeilen 41–51 in einer einzigen Zeile.

Testen wir jede Action mit [curl]. Zuerst mit vorhandenem Parameter, dann ohne:

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 die 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 kodiert 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] dekodiert den Wert, bevor die Action ihn liest:

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

Konvertierung mit [getInt] – erfolgreich, fehlgeschlagen, dann ohne Parameter:

1
2
3
curl "http://localhost:8000/parameters/action02?age=42"
curl -i "http://localhost:8000/parameters/action02?age=abc"
curl http://localhost:8000/parameters/action02
1
2
3
4
5
6
age = [42], of type int
HTTP/1.1 400 Bad Request
Content-Type: text/html; charset=UTF-8
X-Debug-Exception: Input%20value%20%22age%22%20cannot%20be%20converted%20to%20%22int%22.
...
age = [0], of type int

[Symfony] weigert sich, [abc] in eine ganze Zahl zu konvertieren: Das ist ein Client-Fehler, daher der Code 400 („Input value 'age' cannot be converted to 'int'“). Ein fehlender Parameter dagegen ergibt stillschweigend 0: Die Action kann diesen Fall nicht von einem tatsächlich eingegebenen Alter von 0 unterscheiden. Der erforderliche Parameter der Action 03 fehlt und ist daher ungültig. Wir fordern eine JSON-Antwort an (Header [Accept], siehe Beispiel 03), die die Meldung der Exception 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"
1
2
3
4
5
HTTP/1.1 400 Bad Request
Content-Type: application/json

{"type":"https:\/\/tools.ietf.org\/html\/rfc2616#section-10","title":"An error occurred","status":400,"detail":"the [age] parameter is required","class":"Symfony\\Component\\HttpKernel\\Exception\\BadRequestHttpException","trace":[...]}
{"type":"https:\/\/tools.ietf.org\/html\/rfc2616#section-10","title":"An error occurred","status":400,"detail":"[abc] is not an integer","class":"Symfony\\Component\\HttpKernel\\Exception\\BadRequestHttpException","trace":[...]}

(Dieses kompakte JSON wird von unserem Listener nicht neu formatiert, siehe Beispiel 03). In einem Browser zeigt eine 400-Antwort im Debug-Modus die [Symfony]-Fehlerseite 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=symfony"
1
2
3
page = [1]
page = [3]
search = [symfony]

Alle Parameter auf einmal. Der Parameter [name] erscheint zweimal:

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 wieder begegnen. Das Alter ist eine Zeichenkette geblieben (["42"], in JSON in Anführungszeichen eingeschlossen): Es wurde keine Konvertierung 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 Kodierung akzentuierter Zeichen in der URL ([é] wird zu [%C3%A9], mit seinen zwei Bytes in [UTF-8]):

Image

Schließlich die Bindung über [#[MapQueryParameter]], mit und ohne den optionalen Parameter und dann mit einem ungültigen Alter:

1
2
3
curl "http://localhost:8000/parameters/action07?age=42"
curl "http://localhost:8000/parameters/action07?age=42&page=3"
curl -i "http://localhost:8000/parameters/action07?age=abc"
1
2
3
4
5
6
age = [42], page = [1]
age = [42], page = [3]
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=UTF-8
X-Debug-Exception: Invalid%20query%20parameter%20%22age%22.
...

Ohne den Parameter [age] würde die Meldung „Missing query parameter 'age'“ lauten. Der Code 404 mag überraschen: Das Attribut akzeptiert einen Parameter [validationFailedStatusCode], mit dem sich ein anderer wählen lässt ([#[MapQueryParameter(validationFailedStatusCode: 400)]]).

Dieses erste Beispiel veranschaulicht die Grenzen des manuellen Ansatzes: Für jeden Parameter müssen Sie das Lesen, die Konvertierung und die Behandlung fehlender Werte und Fehler schreiben. Bei zehn Parametern wäre der Code der Action von diesen Prüfungen überladen. [#[MapQueryParameter]] vereinfacht die Konvertierung, sagt aber nichts über die Regeln aus („eine Zeichenkette mit 2 bis 20 Zeichen“). Besser ist es, zu beschreiben, was erwartet wird, und das Framework die Prüfung vornehmen zu lassen. Genau das ist der Zweck des folgenden Beispiels.

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

Das Modell einer Action kann durch eine Klasse beschrieben werden: eine Eigenschaft pro erwartetem Parameter samt ihrem Typ und – in Form von Attributen – den Constraints , die sie erfüllen muss. [Symfony] erzeugt dann das Objekt selbst aus der Anfrage, validiert es und übergibt es an die Action. Die Constraints sind die Klassen der Validator-Komponente: [NotBlank] (erforderlich), [Length] (eine Länge), [Range] (ein Intervall), [Choice] (eine Liste von Werten), [Email], [Regex] ... [Symfony] stellt mehr als siebzig davon bereit.

3.2.1. Das Modell: src/Model/PersonModel.php

<?php
// src/Model/PersonModel.php: das Modell der Action, eine Klasse, die die
// erwarteten Parameter und ihre CONSTRAINTS (Validierungsregeln) beschreibt

namespace App\Model;

use Symfony\Component\Validator\Constraints as Assert;

readonly class PersonModel
{
    public function __construct(
        // erforderlich, dann ein String von 2 bis 20 Zeichen: Prüft nacheinander
        // die Constraints in der angegebenen Reihenfolge und stoppt beim ersten, der fehlschlägt
        #[Assert\Sequentially([
            new Assert\NotBlank(),
            new Assert\Length(min: 2, max: 20),
        ])]
        public ?string $name = null,
        // erforderlich, eine Ganzzahl zwischen 0 und 150
        #[Assert\NotNull]
        #[Assert\Range(min: 0, max: 150)]
        public ?int $age = null,
        // erforderlich, nur einer dieser drei Werte
        #[Assert\NotBlank]
        #[Assert\Choice(choices: ['Mr', 'Mme', 'Melle'])]
        public ?string $title = null,
        // optional; falls vorhanden, eine gültige E-Mail-Adresse
        #[Assert\Email]
        public ?string $email = null,
    ) {
    }
}
  • Zeile 7: Import des Constraints-Namespace unter dem Kurznamen [Assert]: Die Constraints werden als [Assert\NotBlank], [Assert\Length] ... geschrieben. Das ist in allen [Symfony]-Projekten üblich;
  • Zeilen 9–31: eine unveränderliche Klasse, deren Eigenschaften durch den Konstruktor initialisiert werden (Beispiel 03). Jede Eigenschaft hat einen Standardwert, [null], und einen nullable-Typ ([?string], [?int]: eine Zeichenkette oder [null]): Fehlt ein Parameter in der URL, ist die Eigenschaft standardmäßig [null], und ein Constraint bestimmt, ob sie erforderlich war. Das ist die übliche Art, diese Klassen zu schreiben;
  • Zeilen 14–18: Der Name ist erforderlich ([NotBlank] weist [null] und eine leere Zeichenkette zurück) und muss aus 2 bis 20 Zeichen bestehen ([Length]). Der Constraint [Sequentially] prüft die darin enthaltenen Constraints der Reihe nach und hält beim ersten fehlgeschlagenen an: Ein leerer Name erzeugt nur einen Fehler, nicht zwei. Die Parameter der Constraints sind benannt ([min: 2]), eine Anforderung seit [Symfony] 8;
  • Zeilen 20–22: Das Alter ist erforderlich ([NotNull]) und muss zwischen 0 und 150 liegen ([Range]). Sein Typ ist [?int]: [Symfony] wandelt die Zeichenkette aus der URL in eine ganze Zahl um;
  • Zeilen 24–26: Die Anrede ist erforderlich und muss einer der drei aufgeführten Werte sein ([Choice]);
  • Zeilen 28–29: Die E-Mail-Adresse ist optional (kein Constraint: [NotBlank]); falls angegeben, muss sie gültig sein. Mit Ausnahme eines Constraints, [NotBlank], akzeptieren alle übrigen [null]: Sie prüfen nur die vorhandenen Werte.

Dieses Modell beschreibt die erwarteten Daten; es enthält keine Validierungsanweisungen. Man spricht von einem deklarativen Stil.

3.2.2. Die Action: src/Controller/PersonsController.php

<?php
// src/Controller/PersonsController.php: eine Action, deren Modell eine Klasse ist

namespace App\Controller;

use App\Model\PersonModel;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\Attribute\MapQueryString;
use Symfony\Component\Routing\Attribute\Route;

class PersonsController extends AbstractController
{
    // /persons/action01?name=martin&age=42&title=Mr
    // #[MapQueryString]: Symfony baut ein PersonModel-Objekt aus den
    // Parametern der URL und VALIDIERT es VOR dem Aufruf der Action. Ein
    // ungültiges Modell löst eine Exception aus (siehe src/EventListener/ValidationErrors.php), und
    // die Action wird nie aufgerufen
    #[Route('/persons/action01', name: 'persons_action01', methods: ['GET'])]
    public function action01(Request $request, #[MapQueryString] PersonModel $person): JsonResponse
    {
        return $this->json([
            'received' => $request->query->all(),
            'person' => $person,
            'ageType' => get_debug_type($person->age),
        ]);
    }
}
  • Zeile 21: Das Attribut [#[MapQueryString]] weist [Symfony] an, den Parameter [$person] aus den Parametern der URL zu erzeugen. Ein Argument-Resolver (Beispiel 05) erledigt diese Aufgabe in zwei Schritten. Zuerst konvertiert er: Mithilfe des Serializers erzeugt er ein [PersonModel]-Objekt, in dem jede Eigenschaft den gleichnamigen Parameter der URL erhält, umgewandelt in den entsprechenden Typ. Danach validiert er das Objekt: Er prüft jeden Constraint jeder Eigenschaft. Ist alles korrekt, wird die Action aufgerufen. Andernfalls löst er eine Exception aus (eine [HttpException] mit dem Code 404, die eine [ValidationFailedException] enthält, die ihrerseits die Liste aller Fehler enthält, nicht nur des ersten), und die Action wird nie aufgerufen: Sie muss sich daher nicht um ungültige Daten kümmern;
  • Zeilen 23–27: Die Action gibt die empfangenen Parameter unverändert zurück, gefolgt vom [PersonModel]-Objekt und dem Typ des Alters, um den Unterschied zu veranschaulichen.

Wer behandelt die Exception? Standardmäßig [Symfony] selbst, über eine 404-Fehlerantwort (oder 422 bei [#[MapRequestPayload]], Beispiel 11): seine Fehlerseite oder, für einen Client, der JSON anfordert, ein Dokument, das die Fehler im Einzelnen aufführt. Hier wollen wir in jedem Fall eine Fehlerantwort in JSON mit dem Statuscode 400 und in unserem eigenen Format. Das ist die Aufgabe eines Listeners.

3.2.3. Fehlerbehandlung: src/EventListener/ValidationErrors.php

<?php
// src/EventListener/ValidationErrors.php: Ein ungültiges Modell erzeugt für die GESAMTE
// Anwendung eine 400-Antwort, die die Fehler im Detail auflistet

namespace App\EventListener;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Validator\Exception\ValidationFailedException;

// ein Listener des Ereignisses [kernel.exception], das ausgelöst wird, wenn eine Exception
// aus der Action (oder aus der Vorbereitung ihrer Parameter) herauskommt
#[AsEventListener(event: KernelEvents::EXCEPTION)]
class ValidationErrors
{
    public function __invoke(ExceptionEvent $event): void
    {
        // Die von #[MapQueryString] ausgelöste HTTP-Exception enthält die Exception der
        // Validierung, die die Liste der Fehler (die „Violations“) enthält
        $validation = $event->getThrowable()->getPrevious();
        if (! $validation instanceof ValidationFailedException) {
            return;    // eine andere Exception: Symfony behandelt sie wie gewohnt
        }
        $errors = [];
        foreach ($validation->getViolations() as $violation) {
            $errors[] = ['field' => $violation->getPropertyPath(), 'message' => $violation->getMessage()];
        }
        // Die Antwort des Ereignisses ersetzt die Fehlerseite von Symfony
        $event->setResponse(new JsonResponse(['status' => 400, 'errors' => $errors], 400));
    }
}
  • Zeile 15: ein Listener für das Ereignis [kernel.exception] (die Konstante [KernelEvents::EXCEPTION]). [Symfony] löst dieses Ereignis aus, wenn während der Action oder bei der Vorbereitung ihrer Parameter eine Exception auftritt, bevor die Action ihre eigene Fehlerantwort erzeugt. So deklariert, gilt der Listener für alle Actions der Anwendung: Jede Action, die ein Modell validiert, profitiert davon, ohne dass eine einzige Zeile Fehlerbehandlungscode geschrieben werden muss;
  • Zeile 22: Das Ereignis, ein [ExceptionEvent]-Objekt, trägt die Exception ([getThrowable()]). Die von [#[MapQueryString]] ausgelöste Exception ist eine HTTP-Exception; [getPrevious()] gibt die Exception zurück, die sie verursacht hat – die Validierungs-Exception;
  • Zeilen 23–25: Ist es kein Validierungsfehler, tut der Listener nichts: [Symfony] behandelt die Exception wie gewohnt. Der Operator [!] („nicht“) kehrt die Bedingung um;
  • Zeilen 26–29: [getViolations()] gibt die Liste der Fehler zurück, die (Constraint-) Verletzungen (Violations) genannt werden. Jede Verletzung hat einen Pfad ([getPropertyPath()], den Namen der fehlerhaften Eigenschaft) und eine Meldung. [$errors[] = ...] fügt am Ende des Arrays [$errors] ein Element hinzu;
  • Zeile 31: [setResponse] liefert dem Ereignis eine Antwort: eine JSON-Antwort mit dem Statuscode 400. [Symfony] sendet sie anstelle seiner Fehlerseite (und wie jede Antwort durchläuft sie den Listener [ReadableJson]).

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 empfangenen Parameter sind Zeichenketten; das [PersonModel]-Objekt enthält das Alter als ganze Zahl (in JSON ohne Anführungszeichen), und die fehlende Adresse ist [null]. Ein von Leerzeichen ([%20]) umgebener Name 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 blieben erhalten: [Symfony] verändert die empfangenen Daten nicht. Ein Constraint kann sie bei der Validierung ignorieren ([new Assert\Length(min: 2, normalizer: 'trim')]), doch der Wert bleibt der gesendete. Im nächsten Kapitel entfernt die Form-Komponente diese Leerzeichen. Nun ohne Parameter: Die drei erforderlichen Felder fehlen.

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

{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "This value should not be blank."
        },
        {
            "field": "age",
            "message": "This value should not be null."
        },
        {
            "field": "title",
            "message": "This value should not be blank."
        }
    ]
}

Vier ungültige Felder auf einmal:

curl "http://localhost:8000/persons/action01?name=m&age=200&title=Mlle&email=xx"
{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "This value is too short. It should have 2 characters or more."
        },
        {
            "field": "age",
            "message": "This value should be between 0 and 150."
        },
        {
            "field": "title",
            "message": "The value you selected is not a valid choice."
        },
        {
            "field": "email",
            "message": "This value is not a valid email address."
        }
    ]
}

Alle Fehler werden auf einmal gemeldet, sodass der Benutzer alles in einem Zug korrigieren kann. Schließlich ein Alter, das keine Zahl ist:

curl "http://localhost:8000/persons/action01?name=m&age=abc&title=Mlle&email=xx"
1
2
3
4
5
6
7
8
9
{
    "status": 400,
    "errors": [
        {
            "field": "age",
            "message": "This value should be of type int."
        }
    ]
}

Diesmal wird nur ein Fehler gemeldet, obwohl Name, Anrede und Adresse weiterhin ungültig sind. Das ist das Ergebnis des zweistufigen Vorgangs von [#[MapQueryString]]: Die Konvertierung schlug fehl ([abc] lässt sich nicht in eine ganze Zahl umwandeln), sodass das Objekt nicht erzeugt werden konnte und die Validierung – die das Objekt prüft – nicht stattfand. Die Meldungen sind auf Englisch, der Standardsprache von [Symfony]. Das folgende Beispiel passt einige davon an.

3.3. Beispiel 09: Validierung durch die Action

In Beispiel 08 unterbricht ein ungültiges Modell die Action, und der Listener der Anwendung antwortet. Das ist praktisch für eine API, deren Clients Programme sind, die eine standardisierte Fehlerantwort erwarten. Eine Webseite zieht es jedoch oft vor, das Formular erneut anzuzeigen – und zwar mit Fehlermeldungen: In diesem Fall muss die Action entscheiden, was mit einem ungültigen Modell geschieht. Sie ruft den Validator selbst auf.

09-action-validation/
├── config/
│   └── packages/
│       └── framework.yaml
├── src/
│   ├── Controller/
│   │   └── PersonsController.php
│   ├── Model/
│   │   └── PersonInput.php
│   └── Kernel.php
├── translations/
│   └── validators.en.yaml
└── ...

3.3.1. Das Modell: src/Model/PersonInput.php

<?php
// src/Model/PersonInput.php: die EINGABE einer Person, so wie sie ankommt
// (Strings), und die Constraints, die sie erfüllen muss

namespace App\Model;

use Symfony\Component\Validator\Constraints as Assert;

class PersonInput
{
    #[Assert\Sequentially([
        new Assert\NotBlank(),
        new Assert\Length(min: 2, max: 20),
    ])]
    public ?string $name = null;

    // ein String aus Ziffern (digit), dessen Wert zwischen 0 und 150 liegt;
    // message: eine für diese Constraint spezifische Meldung
    #[Assert\Sequentially([
        new Assert\NotBlank(),
        new Assert\Type('digit', message: 'an integer is expected'),
        new Assert\Range(min: 0, max: 150),
    ])]
    public ?string $age = null;

    #[Assert\NotBlank]
    #[Assert\Choice(choices: ['Mr', 'Mme', 'Melle'])]
    public ?string $title = null;

    #[Assert\Email]
    public ?string $email = null;
}

Diesmal beschreibt das Modell die Eingabe genau so, wie sie empfangen wird: Zeichenketten, die die Action selbst in das Objekt kopiert. Seine Eigenschaften sind daher gewöhnlich (weder befördert noch [readonly]), und alle haben den Typ [?string], auch das Alter:

  • Zeilen 19–24: Das Alter ist eine Zeichenkette, die vorhanden sein muss ([NotBlank]), nur Ziffern enthalten darf ([Type('digit')], das prüft, ob eine Zeichenkette nur Ziffern enthält) und deren Wert zwischen 0 und 150 liegen muss ([Range] akzeptiert eine Zeichenkette, die eine Zahl darstellt). Dank [Sequentially] wird ein Alter [abc] nur einmal gemeldet. Der Parameter [message] ersetzt die Meldung des Constraints durch unsere eigene: Jeder Constraint hat diesen Parameter (oder mehrere, wenn er mehrere Arten von Fehlern kennt, wie [minMessage] und [maxMessage] bei [Length]);
  • Die übrigen Eigenschaften haben die Constraints aus Beispiel 08.

3.3.2. Eigene Meldungen

Die Fehlermeldungen des Validators sind in seinem Code auf Englisch verfasst, durchlaufen jedoch den [Symfony] -Übersetzer (die Translation-Komponente), der sie in die Sprache der Anfrage übersetzt. [Symfony] liefert Übersetzungen seiner Meldungen in etwa sechzig Sprachen mit: Man muss lediglich die Sprache der Anwendung wählen und den Übersetzer aktivieren, und zwar in [config/packages/framework.yaml]:

1
2
3
4
5
6
7
8
# config/packages/framework.yaml: die Konfiguration des FrameworkBundle
framework:
    secret: '%env(APP_SECRET)%'
    # die Sprache der Anwendung: Die Validierungsmeldungen sind auf Englisch
    default_locale: en
    # der Übersetzungs-Service; seine Wörterbücher liegen im Ordner translations/
    translator:
        default_path: '%kernel.project_dir%/translations'
  • Zeile 5: die Standardsprache der Anwendung (Locale). Sie ist auch die Sprache jeder Anfrage, es sei denn, die Anwendung ändert sie (siehe das Kapitel über Internationalisierung);
  • Zeilen 7–8: der Übersetzer, dessen anwendungsspezifische Wörterbücher im Ordner [translations] liegen. [%kernel.project_dir%] ist ein Parameter des Containers: der Projektordner (Beispiel 01).

Die von [Symfony] übersetzten Meldungen sind nicht immer passend. Die Anwendung kann eigene Übersetzungen mitbringen, die Vorrang haben. Die Validierungsmeldungen liegen in der [validators] -Domäne; die englischen Übersetzungen dieser Domäne stehen in der Datei [translations/validators.en.yaml] (der Name eines Wörterbuchs setzt sich aus Domäne, Sprache und Format zusammen):

1
2
3
4
5
# translations/validators.en.yaml: unsere eigenen Übersetzungen der Validierungs-
# meldungen (Domain [validators]), die Vorrang vor denen von Symfony haben.
# Der Schlüssel ist die englische Originalmeldung
'This value should not be blank.': 'the field is required'
'The value you selected is not a valid choice.': 'unknown value'

Ein Wörterbuch ordnet jedem Schlüssel seine Übersetzung zu. Bei den Meldungen des Validators ist der Schlüssel die englische Originalmeldung: ['This value should not be blank.'] wird als „Das Feld ist erforderlich.“ angezeigt. Die Schlüssel stehen in einfachen Anführungszeichen, weil sie Zeichen (Punkte, Leerzeichen) enthalten, die in [YAML] eine besondere Bedeutung haben. Meldungen, die diese Datei nicht übersetzt, behalten die Übersetzung von [Symfony] (der Datei [vendor/symfony/validator/Resources/translations/validators.en.xlf]), und eine Meldung, die kein Wörterbuch kennt, wird unverändert angezeigt: Das ist bei unserer Meldung „an integer is expected“ der Fall.

3.3.3. Die Action: src/Controller/PersonsController.php

<?php
// src/Controller/PersonsController.php: Die Action entscheidet, was bei einer ungültigen Eingabe zu tun ist

namespace App\Controller;

use App\Model\PersonInput;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Validator\Validator\ValidatorInterface;

class PersonsController extends AbstractController
{
    // Der VALIDATOR, ein Service von Symfony, wird in die Action injiziert (siehe Beispiel 06)
    #[Route('/persons/action01', name: 'persons_action01', methods: ['GET'])]
    public function action01(Request $request, ValidatorInterface $validator): Response
    {
        // die Eingabe: die Parameter der URL, in das Objekt kopiert
        $input = new PersonInput();
        $input->name = $request->query->get('name');
        $input->age = $request->query->get('age');
        $input->title = $request->query->get('title');
        $input->email = $request->query->get('email');
        // validate prüft die Constraints des Objekts und gibt die Liste der Fehler zurück
        $errors = $validator->validate($input);
        if (count($errors) > 0) {
            $items = '';
            foreach ($errors as $error) {
                $items .= "<li>{$error->getPropertyPath()}: {$error->getMessage()}</li>";
            }
            return new Response("<p>The form contains errors:</p><ul>$items</ul>");
        }
        // htmlspecialchars: Der eingegebene Name wird in HTML eingefügt; seine Zeichen
        // < > & " ' werden durch &lt; &gt;... ersetzt (sonst könnte eine Eingabe HTML einschleusen)
        return new Response("<p>Welcome $input->title ".htmlspecialchars($input->name)
            ." ($input->age years old)</p>");
    }
}
  • Zeile 17: Der Validator, ein Service von [Symfony] (vom Typ [ValidatorInterface]), wird wie ein Anwendungsservice in die Action injiziert (Beispiel 06);
  • Zeilen 20–24: Die Action erzeugt das Objekt und kopiert die Parameter der URL hinein. Wir hätten, wie in Beispiel 08, [#[MapQueryString]] das Objekt erzeugen lassen können; [#[MapQueryString]] validiert es jedoch sofort und beendet die Action im Fehlerfall – genau das wollen wir hier vermeiden;
  • Zeile 26: [validate] prüft die Constraints des Objekts und gibt eine Liste von Verletzungen zurück (ein [ConstraintViolationList]-Objekt, das wie ein Array durchlaufen wird und dessen Größe [count] zurückgibt). Die Validierung löst keine Exceptions aus: Die Action selbst entscheidet, wie es weitergeht;
  • Zeilen 27–33: die Fehler, Feld für Feld, jeweils in ein [<li>]-Tag eingeschlossen. In einer Zeichenkette in Anführungszeichen [{$error->getMessage()}] fügt das Ergebnis eines Methodenaufrufs ein (geschweifte Klammern begrenzen den Ausdruck). Der Operator [.=] hängt eine Zeichenkette an das Ende einer anderen an;
  • Zeilen 36–37: Bei Erfolg erscheint eine Willkommensnachricht. Der Name wird durch die Funktion [htmlspecialchars] von [PHP] geleitet, die Zeichen mit besonderer Bedeutung in HTML ([<], [>], [&], ["], [']) durch ihre Entitäten ([&lt;], [&gt;] ...) ersetzt: 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 Betrachters der Seite ausgeführt würde. Das ist die häufigste Sicherheitslücke im Web: die Skriptinjektion (XSS, Cross-Site-Scripting). Die Felder Anrede und Alter benötigen diesen Schutz nicht: Ihre Werte wurden durch Constraints validiert (einer von drei zulässigen Werten, ausschließlich Ziffern). Im nächsten Kapitel übernimmt die View-Engine [Twig] 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 Meldungen sind auf Englisch: die von [Symfony] (Name, Adresse), unsere (Alter) und die aus unserem Wörterbuch (Anrede). Die rohe Antwort auf die zweite Anfrage – die mit einem Namen, der HTML enthält – und die Antwort auf eine Anfrage ohne Namen und mit einem zu hohen Alter:

1
2
3
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"
curl "http://localhost:8000/persons/action01?age=200&title=Mr"
1
2
3
<p>The form contains errors:</p><ul><li>name: This value is too short. It should have 2 characters or more.</li><li>age: an integer is expected</li><li>title: unknown value</li><li>email: This value is not a valid email address.</li></ul>
<p>Welcome Mr &lt;b&gt;martin&lt;/b&gt; (42 years old)</p>
<p>The form contains errors:</p><ul><li>name: the field is required</li><li>age: This value should be between 0 and 150.</li></ul>

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

3.4. Beispiel 10: Mehrfachparameter

Derselbe Parameter kann in einer URL mehrfach vorkommen: [?color=red&color=green]. Das sendet ein Browser für eine Gruppe von Kontrollkästchen mit demselben Namen oder für eine Liste mit Mehrfachauswahl (siehe das nächste Kapitel). [PHP] behandelt diesen Fall auf seine eigene Weise. Der Controller [ArraysController]:

<?php
// src/Controller/ArraysController.php: ein Parameter, der mehrfach in der URL vorkommt

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Validator\ValidatorInterface;

#[Route('/arrays', name: 'arrays_', methods: ['GET'])]
class ArraysController extends AbstractController
{
    // /arrays/action01?color=red&color=green: Für PHP ERSETZT der zweite Parameter
    // den ersten: Nur der LETZTE Wert bleibt erhalten
    #[Route('/action01', name: 'action01')]
    public function action01(Request $request): JsonResponse
    {
        return $this->json(['color' => $request->query->get('color'),
            'raw' => $request->server->get('QUERY_STRING')]);
    }

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

    // /arrays/action03?color[]=red: ein Array, Element für Element validiert
    #[Route('/action03', name: 'action03')]
    public function action03(Request $request, ValidatorInterface $validator): JsonResponse
    {
        $colors = $request->query->all('color');
        // Wir können jeden beliebigen Wert (hier ein Array) validieren, indem wir die
        // zu validierenden Constraints angeben
        $violations = $validator->validate($colors, [
            // eine Liste mit mindestens einem Element
            new Assert\Count(min: 1),
            // All: Die Constraints gelten für JEDES Element
            new Assert\All([new Assert\Choice(choices: ['red', 'green', 'blue'])]),
        ]);
        $errors = [];
        foreach ($violations as $violation) {
            $errors[] = "color{$violation->getPropertyPath()}: {$violation->getMessage()}";
        }
        return $this->json(['colors' => $colors, 'valid' => ! $errors, 'errors' => $errors]);
    }
}
  • Zeilen 21–22: 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 vorhergehenden, und nur der letzte Wert bleibt erhalten. Zum Vergleich gibt die Action auch die rohe Parameterzeichenkette zurück, wie der Browser sie gesendet hat: Die Eigenschaft [server] der Anfrage enthält die Variablen, die der Webserver an [PHP] übermittelt, darunter [QUERY_STRING];
  • Zeilen 28–33: Um alle Werte abzurufen, muss der Name des Parameters mit eckigen Klammern enden: [?color[]=red&color[]=green]. [PHP] speichert die Werte dann in einem Array, dem Wert des Parameters [color]. Die Methode [all] gibt, wenn man ihr einen Parameternamen übergibt, diesen Parameter als Array zurück – leer, wenn der Parameter fehlt;
  • Zeilen 37–53: Das Array wird validiert. Die Methode [validate] des Validators akzeptiert jeden beliebigen Wert, sofern man seine Constraints angibt: hier [Count(min: 1)] (ein Array mit mindestens einem Element) und [All], das die darin enthaltenen Constraints auf jedes Element des Arrays anwendet: Jedes muss eine der drei Farben sein;
  • Zeile 50: Der Pfad der Verletzung identifiziert das fehlerhafte Element: [[1]] für das zweite Element (die Indizes beginnen bei 0) und eine leere Zeichenkette für das Array selbst. Er wird an den Parameternamen angehängt;
  • Zeile 52: Der Operator [!] ergibt [true] für ein leeres Array, das in einer Bedingung als „false“ ausgewertet wird.

Die Datei [translations/validators.en.yaml] im Beispiel übersetzt die Meldung des Constraints [Choice] (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 dagegen kodiert sie ([color%5B%5D=red]), was [PHP] ebenfalls versteht. In HTML müssen Sie die Kontrollkästchen einer Gruppe lediglich [color[]] nennen (die Form-Komponente von [Symfony] übernimmt das für uns; siehe 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.

[Symfony] stellt sicher, dass die beiden Formen nicht verwechselt werden: [get] weist einen Parameter zurück, der ein Array ist, und [all] weist einen Parameter zurück, der kein Array ist. In beiden Fällen wird ein 400-Fehler zurückgegeben:

curl -i -g "http://localhost:8000/arrays/action01?color[]=red"
curl -i "http://localhost:8000/arrays/action02?color=red"
1
2
3
4
5
6
HTTP/1.1 400 Bad Request
X-Debug-Exception: Input%20value%20%22color%22%20contains%20a%20non-scalar%20value.
...
HTTP/1.1 400 Bad Request
X-Debug-Exception: Unexpected%20value%20for%20parameter%20%22color%22%3A%20expecting%20%22array%22%2C%20got%20%22string%22.
...

Die Validierung gelingt, scheitert dann an einer unbekannten Farbe und schließlich an 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: This collection should contain 1 element or more."
    ]
}

Der Fehler zur unbekannten Farbe verweist auf [color[1]]: den Parameter und den Index des problematischen Elements im Array.

3.5. Beispiel 11: Die Parameter einer POST-Anfrage

Die vorherigen Beispiele verwendeten GET-Anfragen, deren Parameter in der URL stehen. Eine POST-Anfrage trä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
// src/Controller/PostController.php: die Parameter einer POST-Anfrage

namespace App\Controller;

use App\Model\PersonModel;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Exception\JsonException;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
use Symfony\Component\HttpKernel\Exception\UnsupportedMediaTypeHttpException;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/post', name: 'post_', methods: ['POST'])]
class PostController extends AbstractController
{
    // die Felder eines HTML-Formulars (Body vom Typ application/x-www-form-urlencoded):
    // $request->request enthält die Parameter des BODYS der Anfrage
    #[Route('/action01', name: 'action01')]
    public function action01(Request $request): JsonResponse
    {
        return $this->json([
            'receivedType' => $request->headers->get('Content-Type'),
            'fields' => $request->request->all(),
        ]);
    }

    // ein JSON-Body: toArray() deserialisiert ihn
    #[Route('/action02', name: 'action02')]
    public function action02(Request $request): JsonResponse
    {
        // das Format des Bodys, abgeleitet aus dem Header Content-Type: 'json', 'form'...
        if ($request->getContentTypeFormat() !== 'json') {
            throw new UnsupportedMediaTypeHttpException('the body of the request must be JSON');
        }
        try {
            $body = $request->toArray();
        } catch (JsonException $e) {
            throw new BadRequestHttpException('Malformed JSON: '.$e->getMessage());
        }
        return $this->json(['receivedType' => $request->headers->get('Content-Type'), 'body' => $body,
            'name' => $request->getPayload()->get('name')]);
    }

    // ein einzelnes Feld; getPayload(): die Parameter des Bodys, ob es sich um ein
    // Formular oder ein JSON-Dokument handelt
    #[Route('/action03', name: 'action03')]
    public function action03(Request $request): Response
    {
        $name = $request->getPayload()->get('name');
        return new Response("name = [$name]");
    }

    // der Body, Formular oder JSON, an ein PersonModel-Objekt gebunden und validiert (siehe
    // Beispiel 08): #[MapRequestPayload] ist das Gegenstück zu #[MapQueryString]
    #[Route('/action04', name: 'action04')]
    public function action04(#[MapRequestPayload] PersonModel $person): JsonResponse
    {
        return $this->json(['person' => $person, 'valid' => true]);
    }
}
  • Zeile 17: Alle Routen des Controllers akzeptieren nur die Methode POST;
  • Zeile 26: der Anfrage-Header [Content-Type];
  • Zeile 27: Die Eigenschaft [request] der Anfrage (der Name „history“ ist irreführend) enthält die Body-Parameter – bei einem Formular-Body – in einer Parameter-Bag, die [query] (Beispiel 07) ähnelt: [get], [getInt], [all] ... Die Felder eines Formulars folgen den Regeln aus Beispiel 10: Ein wiederholtes Feld muss einen Namen haben, der auf [[]] endet;
  • Zeilen 36–38: [getContentTypeFormat()] gibt das Format des Bodys an, abgeleitet vom Header [Content-Type]: [json], [form], [xml] ... Ein Body, der nicht als JSON deklariert ist, wird mit dem Fehler 415 (Unsupported Media Type) zurückgewiesen;
  • Zeilen 39–43: [toArray()] deserialisiert den JSON-Body: Der JSON-Text wird zu einem [PHP]-Array. Ein fehlerhaftes JSON löst eine [JsonException] aus (aus der HttpFoundation-Komponente, in Zeile 7 importiert), die der Block [try] / [catch] abfängt, um mit einem 400-Fehler und unserer Meldung zu antworten. Ohne diesen Block [Symfony] würde es selbst mit einem 400-Fehler antworten: Diese Exception gehört zu denen, die es als Client-Fehler erkennt;
  • Zeilen 44–45: Die Methode [getPayload()] gibt die Parameter des Bodys – ob Formular oder JSON-Dokument – in einer Parameter-Bag zurück. Das ist die am häufigsten verwendete Methode, weil sie nicht von der Form der Anfrage abhängt;
  • Zeile 53: ein Formularfeld, gelesen mit [getPayload()];
  • Zeilen 59–63: Das Attribut [#[MapRequestPayload]] ist das Gegenstück für den Anfrage-Body zu [#[MapQueryString]] (Beispiel 08): Es erzeugt ein [PersonModel]-Objekt (die Klasse aus Beispiel 08) aus den Feldern des Formulars oder des JSON-Dokuments und validiert es. Ein ungültiges Modell löst eine Exception aus (hier mit dem Code 422, Unprocessable Content), die der Listener [ValidationErrors] aus Beispiel 08 in eine 400-Antwort umwandelt. Das Beispiel verwendet außerdem die Konfiguration und das Wörterbuch aus Beispiel 09: Die Meldungen sind auf Englisch, mit unseren eigenen Übersetzungen.

[Symfony] benötigt nichts weiter, um POST-Anfragen zu akzeptieren: Es hat keinen Anti-CSRF-Schutz, der für alle Anfragen gelten würde (Beispiel 02). 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) legt einen anderen Typ fest. 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 im 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 trägt das JSON Datentypen: Das Alter ist bereits eine ganze Zahl. Ein Body, der kein JSON ist, gefolgt von einem fehlerhaften JSON (mit Anforderung einer JSON-Antwort, 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
1
2
3
4
5
6
7
8
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json

{"type":"https:\/\/tools.ietf.org\/html\/rfc2616#section-10","title":"An error occurred","status":415,"detail":"the body of the request must be JSON",...}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{"type":"https:\/\/tools.ietf.org\/html\/rfc2616#section-10","title":"An error occurred","status":400,"detail":"Malformed JSON: Could not decode request body.",...}

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
Content-Type: text/html; charset=UTF-8
Allow: POST
...

Die URL existiert, aber nicht für die Methode GET: [Symfony] gibt eine 405-Antwort (Method Not Allowed) zurück, und ihr Header [Allow] listet die akzeptierten Methoden auf (Beispiel 02). Schließlich das an den Anfrage-Body gebundene Modell – zuerst über ein gültiges Formular, dann über ein ungültiges und schließlich über ein JSON-Dokument:

1
2
3
curl -d "name=martin&age=42&title=Mr" http://localhost:8000/post/action04
curl -i -d "name=m&age=200" http://localhost:8000/post/action04
curl -H "Content-Type: application/json" -d "{\"name\": \"martin\", \"age\": \"42\", \"title\": \"Mr\"}" http://localhost:8000/post/action04
{
    "person": {
        "name": "martin",
        "age": 42,
        "title": "Mr",
        "email": null
    },
    "valid": true
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "status": 400,
    "errors": [
        {
            "field": "name",
            "message": "This value is too short. It should have 2 characters or more."
        },
        {
            "field": "age",
            "message": "This value should be between 0 and 150."
        },
        {
            "field": "title",
            "message": "the field is required"
        }
    ]
}
{
    "status": 400,
    "errors": [
        {
            "field": "age",
            "message": "This value should be of type int|null."
        }
    ]
}

Die letzte Anfrage zeigt einen Unterschied zwischen den beiden Body-Formaten. Formularfelder sind immer Zeichenketten: [Symfony] wandelt daher die Zeichenkette ["42"] in eine ganze Zahl um. Ein JSON-Dokument dagegen hat Datentypen: Sendet der Client eine Zeichenkette (["42"], in Anführungszeichen), wo die Klasse eine ganze Zahl erwartet, handelt es sich um einen Typfehler, den [Symfony] meldet, ohne eine Konvertierung zu versuchen ([int|null] ist der [?int]-Typ der Eigenschaft, anders geschrieben).

3.6. Beispiel 12: Eigene Bindung und Validierung

Standardtypen, Attribute und Constraints reichen nicht immer aus. Dieses Beispiel zeigt drei Möglichkeiten, Bindung und Validierung zu erweitern:

  • ein „eigener“ Argument-Resolver: ein Datum im französischen Format, [23-09-2026], das im Pfad der URL steht und der Action als Objekt bereitgestellt wird;
  • ein Listener , der der Action einen Parameter bereitstellt, der nicht aus der URL stammt, sondern aus einem HTTP-Header;
  • ein eigener Validierungs-Constraint (keine Leerzeichen) und die Konvertierung eines Datums [dd/mm/yyyy].
12-custom-binding/
├── src/
│   ├── Controller/
│   │   └── ExamplesController.php
│   ├── EventListener/
│   │   └── ErrorAsText.php
│   ├── Binding/
│   │   ├── DetectLanguage.php
│   │   ├── DayFr.php
│   │   ├── DayFrResolver.php
│   │   ├── NoSpace.php
│   │   └── NoSpaceValidator.php
│   ├── Model/
│   │   └── SearchModel.php
│   └── Kernel.php
└── ...

3.6.1. Ein an einen Routenparameter gebundenes Objekt: DayFr.php und DayFrResolver.php

Wir haben gesehen, dass die Parameter einer Action von Argument-Resolvern bereitgestellt werden (Beispiel 05): Einer liefert die Routenparameter (Beispiel 02), ein anderer die Anfrage (Beispiel 05), ein weiterer die Services (Beispiel 06), und wieder andere liefern die Parameter der URL ([#[MapQueryParameter]]) oder ein Modell ([#[MapQueryString]]). [Symfony] hat etwa fünfzehn davon, darunter einen für Datumsangaben ([#[MapDateTime]]) und einen für Enumerationen. Die Anwendung kann eigene schreiben. Wir schreiben einen für ein Datum im französischen Format, das durch die Klasse [DayFr] dargestellt wird:

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

namespace App\Binding;

use DateTimeImmutable;
use Stringable;

readonly class DayFr implements Stringable
{
    public function __construct(public DateTimeImmutable $date)
    {
    }

    // Text des Pfads -> DayFr-Objekt; null: Der Text bezeichnet kein Datum
    public static function fromUrl(string $text): ?self
    {
        // Das ! in "!d-m-Y" setzt die Uhrzeit auf null (sonst wäre es die aktuelle Uhrzeit)
        $date = DateTimeImmutable::createFromFormat('!d-m-Y', $text);
        // createFromFormat akzeptiert "31-02-2026" (und macht daraus den 3. März): Wir prüfen,
        // ob das erneut formatierte Datum den empfangenen Text zurückgibt
        if ($date === false || $date->format('d-m-Y') !== $text) {
            return null;
        }
        return new self($date);
    }

    // DayFr-Objekt -> Text des Pfads (verwendet beim Erzeugen der URL einer Route)
    public function __toString(): string
    {
        return $this->date->format('d-m-Y');
    }
}
  • Zeile 9: eine unveränderliche Klasse, die das Interface [Stringable] von [PHP] implementiert: Ihre Objekte können über ihre Methode [__toString] in eine Zeichenkette umgewandelt werden;
  • Zeile 11: das Datum, ein [DateTimeImmutable]-Objekt (die Datumsklasse von [PHP]; die [Immutable]-Version erzeugt bei jeder Änderung ein neues Objekt – [$date->modify('+1 day')] gibt ein neues Datum zurück –, statt das Objekt zu verändern);
  • Zeilen 16–26: eine statische Methode, die aus dem Pfadtext ein [DayFr]-Objekt erzeugt oder [null] zurückgibt, wenn der Text ungültig ist ([?self]: ein Objekt der aktuellen Klasse oder [null]). [DateTimeImmutable::createFromFormat] analysiert eine Zeichenkette gemäß einem bestimmten Format: [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 Validierung in Zeile 22 weist diesen Fall zurück: Das durch [format] neu formatierte Datum muss exakt dem empfangenen Text entsprechen;
  • Zeilen 29–32: die Umkehroperation: Das Objekt wird zum Pfadtext. [Symfony] verwendet dies, um aus einem [DayFr]-Objekt eine URL zu erzeugen.

Der Resolver:

<?php
// src/Binding/DayFrResolver.php: ein ARGUMENT RESOLVER, der die Actions mit
// ihren Parametern vom Typ DayFr versorgt

namespace App\Binding;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\Controller\ValueResolverInterface;
use Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadata;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

class DayFrResolver implements ValueResolverInterface
{
    // wird für jeden Parameter einer Action aufgerufen, der diesen Resolver anfordert (siehe
    // Controller): gibt den Wert des Parameters in einem Array zurück
    public function resolve(Request $request, ArgumentMetadata $argument): iterable
    {
        // der Routenparameter mit demselben Namen wie der Parameter der Action ($day)
        $text = $request->attributes->get($argument->getName());
        if (! is_string($text)) {
            return [];    // nichts bereitzustellen: Ein anderer Resolver kümmert sich darum
        }
        // ein Datum, das nicht existiert: Die URL bezeichnet nichts, Fehler 404
        return [DayFr::fromUrl($text) ?? throw new NotFoundHttpException("[$text] is not a date")];
    }
}
  • Zeile 12: Ein Argument-Resolver implementiert das Interface [ValueResolverInterface], dessen einzige Methode [resolve] ist;
  • Zeile 16: [resolve] erhält die Anfrage und die Beschreibung des Action-Parameters (ein [ArgumentMetadata]-Objekt: sein Name, Typ, Standardwert und seine Attribute). Es gibt den Wert des Parameters in einem Array ([iterable]) zurück oder ein leeres Array, wenn es nichts zurückzugeben hat;
  • Zeile 19: Die Routenparameter sind in den Attributen der Anfrage ([$request->attributes]) gespeichert, einer Parametermenge, die auch von [Symfony] berechnete Informationen enthält (zum Beispiel den Namen der Route, [_route]). Wir suchen den Parameter mit demselben Namen wie die Action;
  • Zeile 24: das Objekt [DayFr] oder, wenn der Text kein Datum bezeichnet, ein 404-Fehler: Die URL verweist auf nichts. Der Operator [??] gibt seinen linken Operanden zurück, wenn dieser nicht [null] ist, andernfalls den rechten; rechts akzeptiert er einen [throw]-Ausdruck.

Die Klasse ist ein Service wie alle im Ordner [src] (Beispiel 02): [Symfony] erkennt sie dank ihres Interfaces ([autoconfigure]) als Argument-Resolver. Der Controller legt fest, welchen Parameter sie bereitstellen muss.

3.6.2. Ein von einem Listener bereitgestellter Parameter: src/Binding/DetectLanguage.php

Um einer Action aus der Anfrage berechnete Informationen bereitzustellen, kann man sie auch von einem Listener berechnen lassen (Beispiel 03), der sie vor der Action in die Anfrage aufnimmt:

<?php
// src/Binding/DetectLanguage.php: ein Listener, der eine Information für die Action BERECHNET

namespace App\Binding;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;

// das Ereignis [kernel.request]: Die Anfrage trifft ein, die Action ist noch nicht aufgerufen
#[AsEventListener(event: KernelEvents::REQUEST)]
class DetectLanguage
{
    public function __invoke(RequestEvent $event): void
    {
        $request = $event->getRequest();
        // 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 verarbeiten
        $request->attributes->set('language', $language);
    }
}
  • Zeile 11: ein Listener für das Ereignis [kernel.request], das ausgelöst wird, wenn die Anfrage eintrifft, bevor die Action aufgerufen wird (das Routing selbst ist ein Listener für dieses Ereignis: Das Kapitel über den Lebenszyklus behandelt ihre Reihenfolge);
  • Zeile 19: Der [Accept-Language]-Header der Anfrage gibt die Sprachen des Benutzers in der Reihenfolge ihrer Präferenz an: [fr-FR,fr;q=0.9,en;q=0.8] (der [q]-Koeffizient misst die Präferenz auf einer Skala von 0 bis 1). [getPreferredLanguage] wählt aus den von der Anwendung angebotenen Sprachen die bevorzugte Sprache des Benutzers aus; ist kein Header vorhanden, wird standardmäßig die erste Sprache der Liste verwendet;
  • Zeile 22: Die Sprache wird in den Attributen der Anfrage unter dem Namen [language] gespeichert, neben den Routenparametern.

Der Listener läuft für alle Anfragen. [Symfony] besitzt kein Äquivalent zu den Route-Middlewares anderer Frameworks: Ein Listener, der nur für bestimmte Routen aktiv sein soll, prüft den Namen der Route selbst ([$request->attributes->get('_route')]). Die Action erhält die Information, ohne dass etwas Besonderes zu tun wäre (siehe den Controller).

3.6.3. Ein „eigener“ Constraint und eine Konvertierung: NoSpace.php und SearchModel.php

Ein „eigener“ Constraint besteht aus zwei Klassen: dem Constraint selbst, der ihn beschreibt (seine Optionen, seine Meldung), und seinem Validator, der ihn prüft.

<?php
// src/Binding/NoSpace.php: eine „selbstgebaute“ Validierungs-Constraint

namespace App\Binding;

use Attribute;
use Symfony\Component\Validator\Constraint;

// #[Attribute]: Die Klasse kann als Attribut verwendet werden (#[NoSpace]); die
// eigentliche Prüfung wird der Klasse NoSpaceValidator übertragen
#[Attribute(Attribute::TARGET_PROPERTY)]
class NoSpace extends Constraint
{
    public string $message = 'the field must not contain a space';
}
  • Zeile 11: Das Attribut [#[Attribute]] von [PHP] erlaubt es, die Klasse als Attribut zu verwenden, hier an einer Eigenschaft ([TARGET_PROPERTY]);
  • Zeile 12: Ein Constraint erbt von der Klasse [Constraint];
  • Zeile 14: seine Fehlermeldung in einer öffentlichen Eigenschaft: Sie lässt sich zur Laufzeit ändern ([#[NoSpace(message: '...')]]).
<?php
// src/Binding/NoSpaceValidator.php: die Prüfung der Constraint NoSpace

namespace App\Binding;

use Symfony\Component\Validator\Constraint;
use Symfony\Component\Validator\ConstraintValidator;

class NoSpaceValidator extends ConstraintValidator
{
    public function validate(mixed $value, Constraint $constraint): void
    {
        if ($value !== null && str_contains((string) $value, ' ')) {
            // Der Wert ist nicht geeignet: Wir melden eine „Violation“ mit der
            // Meldung der Constraint
            $this->context->buildViolation($constraint->message)->addViolation();
        }
    }
}
  • Zeile 9: Der Validator eines Constraints wird nach seiner Klasse benannt, gefolgt von [Validator]: So findet [Symfony] ihn. Er erbt von [ConstraintValidator];
  • Zeilen 11–18: Seine Methode [validate] erhält den zu validierenden Wert und den Constraint. [str_contains] prüft, ob ein Text in einer Zeichenkette enthalten ist; [(string)] wandelt den Wert in eine Zeichenkette um. Ist der Wert ungültig, wird eine Verletzung dem Validierungs-Kontext ([$this->context]) zusammen mit der Meldung des Constraints gemeldet. Der Typ [mixed] steht für jeden beliebigen Typ. Wie die Constraints von [Symfony] akzeptiert auch dieser [null]: Das Fehlen eines Werts wird von [NotBlank] behandelt.

Der Constraint wird vom Suchmodell verwendet:

<?php
// src/Model/SearchModel.php: das Modell der Suche

namespace App\Model;

use App\Binding\NoSpace;
use DateTimeImmutable;
use Symfony\Component\Validator\Constraints as Assert;

readonly class SearchModel
{
    public function __construct(
        // eine „selbstgebaute“ Constraint
        #[NoSpace]
        public ?string $keyword = null,
        // DateTime: ein Datum im Format dd/mm/yyyy, das existiert; {{ value }}: der empfangene Wert
        #[Assert\DateTime(format: 'd/m/Y', message: '{{ value }} is not a valid dd/mm/yyyy date')]
        public ?string $since = null,
    ) {
    }

    // das Datum, in ein Datumsobjekt UMGEWANDELT (null, falls es fehlt)
    public function since(): ?DateTimeImmutable
    {
        return $this->since === null ? null
            : DateTimeImmutable::createFromFormat('!d/m/Y', $this->since);
    }
}
  • Zeilen 14–15: unser Constraint, genau wie jeder andere verwendet;
  • Zeilen 17–18: die Constraint [DateTime] prüft, ob der Wert ein Datum im angegebenen Format ist ([d/m/Y]: tt/mm/jjjj) und ob dieses Datum existiert. Ihre Meldung wird durch unsere ersetzt; der Platzhalter [{{ value }}] wird durch den empfangenen Wert (in Anführungszeichen) ersetzt. Das Datum bleibt im Modell eine Zeichenkette: Eine Eigenschaft vom Typ [DateTimeImmutable] würde zwar vom Serializer konvertiert, ein ungültiges Datum führte dann aber zu einem Konvertierungsfehler (Beispiel 08) mit einer eher vagen Fehlermeldung;
  • Zeilen 23–27: die Konvertierung des Datums in einer Methode des Modells: das entsprechende Objekt [DateTimeImmutable] oder [null] , wenn das Datum fehlt. Die Action ruft diese Methode erst nach der Validierung auf: Das Datum ist somit zwingend gültig.

Schließlich die Antwort auf eine fehlgeschlagene Validierung. Sie soll sich von der in Beispiel 08 unterscheiden: die erste Fehlermeldung als reiner Text mit dem Code 400:

<?php
// src/EventListener/ErrorAsText.php: Ein ungültiges Modell erzeugt eine 400-Antwort,
// die als reinen Text die Meldung des ersten Fehlers enthält

namespace App\EventListener;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Validator\Exception\ValidationFailedException;

#[AsEventListener(event: KernelEvents::EXCEPTION)]
class ErrorAsText
{
    public function __invoke(ExceptionEvent $event): void
    {
        $validation = $event->getThrowable()->getPrevious();
        if ($validation instanceof ValidationFailedException) {
            $event->setResponse(new Response($validation->getViolations()[0]->getMessage(),
                Response::HTTP_BAD_REQUEST, ['Content-Type' => 'text/plain; charset=utf-8']));
        }
    }
}

Dies ist der Listener aus Beispiel 08, auf das Wesentliche reduziert: [getViolations()[0]] ist die erste Verletzung. Ein solcher Listener gilt für die gesamte Anwendung. Um je nach Action eine andere Antwort zu liefern, würde er den Namen der Route prüfen (siehe oben).

3.6.4. Der Controller: src/Controller/ExamplesController.php

<?php
// src/Controller/ExamplesController.php: benutzerdefiniertes Binding und Validierung

namespace App\Controller;

use App\Binding\DayFr;
use App\Binding\DayFrResolver;
use App\Model\SearchModel;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\MapQueryString;
use Symfony\Component\HttpKernel\Attribute\ValueResolver;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/examples', name: 'examples_', methods: ['GET'])]
class ExamplesController extends AbstractController
{
    // /examples/schedule/23-09-2026: #[ValueResolver] überträgt den Parameter $day dem
    // Resolver DayFrResolver, der ihn an den Routenparameter {day} BINDET
    #[Route('/schedule/{day}', name: 'schedule', requirements: ['day' => '[0-9]{2}-[0-9]{2}-[0-9]{4}'])]
    public function schedule(#[ValueResolver(DayFrResolver::class)] DayFr $day): Response
    {
        // generateUrl baut die URL einer Route; das DayFr-Objekt wird über seine Methode __toString zum Text
        // des Pfads: "23-09-2026"
        return new Response("schedule for the day [{$day->date->format('Y-m-d')}], of type "
            .get_debug_type($day->date).', URL: '.$this->generateUrl('examples_schedule', ['day' => $day]));
    }

    // /examples/hello: ein Parameter, der nicht aus der URL stammt, sondern aus einem Header,
    // vom Listener DetectLanguage berechnet und in den Attributen der Anfrage abgelegt
    #[Route('/hello', name: 'hello')]
    public function hello(string $language): Response
    {
        return new Response($language === 'en' ? 'Hello!' : 'Bonjour !');
    }

    // /examples/search?keyword=symfony&since=01/09/2026
    #[Route('/search', name: 'search')]
    public function search(#[MapQueryString] SearchModel $search): Response
    {
        $since = $search->since()?->format('Y-m-d');
        return new Response("search for [$search->keyword] since [$since]");
    }
}
  • Zeile 20: die Kalender-Route, deren Parameter [{day}] durch einen regulären Ausdruck eingeschränkt ist: [[0-9]] bezeichnet eine Ziffer, [{2}] bezeichnet 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 unser Resolver überhaupt befragt wird;
  • Zeile 21: das Attribut [#[ValueResolver]] weist den Parameter [$day] einem Resolver zu, der anhand seiner Klasse bezeichnet wird: Er, und nur er, liefert ihn. Ohne dieses Attribut würde [Symfony] seine Resolver in der Reihenfolge ihrer Priorität ausprobieren, und der Resolver für Routenparameter – der Vorrang vor unserem hat – würde die Zeichenkette ["23-09-2026"] an einen Parameter vom Typ [DayFr] übergeben: ein Fehler;
  • Zeilen 25–26: Das Datum wird im internationalen Format angezeigt ([Y-m-d]: [2026-09-23]). Die Methode [generateUrl] von [AbstractController] erzeugt die URL für eine benannte Route samt ihren Parametern (das hat [redirectToRoute] in Beispiel 04 getan). Ihr wird das Objekt [DayFr] selbst übergeben: [Symfony] wandelt es mithilfe seiner Methode [__toString] in eine Zeichenkette um. Die URL bezieht sich auf die Website ([/examples/...]); ein dritter Parameter würde eine absolute URL erfordern;
  • Zeilen 31–35: Der Parameter [$language] entspricht keinem Routenparameter. Der Resolver für Routenparameter sucht jedoch im Allgemeinen nach einem Request-Attribut mit demselben Namen wie der Parameter: Er findet also dasjenige, das der Listener [DetectLanguage] dort abgelegt hat. Das ist alles: Am Parameter ist kein Attribut erforderlich;
  • Zeilen 38–43: das Suchmodell, gebunden an die URL-Parameter und validiert (Beispiel 08). Die Action akzeptiert nur gültige Modelle; sie ruft die Methode zur Datumskonvertierung auf. Der Operator [?->] (nullsafe) ruft eine Methode auf, wenn das Objekt nicht [null] ist, und liefert andernfalls [null] zurück.

3.6.5. Ausführung

Das dem Routenparameter zugeordnete Objekt:

curl "http://localhost:8000/examples/schedule/23-09-2026"
curl -i "http://localhost:8000/examples/schedule/31-02-2026"
1
2
3
4
5
schedule for the day [2026-09-23], of type DateTimeImmutable, URL: /examples/schedule/23-09-2026
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=UTF-8
X-Debug-Exception: %5B31-02-2026%5D%20is%20not%20a%20date
...

Das Datum wird im internationalen Format angezeigt, die von [generateUrl] erzeugte URL ist jedoch zum französischen Format zurückgekehrt. Den 31. Februar gibt es nicht: 404, mit einer Meldung unseres Resolvers. Ein Datum im internationalen Format, [2026-09-23], passt nicht zu dem vom regulären Ausdruck beschriebenen Muster: ebenfalls 404, aber diesmal, weil keine Route passt.

Der Listener. 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 „hauseigene“ Constraint und die Datumskonvertierung:

1
2
3
4
5
curl "http://localhost:8000/examples/search?keyword=symfony&since=01/09/2026"
curl "http://localhost:8000/examples/search"
curl -i "http://localhost:8000/examples/search?keyword=symfony%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 [symfony] 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

Ohne Parameter erzeugt [#[MapQueryString]] ein leeres Modell, das gültig ist: Beide Eigenschaften sind optional.

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, mit denselben Namen; konvertiert anhand ihres Typs ([int $id]), eingeschränkt durch [requirements]; über einen Argument-Resolver an ein Objekt gebunden ([ValueResolverInterface], [#[ValueResolver]])
URL-Parameter
[$request->query->get(...)], [getInt], [all]...; [#[MapQueryParameter]]; ein wiederholter Parameter wird als [name[]] geschrieben
Felder eines POST-Formulars
[$request->request->get(...)], oder [$request->getPayload()->get(...)], was auch JSON liest
JSON-Body
[$request->toArray()], [$request->getPayload()]
Durch eine Klasse beschriebenes Modell
[#[MapQueryString]] (URL), [#[MapRequestPayload]] (der Body): Konvertierung, dann Validierung
Header
[$request->headers->get(...)], und Methoden, die sie auswerten, wie [getPreferredLanguage]
Validierung
Constraints ([#[Assert\...]]), geprüft vor der Action ([#[MapQueryString]]...) oder während der Action ([ValidatorInterface]); „benutzerdefinierte“ Constraints ([Constraint] und [ConstraintValidator])
Meldungen
die Sprache [default_locale], der Translator und die Wörterbücher [translations/validators.xx.yaml]
Häufige Fehler
ein Event-Listener für [kernel.exception]
Berechneter Parameter
ein Event-Listener [kernel.request], der Informationen in den Request-Attributen ablegt

HTML-Formulare hingegen erfordern mehr als nur Validierung: Sie müssen angezeigt, mit den Eingaben des Benutzers und etwaigen Fehlern erneut angezeigt und vor gefälschten Anfragen geschützt werden. [Symfony] delegiert all das an seine Form-Komponente. Das ist das Thema des nächsten Kapitels, sobald die Views eingeführt sind.