Solicitudes HTTP

• Introducción
• Interacción con la solicitud
  • Accediendo a la solicitud
  • Ruta, host y método de la solicitud
  • Encabezados de la solicitud
  • Dirección IP de la solicitud
  • Negociación de contenido
  • Solicitudes PSR-7
• Entrada
  • Recuperando entrada
  • Presencia de entrada
  • Fusionando entrada adicional
  • Entrada antigua
  • Cookies
  • Recorte y normalización de entrada
• Archivos
  • Recuperando archivos subidos
  • Almacenando archivos subidos
• Configurando proxies confiables
• Configurando hosts confiables

#Introducción

La clase Illuminate\Http\Request de Laravel proporciona una forma orientada a objetos para interactuar con la solicitud HTTP actual que está manejando su aplicación, así como para recuperar la entrada, cookies y archivos que se enviaron con la solicitud.

#Interacción con la solicitud

#Accediendo a la solicitud

Para obtener una instancia de la solicitud HTTP actual mediante inyección de dependencias, debe indicar el tipo Illuminate\Http\Request en la función anónima de su ruta o en el método de su controlador. La instancia de la solicitud entrante será inyectada automáticamente por el contenedor de servicios de Laravel:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class UserController extends Controller
{
    /**
     * Almacenar un nuevo usuario.
     */
    public function store(Request $request): RedirectResponse
    {
        $name = $request->input('name');

        // Almacenar el usuario...

        return redirect('/users');
    }
}

Como se mencionó, también puede indicar el tipo Illuminate\Http\Request en una función anónima de ruta. El contenedor de servicios inyectará automáticamente la solicitud entrante en la función cuando se ejecute:

use Illuminate\Http\Request;

Route::get('/', function (Request $request) {
    // ...
});

#Inyección de dependencias y parámetros de ruta

Si su método de controlador también espera entrada de un parámetro de ruta, debe listar sus parámetros de ruta después de sus otras dependencias. Por ejemplo, si su ruta está definida así:

use App\Http\Controllers\UserController;

Route::put('/user/{id}', [UserController::class, 'update']);

Aún puede indicar el tipo Illuminate\Http\Request y acceder a su parámetro de ruta id definiendo su 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
{
    /**
     * Actualizar el usuario especificado.
     */
    public function update(Request $request, string $id): RedirectResponse
    {
        // Actualizar el usuario...

        return redirect('/users');
    }
}

#Ruta, host y método de la solicitud

La instancia Illuminate\Http\Request proporciona varios métodos para examinar la solicitud HTTP entrante y extiende la clase Symfony\Component\HttpFoundation\Request. A continuación, discutiremos algunos de los métodos más importantes.

#Recuperando la ruta de la solicitud

El método path devuelve la información de la ruta de la solicitud. Por ejemplo, si la solicitud entrante está dirigida a http://example.com/foo/bar, el método path devolverá foo/bar:

$uri = $request->path();

#Inspeccionando la ruta / ruta de la solicitud

El método is le permite verificar que la ruta de la solicitud entrante coincida con un patrón dado. Puede usar el carácter * como comodín al utilizar este método:

if ($request->is('admin/*')) {
    // ...
}

Usando el método routeIs, puede determinar si la solicitud entrante ha coincidido con una ruta nombrada:

if ($request->routeIs('admin.*')) {
    // ...
}

#Recuperando la URL de la solicitud

Para recuperar la URL completa de la solicitud entrante, puede 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 desea agregar datos de cadena de consulta a la URL actual, puede llamar al método fullUrlWithQuery. Este método fusiona el array dado de variables de cadena de consulta con la cadena de consulta actual:

$request->fullUrlWithQuery(['type' => 'phone']);

Si desea obtener la URL actual sin un parámetro de cadena de consulta dado, puede utilizar el método fullUrlWithoutQuery:

$request->fullUrlWithoutQuery(['type']);

#Recuperando el host de la solicitud

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

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

#Recuperando el método de la solicitud

El método method devolverá el verbo HTTP de la solicitud. Puede usar el método isMethod para verificar que el verbo HTTP coincida con una cadena dada:

$method = $request->method();

if ($request->isMethod('post')) {
    // ...
}

#Encabezados de la solicitud

Puede recuperar un encabezado de la solicitud desde la instancia Illuminate\Http\Request usando el método header. Si el encabezado no está presente en la solicitud, se devolverá null. Sin embargo, el método header acepta un segundo argumento opcional que se devolverá si el encabezado no está presente en la solicitud:

$value = $request->header('X-Header-Name');

$value = $request->header('X-Header-Name', 'default');

El método hasHeader puede usarse para determinar si la solicitud contiene un encabezado dado:

if ($request->hasHeader('X-Header-Name')) {
    // ...
}

Para mayor comodidad, el método bearerToken puede usarse para recuperar un token bearer del encabezado Authorization. Si no hay tal encabezado, se devolverá una cadena vacía:

$token = $request->bearerToken();

#Dirección IP de la solicitud

El método ip puede usarse para recuperar la dirección IP del cliente que realizó la solicitud a su aplicación:

$ipAddress = $request->ip();

Si desea recuperar un array de direcciones IP, incluyendo todas las direcciones IP del cliente que fueron reenviadas por proxies, puede usar el método ips. La dirección IP "original" del cliente estará al final del array:

$ipAddresses = $request->ips();

En general, las direcciones IP deben considerarse entradas no confiables y controladas por el usuario, y usarse solo con fines informativos.

#Negociación de contenido

Laravel proporciona varios métodos para inspeccionar los tipos de contenido solicitados en la solicitud entrante a través del encabezado Accept. Primero, el método getAcceptableContentTypes devolverá un array que contiene todos los tipos de contenido aceptados por la solicitud:

$contentTypes = $request->getAcceptableContentTypes();

El método accepts acepta un array de tipos de contenido y devuelve true si alguno de los tipos de contenido es aceptado por la solicitud. De lo contrario, devolverá false:

if ($request->accepts(['text/html', 'application/json'])) {
    // ...
}

Puede usar el método prefers para determinar qué tipo de contenido, de un array dado, 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, puede usar el método expectsJson para determinar rápidamente si la solicitud entrante espera una respuesta JSON:

if ($request->expectsJson()) {
    // ...
}

#Solicitudes PSR-7

El estándar PSR-7 especifica interfaces para mensajes HTTP, incluyendo solicitudes y respuestas. Si desea obtener una instancia de una solicitud PSR-7 en lugar de una solicitud Laravel, primero deberá instalar algunas bibliotecas. Laravel usa 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 haya instalado estas bibliotecas, puede obtener una solicitud PSR-7 indicando el tipo de la interfaz de solicitud en su función anónima de ruta o método de controlador:

use Psr\Http\Message\ServerRequestInterface;

Route::get('/', function (ServerRequestInterface $request) {
    // ...
});

#Entrada

#Recuperando entrada

#Recuperando todos los datos de entrada

Puede recuperar todos los datos de entrada de la solicitud entrante como un array usando el método all. Este método puede usarse independientemente de si la solicitud entrante proviene de un formulario HTML o es una solicitud XHR:

$input = $request->all();

Usando el método collect, puede recuperar todos los datos de entrada de la solicitud entrante como una colección:

$input = $request->collect();

El método collect también le permite recuperar un subconjunto de la entrada de la solicitud como una colección:

$request->collect('users')->each(function (string $user) {
    // ...
});

#Recuperando un valor de entrada

Con unos pocos métodos simples, puede acceder a toda la entrada del usuario desde su instancia Illuminate\Http\Request sin preocuparse por qué verbo HTTP se usó para la solicitud. Independientemente del verbo HTTP, el método input puede usarse para recuperar la entrada del usuario:

$name = $request->input('name');

Puede 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 tipo array, use la notación "punto" para acceder a los arrays:

$name = $request->input('products.0.name');

$names = $request->input('products.*.name');

Puede llamar al método input sin argumentos para recuperar todos los valores de entrada como un array asociativo:

$input = $request->input();

#Recuperando entrada desde la cadena de consulta

Mientras que el método input recupera valores de toda la carga útil de la solicitud (incluyendo la cadena de consulta), el método query solo recuperará valores de la cadena de consulta:

$name = $request->query('name');

Si el valor solicitado de la cadena de consulta no está presente, se devolverá el segundo argumento de este método:

$name = $request->query('name', 'Helen');

Puede llamar al método query sin argumentos para recuperar todos los valores de la cadena de consulta como un array asociativo:

$query = $request->query();

#Recuperando valores de entrada JSON

Al enviar solicitudes JSON a su aplicación, puede acceder a los datos JSON mediante el método input siempre que el encabezado Content-Type de la solicitud esté configurado correctamente como application/json. Incluso puede usar la sintaxis "punto" para recuperar valores anidados dentro de arrays / objetos JSON:

$name = $request->input('user.name');

#Recuperando valores de entrada como Stringable

En lugar de recuperar los datos de entrada de la solicitud como un string primitivo, puede usar el método string para obtener los datos de la solicitud como una instancia de Illuminate\Support\Stringable:

$name = $request->string('name')->trim();

#Recuperando valores de entrada booleanos

Al tratar con elementos HTML como casillas de verificación, su aplicación puede recibir valores "verdaderos" que en realidad son cadenas. Por ejemplo, "true" o "on". Para mayor comodidad, puede 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');

#Recuperando valores de entrada de fecha

Para mayor comodidad, los valores de entrada que contienen fechas / horas pueden recuperarse como instancias de Carbon usando 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 segundo y tercer argumentos aceptados por el método date pueden usarse para especificar el formato de la fecha y la zona horaria, respectivamente:

$elapsed = $request->date('elapsed', '!H:i', 'Europe/Madrid');

Si el valor de entrada está presente pero tiene un formato inválido, se lanzará una InvalidArgumentException; por lo tanto, se recomienda validar la entrada antes de invocar el método date.

#Recuperando valores de entrada Enum

Los valores de entrada que corresponden a enums de PHP también pueden recuperarse de la solicitud. Si la solicitud no contiene un valor de entrada con el nombre dado o el enum no tiene un valor respaldado 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:

use App\Enums\Status;

$status = $request->enum('status', Status::class);

#Recuperando entrada mediante propiedades dinámicas

También puede acceder a la entrada del usuario usando propiedades dinámicas en la instancia Illuminate\Http\Request. Por ejemplo, si uno de los formularios de su aplicación contiene un campo name, puede acceder al valor del campo así:

$name = $request->name;

Al usar propiedades dinámicas, Laravel primero buscará 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.

#Recuperando una parte de los datos de entrada

Si necesita recuperar un subconjunto de los datos de entrada, puede usar los métodos only y except. Ambos métodos aceptan un solo 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');

#Presencia de entrada

Puede 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 pasa un array, 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á la función dada si un valor está presente en la solicitud:

$request->whenHas('name', function (string $input) {
    // ...
});

Se puede pasar una segunda función 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 desea determinar si un valor está presente en la solicitud y no es una cadena vacía, puede 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á la función dada si un valor está presente en la solicitud y no es una cadena vacía:

$request->whenFilled('name', function (string $input) {
    // ...
});

Se puede pasar una segunda función al método whenFilled que se ejecutará si el valor especificado no está "llenado":

$request->whenFilled('name', function (string $input) {
    // El valor "name" está llenado...
}, function () {
    // El valor "name" no está llenado...
});

Para determinar si una clave dada está ausente en la solicitud, puede usar los métodos missing y whenMissing:

if ($request->missing('name')) {
    // ...
}

$request->whenMissing('name', function (array $input) {
    // El valor "name" está ausente...
}, function () {
    // El valor "name" está presente...
});

#Fusionando entrada adicional

A veces puede necesitar fusionar manualmente entrada adicional en los datos de entrada existentes de la solicitud. Para lograr esto, puede 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 puede usarse para fusionar entrada en la solicitud si las claves correspondientes no existen ya en los datos de entrada de la solicitud:

$request->mergeIfMissing(['votes' => 0]);

#Entrada antigua

Laravel le permite conservar la entrada de una solicitud para la siguiente solicitud. Esta característica es particularmente útil para rellenar formularios después de detectar errores de validación. Sin embargo, si está usando las funciones de validación incluidas en Laravel, es posible que no necesite usar manualmente estos métodos de almacenamiento en sesión, ya que algunas de las facilidades de validación integradas en Laravel los llamarán automáticamente.

#Almacenando entrada en la sesión

El método flash en la clase Illuminate\Http\Request almacenará la entrada actual en la sesión para que esté disponible durante la siguiente solicitud del usuario a la aplicación:

$request->flash();

También puede usar los métodos flashOnly y flashExcept para almacenar un subconjunto de los datos de la solicitud en 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');

#Almacenando entrada y luego redirigiendo

Como a menudo querrá almacenar la entrada en la sesión y luego redirigir a la página anterior, puede encadenar fácilmente el almacenamiento de entrada a 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')
);

#Recuperando entrada antigua

Para recuperar la entrada almacenada de la solicitud anterior, invoque el método old en una instancia de Illuminate\Http\Request. El método old extraerá los datos de entrada almacenados previamente de la sesión:

$username = $request->old('username');

Laravel también proporciona un helper global old. Si está mostrando entrada antigua dentro de una plantilla Blade, es más conveniente usar el helper old para rellenar el formulario. Si no existe entrada antigua para el campo dado, se devolverá null:

<input type="text" name="username" value="{{ old('username') }}">

#Cookies

#Recuperando 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 serán consideradas inválidas si han sido modificadas por el cliente. Para recuperar el valor de una cookie de la solicitud, use el método cookie en una instancia de Illuminate\Http\Request:

$value = $request->cookie('name');

#Recorte y normalización de entrada

Por defecto, Laravel incluye los middleware App\Http\Middleware\TrimStrings y Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull en la pila global de middleware de su aplicación. Estos middleware están listados en la pila global por 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ío a null. Esto le permite no preocuparse por estas normalizaciones en sus rutas y controladores.

#Deshabilitando la normalización de entrada

Si desea deshabilitar este comportamiento para todas las solicitudes, puede eliminar los dos middleware de la pila de middleware de su aplicación quitándolos de la propiedad $middleware de su clase App\Http\Kernel.

Si desea deshabilitar el recorte de cadenas y la conversión de cadenas vacías para un subconjunto de solicitudes a su aplicación, puede usar el método skipWhen que ofrecen ambos middleware. Este método acepta una función que debe devolver true o false para indicar si se debe omitir la normalización de entrada. Normalmente, el método skipWhen debe invocarse en el método boot del AppServiceProvider de su aplicación.

use App\Http\Middleware\TrimStrings;
use Illuminate\Http\Request;
use Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    TrimStrings::skipWhen(function (Request $request) {
        return $request->is('admin/*');
    });

    ConvertEmptyStringsToNull::skipWhen(function (Request $request) {
        // ...
    });
}

#Archivos

#Recuperando archivos subidos

Puede recuperar archivos subidos de una instancia Illuminate\Http\Request usando el método file o usando propiedades dinámicas. El método file devuelve una instancia de la clase Illuminate\Http\UploadedFile, que extiende la clase PHP SplFileInfo y proporciona varios métodos para interactuar con el archivo:

$file = $request->file('photo');

$file = $request->photo;

Puede determinar si un archivo está presente en la solicitud usando el método hasFile:

if ($request->hasFile('photo')) {
    // ...
}

#Validando cargas exitosas

Además de verificar si el archivo está presente, puede verificar que no hubo problemas al subir el archivo mediante el método isValid:

if ($request->file('photo')->isValid()) {
    // ...
}

#Rutas y extensiones de archivos

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 basándose en su contenido. Esta extensión puede ser diferente de la extensión que proporcionó 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. Consulte la documentación API de la clase para más información sobre estos métodos.

#Almacenando archivos subidos

Para almacenar un archivo subido, normalmente usará uno de sus sistemas de archivos configurados. La clase UploadedFile tiene un método store que moverá un archivo subido a uno de sus discos, que puede ser una ubicación en su sistema de archivos local o un almacenamiento en la nube como Amazon S3.

El método store acepta la ruta donde el archivo debe almacenarse relativa al 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 debe usarse para almacenar el archivo. El método devolverá la ruta del archivo relativa a la raíz del disco:

$path = $request->photo->store('images');

$path = $request->photo->store('images', 's3');

Si no desea que se genere automáticamente un nombre de archivo, puede usar el método storeAs, que acepta la ruta, el nombre de archivo y el nombre del disco como argumentos:

$path = $request->photo->storeAs('images', 'filename.jpg');

$path = $request->photo->storeAs('images', 'filename.jpg', 's3');

#Configurando proxies confiables

Cuando ejecuta sus aplicaciones detrás de un balanceador de carga que termina certificados TLS / SSL, puede notar que su aplicación a veces no genera enlaces HTTPS al usar el helper url. Normalmente, esto se debe a que su aplicación está recibiendo tráfico reenviado desde su balanceador de carga en el puerto 80 y no sabe que debe generar enlaces seguros.

Para solucionar esto, puede usar el middleware App\Http\Middleware\TrustProxies que se incluye en su aplicación Laravel, el cual le permite personalizar rápidamente los balanceadores de carga o proxies que deben ser confiables para su aplicación. Sus proxies confiables deben listarse como un array en la propiedad $proxies de este middleware. Además de configurar los proxies confiables, puede 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 confiables para esta aplicación.
     *
     * @var string|array
     */
    protected $proxies = [
        '192.168.1.1',
        '192.168.1.2',
    ];

    /**
     * Los encabezados que deben usarse 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;
}

#Confiando en todos los proxies

Si está usando Amazon AWS u otro proveedor de balanceadores de carga "en la nube", puede que no conozca las direcciones IP de sus balanceadores reales. En este caso, puede usar * para confiar en todos los proxies:

/**
 * Los proxies confiables para esta aplicación.
 *
 * @var string|array
 */
protected $proxies = '*';

#Configurando hosts confiables

Por defecto, 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 usará al generar URLs absolutas para su aplicación durante una solicitud web.

Normalmente, debería configurar su servidor web, como Nginx o Apache, para que solo envíe solicitudes a su aplicación que coincidan con un nombre de host dado. Sin embargo, si no tiene la capacidad de personalizar su servidor web directamente y necesita indicar a Laravel que solo responda a ciertos nombres de host, puede hacerlo habilitando el middleware App\Http\Middleware\TrustHosts para su aplicación.

El middleware TrustHosts ya está incluido en la pila $middleware de su aplicación; sin embargo, debe descomentarla para que se active. Dentro del método hosts de este middleware, puede especificar los nombres de host a los que su aplicación debe responder. Las solicitudes entrantes con otros valores de encabezado Host serán rechazadas:

/**
 * Obtener los patrones de host que deben ser confiables.
 *
 * @return array<int, string>
 */
public function hosts(): array
{
    return [
        'laravel.test',
        $this->allSubdomainsOfApplicationUrl(),
    ];
}

El método helper allSubdomainsOfApplicationUrl devolverá una expresión regular que coincide con todos los subdominios del valor de configuración app.url de su aplicación. Este método helper proporciona una forma conveniente de permitir todos los subdominios de su aplicación cuando construye una aplicación que utiliza subdominios comodín.