Encoding Laravel Package

Product Decisions This Supports

• Build vs. buy for SOAP interoperability. This package is the serialization layer of a SOAP stack: it converts PHP values to/from SOAP-encoded XML (SOAP 1.1 §5 encoded types, xsi:type, multi-ref graphs, arrays). It informs the decision to not hand-roll XML encoding and instead compose a maintained codec — and 0.36.0 strengthens that case: a 3 MB payload decode dropped from ~7.2 s to ~0.38 s (‑94.7%), work we would never have prioritized in-house.
• Roadmap: enterprise/legacy integration surface. If your product must talk to ERP, banking, healthcare, government, or older partner systems, SOAP support is a scope item. This release makes high-volume / large-payload SOAP (batch ETL, nightly reconciliation, bulk sync) a realistic roadmap item rather than a "make it async and hope" workaround.
• Feature scoping. Useful when a feature needs to generate or parse SOAP envelopes — partner connectors, middleware/ETL jobs, WSDL-driven client generation, or a compatibility shim in front of a modern REST API.
• Capacity and unit-economics decisions. A 5–95% decode speedup on real payload sizes changes sizing assumptions: fewer workers, shorter batch windows, smaller timeouts, less retry pressure on partner endpoints. Re-baseline any cost model built on the 0.35.x numbers.
• Deprecation / ownership decisions. A small, focused codec keeps SOAP maintenance legible — "one low-churn dependency" — but 0.36.0 shows the churn is real: it is a pre-1.0 library with breaking changes and custom-lens API shifts. Budget a small, recurring upgrade-and-regression-test effort, not zero.
• Stack standardization. Supports choosing within the php-soap/* family (wsdl-reader, http-client, encoding) versus ext-soap, Laminas SOAP, or Symfony-oriented alternatives — with the caveat that this release moves further from ext-soap parity in one documented area (see below), so "drop-in equivalence" is not the right framing.

When to Consider This Package

Consider it when:

• You are building SOAP clients in PHP and need correct, spec-compliant encoding — especially encoded (not just literal) messages, multi-ref structures, typed arrays, and inheritance via xsi:type.
• Payloads are large or volume is high. This is now the clearest reason to pick it over hand-rolled code or slower alternatives: the throwless-lens rewrite delivers 42–95% improvements with byte-identical output on 3 MB payloads. If your integration profile is "many small calls," the win is smaller (25–75% on phpbench payloads) but still free.
• ext-soap is insufficient or unavailable (custom transports, non-WSDL-driven calls, testability, or environments where the extension can't be installed).
• You are already adopting the php-soap/* ecosystem and want the encoding concern handled by a dedicated, single-responsibility library.
• You can accept component-level risk plus pre-1.0 instability. 0.36.0 is evidence in both directions: it is actively maintained with external contributors filing reproduction cases and fixes (a healthy signal), and it removed a public class, changed the lens API signature, and changed default wire behavior. Plan for a pinning + upgrade-test cycle rather than "set and forget." Validate adoption via Packagist downloads, reverse dependencies, and changelog cadence; MIT licensing means forking remains a viable fallback.

Look elsewhere when:

• The integration is REST/JSON — this is irrelevant; use any HTTP client.
• SOAP is simple, WSDL-literal only, and ext-soap already works — the extra dependency buys little, and you'd inherit upgrade churn for no gain.
• You need a turnkey SOAP client (transport, auth, WS-Security, retries). This is one layer; you'd assemble the rest yourself.
• You need byte-exact ext-soap output as a hard requirement. 0.36.0 intentionally diverges: absent optional nillable properties are omitted rather than sent as xsi:nil (unless explicitly set to null), and attributes declared via ref are written in their own namespace (e.g. tns:code) instead of matching ext-soap. Verify against partner WSDLs before swapping out an ext-soap path.
• Procurement requires vendor SLAs, indemnity, or a commercial support contract — this is a community package.
• You need WS-Security/WS-Addressing, MTOM/attachments, or advanced WS-* profiles as first-class features; evaluate the surrounding stack or a commercial SOAP product.

If you adopt, capture these 0.36.0 migration items in the plan: nillable-element omission (#79); ElementLookup replacing the lookup array in custom ProvidesObjectDecoderLens and the removal of DocumentToLookupArrayReader (#80); strict namespace matching for attributes; lens exceptions now surfacing as EncodingException instead of decoding to null (#84); NullValueAware / NullValueHandling for encoder null semantics (#83); and the php-soap/wsdl-reader ~0.34 + veewee/xml ^4.14 + veewee/reflecta ^1.2 constraint alignment, which must be upgraded as a set.

How to Pitch It (Stakeholders)

For executives: We need to integrate with partner systems that still speak SOAP. Rather than build XML/SOAP serialization ourselves — a well-specified but error-prone problem — we adopt a small, MIT-licensed, single-purpose library and compose it with a WSDL reader and HTTP client. Licensing cost is zero, scope is narrow, and the code is small enough that forking is a realistic contingency. The latest release is a meaningful de-risking event on performance: large-payload decoding got roughly 5–20× faster, which improves our batch windows and compute footprint without a rewrite. The trade-off is that the library is pre-1.0 and this release contains breaking changes, so we pin versions, hold a regression suite of real partner payloads, and schedule a small upgrade window per bump. Net: a roadmap item delivered without a vendor contract, at the cost of disciplined dependency hygiene we already apply elsewhere.

For engineering: Focused codec, not a framework — encoding/decoding of typed values, multi-ref graphs, arrays and xsi:type behind a small API. 0.36.0 removes intermediate exception-based control flow, decodes through a new ElementLookup, and writes via plain XMLWriter; output is byte-identical on the published benchmarks, with 42–95% gains on 3 MB payloads. It composes with php-soap/wsdl-reader and php-soap/http-client and unit-tests independently of transport. Treat it as a breaking release: update custom lenses to ElementLookup ($lookup->element(...) / $lookup->attribute(...)), replace DocumentToLookupArrayReader::fromElement() with ElementLookup::fromElement(), make lenses handle their own misses (reflecta optional() / optional_property()) since failures now throw EncodingException, and review null/nillable semantics against the new NullValueAware / NullValueHandling behavior. Watch the two deliberate ext-soap divergences (omitted nillable elements; ref attributes in their own namespace) if you're behind an A/B comparison. Star count still misleads — it's a split sub-package; judge on Packagist adoption, the now-visible responsiveness to external bug reports, test coverage and changelog health. Recommendation stands and is now better supported: spike it against two real partner WSDLs (one encoded, one literal), snapshot golden output on 0.35.x before upgrading, and diff before committing.