Parsoid/So you want your extension to work with Parsoid

This page aims at gathering information about extension development with Parsoid, in the form of a Frequently Asked Questions (FAQ) list.

What's the point?
To make Parsoid the default MediaWiki wikitext engine, the dependencies to the legacy parser must be removed. This means that the Parser.php class and the parser hooks are bound to be deprecated at some point. To prepare for that, affected extensions should transition to the Parsoid API.

Is my extension affected?
An extension is affected if it either:


 * uses the Parser object
 * has a parser hook.

What do I need to do?
The following steps are documented in further section in this document; this section aims at being a quick checklist for all the necessary steps.


 * Register the extension to Parsoid
 * Create hooks for Parsoid to reproduce the functionality of the existing parser hooks
 * Refactor the code that references Parser to provide a version that uses the Parsoid extension API for the Parsoid hooks
 * Probably: add DomImpl.php stub to Phan
 * Possibly: add a dependency to Parsoid in the CI of the extension

How do I register the extension to Parsoid?
This is documented in detail here: Parsoid/Extension API. You'll need to edit extension.json to either flesh out the whole configuration there, or to refer to a class implementing the  interface. There is a small preference among the Parsoid developers for the second option, in order to be consistent with existing code bases and conventions.

How do I create hooks for Parsoid?
This is documented in detail here: Parsoid/Extension API and in Parsoid/Extension API. You'll need classes that extend ' or ' depending on the hooks you want to implement.

How do I refactor my uses of the Parser class?
The hooks provide an access to a which contains entry points into the Parsoid API. If the needs of your extension are not met by this API, please contact with the Content Transform team by opening a Phabricator ticket so that we can discuss solutions.

Phan complains in my CI about PhanUndeclaredTypeReturnType - how do I fix that?
When adding Parsoid hooks such as sourceToDom, phan may complain about. This is caused by a conditional class aliasing of DOM-related classes in Parsoid. Copying  from Parsoid to the extension root should fix the issue. This should not be necessary anymore if/when the class aliasing in parsoid/DomImpl.php becomes unconditional.

My CI is complaining about something else, it seems it can't find Parsoid code
Have a look at Parsoid, it might help.

What about testing?
During the continuous integration of build of an extension,  files in   get added to the list of parser tests to run. These will also be run against Parsoid under two conditions: (a) it contains the  flag, and (b) the   class is available. (a) is handled in the test file by having its header be !! options version=2 parsoid-compatible !! end (b), as of the writing of this document (January 2022), requires the addition of  as a dependency to the extension in the CI configuration - an example of this configuration is provided in. Note that this will imply that the tests are run against the tip of the Parsoid branch corresponding to the extension branch (by default, master) and not against the version of Parsoid referenced by MediaWiki core.

Do you have a minimal example for an extension that was easy to adapt?
Yes, yes we do - have a look at.