Service Mocking Laravel Package

Product Decisions This Supports

• Test strategy investment: Deciding whether to expand integration/functional coverage of a fully-booted application rather than only unit tests. Replacing non-deterministic edges (payments, email, third-party APIs) inside the container lets you exercise real routing, middleware, and wiring while keeping tests deterministic — a cheaper route to confidence than refactoring every dependency to be injectable first.
• Build vs. buy for test tooling: Weighing a small MIT dev-only package against writing an internal container-swap helper. The concept is compact (a trait plus a compiler pass, ~50 lines of real logic), so the decision should hinge on maintenance appetite and stack fit — not on raw capability.
• CI cost and reliability: Substituting mocks for outbound calls reduces paid sandbox spend, avoids vendor rate limits, and removes network flakiness from pipelines — a direct hit on both CI bills and flaky-test toil.
• Roadmap enabler for vendor integrations: Contract tests around vendor SDKs, webhook handlers, and payment flows become feasible when the vendor client can be swapped in the container without touching production code.
• Release confidence and cadence: Shortens the loop between "service is wired" and "service is verified," supporting smaller increments and fewer manual QA passes.
• A caution on this specific package: Its real value proposition is replacing private, already-wired services inside a Symfony-compiled container — a problem Laravel has largely already solved natively ($this->mock(), $this->instance(), $this->spy(), Http::fake(), Mail::fake(), Queue::fake()). For a Laravel-first estate, the honest framing is "adopt the pattern, not the dependency."

When to Consider This Package

• You have a genuine Symfony surface — a legacy service, an extracted microservice, a queue worker, a CLI tool, or a partner team's Symfony test suite — and you need to replace a service inside a compiled container, where $container->set() doesn't reach private/constructor-injected services. That is the package's legitimate home.
• You boot the full framework in tests and need to mock a service that is private, eagerly instantiated, or unreachable via a facade — i.e., where the framework's native public-binding helpers don't get you there.
• You have legacy service-locator code (app()->make(), Container::get()) that can't be refactored this quarter but still needs deterministic tests.
• Adoption criteria: treat it as a dev-only dependency, pin the version, register the bundle only in the test environment, and wrap it behind a single internal test helper so a future swap is a one-file change. Someone must own that wrapper.
• Look elsewhere if: you're on modern Laravel, where native fakes and instance swaps already cover the seam; if you can refactor to constructor injection; or if your OSS policy requires actively maintained dependencies with broad adoption. 45 stars and 0 dependents is a thin support signal, and single-maintainer status is a real bus-factor risk. In those cases, either vendor/fork it or build the internal equivalent.

How to Pitch It (Stakeholders)

• Executives: A free, MIT-licensed, test-only tool that makes integration tests deterministic and cheaper to run — fewer paid sandbox calls, less CI flakiness, faster feedback. It has zero production code or runtime footprint: it ships as a require-dev dependency and can be removed without a release. Caveat stated up front: it is a Symfony package, not a Laravel one, and adoption is thin (45 stars, 0 dependents, single maintainer). Frame it as a tactical convenience worth a one-sprint spike, not a platform bet — and only proceed for the parts of the estate that are genuinely Symfony.
• Engineering: For Symfony surfaces, it lets us replace services inside an already-built container, so we can test real application wiring while mocking the expensive or unreliable edges. For Laravel, the smart move is to port the pattern: a small MockableServices test trait that resolves configured service IDs from app(), rebinds them to Mockery doubles in setUp(), and restores originals via app()->forgetInstance() in tearDown(). Either way, we ship it behind a thin internal wrapper with a pinned version; if the package stalls, we swap the wrapper's implementation in an afternoon.
• The one-line decision for the room: "Don't add this package to the Laravel app — Laravel already solves this natively. Use the real package only where a genuine Symfony container exists, and everywhere else adopt the idea via a ~1–3 day internal adapter. Record the outcome in an ADR so we don't re-litigate it every quarter."
• Risk framing to engineering: the dangerous failure mode isn't breakage, it's silent non-mocking — if code under test resolves a dependency via new or a static factory, the mock never injects and the test passes against the real service. Any adoption must include an assertion that the mock was actually used, or we risk eroding trust in the suite.