Product Decisions This Supports

Upgrade Sequencing (v3.3 → v4.0): This release is a deliberate deprecation bridge. Almost every change is a "works today, removed in 4.0" signal: the config alias changes to cleverage_soap_process (old keys were silently ignored), ClientRegistry::addClient() is deprecated in favor of code on the cleverage.soap.client tag or the new #[AsSoapClient(code: '...')] attribute, the task/transformer service IDs move to soap_request (former IDs remain as aliases until 4.0), and RequestTask, RequestTransformer, ClientRegistry and CleverAgeSoapProcessBundle are @final since 3.3. This is a roadmap input: schedule a v4.0 readiness work item now, while the upgrade path is documented in UPGRADE.md.
Runtime Contract (Corrected Baseline): The package requires PHP ^8.2, cleverage/process-bundle ^5.4, psr/log ^2|^3, plus symfony/polyfill-php83/84/85 and symfony/service-contracts. Note two constraints your platform decision must absorb: PHP 9 is explicitly excluded (until tested — good hygiene, but it means a PHP 9 migration will block on this dependency), and psr/log 1.x is a fatal error, so any service still pinned to psr/log ^1 must be upgraded alongside.
Resilience / Blast Radius Reduction: Client loading is now lazy via a service locator indexed by code — a single misconfigured SOAP client no longer fails an entire process run, only the tasks that actually use it. This is a direct reduction in operational blast radius for integrations spanning many endpoints (ERP + payment + government APIs in one process).
Observability as a Shipped Fix: RequestTask now logs to the cleverage_process_task channel with proper process context instead of app, which means SOAP failures finally surface in the process execution UI. This changes incident triage: previously failed SOAP calls could appear as an empty result set (Empty resultset for query) rather than a failure — a genuinely misleading signal for on-call.
Error Handling Contract: Bundle exceptions now implement ProcessExceptionInterface while still extending the SPL exceptions thrown before, with identical messages. Existing catch blocks keep working and failures can now be handled uniformly with the rest of the process bundle — relevant for retry/alerting policy design.
Dependency Footprint: Dropping symfony/finder, removing the unnecessary symfony/flex plugin authorization, and adding .gitattributes (dev files excluded from the Composer dist archive) reduce install size and supply-chain surface — a small but real build-time and audit win.
Use Cases Unchanged but Better Served: Enterprise B2B SOAP integrations, legacy system bridges, and any Laravel/Symfony app running SOAP calls inside a process/pipeline abstraction where per-task isolation, typed exceptions, and UI-visible logs matter.

When to Consider This Package

Adopt If:

Your project uses SOAP services (payment gateways, government APIs, ERP, legacy bridges) and you want structured task/transformer handling rather than raw SoapClient calls.
You are on PHP 8.2+ and can also adopt cleverage/process-bundle 5.4+ — this is a hard co-dependency, not optional; v3.3 exists largely to align with it.
You run long-lived workers (queues, Messenger, Swoole/RoadRunner): note the documented caveat that a shared client keeps its state between two process executions — adopt only with that understood, or isolate by code per execution.
You benefit from lazy client instantiation (many SOAP endpoints, only some used per run) or need failures to be isolated per task.
Your team lacks deep SOAP expertise but needs XML validation, WS-Security, and consistent request/response plumbing.
You can absorb deprecation warnings now in exchange for a clean v4.0 upgrade later (DebugClassLoader will flag extensions of the @final since 3.3 classes; container compilation emits a notice for legacy config keys).

Look Elsewhere If:

You are on PHP 8.1 or below, or on psr/log 1.x with no upgrade path — v3.3 will not install.
You need to be PHP 9-ready soon; ^8.2 explicitly rejects it until upstream testing lands.
Your use case is REST/JSON-heavy (use Laravel's HTTP client or guzzlehttp/guzzle) or requires GraphQL/gRPC — this package is SOAP-specific.
You cannot take a cleverage/process-bundle 5.4+ requirement, or you use a different process/pipeline abstraction — the task codes, ProcessExceptionInterface, and TaskLogger integration are all coupled to it.
You plan to extend RequestTask / RequestTransformer / ClientRegistry / the Bundle class as a customization strategy — these are @final since 3.3 and will be final in 4.0. Prefer composition now.
Your project is headless/JS-first and SOAP is irrelevant.
You need long-term API stability guarantees beyond Symfony's BC promise — v4.0 will remove the deprecated aliases, the eager addClient() path, and legacy config keys.

How to Pitch It (Stakeholders)

For Executives:

"This is a maintenance release on a dependency we already use to talk to SOAP-based systems — ERP, payment processors, government APIs — inside our process pipelines. It doesn't add scope; it makes the integration more reliable and cheaper to operate: SOAP failures now show up correctly in our execution logs instead of looking like empty results, a broken client endpoint no longer takes down an entire process run, and the package tracks a supported PHP 8.2+ baseline with polyfills for newer language features. The one decision it forces is timing: the maintainers have clearly signposted a 4.0 cleanup, and v3.3 is the cheapest moment to do the small migrations (client codes, service IDs) — while they're optional rather than breaking. Low-risk, low-effort, and it de-risks a future upgrade instead of deferring it."

For Engineering:

"v3.3 is an alignment + deprecation release, not a feature release. Concretely:

Requires cleverage/process-bundle ^5.4, PHP ^8.2 (PHP 9 rejected until tested), psr/log ^2|^3 (1.x is a fatal error), symfony/service-contracts, symfony/deprecation-contracts, and PHP 8.3–8.5 polyfills. symfony/finder and the symfony/flex plugin allowance are gone.
Clients are now loaded lazily from a service locator keyed by code — set via the cleverage.soap.client tag's code attribute or #[AsSoapClient(code: '...')]. Duplicate or empty codes fail container compilation. Tagging without code still works but addClient() is deprecated.
Exceptions now implement ProcessExceptionInterface while extending the previous SPL exceptions with the same messages — existing catch blocks are unaffected, but you can now handle failures uniformly.
RequestTask/RequestTransformer are addressable as soap_request; the old cleverage_soap_process.task.request and .transformer.request IDs are deprecated aliases removed in 4.0, and direct container fetching is deprecated (container.private).
Deprecations to burn down now: rename the config alias to cleverage_soap_process (old keys were silently ignored — anything you configured there never applied), stop extending the @final since 3.3 classes, always supply a client code, and stop fetching services by ID.*
Ops note: shared clients retain state between process executions in long-running workers — review worker-scoped client usage before rollout.*

No forced refactor today, but treat the deprecation list as a v4.0 work item with a deadline set by upstream."

For Developers:

"Upgrade is mechanical; the value is in the fixes and the guardrails.

Fixes you'll actually notice

🐛 Logging — RequestTask now injects logger (not monolog.logger), so SOAP failures log to the cleverage_process_task channel with process context and appear in the execution UI. Also, a failed call now logs Soap call failed instead of the misleading Empty resultset for query. If you were debugging SOAP failures by guessing, this is your release.
✅ Resilience — lazy client registry: an error in a client a given process doesn't use no longer fails that process.

API changes to adopt

Clients: add code to the cleverage.soap.client tag, or use #[AsSoapClient(code: '...')]. The code must match getCode(). Empty/duplicate codes fail compilation — treat that as a feature.
Tasks/transformers: reference by code soap_request (requires process-bundle 5.4+). cleverage_soap_process.task.request / .transformer.request are deprecated aliases. Don't pull them from the container directly — they go private in 4.0.
Exceptions: new Exception\UnexpectedValueException, InvalidArgumentException, RuntimeException implement ProcessExceptionInterface and extend the SPL ones — same messages, existing catches keep working.
Config: the alias is cleverage_soap_process. The bundle has no configuration; keys under the old spelling were silently ignored (compile-time notice now, rejected in 4.0). Remove them.
RequestTask, RequestTransformer, ClientRegistry, CleverAgeSoapProcessBundle are @final since 3.3 → extend via composition; DebugClassLoader will warn otherwise. Client and MissingClientException remain open for extension. CleverAgeSoapProcessExtension and RegisterClientsPass are @internal.

Watch out for

psr/log 1.x will fatal — bump to ^2|^3 first.
PHP is capped at ^8.2 (PHP 9 not accepted).
Shared clients keep state across process executions in long-running workers — don't assume a clean slate per run.
Follow UPGRADE.md#v33; CI now tests --prefer-lowest on PHP 8.2, so low-end deps are actually exercised.

Example: wrap a SOAP payment gateway as a Client with #[AsSoapClient(code: 'payment')], call it from a soap_request task — failures now land as typed ProcessExceptionInterface exceptions and show up in the process UI."*

Soap Process Bundle Laravel Package