URL-Generierung

Erläutert den url()-Helper von Laravel sowie das Erzeugen von URLs für benannte Routen, signierte URLs und Controller-Actions.

​

Einführung

Laravel bietet mehrere Helper zur Erzeugung von URLs für Ihre Anwendung. Diese sind besonders nützlich beim Aufbau von Links in Templates oder API-Antworten sowie beim Generieren von Redirect-Antworten zu anderen Stellen Ihrer Anwendung.

​

Grundlagen

​

URL erzeugen

Mit dem Helper url erzeugen Sie beliebige URLs. Die generierten URLs verwenden automatisch das Schema (HTTP oder HTTPS) und den Host der aktuellen Anfrage.

$post = App\Models\Post::find(1);

echo url("/posts/{$post->id}");

// http://example.com/posts/1

Für URLs mit Query-String-Parametern nutzen Sie die Methode query.

echo url()->query('/posts', ['search' => 'Laravel']);

// https://example.com/posts?search=Laravel

echo url()->query('/posts?sort=latest', ['search' => 'Laravel']);

// http://example.com/posts?sort=latest&search=Laravel

Wenn Sie einen Parameter übergeben, der bereits im Pfad existiert, wird der bestehende Wert überschrieben.

echo url()->query('/posts?sort=latest', ['sort' => 'oldest']);

// http://example.com/posts?sort=oldest

Auch Array-Werte lassen sich als Query-Parameter übergeben. Sie werden korrekt indiziert und in der URL kodiert.

echo $url = url()->query('/posts', ['columns' => ['title', 'body']]);

// http://example.com/posts?columns%5B0%5D=title&columns%5B1%5D=body

echo urldecode($url);

// http://example.com/posts?columns[0]=title&columns[1]=body

​

Aktuelle URL abrufen

Wenn Sie dem Helper url keinen Pfad übergeben, erhalten Sie eine Illuminate\Routing\UrlGenerator-Instanz mit Zugriff auf Informationen zur aktuellen URL.

// Aktuelle URL ohne Query-String
echo url()->current();

// Aktuelle URL mit Query-String
echo url()->full();

Diese Methoden sind auch über die Facade URL verfügbar.

use Illuminate\Support\Facades\URL;

echo URL::current();

​

Vorherige URL abrufen

Manchmal möchten Sie die zuvor besuchte URL kennen. Dafür stellt der Helper url die Methoden previous und previousPath bereit.

// Vollständige URL des vorherigen Requests
echo url()->previous();

// Pfad des vorherigen Requests
echo url()->previousPath();

Sie können die vorherige URL auch über die Session abrufen.

use Illuminate\Http\Request;

Route::post('/users', function (Request $request) {
    $previousUri = $request->session()->previousUri();

    // ...
});

Ebenso lässt sich der Routenname der zuletzt besuchten URL über die Session ermitteln.

$previousRoute = $request->session()->previousRoute();

​

URLs für benannte Routen

Der Helper route erzeugt URLs für benannte Routen. Damit generieren Sie URLs unabhängig von der tatsächlichen Route-URL. Ändert sich die URL der Route, müssen Sie die Aufrufe von route nicht anpassen.

Route::get('/post/{post}', function (Post $post) {
    // ...
})->name('post.show');

Um für diese Route eine URL zu erzeugen:

echo route('post.show', ['post' => 1]);

// http://example.com/post/1

Auch Routen mit mehreren Parametern werden unterstützt.

Route::get('/post/{post}/comment/{comment}', function (Post $post, Comment $comment) {
    // ...
})->name('comment.show');

echo route('comment.show', ['post' => 1, 'comment' => 3]);

// http://example.com/post/1/comment/3

Zusätzliche Array-Werte, die keinen Route-Parametern entsprechen, werden an den Query-String angehängt.

echo route('post.show', ['post' => 1, 'search' => 'rocket']);

// http://example.com/post/1?search=rocket

​

Eloquent-Modelle

Häufig verwenden Sie den Route-Key (üblicherweise den Primärschlüssel) eines Eloquent-Modells zur URL-Erzeugung. Sie können das Modell direkt als Parameterwert übergeben; route extrahiert den Route-Key automatisch.

echo route('post.show', ['post' => $post]);

​

Signierte URLs

Laravel erlaubt es, „signierte” URLs für benannte Routen zu erstellen. An diese URLs wird ein „Signature”-Hash angehängt, sodass Laravel prüfen kann, ob die URL nach der Erzeugung manipuliert wurde. Signierte URLs sind besonders praktisch für öffentliche, aber vor Manipulation zu schützende Routen.

Ein Beispiel ist ein öffentlicher „Abmelde”-Link, den Sie per E-Mail an Kunden versenden. Mit der Methode signedRoute der Facade URL erstellen Sie signierte URLs.

use Illuminate\Support\Facades\URL;

return URL::signedRoute('unsubscribe', ['user' => 1]);

Mit dem Argument absolute können Sie die Domain aus dem Signatur-Hash ausschließen.

return URL::signedRoute('unsubscribe', ['user' => 1], absolute: false);

Für eine URL, die nach einer bestimmten Zeit abläuft, verwenden Sie temporarySignedRoute. Beim Verifizieren prüft Laravel, dass der eingebettete Ablauf-Zeitstempel nicht überschritten wurde.

use Illuminate\Support\Facades\URL;

return URL::temporarySignedRoute(
    'unsubscribe', now()->plus(minutes: 30), ['user' => 1]
);

​

Ablauf der Verifizierung signierter URLs

​

Signierte Requests validieren

Um zu prüfen, ob eine eingehende Anfrage eine gültige Signatur besitzt, rufen Sie auf der Illuminate\Http\Request-Instanz hasValidSignature auf.

use Illuminate\Http\Request;

Route::get('/unsubscribe/{user}', function (Request $request) {
    if (! $request->hasValidSignature()) {
        abort(401);
    }

    // ...
})->name('unsubscribe');

Sollen bestimmte Query-Parameter ignoriert werden, verwenden Sie hasValidSignatureWhileIgnoring.

if (! $request->hasValidSignatureWhileIgnoring(['page', 'order'])) {
    abort(401);
}

Alternativ zur manuellen Prüfung können Sie die Middleware signed (Illuminate\Routing\Middleware\ValidateSignature) verwenden. Ohne gültige Signatur wird automatisch ein 403 zurückgegeben.

Route::post('/unsubscribe/{user}', function (Request $request) {
    // ...
})->name('unsubscribe')->middleware('signed');

Enthält die signierte URL keine Domain, übergeben Sie der Middleware das Argument relative.

Route::post('/unsubscribe/{user}', function (Request $request) {
    // ...
})->name('unsubscribe')->middleware('signed:relative');

​

Reaktion auf ungültige signierte Routen

Wird eine abgelaufene signierte URL aufgerufen, erscheint die generische Fehlerseite mit Status 403. Passen Sie das Verhalten in bootstrap/app.php an, indem Sie eine eigene render-Closure für die Exception InvalidSignatureException definieren.

use Illuminate\Routing\Exceptions\InvalidSignatureException;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->render(function (InvalidSignatureException $e) {
        return response()->view('errors.link-expired', status: 403);
    });
})

​

URLs zu Controller-Actions

Die Funktion action erzeugt die URL zu einer angegebenen Controller-Action.

use App\Http\Controllers\HomeController;

$url = action([HomeController::class, 'index']);

Nimmt die Methode Route-Parameter entgegen, übergeben Sie diese als zweites Argument als assoziatives Array.

$url = action([UserController::class, 'profile'], ['id' => 1]);

​

Fluent URI-Objekt

Die URI-Klasse von Laravel bietet eine fluent-Schnittstelle zum Erzeugen und Bearbeiten von URIs als Objekt.

use App\Http\Controllers\UserController;
use Illuminate\Support\Uri;

// URI-Instanz aus String erzeugen
$uri = Uri::of('https://example.com/path');

// URI zu Pfad, benannter Route oder Controller-Action
$uri = Uri::to('/dashboard');
$uri = Uri::route('users.show', ['user' => 1]);
$uri = Uri::signedRoute('users.show', ['user' => 1]);
$uri = Uri::temporarySignedRoute('user.index', now()->plus(minutes: 5));
$uri = Uri::action([UserController::class, 'index']);

// URI-Instanz aus der aktuellen Request-URL
$uri = $request->uri();

Sobald Sie eine URI-Instanz haben, können Sie sie fluent modifizieren.

$uri = Uri::of('https://example.com')
    ->withScheme('http')
    ->withHost('test.com')
    ->withPort(8000)
    ->withPath('/users')
    ->withQuery(['page' => 2])
    ->withFragment('section-1');

​

Default-Werte für URL-Parameter

Für bestimmte URL-Parameter möchten Sie eventuell requestweite Default-Werte setzen. Beispiel: Viele Routen enthalten einen {locale}-Parameter.

Route::get('/{locale}/posts', function () {
    // ...
})->name('post.index');

Bei jedem Aufruf von route explizit locale mitzugeben ist umständlich. Mit URL::defaults legen Sie für den aktuellen Request einen Standardwert fest. Diese Methode wird in der Regel innerhalb einer Route-Middleware aufgerufen, damit sie Zugriff auf den aktuellen Request hat.

<?php

namespace App\Http\Middleware;

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

class SetDefaultLocaleForUrls
{
    /**
     * Eingehenden Request verarbeiten.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        URL::defaults(['locale' => $request->user()->locale]);

        return $next($request);
    }
}

Sobald ein Default für locale gesetzt ist, müssen Sie ihn bei route-Aufrufen nicht mehr übergeben.

Das Setzen von URL-Defaults kann Laravels implizites Model Binding beeinträchtigen. Sorgen Sie über die Middleware-Priorität dafür, dass Ihre Default-Middleware vor der SubstituteBindings-Middleware ausgeführt wird. In bootstrap/app.php konfigurieren Sie das über die Methode priority.

->withMiddleware(function (Middleware $middleware): void {
    $middleware->prependToPriorityList(
        before: \Illuminate\Routing\Middleware\SubstituteBindings::class,
        prepend: \App\Http\Middleware\SetDefaultLocaleForUrls::class,
    );
})