Continuous integration/Tutorials/Add phan to a MediaWiki extension

This is a tutorial to set up phan for a MediaWiki extension or composer library. We'll look at the ParserMigration extension specifically.

Setup
You'll need to install PHP 7.0, and (optionally) the ast extension. On Debian/Ubuntu  should do it. If you don't install the ast extension, you'll need to use  on your phan command line, and there will be some (very minor) limitations on where certain annotations will be recognized. phan has some other advice for this part too.

If you'll be running phan directly from composer (this means your composer.json must require php >= 7.0 and the jenkins configuration should mention something like composer-test-package-php72-or-later) then installing phan is simple: Otherwise, if installing from git, clone phan to a directory, and set it up.

Adding phan configuration
I'm going to assume that you installed MediaWiki core to  and ParserMigration to. Make sure you've fully set up MediaWiki core and installed all the composer dependencies.

First, let's set up the default configuration:

We're now ready to try to run phan. If you're going to run from composer, then add the following scripts to your  file: And you can run phan with   or.

If you installed from git, then invoke phan from your installed copy:

You should see a progress bar, and it might take a minute to finish running. It looks like we have some errors: includes/Hooks.php:11 PhanUndeclaredTypeParameter Parameter of undeclared type \MediaWiki\ParserMigration\User includes/MigrationEditPage.php:31 PhanDeprecatedProperty Reference to deprecated property \MediaWiki\ParserMigration\MigrationEditPage::mTitle defined at ./../../includes/EditPage.php:230 includes/MigrationEditPage.php:34 PhanDeprecatedProperty Reference to deprecated property \MediaWiki\ParserMigration\MigrationEditPage::mTitle defined at ./../../includes/EditPage.php:230

Looking at the first one, the namespace for User on the  documentation comment is wrong. Let's fix it (example).

For the second one,  is marked as deprecated for public use, to it's OK that we're using it in MigrationEditPage. You can suppress that warning on each particular line (phan docs) or you can suppress it throughout the extension. Let's suppress that warning for now by adding it to  in config.php.

We can do something like:

For whatever extension you're working on, there will likely be other errors. You'll have to use some judgement on whether the issue needs fixing or can be suppressed.

Let's run phan again with the same command, and there should be no errors left! You can commit your work and submit it to Gerrit.

If you added phan directly to your composer.json's "test" script, then you don't need to do anything special at this point (other than perhaps to make sure CI is not running tests on php versions <7.0).

If you're keeping compatibility with HHVM and php<7.0 and didn't add phan to your composer.json, then on your Gerrit patch, comment  and it'll run phan as part of the CI system to make sure it will pass when enabled for all patches. You can then send a patch to the  repository to run phan for the repository on a per-commit basis. See for an example.

Advanced
If your extension depends upon other extensions, you can add those extensions to  and. Here's an example:

Migrating from phan 0.8.0
Before February 2019, Wikimedia CI was hardcoded to using phan 0.8.0, and had developed significant workarounds that are no longer needed. To migrate to newer phan, do the following:


 * 1) Move   to , and edit to fix the relative path to the vendor directory.
 * 2) * Note that any references to other directories like extension dependencies that are in the form of  should be switched to   (removing the leading  ).
 * 3) Upgrade mediawiki/mediawiki-phan-config to 0.4.0 in composer.json
 * 4) Switch from   on individual lines to using upstream's new  :  (upstream docs)
 * 5) * Ignore Issues starting with, because the plugin is still using 0.8.0 (T216974)
 * 6) Re-enable any disabled sniffs to see if false positives and bugs were fixed in the new upstream version.
 * 7) Fix any other new errors that phan finds
 * 8) Remove   from   since that file is no longer created