Html5 Laravel Package

Product Decisions This Supports

• Build vs. buy (buy): Any feature that requires reading or rewriting HTML in PHP should consume this library rather than hand-rolled regex or string manipulation. It converts an "engineering research project" into a Composer line item.
• Content ingestion and normalization: CMS migrations, WYSIWYG output cleanup, cross-format conversion (HTML → DOM → HTML, HTML → PDF/email templates), and reconciling third-party HTML from partners or legacy systems.
• Web scraping / aggregation features: Turning fetched pages into traversable DOMDocument trees for downstream extraction, enrichment, or deduplication.
• Email and PDF rendering pipelines: Serializing DOM trees back to standards-compliant HTML5 so template engines and renderers (wkhtmltopdf, headless browsers, email clients) receive predictable markup.
• Security and trust boundaries: Normalizing untrusted HTML before storage or display; pairing with a sanitizer to control what survives the parse/serialize round trip.
• Roadmap leverage: A low-cost enabling component for roadmap items (importers, integrations, reporting exports) that would otherwise each require bespoke parsing code.

When to Consider This Package

Consider adopting when all of the following are true:

• The stack is PHP 7.4+ and Composer-managed.
• You need to parse real-world, malformed HTML (not well-formed XML) into a traversable tree, and/or serialize a DOM back to spec-shaped HTML5.
• You want the output to be a native DOMDocument so existing DOM/XPath tooling, Symfony DomCrawler, or QueryPath can operate on it.
• You value a mature, widely deployed dependency (5M+ downloads, sustained stability, MIT-style licensing) over a bespoke parser.
• Your requirement is structure, not validation or rendering — you do not need to enforce spec conformance or execute scripts/CSS.

Look elsewhere (or supplement) when:

• You need a validating parser — this one corrects some HTML but does not verify conformance.
• You need to pause/mutate mid-parse — the parser is not re-entrant.
• Your primary need is CSS-selector querying — use Symfony DomCrawler (which itself builds on this library) rather than calling the low-level API directly.
• You're parsing XML or strict feeds — use a dedicated XML parser; HTML5 namespace semantics differ from XML.
• You need JavaScript/CSS execution or visual rendering — this is a server-side parser, not a browser engine.
• You're outside PHP — pick the ecosystem equivalent (html5lib, jsdom, BeautifulSoup) rather than bridging.

How to Pitch It (Stakeholders)

For executives: We need reliable HTML handling across several planned features (content import, email/PDF output, partner HTML ingestion). Rather than funding custom parsing code, we can adopt a mature open-source PHP library that is already used at scale — over five million downloads, a stable release cadence, and permissive licensing. It's low-risk, low-cost foundational infrastructure: it removes a recurring class of bugs and unblocks roadmap work without adding a vendor contract.

For engineering: This is the de facto HTML5 parser for PHP — spec-shaped tokenizer/serializer, DOMDocument output, SAX-style event API when we need custom traversal, and options for namespaces and entity encoding. It slots into Composer, plays well with Symfony DomCrawler and XPath, and is battle-tested in production. Trade-offs to note: it's non-validating, non-re-entrant, and not a rendering engine — so we pair it with a sanitizer for untrusted input and keep XML parsing separate. Net: we delete bespoke regex parsing, standardize on one parsing path, and inherit a well-understood maintenance profile.