/**
* Simple script that try to find documented hook and hooks actually
* in the code and show what's missing.
- *
+ *
* This script assumes that:
* - hooks names in hooks.txt are at the beginning of a line and single quoted.
* - hooks names in code are the first parameter of wfRunHooks.
*
* if --online option is passed, the script will compare the hooks in the code
- * with the ones at http://www.mediawiki.org/wiki/Manual:Hooks
+ * with the ones at https://www.mediawiki.org/wiki/Manual:Hooks
*
* Any instance of wfRunHooks that doesn't meet these parameters will be noted.
*
+ * Copyright © Antoine Musso
+ *
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
* http://www.gnu.org/copyleft/gpl.html
*
+ * @file
* @ingroup Maintenance
- *
- * @author Ashar Voultoiz <hashar@altern.org>
- * @copyright Copyright © Ashar voultoiz
- * @license http://www.gnu.org/copyleft/gpl.html GNU General Public Licence 2.0 or later
+ * @author Antoine Musso <hashar at free dot fr>
*/
-require_once( dirname(__FILE__) . '/Maintenance.php' );
+require_once __DIR__ . '/Maintenance.php';
+/**
+ * Maintenance script that compares documented and actually present mismatches.
+ *
+ * @ingroup Maintenance
+ */
class FindHooks extends Maintenance {
+ const FIND_NON_RECURSIVE = 0;
+ const FIND_RECURSIVE = 1;
+
+ /*
+ * Hooks that are ignored
+ */
+ protected static $ignore = [ 'Test' ];
+
public function __construct() {
parent::__construct();
- $this->mDescription = "Find hooks that are undocumented, missing, or just plain wrong";
- $this->addOption( 'online', 'Check against mediawiki.org hook documentation' );
+ $this->addDescription( 'Find hooks that are undocumented, missing, or just plain wrong' );
+ $this->addOption( 'online', 'Check against MediaWiki.org hook documentation' );
}
public function getDbType() {
public function execute() {
global $IP;
- $documented = $this->getHooksFromDoc( $IP . '/docs/hooks.txt' );
- $potential = array();
- $bad = array();
- $pathinc = array(
- $IP.'/',
- $IP.'/includes/',
- $IP.'/includes/api/',
- $IP.'/includes/db/',
- $IP.'/includes/diff/',
- $IP.'/includes/filerepo/',
- $IP.'/includes/parser/',
- $IP.'/includes/search/',
- $IP.'/includes/specials/',
- $IP.'/includes/upload/',
- $IP.'/languages/',
- $IP.'/maintenance/',
- $IP.'/skins/',
- );
+ $documentedHooks = $this->getHooksFromDoc( $IP . '/docs/hooks.txt' );
+ $potentialHooks = [];
+ $badHooks = [];
+
+ $recurseDirs = [
+ "$IP/includes/",
+ "$IP/mw-config/",
+ "$IP/languages/",
+ "$IP/maintenance/",
+ // Omit $IP/tests/phpunit as it contains hook tests that shouldn't be documented
+ "$IP/tests/parser",
+ "$IP/tests/phpunit/suites",
+ ];
+ $nonRecurseDirs = [
+ "$IP/",
+ ];
+ $extraFiles = [
+ "$IP/tests/phpunit/MediaWikiTestCase.php",
+ ];
- foreach( $pathinc as $dir ) {
- $potential = array_merge( $potential, $this->getHooksFromPath( $dir ) );
- $bad = array_merge( $bad, $this->getBadHooksFromPath( $dir ) );
+ foreach ( $recurseDirs as $dir ) {
+ $ret = $this->getHooksFromDir( $dir, self::FIND_RECURSIVE );
+ $potentialHooks = array_merge( $potentialHooks, $ret['good'] );
+ $badHooks = array_merge( $badHooks, $ret['bad'] );
}
-
+ foreach ( $nonRecurseDirs as $dir ) {
+ $ret = $this->getHooksFromDir( $dir );
+ $potentialHooks = array_merge( $potentialHooks, $ret['good'] );
+ $badHooks = array_merge( $badHooks, $ret['bad'] );
+ }
+ foreach ( $extraFiles as $file ) {
+ $potentialHooks = array_merge( $potentialHooks, $this->getHooksFromFile( $file ) );
+ $badHooks = array_merge( $badHooks, $this->getBadHooksFromFile( $file ) );
+ }
+
+ $documented = array_keys( $documentedHooks );
+ $potential = array_keys( $potentialHooks );
$potential = array_unique( $potential );
- $bad = array_unique( $bad );
- $todo = array_diff( $potential, $documented );
- $deprecated = array_diff( $documented, $potential );
-
- // let's show the results:
- $this->printArray('Undocumented', $todo );
- $this->printArray('Documented and not found', $deprecated );
- $this->printArray('Unclear hook calls', $bad );
-
- if ( count( $todo ) == 0 && count( $deprecated ) == 0 && count( $bad ) == 0 )
+ $badHooks = array_diff( array_unique( $badHooks ), self::$ignore );
+ $todo = array_diff( $potential, $documented, self::$ignore );
+ $deprecated = array_diff( $documented, $potential, self::$ignore );
+
+ // Check parameter count and references
+ $badParameterCount = $badParameterReference = [];
+ foreach ( $potentialHooks as $hook => $args ) {
+ if ( !isset( $documentedHooks[$hook] ) ) {
+ // Not documented, but that will also be in $todo
+ continue;
+ }
+ $argsDoc = $documentedHooks[$hook];
+ if ( $args === 'unknown' || $argsDoc === 'unknown' ) {
+ // Could not get parameter information
+ continue;
+ }
+ if ( count( $argsDoc ) !== count( $args ) ) {
+ $badParameterCount[] = $hook . ': Doc: ' . count( $argsDoc ) . ' vs. Code: ' . count( $args );
+ } else {
+ // Check if & is equal
+ foreach ( $argsDoc as $index => $argDoc ) {
+ $arg = $args[$index];
+ if ( ( $arg[0] === '&' ) !== ( $argDoc[0] === '&' ) ) {
+ $badParameterReference[] = $hook . ': References different: Doc: ' . $argDoc .
+ ' vs. Code: ' . $arg;
+ }
+ }
+ }
+ }
+
+ // Print the results
+ $this->printArray( 'Undocumented', $todo );
+ $this->printArray( 'Documented and not found', $deprecated );
+ $this->printArray( 'Unclear hook calls', $badHooks );
+ $this->printArray( 'Different parameter count', $badParameterCount );
+ $this->printArray( 'Different parameter reference', $badParameterReference );
+
+ if ( !$todo && !$deprecated && !$badHooks
+ && !$badParameterCount && !$badParameterReference
+ ) {
$this->output( "Looks good!\n" );
+ } else {
+ $this->error( 'The script finished with errors.', 1 );
+ }
}
/**
- * Get the hook documentation, either locally or from mediawiki.org
- * @return array of documented hooks
+ * Get the hook documentation, either locally or from MediaWiki.org
+ * @param string $doc
+ * @return array Array: key => hook name; value => array of arguments or string 'unknown'
*/
private function getHooksFromDoc( $doc ) {
- if( $this->hasOption( 'online' ) ){
- // All hooks
- $allhookdata = Http::get( 'http://www.mediawiki.org/w/api.php?action=query&list=categorymembers&cmtitle=Category:MediaWiki_hooks&cmlimit=500&format=php' );
- $allhookdata = unserialize( $allhookdata );
- $allhooks = array();
- foreach( $allhookdata['query']['categorymembers'] as $page ) {
- $found = preg_match( '/Manual\:Hooks\/([a-zA-Z0-9- :]+)/', $page['title'], $matches );
- if( $found ) {
- $hook = str_replace( ' ', '_', $matches[1] );
- $allhooks[] = $hook;
- }
- }
- // Removed hooks
- $oldhookdata = Http::get( 'http://www.mediawiki.org/w/api.php?action=query&list=categorymembers&cmtitle=Category:Removed_hooks&cmlimit=500&format=php' );
- $oldhookdata = unserialize( $oldhookdata );
- $removed = array();
- foreach( $oldhookdata['query']['categorymembers'] as $page ) {
- $found = preg_match( '/Manual\:Hooks\/([a-zA-Z0-9- :]+)/', $page['title'], $matches );
- if( $found ) {
- $hook = str_replace( ' ', '_', $matches[1] );
- $removed[] = $hook;
+ if ( $this->hasOption( 'online' ) ) {
+ return $this->getHooksFromOnlineDoc();
+ } else {
+ return $this->getHooksFromLocalDoc( $doc );
+ }
+ }
+
+ /**
+ * Get hooks from a local file (for example docs/hooks.txt)
+ * @param string $doc Filename to look in
+ * @return array Array: key => hook name; value => array of arguments or string 'unknown'
+ */
+ private function getHooksFromLocalDoc( $doc ) {
+ $m = [];
+ $content = file_get_contents( $doc );
+ preg_match_all(
+ "/\n'(.*?)':.*((?:\n.+)*)/",
+ $content,
+ $m,
+ PREG_SET_ORDER
+ );
+
+ // Extract the documented parameter
+ $hooks = [];
+ foreach ( $m as $match ) {
+ $args = [];
+ if ( isset( $match[2] ) ) {
+ $n = [];
+ if ( preg_match_all( "/\n(&?\\$\w+):.+/", $match[2], $n ) ) {
+ $args = $n[1];
}
}
- return array_diff( $allhooks, $removed );
- } else {
- $m = array();
- $content = file_get_contents( $doc );
- preg_match_all( "/\n'(.*?)'/", $content, $m );
- return array_unique( $m[1] );
+ $hooks[$match[1]] = $args;
}
+ return $hooks;
}
/**
- * Get hooks from a PHP file
- * @param $file Full filename to the PHP file.
- * @return array of hooks found.
+ * Get hooks from www.mediawiki.org using the API
+ * @return array Array: key => hook name; value => string 'unknown'
*/
- private function getHooksFromFile( $file ) {
- $content = file_get_contents( $file );
- $m = array();
- preg_match_all( '/wfRunHooks\(\s*([\'"])(.*?)\1/', $content, $m);
- return $m[2];
+ private function getHooksFromOnlineDoc() {
+ $allhooks = $this->getHooksFromOnlineDocCategory( 'MediaWiki_hooks' );
+ $removed = $this->getHooksFromOnlineDocCategory( 'Removed_hooks' );
+ return array_diff_key( $allhooks, $removed );
+ }
+
+ /**
+ * @param string $title
+ * @return array
+ */
+ private function getHooksFromOnlineDocCategory( $title ) {
+ $params = [
+ 'action' => 'query',
+ 'list' => 'categorymembers',
+ 'cmtitle' => "Category:$title",
+ 'cmlimit' => 500,
+ 'format' => 'json',
+ 'continue' => '',
+ ];
+
+ $retval = [];
+ while ( true ) {
+ $json = Http::get(
+ wfAppendQuery( 'http://www.mediawiki.org/w/api.php', $params ),
+ [],
+ __METHOD__
+ );
+ $data = FormatJson::decode( $json, true );
+ foreach ( $data['query']['categorymembers'] as $page ) {
+ if ( preg_match( '/Manual\:Hooks\/([a-zA-Z0-9- :]+)/', $page['title'], $m ) ) {
+ // parameters are unknown, because that needs parsing of wikitext
+ $retval[str_replace( ' ', '_', $m[1] )] = 'unknown';
+ }
+ }
+ if ( !isset( $data['continue'] ) ) {
+ return $retval;
+ }
+ $params = array_replace( $params, $data['continue'] );
+ }
}
/**
- * Get hooks from the source code.
- * @param $path Directory where the include files can be found
- * @return array of hooks found.
+ * Get hooks from a PHP file
+ * @param string $filePath Full file path to the PHP file.
+ * @return array Array: key => hook name; value => array of arguments or string 'unknown'
*/
- private function getHooksFromPath( $path ) {
- $hooks = array();
- if( $dh = opendir($path) ) {
- while(($file = readdir($dh)) !== false) {
- if( filetype($path.$file) == 'file' ) {
- $hooks = array_merge( $hooks, $this->getHooksFromFile($path.$file) );
+ private function getHooksFromFile( $filePath ) {
+ $content = file_get_contents( $filePath );
+ $m = [];
+ preg_match_all(
+ // All functions which runs hooks
+ '/(?:wfRunHooks|Hooks\:\:run)\s*\(\s*' .
+ // First argument is the hook name as string
+ '([\'"])(.*?)\1' .
+ // Comma for second argument
+ '(?:\s*(,))?' .
+ // Second argument must start with array to be processed
+ '(?:\s*(?:array\s*\(|\[)' .
+ // Matching inside array - allows one deep of brackets
+ '((?:[^\(\)\[\]]|\((?-1)\)|\[(?-1)\])*)' .
+ // End
+ '[\)\]])?/',
+ $content,
+ $m,
+ PREG_SET_ORDER
+ );
+
+ // Extract parameter
+ $hooks = [];
+ foreach ( $m as $match ) {
+ $args = [];
+ if ( isset( $match[4] ) ) {
+ $n = [];
+ if ( preg_match_all( '/((?:[^,\(\)]|\([^\(\)]*\))+)/', $match[4], $n ) ) {
+ $args = array_map( 'trim', $n[1] );
+ // remove empty entries from trailing spaces
+ $args = array_filter( $args );
}
+ } elseif ( isset( $match[3] ) ) {
+ // Found a parameter for Hooks::run,
+ // but could not extract the hooks argument,
+ // because there are given by a variable
+ $args = 'unknown';
}
- closedir($dh);
+ $hooks[$match[2]] = $args;
}
+
return $hooks;
}
/**
* Get bad hooks (where the hook name could not be determined) from a PHP file
- * @param $file Full filename to the PHP file.
- * @return array of bad wfRunHooks() lines
+ * @param string $filePath Full filename to the PHP file.
+ * @return array Array of bad wfRunHooks() lines
*/
- private function getBadHooksFromFile( $file ) {
- $content = file_get_contents( $file );
- $m = array();
- # We want to skip the "function wfRunHooks()" one. :)
- preg_match_all( '/(?<!function )wfRunHooks\(\s*[^\s\'"].*/', $content, $m);
- $list = array();
- foreach( $m[0] as $match ){
- $list[] = $match . "(" . $file . ")";
+ private function getBadHooksFromFile( $filePath ) {
+ $content = file_get_contents( $filePath );
+ $m = [];
+ // We want to skip the "function wfRunHooks()" one. :)
+ preg_match_all( '/(?<!function )wfRunHooks\(\s*[^\s\'"].*/', $content, $m );
+ $list = [];
+ foreach ( $m[0] as $match ) {
+ $list[] = $match . "(" . $filePath . ")";
}
+
return $list;
}
/**
- * Get bad hooks from the source code.
- * @param $path Directory where the include files can be found
- * @return array of bad wfRunHooks() lines
+ * Get hooks from a directory of PHP files.
+ * @param string $dir Directory path to start at
+ * @param int $recursive Pass self::FIND_RECURSIVE
+ * @return array Array: key => hook name; value => array of arguments or string 'unknown'
*/
- private function getBadHooksFromPath( $path ) {
- $hooks = array();
- if( $dh = opendir($path) ) {
- while(($file = readdir($dh)) !== false) {
- # We don't want to read this file as it contains bad calls to wfRunHooks()
- if( filetype( $path.$file ) == 'file' && !$path.$file == __FILE__ ) {
- $hooks = array_merge( $hooks, $this->getBadHooksFromFile($path.$file) );
- }
+ private function getHooksFromDir( $dir, $recurse = 0 ) {
+ $good = [];
+ $bad = [];
+
+ if ( $recurse === self::FIND_RECURSIVE ) {
+ $iterator = new RecursiveIteratorIterator(
+ new RecursiveDirectoryIterator( $dir, RecursiveDirectoryIterator::SKIP_DOTS ),
+ RecursiveIteratorIterator::SELF_FIRST
+ );
+ } else {
+ $iterator = new DirectoryIterator( $dir );
+ }
+
+ foreach ( $iterator as $info ) {
+ // Ignore directories, work only on php files,
+ if ( $info->isFile() && in_array( $info->getExtension(), [ 'php', 'inc' ] )
+ // Skip this file as it contains text that looks like a bad wfRunHooks() call
+ && $info->getRealPath() !== __FILE__
+ ) {
+ $good = array_merge( $good, $this->getHooksFromFile( $info->getRealPath() ) );
+ $bad = array_merge( $bad, $this->getBadHooksFromFile( $info->getRealPath() ) );
}
- closedir($dh);
}
- return $hooks;
+
+ return [ 'good' => $good, 'bad' => $bad ];
}
/**
- * Nicely output the array
- * @param $msg A message to show before the value
- * @param $arr An array
- * @param $sort Boolean : wheter to sort the array (Default: true)
+ * Nicely sort an print an array
+ * @param string $msg A message to show before the value
+ * @param array $arr
*/
- private function printArray( $msg, $arr, $sort = true ) {
- if($sort) asort($arr);
- foreach($arr as $v) $this->output( "$msg: $v\n" );
+ private function printArray( $msg, $arr ) {
+ asort( $arr );
+
+ foreach ( $arr as $v ) {
+ $this->output( "$msg: $v\n" );
+ }
}
}
-$maintClass = "FindHooks";
-require_once( DO_MAINTENANCE );
+$maintClass = 'FindHooks';
+require_once RUN_MAINTENANCE_IF_MAIN;