1. Conceptos básicos
  2. Solicitudes HTTP

Introducción

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.

Interactuar con la Solicitud

Acceder a 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) {
// ...
});

Inyección de Dependencias y Parámetros de Ruta

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');
}
}

Ruta, Host y Método de la Solicitud

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.

Obtener la Ruta de la Solicitud

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();

Inspeccionar la Ruta / Ruta de la Solicitud

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.*')) {
// ...
}

Obtener la URL de la Solicitud

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']);

Obtener el Host de la Solicitud

Puedes recuperar el "host" de la solicitud entrante mediante los métodos host, httpHost y schemeAndHttpHost:

$request->host();
$request->httpHost();
$request->schemeAndHttpHost();

Obtener el Método de la Solicitud

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')) {
// ...
}

Cabeceras de la Solicitud

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();

Dirección IP de la Solicitud

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();

Negociación de Contenido

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()) {
// ...
}

Solicitudes PSR-7

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-bridge
composer 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.

Entrada

Obtener Entrada

Obtener Todos los Datos de Entrada

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) {
// ...
});

Obtener un Valor de Entrada

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();

Obtener Entrada de la Cadena de Consulta

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();

Obtener Valores de Entrada JSON

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');

Obtener Valores de Entrada Stringable

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();

Obtener Valores de Entrada Booleanos

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');

Obtener Valores de Entrada de Fecha

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.

Obtener Valores de Entrada Enum

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);

Obtener Entrada a través de Propiedades Dinámicas

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.

Obtener una Porción de los Datos de Entrada

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.

Determinar si hay Entrada

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...
});

Combinar Entrada Adicional

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]);

Entrada Anterior

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.

Parpadeo de la Entrada en la Sesión

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');

Parpadeo de la Entrada y Redirección

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')
);

Obtener Entrada Antigua

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') }}">

Cookies

Obtener Cookies de las Solicitudes

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');

Recorte y Normalización de la Entrada

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.

Desactivar Normalización de Entrada

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) {
// ...
});
}

Archivos

Obtener Archivos Cargados

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')) {
// ...
}

Validar Cargas Exitosas

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()) {
// ...
}

Rutas de Archivos y Extensiones

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();

Otros Métodos de Archivo

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.

Almacenar Archivos Cargados

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.

Configurar Proxies de Confianza

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 ser Request::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.

Confiar en Todos los 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 = '*';

Configurar Hosts de Confianza

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.