Engine Laravel Package

Technical Evaluation

Architecture fit

php-soap/engine is a framework-agnostic core with three clean seams that map well onto how a Laravel application is already structured:

• Transport seam (PSR-18). Laravel already ships guzzlehttp/guzzle, which implements Psr\Http\Client\ClientInterface. This means the engine can ride on the same Guzzle stack the app uses for HTTP, inheriting Laravel's HTTP client middleware, timeouts, retries, and logging rather than introducing a second outbound HTTP path.
• Serialization seam (encoders/decoders). SOAP envelope construction is isolated from transport, so envelope concerns (WS-Security headers, SOAPAction, SOAP 1.1 vs 1.2) are pluggable middleware rather than baked-in behavior.
• Discoverability seam (WSDL-driven). Operations and types are derived from the WSDL, which is the right abstraction for a TPM to reason about: the contract is the document, and drift is detectable.

The trade-off versus ext-soap is that this is a pure-PHP reimplementation. That is the entire value proposition (testability, middleware, typed calls, no C-extension surprises) and also the entire risk surface (WSDL edge cases that ext-soap tolerates).

Integration feasibility

Feasible with modest effort. Expected pieces:

• composer require php-soap/engine plus the PSR-18 transport adapter and a PSR-18 client (Guzzle).
• A small service provider binding a configured engine (WSDL location, endpoint, transport) as a singleton, plus per-service client wrappers.
• A caching layer for parsed WSDL (the cached-engine companion or Laravel's cache repository). This is not optional at production scale.
• Optional code generation for typed DTOs — valuable but adds a build step and tooling ownership.

No Laravel-specific package appears to exist from the maintainers, so the integration glue is ours to own. That is ~1–2 days of work per external service including tests, not a platform project.

Technical risk

Key questions

1. How many distinct external SOAP services, and do all their WSDLs parse cleanly?
2. Which WS-* features are contractually required (WS-Security, MTOM, WS-Addressing)?
3. Is there a hard requirement to stay on ext-soap for any service?
4. Who owns the abstraction layer internally if the upstream project stalls?
5. What is the acceptable WSDL-refresh latency under provider schema changes?

Integration Approach

Stack fit

Good. The package sits below the application layer and above Guzzle, touching none of Laravel's request lifecycle, container, or ORM. Recommended shape:

• config/soap.php — per-service WSDL path, endpoint per environment, timeout, cache store, cache TTL.
• App\Soap\Contracts\{Service}Gateway — one interface per external service, expressed in domain terms.
• App\Soap\{Service}Client — adapter that depends on the engine client, translates domain DTOs to SOAP requests and faults to domain exceptions.
• SoapServiceProvider — builds engines as singletons, wires the PSR-18 transport to Guzzle/Laravel HTTP client.
• Middleware stack: correlation-ID injection, envelope logging with PII redaction, metrics/timing.
• Feature tests use a fake PSR-18 client returning recorded envelopes — no live network, no ext-soap mocking pain.

Putting the interface boundary in place from day one is the single highest-leverage TPM decision here, because it converts a package-adoption risk into an implementation-detail risk.

Migration path

• Phase 1 — PoC (1 sprint). One service, real WSDL, cold and warm WSDL parse timed, happy path + fault path + one edge case. Decision gate: does it handle our WSDL corpus?
• Phase 2 — Abstraction. Gateway interface + adapter + DTO mapping + fake-transport tests. Still one service in production.
• Phase 3 — Operationalize. WSDL caching, config, structured logging, metrics, timeout/retry policy on the Guzzle transport, alerting on SOAP fault rate.
• Phase 4 — Migration. Move remaining services one at a time, lowest-criticality first. Leave ext-soap clients untouched until the abstraction has proven itself.
• Phase 5 — Typed DTOs (optional). Introduce code generation for request/response types if DTO volume justifies the build-step cost.

Compatibility

Verify explicitly: minimum PHP version vs the Laravel version in use, PSR-7/17/18 implementation versions, and Guzzle major-version alignment. Pin minor versions and let Renovate/Dependabot surface upgrades rather than floating ranges.

Sequencing

Do not migrate everything at once. The abstraction layer first, one service end-to-end second, breadth last. If the package fails the PoC, the abstraction survives and the implementation is swapped — this is the whole point of the sequencing.

Operational Impact

Maintenance

Pin to a specific minor; upgrade deliberately with the contract-test suite as the safety net. Because the library is MIT and framework-agnostic, the maintenance ceiling is "fork and patch" — acceptable. Budget a named internal owner and a recurring review of upstream activity. The low star count is not disqualifying (the ecosystem is split across several repos), but it does mean the project cannot be relied on to absorb its own bugs on a schedule.

Support

No vendor SLA. Support is GitHub issues plus our own engineers. For a TPM this means the team must be capable of reading SOAP envelopes and WSDL XML — not just calling a method and hoping. Plan for at least one engineer to become the internal SOAP subject-matter expert.

Scaling

Favorable. The engine is stateless and per-request; horizontal scaling is not a concern. Two real scaling constraints:

• WSDL parse cost — mitigate with a shared cache (Redis) so all pods reuse the parsed definition. Warm-path cost should be milliseconds.
• Large XML payloads and attachments — memory and serialization time grow with envelope size; set payload size expectations and test with production-representative samples.

Outbound concurrency is bounded by the Guzzle transport, so connection reuse and pool tuning live where the team already knows how to tune them.

Failure modes

• WSDL unavailable at boot — fatal if fetched lazily. Mitigate by caching to disk/Redis and treating the WSDL as a deployable artifact, not a runtime fetch.
• Provider schema drift — silent breakage or opaque decoding errors. Mitigate with CI contract tests against a pinned WSDL snapshot and alerting on decode failures.
• SOAP faults returned as HTTP 500 — must be mapped explicitly to domain exceptions; otherwise they surface as generic transport errors.
• Timeout/retry semantics — retries on non-idempotent operations are dangerous; scope retry middleware to read-only operations.
• XML security — disable external entity resolution in the parser; verify large-payload and entity behavior in the PoC.
• Silent namespace/encoding bugs — the package's testability helps here; require envelope-level assertions in tests, not just response-object assertions.

Ramp-up

Moderate. The PSR-18/PSR-7 model is familiar to most Laravel engineers, but SOAP itself is not — expect time spent on WSDL reading, namespace handling, and fault taxonomy. Realistic estimate: one engineer productive in a week, team-productive in three to four weeks, with the abstraction layer and test harness doing most of the de-risking. Budget for a short internal knowledge-share on debugging SOAP envelopes, because that is where incidents will be won or lost.