Laravel Event System Laravel Package

Getting Started

This package is a DTO-centric layer for Laravel that pairs data transfer objects with form requests, translatable request attributes, and an internal event system. The 2.3.0 release bumps the underlying core package (1.24 → 1.26) and touches all three areas, so start there.

1. Install and publish the package config, then confirm the core dependency resolved to ^1.26:

   composer require <vendor>/<package>:^2.3
   php artisan vendor:publish --tag=<package>-config
   

2. Look first at the DTO base class and the upgrade dto method referenced in the release notes. This is the method you call to convert a request (or array) into a DTO instance. Everything else — validation, translation, events — hangs off it.
3. Then read the form request classes, since 2.3.0 changed validation rules (status no longer nullable) and added translation attributes.
4. First use case: take an existing controller that validates with a FormRequest and manually maps $request->validated() into a model. Replace the manual mapping with the DTO's upgrade/fromRequest method, and dispatch through the package's event system service instead of firing model events directly.

A minimal first integration:

class StoreOrderRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'status' => ['required', 'string'], // no longer nullable as of 2.3.0
            'name'   => ['required', 'string'], // translation attributes apply here
        ];
    }
}

$dto = OrderDto::fromRequest($request); // or the renamed upgrade method

Implementation Patterns

DTO as the boundary object. Keep controllers thin: validate with the package request, upgrade to a DTO, and pass the DTO into a service or action. Avoid passing Request or raw arrays past the controller — the 2.3.0 core bump specifically targets the upgrade-into-DTO path, which suggests that is the intended seam.

Request → DTO → Event flow. The release also changes EventSystem Service. The idiomatic workflow appears to be: request validates, DTO is built, the DTO carries the payload into the event system, and listeners consume the DTO rather than the request. Register listeners in your service provider as usual, but verify registration after the upgrade — see Gotchas.

Translatable request attributes. 2.3.0 adds translation attributes to requests. Use these when a single form submission contains multiple locales (e.g. name.en, name.fr) instead of hand-rolling locale loops:

protected array $translatable = ['name', 'description'];

Then read the resolved per-locale values off the DTO rather than off $request->input().

DTO effects. The new "DTO effect" concept lets a DTO declare side effects that fire after construction. Keep effects idempotent and free of request access — they should operate purely on the DTO payload so they remain reusable from queue jobs and console commands, not just HTTP.

Cross-context reuse. Because the DTO constructor is decoupled from the request, build the same DTO from a queued job or an artisan command by passing an array. This is the main day-to-day payoff: one validation/translation/event contract shared by HTTP and non-HTTP entry points.

Gotchas and Tips

• Breaking: status is no longer nullable. Any request that previously omitted status will now fail validation. Audit every form request and every client integration (API consumers, seeders, tests) before deploying. If you genuinely need optional status, reintroduce nullable locally rather than pinning the old version.
• Transitive core upgrade (1.24 → 1.26). The DTO upgrade method signature changed twice across those minor versions. If you call it directly (rather than via fromRequest), check for renamed arguments or a changed return type. Run a full composer update <vendor>/core and inspect the diff — minor bumps on the core are the likeliest source of silent breakage here.
• Event system service changes. Re-verify listener registration and any cached event/service manifests (php artisan event:cache, optimize:clear). A changed service class frequently breaks apps that bound or extended the old implementation directly in a service provider.
• Debugging DTO construction. Failures during upgrade usually surface as an empty or partially-populated DTO rather than an exception. Dump the validated payload immediately before the upgrade call to isolate whether the problem is validation or mapping.
• Translation fallback. With multiple locales in one request, confirm your fallback_locale produces sensible values for missing translations — do not assume every locale key is present.
• Test surface changed. The release notes mention "changed test," which often signals adjusted assertion helpers or fixture shapes. Re-run your own suite against 2.3.0 rather than assuming the package's internal test changes are inert.
• Extension point. If the event system service is now resolved from the container, prefer binding your own implementation via the container over subclassing — that survives future core bumps more cleanly.