Record your test suite's HTTP interactions and replay them during future test runs for fast, deterministic, accurate tests.

Installs: 2 226 196

Dependents: 139

Suggesters: 0

Security: 0

Stars: 1 136

Watchers: 29

Forks: 201

Open Issues: 82



Continuous Integration Code Coverage Scrutinizer Quality Score

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. A bit of documentation can be found on the php-vcr website.

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
    • everything using streamWrapper: fopen(), fread(), file_get_contents(), ... without any modification (except $http_response_header see #96)
    • SoapClient by adding \VCR\VCR::turnOn(); in your tests/bootstrap.php
    • curl(), by adding \VCR\VCR::turnOn(); in your tests/bootstrap.php
  • 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, and you can easily implement your own custom serializer)
  • Supports PHPUnit annotations.

Usage example

Using static method calls:

class VCRTest extends TestCase
    public function testShouldInterceptStreamWrapper()
        // After turning on the VCR will intercept all requests

        // Record requests and responses in cassette file 'example'

        // Following request will be recorded once and replayed in future test runs
        $result = file_get_contents('');

        // To stop recording requests, eject the cassette

        // Turn off VCR to stop intercepting requests

    public function testShouldThrowExceptionIfNoCasettePresent()
            "Invalid http request. No cassette inserted. Please make sure to insert "
            . "a cassette in your unit test using VCR::insertCassette('name');"
        // If there is no cassette inserted, a request throws an exception

You can use annotations in PHPUnit by using phpunit-testlistener-vcr:

class VCRTest extends TestCase
     * @vcr unittest_annotation_test
    public function testInterceptsWithAnnotations()
        // Requests are intercepted and stored into  tests/fixtures/unittest_annotation_test.
        $result = file_get_contents('');

        $this->assertEquals('This is a annotation test dummy.', $result, 'Call was not intercepted (using annotations).');

        // VCR is automatically turned on and off.


Simply run the following command:

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


PHP-VCR depends on:

Composer installs all dependencies except extensions like curl.

Run tests

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-2023 Adrian Philipp. Released under the terms of the MIT license. See LICENSE for details. Contributors