Overview

This package sits in a deliberately narrow space: it gives us a standards-shaped DOM in PHP, but it does not try to become a framework, router, or templating language.

That is useful when we want to work with HTML or XML documents directly and keep the code close to the web standards many of us already know from the browser.

What to expect from the API

Most of the public API mirrors familiar DOM concepts:

• documents such as HTMLDocument and XMLDocument
• generic nodes such as Element, Text, Comment, and DocumentFragment
• traversal helpers such as querySelector, children, closest, and parentElement
• browser-like collection types such as HTMLCollection, NodeList, DOMTokenList, and DOMStringMap

For details of what those APIs do, MDN remains the best reference:

• Document on MDN
• Element on MDN
• HTMLElement on MDN
• Node on MDN

What this documentation covers instead

The more useful questions for this repository are usually integration questions rather than API catalogue questions:

• When should we construct a document manually?
• What gets added automatically to an HTMLDocument?
• Which collections are live?
• What happens when we call browser APIs that only make sense client-side?
• How should this fit into a WebEngine application?
• When should we stop manipulating nodes directly and use DomTemplate instead?

Those are the questions covered in this guide.

DOM versus DomTemplate

It is perfectly valid to use this library directly:

$price = $document->querySelector(".price");
$price->innerText = "£14.99";

But if the application is mainly binding data into HTML, repeating lists, expanding components, or composing page layouts, DOM manipulation can become too tightly coupled to the exact shape of the markup.

That is the gap filled by DomTemplate: the HTML says what can change, and PHP supplies the data. In WebEngine, DomTemplate is provided by default for precisely that reason.

WebEngine context

This library is also a foundational part of WebEngine.

• WebEngine provides a pre-constructed HTMLDocument for the current page.
• The framework handles the page lifecycle around that document.
• DomTemplate is included by default, so many common page updates can happen declaratively without low-level DOM code.

If you are writing page logic in WebEngine, you will usually work on an existing document rather than instantiate one from scratch, and it would make sense to use DomTemplate's bind attributes rather than manipulating the DOM directly yourself.

PHP 8.4's native HTMLDocument

Since PHP 8.4, a native HTMLDocument class has shipped which enhances the functionality of the old DOMDocument class, but still misses a lot of specification in terms of properties and functions. Discussions are being made about whether this native class can be used within this repository, to increase efficiency of code execution and standardise further, but the native class is declared final so none of PHP.GT/Dom enhancements can be applied.

That means that for now, the extension of the original DOMDocument will continue into the forseable future, but it's worth knowing about PHP's native HTMLDocument class in case you don't need any of this library's helpers.

A small subset of what PHP.GT/Dom has that PHP's native HTMLDocument doesn't: document.contentType, embeds, forms, images, links, scripts, getElementsByName, innerText, dataset, hidden, title, tabIndex, RadioNodeList(https://developer.mozilla.org/en-US/docs/Web/API/RadioNodeList), and all properties are static (changing the document does not update a referenced NodeList's contents, whereas PHP.GT/Dom's document does).

---

Next, we will put together the smallest useful setup in Getting started.