Isolator Laravel Package

Product Decisions This Supports

• Test-coverage investment on legacy code (build vs. refactor). Isolator lets engineers stub global PHP functions (time(), mt_rand(), file_get_contents(), curl_exec(), sleep()) inside a test, so brittle procedural code can be covered with characterization tests before anyone commits to the cost of refactoring it to injectable services. This is a "buy a bridge, defer the rebuild" decision.
• Determinism / flakiness roadmap. Many intermittent test failures trace to wall-clock time, randomness, and network calls buried in global functions. This package converts those into controlled inputs, which is a prerequisite for turning CI red/green into a trustworthy signal — a quality decision, not just a tooling one.
• Feature work in time- and randomness-dependent domains. Expiring tokens, cache TTLs, retry/backoff, rate limiting, trial periods, A/B bucketing, and ID generation all become testable at boundaries (e.g. "what happens at exactly expires_at?") without sleeping in tests or shipping a clock abstraction first.
• Scope decision on an internal test-utility layer. The alternative is building and maintaining an in-house function-mocking harness. This package is a candidate to avoid that sunk cost — but see the risk flag below before treating it as cheaper.
• Use cases it unlocks concretely: testing scheduled-job logic without waiting, verifying that a payment retry stops after N attempts, asserting cache invalidation at TTL boundaries, and pinning randomness so a probabilistic branch is exercised.

When to Consider This Package

Consider it when:

• You own a legacy PHP 5.x/7.x-era codebase with heavy direct use of global functions and near-zero test coverage, and you need tests now to de-risk a migration or a rewrite.
• The code is already organized (or can be cheaply organized) into namespaces, since the interception mechanism depends on unqualified function calls resolving through a namespace-local shim.
• You are on an older PHPUnit generation and are not planning a test-stack upgrade in the same quarter.
• The work is explicitly time-boxed and transitional — you intend to replace it with injected collaborators as modules are touched.
• You have accepted that it is a dev-only dependency, so a stale version carries no production runtime exposure.

Look elsewhere when:

• You are on PHP 8+ or a modern PHPUnit. The last release is March 2015, and the package is built on PHPUnit's mock-object APIs (getMock) that were removed/changed in PHPUnit 6+; assume it needs patching or a fork. The 35-star, effectively single-maintainer footprint is a real bus-factor signal.
• Your architecture already permits constructor injection — inject a clock (Psr\Clock\ClockInterface), a PSR-18 HTTP client, and a filesystem abstraction (Flysystem) instead. Those are stable, well-maintained, and make the dependency explicit rather than magical.
• You have few call sites. If a codebase touches global functions in a handful of places, a small hand-rolled wrapper or php-mock/php-mock (actively maintained, same problem space) is the lower-risk call. Symfony's PHPUnit Bridge ClockMock covers the time-only case.
• The interception's invasiveness is unacceptable: it constrains how code is namespaced and how functions are called, which is a convention tax your team must actually agree to.

How to Pitch It (Stakeholders)

To executives: This is a zero-runtime-risk, MIT-licensed testing utility we would add as a dev-only dependency. It buys us the ability to put automated tests around legacy modules — particularly anything involving time, randomness, or network calls — without funding a refactor first. That directly reduces the cost of change and the frequency of flaky CI failures, and it lets us ship riskier features (retries, expiry, rate limits) with real evidence they behave at the edges. The caveat to state plainly: the package has not been released since 2015 and has a single-maintainer footprint, so I am recommending it as a transitional tool with a defined exit path — not as a permanent architectural commitment. Budget a small spike (1–2 days) to confirm it runs on our PHP/PHPUnit versions before we plan around it.

To engineering: Treat this as scaffolding, not architecture. It isolates global function calls so they can be stubbed in tests — the right move for legacy code you're not ready to refactor. But it's unmaintained since 2015 and depends on PHPUnit APIs that modern versions removed; expect to fork or pin. So: use it in modules we plan to touch anyway, write the tests, then replace it with injected collaborators (clock, HTTP client, filesystem) as we refactor out. If we're starting greenfield or already on PHP 8, skip it and inject the dependency — php-mock/php-mock is the maintained alternative if we need function-level mocking at all.