Respuestas HTTP

• Creación de respuestas
  • Adjuntar encabezados a las respuestas
  • Adjuntar cookies a las respuestas
  • Cookies y cifrado
• Redirecciones
  • Redirección a rutas con nombre
  • Redirección a acciones de controlador
  • Redirección a dominios externos
  • Redirección con datos de sesión destellantes
• Otros tipos de respuestas
  • Respuestas de vista
  • Respuestas JSON
  • Descargas de archivos
  • Respuestas de archivos
• Macros de respuesta

Creación de respuestas

Cadenas y matrices

Todas las rutas y controladores deben devolver una respuesta que se enviará de vuelta al navegador del usuario. Laravel proporciona varias formas diferentes de devolver respuestas. La respuesta más básica es devolver una cadena desde una ruta o controlador. El framework convertirá automáticamente la cadena en una respuesta HTTP completa:

Route::get('/', function () {
    return 'Hello World';
});

Además de devolver cadenas desde tus rutas y controladores, también puedes devolver matrices. El framework convertirá automáticamente la matriz en una respuesta JSON:

Route::get('/', function () {
    return [1, 2, 3];
});

Nota ¿Sabías que también puedes devolver colecciones Eloquent desde tus rutas o controladores? Se convertirán automáticamente a JSON. ¡Inténtalo!

Objetos de respuesta

Por lo general, no solo devolverás cadenas o matrices simples desde las acciones de tus rutas. En cambio, devolverás instancias completas de Illuminate\Http\Response o vistas.

Devolver una instancia completa de Response te permite personalizar el código de estado HTTP y los encabezados de la respuesta. Una instancia de Response hereda de la clase Symfony\Component\HttpFoundation\Response, que proporciona una variedad de métodos para construir respuestas HTTP:

Route::get('/home', function () {
    return response('Hello World', 200)
                  ->header('Content-Type', 'text/plain');
});

Modelos y colecciones eloquent

También puedes devolver modelos y colecciones Eloquent ORM directamente desde tus rutas y controladores. Cuando lo haces, Laravel convertirá automáticamente los modelos y colecciones a respuestas JSON respetando los atributos ocultos del modelo:

use App\Models\User;
 
Route::get('/user/{user}', function (User $user) {
    return $user;
});

Adjuntar encabezados a las respuestas

Ten en cuenta que la mayoría de los métodos de respuesta son encadenables, lo que permite la construcción fluida de instancias de respuesta. Por ejemplo, puedes usar el método header para agregar una serie de encabezados a la respuesta antes de enviarla al usuario:

return response($content)
            ->header('Content-Type', $type)
            ->header('X-Header-One', 'Header Value')
            ->header('X-Header-Two', 'Header Value');

O puedes usar el método withHeaders para especificar una matriz de encabezados que se agregarán a la respuesta:

return response($content)
            ->withHeaders([
                'Content-Type' => $type,
                'X-Header-One' => 'Header Value',
                'X-Header-Two' => 'Header Value',
            ]);

Middleware de control de caché

Laravel incluye un middleware cache.headers, que se puede utilizar para establecer rápidamente el encabezado Cache-Control para un grupo de rutas. Las directivas deben proporcionarse utilizando el equivalente en "snake case" de la directiva de cache-control correspondiente y deben separarse por un punto y coma. Si se especifica etag en la lista de directivas, se establecerá automáticamente un identificador de ETag como el hash MD5 del contenido de la respuesta:

Route::middleware('cache.headers:public;max_age=2628000;etag')->group(function () {
    Route::get('/privacy', function () {
        // ...
    });
 
    Route::get('/terms', function () {
        // ...
    });
});

Adjuntar cookies a las respuestas

Puedes adjuntar una cookie a una instancia saliente de Illuminate\Http\Response usando el método cookie. Debes pasar el nombre, el valor y el número de minutos que la cookie debe considerarse válida a este método:

return response('Hello World')->cookie(
    'name', 'value', $minutes
);

El método cookie también acepta algunos argumentos adicionales que se usan con menos frecuencia. En general, estos argumentos tienen el mismo propósito y significado que los argumentos que se darían al método nativo setcookie de PHP:

return response('Hello World')->cookie(
    'name', 'value', $minutes, $path, $domain, $secure, $httpOnly
);

Si deseas asegurarte de que se envíe una cookie con la respuesta saliente pero aún no tienes una instancia de esa respuesta, puedes usar la fachada Cookie para "poner en cola" cookies para adjuntar a la respuesta cuando se envíe. El método queue acepta los argumentos necesarios para crear una instancia de cookie. Estas cookies se adjuntarán a la respuesta saliente antes de que se envíe al navegador:

use Illuminate\Support\Facades\Cookie;
 
Cookie::queue('name', 'value', $minutes);

Generación de instancias de cookies

Si deseas generar una instancia de Symfony\Component\HttpFoundation\Cookie que se pueda adjuntar a una instancia de respuesta en un momento posterior, puedes usar la función global cookie. Esta cookie no se enviará de vuelta al cliente a menos que se adjunte a una instancia de respuesta:

$cookie = cookie('name', 'value', $minutes);
 
return response('Hello World')->cookie($cookie);

Caducidad anticipada de cookies

Puedes eliminar una cookie caducándola mediante el método withoutCookie de una respuesta saliente:

return response('Hello World')->withoutCookie('name');

Si aún no tienes una instancia de la respuesta saliente, puedes usar el método expire de la fachada Cookie para caducar una cookie:

Cookie::expire('name');

Cookies y cifrado

Por defecto, todas las cookies generadas por Laravel están cifradas y firmadas para que no puedan ser modificadas o leídas por el cliente. Si deseas deshabilitar el cifrado para un subconjunto de cookies generadas por tu aplicación, puedes usar la propiedad $except del middleware App\Http\Middleware\EncryptCookies, que se encuentra en el directorio app/Http/Middleware:

/**
 * Nombres de las cookies que no deben ser cifradas.
 *
 * @var array
 */
protected $except = [
    'cookie_name',
];

Redirecciones

Las respuestas de redirección son instancias de la clase Illuminate\Http\RedirectResponse y contienen los encabezados adecuados necesarios para redirigir al usuario a otra URL. Hay varias formas de generar una instancia de RedirectResponse. El método más sencillo es usar la función global redirect:

Route::get('/dashboard', function () {
    return redirect('home/dashboard');
});

A veces puedes querer redirigir al usuario a su ubicación anterior, como cuando un formulario enviado no es válido. Puedes hacerlo usando la función global back. Dado que esta función utiliza la sesión, asegúrate de que la ruta que llama a la función back esté utilizando el grupo de middleware web:

Route::post('/user/profile', function () {
    // Validar la solicitud...
 
    return back()->withInput();
});

Redirección a rutas con nombre

Cuando llamas a la función redirect sin parámetros, se devuelve una instancia de Illuminate\Routing\Redirector, lo que te permite llamar a cualquier método en la instancia de Redirector. Por ejemplo, para generar una RedirectResponse a una ruta con nombre, puedes usar el método route:

return redirect()->route('login');

Si tu ruta tiene parámetros, puedes pasarlos como segundo argumento al método route:

// Para una ruta con la siguiente URI: /perfil/{id}
 
return redirect()->route('profile', ['id' => 1]);

Rellenar parámetros mediante modelos eloquent

Si estás redirigiendo a una ruta con un parámetro "ID" que se está completando desde un modelo Eloquent, puedes pasar el modelo en sí. El ID se extraerá automáticamente:

// Para una ruta con la siguiente URI: /perfil/{id}
 
return redirect()->route('profile', [$user]);

Si deseas personalizar el valor que se coloca en el parámetro de la ruta, puedes especificar la columna en la definición del parámetro de la ruta (/perfil/{id:slug}) o puedes anular el método getRouteKey en tu modelo Eloquent:

/**
 * Obtener el valor de la clave de ruta del modelo.
 */
public function getRouteKey(): mixed
{
    return $this->slug;
}

Redirección a acciones de controlador

También puedes generar redirecciones a acciones del controlador. Para hacerlo, pasa el nombre del controlador y la acción al método action:

use App\Http\Controllers\UserController;
 
return redirect()->action([UserController::class, 'index']);

Si la ruta de tu controlador requiere parámetros, puedes pasarlos como segundo argumento al método action:

return redirect()->action(
    [UserController::class, 'profile'], ['id' => 1]
);

Redirección a dominios externos

A veces es posible que necesites redirigir a un dominio fuera de tu aplicación. Puedes hacerlo llamando al método away, que crea una RedirectResponse sin codificación, validación ni verificación de URL adicionales:

return redirect()->away('https://www.google.com');

Redirección con datos de sesión destellantes

Las redirecciones a una nueva URL y el parpadeo de datos en la sesión generalmente se hacen al mismo tiempo. Normalmente, esto se hace después de realizar con éxito una acción cuando parpadeas un mensaje de éxito en la sesión. Por conveniencia, puedes crear una instancia de RedirectResponse y parpadear datos en la sesión en una sola cadena de métodos fluida:

Route::post('/user/profile', function () {
    // ...
 
    return redirect('dashboard')->with('status', 'Profile updated!');
});

Después de que el usuario sea redirigido, puedes mostrar el mensaje parpadeado desde la sesión. Por ejemplo, usando la sintaxis de Blade:

@if (session('status'))
    <div class="alert alert-success">
        {{ session('status') }}
    </div>
@endif

Redirección con entrada

Puedes usar el método withInput proporcionado por la instancia de RedirectResponse para parpadear los datos de entrada de la solicitud actual en la sesión antes de redirigir al usuario a una nueva ubicación. Esto se hace típicamente si el usuario ha encontrado un error de validación. Una vez que la entrada se ha parpadeado en la sesión, puedes recuperarla fácilmente durante la siguiente solicitud para repoblar el formulario:

return back()->withInput();

Otros tipos de respuestas

La función response se puede usar para generar otros tipos de instancias de respuesta. Cuando se llama a la función response sin argumentos, se devuelve una implementación del contrato Illuminate\Contracts\Routing\ResponseFactory. Este contrato proporciona varios métodos útiles para generar respuestas.

Respuestas de vista

Si necesitas control sobre el estado y los encabezados de la respuesta pero también necesitas devolver una vista como contenido de la respuesta, debes usar el método view:

return response()
            ->view('hello', $data, 200)
            ->header('Content-Type', $type);

Por supuesto, si no necesitas pasar un código de estado HTTP personalizado o encabezados personalizados, puedes usar la función global view.

Respuestas JSON

El método json establecerá automáticamente el encabezado Content-Type en application/json, así como convertirá la matriz dada a JSON usando la función json_encode de PHP:

return response()->json([
    'name' => 'Abigail',
    'state' => 'CA',
]);

Si deseas crear una respuesta JSONP, puedes usar el método json en combinación con el método withCallback:

return response()
            ->json(['name' => 'Abigail', 'state' => 'CA'])
            ->withCallback($request->input('callback'));

Descargas de archivos

El método download se puede usar para generar una respuesta que obliga al navegador del usuario a descargar el archivo en la ruta dada. El método download acepta un nombre de archivo como segundo argumento al método, que determinará el nombre de archivo que verá el usuario que descargue el archivo. Finalmente, puedes pasar una matriz de encabezados HTTP como tercer argumento al método:

return response()->download($pathToFile);
 
return response()->download($pathToFile, $name, $headers);

Advertencia Symfony HttpFoundation, que gestiona las descargas de archivos, requiere que el archivo que se está descargando tenga un nombre de archivo ASCII.

Descargas transmitidas

A veces puedes desear convertir la respuesta de cadena de una operación dada en una respuesta descargable sin tener que escribir el contenido de la operación en el disco. Puedes usar el método streamDownload en este escenario. Este método acepta un callback, un nombre de archivo y, de manera opcional, una matriz de encabezados como sus argumentos:

use App\Services\GitHub;
 
return response()->streamDownload(function () {
    echo GitHub::api('repo')
                ->contents()
                ->readme('laravel', 'laravel')['contents'];
}, 'laravel-readme.md');

Respuestas de archivos

El método file se puede usar para mostrar un archivo, como una imagen o PDF, directamente en el navegador del usuario en lugar de iniciar una descarga. Este método acepta la ruta al archivo como su primer argumento y una matriz de encabezados como su segundo argumento:

return response()->file($pathToFile);
 
return response()->file($pathToFile, $headers);

Macros de respuesta

Si deseas definir una respuesta personalizada que puedas reutilizar en varias de tus rutas y controladores, puedes usar el método macro en la fachada Response. Por lo general, debes llamar a este método desde el método boot de uno de los proveedores de servicios de tu aplicación, como el proveedor de servicios App\Providers\AppServiceProvider:

<?php
 
namespace App\Providers;
 
use Illuminate\Support\Facades\Response;
use Illuminate\Support\ServiceProvider;
 
class AppServiceProvider extends ServiceProvider
{
    /**
     * Inicializar cualquier servicio de la aplicación.
     */
    public function boot(): void
    {
        Response::macro('caps', function (string $value) {
            return Response::make(strtoupper($value));
        });
    }
}

La función macro acepta un nombre como su primer argumento y un cierre como su segundo argumento. El cierre de la macro se ejecutará al llamar al nombre de la macro desde una implementación de ResponseFactory o el ayudante response:

return response()->caps('foo');