php-vcr is an MIT-licensed PHP library that records a test suite's HTTP interactions into cassette files and replays them on later runs, giving PHPUnit-style projects fast, deterministic tests that do not touch the live network.

What it is

php-vcr is a PHP port of the Ruby VCR library, distributed through Composer as php-vcr/php-vcr and documented at php-vcr.github.io/php-vcr. It hooks into the HTTP layer of a PHP process so that outgoing requests are captured to disk on the first run and served from those recordings afterwards. The captured data is a "cassette": a file holding the recorded request and response pairs, serialized in YAML or JSON, which the test suite can commit alongside its source.

The concrete problem it solves is the live network dependency inside automated tests. A test that calls a remote REST endpoint, a SOAP service, or any URL through cURL is slow, fragile against rate limits and outages, and non-deterministic when the upstream data changes. php-vcr replaces the live HTTP call with a replay of a previously recorded exchange, so a test that fetched http://example.com once can assert on the same bytes on every later run. It also closes the failure mode where a forgotten cassette silently reaches the network: when no cassette is inserted, php-vcr throws a BadMethodCallException with the message "Invalid http request. No cassette inserted. Please make sure to insert a cassette in your unit test using VCR::insertCassette('name');" instead of making the request.

Key capabilities

• Records and replays HTTP and HTTPS interactions with minimal setup, using VCR::turnOn(), VCR::insertCassette('example'), VCR::eject(), and VCR::turnOff().
• Intercepts three library hooks by default when VCR::turnOn() is called: the stream_wrapper hook (covering functions such as file_get_contents), the curl hook, and the soap hook for SoapClient.
• Blocks every HTTP request that is not explicitly allowed, using the configured record mode.
• Supports the record modes new_episodes (default), once, none, and all, which control how a cassette behaves while it is inserted.
• Matches requests configurably on HTTP method, URI, host, path, body, and headers, and allows a custom request matcher to be written for other needs.
• Stores recorded requests and responses on disk in a serialization format of choice, with YAML and JSON built in.
• Lets the same request return different responses in different tests by inserting different cassettes.

Who uses it and how

• PHPUnit test suites that exercise code paths reaching external HTTP services, where the test case extends TestCase and drives the VCR static API in setUp or in the individual test method.
• Teams testing REST and SOAP integrations, including Guzzle-based clients, that need the same assertions to pass offline and inside CI without depending on a third-party sandbox being up.
• Projects that call curl_* functions or instantiate SoapClient, where VCR must be turned on immediately after Composer's autoloader and before any code loading those entry points, otherwise the interception is not registered.
• Bootstraps that want hooks live only for part of the run: the pattern is to call VCR::turnOn() then VCR::turnOff() in the bootstrap file, and let each test cheaply call turnOn() again when it actually wants a cassette.
• Repositories that commit cassettes to version control so recorded exchange data is reviewable and travels with the code that depends on it.

Getting started

Install with Composer as a development dependency: composer require --dev php-vcr/php-vcr. Full guides, including library hooks and request matching, live in the project documentation and in the raw Markdown under docs/.

How it compares

php-vcr is a port of the Ruby VCR library, so it brings the same cassette record-and-replay model into PHP, which does not support the monkey patching that makes the Ruby original straightforward. Where PHP HTTP test doubles are often bound to a single client, php-vcr intercepts the stream_wrapper, curl, and soap hooks together and additionally works with Guzzle-based services named in its topics. The licence is MIT, and the recordings live in files the project itself owns rather than in an external hosted service.

When to use it — and when not to

Choose php-vcr when a PHP test suite reaches real HTTP endpoints and the team wants those calls recorded once, committed as YAML or JSON cassettes, and replayed without network access. Be aware of what a self-hoster must operate: this is a library, not a service, so there is no database or mail server to run, but the cassettes themselves become artifacts that must be stored, curated, and regenerated when upstream responses change, and the hook ordering requirement means VCR has to be turned on before any code that loads curl_* or SoapClient. It is a poor fit for tests that genuinely need to validate live upstream behaviour, and the project's own disclaimer notes that interception in PHP is harder than in languages supporting monkey patching, so anyone expecting the Ruby VCR's transparency should check the library hooks documentation before committing to it.

class VCRTest extends TestCase
{
    public function testShouldInterceptStreamWrapper()
    {
        // After turning on the VCR will intercept all requests
        \VCR\VCR::turnOn();

        // Record requests and responses in cassette file 'example'
        \VCR\VCR::insertCassette('example');

        // Following request will be recorded once and replayed in future test runs
        $result = file_get_contents('http://example.com');
        $this->assertNotEmpty($result);

        // To stop recording requests, eject the cassette
        \VCR\VCR::eject();

        // Turn off VCR to stop intercepting requests
        \VCR\VCR::turnOff();
    }
}

public function testShouldThrowExceptionIfNoCasettePresent()
{
    $this->expectException(\BadMethodCallException::class);
    $this->expectExceptionMessage(
        "Invalid http request. No cassette inserted. Please make sure to insert "
        . "a cassette in your unit test using VCR::insertCassette('name');"
    );
    \VCR\VCR::turnOn();
    file_get_contents('http://example.com');
}

composer require --dev php-vcr/php-vcr

composer install
composer test