Laravel Actions Laravel Package

Technical Evaluation

Architecture fit. Laravel Actions is a convention layer, not infrastructure. It collapses the controller/service/job/listener/command split into a single class with a handle() method plus context-specific asX() methods, and dispatches that class through Laravel's existing container, router, queue, and event bus. For a codebase suffering from fat controllers, duplicated validation between FormRequest and job payloads, and logic scattered across listeners, this is a low-risk, high-leverage refactor target: the abstraction is thin, per-class reversible, and does not require schema, queue, or deployment changes. The architectural caveat is that the "one class, many contexts" model makes it easy to couple HTTP concerns (request binding, authenticated user, authorization) to asynchronous concerns (payload serialization, idempotency, retry semantics). That coupling must be policed by convention, not by the package.

Integration feasibility. composer require lorisleiva/laravel-actions, one artisan generator, and registering the class as an invokable route is the entire onboarding path. No migrations, no config publication required, no service provider work in the common case. Roughly a half-day spike to a working pilot. The real integration cost is not installation — it is agreeing on where actions live in the namespace, what handle() signatures are allowed to accept (serializable job payloads vs. Eloquent models vs. Request), and how authorization and validation are expressed.

Technical risk. Four items dominate:

Signals worth flagging to stakeholders: the repository exposes only README and releases (docs are hosted externally at laravelactions.com, not versioned in-repo), the aggregate score of 56.9 is middling, and dependents is reported as 0 — which almost certainly reflects measurement, not reality, but means we should not treat downstream-adoption data as evidence of production hardening.

Key questions.

1. Which Laravel/PHP versions must we support at rollout, and does that pin us to 2.9.x or 2.13.x? Are we willing to accept framework-version-driven upgrade pressure?
2. Do we need a fork-and-own contingency? The package is small enough that an internal fork is credible; is that budgeted?
3. Who is the internal owner/champion? A single-maintainer dependency without an internal owner is an unowned risk.
4. Are we standardizing on actions for new code only, or refactoring existing controllers? The answer changes scope by an order of magnitude.
5. Does our queue topology (unique jobs, debouncing, after-commit dispatch) interact with the job decorators we'd inherit?
6. Is external documentation acceptable, or do we require in-repo, versioned docs for compliance/knowledge continuity?

Verdict. Recommend adopt with guardrails — high pattern value, low switching cost, contained blast radius. Do not adopt as a mandated org-wide architecture without an internal owner and a documented exit path.

Integration Approach

Stack fit. Requires PHP 8.1+ and a modern Laravel. Version mapping must be pinned explicitly per application:

• ≤2.9.x → Laravel 10/11/12
• 2.10.0+ → Laravel 11/12/13, Laravel 10 dropped
• 2.13.0 adds debounced job support

For a Laravel 10 codebase, this is effectively a frozen dependency; for Laravel 12/13, it is actively tracked. Confirm before committing.

Migration path. Strangler-fig, not big-bang. Actions are ordinary classes callable via Action::run(...) from anywhere, so each conversion is independently revertible.

1. Pilot (1 sprint). Convert two or three high-churn service classes into actions; use them as objects only — no routing, no queuing. Measure diff size and reviewer comprehension.
2. Conventions + ADR. Codify: namespace/location, allowed handle() parameter types, when asController vs. a plain controller is permitted, when asJob is permitted, whether asListener is allowed at all, and where authorization/validation live.
3. Test standard. Standardize on the package's mocking helpers (Action::mock()) and assertPushed-style assertions before broad rollout — this is the largest day-to-day productivity gain and the hardest thing to retrofit.
4. Broad rollout. New feature slices adopt actions by default. Existing controllers are converted opportunistically when touched, not by a dedicated refactor epic.
5. Stabilize. Static analysis gate: enable the PHPStan extension at level 5 and raise incrementally.

Compatibility. Coexists cleanly with existing controllers, jobs, and listeners — no interception of framework behavior unless you opt in per class. Two watch items: auto-registration of routes and commands runs through lorisleiva/lody, so non-App namespaces need verification in the pilot; and the Octane path must be exercised explicitly (container and request resolved on demand) rather than assumed.

Sequencing. Freeze the Laravel upgrade decision before the pilot begins. Nothing in this package is harder to undo than a framework-version mismatch discovered mid-rollout, and the 2.10.0 drop-of-Laravel-10 precedent means the constraint set shifts within a minor-version story.

Operational Impact

Maintenance. Low surface area: one dependency, no migrations, no runtime services, no config to drift. The maintenance burden is concentrated in version bumps, which are gated on Laravel major releases rather than on the package's own cadence. Budget a standing line item for dependency-watch and a quarterly compatibility check. Documentation lives off-repo, so the durable artifact must be our internal conventions doc, not a link to laravelactions.com.

Support. MIT with no vendor. Support model is community PRs plus internal ownership. Mitigations: designate an internal owner, require a second engineer proficient in the trait lifecycle, and pre-evaluate a fork. The fork is genuinely viable — the package is a bounded set of traits and decorators — which materially de-risks the bus-factor concern. Do not, however, treat "we could fork it" as a plan; treat it as a contingency with an estimated cost.

Scaling. No material runtime overhead: controllers remain controllers, jobs remain jobs, and throughput characteristics are Laravel's, not the package's. The scaling risk is behavioral, not performance — actions dispatched as jobs inherit queue scaling, retry, and idempotency semantics that the class author may not have reasoned about when writing the same logic for the HTTP path. Enforce a rule: any action with an asJob method must document its idempotency and retry policy.

Failure modes to instrument or review for.

• Context drift — same action, different behavior under HTTP vs. queue: asController receives Request and authenticated user; the queued path has neither. Silent divergence, not a crash.
• Validation/authorization scoping — package-injected validation and authorization fire in the controller context; explicit-method routes deliberately skip them. Easy to create an unguarded endpoint by accident.
• Authorization with route parameters — injection behavior was only added in 2.12.0; older pins may authorize against incomplete context.
• Event/transaction ordering — ShouldDispatchAfterCommit listeners were misdetected until 2.10.2. If we rely on after-commit dispatch, pin accordingly.
• Octane request capture — historically resolved; re-verify under our Octane config rather than trusting the changelog.
• Decorator opacity — unique-job and debounce decorators alter dispatch behavior invisibly at the call site; require explicit tests for any action using them.
• Tooling regressions — IDE-helper and PHPStan interactions have broken before; keep both in CI as canaries.

Ramp-up. One to two days per engineer to be productive, split roughly: half a day on the pattern and lifecycle, half a day on testing/mocking, and the remainder on internal conventions. Reviewers take longer than authors — plan for one senior reviewer to absorb the pattern first and act as gatekeeper for the initial batch, otherwise the abstraction leaks into inconsistent usage and the productivity gain is consumed by review friction.