Soap Process Bundle Laravel Package

Technical Evaluation

What changed since v3.0 (v3.3 release, published 2025-12-10)

• Platform baseline corrected: v3.3 requires PHP ^8.2 (not >=8.2), explicitly rejecting PHP 9, and layers symfony/polyfill-php83/84/85 so PHP 8.3–8.5 language features are usable while still supporting PHP 8.2. The prior assessment's premise that this package is gated on PHP 8.5/Symfony 8 is wrong and materially changes the risk profile.
• New hard dependency: cleverage/process-bundle ^5.4. This is now a peer package, not an optional add-on, and its version becomes part of our upgrade graph.
• Deprecation-release character: v3.3 is explicitly a bridge to 4.0. Multiple items (config key rejection, ClientRegistry::addClient(), legacy service IDs, @final since 3.3) become breaking in 4.0.
• Behavioural fixes: RequestTask now logs failures as Soap call failed (previously the misleading Empty resultset for query) and logs on the cleverage_process_task channel, restoring log visibility in the process execution UI.
• Architectural improvement: clients are now loaded lazily from a service locator indexed by a code (via tag attribute or #[AsSoapClient(code: '...')]).

Architecture Fit cleverage/soap-process-bundle remains a Symfony bundle, not a Laravel package. Fit with a Laravel codebase is therefore indirect: we consume it as a Symfony component-style dependency or wrap it. v3.3 strengthens the underlying architecture (lazy client registry, exception hierarchy implementing ProcessExceptionInterface, defined public API surface) but does not add any Laravel-facing surface — still no service provider, no facade, no config publishing.

Importantly, the bundle now declares no configuration at all: the extension alias is cleverage_soap_process (correcting the previously misspelled clever_age_soap_process), and configuring keys under it is deprecated and will be rejected in 4.0. Any assumption that this package offers runtime configuration toggles (endpoints, timeouts, credentials via config) is false — wiring happens through DI tags and attributes, which Laravel does not have natively.

Integration Feasibility

• Laravel baseline: Laravel 11.x/12.x (PHP 8.2+) is the realistic floor. Laravel 10 on PHP 8.1 is excluded by the ^8.2 constraint. Confirm the Symfony constraint in composer.json before committing; v3.3's notes only evidence symfony/service-contracts, symfony/deprecation-contracts, and removal of symfony/finder.
• Wiring effort is now higher, not lower: the code-indexed service locator and #[AsSoapClient] attribute are Symfony DI autoconfiguration features. In Laravel we must either (a) register clients manually and call the (deprecated-in-4.0) ClientRegistry::addClient(), or (b) build a Laravel wrapper that constructs the locator ourselves. Option (a) is a dead end past 4.0.
• Peer dependency: cleverage/process-bundle ^5.4 must be installed and, if we use its process/UI features, understood. Task referencing by service is deprecated in favour of the new soap_request task code — this is actually a cleaner integration point for a Laravel wrapper than the old service-ID approach.
• Observability is feasible out of the box: with the logger fix, task failures land on a dedicated channel, so standard Laravel/Monolog log aggregation will capture failed SOAP calls with process context.

Technical Risk

• PHP 8.1 exclusion: blocking for any Laravel 10 service still on 8.1. Audit required before adoption.
• 4.0 cliff: v3.3 accumulates deprecations that become removals. Adopting 3.3 without a 4.0 remediation plan converts future upgrades into a coordinated breaking change.
  • ClientRegistry::addClient() → code mandatory.
  • Legacy service IDs cleverage_soap_process.task.request / .transformer.request → removed; use soap_request and class-name IDs.
  • Direct container fetches of the task/transformer → private services.
  • Extending RequestTask, RequestTransformer, ClientRegistry, CleverAgeSoapProcessBundle → deprecated now, fatal in 4.0.
  • Config keys under cleverage_soap_process → rejected in 4.0.
• Statefulness in long-running workers (highest operational risk for Laravel): the release documentation explicitly states a shared client keeps its state between two process executions in a long-running worker. Under Laravel Octane or long-lived queue workers this means stale auth headers, cookies, or accumulated SOAP state bleeding across jobs. This is a genuine correctness hazard, not a performance note.
• Lazy loading shifts failure later: a misconfigured client no longer fails container compilation or unrelated processes — good — but the failure now surfaces at first use in production rather than at deploy. Mitigate with a smoke test that exercises every registered client code.
• Container compile failures on bad codes: duplicate or empty client codes fail compilation. This is a fail-fast win, but it means CI must compile the container (a step Laravel shops rarely run).
• Minor BC: MissingClientException::create(string $code) is now strictly typed; psr/log ^2|^3 is required (psr/log 1 causes a fatal error on typed logger signatures).

Key Questions

1. What PHP versions are actually running across the Laravel fleet, and can 8.1 be retired?
2. Is cleverage/process-bundle an acceptable addition to our dependency graph, or does it imply adopting a process-execution framework we don't want?
3. Who owns the Laravel wrapper (service provider + registry factory + #[AsSoapClient] equivalent), and is it funded for the 4.0 migration?
4. Are we running Octane or long-lived queue workers? If so, what is the strategy for client state isolation per execution?
5. Do we have container-compilation and per-client smoke tests in CI, or only functional endpoint tests?
6. Is there an existing SOAP client (php-soap, guzzle-soap, diabol/soap) whose removal cost exceeds the benefit of this bundle?

Integration Approach

Stack Fit

• Target: Laravel 11/12 on PHP 8.2–8.5, consuming the bundle plus cleverage/process-bundle ^5.4.
• Preferred pattern: an internal laravel-soap-process wrapper package that (a) registers a service provider, (b) builds ClientRegistry from a Laravel config array into the new locator-based constructor, (c) exposes a facade for dispatching RequestTask, and (d) provides a Laravel-native attribute (or config key) mirroring #[AsSoapClient(code: '...')]. This mirrors the bundle's own lazy-loading design rather than fighting it.
• Avoid: direct ClientRegistry::addClient() calls (deprecated, removed in 4.0) and referencing the task by legacy service ID.
• Alternatives to benchmark: native php-soap extension (fastest, least abstraction), guzzle-soap, diabol/soap. The bundle's differentiator is process orchestration and transformation, not raw SOAP transport — if we only need request/response, the bundle is over-scoped.

Migration Path

1. Audit: composer.json PHP/Symfony constraints across all SOAP-touching services; inventory existing SOAP clients; confirm cleverage/process-bundle version compatibility with anything already installed.
2. Adopt 3.3 as the bridge: install v3.3, immediately migrate off every item on the 4.0 removal list (config keys, addClient(), legacy service IDs, container fetches, subclassing of @final since 3.3 classes).
3. Wire via wrapper: implement the Laravel service provider and locator factory; assign stable code values per client.
4. Replace legacy SOAP logic incrementally with RequestTask invocations.
5. Harden: add container-compilation check, per-client smoke test, and SOAP fault fixtures to CI.

Compatibility

• PHP: ^8.2 hard floor; PHP 9 rejected. Polyfills required and installed automatically.
• psr/log ^2|^3 — verify no transitive dependency pins psr/log ^1.
• symfony/finder no longer required (bundled files loaded via glob) — safe to drop if unused elsewhere.
• Dev files (.docker/, .github/, tests/, quality configs, Makefile) are excluded from the Composer dist archive — smaller vendor footprint, no dev-only code shipped.
• Laravel's HTTP client and the bundle's transport can coexist, but do not route the same call through both; pick one owner per integration.

Sequencing

1. Phase 0 — Decision: confirm the bundle is warranted versus php-soap/Guzzle.
2. Phase 1 — Platform: get target services to PHP 8.2+ and install cleverage/process-bundle ^5.4 + bundle v3.3.
3. Phase 2 — Deprecation burn-down: eliminate all 4.0-removal-list usages while on 3.3 (this is the cheapest moment to do it).
4. Phase 3 — Laravel wrapper: service provider, registry factory, facade, code-based client registration.
5. Phase 4 — Cutover: migrate endpoints service by service behind feature flags.
6. Phase 5 — 4.0 readiness: re-run deprecation scan; expect a near-mechanical 4.0 upgrade if Phase 2 was completed.

Operational Impact

Maintenance

• Positive: v3.3 introduces a real public API contract (Symfony BC promise) — RequestTask, RequestTransformer, ClientRegistry, CleverAgeSoapProcessBundle are @final since 3.3; CleverAgeSoapProcessExtension and RegisterClientsPass are @internal. This is exactly the signal a TPM wants: extending these classes is now a known-unsupported path, which reduces long-term fork risk if we respect it.
• Negative: the Laravel wrapper is ours to own and maintain, including tracking cleverage/process-bundle releases. Two upstream packages now gate our upgrades instead of one.
• Ongoing tax: repeated deprecation-notice monitoring (the bundle emits a container-compile notice when config keys are present). Suppress-by-ignoring is not viable; the notice becomes an error in 4.0.

Support

• Debugging improved: failed SOAP calls now log Soap call failed on the cleverage_process_task channel with process context — failed calls are finally visible in process execution logs rather than silently missing or mislabelled.
• Exceptions: the bundle now throws ProcessExceptionInterface-implementing UnexpectedValueException, InvalidArgumentException, and RuntimeException that extend the previously thrown SPL exceptions with identical messages. Existing catch blocks keep working, which means our error handling needs no rewrite — but new code should catch the interface, not the SPL base.
• Community: no Laravel-specific support channel; Symfony/Soap communities only. Budget internal expertise.
• Diagnosability gap: lazy client loading means a broken client is invisible until first invocation. Support runbooks must include "which client codes exist and are they exercised?"

Scaling

• Throughput: SOAP remains chatty and XML-bound; the bundle does not change that. Benchmark against php-soap before assuming parity.
• Resilience win: with lazy clients, an error in one client no longer fails processes that don't use it — this is a genuine availability improvement at scale.
• Horizontal scaling: stateless per-request usage scales linearly; cache WSDL/metadata aggressively.
• Statefulness under Octane/queue workers: shared clients persist state across executions. This is the primary scaling hazard — plan for per-execution client isolation or disable shared clients in long-running contexts.

Failure Modes

Ramp-Up

• Low: Symfony-fluent engineers — v3.3's attribute/locator model is idiomatic Symfony.
• Medium: Laravel engineers — the DI model (tags, autoconfiguration, service locators) has no direct Laravel analogue; the wrapper exists precisely to hide this.
• High: teams new to SOAP itself (WSDL, namespaces, WS-Security, encoding).

Onboarding steps

1. Sandbox a Laravel 11/12 app on PHP 8.2 with the bundle and cleverage/process-bundle ^5.4.
2. Register one client by code, invoke RequestTask via the soap_request task code, and confirm the log lands on cleverage_process_task.
3. Verify error handling catches ProcessExceptionInterface.
4. Benchmark against php-soap for a representative payload.
5. Document the internal wrapper's contract and the 4.0 removal checklist.

Training focus: SOAP fundamentals (envelopes, WSDL, faults), Symfony DI autoconfiguration and service locators, and — critically — the semantics of shared clients in long-running workers.