Testing
Testing is software development.
Software development is writing code. Testing makes sure the code actually works, so in a nutshell: Testing is software development :-)
Phan is a static analyzer for PHP. Phan project on GitHub It will help you write better PHP code. You'll need the Abstract Syntax Tree PHP extension. You can read a tutorial for how to get Phan working in your project
The MediaWiki project uses Phan. See the article Continuous_integration/Phan
Contents
Links[edit | edit source]
- https://github.com/wikimedia/mediawiki-tools-phan
- https://github.com/phan/phan
- https://www.mediawiki.org/wiki/Continuous_integration/Entry_points
- https://www.mediawiki.org/wiki/Continuous_integration/Phan
- https://www.mediawiki.org/wiki/Best_practices_for_extensions#File_structure
- https://github.com/nikic/php-ast
- https://github.com/phan/phan/wiki/Getting-Started
- https://github.com/phan/phan/blob/v5/internal/CLI-HELP.md
Static Analysis of MediaWiki[edit | edit source]
For some current analysis see https://doc.wikimedia.org/mediawiki-core/master/phpmetrics/complexity.html
The on-wiki documentation and even the upstream projects do not exactly provide a usable guide for MediaWiki extension developers to actually use Phan. If you download MediaWiki and composer update (to get dev dependencies) and also install PHP-AST, then you should be able to run composer phan or ./vendor/bin/phan -p . But, that analyzes the entire MediaWiki codebase, and does not analyze your extension (unless you specifically add a proper .phan/config.php file to your extension).
Mark Hershberger provides an example of what that might look like in his CommentStreams configuration
<?php
$cfg = require __DIR__ . '/../vendor/mediawiki/mediawiki-phan-config/src/config.php';
$extensions = [ "Echo", "SocialProfile" ];
// Assume this extension exists in a directory with a bunch of other extensions that may, or may not be, $IP/extensions
$extDir = realpath( __DIR__ . "/../.." );
$dirList = array_filter(
array_map( fn ( $dir ): string => "$extDir/$dir", $extensions ),
fn ( $dir ): bool => is_dir( $dir )
);
$cfg['directory_list'] = array_merge( $cfg['directory_list'] ?? [], $dirList );
$cfg['exclude_analysis_directory_list'] = array_merge(
$cfg['exclude_analysis_directory_list'] ?? [], $dirList
);
$cfg['suppress_issue_types'][] = 'PhanUndeclaredConstant';
return $cfg;
The more traditional form of that[1] is
$cfg = require __DIR__ . '/../vendor/mediawiki/mediawiki-phan-config/src/config.php';
$cfg['directory_list'] = array_merge(
$cfg['directory_list'],
[
'../../extensions/Echo',
'../../extensions/SocialProfile',
]
);
$cfg['exclude_analysis_directory_list'] = array_merge(
$cfg['exclude_analysis_directory_list'],
[
'../../extensions/Echo',
'../../extensions/SocialProfile',
]
);
return $cfg;
But why is the normal pattern to include directories and exclude those same directories? The answer seems to be that you include 'dependencies' for class definition, but do not warn about issues outside the limits of your own extension.
The bigger (unanswered) question is what does mediawiki-phan-config do? What is the compiled and complete configuration that you are "running" against your codebase?
Plugins[edit | edit source]
Phan ha a ton of plugins - but they don't seem to be used in the MediaWiki configuration. Or are they? It's not obvious to me yet.
https://github.com/phan/phan/tree/v5/.phan/plugins#2-general-use-plugins
The writing plugins guide also describes how they work.
Check code for compatibility with a particular PHP version[edit | edit source]
One major reason I wanted to use phan was to upgrade a whole codebase, and check its compatibility with an upgraded PHP (moving from 7.4 to 8.1). There is at least one caveat to doing this: You should be running php 8.1 in order to check code for compatibility with 8.1 You can use phan with the config setting of target_php_version[2]
Phan with VSCode[edit | edit source]
https://github.com/phan/phan/wiki/Editor-Support supposed to just work (with the plugin). But after I installed the plugin, it was not producing any hint of working or any errors.
Phan checks[edit | edit source]
There are over 1,000 things that phan tests its own code against
https://github.com/phan/phan/tree/v5/tests
https://github.com/phan/phan/tree/v5/tests/files/src
