Weave Code
Vcr Plugin Laravel Package
php-http/vcr-plugin
A PHP-HTTP plugin that records real HTTP interactions and replays them in tests, similar to Ruby's VCR. Drop it into any HTTPlug-compatible client to capture responses once, then run fast, deterministic, offline test suites without hitting external APIs.
php-http/vcr-plugin is a PHP HTTP client plugin for recording and replaying HTTP interactions in tests. It integrates with HTTPlug/PSR-18 clients, letting you capture real responses once and replay them deterministically—eliminating flaky network calls and speeding up test suites.
- Records requests and responses to fixtures for later replay
- Matches on method, URL, headers, and body
- Works with PHP-HTTP and PSR-18 clients
- Enables fast, deterministic, offline-friendly tests
- Configurable storage and matching for flexible workflows
Frequently asked questions about Vcr Plugin
- What is php-http/vcr-plugin and how does it work?
- It is a test-only plugin for PHP-HTTP (HTTPlug) clients that records real request and response pairs into cassette files on the first run, then replays them on later runs. Your tests still exercise the real client stack, but no network call is made after recording, so suites stay fast, deterministic, and offline. It follows the same VCR pattern popularized by Ruby's VCR and Java's Betamax. Because it plugs into the client middleware layer, application code needs no special test conditionals.
- How do I install php-http/vcr-plugin in a Laravel project?
- Install it with composer require --dev php-http/vcr-plugin so it never reaches production dependencies. Then wrap the HTTP client your tests use with the plugin, usually in tests/TestCase.php or a Pest.php bootstrap, and point it at a cassette directory such as tests/Fixtures/Cassettes. Commit the composer.lock change and the cassette directory convention so every developer and CI runner behaves identically. No application code changes are required for the initial trial.
- Does php-http/vcr-plugin work with Laravel's HTTP client and PSR-18?
- It targets the PHP-HTTP/HTTPlug plugin ecosystem, so it works natively with plugin-capable clients, while plain PSR-18 clients without a plugin layer need an adapter or a wrapper client. Laravel's Http facade does not expose that plugin layer, so for facade-based tests Http::fake() is usually the simpler choice. If your service code type-hints Psr\Http\Client\ClientInterface or an HTTPlug client, bind a wrapped instance in the container for tests and let the plugin intercept it.
- Which PHP and Laravel versions does php-http/vcr-plugin support?
- It is a standalone PHP package requiring a modern PHP 8.x runtime plus PSR-7 and PSR-17 message implementations, and it does not depend on Laravel itself. That means Laravel version support follows from your application's PHP constraint rather than a Laravel-specific requirement. Check the plugin's composer.json constraints for PHP and PSR-7/PSR-17 before rollout, and pin an exact version in composer.json.
- How do I set up cassette files for Laravel tests?
- After installing as a dev dependency, wrap the client under test with the plugin and give it a cassette directory, typically tests/Fixtures/Cassettes. Configure it once in your base TestCase or Pest bootstrap so each test gets a fresh plugin instance scoped to that test. Name cassettes after the test class and method so recordings stay isolated, reviewable, and easy to delete when they go stale.
- What record modes does php-http/vcr-plugin support and how do I lock CI to replay-only?
- Typical modes are record-once, where a missing cassette is recorded and existing ones are replayed, replay-only, which fails if no cassette exists, and re-record or overwrite when you deliberately need fresh data. Commit cassettes to the repository and hard-lock CI to replay-only so a missing recording fails loudly instead of silently hitting the network. Keep a documented refresh procedure: delete the cassette, re-record against a known-good environment, and review the diff like any other fixture.
- How does request matching work for replayed responses?
- The plugin matches each incoming request to a recorded interaction, typically on method and URI with optional body and header matching depending on configuration. Strict matching catches accidental request changes but makes cassettes brittle, while loose matching can hide real regressions. Tune strictness per suite rather than globally, and review cassette diffs in pull requests so matching changes are visible.
- How do I scrub secrets from cassettes before committing them?
- Treat cassettes as committed artifacts and scrub them before they ever reach git. Strip or replace Authorization, Cookie, API-key, and session headers, and redact tokens or personal data inside JSON bodies using the plugin's replacement configuration or a post-processing step. Add a pre-commit hook or CI grep for known secret patterns so a leaked credential cannot slip through. If a real secret was recorded before scrubbing rules existed, rotate it.
- Is php-http/vcr-plugin safe to use with parallel test runs in Pest or PHPUnit?
- Parallel execution is workable as long as each test or worker writes to a distinct cassette file, because shared cassettes will race and produce corrupt or flaky recordings. Use per-test naming conventions or a worker-id suffix in the cassette path, and avoid recording mode during parallel CI runs. Verify the behaviour under your parallel runner during the initial spike before converting larger suites.
- Is php-http/vcr-plugin actively maintained and what are the alternatives?
- The package is MIT-licensed and small, but its ecosystem footprint is limited, so plan for a single maintainer or a slow release cadence. Pin the version, treat upgrades as reviewed changes, and keep cassettes as regenerable artifacts so forking or replacing the package stays cheap. Alternatives include client-specific mock handlers and Laravel's Http::fake() for facade-based code, so confirm the plugin fits your client abstraction before committing.
Weaver
How can I help you explore Laravel packages today?