This is a port of the VCR Ruby library to PHP.

Record your test suite's HTTP interactions and replay them during future test runs for fast, deterministic, accurate tests. Full documentation lives at php-vcr.github.io/php-vcr — or browse the raw Markdown in docs/.

Disclaimer: Doing this in PHP is not as easy as in programming languages which support monkey patching (I'm looking at you, Ruby)

• Automatically records and replays your HTTP(s) interactions with minimal setup/configuration code.
• Supports common http functions and extensions — see Supported HTTP libraries below
• The same request can receive different responses in different tests -- just use different cassettes.
• Disables all HTTP requests that you don't explicitly allow by setting the record mode
• Request matching is configurable based on HTTP method, URI, host, path, body and headers, or you can easily implement a custom request matcher to handle any need.
• The recorded requests and responses are stored on disk in a serialization format of your choice (currently YAML and JSON are built in)

⚠️ Turn VCR on as soon as possible — right after Composer's autoloader, before any code that calls curl_* or uses SoapClient gets loaded. That call is what registers the interception; turn it back off right afterwards (VCR::turnOn(); VCR::turnOff(); in your bootstrap file) if you don't want hooks live for the whole run — each test can cheaply call turnOn() again only when it actually wants a cassette. Details: How VCR works.

Using static method calls:

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();
    }
}

Forgetting to insert a cassette throws immediately, instead of silently hitting the network:

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');
}

All three hooks (stream_wrapper, curl, soap) are enabled by default when you call VCR::turnOn(). Full interception details and how to enable only specific hooks: Library Hooks.

The record mode controls how VCR behaves when a cassette is inserted: new_episodes (default), once, none, all. Full behaviour per mode: Record Modes.

By default php-vcr records identical requests separately and replays them in the same order they were made. Details and how to change this: Cassettes → identical requests.

Simply run the following command:

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

PHP-VCR depends on PHP 8 and the curl extension, plus a few Composer packages Composer installs for you. Full requirements and the tested HTTP library matrix: Requirements.

Full documentation — searchable, versioned, dark mode — lives at php-vcr.github.io/php-vcr. Or browse the raw Markdown directly in docs/:

• Getting Started · How VCR works
• Cassettes · Record Modes · Request Matching
• How-to: PHPUnit · Codeception · Filter sensitive data · SOAP · Storage factory / custom storage
• Reference: Configuration · Events · Storage backends

Bug reports, feature requests and pull requests are welcome — see CONTRIBUTING.md for how this repository is set up, the pre-push checks, and why documentation is part of every change.

In order to run all tests you need to get development dependencies using composer:

composer install
composer test

The changelog has moved to the PHP-VCR releases page.

Old changelog entries

Copyright (c) 2013-2026 Adrian Philipp. Released under the terms of the MIT license. See LICENSE for details. Contributors