Download the PHP package spodnet/laravel-http-client-replay without Composer

The Problem

When integrating third-party APIs (such as Strava, Stripe, GitHub, or OpenAI), local development and automated testing present major pain points:

• Strict Rate Limits: Running your test suite or reloading local features can burn through daily API quotas in minutes.
• Flaky & Slow Tests: Network latency, third-party outages, or changing remote data cause intermittent test failures in CI.
• Tedious Mocking: Manually constructing complex Http::fake([...]) payloads is tedious, prone to falling out of date, and doesn't reflect real API responses.

The Solution

laravel-http-client-replay records real outbound HTTP requests made via Laravel's native HTTP Client (Http::*), sanitizes sensitive secrets (bearer tokens, API keys, passwords), and saves them into clean JSON cassettes. Subsequent requests replay deterministically using Laravel's native Http::fake() without touching the internet.

• Zero-Hack Architecture: Leverages Laravel's native Http::fake() and ResponseReceived events. No custom Guzzle client wrappers or proxy servers needed.
• 4 Operating Modes: off, record, replay, and auto.
• Automatic Secret Redaction: Masks Authorization headers, sensitive query parameters, and sensitive request/response JSON and form body fields before writing to disk.
• Deterministic Fingerprinting: Matches requests by HTTP method, normalized URL path, alphabetically sorted query parameters, and SHA-256 payload hash.
• Pluggable Storage Drivers: Save cassettes as local files, to Laravel Storage disks (e.g. S3), or to a database table.
• Domain & URL Scoping: Intercept only specific external APIs while letting internal/local traffic pass through.
• Artisan Management: Inspect and purge cassettes with built-in CLI commands.

Installation

Install the package via Composer:

Publish the configuration file:

(Optional) If you plan to use the database cassette storage driver, publish and run the migration:

Quickstart

1. Configure the Mode

Set the mode in your .env or phpunit.xml:

2. Make Normal HTTP Requests

Continue using Laravel's standard Http facade. Everything works automatically:

Operating Modes

Configure the active mode in config/http-client-replay.php or via the HTTP_CLIENT_REPLAY_MODE environment variable:

You can switch modes programmatically at runtime:

Testing Ergonomics

Using Named Cassettes

By default, cassettes are saved with a deterministic identifier derived from the request URL and payload. In tests, you can assign human-friendly cassette names:

You can also pass a closure to useCassette() to scope the cassette to that specific block:

Test Trait (InteractsWithHttpClientReplay)

Include the trait in your Pest or PHPUnit tests for convenience:

Sensitive Data Redaction

Cassettes should be safe to commit to version control. laravel-http-client-replay automatically redacts sensitive data before writing cassettes to storage.

Configure what to redact in config/http-client-replay.php:

Auto-Expiring Cassettes (TTL)

Cassettes can be configured to automatically expire after a set duration. When an expired cassette is accessed:

• In auto mode: The stale cassette is removed and the request executes live to fetch and record fresh data.
• In replay mode: A CassetteExpiredException is thrown to ensure strict offline test reproducibility.

TTL values mirror Laravel Cache and accept integer seconds, \DateTimeInterface (e.g. now()->addHours(2)), \DateInterval, or \Carbon\CarbonInterval.

1. Using remember() (Mirroring Cache::remember())

2. Request-Level Expiration via Laravel HTTP Client Options

3. Fluent Runtime Modifiers & Touching Cassettes

Domain & URL Scoping

To avoid intercepting unrelated outbound requests (like internal microservices, AWS S3, or third-party webhooks), scope which URLs to handle:

In Configuration (config/http-client-replay.php)

Scopes can be defined as simple strings or keyed with scope options like ttl:

At Runtime

Pluggable Storage Drivers

laravel-http-client-replay supports multiple storage drivers configured via HTTP_CLIENT_REPLAY_DRIVER:

1. file Driver (Default)

Stores cassettes as human-readable .json files on local disk:

2. disk Driver

Stores cassettes on any configured Laravel Filesystem disk (e.g. s3, local):

3. database Driver

Persists cassettes in a database table:

Artisan Commands

List Recorded Cassettes

View all recorded cassettes along with their size, age, HTTP status, and request signature:

Example output:

Clear Recorded Cassettes

Delete all cassettes or filter by domain:

Testing & Quality

Run full validation (Static analysis, Pint linting, 100% type coverage, and parallel Pest unit tests):

Or individual commands:

Changelog

Please see CHANGELOG.md for more information on what has changed recently.

Contributing

Please review CONTRIBUTING.md to get started.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Martin Wheatley
• All Contributors

License

Laravel HTTP Client Replay is open-source software licensed under the MIT license.