> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Eingaben aus signierten URLs korrekt verarbeiten

> Erläutert anhand eines zeitlich begrenzten Links, was signierte URLs in Laravel 13 schützen und warum Sie signierte Query-Werte mit query() abrufen sollten.

## Ziel dieser Seite

Wenn ein zeitlich begrenzter Freigabelink genau die bei der Ausstellung festgelegten Bedingungen verwenden soll, genügt es nicht, die Signatur der URL zu prüfen. Sie müssen außerdem einheitlich festlegen, **woher Sie die Werte lesen**.
Diese Seite erläutert das an einem Beispiel, das Berichtstyp und Ausgabeformat in die URL aufnimmt und JSON für eine Vorschau zurückgibt.

Die Seite bezieht sich auf Laravel 13. Allgemeines zur URL-Erzeugung finden Sie unter [URL-Generierung](/de/urls), die Grundlagen zum Abrufen von Eingaben unter [HTTP-Requests](/de/requests).

<Warning>
  Eine Signatur schützt nicht den gesamten Request. Formular- und JSON-Bodys werden nicht signiert.
  Rufen Sie signierte Query-Werte nach der Signaturprüfung zum Beispiel mit `$request->query('format')` ab.
  Mit `input()`, `all()` oder dynamischen Properties erhalten Sie möglicherweise unsignierte Werte aus dem Body. Diese Unterscheidung ist auch bei GET-Requests nötig.
</Warning>

## Was die Signatur schützt

| Element | Behandlung |
| - | - |
| URL-Pfad | Wird bei der Signaturprüfung berücksichtigt |
| Query-String | Wird grundsätzlich bei der Signaturprüfung berücksichtigt, mit Ausnahme von Parametern, die Sie von der Prüfung ausnehmen |
| Schema und Host | Normalerweise Teil der Signatur. Bei relativen Signaturen nicht enthalten |
| Formular- und JSON-Body | Nicht Teil der Signatur |
| Ablaufzeit | Wird von `temporarySignedRoute()` hinzugefügt und bei der Prüfung auf Ablauf kontrolliert |

`input()` ist eine API, die nicht nur den Query-String, sondern auch den Body verarbeitet. Beim Zusammenführen dieser Eingaben gibt Laravel den Werten aus dem Body Vorrang vor denen aus dem Query-String.
`query()` liest dagegen ausschließlich den Query-String.

Dass die Signaturprüfung erfolgreich war und dass ein danach gelesener Wert signiert ist, sind zwei getrennte Prüfpunkte.

```mermaid theme={null}
flowchart TD
    A["Aufruf über zeitlich begrenzte URL"] --> B{"Middleware signed<br>Signatur und Ablaufzeit prüfen"}
    B -->|Ungültig| C["403-Response"]
    B -->|Gültig| D["Signierte Query-Werte<br>mit query() abrufen"]
    D --> E["Format und zulässigen Bereich der Werte validieren"]
    E --> F["Vorschau zurückgeben"]
```

## Einen zeitlich begrenzten Vorschaulink implementieren

### 1. Die zu prüfende Route definieren

Definieren Sie in `routes/web.php` eine benannte Route, die eine Signatur voraussetzt.
Das Beispiel greift weder auf die Datenbank noch auf Dateien zu, sondern gibt nur die empfangenen Bedingungen zurück.

```php theme={null}
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use Illuminate\Support\Facades\Validator;

Route::get('/reports/preview', function (Request $request) {
    $options = Validator::make([
        'report' => $request->query('report'),
        'format' => $request->query('format'),
    ], [
        'report' => ['required', 'string', 'in:monthly,annual'],
        'format' => ['required', 'string', 'in:csv,pdf'],
    ])->validate();

    return response()->json($options);
})->middleware('signed')->name('reports.preview');
```

* Die Middleware `signed` prüft Signatur und Ablaufzeit, bevor die Closure ausgeführt wird. Ist eines davon ungültig, gibt sie `403` zurück.
* Mit `query()` lesen Sie die für die Verarbeitung verwendeten Werte explizit aus dem Query-String.
* Die Validierung erfolgt auf dem abgerufenen Array. Die Signaturprüfung garantiert weder den Typ der Werte noch fachlich zulässige Bereiche.

<Info>
  In diesem Beispiel werden an `Validator::make()` nur die mit `query()` ausgelesenen Werte übergeben.
  Ersetzen Sie sie an einer Stelle, die signierte Query-Werte validieren soll, durch `$request->all()`, verarbeiten Sie Eingaben einschließlich des Bodys.
</Info>

### 2. Die URL in einem vertrauenswürdigen Ausstellungsprozess erzeugen

Nachdem die benannte Route registriert ist, verwenden Sie im Prozess, der die Links ausstellt, folgenden Code.
Da `report` und `format` keine Platzhalter im Pfad sind, werden sie an den Query-String angehängt.

```php theme={null}
use Illuminate\Support\Facades\URL;

$url = URL::temporarySignedRoute(
    'reports.preview',
    now()->addMinutes(30),
    ['report' => 'monthly', 'format' => 'csv'],
);
```

Neben den angegebenen Bedingungen enthält diese URL `expires` und `signature`.
`expires` und `signature` sind reservierte Parameter, die Laravel verwendet. Nutzen Sie sie daher nicht als Namen für eigene fachliche Parameter.

Wenn Sie den Ausstellungsprozess in einer echten Anwendung öffentlich zugänglich machen, darf nicht jeder Links mit beliebigen Bedingungen ausstellen können. Sorgen Sie für die nötige [Authentifizierung](/de/authentication) und [Autorisierung](/de/authorization).

### 3. Die normale Nutzung prüfen

Öffnen Sie die ausgestellte URL unverändert innerhalb der Gültigkeitsdauer, wird folgendes JSON zurückgegeben.

```json theme={null}
{
  "report": "monthly",
  "format": "csv"
}
```

Ist der Link abgelaufen, gibt die Middleware `signed` der Route `403` zurück.
Signierte URLs sind keine Einmal-Tokens. In diesem Beispiel lässt sich dieselbe URL innerhalb der Gültigkeitsdauer erneut verwenden.
Soll ein Link nur einmal nutzbar sein, müssen Sie den Nutzungsstatus unabhängig von der Signatur verwalten.

## Von der Prüfung ausgenommene Werte trennen

Möchten Sie etwa vom Frontend hinzugefügte Seitenzahlen zulassen, können Sie diese mit `hasValidSignatureWhileIgnoring(['page'])` von der Signaturprüfung ausnehmen.
Ausgenommene Werte kann jedoch jeder ändern. Behandeln Sie sie daher nicht als signierte Bedingungen.

So hat beispielsweise `page` für die Anzeige eine andere Rolle als `report` und `format`, die bei der Ausstellung festgelegt werden.
Nehmen Sie Werte, mit denen über Zieldaten, Empfänger, Preise und Ähnliches entschieden wird, nicht allein aus Bequemlichkeit von der Prüfung aus.

<Warning>
  Das obige Beispiel verwendet die normale Middleware `signed` und nimmt daher auch `page` nicht aus.
  Wenn Sie zusätzliche Query-Parameter verwenden möchten, legen Sie zuerst fest, was auf der erzeugenden und der prüfenden Seite signiert werden soll.
</Warning>

## Relative Signaturen verwenden

Soll die Domain nicht Teil der Signatur sein, kombinieren Sie `absolute: false` bei der Erzeugung mit `signed:relative` bei der Prüfung.

```php theme={null}
$url = URL::temporarySignedRoute(
    'reports.preview',
    now()->addMinutes(30),
    ['report' => 'monthly', 'format' => 'csv'],
    absolute: false,
);
```

Ändern Sie in diesem Fall `middleware('signed')` der obigen Route in `middleware('signed:relative')`.
Auch bei relativen Signaturen wird der Body nicht signiert. Am Abrufen mit `query()` ändert sich daher nichts.

## Checkliste für die Implementierung

* Die empfangende Route setzt eine Signaturprüfung voraus.
* Signierte Query-Werte werden mit `query()` abgerufen.
* Format und zulässiger Bereich der Werte werden separat validiert.
* Von der Signaturprüfung ausgenommene Werte werden nicht als bei der Ausstellung festgelegte Bedingungen verwendet.
* Die Einstellungen für absolute und relative Signaturen stimmen auf erzeugender und prüfender Seite überein.
* Die Kenntnis der URL wird nicht mit den Berechtigungen des angemeldeten Benutzers gleichgesetzt.

## Verwandte Seiten und Primärquellen

* [URL-Generierung](/de/urls): APIs für signierte URLs und Reaktion auf ungültige Signaturen
* [HTTP-Requests](/de/requests): Eingabewerte und Query-Strings abrufen
* [Validierung](/de/validation): Eingabeformat und zulässige Werte validieren
* [Offizielle Laravel-Dokumentation: Signed URLs](https://github.com/laravel/docs/blob/13.x/urls.md#signed-urls)
* [Offizielle Laravel-Dokumentation: Retrieving input from the query string](https://github.com/laravel/docs/blob/13.x/requests.md#retrieving-input-from-the-query-string)
* [Laravel Framework: UrlGenerator](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Routing/UrlGenerator.php)
* [Laravel Framework: ValidateSignature](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Routing/Middleware/ValidateSignature.php)


## Related topics

- [URL-Generierung](/de/urls.md)
- [Laravel AI SDK](/de/ai-sdk.md)
- [Asset-Bundling mit Vite](/de/vite.md)
- [Labeler](/de/packages/laravel-bluesky/labeler.md)
- [Bildbearbeitung](/de/images.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.