Soap Client Laravel Package

Technical Evaluation

Architecture fit. phpro/soap-client is framework-agnostic and built on PSR abstractions (PSR-18 HTTP client, PSR-17 factories, PSR-3 logger, PSR-16 cache, Symfony EventDispatcher), which maps cleanly onto Laravel's service container, config repository, logging, and queue primitives. Its defining characteristic is code generation: from a WSDL/XSD it emits a typed client class plus request/response value objects, so SOAP calls become typed method calls instead of hand-built SoapClient::__soapCall arrays. That is the strongest architectural argument for adopting it — it makes a legacy protocol statically analyzable (PHPStan/Psalm/IDE completion) and testable, and it isolates transport concerns into a middleware pipeline (logging, last-request capture, validation, event dispatch) rather than scattering them across call sites.

Integration feasibility. For a single, well-formed WSDL this is roughly a one-to-two-day spike for a mid-level PHP developer: install, configure a ClientSpecification, run the generator, wire a container binding. Effort scales with the contract, not the library: WS-Security (UsernameToken, X.509 sign/encrypt), WS-Addressing, MTOM/attachments, SOAP 1.2-vs-1.1 quirks, and custom HTTP headers each require bespoke middleware or manual envelope manipulation. Authentication is the most common hidden cost — HTTP Basic is trivial; WS-Security and certificate rotation are not.

Technical risk.

• Spec coverage gap. WS-* extensions are only partially supported. Where a provider demands WS-Security or MTOM, you either write custom middleware or fall back to the ext-soap-backed engine, which forfeits much of the PSR-18/type-safety benefit. This is the decision that should be made before committing.
• Build-time coupling to the vendor. Generation requires the WSDL/XSD to be reachable and valid during build or CI. Third-party WSDLs change without notice; a provider-side schema edit becomes a build break or, worse, a silent runtime mismatch.
• Generated-code volume. Large enterprise WSDLs can emit hundreds of classes. These must be owned, reviewed (or explicitly excluded from review), regenerated deterministically, and diffed in CI.
• Maturity/community signal. ~890 stars and a single-vendor maintenance model is thin compared to Guzzle/Laravel, though the recent release date indicates active upkeep. Expect to be your own first-line support for edge-case SOAP behaviour.
• No Laravel-native package. There is no first-party service provider, config schema, or facade. The glue layer is ours to build, document, and maintain — that is real, recurring cost, not a one-off.

Key questions.

1. Which WSDLs, and are they stable, versioned, and available offline (checked into the repo)?
2. What authentication and WS-* extensions does the provider mandate? Does that force the ext-soap engine?
3. Is ext-soap permitted in our runtime image, or must we stay pure-PHP/PSR-18?
4. Do we need attachments/MTOM, or are payloads small?
5. Who owns generated artifacts — committed to the repo, or built at deploy time?
6. What is the provider's change-notification SLA for WSDL revisions?
7. Do we need async/bulk submission (queue + retry semantics), and who owns idempotency?
8. Is there an existing ext-soap or NuSOAP implementation to migrate, and do we have golden-request fixtures to prove parity?

Integration Approach

Stack fit. Composer-installable, PHP 8.x, no framework assumptions. Pairs with a PSR-18 implementation (Guzzle 7 satisfies PSR-18 directly) for transport, symfony/event-dispatcher for lifecycle hooks, and Laravel's container for per-service client bindings. It sits naturally behind a repository/gateway interface, so domain code depends on our interface, not on generated classes.

Migration path. Treat it as a strangler-fig replacement:

1. Inventory every SOAP endpoint currently called (ext-soap, NuSOAP, cURL+string templates).
2. Pick the highest-value, lowest-complexity WSDL for the pilot.
3. Generate the client, wrap it in a domain-level interface, and add contract tests recorded from the existing client's real requests/responses.
4. Route one code path through the new client behind a feature flag; compare payloads and responses in parallel.
5. Expand service-by-service, retiring the old call sites and eventually the legacy extension dependency.

Compatibility. Verify the PHP constraint against the runtime image, Laravel version (service-provider and config-publishing APIs are stable across 10/11/12), and the Guzzle/PSR-18 adapter version. Pin the generator and library versions in composer.lock; regeneration must be reproducible. Keep generated code in a dedicated namespace/directory so it is excluded from coverage and static-analysis baselines.

Sequencing.

1. Spike (1 week): one WSDL end-to-end, including the real auth mechanism — this is where go/no-go lives.
2. Generation in CI: a deterministic generate script, committed output or build artifact, with a drift check that fails the build if regeneration produces a diff.
3. Wiring: per-service config file (endpoint, credentials, timeouts), container bindings, and a thin gateway interface.
4. Cross-cutting middleware: structured request/response logging with redaction, correlation IDs, retry/backoff, timeout enforcement, SOAP Fault → domain exception mapping.
5. Testing: fixture-based contract tests against recorded XML; a nightly smoke test against the provider's sandbox to catch silent schema drift.
6. Rollout: per-domain migration behind flags, then decommission legacy clients.

Operational Impact

Maintenance. Recurring cost concentrates in three places: (a) regenerating and reviewing clients when a vendor WSDL changes, (b) the bespoke glue layer (providers, config, middleware, exception mapping) that no upstream package will maintain for us, and (c) dependency churn — laminas/laminas-code, Symfony EventDispatcher, and PSR adapter updates flow through composer.lock and need periodic, low-drama upgrades. Budget a standing fraction of one engineer for a multi-endpoint integration; a single stable endpoint is near-zero after the pilot.

Support. Upstream support is best-effort by a small maintainer group. Realistic escalation model: internal owner for the glue layer and generated code; upstream GitHub issues only for genuine library bugs; the SOAP provider is the escalation path for schema and fault semantics. Make WSDL change notification a contractual line item with the vendor — the absence of that clause is the single most common cause of unplanned outage in SOAP integrations.

Scaling. Throughput is bounded by the remote service, not by this library; keep-alive and connection reuse come from the underlying PSR-18 client. Real constraints to plan for: WSDL/XSD parsing is CPU- and memory-heavy — cache parsed metadata and never fetch the WSDL at request time in production; large responses can breach memory_limit, so stream or paginate where the provider allows; bulk operations should run on queues with explicit concurrency limits and idempotency keys, because SOAP endpoints rarely tolerate retry storms.

Failure modes to instrument and alert on.

• WSDL unreachable or altered at build/deploy time (drift check + pinned local copy).
• Provider schema change after deployment producing nulls/defaults instead of hard errors — mitigate with contract tests and response validation middleware.
• SOAP Faults collapsing into generic 500s — map fault codes to typed exceptions, alert on unhandled codes.
• Auth/token and certificate expiry, and TLS trust-store rotation.
• Endpoint timeouts and slow-response tail latency — enforce client-side timeouts; capture last-request/response for postmortems.
• XXE exposure if entity loading is left enabled — explicitly disable external entities and verify in a security test.
• Attachment/MTOM memory blowups on large binary payloads.

Ramp-up. Expect one to two weeks for a competent Laravel developer unfamiliar with SOAP to become productive, and longer to become confident with WS-Security. The friction is conceptual, not syntactic: developers must learn to read WSDL/XSD, understand envelope structure and faults, and accept that generated classes are build artifacts rather than hand-edited code. Mitigate with a runbook covering "how to regenerate," "how to add an endpoint," "how to read a SOAP fault," a recorded-request testing pattern, and a code-owners entry for the generated namespace so review expectations are explicit.