Documentación de Laravel 10.x
Aquí encontrarás fragmentos de código de Laravel y consejos útiles sobre desarrollo web.
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!
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');});
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;});
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', ]);
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 () { // ... });});
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);
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);
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');
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',];
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();});
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]);
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;}
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]);
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');
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
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();
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.
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
.
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'));
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.
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');
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);
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');