Documentación de Laravel 10.x
Aquí encontrarás fragmentos de código de Laravel y consejos útiles sobre desarrollo web.
La clase Illuminate\Http\Request
de Laravel proporciona una forma orientada a objetos de interactuar con la solicitud HTTP actual que está siendo manejada por tu aplicación, así como de recuperar la entrada, las cookies y los archivos que se enviaron con la solicitud.
Para obtener una instancia de la solicitud HTTP actual a través de la inyección de dependencias, debes hacer referencia a la clase Illuminate\Http\Request
en tu cierre de ruta o método del controlador. La instancia de solicitud entrante se inyectará automáticamente mediante el contenedor de servicios de Laravel:
<?php namespace App\Http\Controllers; use Illuminate\Http\RedirectResponse;use Illuminate\Http\Request; class UserController extends Controller{ /** * Almacena un nuevo usuario. */ public function store(Request $request): RedirectResponse { $name = $request->input('name'); // Almacena el usuario... return redirect('/users'); }}
Como se mencionó, también puedes hacer referencia a la clase Illuminate\Http\Request
en una ruta. El contenedor de servicios inyectará automáticamente la solicitud entrante en el cierre cuando se ejecute:
use Illuminate\Http\Request; Route::get('/', function (Request $request) { // ...});
Si el método de tu controlador también espera la entrada de un parámetro de ruta, debes listar tus parámetros de ruta después de tus otras dependencias. Por ejemplo, si tu ruta está definida así:
use App\Http\Controllers\UserController; Route::put('/user/{id}', [UserController::class, 'update']);
Todavía puedes hacer referencia a la clase Illuminate\Http\Request
y acceder a tu parámetro de ruta id
definiendo tu método de controlador de la siguiente manera:
<?php namespace App\Http\Controllers; use Illuminate\Http\RedirectResponse;use Illuminate\Http\Request; class UserController extends Controller{ /** * Actualiza el usuario especificado. */ public function update(Request $request, string $id): RedirectResponse { // Actualiza el usuario... return redirect('/users'); }}
La instancia Illuminate\Http\Request
proporciona una variedad de métodos para examinar la solicitud HTTP entrante y extiende la clase Symfony\Component\HttpFoundation\Request
. Discutiremos algunos de los métodos más importantes a continuación.
El método path
devuelve la información de la ruta de la solicitud. Así que, si la solicitud entrante está dirigida a http://ejemplo.com/foo/bar
, el método path
devolverá foo/bar
:
$uri = $request->path();
El método is
te permite verificar que la ruta de la solicitud entrante coincide con un patrón dado. Puedes usar el carácter *
como comodín al utilizar este método:
if ($request->is('admin/*')) { // ...}
Utilizando el método routeIs
, puedes determinar si la solicitud entrante ha coincidido con una ruta con nombre:
if ($request->routeIs('admin.*')) { // ...}
Para recuperar la URL completa de la solicitud entrante, puedes usar los métodos url
o fullUrl
. El método url
devolverá la URL sin la cadena de consulta, mientras que el método fullUrl
incluye la cadena de consulta:
$url = $request->url(); $urlWithQueryString = $request->fullUrl();
Si deseas agregar datos de cadena de consulta a la URL actual, puedes llamar al método fullUrlWithQuery
. Este método fusiona la matriz dada de variables de cadena de consulta con la cadena de consulta actual:
$request->fullUrlWithQuery(['type' => 'phone']);
Si deseas obtener la URL actual sin un parámetro de cadena de consulta dado, puedes utilizar el método fullUrlWithoutQuery
:
$request->fullUrlWithoutQuery(['type']);
Puedes recuperar el "host" de la solicitud entrante mediante los métodos host
, httpHost
y schemeAndHttpHost
:
$request->host();$request->httpHost();$request->schemeAndHttpHost();
El método method
devolverá el verbo HTTP de la solicitud. Puedes usar el método isMethod
para verificar que el verbo HTTP coincide con una cadena dada:
$method = $request->method(); if ($request->isMethod('post')) { // ...}
Puedes recuperar una cabecera de la solicitud Illuminate\Http\Request
utilizando el método header
. Si la cabecera no está presente en la solicitud, se devolverá null
. Sin embargo, el método header
acepta un segundo argumento opcional que se devolverá si la cabecera no está presente en la solicitud:
$value = $request->header('X-Header-Name'); $value = $request->header('X-Header-Name', 'default');
El método hasHeader
se puede usar para determinar si la solicitud contiene una cabecera dada:
if ($request->hasHeader('X-Header-Name')) { // ...}
Para mayor comodidad, el método bearerToken
se puede utilizar para recuperar un token de portador de la cabecera Authorization
. Si no hay tal cabecera, se devolverá una cadena vacía:
$token = $request->bearerToken();
El método ip
se puede usar para recuperar la dirección IP del cliente que realizó la solicitud a tu aplicación:
$ipAddress = $request->ip();
Laravel proporciona varios métodos para inspeccionar los tipos de contenido solicitados de la solicitud entrante a través de la cabecera Accept
. En primer lugar, el método getAcceptableContentTypes
devolverá una matriz que contiene todos los tipos de contenido aceptados por la solicitud:
$contentTypes = $request->getAcceptableContentTypes();
El método accepts
acepta una matriz de tipos de contenido y devuelve true
si alguno de los tipos de contenido es aceptado por la solicitud. De lo contrario, se devolverá false
:
if ($request->accepts(['text/html', 'application/json'])) { // ...}
Puedes usar el método prefers
para determinar qué tipo de contenido de un conjunto dado de tipos de contenido es el más preferido por la solicitud. Si ninguno de los tipos de contenido proporcionados es aceptado por la solicitud, se devolverá null
:
$preferred = $request->prefers(['text/html', 'application/json']);
Dado que muchas aplicaciones solo sirven HTML o JSON, puedes usar el método expectsJson
para determinar rápidamente si la solicitud entrante espera una respuesta JSON:
if ($request->expectsJson()) { // ...}
La norma PSR-7 especifica interfaces para mensajes HTTP, incluidas solicitudes y respuestas. Si deseas obtener una instancia de una solicitud PSR-7 en lugar de una solicitud de Laravel típica, primero deberás instalar algunas bibliotecas. Laravel utiliza el componente Symfony HTTP Message Bridge para convertir solicitudes y respuestas típicas de Laravel en implementaciones compatibles con PSR-7:
composer require symfony/psr-http-message-bridgecomposer require nyholm/psr7
Una vez que hayas instalado estas bibliotecas, puedes obtener una solicitud PSR-7 tipando la interfaz de solicitud en el cierre de tu ruta o en el método del controlador:
use Psr\Http\Message\ServerRequestInterface; Route::get('/', function (ServerRequestInterface $request) { // ...});
Nota Si devuelves una instancia de respuesta PSR-7 desde una ruta o controlador, se convertirá automáticamente a una instancia de respuesta de Laravel y se mostrará mediante el framework.
Puedes recuperar todos los datos de entrada de la solicitud entrante como un array
utilizando el método all
. Este método se puede utilizar independientemente de si la solicitud entrante proviene de un formulario HTML o es una solicitud XHR:
$input = $request->all();
Utilizando el método collect
, puedes recuperar todos los datos de entrada de la solicitud entrante como una colección:
$input = $request->collect();
El método collect
también te permite recuperar un subconjunto de los datos de entrada de la solicitud entrante como una colección:
$request->collect('users')->each(function (string $user) { // ...});
Usando algunos métodos simples, puedes acceder a todos los datos de entrada del usuario desde tu instancia Illuminate\Http\Request
sin preocuparte por el verbo HTTP que se utilizó para la solicitud. Independientemente del verbo HTTP, se puede usar el método input
para recuperar la entrada del usuario:
$name = $request->input('name');
Puedes pasar un valor predeterminado como segundo argumento al método input
. Este valor se devolverá si el valor de entrada solicitado no está presente en la solicitud:
$name = $request->input('name', 'Sally');
Al trabajar con formularios que contienen entradas de array, usa la notación "dot" para acceder a los arrays:
$name = $request->input('products.0.name'); $names = $request->input('products.*.name');
Puedes llamar al método input
sin ningún argumento para recuperar todos los valores de entrada como un array asociativo:
$input = $request->input();
Mientras que el método input
recupera valores de todo el cuerpo de la solicitud (incluida la cadena de consulta), el método query
solo recuperará valores de la cadena de consulta:
$name = $request->query('name');
Si los datos del valor de la cadena de consulta solicitada no están presentes, se devolverá el segundo argumento de este método:
$name = $request->query('name', 'Helen');
Puedes llamar al método query
sin ningún argumento para recuperar todos los valores de la cadena de consulta como un array asociativo:
$query = $request->query();
Cuando envías solicitudes JSON a tu aplicación, puedes acceder a los datos JSON a través del método input
siempre que el encabezado Content-Type
de la solicitud esté correctamente establecido en application/json
. Incluso puedes usar la sintaxis "dot" para recuperar valores que están anidados dentro de arreglos u objetos JSON:
$name = $request->input('user.name');
En lugar de recuperar los datos de la solicitud como un string
primitivo, puedes usar el método string
para recuperar los datos de la solicitud como una instancia de Illuminate\Support\Stringable
:
$name = $request->string('name')->trim();
Al tratar con elementos HTML como casillas de verificación, tu aplicación puede recibir valores "verdaderos" que son cadenas en realidad. Por ejemplo, "true" o "on". Para mayor comodidad, puedes usar el método boolean
para recuperar estos valores como booleanos. El método boolean
devuelve true
para 1, "1", true, "true", "on" y "yes". Todos los demás valores devolverán false
:
$archived = $request->boolean('archived');
Para mayor comodidad, los valores de entrada que contienen fechas/horas se pueden recuperar como instancias de Carbon utilizando el método date
. Si la solicitud no contiene un valor de entrada con el nombre dado, se devolverá null
:
$birthday = $request->date('birthday');
Los segundos y terceros argumentos aceptados por el método date
se pueden usar para especificar el formato y la zona horaria de la fecha, respectivamente:
$elapsed = $request->date('elapsed', '!H:i', 'Europe/Madrid');
Si el valor de entrada está presente pero tiene un formato no válido, se lanzará una InvalidArgumentException
; por lo tanto, se recomienda que valides la entrada antes de invocar el método date
.
También se pueden recuperar valores de entrada que correspondan a enums de PHP de la solicitud. Si la solicitud no contiene un valor de entrada con el nombre dado o el enum no tiene un valor de respaldo que coincida con el valor de entrada, se devolverá null
. El método enum
acepta el nombre del valor de entrada y la clase enum como sus primeros y segundos argumentos, respectivamente:
use App\Enums\Status; $status = $request->enum('status', Status::class);
También puedes acceder a la entrada del usuario utilizando propiedades dinámicas en la instancia Illuminate\Http\Request
. Por ejemplo, si uno de los formularios de tu aplicación contiene un campo name
, puedes acceder al valor del campo así:
$name = $request->name;
Al usar propiedades dinámicas, Laravel buscará primero el valor del parámetro en la carga útil de la solicitud. Si no está presente, Laravel buscará el campo en los parámetros de la ruta coincidente.
Si necesitas recuperar un subconjunto de los datos de entrada, puedes usar los métodos only
y except
. Ambos métodos aceptan un único array
o una lista dinámica de argumentos:
$input = $request->only(['username', 'password']); $input = $request->only('username', 'password'); $input = $request->except(['credit_card']); $input = $request->except('credit_card');
Advertencia El método
only
devuelve todos los pares de clave/valor que solicitas; sin embargo, no devolverá pares de clave/valor que no estén presentes en la solicitud.
Puedes usar el método has
para determinar si un valor está presente en la solicitud. El método has
devuelve true
si el valor está presente en la solicitud:
if ($request->has('name')) { // ...}
Cuando se le da una matriz, el método has
determinará si todos los valores especificados están presentes:
if ($request->has(['name', 'email'])) { // ...}
El método hasAny
devuelve true
si alguno de los valores especificados está presente:
if ($request->hasAny(['name', 'email'])) { // ...}
El método whenHas
ejecutará el cierre dado si hay un valor presente en la solicitud:
$request->whenHas('name', function (string $input) { // ...});
Se puede pasar un segundo cierre al método whenHas
que se ejecutará si el valor especificado no está presente en la solicitud:
$request->whenHas('name', function (string $input) { // El valor "name" está presente...}, function () { // El valor "name" no está presente...});
Si deseas determinar si un valor está presente en la solicitud y no es una cadena vacía, puedes usar el método filled
:
if ($request->filled('name')) { // ...}
El método anyFilled
devuelve true
si alguno de los valores especificados no es una cadena vacía:
if ($request->anyFilled(['name', 'email'])) { // ...}
El método whenFilled
ejecutará el cierre dado si hay un valor presente en la solicitud y no es una cadena vacía:
$request->whenFilled('name', function (string $input) { // ...});
Se puede pasar un segundo cierre al método whenFilled
que se ejecutará si el valor especificado no está "filled":
$request->whenFilled('name', function (string $input) { // El valor "name" está lleno...}, function () { // El valor "name" no está lleno...});
Para determinar si una clave dada está ausente en la solicitud, puedes usar los métodos missing
y whenMissing
:
if ($request->missing('name')) { // ...} $request->whenMissing('name', function (array $input) { // Falta el valor "name"...}, function () { // El valor "name" está presente...});
A veces, es posible que debas fusionar manualmente datos de entrada adicionales en los datos de entrada existentes de la solicitud. Para hacer esto, puedes usar el método merge
. Si una clave de entrada dada ya existe en la solicitud, será sobrescrita por los datos proporcionados al método merge
:
$request->merge(['votes' => 0]);
El método mergeIfMissing
se puede utilizar para fusionar la entrada en la solicitud si las claves correspondientes aún no existen en los datos de entrada de la solicitud:
$request->mergeIfMissing(['votes' => 0]);
Laravel te permite conservar la entrada de una solicitud durante la próxima solicitud. Esta función es particularmente útil para volver a completar formularios después de detectar errores de validación. Sin embargo, si estás utilizando las características de validación incluidas en Laravel, es posible que no necesites utilizar manualmente estos métodos de parpadeo de entrada de sesión directamente, ya que algunas de las instalaciones de validación integradas de Laravel los llamarán automáticamente.
El método flash
en la clase Illuminate\Http\Request
parpadeará la entrada actual a la sesión para que esté disponible durante la próxima solicitud del usuario a la aplicación:
$request->flash();
También puedes usar los métodos flashOnly
y flashExcept
para parpadear un subconjunto de los datos de la solicitud a la sesión. Estos métodos son útiles para mantener información sensible como contraseñas fuera de la sesión:
$request->flashOnly(['username', 'email']); $request->flashExcept('password');
Dado que a menudo querrás parpadear la entrada a la sesión y luego redirigir a la página anterior, puedes encadenar fácilmente el parpadeo de entrada en una redirección usando el método withInput
:
return redirect('form')->withInput(); return redirect()->route('user.create')->withInput(); return redirect('form')->withInput( $request->except('password'));
Para recuperar la entrada parpadeada de la solicitud anterior, invoca el método old
en una instancia de Illuminate\Http\Request
. El método old
extraerá los datos de entrada parpadeados previamente de la sesión:
$username = $request->old('username');
Laravel también proporciona un ayudante global old
. Si estás mostrando la entrada antigua dentro de una plantilla Blade, es más conveniente usar el ayudante old
para repoblar el formulario. Si no existe entrada antigua para el campo dado, se devolverá null
:
<input type="text" name="username" value="{{ old('username') }}">
Todas las cookies creadas por el framework Laravel están cifradas y firmadas con un código de autenticación, lo que significa que se considerarán inválidas si han sido modificadas por el cliente. Para recuperar un valor de cookie de la solicitud, utiliza el método cookie
en una instancia de Illuminate\Http\Request
:
$value = $request->cookie('name');
De forma predeterminada, Laravel incluye los middleware App\Http\Middleware\TrimStrings
e Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull
en la pila global de middleware de tu aplicación. Estos middleware se enumeran en la pila global de middleware mediante la clase App\Http\Kernel
. Estos middleware recortarán automáticamente todos los campos de cadena entrantes en la solicitud, así como convertirán cualquier campo de cadena vacía a null
. Esto te permite no preocuparte por estas cuestiones de normalización en tus rutas y controladores.
Si deseas desactivar este comportamiento para todas las solicitudes, puedes eliminar los dos middleware de la pila de middleware de tu aplicación eliminándolos de la propiedad $middleware
de tu clase App\Http\Kernel
.
Si deseas deshabilitar el recorte de cadenas y la conversión de cadenas vacías para un subconjunto de solicitudes a tu aplicación, puedes usar el método skipWhen
ofrecido por ambos middleware. Este método acepta un cierre que debe devolver true
o false
para indicar si se debe omitir la normalización de la entrada. Típicamente, el método skipWhen
debería invocarse en el método boot
del AppServiceProvider
de tu aplicación.
use App\Http\Middleware\TrimStrings;use Illuminate\Http\Request;use Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull; /** * Inicializa cualquier servicio de la aplicación. */public function boot(): void{ TrimStrings::skipWhen(function (Request $request) { return $request->is('admin/*'); }); ConvertEmptyStringsToNull::skipWhen(function (Request $request) { // ... });}
Puedes recuperar archivos cargados de una instancia de Illuminate\Http\Request
utilizando el método file
o mediante propiedades dinámicas. El método file
devuelve una instancia de la clase Illuminate\Http\UploadedFile
, que extiende la clase PHP SplFileInfo
y proporciona una variedad de métodos para interactuar con el archivo:
$file = $request->file('photo'); $file = $request->photo;
Puedes determinar si hay un archivo presente en la solicitud utilizando el método hasFile
:
if ($request->hasFile('photo')) { // ...}
Además de verificar si el archivo está presente, puedes verificar que no haya habido problemas al cargar el archivo mediante el método isValid
:
if ($request->file('photo')->isValid()) { // ...}
La clase UploadedFile
también contiene métodos para acceder a la ruta completamente calificada del archivo y su extensión. El método extension
intentará adivinar la extensión del archivo en función de su contenido. Esta extensión puede ser diferente de la extensión proporcionada por el cliente:
$path = $request->photo->path(); $extension = $request->photo->extension();
Hay una variedad de otros métodos disponibles en las instancias de UploadedFile
. Consulta la documentación de la API para la clase para obtener más información sobre estos métodos.
Para almacenar un archivo cargado, normalmente utilizarás uno de tus sistemas de archivos configurados. La clase UploadedFile
tiene un método store
que moverá un archivo cargado a uno de tus discos, que puede ser una ubicación en tu sistema de archivos local o una ubicación de almacenamiento en la nube como Amazon S3.
El método store
acepta la ruta donde se debe almacenar el archivo en relación con el directorio raíz configurado del sistema de archivos. Esta ruta no debe contener un nombre de archivo, ya que se generará automáticamente un ID único para servir como nombre de archivo.
El método store
también acepta un segundo argumento opcional para el nombre del disco que se utilizará para almacenar el archivo. El método devolverá la ruta del archivo en relación con la raíz del disco:
$path = $request->photo->store('images'); $path = $request->photo->store('images', 's3');
Si no quieres que se genere automáticamente un nombre de archivo, puedes usar el método storeAs
, que acepta la ruta, el nombre del archivo y el nombre del disco como argumentos:
$path = $request->photo->storeAs('images', 'filename.jpg'); $path = $request->photo->storeAs('images', 'filename.jpg', 's3');
Nota Para obtener más información sobre el almacenamiento de archivos en Laravel, consulta la documentación completa de almacenamiento de archivos.
Al ejecutar tus aplicaciones detrás de un equilibrador de carga que termina certificados TLS/SSL, es posible que notes que tu aplicación a veces no genera enlaces HTTPS al usar el ayudante url
. Normalmente, esto se debe a que tu aplicación está recibiendo tráfico reenviado desde tu equilibrador de carga en el puerto 80 y no sabe que debería generar enlaces seguros.
Para resolver esto, puedes usar el middleware App\Http\Middleware\TrustProxies
que está incluido en tu aplicación Laravel, lo que te permite personalizar rápidamente los equilibradores de carga o proxies que deben ser confiables para tu aplicación. Tus proxies confiables deben figurar como un array en la propiedad $proxies
de este middleware. Además de configurar los proxies confiables, puedes configurar los $headers
del proxy que deben ser confiables:
<?php namespace App\Http\Middleware; use Illuminate\Http\Middleware\TrustProxies as Middleware;use Illuminate\Http\Request; class TrustProxies extends Middleware{ /** * Los proxies de confianza para esta aplicación. * * @var string|array */ protected $proxies = [ '192.168.1.1', '192.168.1.2', ]; /** * Las cabeceras que se deben usar para detectar proxies. * * @var int */ protected $headers = Request::HEADER_X_FORWARDED_FOR | Request::HEADER_X_FORWARDED_HOST | Request::HEADER_X_FORWARDED_PORT | Request::HEADER_X_FORWARDED_PROTO;}
Nota Si estás utilizando AWS Elastic Load Balancing, tu valor
$headers
debería serRequest::HEADER_X_FORWARDED_AWS_ELB
. Para obtener más información sobre las constantes que se pueden usar en la propiedad$headers
, consulta la documentación de Symfony sobre confiar en proxies.
Si estás utilizando Amazon AWS u otro proveedor de equilibradores de carga "en la nube", es posible que no conozcas las direcciones IP de tus equilibradores de carga reales. En este caso, puedes usar *
para confiar en todos los proxies:
/** * Los proxies de confianza para esta aplicación. * * @var string|array */protected $proxies = '*';
De forma predeterminada, Laravel responderá a todas las solicitudes que reciba independientemente del contenido del encabezado Host
de la solicitud HTTP. Además, el valor del encabezado Host
se utilizará al generar URL absolutas para tu aplicación durante una solicitud web.
Por lo general, debes configurar tu servidor web, como Nginx o Apache, para enviar solo las solicitudes a tu aplicación que coincidan con un nombre de host determinado. Sin embargo, si no tienes la capacidad de personalizar tu servidor web directamente y necesitas indicarle a Laravel que solo responda a ciertos nombres de host, puedes hacerlo habilitando el middleware App\Http\Middleware\TrustHosts
para tu aplicación.
El middleware TrustHosts
ya está incluido en la pila $middleware
de tu aplicación; sin embargo, debes descomentarlo para que esté activo. Dentro del método hosts
de este middleware, puedes especificar los nombres de host a los que tu aplicación debería responder. Las solicitudes entrantes con otros encabezados de valor Host
serán rechazadas:
/** * Obtiene los patrones de host que deben ser de confianza. * * @return array<int, string> */public function hosts(): array{ return [ 'laravel.test', $this->allSubdomainsOfApplicationUrl(), ];}
El método ayudante allSubdomainsOfApplicationUrl
devolverá una expresión regular que coincida con todos los subdominios de la URL de aplicación app.url
de tu aplicación. Este método ayudante proporciona una forma conveniente de permitir todos los subdominios de tu aplicación al construir una aplicación que utiliza subdominios comodín.