Laravel Actions Laravel Package

Technical Evaluation

What the package is. An opinionated implementation of the "action" pattern: one class encapsulates a single unit of business logic and can be invoked across Laravel contexts — HTTP controller, queued job, event listener, artisan command — without duplicating the class per entry point. Now at v0.2.3 (still pre-1.0).

Architecture fit

• Aligns with Laravel's invokable-controller and service-container idioms. If the team already practices Action-Domain-Responder or a service-layer convention, this formalizes what exists rather than importing a new paradigm.
• Overlap risk is real: lorisleiva/laravel-actions solves the same problem with far greater adoption. Running both is an architectural smell, not a feature.
• Coupling cost: business logic becomes bound to a framework-specific trait/base class, reducing portability to non-Laravel consumers (standalone workers, CLI tools, other services).

Integration feasibility

• Composer-only install, MIT, minimal transitive weight expected. Verify composer.json constraints against the app's Laravel and PHP versions before committing.
• Still seven stars and zero dependents — no third-party validation, no Stack Overflow corpus, no peer benchmarks. v0.2.3 is a quality signal from the maintainer, not an adoption signal.

Technical risk

• Adoption / bus factor — high. Single-maintainer, low-visibility project. A stall is absorbed entirely by us. v0.2.3 is one positive maintenance data point, not a trend; do not re-weight on a single patch.
• Magic-dispatch opacity — medium, reduced. v0.2.3 ("Static Analysis turned up to 11", improved parameter and return type declarations) directly targets the concern that trait/__call dispatch defeats IDE navigation and static analysis. This is the most relevant change in the release for us: the spike's exit criteria hinge on PHPStan/Larastan cleanliness, and typed signatures on the package surface make that materially more achievable. Caveat: typing the package's own surface does not automatically type our action classes — we still need Larastan rules and likely stubs/generics for the dispatch entry points.
• Serialization semantics — medium. The same class run as a controller may accept request-bound dependencies; run as a queued job it must serialize cleanly. Unchanged by this release; stricter constructor typing may actually surface non-serializable state earlier at dispatch, which is a mild improvement.
• Tightened typing under 0.x semver — low/medium, new. Improved parameter and return declarations shipped in a patch release can be a de-facto breaking change for anyone subclassing an action, overriding a method, or stubbing actions in tests with loose signatures. Pre-1.0 semver gives no compatibility guarantee, so each bump needs a read of the diff, not just a green CI run.

Key questions

1. What is the supported Laravel/PHP matrix, and is there a stated deprecation policy?
2. Is there a CI matrix and measurable coverage, and does the "static analysis at 11" claim run against the package only or also against consumer-style fixtures?
3. How does dispatch resolve constructor dependencies versus queue payloads — and what happens on a non-serializable property?
4. Does it declare a conflict with lorisleiva/laravel-actions, and are the interfaces interchangeable?
5. What is the upgrade story across Laravel majors — loose illuminate/* constraints or pinned? Is a 1.0 with a compatibility promise planned?
6. Were v0.2.3's signature changes non-breaking for subclassing and test doubles, and is there a changelog entry or PR we can read rather than infer?

Integration Approach

Stack fit. Designed for Laravel's container and queue subsystem. Fits if the codebase is Laravel-native with no multi-framework constraint and the team is on a currently supported major.

Migration path

1. Timeboxed spike (one sprint). Convert one low-risk, well-tested controller and one queued job into actions behind a feature flag. Measure: LOC delta, test pass rate, PHPStan/Larastan clean run. v0.2.3 makes the third metric a fair test rather than a foregone failure — run our own analysis level against a converted class, don't take the release note as proof.
2. Convention document. Publish the rule set — when to use an action versus a plain service versus a job; naming; where validation lives; how responses are returned per context; how actions are typed and stubbed in tests.
3. Bounded rollout. One domain module at a time. Do not mix with the competing package.
4. Exit criteria. If the spike still shows static-analysis friction — particularly if generics/stubs are needed to make dispatch calls type-safe — or ambiguous queue semantics, stop and retain the existing service-layer pattern.

Compatibility. Pin the version explicitly (0.2.3, not a caret range) in composer.json and add a conflict guard against lorisleiva/laravel-actions. Because typing tightened in a patch, re-run the full suite and Larastan after every bump while pre-1.0. Confirm it doesn't collide with existing base-controller or FormRequest conventions.

Sequencing. Spike → static-analysis config → conventions → module-by-module. Never a big-bang rewrite; the benefit is boilerplate reduction, which accrues incrementally by nature.

Operational Impact

Maintenance. MIT plus a small surface area means we can vendor or fork at low cost — but the obligation becomes ours. v0.2.3 shows active investment in code quality, which modestly lowers the "abandoned mid-major" probability, but a single release from a single maintainer is not evidence of a support commitment. Budget a recurring review at each Laravel major upgrade, plus a diff review on each 0.x bump; if the package lags, we are pinned.

Support. GitHub issues only, no vendor SLA. The escalation path is "read the source." Acceptable for a small internal utility; not acceptable on the critical path of revenue flows.

Scaling. Action classes are stateless and container-resolved; runtime overhead is negligible at any realistic request or queue volume. Stricter type declarations have no runtime cost. The scaling constraint here is cognitive, not computational — the pattern must stay consistent as headcount grows.

Failure modes to instrument

• Queued action with non-serializable state → job fails at dispatch or unserialize; add a lint/test over constructor arguments.
• Silent context drift — identical class behaves differently as controller versus job; cover both paths in tests.
• Tightened 0.x signatures break subclasses, overrides, or mocked actions → new with typed-declaration releases; pin exactly, and run the full suite plus static analysis on every upgrade.
• Package abandonment mid-Laravel-major → pin, then fork.
• Pattern proliferation (action and service and job for the same logic) → enforce in code review.

Ramp-up. Low for engineers already fluent in Laravel: roughly half a day plus the convention doc. Better type declarations slightly reduce the "what does this trait actually do" tax. The hidden cost remains reviewer discipline — without it, the pattern degrades into an inconsistent third way of doing things.

TPM recommendation. v0.2.3 improves the one axis the spike was designed to measure and is a genuine positive maintenance signal, but it does not change the adoption picture: seven stars, zero dependents, single maintainer, pre-1.0. Hold the prior position — green-light only the timeboxed spike, pin the exact version, and require PHPStan/Larastan cleanliness plus unambiguous queue semantics before any wider standardization. If the spike is inconclusive, adopt the pattern without the package — the pattern is free, the dependency is not.