Categoría: Laravel

Este artículo explica cómo reemplazar middleware que solo propagan datos por petición con un contexto scoped (AsyncRequestContext) en Laravel. El objetivo: reducir la complejidad de rutas, mejorar la claridad de dependencias y facilitar pruebas unitarias.

Incluye el diseño del contexto, el enlace en el service container y ejemplos de uso en acciones, controladores, rutas y pruebas.

• Introducción
• Prerrequisitos
• Desarrollo
• Ejemplos
• Checklist
• Conclusión

Introducción

El patrón AsyncRequestContext propone un contenedor ligero por petición para almacenar estado que actualmente se inyecta en Illuminate\Http\Request mediante middleware.

En lugar de ensuciar el Request con claves arbitrarias, se inicializa un contexto por ciclo de petición y se usa desde acciones y bindings del contenedor.

Prerrequisitos

Conocimientos básicos de Laravel: service container, providers, uso de acciones/servicios y rutas. No se requiere configuración adicional en el framework más allá de registrar el provider.

Desarrollo

La idea central es exponer un RequestContext scoped que se inicializa al enlazar en el container y se limpia en termination. Evita ‘request pollution’ y hace explícitas las dependencias.

<?php
namespace App\Context;

class RequestContext
{
    private static ?array $data = null;

    public static function initialize(): void
    {
        self::$data = [];
    }

    public static function set(string $key, mixed $value): void
    {
        self::$data[$key] = $value;
    }

    public static function get(string $key): mixed
    {
        return self::$data[$key] ?? null;
    }

    public static function flush(): void
    {
        self::$data = null;
    }
}
Lenguaje del código: PHP (php)

En el service provider se enlaza RequestContext para inicializarlo por petición y se registra un hook de terminating para limpiar el estado.

<?php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Context\RequestContext;

class ContextServiceProvider extends ServiceProvider
{
    public function boot()
    {
        $this->app->bind(RequestContext::class, function () {
            RequestContext::initialize();
            return new RequestContext();
        });

        $this->app->terminating(function () {
            RequestContext::flush();
        });
    }
}
Lenguaje del código: PHP (php)

Procedimiento

En lugar de usar middleware que sólo añade datos al Request, crea acciones que reciben el Request y escriben en el RequestContext. Eso permite invocarlas donde y cuando hagan falta.

<?php
namespace App\Actions;

use Illuminate\Http\Request;
use App\Context\RequestContext;
use App\Models\Tenant;

class ResolveTenant
{
    public function __construct(private RequestContext $context) {}

    public function execute(Request $request): void
    {
        $tenant = Tenant::fromDomain($request->host());
        $this->context->set('tenant', $tenant);
    }
}
Lenguaje del código: PHP (php)

Consume el contexto explícitamente en controladores o servicios, lo que revela dependencias y facilita pruebas unitarias.

<?php
namespace App\Http\Controllers;

use App\Context\RequestContext;

class ReportController
{
    public function index(RequestContext $context)
    {
        $tenant = $context->get('tenant');
        return $tenant->reports()->paginate();
    }
}
Lenguaje del código: PHP (php)

Las rutas pueden simplificarse ejecutando acciones de resolución dentro de la closure y pasando el contexto al controlador.

<?php
use App\Actions\ResolveTenant;
use App\Context\RequestContext;
use App\Http\Controllers\ReportController;
use Illuminate\Support\Facades\Route;

Route::get('/reports', function (
    ResolveTenant $resolve,
    RequestContext $context
) {
    $resolve->execute(request());
    return (new ReportController)->index($context);
})->middleware('auth:api');
Lenguaje del código: PHP (php)

Con este enfoque mantienes middleware para filtrado (autenticación, throttling) y usas acciones/contexto para propagar estado.

Ejemplos

Ejemplo de binding contextual que elige una implementación según un valor en RequestContext.

<?php
// En AppServiceProvider.php
$this->app->bind(ReportExporter::class, function () {
    $format = RequestContext::get('export_format') ?? 'csv';
    return match ($format) {
        'excel' => new ExcelExporter,
        'pdf'   => new PDFExporter,
        default => new CSVExporter,
    };
});
Lenguaje del código: PHP (php)

Prueba unitaria sin levantar el HTTP layer inicializando el contexto manualmente:

<?php
test('exports tenant reports in excel', function () {
    RequestContext::initialize();
    RequestContext::set('tenant', Tenant::factory()->create());
    RequestContext::set('export_format', 'excel');

    $exporter = app(ReportExporter::class);
    $this->assertInstanceOf(ExcelExporter::class, $exporter);
});
Lenguaje del código: PHP (php)

Checklist

1. Auditar middleware que solo escriben datos en el Request.
2. Refactorizar esas responsabilidades en acciones (ResolveX classes).
3. Sustituir $request->get(‘foo’) por $context->get(‘foo’) donde corresponda.
4. Reducir arrays de middleware en rutas dejando filtros reales (auth, throttle).
5. Asegurar que RequestContext::flush() se ejecuta en terminating.

Conclusión

AsyncRequestContext ofrece una alternativa práctica al uso excesivo de middleware para propagar estado por petición. Mejora la claridad, facilita pruebas y mantiene middleware para filtrado.

Middleware es para filtrado, no para propagar datos. Deja que el contexto lleve tu estado cross‑cutting.