Open main menu

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

Links

  1. https://github.com/wikimedia/mediawiki-tools-phan
  2. https://github.com/phan/phan
  3. https://www.mediawiki.org/wiki/Continuous_integration/Entry_points
  4. https://www.mediawiki.org/wiki/Continuous_integration/Phan
  5. https://www.mediawiki.org/wiki/Best_practices_for_extensions#File_structure
  6. https://github.com/nikic/php-ast
  7. https://github.com/phan/phan/wiki/Getting-Started
  8. https://github.com/phan/phan/blob/v5/internal/CLI-HELP.md

Static Analysis of MediaWiki

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

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

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

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

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

Other Static Analysis tools for PHP

PHPStan

https://phpstan.org/

Psalm

https://psalm.dev/