Continuous integration/Phan

From MediaWiki.org
Jump to navigation Jump to search
For the security plugin built on top of phan, see phan-taint-check-plugin.

We perform static analysis of MediaWiki's PHP code base using Phan. MediaWiki core configuration for Phan is in the tests/phan directory. All MediaWiki core patches are analyzed by Phan as part of the CI infrastructure.

You might also be interested in the tutorial to add phan to a MediaWiki extension (or library).

Installing Phan[edit]

Phan requires PHP >= 7.0 to run. This is because Phan analyzes the AST that was added to PHP in version 7. It fully supports analyzing PHP 5 codebases, but the analysis must be run from PHP 7. It also requires the php-ast extension.

Getting Phan[edit]

From composer

$ composer g require phan/phan

From docker[edit]

TODO: Document the docker method

From git[edit]

$ mkdir ~/git
$ git clone https://github.com/phan/phan.git ~/git/phan
$ cd ~/git/phan
$ git checkout 1.2.4
$ composer install

You can figure out the exact version of phan you need based on looking at the "extra.phan" key in the repository's composer.json. If that isn't present, you might need to look at vendor/mediawiki/mediawiki-phan-config/composer.json.

Running Phan[edit]

From composer[edit]

$ ~/.composer/vendor/bin/phan --allow-polyfill-parser

From git[edit]

~/git/phan/phan -d . -p

  • -d . tells it to analyze the current directory
  • -p tells it to output a progress bar

Upstream Documentation[edit]

Interpreting Results[edit]

Results are in the following structure, one per line.

includes/AuthPlugin.php:165 PhanUndeclaredMethod Call to undeclared method \AuthPlugin::allowEmailChange
includes/DerivativeRequest.php:56 PhanParamSignatureMismatch Declaration of function getHeader($name, int $flags = null) should be compatible with function getHeader(string $name, int $flags = null) : array|bool|string defined in includes/WebRequest.php:1028

Suppressing Issues[edit]

Sometimes phan gets it wrong. Or the code is just so hopeless that a large refactor is needed to make the analysis line up. In these cases errors from individual lines can be suppressed with the following format:

/** @phan-suppress-next-line PhanUndeclaredMethod some text saying why it was suppressed */

See the upstream documentation

Known Problems[edit]

  • Phan cannot read /** @var Foo $bar */ annotations in the middle of functions. This is a limitation of the PHP AST. The closest workaround currently is to specify @var annotations in the method doc block.