Alias Parsoid DOM nodes to PHP DOM implementation
commitf856992ad95526439aa59cdb882fe5e6efcf3908
authorC. Scott Ananian <cscott@cscott.net>
Fri, 16 Feb 2024 20:14:08 +0000 (16 15:14 -0500)
committerC. Scott Ananian <cscott@cscott.net>
Wed, 22 May 2024 14:35:02 +0000 (22 10:35 -0400)
tree6a60cd2e9fb9f78d9bf61a5631620f91c0d4a974
parent189d41676f27744d650d95caf2334e915a04dabe
Alias Parsoid DOM nodes to PHP DOM implementation

Parsoid abstracts the specific DOM implementation it is using, in
practice (currently) using subclasses of the built-in \DOMDocument
classes using the \DOMDocument::registerNodeClass() mechanism.
Parsoid's own phan configuration uses stubs for its abstract DOM
classes to encourage the use of "standard" DOM methods -- but core
doesn't use Parsoid's phan configuration and doesn't really understand
the way that ::registerNodeClass() works and so get confused by code
such as:

   $el = $document->createElement('div');

In actual practice this is a Wikimedia\Parsoid\DOM\Document (a
subclass of \DOMDocument) which creates a
Wikimedia\Parsoid\DOM\Element (a subclass of \DOMElement) via the
::registerNodeClass() mechanism, but phan sees only the base
\DOMDocument::createElement() signature and assumes this creates a
\DOMElement *not* a Wikimedia\Parsoid\DOM\Element.  If you do
"element-y" things on this, phan has no complaints, but if you pass
this back to a Parsoid method which expects the abstract
Wikimedia\Parsoid\DOM\Element type then phan (spuriously) complains.
This type error can be hard to understand.

Workaround this issue by simply aliasing Parsoid's abstract DOM types
to the built-in \DOMDocument etc types.  The alternative would be to
use Parsoid's stubs, but it seems cleaner (for now) to avoid reaching
into

  vendor/wikimedia/parsoid/.phan/stubs

to get them.

Change-Id: I90b33c5d65bde1582be9a452a144808b6d53d914
.phan/config.php
.phan/stubs/DomImpl.php [new file with mode: 0644]
includes/OutputTransform/ContentDOMTransformStage.php
includes/OutputTransform/Stages/HandleParsoidSectionLinks.php