Soapy Laravel Package

Technical Evaluation

Architecture fit

• souretcoad/soapy is a thin, opinionated Laravel wrapper around PHP's native ext-soap client. It fits cleanly into a Laravel service that must consume one or more third-party SOAP/WSDL APIs (payments, logistics, healthcare clearinghouses, government gateways) and where the team wants configuration-driven clients, a consistent option surface, and test-friendly fakes rather than ad-hoc new SoapClient(...) calls scattered across the codebase.
• It is an integration adapter, not an ESB, not a resilience layer. It does not provide retries, circuit breaking, queuing, or async transport. Those remain application responsibilities (Laravel HTTP/queue layer or an internal client wrapper).
• v3.1.0 is a compatibility release: PHP 8.4 and Laravel 12 support. No new public API surface is advertised. Architecturally this is a "keep the dependency current" signal rather than a capability change.

Integration feasibility

• Low friction: composer require souretcoad/soapy, publish config, declare named clients with WSDL, endpoint, and options, then resolve through the provided facade/manager. Fits existing Laravel service-provider and config-cache conventions.
• Hard prerequisite: the ext-soap PHP extension must be present in every runtime image (local, CI, staging, prod, queue workers, scheduler containers). This is the most common first-day blocker and should be verified before commitment.
• v3.1.0 explicitly widens the supported matrix to PHP 8.4 and Laravel 12, which unblocks teams on the current Laravel LTS/current release cadence and removes a former "cannot upgrade framework" constraint.

Technical risk

• Vendor/maintainer concentration: small open-source project with a narrow contributor base and infrequent releases. Treat as a supply-chain dependency requiring version pinning and an internal fallback plan.
• Abstraction leakage: because it wraps ext-soap, behavior and limitations of the native extension (WSDL parsing quirks, SOAP_* constants, encoding, SSL context options) surface directly. Debugging often means dropping to raw SoapClient semantics.
• Minor-version assumption: v3.0.0 → v3.1.0 is a semver-minor bump; the release notes show only additive platform support, so no breaking change is expected. That is an assumption to validate with the package's own test suite in our pipeline, not a guarantee.
• Platform edge cases: PHP 8.4 introduces deprecations and stricter typed behavior in surrounding code; Laravel 12 changes service-container and bootstrap details. "Support" claimed in a PR is not the same as "verified in our application."
• Legacy protocol risk: SOAP counterparties are frequently the least agile part of the estate; WSDL/version drift on the provider side is a larger risk than the package itself.

Key questions

1. Which concrete upstream SOAP services will use this, and is their WSDL versioned and contract-tested by the provider?
2. Does the package's fake/mocking mechanism satisfy our test strategy (contract tests in CI without live endpoints)?
3. Do we need per-tenant credentials, custom headers, WS-Security, or MTOM/attachments — and are those expressible through this wrapper's configuration, or do we need to extend it?
4. What are our timeout, retry, and idempotency requirements, and where do they live if the package does not provide them?
5. Is ext-soap already present in all environments, or is this a platform-team change with lead time?
6. Who owns upgrades when Laravel/PHP majors land — is this dependency on the platform team's upgrade checklist?

Integration Approach

Stack fit

• Target: Laravel 11/12 on PHP 8.2–8.4. v3.1.0 is the minimum version that keeps us aligned with Laravel 12 and PHP 8.4, so it should be the floor in composer.json (^3.1), not a floating constraint.
• Fits naturally alongside existing Laravel idioms: config-driven clients, service-container resolution, and test doubles. It composes with our standard observability (Laravel logging/events) rather than replacing it.
• Poor fit if the requirement set is event-driven, high-fan-out, or latency-critical; in that case SOAP calls belong behind a queue or an internal anti-corruption service.

Migration path

1. Inventory: catalogue every direct new SoapClient(...), WSDL URL, and hand-rolled XML call currently in the codebase, with owning team and call volume.
2. Pilot: migrate one low-risk, low-volume client to a config-declared definition resolved via the package. Keep the domain-facing interface identical so callers are untouched.
3. Wrap: introduce a thin internal SoapGateway (or per-provider client class) that owns retries, timeouts, logging, and exception translation, and delegates transport to Soapy. This bounds future churn if the package is ever replaced — the exit cost becomes one file, not a codebase-wide refactor.
4. Roll forward: migrate remaining clients service by service, each behind its own feature flag where callers can be switched back.
5. Decommission: remove direct SoapClient usage and any duplicate WSDL/credential handling.

Compatibility

• Upgrade path from v3.0.0 is expected to be a lockfile change plus a full test run — no code changes anticipated from these notes.
• Framework compatibility is the headline: teams previously blocked on Laravel 12 or PHP 8.4 can now take those upgrades without forking or pinning the SOAP layer.
• Verify the published composer.json constraints actually admit our PHP/Laravel combination before planning the framework upgrade; the release notes describe intent, the manifest describes reality.

Sequencing (suggested)

1. Platform: confirm ext-soap in all images and CI; add to base-image definition and document.
2. Spike (1–2 days): one client end-to-end in a non-production environment, including a failure-path test (SOAP fault, timeout, unreachable WSDL).
3. Decision gate: confirm the wrapper meets credential/header/mock requirements; if not, decide between extending it and building the internal gateway directly on ext-soap.
4. Framework upgrade (Laravel 12 / PHP 8.4) with Soapy ^3.1 pinned, run in staging against live-like provider sandboxes.
5. Production rollout per client, with rollback via feature flag.
6. Add to dependency register with an assigned owner and a review trigger on each Laravel/PHP major.

Operational Impact

Maintenance

• Low ongoing code maintenance (small surface area, config-driven), but non-zero governance maintenance: pin exact versions, review changelogs on each release, and re-run the integration suite on every Laravel/PHP minor.
• Budget roughly a half-day per quarter for dependency review, plus a defined contingency (fallback to a ~150-line internal ext-soap wrapper) in case the project stalls. Document that contingency now, while the wrapper boundary is fresh.
• Renovate/Dependabot should be configured to open PRs but not auto-merge majors here.

Support

• Community-supported only; no SLA, no vendor escalation path. Internal ownership must be explicit — name a team and an individual as the package steward.
• Support burden concentrates on provider-side issues (WSDL changes, certificate rotation, IP allow-listing) rather than on the package. Runbooks should target the upstream service, not the library.

Scaling

• Synchronous and blocking by nature: each call holds a PHP-FPM worker or queue worker for the duration of the round trip. Capacity planning must model upstream latency, not our CPU.
• Prefer queue workers for bulk/batch SOAP operations; keep web requests to a single call with a hard timeout.
• Enable WSDL caching and, where the runtime permits, opcache/preloading so WSDL parsing is not repeated per request. Watch memory for large XML payloads — ext-soap builds full DOM trees in memory.
• No connection pooling to speak of; throughput is bounded by the upstream provider's limits, which are usually the real ceiling.

Failure modes

• WSDL unreachable at boot/resolve time → hard failure at container or request start. Mitigate with local WSDL copies or warm-up health checks where the provider allows it.
• SOAP Fault → must be translated into domain exceptions at the gateway boundary; otherwise fault strings leak into user-facing errors.
• Timeouts / partial responses → the package does not retry. Non-idempotent operations must never be blind-retried; classify operations explicitly.
• TLS/certificate and IP allow-list drift → common breakage source; alert on certificate expiry and provider connectivity separately from application errors.
• Encoding/charset and namespace mismatches → intermittent, hard-to-reproduce failures; capture raw request/response (redacted) in logs for the first weeks of each new client.
• Silent semantic drift → provider changes a field's meaning without changing the WSDL. Contract tests against a provider sandbox are the only reliable guard.

Ramp-up

• A Laravel developer is productive with Soapy in well under a day: publish config, define a client, call it, fake it in tests.
• The real ramp-up cost is SOAP/WSDL literacy — faults vs. transport errors, WS-Security, attachments, namespaces — plus the specifics of each counterparty's sandbox and certification process. Plan provider onboarding lead time (often weeks, sometimes regulatory) separately from engineering effort.
• Onboarding material to produce: a one-page "how we call SOAP services here" standard (gateway boundary, timeout defaults, retry policy, logging/redaction rules), plus a working example test using the package's fake support so new joiners copy a known-good pattern.