Xml Iterator Laravel Package

Technical Evaluation

Architecture fit. halilim/xml-iterator is a framework-agnostic, single-purpose library. It wraps PHP's XMLReader (libxml) in an Iterator that yields each matched node as an array or object, giving us streaming semantics without loading the full document into memory. It is not a Laravel package: there is no service provider, config file, facade, or published conventions. Architecturally it belongs in the infrastructure layer behind a domain-owned interface (e.g. FeedReader), not scattered through controllers or models. Best-fit use cases are large-file ingestion: supplier/catalog feeds, sitemaps, bank/EDI-style exports, and third-party bulk APIs delivered as XML.

Integration feasibility. Low. composer require halilim/xml-iterator plus PSR-4 autoloading is the entire install. Runtime requirements are ext-xmlreader (bundled with libxml, enabled on most builds) and ext-simplexml if node expansion is used. There is no version conflict with the framework, no bootstrapping cost, and it composes cleanly inside a queued job or artisan command. A proof of concept against one production-sized file should take under a day.

Technical risk.

• Bus factor / maturity. ~19 stars, a single maintainer, and no evident security policy or LTS commitment. Recent release activity is a positive signal but not a guarantee.
• Parsing attack surface. XML is hostile input by nature. We must explicitly verify XXE and entity-expansion behaviour (network access disabled, external entities off) rather than assume libxml defaults protect us.
• Semantics drift. Node-to-array conversion is lossy by design: attributes, repeated siblings, mixed content, and namespaces are flattened in ways that may not match our current SimpleXMLElement assumptions.
• Silent empty results. A namespace or node-name mismatch yields zero iterations without error — a classic source of "the import ran successfully and imported nothing."

Key questions for the maintainer / spike.

1. What is the tested PHP version matrix, and does it support PHP 8.3/8.4 and Laravel 11/12?
2. How are XMLReader options exposed, and can we force LIBXML_NONET and disable entity substitution globally?
3. Does it support namespace-aware node selection, or only local names?
4. Can it open stream wrappers (S3, php://temp, gzipped files) or only local paths?
5. What is the error contract on malformed XML mid-stream — exception, false, or partial iteration?
6. How are attributes and nested repeated elements represented in the array output?
7. Is there a stated support window or deprecation policy?

Integration Approach

Stack fit. Treat it as a low-level utility: one thin adapter class per feed format, implementing an internal interface, returning typed DTOs or arrays. Keep the package namespace confined to app/Infrastructure/Xml/ (or equivalent) so the rest of the codebase never imports it directly. This preserves the option to swap in prewk/xml-string-streamer, a hand-rolled XMLReader loop, or a SaaS parser later.

Migration path. For any existing simplexml_load_file / DOMDocument code, migrate incrementally:

1. Introduce the adapter interface and have the legacy implementation satisfy it first — no behaviour change.
2. Add the iterator-backed implementation side by side.
3. Run both against a golden corpus of real files and diff outputs.
4. Cut over per feed, keeping the legacy path behind a config flag for one release cycle. This keeps the blast radius to one feed at a time and gives a clean rollback.

Compatibility. No framework coupling means no upgrade friction from Laravel majors, but it also means no framework-level safety net: no assertXml test helpers, no Http-style fakes, no container bindings. Ensure the deploy image (including any FPM/queue/CI containers) has ext-xmlreader; this is the single most common "works locally, fails in prod" cause for this class of library. Pin a caret constraint in composer.json and commit the lock file.

Sequencing.

1. Spike (1–2 days): parse three representative production files; measure peak memory, wall time, and output fidelity versus the current parser.
2. Harden: lock down libxml options, add input-size and node-count guards, define the malformed-XML policy.
3. Wrap: adapter interface, DTO mapping, unit tests with fixture files including adversarial inputs.
4. Integrate: move into a queued job with chunked persistence and idempotent upserts.
5. Observe: structured logs for bytes read, nodes yielded, records persisted, and duration.
6. Roll out: behind a feature flag, feed by feed, with the legacy parser retained as fallback.

Operational Impact

Maintenance. Small, stable surface area — the public API is a handful of methods, so upgrade churn should be minimal. The real maintenance obligation is ours: version pinning, composer audit in CI, and a documented contingency plan for adoption/abandonment. Budget a periodic review of the upstream repository rather than continuous upkeep.

Support. Community-only via GitHub issues; no vendor SLA, no Laravel-specific documentation, no Stack Overflow corpus. Assume the team is self-supporting and write internal runbook documentation at integration time — this is the single highest-leverage operational investment for a package this small.

Scaling. This is the package's core strength: memory stays roughly flat regardless of document size, so multi-gigabyte feeds become feasible on ordinary workers. Scale-out is horizontal via queue workers; throughput is CPU-bound by per-node conversion, so expect to tune batch sizes, job timeouts, and worker concurrency rather than memory limits. Watch for the pathological case where one node is very large (deeply nested or a single massive record) — the constant-memory guarantee is per-node, not absolute.

Failure modes to instrument for.

• Malformed XML partway through a stream → partial import. Mitigate with checkpointed, idempotent upserts keyed on a stable business ID.
• Silent zero-result parses from namespace or node-name mismatches → assert an expected minimum node count and alert on deviation.
• Missing ext-xmlreader in a container or host → fail fast at deploy time with a health check.
• Encoding issues (UTF-16, BOMs, mixed encodings) → validate and normalise on ingest.
• Worker timeout on very large files → chunk by node count, not just by time, and persist progress.
• Entity-expansion / XXE payloads → reject or sanitise before parsing; never trust a partner feed.

Ramp-up. The library itself is learnable in hours. The real ramp-up is XMLReader semantics — namespaces, cursor position, expansion behaviour, and error handling — plus the domain's mapping rules. Estimate one developer-day for a mid-level engineer to be productive and two to three days to be genuinely confident with adversarial inputs. Because there are no framework conventions to lean on, pair the adoption with an internal README covering the adapter contract, security settings, and the golden-corpus test suite.