Soap Laravel Package

Technical Evaluation

Architecture fit. ricorocks/soap is a thin, Laravel-native SOAP client: it wraps PHP's ext-soap SoapClient behind a fluent, HTTP-client-style API (Soap::to($wsdl)->call(...)), a facade and service provider, a hook system (BeforeSending, ResponseReceived, ResponseReceived, SoapCall-style lifecycle points), and first-class test doubles (Soap::fake(), Soap::assertSent()). It sits cleanly in a gateway/service-layer pattern — consumers depend on an injected client, not on WSDL plumbing — and adds almost no framework coupling beyond the container and the facade. For a team already on Laravel this is a low-ceremony fit; for anything requiring WS-Security, MTOM attachments, or strict XSD code generation it is thinner than phpro/soap-client and should be evaluated against that alternative.

Integration feasibility. Install is a single Composer require plus ensuring ext-soap is compiled into every runtime image (not merely present in php.ini on a dev box). No custom transport, no Guzzle handler conflicts, no queue or cache dependencies. The only real gating constraint introduced by 4.0.0 is the framework matrix.

Technical risk. 4.0.0 is a breaking release by constraint, not by API: it adds Laravel 13 support and removes Laravel 11 support, with no listed feature or behavioural changes. Two consequences for planning:

• The package's major versions track the Laravel support matrix, not its own feature surface. Version numbers therefore carry framework-compatibility meaning and must be pinned explicitly (^3.0 vs ^4.0) rather than floated.
• Any application still on Laravel 11 is silently capped at 3.x. Because the drop aligns with Laravel 11's upstream end of security fixes, 3.x should be treated as a shrinking branch, not a long-term home.

Secondary risks: single-agency maintainership (mitigated somewhat by a new contribution from a well-known Laravel community maintainer — a positive maintainership signal, but one PR is not a bus-factor fix); and a narrow abstraction that leaves XSD/namespace/WSDL complexity with the integrating developer.

Key questions.

1. Does 4.0.0 change the minimum PHP version or the ext-soap requirement, or is the diff purely composer.json constraints?
2. Is Laravel 12 still supported alongside 13, or is this a one-in-one-out matrix? (Determines whether our L12 upgrade can proceed independently.)
3. Are 3.x releases still receiving security fixes, and for how long?
4. Any internal refactors to the hook pipeline or fake/assertion API not captured in the release notes?
5. Do we have any dependency that itself pins Laravel 11 and would block the whole upgrade chain?

Integration Approach

Stack fit. Laravel 12/13 application, PHP 8.2+, ext-soap enabled in the base image, package pinned at ^4.0. The package rides on Laravel's HTTP client conventions, so timeout, retry, and middleware idioms carry over — no new operational concept for the team to learn at the transport layer.

Migration path. From 3.0.0 → 4.0.0 the code migration should be a no-op; the platform migration is the work. Sequence it as a coupled framework upgrade rather than an isolated dependency bump:

• On Laravel 12: bump ^4.0, run the suite, ship. Low risk.
• On Laravel 11: blocked. Upgrade Laravel to 12 first (using Laravel's own upgrade guide / Shift), validate against Soap 3.x, then bump to 4.0.0 on a short-lived branch. Do not attempt both in one PR.

Compatibility. Before committing, run composer why-not ricorocks/soap ^4.0 to see exactly which packages (or the root laravel/framework constraint) block resolution — this is the single highest-value pre-flight check and surfaces transitive Laravel 11 pins immediately. Also confirm the WSDL/sandbox endpoints we depend on are reachable from CI, since the test suite will exercise fakes rather than the real service.

Sequencing.

1. Inventory every SOAP endpoint, WSDL, and Soap::fake() assertion in the codebase and test suite.
2. Upgrade framework to Laravel 12; keep Soap at 3.x; full regression run.
3. Branch: bump Soap to ^4.0, resolve constraints, run unit + contract tests.
4. Canary one non-critical SOAP integration in staging against a real sandbox WSDL (fakes will not catch a transport-layer regression).
5. Promote; keep the 3.x tag pinned in composer.lock as a documented rollback point.

Operational Impact

Maintenance. Small dependency surface, but the upgrade cadence is now dictated by Laravel majors — budget one planned bump per framework release cycle. Watch 3.x actively while any service remains on it; once Laravel 11 security support ends, 3.x becomes an unpatched branch and an audit finding.

Support. Open-source, agency-maintained, GitHub issues as the only escalation path. Acceptable for internal integrations; if a SOAP endpoint is revenue-critical, plan to vendor/fork the package or wrap it behind our own adapter interface so it can be swapped, and note the fork obligation in the runbook.

Scaling. The client is synchronous and blocking; throughput is bounded by the upstream SOAP service and its WSDL, not by this package. Push long-running or batch SOAP calls onto queues, set explicit per-call timeouts, and use Laravel's retry semantics deliberately — blind retries against a non-idempotent SOAP operation is the classic incident here. Avoid resolving the client eagerly at container boot, which turns a WSDL fetch into a startup dependency.

Failure modes to instrument.

• ext-soap absent from a rebuilt container image → fatal at first call, not at deploy. Add an image-level extension assertion in CI.
• WSDL unreachable or changed upstream → parse/SoapFault at call time; cache the WSDL locally where the service is stable.
• Fake/real drift: tests pass against hand-written fakes while the live WSDL has moved. Mitigate with a scheduled contract test against the sandbox.
• Composer silently resolving 3.x because of a transitive Laravel 11 constraint — the upgrade "succeeds" without changing behaviour. Guard with composer show ricorocks/soap in the deploy pipeline.
• SOAP faults surfacing as unhandled exceptions and taking down a request path; wrap calls and map fault codes to domain errors.

Ramp-up. The API surface is small and idiomatic — a Laravel developer is productive in an afternoon. The real onboarding cost is SOAP domain knowledge (namespaces, XSD strictness, WS-Security, fault codes), which this package deliberately does not abstract. Offset it with a short internal runbook, one worked example per endpoint family, and a fake-based test harness as the default way to develop against these integrations without touching a live service.