Runnable Laravel Package

Product Decisions This Supports

• Standardizing an action/service-layer convention. This package is the cheapest possible enforcement mechanism for "one class, one job." If you've debated whether to mandate action classes vs. fat controllers vs. god-services, Runnable makes the winning option also the easiest one to test — which is usually what determines whether a convention survives contact with a real sprint.
• Build vs. buy on test infrastructure. The alternative isn't "nothing," it's an internal base class, a hand-rolled fake registry, and per-test Mockery boilerplate that someone owns forever. Here the buy cost is one Composer line under MIT and the reversal cost is deleting an import. That asymmetry means this is a decision you can make at the team level, not the architecture-review level.
• Test-suite economics: CI runtime and flake rate. Container-level faking at the class boundary lets side-effecting work (payments, email, search, third-party APIs) stay out of feature tests without call-site mocking. That's a direct lever on CI minutes and on the "rerun the pipeline and hope" tax — both of which are measurable and both of which you can put in front of leadership.
• Integration-swap optionality. If the roadmap includes adding or replacing a vendor integration, a fake-able seam at every action boundary means the swap happens inside one class rather than across every caller. This is option value you buy now and exercise later.
• Testability as a design forcing function. Classes become fake-able precisely because they're container-resolved and single-purpose. Adopting the package nudges the codebase toward the shape you'd want anyway — useful when multiple squads contribute to one Laravel monolith and you need a shared seam, not a shared document.
• Low-risk roadmap sequencing. Adoption is additive: no schema, no infra, no deployment change, no vendor lock-in. It can ship per-module in a spare sprint slot rather than competing for a planning cycle. Decisions that cost nothing to reverse should not be scheduled like decisions that do.

When to Consider This Package

Adopt when:

• You're on Laravel and already resolve business logic through the container (app()->make(), constructor injection). Outside that, the value proposition collapses entirely.
• You have accumulated inconsistent test seams — some Mockery, some real integrations, some hand-rolled fakes — and want one convention instead of five.
• Your team writes many small focused classes and will actually keep doing so. The package rewards discipline; it doesn't create it.
• You resolve classes with explicit constructor parameters. v1.0.2 specifically fixes fakes being silently bypassed via app()->make(Action::class, ['dependency' => $dep]) — pin ≥ 1.0.2 or you'll hit a false-green test and lose a day.
• You want a dev/test-scoped utility, not a runtime framework. Scope it to the test seam and the decision stays small.

Look elsewhere when:

• The stack isn't Laravel, or logic is resolved via facades and service locators rather than the container.
• Procurement requires externally validated dependencies. 11 stars, 0 dependents, single-org maintainer, v1.x is the honest picture: no third-party production validation, no support channel, no community to ask when it breaks. Treat adoption as a maintenance commitment — plan to vendor or fork under MIT if it stalls.
• You need workflow capability: queued execution, retries, pipelines, telemetry, orchestration. This is a seam, not an engine. Reach for Laravel's queue/job primitives or a workflow package instead.
• Your architecture is queue- or event-first, where job-level faking already covers the boundary and this adds a second, overlapping concept.
• You'd be the first serious adopter and nobody owns the dependency. "0 dependents" means you are the validation.

One diligence item: the listed last release is 2026-10-02, which is future-dated relative to today. Verify the actual tag history and maintainer cadence before pinning — a surprising release date is a small thing that signals you should read the repo rather than the metadata.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed developer-productivity package, not a platform bet. It makes one architectural pattern — single-purpose classes resolved from Laravel's container — cheap to test, by letting teams substitute fakes for real integrations like payments and email. The expected outcomes are faster, less flaky CI and more consistent code across squads. There is no infrastructure, data, or vendor-lock-in implication; removing it means deleting a base-class import, and the MIT license gives us a fork escape hatch. The honest risk is maturity: early-stage, zero downstream dependents, limited maintainer visibility. So the ask is not adoption — it's a one-sprint pilot in a single bounded module with a before/after on test runtime and flake rate, plus an explicit decision point to fork or drop.

To engineering: Install the package, have focused action classes implement its runnable contract, resolve them through the container, and register fakes in tests instead of mocking call sites. Pin ≥ 1.0.2 — that release fixes fakes being bypassed when a class is resolved with explicit constructor parameters, which is exactly how most of our call sites work. Cost is minutes per class; reversal cost is near zero. We'll pilot in one module, capture test-duration and flakiness deltas, watch for fake state leaking across tests and binding collisions, and review after one sprint before making it a team convention. Success criteria are fewer mocks, less test setup, and clearer action boundaries — not novelty.