Skip to main content

Request Matching

One-liner: to replay a recording, php-vcr has to decide an incoming request "is" a previously recorded one — that decision is what request matching configures.

On this page: The default: everything must agree · Narrowing what matters · Custom matchers

The default: everything must agree​

By default, all 8 built-in matchers are enabled — method, URL path, host, headers, body, post fields, query string, SOAP operation. An incoming request only matches a recording if every enabled matcher returns true (logical AND, see Request::matches()). That's the strictest possible interpretation of "same request", and it's the safest default: nothing replays unless it's genuinely the same call.

Narrowing what matters​

Real requests often carry incidental variation — a changing timestamp header, a random idempotency key, query parameters your test doesn't care about. Rather than fighting that noise, enable only the matchers that identify the request for your use case:

\VCR\VCR::configure()->enableRequestMatchers(['method', 'url', 'host']);

Now two requests that only differ in headers or body replay the same recording. See the full list and exact semantics of each in the Request Matchers reference.

Custom matchers​

When none of the built-ins capture what "the same request" means for your API, write a matcher:

\VCR\VCR::configure()
    ->addRequestMatcher('api_version', function (\VCR\Request $recorded, \VCR\Request $incoming) {
        return $recorded->getHeader('X-Api-Version') === $incoming->getHeader('X-Api-Version');
    })
    ->enableRequestMatchers(['method', 'url', 'api_version']);

Custom matchers combine with built-ins the same way — all enabled matchers still need to agree. See Custom request matcher for a complete recipe.

← Record Modes · Next: Use with PHPUnit →