Download the PHP package cleatsquad/php-http-replay without Composer

PHP HTTP Replay

Deterministic HTTP request recording and replay for PHP built on PSR-7 and PSR-18.

A test that calls a real API is slow, costs money, and fails for reasons that have nothing to do with your code. Record the exchange once, replay it forever after: the same request returns the same response, offline, in milliseconds. When the request no longer matches what was recorded, you get told exactly which field differed — not just that something did.

Architecture

php-http-replay separates the replay pipeline into four independent layers:

• Interception (HttpReplayEngine): PSR-18 client orchestrating replay, record, record-once, and passthrough modes.
• Selection (ExchangeSelectorInterface): Pluggable exchange selection strategies (UnorderedExchangeSelector).
• Matching (RequestMatcherInterface): Semantic JSON and HTTP request comparison producing detailed MatchResult diagnostics.
• Cassette Format v2: Versioned schema (version: 2) with SHA-256 checksum integrity and backward-compatible loading of legacy v1 cassettes.

Installation

Requires PHP 8.2 or later. The core depends on PSR interfaces only (psr/http-message, psr/http-client, psr/http-factory); Guzzle and Symfony YAML are optional and used only by the integration and import layers.

See UPGRADE.md for upgrade notes and compatibility guides between major/minor versions.

Usage

Execution Modes

• ExecutionMode::Replay : Performs no network calls and replays recorded responses from the cassette.
• ExecutionMode::Record : Sends real HTTP requests, sanitizes the response, appends the exchange to the cassette, and returns the response.
• ExecutionMode::RecordOnce : Replays if a matching exchange exists in the cassette; executes real network call, sanitizes, and appends to cassette if missing.
• ExecutionMode::Passthrough : Bypasses the replay engine and performs live HTTP calls without modifying cassettes.

Matching Modes & Strategies

By default, requests are matched sequentially (ExecutionMatchingMode::Sequential). You can configure non-sequential, out-of-order matching via ExecutionMatchingMode::Unordered (OPT-IN):

• ExecutionMatchingMode::Sequential (Default): Requests must match cassette exchanges in exact sequential order. Preserves deterministic response order for repeated identical requests.
• ExecutionMatchingMode::Unordered (OPT-IN): Requests can match any available, unconsumed exchange in the cassette. Useful for asynchronous, parallel, or non-deterministic test runners where request dispatch order varies. Once consumed, an exchange cannot be replayed.

Performance & Trade-offs: In Sequential mode, matching is $O(1)$ per request. In Unordered mode, matching is up to $O(N)$ per request where $N$ is the number of exchanges in the cassette. For large cassettes ($N > 1000$), Sequential mode is strongly recommended.

Matching

DefaultRequestMatcher compares method, URI, headers and body. JSON bodies are compared semantically: object key order is ignored, array element order is significant, and scalar types are compared strictly, so 1 does not match "1". Query parameters are compared as a set.

When nothing matches, RequestMismatchException (or UnorderedMismatchException in unordered mode) names the failing path, for instance body.messages.0.content, along with the expected and actual values.

Diagnostics & CLI Output

Difference, MatchResult, and RequestMismatchException offer multi-line CLI diagnostic output:

Output:

Sanitization & JSON Path Redaction

DefaultSanitizer redacts secrets in headers, URI query parameters, recursively in JSON bodies by key name, and by explicit JSON paths/pointers (e.g., $.user.profile.token or payment.card.number):

Storage Backends & Checksum Integrity

• JsonCassetteStore : Writes UTF-8 JSON atomically through a temporary file and LOCK_EX rename, stamped with a schema version and automatic SHA-256 integrity checksum (sha256:<hash>).
• InMemoryCassetteStore : RAM-only cassette store for fast, zero-I/O unit tests.

Replay Audit Trail & Inspection

HttpReplayEngine::stats() returns a ReplayStats snapshot to inspect cassette consumption:

unusedIndices lists the exchanges the cassette already held and that were never replayed, which is what a stale cassette looks like. An exchange recorded during the session by Record or RecordOnce is never counted as unused.

Cassette Naming Strategies

Use CassetteNamingStrategyInterface for dynamic cassette resolution:

Importing php-vcr cassettes

Optional Community Integrations

php-http-replay is fully autonomous and zero-dependency. Community integration packages can be installed separately:

• cleatsquad/php-http-replay-vcr (External adapter for legacy PHP-VCR storage)
• cleatsquad/php-http-replay-vcr-plugin (External adapter for HTTPlug pipeline)
• cleatsquad/php-http-replay-phpunit (Tooling package for PHPUnit 11 #[Cassette] attributes)

Limitations

• Asynchronous execution: GuzzleReplayHandler returns Guzzle promises, but the underlying replay and record paths are synchronous (PSR-18 sendRequest), so promises settle on invocation. True event-loop streaming is out of scope.
• Streaming and SSE: transport-level timing and chunk boundaries for Server-Sent Events are not reproduced. Stream bodies remain readable in full through PSR-7.

Public API

Everything under src/ that is public follows Semantic Versioning, except src/Internal/, which is excluded and may change in any release.

Contributing

See UPGRADE.md. Bug reports and pull requests are welcome.

License

MIT. Copyright (c) 2026 Mohamed El Mrabet. See LICENSE.