Mediawiki Phan Config Laravel Package

Getting Started

Begin by installing the package in your MediaWiki extension or skin project:

composer require --dev mediawiki/mediawiki-phan-config

Create a phan.php at the project root and include the appropriate base config (config.php for MediaWiki code, config-library.php for standalone libraries):

<?php
return require __DIR__ . '/vendor/mediawiki/mediawiki-phan-config/config.php';

Run Phan immediately to catch issues:

vendor/bin/phan

Refer to Phan CI docs for GitHub Actions/Jenkins integration.

Implementation Patterns

• Enforce consistency: Use config.php across all MediaWiki extensions/skins to unify static analysis—ensuring uniform adherence to MediaWiki coding standards, taint analysis, and deprecation coverage.
• Extend minimally: Override only critical settings (e.g., $cfg['directory_list'], suppressions) after require—avoid duplicating core logic:

  $cfg['directory_list'] = array_merge($cfg['directory_list'], ['includes/']);
  $cfg['suppress_issue_types'] = ['PhanPluginTaintNoSource']; // for trusted input wrappers
  

• Leverage taint analysis: The mediawiki/phan-taint-check-plugin is auto-enabled. Annotate functions with @taint (e.g., @taint output for XSS-prone methods) to enable flow tracking.
• CI synergy: Pair with mediawiki/mediawiki-codesniffer (for sniffing) and covers-validator (for test coverage gates) to create a unified quality pipeline.

Gotchas and Tips

• Gerrit mirrors: This repo is a read-only GitHub mirror. All contributions must go through Gerrit per Wikimedia’s developer access guidelines—GitHub PRs will be ignored.
• PHP 8.1+ hard requirement: Phan 6+ and config assume PHP 8.1+. Using PHP 8.0 or earlier breaks taint analysis and causes silent false negatives/positives. Verify php --version in CI.
• Dynamic code pitfalls: MediaWiki’s runtime magic (e.g., require_once, wfRunHooks(), GlobalVar magic) often triggers PhanUndeclaredProperty or PhanUndeclaredMethod. Fix via:
  • @phan-var annotations on globals
  • Stub files (e.g., stubs/MediaWiki.php)
  • Targeted suppress_issue_types (never blanket disables)
• Debug efficiently: Use --debug for verbose logs, or pipe output to Checkstyle for CI reporting:

  vendor/bin/phan --output-format=checkstyle > phan-results.xml
  

• Legacy extension strategy: For older codebases, create phan-legacy.php inheriting config.php but relaxing strictness (e.g., $cfg['null_casts_as_any_type'] = true; $cfg['allow_array_cast'] = true;) and run in a separate CI job.
• Plugin order matters: Ensure phan-taint-check-plugin loads before your custom config’s require—otherwise taint checks may not apply. Verify via composer show mediawiki/phan-taint-check-plugin.