Xsd Reader Laravel Package

Technical Evaluation

Architecture fit

• This is a parsing primitive, not a Laravel package. There is no service provider, config file, facade, or published migrations — it produces an in-memory PHP object graph of a schema (Schema, Element, ComplexType, SimpleType, Attribute, Group) that our own code must interpret. Budget for an adapter layer, not a drop-in install.
• Best architectural fit is build-time / offline metadata extraction, not request-time parsing. In a Laravel app the natural seams are: an artisan command or queued job that ingests XSDs and emits cached metadata or generated DTOs, then runtime code that consumes the cached artifact.
• Secondary fit is integration middleware for partner SOAP/XSD APIs: parse once, persist a normalized contract, and drive validation, payload mapping, or stub generation from it. The companion ecosystem (wsdl-reader, and by extension xsd2php-style code generation) is the reason to pick this over rolling our own DOM traversal.
• Poor fit for anything needing XSD 1.1 assertions, or for high-frequency, low-latency schema validation inside a request cycle.

Integration feasibility

• Low mechanical effort: composer require, then instantiate the reader directly. The API surface is small and the object model is traversable, so a thin SchemaRegistry/XsdParser service bound as a singleton is enough to make it idiomatic in Laravel.
• Import/include resolution across namespaces is the feature that justifies the dependency — hand-rolling that correctly is weeks of work.
• Extensibility callbacks give us a hook point for custom resolvers, which is where we will need to intervene (see risk below).

Technical risk

• SSRF / remote fetch risk (highest). Schema imports and includes can reference remote URIs. Any path where an uploaded or tenant-supplied XSD reaches this parser can cause outbound requests to arbitrary hosts. Mitigation: custom resolver restricted to local disk or an allow-listed host set, plus timeouts. This is a mandatory control, not a hardening nice-to-have.
• XXE. Parsing is libxml-backed; confirm entity loading and network access are disabled in our wrapper before any user-influenced document is parsed.
• XSD spec coverage. Verify support for substitution groups, wildcards (xs:any), xs:choice nesting, and derivation/extension chains in the schemas we actually care about. Assume XSD 1.0 semantics; if a partner publishes 1.1, we need a fallback.
• Bus factor. 61 stars, effectively single-maintainer lineage, MIT. Recent release cadence (Sept 2025) is reassuring, but there is no vendor SLA. Treat as a vendored-risk dependency: pin the version, and be prepared to fork.
• Object graph handling. Parsed schemas are rich, interconnected objects; naive serialization for caching may not round-trip cleanly (circular references between types). Confirm in a spike before designing a cache around it.

Key questions

• Which concrete business driver is this for — partner SOAP integration, contract-driven codegen, or upload validation? Each implies a different risk posture.
• Do we need runtime validation or just design-time introspection? The library reads schemas; it is not itself a validating parser against instance documents.
• What is the largest schema in scope (file count, import depth, size)? This determines whether in-request parsing is even conceivable.
• Is anyone on the team fluent in XSD? Without that, the API is easy and the semantics are not.

Integration Approach

Stack fit

• Framework-agnostic PHP with ext-dom/libxml underneath; sits cleanly inside Laravel 10/11/12 on PHP 8.1+. No conflicts expected with the framework, but it will not benefit from Laravel conventions either.
• Wrap it: a SchemaRepository service (container-bound, interface-backed) that owns parsing, resolution policy, and caching. Nothing else in the codebase should touch the library's classes directly — that keeps the fork/replace option open.

Migration path

• If we are currently on ext-soap in WSDL mode: this is not a like-for-like replacement. ext-soap does transport and marshalling; this reads schema metadata. The realistic path is to keep ext-soap for calls and add this only where we need to inspect or generate from contracts.
• If we are hand-rolling DOM/XPath traversal today: this is a straightforward win — replace ad-hoc traversal with the typed object model, keep our own mapping code on top.
• If we are evaluating generated DTOs: adopt the reader together with its companion codegen rather than building a generator against the raw API.

Compatibility

• Constrain the version in composer.json and commit the lock. Verify PHP version support against our matrix and check transitive dependency overlap with the rest of the app (notably anything already pulling in libxml/DOM utilities).
• Confirm behaviour on the specific schema dialects our partners publish before committing — that is the real compatibility test, not the CI suite.

Sequencing

1. Spike (1–2 days): parse two or three real production schemas end-to-end; measure memory/time; confirm import resolution and cache serialization.
2. Wrapper + resolver: service class, allow-listed resolver, XXE hardening, structured error mapping into Laravel exceptions/logging.
3. Offline pipeline: artisan command and/or queued job that parses schemas from configured storage and writes a cached artifact; add to deploy.
4. Consumer: whichever downstream need triggered this — codegen, validation mapping, or contract introspection.
5. Operationalize: monitoring, cache invalidation on schema change, dependency pinning and a written fork contingency.

Operational Impact

Maintenance

• Ongoing cost is low in code volume but non-zero in attention: a low-traffic upstream means we should watch releases ourselves rather than rely on community noise to surface issues. Assign a named owner.
• Our wrapper is the durable asset; upstream is replaceable. Keep the adapter thin so a fork or swap is a contained change.
• Track PHP minor-version compatibility proactively — small libraries often lag on new PHP releases.

Support

• No commercial support, no SLA. Escalation path is: our wrapper workaround → upstream issue → fork. Document that path.
• Errors from deep schema constructs can be opaque; invest early in wrapping parse failures with schema name, file, and line context, or debugging will be painful.

Scaling

• Parsing is CPU- and memory-bound and does not parallelize within a single schema. Horizontal scaling helps only if parsing is in queue workers, not web requests.
• The scaling answer is cache aggressively: parse at deploy/build time, persist the normalized contract, serve requests from the cache. Treat schema parsing like a compile step.
• Very large multi-import schema sets may need chunking or per-namespace warmup; validate with real data, not synthetic fixtures.

Failure modes

• Unresolvable remote import → hard failure at parse time; must fail loudly at build/deploy, never silently at request time.
• Unsupported construct in a partner schema revision → partial or incorrect object model, which is worse than an exception. Add a smoke test that parses every known partner schema on every deploy.
• SSRF/XXE if the resolver and libxml flags are ever bypassed by a new code path — enforce through a single entry point, not convention.
• Cache staleness when a partner silently updates a schema; pair the cache with a content hash and a scheduled re-parse.
• Upstream abandonment: pinned version keeps working; the fork contingency is the exit.

Ramp-up

• API learning curve is small (a day for a competent PHP developer). The real ramp-up is XSD domain literacy — namespaces, derivation, groups, substitution — and that is measured in weeks, not days.
• Mitigate by centralizing all schema work behind the wrapper and one owner, so XSD expertise is a single point of contact rather than a team-wide requirement.