Data objects, Concerns y Events: el reparto de apoyo de una Action en Laravel: 04 de 08
Qué corresponde a un Data object, un Concern o un Event alrededor de una Action de Laravel: reglas prácticas, las trampas (traits cajón de sastre, flujo oculto, eventos que corren sin tenant) y un ejemplo de facturas con tenant.
Qué corresponde a un Data object, un Concern o un Event alrededor de una Action de Laravel: reglas prácticas, las trampas (traits cajón de sastre, flujo oculto, eventos que corren sin tenant) y un ejemplo de facturas con tenant.
Imagina que la Action de aprobación del artículo anterior se mantiene limpia durante un mes. Luego producto pide cuatro cosas pequeñas: enviar un correo al cliente, empujar la factura al libro mayor, escribir una entrada de auditoría y avisar al canal de ventas. Cada una cabe en la transacción en tres líneas. Tras cuatro peticiones, la Action es el nuevo controlador gordo, y su firma se ha vuelto sin hacer ruido handle(array $data), donde nadie recuerda qué claves son obligatorias.
Una Action resuelve dónde vive la regla. No resuelve qué la alimenta, qué comparte con otras clases ni qué debe anunciar al resto de la app. Tres herramientas más pequeñas cubren eso: los Data objects para la entrada, los Concerns para las capacidades compartidas y los Events para los efectos secundarios. Las tres son fáciles de usar mal, así que este artículo dedica tanto tiempo a dónde se detiene cada una como a cómo funciona.
El array que sabía demasiado
Un array de entrada no tiene forma. ¿La clave es due_date o dueDate? ¿notes es opcional? ¿La cantidad es un string porque vino de un post de formulario? La Action no puede decirlo, tu editor tampoco, y un typo falla en tiempo de ejecución en producción.
Un Data object le da a la entrada un nombre y un tipo. En PHP moderno eso es una clase readonly:
final readonly class IssueInvoiceData
{
/** @param list<InvoiceLineData> $lines */
public function __construct(
public int $customerId,
public CarbonImmutable $dueDate,
public array $lines,
public ?string $notes = null,
) {}
public static function fromRequest(StoreInvoiceRequest $request): self
{
$input = $request->validated();
return new self(
customerId: (int) $input['customer_id'],
dueDate: CarbonImmutable::parse($input['due_date']),
lines: array_map(InvoiceLineData::fromArray(...), $input['lines']),
notes: $input['notes'] ?? null,
);
}
}
El cast (int) está ahí a propósito. Los posts de formulario entregan strings, y el Data object es el único lugar que los convierte. InvoiceLineData es otra clase readonly construida igual. Las clases readonly necesitan PHP 8.2 o superior.
Ahora la Action pide lo que necesita, y cada llamador tiene que proporcionarlo:
public function handle(IssueInvoiceData $data, User $author): Invoice
El mismo objeto sirve desde un controlador, una importación por consola, el payload de un job en cola o un test, sin copiar la lógica de mapeo.
Hay límites. Un Data object contiene datos y la forma de los datos. No consulta la base de datos, no aplica reglas de negocio ni pasea modelos de Eloquent. Y es excesivo para un método con dos argumentos escalares: ApproveInvoice no necesita uno. Paquetes como spatie/laravel-data automatizan el mapeo, y vale la pena mirarlos cuando escribir fromRequest a mano empiece a doler. Hasta entonces bastan las clases readonly simples.
Para qué sirve un Concern
Laravel mismo pone el comportamiento compartido de los modelos en un namespace Concerns, y el hábito vale la pena copiarlo. Un Concern es un trait que da a muchas clases la misma capacidad pequeña. El artículo del tenant tenía uno bueno, BelongsToCompany: engancha un scope, rellena una columna y se aplica a todos los modelos que pertenecen a un tenant. Otro podría ser:
trait Archivable
{
public function scopeActive(Builder $query): void
{
$query->whereNull('archived_at');
}
public function archive(): void
{
$this->forceFill(['archived_at' => now()])->save();
}
}
Una prueba rápida te dice si algo es un Concern. ¿Puedes nombrarlo como una capacidad, con un prefijo como Has, Belongs o un adjetivo como Archivable? Si el mejor nombre que encuentras es HandlesInvoiceApproval, es una Action disfrazada de trait.
El modo de fallo es el cajón de sastre. Un modelo de 3.000 líneas partido en ocho traits sigue siendo un modelo de 3.000 líneas, solo que más difícil de leer, porque los métodos están en ocho archivos y cada trait asume en silencio columnas que viven en otra parte. Tres costos a vigilar:
- Acoplamiento oculto: el trait usa
$this->statussin declarar que lo necesita. - Colisiones de nombres entre métodos de traits distintos.
- Tests que solo funcionan a través de un modelo que usa el trait.
Mantén los Concerns pequeños, con forma de capacidad y aburridos.
Events para lo que la Action no debe saber
Volvamos a las cuatro peticiones. Enviar el correo, actualizar el libro mayor y avisar al canal son reacciones a un hecho: una factura fue aprobada. La Action no necesita saber quién reacciona. Anuncia el hecho, y quien le interese escucha.
Una división útil: lo que debe tener éxito o fallar junto con la aprobación se queda dentro de la transacción de la Action. Lo que puede ocurrir después, o fallar por su cuenta, se vuelve un listener. El correo es un listener. El cambio de estado no.
final class InvoiceApproved implements ShouldDispatchAfterCommit
{
use Dispatchable;
public function __construct(
public readonly int $invoiceId,
public readonly int $companyId,
) {}
}
La interfaz ShouldDispatchAfterCommit importa. Según la documentación de eventos de Laravel, un evento así no se despacha hasta que la transacción abierta de la base de datos se confirma, y se descarta si la transacción falla. Sin ella, un listener en cola podría correr antes del commit, o enviar un correo por una aprobación que se revirtió.
La Action lo despacha desde dentro de la transacción, con ids en lugar de modelos, de modo que el payload sea pequeño y explícito:
InvoiceApproved::dispatch($invoice->id, $invoice->company_id);
El listener es donde vuelve el artículo del tenant. Un listener en cola corre en un worker, sin URL ni usuario, así que con un scope que falla cerrado no tiene empresa. La solución es el middleware de job que ya conocemos, que los listeners también soportan. Esta versión recibe el id en su constructor, porque un listener no puede leerlo del job como hacía el ejemplo anterior:
final class RunsAsCompany
{
public function __construct(private int $companyId) {}
public function handle(object $job, Closure $next): void
{
app(TenantContext::class)->runAs($this->companyId, fn () => $next($job));
}
}
final class SendApprovalEmail implements ShouldQueue
{
public function middleware(InvoiceApproved $event): array
{
return [new RunsAsCompany($event->companyId)];
}
public function handle(InvoiceApproved $event): void
{
$invoice = Invoice::findOrFail($event->invoiceId);
Mail::to($invoice->customer->email)->send(new InvoiceApprovedMail($invoice));
}
}
La documentación muestra el método middleware de un listener recibiendo el evento como argumento, y eso es lo que hace que esto funcione. Laravel descubre los listeners escaneando el directorio Listeners en busca de métodos handle con un evento tipado, así que no hay paso de registro. Cuando quieras ver el cableado, php artisan event:list lo imprime.
El camino completo queda así:

Lo que esto te cuesta
Los eventos cambian claridad por desacoplamiento, y la factura llega en cuatro lugares:
- Flujo oculto. Quien lea
ApproveInvoiceno ve el correo. Nombra los eventos en pasado, mantén pocos listeners y usaevent:list. Un evento con un solo listener y sin perspectiva de un segundo es una llamada a un método disfrazada. - Consistencia eventual. El correo llega después de la respuesta, y el libro mayor puede ir atrasado. La interfaz tiene que tolerarlo.
- Los listeners pueden correr dos veces. Las colas reintentan. Haz cada listener idempotente, para que un segundo correo o una segunda fila en el libro mayor no sea posible.
- Pruebas en dos partes. Simula el evento en el test de la Action (
Event::fake([InvoiceApproved::class])) y prueba cada listener por separado.
Los Data objects cuestan una clase por caso de uso. Los Concerns cuestan legibilidad en cuanto se multiplican. Ninguna de las tres es gratis, y ninguna hace falta el día uno.
Conclusión
La Action que derivaba hacia handle(array $data) ahora recibe un objeto tipado, deja sus capacidades a Concerns pequeños y anuncia lo que pasó en lugar de hacer las tareas de todos. Lo que cambió no es la cantidad de código. Es que cada pieza tiene una razón para existir y una razón para detenerse.
Para hoy: encuentra una Action con un argumento array y dale un Data object, y encuentra un trait cuyo nombre sea una frase verbal y pregunta si en realidad es una Action. El último artículo de la serie se aparta del código y mira el orden en que un proyecto como este se construye y se entrega de verdad.