Htmlpagedom Laravel Package

Product Decisions This Supports

• Feature enablement: Unlocks a whole class of "read HTML → change HTML → emit HTML" features that Symfony's Crawler alone can't do cleanly: rewriting links/UTMs in outbound emails and notifications, post-processing rendered Blade output, injecting affiliate or tracking attributes into third-party content, converting legacy markup to responsive/AMP-friendly markup, and cleaning up HTML pulled in from feeds, CMS imports, or partner APIs.
• Roadmap framing: Treat this as an enabler, not a product. It upgrades an existing read-only capability (Crawler's CSS-selector querying) into a read-write editing capability, which is typically the missing piece between "we can scrape/inspect HTML" and "we can ship an HTML transformation feature."
• Build vs. buy: Strong buy/adopt case. Rebuilding jQuery-style mutation on top of DOMDocument means weeks of work plus a permanent bug tail around malformed markup, HTML5 parsing quirks, encoding, and node insertion edge cases. This package is a thin, MIT-licensed wrapper that delegates the hard part to Symfony's Crawler and an HTML5 parser — the cost of adoption is a composer require and a short spike.
• Scope/effort sizing: The API surface is small and familiar to anyone who has used jQuery (filter, attr, append, prepend, remove, html), which keeps estimation honest: an engineer can prototype a working transformation in hours, and the PM can demo something concrete in a sprint rather than a quarter.
• Lock-in decision: Because the value is a thin ergonomic layer over a first-party Symfony component, the exit cost is low. v3.1.0 tracks the current Symfony line (Symfony 8 support added), which is the signal we want from a wrapper library: it stays aligned with the upstream component we already depend on. That makes it a safe "yes" for a spike and a defensible "yes" for production behind a small internal adapter, without needing an architecture review.
• Platform baseline decision: v3.1.0 raises the minimum PHP to 8.1. That is only a blocker if any service that would host this work still runs PHP 8.0 or older — check the target app's composer.json before committing, because adopting this package effectively pins that service to a supported PHP floor. For any app already on a maintained PHP version, this is a non-event and arguably a benefit (it removes ambiguity about which PHP versions the library is tested against).
• Risk signal to weigh, not ignore: 337 stars and effectively no declared dependents means a small community and a single-maintainer bus factor. The v3.1.0 release is a positive maintenance signal — the library is not abandoned and upstream compatibility work is being merged — but one release does not change the structural concentration risk. That remains acceptable for a convenience layer, not acceptable as a load-bearing dependency for a security-sensitive pipeline — which informs where in the codebase we allow it.
• Laravel-specific note: This is framework-agnostic and drops into a Laravel app cleanly, but Laravel has no first-party equivalent — so this is genuinely filling a gap rather than duplicating a framework feature we already pay for. The Symfony 8 compatibility bump also future-proofs it against the Symfony components that Laravel pulls in transitively, reducing the odds of a constraint conflict during a future framework upgrade.

When to Consider This Package

Adopt when most of these are true:

• You already use — or are willing to use — symfony/dom-crawler; the team's mental model already matches CSS selectors rather than XPath.
• The target application is on PHP 8.1+ (v3.1.0's floor) and on a Symfony component line this release supports — the library now spans the current Symfony 8 generation as well as earlier lines, so recent Laravel/Symfony upgrades are not a blocker.
• The requirement involves modification, not just extraction: attribute rewrites, node insertion/removal/wrapping, reordering, or serializing a changed document back out.
• Your inputs are real-world, messy, HTML5-ish documents where a tolerant HTML5 parser beats DOMDocument's libxml quirks.
• Documents comfortably fit in memory (typical web pages, emails, fragments, reports) — not multi-gigabyte exports.
• The alternative on the table is regex string-munging HTML, which is the outcome you most want to avoid.

Look elsewhere when:

• You need rendered DOM. If the markup only exists after JavaScript runs, this is the wrong layer — reach for a headless browser (Browsershot/Puppeteer) instead.
• You need a security boundary. This is not a sanitizer. For untrusted user HTML, use a dedicated sanitizer (Symfony HtmlSanitizer or HTML Purifier) and treat this as a pre/post-processing step at most.
• You need templating. If the goal is composing pages from data, Blade/Twig is the answer; this is for post-hoc surgery on HTML you already have.
• Performance is on the hot path. Per-page parsing and object overhead in a tight loop (thousands of documents per request/batch) warrants benchmarking against raw DOMDocument/libxml first.
• You need full DOM spec fidelity or streaming. Very large or streamed documents point to XMLReader or direct libxml work.
• You are stuck below PHP 8.1. v3.1.0 will not install; you would have to pin an older release and accept that you are off the maintained track — in which case upgrade the runtime first, not the dependency.
• Procurement requires vendor assurance. Zero declared dependents plus a single maintainer is a governance flag; either accept it for non-critical paths or wrap it behind an internal interface so replacement is a one-file change.

How to Pitch It (Stakeholders)

For executives: This is a small, MIT-licensed PHP library that lets our backend edit HTML, not just read it. It's a thin extension to Symfony's Crawler — a component we already trust — so it's low-cost, low-risk, and easy to walk away from. It is actively maintained: the newest release adds support for the current Symfony generation, so it isn't going stale under us. It's the cheapest credible path to shipping several backlog items that all share the same shape: take HTML from somewhere (our templates, a partner feed, a CMS export, an email), make targeted changes, and send it onward. Recommendation: approve a short engineering spike; if it holds up, it becomes the standard tool for HTML transformation work and retires a category of fragile regex hacks.

For engineering: It's composer require wa72/htmlpagedom, and you get jQuery-style ergonomics (filter('.x')->attr('href', $new)->append(...)) on top of the Crawler you already know, with proper HTML5 parsing and serialization. Note the v3.1.0 constraints before you start: minimum PHP 8.1 and Symfony 8 support, so verify the target service's composer constraints resolve cleanly — the spike's first task is a dry-run install, not code. It removes the excuse to regex HTML. Two caveats we're designing around: keep it off the security boundary (pair it with a real sanitizer for untrusted input), and put a thin internal wrapper around it so the single-maintainer risk is a swap, not a rewrite. We'll benchmark on representative payloads before it goes anywhere near a high-volume path.