Continuous integration/Tutorials/Add phan to a MediaWiki extension

From MediaWiki.org
Jump to navigation Jump to search

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

Setup[edit]

You'll need to install PHP 7.0, and the ast extension. On Debian/Ubuntu sudo apt-get install php-cli php-ast should do it. phan has some other advice for this part too.

We'll clone phan to a directory, and set it up.

$ cd ~/projects # Pick any directory you want
$ git clone https://github.com/phan/phan
$ cd phan
$ git checkout 1.2.4
$ composer install --no-dev
$ export PHAN=/home/km/projects/phan/phan # Wherever you installed phan to

Preparing your extension[edit]

Your extension must follow the best practices file structure, since the default phan configuration will only look in those directories for PHP code.

Adding phan configuration[edit]

I'm going to assume that you installed MediaWiki core to ~/projects/mediawiki and ParserMigration to ~/projects/mediawiki/extensions/ParserMigration. Make sure you've fully set up MediaWiki core and installed all the composer dependencies.

First, let's set up the default configuration:

$ cd ~/projects/mediawiki/extensions/ParserMigration
$ composer require --dev mediawiki/mediawiki-phan-config:0.5.0
$ mkdir -p .phan
$ echo "<?php" >> .phan/config.php
$ echo "return require __DIR__ . '/../vendor/mediawiki/mediawiki-phan-config/src/config.php';" >> .phan/config.php

We're now ready to try to run phan:

$ cd ~/projects/mediawiki/extensions/ParserMigration
$ /home/km/projects/phan/phan -d . -p

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 Hooks::onGetPreferences() documentation comment is wrong. Let's fix it (example).

For the second one, EditPage::$mTitle 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 suppress_issue_types in config.php.

We can do something like:

<?php
$cfg = require __DIR__ . '/../vendor/mediawiki/mediawiki-phan-config/src/config.php';

$cfg['suppress_issue_types'] = array_merge( $cfg['suppress_issue_types'], [
	// MigrationEditPage::$mTitle is a false-positive
	'PhanDeprecatedProperty',
] );

return $cfg;

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.

On your Gerrit patch, comment check experimental 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 integration/config repository to run phan for the repository on a per-commit basis. See [1] for an example.

Advanced[edit]

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

$cfg['directory_list'] = array_merge(
	$cfg['directory_list'],
	[
		'../../extensions/CheckUser',
	]
);

$cfg['exclude_analysis_directory_list'] = array_merge(
	$cfg['exclude_analysis_directory_list'],
	[
		'../../extensions/CheckUser',
	]
);

Stubs[edit]

If you don't want to require having the dependency checked out while running phan, you can also use stubs. Stubs are a copy of the class/function structure, with any necessary documentation blocks, but none of the implementation code. You can see an example of this in the MassMessage extension. The downside to using stubs is that if the dependency changes, you also need to update the stub for phan to know of the change.

Stub files should be placed in .phan/stubs/.

The upstream documentation about stubs may also be useful.

Migrating from phan 0.8.0[edit]

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 tests/phan/config.php to .phan/config.php, and edit to fix the relative path to the vendor directory.
    • Note that any references to other directories like extension dependencies that are in the form of ./../../extensions/CheckUser should be switched to ../../extensions/CheckUser (removing the leading ./).
  2. Upgrade mediawiki/mediawiki-phan-config to 0.5.0 in composer.json
  3. Switch from @suppress on individual lines to using upstream's new @phan-suppress-next-line: (upstream docs)
    • Ignore Issues starting with SecurityCheck, because the plugin is still using 0.8.0 (T216974)
  4. Re-enable any disabled sniffs to see if false positives and bugs were fixed in the new upstream version.
  5. Fix any other new errors that phan finds
  6. Remove tests/phan/issues from .gitignore since that file is no longer created