Soap Recorder Bundle Laravel Package

Getting Started

• Set expectations before you install anything. This is an archived, [DEPRECATED] Symfony bundle targeting Symfony 2.x/3.x and pre-PHP-8 runtimes. It is not a Laravel package: there is no service provider, no package-discovery manifest, no Laravel config. Day-to-day leverage in a Laravel codebase is therefore zero if you install it, and high if you read it and reimplement the pattern. Decide up front which of those two you're doing.
• If you are inside a legacy Symfony app (the only case where you actually run this), install with composer require --dev liip/soap-recorder-bundle, pin a tag or dev-master, and register the bundle manually in AppKernel (new Liip\SoapRecorderBundle\LiipSoapRecorderBundle()) — this predates Flex recipes. Expect to need --ignore-platform-reqs on modern Composer.
• Read these three files first, in this order:
  1. DependencyInjection/Configuration.php — the only real knobs: where fixtures land and record-vs-replay mode.
  2. Resources/config/ service definitions — this shows you how the client decorator is wired into the SOAP client, which is the part worth copying.
  3. The recorder/player class — this shows you how a request is hashed into a fixture filename and how a recording is matched on replay. This is the whole idea in a few hundred lines.
• First use case, end to end: take one existing \SoapClient call in a functional test → route it through the recorder client → run once against the live WSDL endpoint to generate a YAML fixture → flip to replay mode → re-run offline. That single record→replay loop is the entire value proposition. Validate it on one call before investing in anything else.
• If you're Laravel-first (most likely), skip the install entirely. Start by inventorying your SOAP calls and identifying the seam: does the traffic ride on Guzzle/HttpClient? If yes, Http::fake() or php-vcr buys you most of this with no framework mismatch. If it's a hand-rolled ext-soap wrapper or a vendor SDK client, you'll implement the decorator yourself — use this repo as the reference implementation.

Implementation Patterns

• Decorate, never replace. The bundle works by wrapping your SoapClient with the same WSDL and options so call sites stay untouched. Swap the construction point (a factory or DI service), not the business logic. In Laravel the analogue is binding your client interface in a service provider and swapping the binding in TestCase::setUp().
• Own the seam. Define an interface for your SOAP client (SoapClientInterface::call($method, array $args)) that your application code depends on. Production gets the real ext-soap client; tests get RecordingSoapClient (writes fixtures) or ReplaySoapClient (reads them). This is ~200–400 LOC and is cheaper to own than a patched fork of an archived bundle.
• Three modes, one flag. record (call live, save fixture), replay (serve fixture, never touch network), passthrough (call live, save nothing). Default to replay in CI; make record an explicit, deliberate, human-run action. This mirrors the bundle's configuration and is the pattern that keeps CI honest.
• Key fixtures on method + normalized arguments. The bundle hashes the call to a filename. Copy that idea but normalize first: strip or replace timestamps, nonces, message IDs, and correlation IDs, or you will get a constant cache miss and a live call on every run — the single most common way record/replay silently stops working.
• Refresh stale fixtures deliberately. Record/replay tools rot when the upstream contract moves. Keep a separate command (or a scheduled job against the sandbox) that re-records the fixture set and opens a diff for review. A green replay test against a stale fixture is worse than no test.
• Commit fixtures and review them like code. YAML fixtures are the test oracle. They belong in the repo, in a dedicated directory, reviewed in PRs. Establish the redaction policy before the first recorded run (see Gotchas).
• Set up the test harness once. In PHPUnit, a base test case that boots the container, resolves the client interface to the replay implementation, and points it at the fixtures directory. In Laravel, the equivalent is a trait used by your SOAP integration tests that rebinds the client and asserts no live traffic escaped (e.g., fail the test if the HTTP client records an unexpected request).
• Treat SOAP as XML-over-HTTP where you can. If the client underneath is Guzzle/HttpClient, HTTP-layer record/replay (php-vcr, or Http::fake() with checked-in response XML) covers the same need without touching SOAP semantics at all. Reach for SOAP-layer interception only when the client hides the transport from you.
• Contract-first fixtures as the cheaper path. For stable partner integrations, hand-authored or generated SOAP response XML checked into the repo and replayed through a test HTTP client is often more durable than recording real traffic — no secrets to redact, no drift from volatile WSDLs, diff-friendly.

Gotchas and Tips

• It is archived and explicitly deprecated. No security patching, no PHP 8.x / ext-soap compatibility work, no fixes for faults, typed SOAP objects, or MTOM/attachments. In a Laravel app this alone disqualifies adoption; treat the codebase as reference only.
• Framework mismatch is disqualifying for adoption. Every file you'd actually use is Symfony DI glue. Vendoring it to get one recorder class is strictly worse than writing the class.
• ext-soap is a hard CI dependency. Verify it's installed in every build image, including parallel test workers and the container your CI uses for the record job. Missing extension produces opaque failures.
• Secrets leak into fixtures by default. SOAP headers routinely carry credentials, bearer tokens, WS-Security UsernameToken, and PII in the body. Recorded YAML gets committed. Redact at write time (not review time) and add a pre-commit secret scan. This is the highest-severity operational risk with this pattern.
• Replay miss → silent passthrough is the scary failure. If a request doesn't match a fixture and the client falls back to live, CI either goes flaky or — worse — writes to a partner system from a test run. Make replay mode strict: miss = exception, never a network call.
• Fixture drift gives false confidence. WSDL or schema changes upstream while recordings keep passing; tests stay green, production breaks. Mitigate with a scheduled re-record against sandbox and diff review.
• Hashing is brittle. Nonces, timestamps, and message IDs in the SOAP envelope will produce a new key every run. Normalize the request before hashing, and unit-test the normalizer.
• Parallel test runners collide. Paratest workers writing the same fixture path corrupt each other. Recording must be single-writer, or namespace the fixture path per worker and merge after. Replay-only is safe in parallel; record is not.
• Large XML fixtures are not diff-friendly and grow monotonically. Past a few hundred cases, move fixtures to an artifact store or a separate repo. Don't let them bloat the main tree.
• Fault responses need explicit handling. A recorded SOAP fault (thrown exception on the live call) must replay as the same thrown exception, not as a successful response object. The bundle is thin here; in your own implementation, store the fault and re-raise on replay.
• Filesystem failures surface as opaque errors. Permissions and disk in containerized CI are a common cause of "fixture not found" or empty files. Fail loudly on write errors.
• Extension points worth stealing: the decorator wiring, the request-hash-to-filename convention, and the record/replay/passthrough mode flag. Everything else is Symfony-era boilerplate you don't want. MIT licence means you can copy those parts — own whatever you copy, with tests.