Come up with a migration strategy from DOMDocument to Dodo.
Ideally we'd be able to subclass the DOMDocument so that a Dodo document could be passed around transparently. But in actual practice native classes (DOMDocument is a C binding of a libxml object) don't really play nicely that way.
Especially for generic libraries, but also for code during a transition period, it would be better to allow use of "any" standards-compliant DOM library. (But note that there are specific PHP bugs in the library that you might need to be compatible with, so there might be a "quirks mode" you'd have to put Dodo into to make this work.)
So do we:
- Declare all types as unions, eg no PHP type hinting and tell phan everything is a \DOMElement|\Wikimedia\Dodo\Element
- Use typedefs eg class_alias (https://www.php.net/manual/en/function.class-alias.php). I don't know if this lets you overwrite "built-in" classes like \DOMDocument so you'd probably have to update all your types in your library to (say) \GenericDOM\Document and then each DOM library would provide a set of class_alias statements to let you use their library. But you still couldn't interoperate between libraries (maybe that's ok).
- Define an interface superclass (like \GenericDOM\Document). Maybe convince upstream that \DOMDocument should extend this same superclass.
- Strip all PHP type hints, and just lie to phan about what types you're using. Eg tell phan that you're always using \DOMDocument even though you might be passing a Dodo document, or vice versa.
This isn't a blocking task until we start running Parsoid with Dodo -- and maybe not even then, we can always do some evil hack just for Parsoid. But we should have a reasonable strategy implemented here before starting to port other parts of the WMF codebase to Dodo.