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 support 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.

Composer
Run the following from your MediaWiki core git checkout. Note that after this is done you can only ever run composer with PHP >= 7.0.

Running Phan
Mediawiki core comes with a bash script that will run Phan with a configuration suitable for MediaWiki. This script requires an environment variable, PHAN, to be set which points 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 tests/phan/issues/issues-&lt;githash&gt; with the same content. &lt;githash&gt; refers to the commit-id of HEAD in the MediaWiki core repository. It also links tests/phan/issues/latest 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 /** @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.