Vcr Bundle Laravel Package

Product Decisions This Supports

• Test-suite reliability as a delivery KPI. Record/replay of HTTP interactions removes the single largest source of flaky CI in integration-heavy products: live calls to third-party APIs. If your team tracks "builds failed for reasons unrelated to code" or mean-time-to-green, this is a direct lever.
• Build vs. buy for HTTP mocking. The core capability lives in php-vcr (the recorder/replayer); this bundle is thin glue for Symfony's DI container and web profiler. The decision isn't "build VCR from scratch" — it's "adopt an established library plus a maintenance-light integration" versus writing Guzzle/Symfony HttpClient middleware yourself (a few days of engineering, then owned forever). Weigh ongoing maintenance against a ~13-star, 0-dependent dependency. The 3.0.0 release is a good signal that the glue is at least actively maintained against current Symfony LTS (6.4) and current PHP (8.1–8.5), which de-risks the "will it rot" question somewhat.
• Third-party API cost and quota management. Cassettes let CI exercise payment, shipping, email, SMS, geocoding, and LLM-provider integrations without burning sandbox quota, hitting rate limits, or requiring vendor credentials in every pipeline. This shows up as a real line item as integration count grows.
• Roadmap decisions around vendor migrations. When evaluating an API version upgrade or a vendor swap, recorded fixtures double as a behavioral baseline: replay the old cassette against the new client and diff. That makes "can we do this migration this quarter?" an evidence-based call rather than a spike.
• Developer onboarding and local development. Committed cassettes give new engineers a deterministic, offline-capable test environment on day one — a measurable reduction in "works on my machine" ramp-up time.
• Observability decisions for the developer experience. The profiler integration surfaces recorded/replayed requests inside Symfony's web profiler, which supports investment in in-request debugging tooling versus relying solely on log archaeology. Note this benefit is Symfony-only; it does not transfer to Laravel.
• Upgrade-window planning. The 3.0 line is a support-matrix release: PHP ^8.1, Symfony ^5.4|^6.4, PHPUnit ^9.6|^10.5, php-vcr ^1.6. Teams on PHP 7 or Symfony 4 must stay on the 2.x line, which is now effectively frozen. Treat the platform floor this establishes as a scheduling input when you plan your next PHP/Symfony/PHPUnit upgrades.
• Use cases well served: contract-drift detection against vendor APIs, regression coverage across API client refactors, deterministic CI for services behind VPN or IP allowlists, and reproducing production incidents from captured request logs.

When to Consider This Package

Adopt when:

• The application is a Symfony application on Symfony 5.4 or 6.4 and PHP 8.1+. The bundle's value is almost entirely in bundle wiring and profiler panels — both Symfony concepts. Note: despite early anticipation, Symfony 7.x is not in this release's support matrix; verify a 7-compatible release exists before committing a Symfony 7 upgrade timeline to it.
• You already have, or plan to have, a meaningful number of outbound HTTP integrations (roughly 3+) and integration tests that currently touch the network.
• You want record/replay with credential scrubbing and per-environment cassette configuration without hand-rolling middleware.
• You are on PHPUnit 9.6 or 10.5 — 3.0.0 adds PHPUnit 10 support via the updated VCRTestCaseTrait, which matters if you're modernising your test tooling in parallel.
• Your team is comfortable with a small, single-maintainer dependency for non-production code, or willing to vendor/fork the glue if it goes stale. The recent 3.0.0 cut is mild evidence of maintenance, but not proof of sustained cadence — keep a fork/exit plan.
• You need profiler-level visibility into what was recorded — useful for debugging cassettes that don't match on replay.

Look elsewhere when:

• You are on Laravel. Laravel does not use Symfony bundles. Laravel's Http::fake(), Http::preventStrayRequests(), and Http::record()/Http::replay() cover most of this ground natively and are already in the framework you support. This is the decisive criterion for a Laravel shop: the bundle is not installable-useful, even though the underlying php-vcr library can still be used directly as a bare Composer dependency. The 3.0.0 release does not change this calculus at all.
• You are on PHP 7.x or Symfony 4. You are pinned to 2.x, which this release leaves behind; the support-matrix divergence will become an increasing drag over time.
• You need only a handful of simple stubs. MockHttpClient (Symfony) or Guzzle's MockHandler is lower-ceremony than cassette management.
• You need formal contract testing against an OpenAPI/AsyncAPI spec or a provider's contract — Pact, Schemathesis, or spec-driven validation is the right tool; cassettes capture whatever happened to be true on recording day.
• Dependency-risk policy is strict. 13 stars, 0 known dependents, and a single maintainer are legitimate red flags for a governed dependency policy. A "no bus-factor-1 dependencies in the critical path" rule is reasonable here; mitigate by scoping adoption to require-dev.

How to Pitch It (Stakeholders)

To executives — one paragraph: We can cut CI flakiness and third-party API spend in our test pipeline by recording real HTTP interactions once and replaying them deterministically on every build. The integration itself is small and low-cost — it wires an established open-source recorder into our framework's dependency injection and debugging tools — so the investment is measured in days, not a quarter, and the payoff is a faster, cheaper, more trustworthy build that doesn't break when a vendor has an outage or throttles us. The 3.0.0 release has modernised the support matrix (PHP 8.1–8.5, Symfony 5.4/6.4, PHPUnit 10), which reduces the "abandonware in our test stack" risk, though Symfony 7 is still not officially supported. The main caveat is that the integration layer remains a small, thinly-adopted open-source project, so we should treat it as require-dev only, keep an exit path, and confirm it applies to our stack before committing engineering time.

To engineering — the substance:

• It's php-vcr with Symfony wiring: a bundle class, DI extension, configuration tree for cassette paths and matching rules, and a web profiler panel showing recorded requests in context. Small surface area; read it in an afternoon.
• 3.0.0 is a dependency-constraint major, not a behavioural one. No runtime changes; bundle API, config keys, and service names are unchanged. Upgrading from 2.x is composer require php-vcr/vcr-bundle:^3.0 with no code edits. The catch is the platform floor: PHP 8.1+, Symfony 5.4/6.4, php-vcr 1.6+, PHPUnit 9.6/10.5. If we're stuck on PHP 7 or Symfony 4, we're on 2.x.
• Symfonfy 7 is not in the 3.0 support matrix — check the release history before we hard-commit to a Symfony 7 upgrade that includes this bundle.
• Cassettes are YAML on disk and belong in version control. Establish fixtures hygiene up front: scrub auth headers and tokens, set deterministic matching (method + URL, body matchers only where needed), and record against a stable sandbox.
• This is Symfony-only. For Laravel, the equivalent outcome is Http::fake() with Http::preventStrayRequests() in the base TestCase, plus Http::record()/Http::replay() if we want cassette semantics — no third-party bundle required. Nothing in 3.0.0 changes this.
• Health check before adoption: pin the version, verify the release cadence covers our Symfony/PHP upgrade window (and confirm a Symfony 7-compatible release path), and be prepared to vendor the bundle (it's small enough to own) if maintenance lapses. Do not let it become a load-bearing dependency in production code paths — require-dev only.
• Adjacent tooling to evaluate in the same decision: whether recorded fixtures can also serve as the behavioural baseline for upcoming vendor API version migrations, which is where most of the long-term value sits.