Open-Source Testing · php-vcr

php-vcr

PHP-VCR records HTTP interactions during test runs and replays them later, enabling fast, deterministic tests without real network calls. It supports multiple HTTP libraries (curl, streams, SOAP) and serialization formats (YAML, JSON), with configurable matching and record modes.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/php-vcr/php-vcr

1.2k

GitHub stars

210

Forks

PHP

Primary language

MIT

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	php-vcr/php-vcr
Owner	php-vcr
Primary language	PHP
License	MIT — OSI-approved
Stars	1.2k
Forks	210
Open issues	28
Latest release	1.10.0 (2026-07-05)
Last updated	2026-07-05
Source	https://github.com/php-vcr/php-vcr

What php-vcr is

A PHP port of Ruby's VCR that intercepts HTTP requests via stream wrappers, curl rewriting, and SOAP client patching. It stores cassettes (request/response pairs) on disk and replays them based on configurable matching rules and record modes (new_episodes, once, none, all).

Quickstart

Get the php-vcr source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/php-vcr/php-vcr.git2cd php-vcr3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Unit and integration test isolation

Record external API calls once, then replay in CI/CD pipelines to achieve consistent, fast test runs without dependency on third-party service availability or latency.

API client library testing

Test code consuming REST, SOAP, or custom HTTP-based APIs by capturing real interactions once, then validating client behavior deterministically across versions.

Legacy system integration testing

Record interactions with legacy or hard-to-reach backends, then replay to validate integration layers without requiring live external system access during development.

Implementation considerations

HTTP hooks (stream_wrapper, curl, soap) are enabled by default but can be selectively enabled if your codebase uses only one library to reduce overhead.
Record mode selection is critical: new_episodes allows learning new interactions, once prevents drift in CI, none enforces strict playback, and all forces fresh recording—choose per cassette or test suite based on workflow.
Request matching is configurable (method, URI, host, path, body, headers); default matching may be too loose or strict; test and document custom matchers if you need precise control.
Cassettes are human-readable YAML/JSON files stored on disk; plan directory structure, version control strategy, and redaction of sensitive data (API keys, tokens) before production use.
Curl rewriting and SOAP patching rely on PHP stream filters applied when classes are loaded; ensure VCR is turned on before code that makes HTTP calls to guarantee interception.

When to avoid it — and what to weigh

Real-time data or state-dependent responses required — VCR replays recorded responses; it cannot handle APIs that return time-sensitive data or responses dependent on current backend state. Manual test fixtures may be needed instead.
Dynamic, unpredictable request/response patterns — If your code makes requests with highly variable payloads or URLs that don't match recorded patterns, cassette maintenance becomes burdensome and request matchers must be carefully tuned.
PHP < 8 projects — The latest release (1.10.0) requires PHP 8; projects on PHP 7.x will need an older version or must upgrade their runtime.
Security-sensitive data in recorded cassettes — Cassettes store plaintext request/response bodies and headers on disk; credentials, tokens, or PII must be manually scrubbed or redacted before committing to version control.

License & commercial use

MIT License. Permissive OSI-approved license allowing use, modification, and distribution in commercial and proprietary projects, provided the license text and copyright notice are retained.

MIT license permits commercial use. No restrictions on integrating php-vcr into proprietary or commercial software. Verify compliance with bundled dependencies (symfony/*, beberlei/assert) which are also permissive but should be audited for your use case.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Adequate
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

Cassettes are plaintext YAML/JSON files stored on disk containing full request/response bodies and headers. Sensitive data (API keys, authentication tokens, PII) must be manually redacted or filtered before committing cassettes to version control or sharing code. No built-in encryption or secrets masking. Review stored cassettes before sharing test fixtures.

Alternatives to consider

Mockery / PHPUnit mocks

Manual mocking libraries provide fine-grained control but require writing mock expectations; less automation than VCR and no automatic cassette generation. Lighter-weight for simple unit tests but more verbose for complex HTTP workflows.

WireMock / Testcontainers

Mock HTTP server running in a container that intercepts and responds to requests; better for testing complex, state-dependent interactions. More infrastructure overhead than file-based cassettes but no disk storage management.

Jest / Nock (JavaScript ecosystems)

Language-specific HTTP mocking tools with similar cassette-based replay semantics; if your team uses Node.js or TypeScript, these are native alternatives with similar feature sets and potentially better ecosystem integration.

Software development agency

Build on php-vcr with DEV.co software developers

PHP-VCR eliminates flaky network-dependent tests. Record real API calls once, replay deterministically. Free, MIT-licensed, and ready for CI/CD.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

vcrpy go-vcr pytest-recording

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Testing API Development Custom Software Development Talk to DEV.co

php-vcr FAQ

Do I need to modify my application code to use PHP-VCR?

No modification to production code is required. You only add VCR calls to test setup (VCR::turnOn(), insertCassette()). For PHPUnit, optional annotations (@vcr) simplify boilerplate. HTTP calls are intercepted automatically via stream filters.

What happens if I make a request that doesn't match any recorded cassette?

Behavior depends on record mode: new_episodes (default) makes a real HTTP request and records it; once and none throw an exception; all ignores the cassette and re-records fresh. Choose the mode that fits your workflow.

How do I hide sensitive data in cassettes?

VCR does not provide built-in redaction. Manually edit YAML/JSON cassettes to remove API keys, tokens, or PII before committing, or write a custom serializer that filters sensitive headers/bodies. Consider cassettes as test fixtures with security implications.

Does VCR work with asynchronous or streaming HTTP requests?

Not clearly stated in documentation. Streaming and async patterns are not mentioned in supported libraries list. Review advanced documentation or test with your specific async library before relying on VCR for non-blocking requests.

Software development & web development with DEV.co

Adopting php-vcr is usually one piece of a larger software development effort. As a software development agency, DEV.co provides software development services and web development expertise — pairing senior software developers and web developers with your team to design, build, and operate open-source testing software in production.

Speed up your PHP test suite with recorded HTTP interactions

PHP-VCR eliminates flaky network-dependent tests. Record real API calls once, replay deterministically. Free, MIT-licensed, and ready for CI/CD.

Talk to DEV.co Schedule a Consultation