README

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)

Features

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, 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
        \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->setExpectedException(
            'BadMethodCallException',
            "Invalid http request. No cassette inserted. Please make sure to insert "
            . "a cassette in your unit test using VCR::insertCassette('name');"
        );
        \VCR\VCR::turnOn();
        // If there is no cassette inserted, a request throws an exception
        file_get_contents('http://example.com');
    }
}

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('http://google.com');

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

        // VCR is automatically turned on and off.
    }
}

Supported HTTP libraries

All three hooks are enabled by default when you call VCR::turnOn(). No extra configuration is required.

Hook name	Intercepted libraries	How it works
`stream_wrapper`	`fopen()`, `fread()`, `file_get_contents()`, `Symfony\Component\HttpClient\NativeHttpClient`	Replaces the `http`/`https` stream wrapper — no source rewriting
`curl`	`curl_*` functions, `Symfony\Component\HttpClient\CurlHttpClient`, Guzzle (curl backend)	Rewrites `curl_*` calls in loaded PHP source via a stream filter
`soap`	`SoapClient`	Rewrites `new SoapClient(…)` in loaded PHP source via a stream filter

To enable only specific hooks (e.g. when you know your code only uses curl):

\VCR\VCR::configure()->enableLibraryHooks(['curl']);
\VCR\VCR::turnOn();

Available hook names: stream_wrapper, curl, soap.

Record modes

The record mode controls how VCR behaves when a cassette is inserted.

Mode	Constant	Behaviour
`new_episodes`	`VCR::MODE_NEW_EPISODES`	Default. Plays back recorded interactions; performs real HTTP for any request that has no recording and records the response.
`once`	`VCR::MODE_ONCE`	Plays back recorded interactions. Allows new requests only when the cassette is new (first run). Throws on a miss after that.
`none`	`VCR::MODE_NONE`	Read-only. Plays back recorded interactions only. Throws on any request that has no recording.
`all`	`VCR::MODE_ALL`	Re-record mode. Never plays back. Always performs the real HTTP request and records the response fresh. The cassette is purged on insert so every run starts clean.

// Re-record an existing cassette from scratch
\VCR\VCR::configure()->setMode(\VCR\VCR::MODE_ALL);
\VCR\VCR::turnOn();
\VCR\VCR::insertCassette('my_cassette'); // existing recordings are purged
file_get_contents('http://example.com');  // hits network, recorded fresh
\VCR\VCR::eject();
\VCR\VCR::turnOff();

Note: A run under MODE_ALL that performs no HTTP request leaves an empty cassette — this is inherent to the fresh re-record semantics.

Installation

Simply run the following command:

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

Dependencies

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

Changelog

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

Old changelog entries

php-vcr / php-vcr

Maintainers

Package info

Statistics

Security