Php Mock Prophecy Laravel Package

Product Decisions This Supports

• De-risking time-dependent features without refactors. Billing cycles, free-trial expiry, subscription renewals, token/session TTLs, rate limits, cooldowns, "last seen" displays and audit timestamps are the top source of flaky CI. This package lets tests pin time(), date(), mktime() and friends to deterministic values, so we can ship date-sensitive logic with trustworthy automated coverage instead of manual QA passes.
• Deterministic randomness for testable product rules. Referral codes, idempotency keys, coupon generation, A/B bucket assignment, pagination seeds and shuffle ordering can be pinned by mocking rand(), mt_rand(), random_int() and uniqid() — turning "sometimes fails" tests into reproducible cases.
• Legacy-code velocity vs. refactor trade-off. The clean answer is injecting a Clock/Randomizer interface. This package is the pragmatic alternative when a codebase calls time() directly in hundreds of places: it buys test coverage now and defers the DI refactor, letting us sequence that work on the roadmap rather than blocking a release on it.
• Test-strategy and tooling standardisation. Because it is Prophecy-specific, adopting it is implicitly a decision about our test stack. It matters only if we are — or plan to be — on phpspec/Prophecy; it is a signal to confirm which mocking framework is our house standard before we invest in shared test helpers.
• Build vs. buy for test infrastructure. The capability is small (a namespaced function-interception shim). "Buy" here means taking a dev-only dependency with a permissive licence and near-zero runtime footprint; "build" means an internal TestClock utility plus a slow migration to injectable time. The decision hinges on how much legacy code we intend to keep.
• Supply-chain and maintenance posture. 16 stars, a single maintainer ecosystem, WTFPL (no warranty, no vendor support) and a dev-only scope mean the blast radius is limited to CI. That is a low-risk, reversible bet — appropriate for a spike or a stabilisation sprint, not something to build a platform strategy on.

When to Consider This Package

Adopt when most of the following hold:

• The team uses phpspec/Prophecy. This is the Prophecy adapter; on PHPUnit the equivalent is php-mock/php-mock-phpunit. If we standardise on PHPUnit, this specific package is the wrong choice even though the underlying php-mock/php-mock capability is right.
• Code under test calls built-ins directly (time(), date(), rand(), file_get_contents(), sys_get_temp_dir(), header()), and refactoring to injected dependencies is not on the near-term roadmap.
• The code lives in a namespace and calls functions unqualified. The mechanism works by defining functions in the calling namespace; fully-qualified \time() calls or global-namespace code will not be intercepted. Verify this before committing — it is the most common reason a rollout stalls.
• We need targeted, per-test control rather than a global frozen clock for the whole suite; the mocking is opt-in inside individual specs.
• We accept the cost: a dev-only Composer dependency, extra test bootstrap wiring, measurable per-test overhead on large suites, and understanding that mocked time/randomness must never be treated as evidence about real cryptographic or production behaviour.
• We are stabilising, not architecting. Treat it as a bridge with an exit criterion (e.g. "retire once ClockInterface is injected in the billing and auth modules").

Look elsewhere when:

• New or greenfield code — design in a Clock/Randomizer abstraction from day one; it is cheaper, framework-agnostic and survives a test-framework change.
• The suite is PHPUnit/Pest-based — use the PHPUnit adapter or a clock library instead.
• We need production-grade vendor support, SLAs or security review — a 16-star, WTFPL-licensed package will not clear that bar, and its bus factor is effectively one ecosystem maintainer.
• Tests would become mocks-of-everything. Mocking many built-ins is a smell that the unit under test is doing too much; prefer a seam.
• Cryptographic correctness matters — pinning random_int() proves nothing about entropy in production; keep those assertions at the integration level.

How to Pitch It (Stakeholders)

To executives (one paragraph): A small, free, development-only add-on that lets our automated tests control time and randomness inside PHP code. In practice it removes a class of intermittent CI failures that currently cost engineering hours and occasionally let date-related bugs — trial expiry, renewals, rate limits — reach customers. It ships nothing to production, adds no runtime dependency, and requires no refactor to adopt, so it is a cheap, reversible way to raise release confidence on our time-sensitive revenue features while a longer-term cleanup is scheduled.

To engineering leadership: This is the Prophecy adapter from the php-mock family. It intercepts namespaced calls to built-ins so specs can return a fixed time() or rand(), eliminating sleep-based tests and flaky clock assertions in legacy code paths. Cost: one dev dependency, a bootstrap hook, and per-test overhead; the constraint is that it only intercepts unqualified built-in calls in namespaced code and only fits a Prophecy-based suite. Benefit: immediate, low-effort coverage of TTL, scheduling and expiry logic that is otherwise untestable without invasive changes.

To engineers: Use it as a scalpel, not a foundation. Mock exactly the built-ins a spec needs, keep the mocks local to the spec, and avoid broad global stubbing that hides real behaviour. Every time you reach for it in new code, ask whether a Clock or Randomizer dependency would be the better seam — and log that as tech debt if the answer is yes. Do not use it to "prove" security properties of randomness, and check the calling-namespace requirement first so we do not burn a sprint discovering interception does not apply.