Continuous integration/Phan

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

Installing Phan
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.

Dependencies
For Debian/Ubuntu users, if your system does not come with PHP 7, you can use packages from https://deb.sury.org. The repositories have co-installable packages for PHP5 and PHP7, and are what is used in the Wikimedia CI infrastructure.

Fedora users should update to Fedora 25, which comes with PHP 7. will install both the ast extension and composer (which is used in the next step).

Composer
Enter the folder which has your local MediaWiki core git checkout.

For Debian/Ubuntu users, run the following command. Note that after this is done you can only ever run composer with PHP >= 7.0.

Fedora 25+ users replace  by   in the command above.

Manual
For Debian/Ubuntu users:

Fedora 25 users replace  by   in the command above.

Running Phan
Mediawiki core comes with a bash script that will run Phan with a configuration suitable for MediaWiki. This script requires that either your Phan CLI script is included in your  environment variable, or that a   environment variable is set pointing to the Phan CLI script in the install you made above.

Running Phan will take a couple minutes (it doesn't output any progress report). After it has run it will emit all the issues it found, along with creating a file  with the same content. refers to the commit-id of HEAD in the MediaWiki core repository. It also links  to the specific issue file.

Useful CLI flags

 * -j, --processes : The number of parallel processes to run during the analysis phase. Defaults to 1.


 * -p, --progress-bar : Show progress bar

Upstream Documentation

 * Annotating Your Source Code
 * About Union Types
 * Issue Types Caught by Phan
 * Typing Parameters

Interpreting Results
Results are in the following structure, one per line. Signatures are in the form used in PHP 7. For our PHP 5 code base the types for arguments and return values are specified in the docblock.

Supressing 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:

Known Problems

 * Phan cannot read  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.
 * There's an experimental workaround at https://gerrit.wikimedia.org/r/#/c/386830/