Encoding Laravel Package

Technical Evaluation

Architecture fit

• php-soap/encoding is a low-level serialization component, not a SOAP client. It handles XML/SOAP envelope construction, XSD type mapping, and encode/decode of message bodies. It has no Laravel service provider, facade, config, or transport layer, so it slots in beneath application code rather than beside it.
• It is best treated as an internal dependency of a higher-level stack (php-soap/client, php-soap/engine, or a wrapper such as code-distortion/laravel-soap) rather than a direct application dependency. Adopting it directly means we own the transport, WSDL resolution, and error-handling layers ourselves.
• Framework-agnostic and PSR-4 autoloadable, so it does not fight Laravel's architecture. The cost is that all Laravel-flavored concerns (config, logging, retries, HTTP client, DI bindings) must be written by us.
• 0.36.0 does not change this positioning. It is an internal refactor plus behavior corrections inside the encoding layer — the package boundary, public entry points, and absence of framework integration are unchanged.

Integration feasibility

• Composer install is trivial; the real effort is domain knowledge. Correct use requires understanding SOAP 1.1 vs 1.2 envelopes, RPC/encoded vs document/literal styles, XSD imports/includes, complex types, nil semantics, and namespace handling.
• Feasible as a bounded pilot behind an adapter interface. Not feasible as a "drop in and call an endpoint" library — expect to write 200–500 lines of glue plus fixture-based tests before first production call.
• 0.36.0 slightly raises the customization ceiling and the customization tax at the same time: extension points (custom lenses) are now more capable but their contract changed. Any glue code we write that implements ProvidesObjectEncoderLens / ProvidesObjectDecoderLens is not portable across this upgrade and must be migrated (array lookup → ElementLookup object, plus explicit miss handling).

Technical risk

• Maturity signal: still a 0.x pre-1.0 component with a small adopter base, but 0.36.0 is a positive signal — two external contributors (@ITernovtsii, @NickSdot) diagnosed real correctness bugs, upstream merged them with attribution, and the release is backed by a published benchmark methodology and byte-identical-output verification. Community validation is thin but genuinely engaged, not a single-maintainer monologue. The anomalous 2026-10-16 date noted previously should still be reconciled against Packagist, but release activity is now clearly real.
• Semver discipline: 0.36.0 ships multiple breaking behavior changes in a minor-style bump (removed class, changed lens API, changed attribute namespacing, changed nil-on-encode semantics, changed exception propagation). This is expected for 0.x and confirms the existing control: pin exact versions, read changelogs on every bump, and treat any version change as potentially behavior-changing.
• Bus factor: still likely one or two maintainers (release is overwhelmingly authored by @veewee). MIT license keeps a vendor fork viable, but forking a serializer is an ongoing tax, not a one-time cost.
• Parity risk (new, material): 0.36.0 deliberately diverges from ext-soap in how ref-declared attributes are namespaced (xml:lang, tns:code). If we run a mixed estate — ext-soap for simple endpoints, this package for complex ones — the same logical payload can serialize differently across the two paths. That is a correctness and auditability concern, not just a cosmetic one.
• Wire-format risk (new): absent optional nillable elements are no longer emitted as xsi:nil. This is semantically better but is a behavioral change on the wire. Vendors with strict or hand-rolled XSD validation, or partners who historically relied on receiving an explicit nil, may reject or misinterpret payloads that were previously accepted. This must be validated against every counterparty, not just against local fixtures.
• Security surface: unchanged and still caller-relevant. XML parsing is a classic XXE and entity-expansion target. Confirm the library disables external entity loading and enforces libxml limits, or wrap it so we do.
• Runtime dependencies: 0.36.0 tightens the graph to veewee/reflecta ^1.2, veewee/xml ^4.14, php-soap/wsdl-reader ~0.34, and widens dev/runtime allowances for symfony/var-dumper ^8.0 and guzzlehttp/guzzle ^8.0. Verify all of these against our PHP version, locked dependency set, and base images before bumping.

Key questions

1. Do we implement any custom ProvidesObjectEncoderLens / ProvidesObjectDecoderLens? If yes, this upgrade is a code change plus a test change, not a version bump.
2. Do we reference DocumentToLookupArrayReader anywhere (including tests, examples, or forked code)? It is removed with no deprecation shim.
3. Does any counterparty depend on receiving explicit xsi:nil for absent optional fields? Enumerate endpoints where a missing element is acceptable before rollout.
4. Do we decode attributes that arrive in an unexpected namespace, or rely on the old behavior where an attribute could populate a same-named child property? Those now silently decode to null.
5. Do any custom lenses currently rely on throwing to signal "not found"? Those throws now surface as EncodingException and fail the whole encode/decode.
6. Are we running a mixed ext-soap / php-soap/encoding estate? If so, how do we reconcile the new ref-attribute namespacing divergence?
7. Is this package already pulled in transitively by our existing SOAP dependency? If so, direct adoption is unnecessary and the upgrade may be forced on us by a parent bump.
8. Which encoding styles and SOAP versions are actually supported and tested (SOAP 1.2, MTOM/attachments, XSD import/include), and does 0.36.0 change any of them?
9. Does it handle XXE hardening internally, or is that the caller's responsibility?
10. Who owns this internally if the upstream maintainer goes silent?

Integration Approach

Stack fit

• Compatible with a standard Laravel 10/11/12 stack on PHP 8.1+. No framework coupling is a plus for a long-lived integration layer; it also means zero Laravel-native ergonomics.
• Fit remains conditional: good fit if we are building or customizing a SOAP client layer; poor fit if we simply need to call two vendor endpoints, where ext-soap's SoapClient or a maintained wrapper is cheaper.
• 0.36.0 strengthens the case for the "custom client layer" use case — typed xsd:anyType / SOAP-ENC Map and Struct decoding materially improves handling of loosely-typed vendor payloads — and strengthens the case against direct adoption for simple endpoints, where ext-soap parity is now less guaranteed than before.

Migration path

• Do not rip out ext-soap wholesale. Run a strangler pattern: keep SoapClient for stable, simple integrations and introduce this package only where ext-soap demonstrably fails (custom type mapping, non-standard envelopes, strict schema validation, testability). Note that this pattern now carries a parity obligation: the two paths no longer serialize identically for ref attributes, so any endpoint that crosses the boundary needs explicit contract tests.
• If the codebase already uses php-soap/client, this package is largely transparent and the migration is a version bump, not a rewrite — but the bump is not behavior-neutral (see compatibility below).
• Encapsulate behind our own SoapEncoderInterface so a future swap to ext-soap, laminas/laminas-soap, or a fork is a container binding change rather than a refactor. This abstraction also absorbs the 0.36.0 ElementLookup churn from the rest of the app.

Compatibility

• Breaking changes to schedule for: DocumentToLookupArrayReader removed; custom decoder lenses receive Soap\Encoding\Xml\Node\ElementLookup instead of an array; attributes now resolve by exact namespace (mismatched namespace → null, no fallback to same-named child property); throwing custom lenses now raise EncodingException instead of reading as null; absent optional nillable properties are omitted on encode rather than sent as xsi:nil; ref-declared attributes are written in their own namespace.
• New APIs available: Feature\NullValueAware + NullValueHandling for explicit null semantics per property, and ElementLookup::fromElement() / element() / attribute() as the replacement read path.
• Confirm PHP minor-version support and that CI covers our exact PHP and libxml versions; libxml behavior differences across distros are a real source of encoding drift, and a release this focused on decode paths is worth validating on our actual base image.
• Verify the bumped dependency floors (reflecta ^1.2, veewee/xml ^4.14, wsdl-reader ~0.34) do not collide with anything already locked in the application.
• Watch for namespace or autoload conflicts with other SOAP libraries and with ext-soap's own class names — coexistence is normal but must be verified.
• Pin exact versions in composer.json, lock them, and configure Renovate/Dependabot for review-only PRs on this dependency. Given 0.36.0's breaking changes inside a 0.x bump, auto-merge must be explicitly disabled.

Sequencing

1. Inventory — catalog existing SOAP endpoints, encoding styles, WSDL complexity, and which ones currently fail or require hacks. Add two new columns: relies on xsi:nil on the wire and uses custom lenses.
2. Upgrade audit — grep for DocumentToLookupArrayReader, ProvidesObjectEncoderLens, ProvidesObjectDecoderLens, and any lens that throws for control flow. Produce a per-file change list against the 0.36.0 changelog.
3. Spike — build one non-critical integration end-to-end with the package behind an adapter; record effort and surprises. Reuse the same spike to migrate one custom lens to ElementLookup and measure the real cost.
4. Contract tests — capture real request/response XML fixtures; assert byte-level or canonicalized equivalence. Capture fixtures on 0.35.0 before upgrading, then diff after — this is the only reliable way to catch the nil-omission and attribute-namespace changes in our own payloads.
5. Counterparty validation — for each endpoint where nil-omission or ref-attribute namespacing changes output, confirm acceptance with the vendor in a non-production environment.
6. Harden — XML security configuration, timeouts, retry/backoff, structured error mapping to Laravel exceptions and logs. Re-check that lens-thrown EncodingExceptions map to a diagnosable error, not a generic 500.
7. Pilot in production — one endpoint, feature-flagged, with shadow traffic if possible. Re-benchmark on our hardware and our payloads rather than trusting the published table.
8. Decide — expand, hold, or fall back to ext-soap/a fork based on measured effort.

Operational Impact

Maintenance

• Low release cadence and a small maintainer pool mean we should plan for the possibility of upstream stagnation. Budget a small quarterly review: dependency audit, changelog scan, security advisory check. 0.36.0 is a reminder that a "small" release here can require code changes, so the review must be a real review, not a rubber stamp.
• Maintain a standing upgrade runbook for this package: capture XML fixtures on the current version → upgrade in a branch → diff canonicalized output → validate against counterparties → promote. This is now the single highest-value operational artifact for the dependency.
• Keep a documented fork-and-patch runbook: because it is MIT and self-contained, an internal fork is a realistic contingency, but assign an owner before it is needed.

Support

• Community support will be thin — GitHub issues, no commercial backing — but 0.36.0 shows responsive upstream maintainership and a functioning external-contributor loop, which reduces (not eliminates) the risk of a fix we need going unmerged.
• Internal expertise must be deliberate: designate one or two engineers as owners and require them to review changes to the SOAP layer. The ElementLookup migration means lens-level knowledge is now version-specific; document it alongside the runbook.
• Expect to self-support debugging of vendor-specific quirks; vendor WSDL defects are common and the library will surface them as encoding errors rather than friendly messages. The new EncodingException on lens throws gives better diagnostics but can also convert a previously-degraded decode into a hard failure — alerting must distinguish the two.

Scaling

• This release materially changes the scaling picture in our favor. Published benchmarks on 3MB payloads show 51–95% decode improvements and 43–74% encode improvements versus 0.35.0, with byte-identical output. Encoding/decoding moves from "a plausible CPU hotspot at multi-MB payloads" to "unlikely to be the bottleneck" for typical enterprise SOAP volumes. This should be re-verified on our hardware and payload shapes before we bank it, but the direction is credible and the methodology is disclosed.
• The primary driver of the gain — removing an exception throw/catch per absent element and per stdClass property — means payloads with many sparse/absent fields benefit most. Dense payloads improve least (~43–51%). Sizing estimates should be segmented by payload shape, not averaged.
• No built-in caching. WSDL parsing and schema compilation, if repeated per request, will still dominate latency — cache parsed metadata in Redis or warm it at boot. Performance work here may now expose WSDL parsing as the next bottleneck.
• Horizontal scaling is straightforward since the component is stateless; the constraint is worker memory, not concurrency. Re-baseline queue-worker memory limits after upgrade rather than carrying forward old headroom assumptions.

Failure modes

• New in 0.36.0: absent optional nillable properties now encode as omitted elements rather than xsi:nil — counterparties with strict or hand-rolled validation may reject or misread the payload.
• New in 0.36.0: attributes arriving in an unexpected namespace decode to null silently; previously they could fall back to a same-named child property. A field that used to populate now quietly goes empty, which is far harder to detect than an error.
• New in 0.36.0: custom lenses that throw now fail the entire encode/decode with EncodingException; a previously tolerated "not found" becomes an outage.
• New in 0.36.0: ref-declared attributes serialize into their own namespace, diverging from ext-soap — mixed-stack estates can produce inconsistent payloads for the same logical request.
• New in 0.36.0: removal of DocumentToLookupArrayReader will fatal at autoload/compile time on any lingering reference; this fails loudly and is easy to catch pre-deploy.
• Namespace or prefix mismatches producing valid-looking but semantically wrong payloads.
• Encoding-style mismatch (RPC/encoded vs document/literal) causing vendor-side rejection with opaque faults.
• XSD type coercion errors: dates, decimals, booleans, nil vs empty element.
• Silent truncation or loss of attributes on deeply nested complex types.
• XXE / billion-laughs exposure if libxml entity loading is not explicitly disabled.
• Unhandled SOAP faults surfacing as generic 500s, obscuring the real vendor error from support.
• Unpinned version upgrades changing serialization output between deploys — now demonstrated as a live risk, not theoretical.

Ramp-up

• Steep for a team fluent in REST/JSON. Expect one to two weeks before an engineer is productive and four to six before they are confident with edge cases; budget for a SOAP primer and pair the new owner with whoever understands the current integrations.
• Mitigate by wrapping the library in an application-level abstraction with a narrow, documented surface (encode request, decode response, typed errors) so most engineers never touch the library directly. The 0.36.0 ElementLookup change is a concrete argument for this: teams behind the abstraction absorb a version bump, teams with lenses scattered through the app absorb a refactor.
• Produce internal documentation covering supported encoding styles, error taxonomy, null/nil handling policy (when we set null deliberately vs leave a property unset), attribute-namespace expectations, and the decision record for choosing this package over ext-soap. Without it, the next maintainer will re-litigate the choice — and will likely get the nil semantics wrong on the first attempt.