Generación de URLs - Knowledge of Laravel

Introducción

Laravel proporciona varios helpers para generar URLs de tu aplicación. Son especialmente útiles al construir enlaces en plantillas o respuestas de API, o al generar respuestas de redirección a otra parte de la aplicación.

Uso básico

Generar URLs

Con el helper url puedes generar cualquier URL. La URL generada utiliza automáticamente el esquema (HTTP o HTTPS) y el host de la solicitud actual.

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

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

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

Para generar una URL con parámetros de query string, usa el método 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

Si indicas parámetros de query que ya existen en la ruta, se sobrescriben los valores existentes.

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

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

También puedes pasar valores como array. Estos valores se indexan correctamente y se codifican en la URL generada.

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

Obtener la URL actual

Si no pasas una ruta al helper url, se devuelve una instancia de Illuminate\Routing\UrlGenerator que da acceso a información sobre la URL actual.

// URL actual sin query string
echo url()->current();

// URL actual con query string
echo url()->full();

También puedes acceder a estos métodos con la fachada URL.

use Illuminate\Support\Facades\URL;

echo URL::current();

Obtener la URL anterior

A veces querrás saber la URL que visitaba el usuario justo antes. Puedes obtenerla con previous o previousPath del helper url.

// URL completa de la solicitud anterior
echo url()->previous();

// Ruta de la solicitud anterior
echo url()->previousPath();

También puedes obtenerla a través de la sesión.

use Illuminate\Http\Request;

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

    // ...
});

Y también el nombre de ruta de la última URL visitada.

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

URLs de rutas con nombre

El helper route sirve para generar URLs de rutas con nombre. Con rutas con nombre puedes generar URLs sin depender de la URL real definida en la ruta. Así, aunque la URL cambie, no necesitas modificar las llamadas a route.

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

Genera la URL a esta ruta así:

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

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

También funciona con rutas de varios parámetros.

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

Los elementos del array que no coincidan con parámetros de la ruta se añaden como query string.

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

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

Modelos Eloquent

Es habitual generar URLs con la clave de ruta (normalmente la clave primaria) de un modelo Eloquent. Puedes pasar el modelo directamente como parámetro. route extraerá automáticamente la clave de ruta del modelo.

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

URLs firmadas

Laravel facilita la creación de URLs “firmadas” a rutas con nombre. A la URL se le añade un hash de “firma” en el query string, lo que permite a Laravel comprobar que la URL no ha sido manipulada tras su creación. Las URLs firmadas son muy útiles en rutas de acceso público que necesitan protección frente a manipulación. Por ejemplo, puedes usar URLs firmadas para implementar un enlace público de “cancelar suscripción” que envías por correo. Créalas con signedRoute de la fachada URL.

use Illuminate\Support\Facades\URL;

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

Con el argumento absolute de signedRoute puedes excluir el dominio del hash de firma.

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

Para generar una URL firmada temporal que caduque tras un tiempo dado, usa temporarySignedRoute. Al validar una URL firmada temporal, Laravel comprueba que el timestamp de caducidad codificado en la URL no haya pasado.

use Illuminate\Support\Facades\URL;

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

Flujo de verificación de la URL firmada

Verificar solicitudes con ruta firmada

Para comprobar que la solicitud entrante tiene una firma válida, llama a hasValidSignature sobre la instancia Illuminate\Http\Request.

use Illuminate\Http\Request;

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

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

Si quieres ignorar ciertos parámetros del query string al validar, usa hasValidSignatureWhileIgnoring.

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

En lugar de la instancia de la solicitud, puedes asignar el middleware signed (Illuminate\Routing\Middleware\ValidateSignature) a la ruta. Si la solicitud no tiene una firma válida, el middleware responde automáticamente con 403.

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

Si la URL firmada no incluye el dominio, indícalo con el argumento relative en el middleware.

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

Respuesta a rutas firmadas no válidas

Cuando se accede a una URL firmada caducada, se muestra una página de error genérica con código HTTP 403. Puedes personalizar este comportamiento definiendo un closure de “render” para la excepción InvalidSignatureException en bootstrap/app.php.

use Illuminate\Routing\Exceptions\InvalidSignatureException;

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

URLs de acciones de controlador

La función action genera la URL de una acción de controlador determinada.

use App\Http\Controllers\HomeController;

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

Si el método del controlador recibe parámetros de ruta, pasa un array asociativo como segundo argumento.

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

Objeto URI fluido

La clase URI de Laravel proporciona una interfaz fluida para crear y manipular URIs mediante objetos.

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

// Crear una instancia URI desde un string
$uri = Uri::of('https://example.com/path');

// Generar un URI a una ruta, ruta con nombre o acción de controlador
$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']);

// Crear una instancia URI desde la URL de la solicitud actual
$uri = $request->uri();

Una vez obtenida la instancia, puedes modificarla de forma fluida.

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

Parámetros de URL por defecto

A veces querrás fijar un valor por defecto para ciertos parámetros de URL en toda la solicitud. Por ejemplo, imagina que muchas rutas tienen un parámetro {locale}.

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

Pasar locale cada vez que se llama a route resulta pesado. Con URL::defaults puedes definir un valor por defecto de este parámetro que se aplique durante toda la solicitud actual. Llamando a este método desde un middleware de ruta puedes acceder a la solicitud actual.

<?php

namespace App\Http\Middleware;

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

class SetDefaultLocaleForUrls
{
    /**
     * Procesa la solicitud entrante.
     *
     * @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);
    }
}

Con el valor por defecto de locale establecido, ya no hace falta pasarlo al generar URLs con route.

Establecer valores por defecto puede interferir con el implicit model binding de Laravel. Ordena las prioridades del middleware para que el que establece los defaults se ejecute antes que el SubstituteBindings de Laravel. Puedes configurar la prioridad del middleware con el método priority en bootstrap/app.php.

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

​Introducción

​Uso básico

​Generar URLs

​Obtener la URL actual

​Obtener la URL anterior

​URLs de rutas con nombre

​Modelos Eloquent

​URLs firmadas

​Flujo de verificación de la URL firmada

​Verificar solicitudes con ruta firmada

​Respuesta a rutas firmadas no válidas

​URLs de acciones de controlador

​Objeto URI fluido

​Parámetros de URL por defecto