Z Engine Laravel Package

Product Decisions This Supports

• Test determinism as a platform capability vs. per-team hacks. Engine-level interception lets you freeze/pin time(), date(), random_bytes(), mt_rand(), and similar internals below your application code. That closes the gap left by Carbon::setTestNow() and PSR-20 clocks, which only work where code happens to call through your abstraction. Decision: fund a shared time-travel harness, or keep letting squads hand-roll it?
• Buy-vs-build on vendor SDKs. When a third-party SDK does something you can't configure (aggressive retries, hardcoded timeouts, an internal sleep(), a static singleton), the choice is normally fork/patch/wrap/replace. Runtime interception adds a fourth option: keep the vendor package, patch behavior in the test or edge environment. That's a roadmap-relevant cost lever.
• Legacy modernization sequencing. It buys time on code you can't refactor yet — final classes, static calls, global functions. Useful input to "which modules do we rewrite first" (answer: the ones we're currently monkey-patching).
• Fault injection / chaos testing. Deterministically forcing failures in internal calls is a cheap way to prove resilience claims (timeouts, circuit breakers, idempotency) before you commit to a reliability roadmap item.
• Long-running worker behavior (Swoole/RoadRunner/FrankenPHP context). The publishing org (symfony-swoole) signals intent around resident-memory runtimes; runtime patching without redeploy is a real, if risky, capability for hotfixing a single tenant's behavior in a worker pool.
• Explicit non-decision: this should not enter the customer-facing request path. It is not an architecture, tenancy-isolation, or performance strategy.

When to Consider This Package

Consider it when all of these hold:

• You must intercept calls you don't own — internal PHP functions, statics, finals — and DI decorators, Mockery, or refactoring are genuinely off the table.
• Scope is test-only or CLI-only, and the extension can be excluded from the production image entirely.
• You control the container/AMI build: ability to compile a C extension, pin the exact PHP minor version, no Windows, no shared-hosting, no managed runtime.
• You can wrap it behind a narrow internal adapter (TimeProvider, Interceptor) so exactly one module touches the engine API.
• Someone on the team will own a fork if upstream stalls.

Look elsewhere when:

• You just need test doubles → PHPUnit mocks, ClockMock, PSR-20 fakes. Cheaper, portable, no build step.
• You need it in production traffic → prefer a real seam in your code. Engine poking breaks under OPcache/JIT, obscures stack traces, defeats static analysis, and will not survive a PHP minor upgrade without a rebuild.
• You need performance → this is not an optimization tool; it's an instrumentation/manipulation tool.

Adoption gates (evidence, not vibes):

Recommended shape: a one-to-two sprint spike, test-only, one team, one use case (deterministic time), with a written exit plan. Kill it if the adapter can't hide 100% of the API.

How to Pitch It (Stakeholders)

To executives (one paragraph): This is a small, timeboxed experiment in making our test suites deterministic and reducing our dependence on forked vendor code. It is a low-cost option on a capability we currently pay for in engineer hours, not a platform commitment. The package itself is immature — negligible adoption, single-maintainer risk, and it requires a compiled PHP extension — so the ask is two engineer-weeks behind a feature boundary we can delete, with a go/no-go at the end. Expected payoff is faster, less flaky CI and avoided vendor forks; downside is capped at the spike cost.

To engineering: Treat it as a sharp tool, quarantined. One adapter interface, test/dev environments only, exact PHP version pinned in the image, extension excluded from production artifacts and blocked in CI policy. If the spike succeeds, we own the fork and the PHP-upgrade treadmill — say that out loud before starting. If we can't express the need as a clean interface that also works with a plain clock fake, we don't have a use case; we have a workaround.