Continuous integration/Phan

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 .phan directory. All MediaWiki core patches are analyzed by Phan as part of the CI infrastructure, and the same goes for many extensions.

Installing Phan

Phan requires PHP >= 7.2 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. The php-ast extension is also strongly recommended. You can use phan without it (as long as you pass the --allow-polyfill-parser option), but it could be slower.

Getting Phan

We pull phan via composer. If your repo already requires mediawiki/mediawiki-phan-config, all you have to do is run composer update to install phan. Otherwise, you should run composer require --dev mediawiki/mediawiki-phan-config first.

Running Phan

Simply use vendor/bin/phan -d . -p

-d . tells it to analyze the current directory
-p tells it to output a progress bar. Alternatively, you may use --long-progress-bar to get a progress bar more suitable for e.g. CI logs.

Web demo

A web demo is available. Note, however, that it's usually useful only if you want to analyze a small piece of code.

Upstream Documentation

Interpreting Results

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

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.

Or you can suppress particular error types from an entire repo by modifying the

suppress_issue_types

array in your phan config.php file.[1]

Known Problems

Phan cannot read /** @var Foo $bar */ annotations in the middle of functions. This is a limitation of the PHP AST, and it likely won't change in the near future. The closest workaround currently is to specify @var annotations in the method doc block.
- You can also use the ugly-but-it-works string literal version: '@phar-var Foo $bar'; see line 302 in this commit for an example.