Idle Dom Laravel Package

Technical Evaluation

What the package actually is. wikimedia/idle-dom is not a Laravel package and not an application-facing library. It is a set of PHP interfaces (namespace IDLeDOM\) that model the WHATWG DOM spec — Document, Element, Node, NodeList, etc. — plus a small amount of supporting code. It deliberately contains no parser and no concrete DOM implementation. On its own it does essentially nothing at runtime; it only becomes useful when paired with an implementing library (canonically wikimedia/remex-html for HTML5 parsing) or when used to type-hint and mock DOM behavior in tests.

Architecture fit. Poor-to-neutral for a typical Laravel application. Laravel's ecosystem, and PHP generally, assumes ext-dom (DOMDocument, DOMXPath, libxml). That extension is fast, ubiquitous, and already a de facto platform requirement. Introducing IDLeDOM means introducing a second, parallel DOM abstraction with no Eloquent, HTTP, queue, or view-layer integration surface whatsoever. There is no service provider, no config file, no facade, and nothing to register in config/app.php.

Integration feasibility. Mechanically trivial: composer require wikimedia/idle-dom and you can type-hint IDLeDOM\Document. Practically, the only defensible reasons to adopt it are:

• You need a pure-PHP DOM path because you cannot guarantee ext-dom in the target runtime (rare, and usually false for Laravel — many packages require ext-dom).
• You are writing a library that must abstract over DOM implementations so consumers can inject mocks, and you want a spec-aligned contract rather than a bespoke one.
• You are already in the MediaWiki/RemexHtml family and want interface compatibility.

Absent one of those, this is an unnecessary abstraction layer.

Technical risk. Moderate, and mostly governance-shaped rather than code-shaped:

• The GitHub repository is an explicit read-only mirror; the canonical code and review live on Wikimedia Gerrit. Issues and PRs on GitHub will not be triaged. Contribution requires MediaWiki developer access.
• Packagist signals are weak (1 star, 0 listed dependents), but that understates real usage: MediaWiki core consumes this via Composer, so the code is exercised in production at scale — just not visibly on Packagist. Treat the star count as a discoverability metric, not a quality metric.
• Interface-only packages shift a failure mode into your application: a missing or mismatched implementation is a runtime error, not a compile-time one.
• Version constraint hygiene matters more than usual, because Gerrit mirrors can lag tagged releases.

Key questions for the team.

1. Do we have a concrete requirement that ext-dom cannot satisfy, or is this abstraction for its own sake?
2. If we adopt, which implementation are we binding (remex-html? a custom one?), and who owns that choice?
3. Are we consuming tagged Composer releases, or tracking mirror commits? What is our policy on Gerrit-only changelogs?
4. Is the goal testability/mocking of DOM code, and if so, would a thin in-house adapter over ext-dom be cheaper?
5. What is our support path when a bug is found — Gerrit patch, or vendor fork?

Integration Approach

Stack fit. Treat this as a low-level domain dependency inside a single service class, never as a cross-cutting concern. The correct pattern is a hexagonal one: define your own narrow port (e.g., HtmlExtractionService), implement it with either ext-dom or IDLeDOM + remex-html, and keep IDLeDOM\* type hints out of controllers, models, jobs, and anything else that leaks into the framework layer. IDLeDOM types in an Eloquent model or a queued job payload would be a design defect.

Migration path. There is nothing to migrate to — this is greenfield adoption, not a replacement for an existing Laravel subsystem. If the motivation is replacing DOMDocument usage, the migration is: (a) inventory all DOMDocument/DOMXPath call sites, (b) wrap each behind the port interface, (c) swap the implementation behind a config flag, (d) compare output on a golden corpus of real HTML. Step (d) is non-negotiable; HTML5 parsing behavior differs meaningfully between libxml and RemexHtml on malformed input, which is exactly the input real-world scrapers and sanitizers encounter.

Compatibility. No autoload or namespace collision risk — IDLeDOM uses IDLeDOM\, not DOM\, so it coexists with ext-dom. Verify the PHP constraint in composer.json against your runtime matrix before committing; the package targets modern PHP 7/8 and will not help you on legacy runtimes, which is often the very reason people reach for pure-PHP DOM in the first place. Licensing is MIT and compatible with any Laravel project. No Laravel version coupling exists, which is both a feature (nothing breaks on Laravel upgrades) and a signal (nothing is tested against Laravel either).

Sequencing.

1. Spike (1–2 days): confirm the actual requirement. Reproduce your DOM workload with ext-dom and with IDLeDOM + remex-html. Measure correctness on malformed HTML and measure throughput.
2. Decide: if the spike shows no functional gap, close the evaluation. This is the expected outcome for most Laravel teams.
3. If adopted: introduce the port interface first, with an ext-dom adapter as the default and the IDLeDOM adapter behind a flag.
4. Golden-corpus validation of the new adapter before any traffic.
5. Rollout per-endpoint or per-job, with the old path retained until metrics are clean.
6. Then consider whether the abstraction has earned its keep; if only one implementation is ever used, collapse it.

Operational Impact

Maintenance. Near-zero runtime surface: no services, no daemons, no config, no migrations, no scheduled work. The maintenance cost is entirely upstream-tracking. Budget for someone reading Gerrit or the Packagist release feed, because GitHub notifications will be silent. Pin an exact version in composer.json and upgrade deliberately; do not float on a branch alias against a mirror.

Support. This is the weakest dimension. There is no GitHub issue tracker in practice, no vendor SLA, and no Laravel community familiarity. Wikimedia's developer-access process is the support channel, which is unreasonable for a product team to depend on for routine questions. Escalation realistically means reading MediaWiki source and patching locally. A vendor fork should be assumed as the contingency, which means the license and mirror structure must permit it (MIT does; the mirror explicitly encourages forking).

Scaling. If IDLeDOM is backed by a pure-PHP implementation, expect significantly lower throughput and higher memory per document than ext-dom. PHP-userland DOM construction allocates an object per node; libxml-backed DOMDocument does not. For a request-path HTML sanitizer or a scraper processing thousands of documents per job batch, this is the deciding factor. Profile before committing. Concurrency is unaffected (no shared state, no I/O), so horizontal scaling behavior is ordinary — the cost is per-unit CPU and memory, not architectural.

Failure modes.

• Unbound implementation: an IDLeDOM type is requested but no concrete class is wired — surfaces as a container binding or type error at runtime, not at boot. Mitigate with an explicit binding and a boot-time smoke test.
• Parse-behavior divergence: output differs from ext-dom on malformed input, silently changing extraction or sanitization results. Mitigate with the golden-corpus diff in the integration plan.
• Abandoned-mirror drift: the Packagist package falls behind or ahead of Gerrit in a way that is not visible in release notes. Mitigate with pinned versions and a periodic manual review.
• Over-abstraction creep: IDLeDOM\* types propagate into application code, making the eventual removal expensive. Mitigate with an architectural rule and a static-analysis check on the namespace.
• Silent scope failure: the team adopts this expecting a parser and discovers it is interfaces only, then pulls in remex-html as an unplanned dependency. Mitigate by stating the pairing requirement explicitly in the decision record.

Ramp-up. Low for anyone who knows the DOM spec — the interface names are deliberately spec-faithful, so a frontend-adjacent developer will find it familiar. The real ramp-up cost is organizational: explaining to the team why a second DOM abstraction exists in a codebase that already has a perfectly good native one. That question will be asked repeatedly at code review unless the decision record answers it in one sentence. Given a 0.005 viability score and zero visible dependents, the default recommendation is do not adopt unless a specific, documented constraint rules out ext-dom; if such a constraint exists, adopt narrowly, behind a port, pinned and forked-ready.