* - 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.
*
* @ingroup Maintenance
*/
class FindHooks extends Maintenance {
+ const FIND_NON_RECURSIVE = 0;
+ const FIND_RECURSIVE = 1;
+
/*
* Hooks that are ignored
*/
- protected static $ignore = array( 'testRunLegacyHooks' );
+ protected static $ignore = [ 'testRunLegacyHooks', 'Test' ];
public function __construct() {
parent::__construct();
global $IP;
$documentedHooks = $this->getHooksFromDoc( $IP . '/docs/hooks.txt' );
- $potentialHooks = array();
- $bad = array();
+ $potentialHooks = [];
+ $badHooks = [];
- // TODO: Don't hardcode the list of directories
- $pathinc = array(
- $IP . '/',
- $IP . '/includes/',
- $IP . '/includes/actions/',
- $IP . '/includes/api/',
- $IP . '/includes/cache/',
- $IP . '/includes/changes/',
- $IP . '/includes/changetags/',
- $IP . '/includes/clientpool/',
- $IP . '/includes/content/',
- $IP . '/includes/context/',
- $IP . '/includes/dao/',
- $IP . '/includes/db/',
- $IP . '/includes/debug/',
- $IP . '/includes/deferred/',
- $IP . '/includes/diff/',
- $IP . '/includes/exception/',
- $IP . '/includes/export/',
- $IP . '/includes/externalstore/',
- $IP . '/includes/filebackend/',
- $IP . '/includes/filerepo/',
- $IP . '/includes/filerepo/file/',
- $IP . '/includes/gallery/',
- $IP . '/includes/htmlform/',
- $IP . '/includes/import/',
- $IP . '/includes/installer/',
- $IP . '/includes/interwiki/',
- $IP . '/includes/jobqueue/',
- $IP . '/includes/json/',
- $IP . '/includes/logging/',
- $IP . '/includes/mail/',
- $IP . '/includes/media/',
- $IP . '/includes/page/',
- $IP . '/includes/parser/',
- $IP . '/includes/password/',
- $IP . '/includes/rcfeed/',
- $IP . '/includes/resourceloader/',
- $IP . '/includes/revisiondelete/',
- $IP . '/includes/search/',
- $IP . '/includes/session/',
- $IP . '/includes/site/',
- $IP . '/includes/skins/',
- $IP . '/includes/specialpage/',
- $IP . '/includes/specials/',
- $IP . '/includes/upload/',
- $IP . '/includes/user/',
- $IP . '/includes/utils/',
- $IP . '/languages/',
- $IP . '/maintenance/',
- $IP . '/maintenance/language/',
- $IP . '/tests/',
- $IP . '/tests/parser/',
- $IP . '/tests/phpunit/suites/',
- );
+ $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/",
+ ];
- foreach ( $pathinc as $dir ) {
- $potentialHooks = array_merge( $potentialHooks, $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'] );
}
$documented = array_keys( $documentedHooks );
$potential = array_keys( $potentialHooks );
$potential = array_unique( $potential );
- $bad = array_diff( array_unique( $bad ), self::$ignore );
+ $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 = array();
+ $badParameterCount = $badParameterReference = [];
foreach ( $potentialHooks as $hook => $args ) {
if ( !isset( $documentedHooks[$hook] ) ) {
// Not documented, but that will also be in $todo
}
}
- // let's show the results:
+ // Print the results
$this->printArray( 'Undocumented', $todo );
$this->printArray( 'Documented and not found', $deprecated );
- $this->printArray( 'Unclear hook calls', $bad );
+ $this->printArray( 'Unclear hook calls', $badHooks );
$this->printArray( 'Different parameter count', $badParameterCount );
$this->printArray( 'Different parameter reference', $badParameterReference );
- if ( count( $todo ) == 0 && count( $deprecated ) == 0 && count( $bad ) == 0
- && count( $badParameterCount ) == 0 && count( $badParameterReference ) == 0
+ if ( !$todo && !$deprecated && !$badHooks
+ && !$badParameterCount && !$badParameterReference
) {
$this->output( "Looks good!\n" );
} else {
* @return array Array: key => hook name; value => array of arguments or string 'unknown'
*/
private function getHooksFromLocalDoc( $doc ) {
- $m = array();
+ $m = [];
$content = file_get_contents( $doc );
preg_match_all(
"/\n'(.*?)':.*((?:\n.+)*)/",
);
// Extract the documented parameter
- $hooks = array();
+ $hooks = [];
foreach ( $m as $match ) {
- $args = array();
+ $args = [];
if ( isset( $match[2] ) ) {
- $n = array();
+ $n = [];
if ( preg_match_all( "/\n(&?\\$\w+):.+/", $match[2], $n ) ) {
$args = $n[1];
}
* @return array
*/
private function getHooksFromOnlineDocCategory( $title ) {
- $params = array(
+ $params = [
'action' => 'query',
'list' => 'categorymembers',
'cmtitle' => "Category:$title",
'cmlimit' => 500,
'format' => 'json',
'continue' => '',
- );
+ ];
- $retval = array();
+ $retval = [];
while ( true ) {
$json = Http::get(
wfAppendQuery( 'http://www.mediawiki.org/w/api.php', $params ),
- array(),
+ [],
__METHOD__
);
$data = FormatJson::decode( $json, true );
/**
* Get hooks from a PHP file
- * @param string $file Full filename to the 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 getHooksFromFile( $file ) {
- $content = file_get_contents( $file );
- $m = array();
+ private function getHooksFromFile( $filePath ) {
+ $content = file_get_contents( $filePath );
+ $m = [];
preg_match_all(
// All functions which runs hooks
'/(?:wfRunHooks|Hooks\:\:run|ContentHandler\:\:runLegacyHooks)\s*\(\s*' .
// Comma for second argument
'(?:\s*(,))?' .
// Second argument must start with array to be processed
- '(?:\s*array\s*\(' .
+ '(?:\s*(?:array\s*\(|\[)' .
// Matching inside array - allows one deep of brackets
- '((?:[^\(\)]|\([^\(\)]*\))*)' .
+ '((?:[^\(\)\[\]]|\((?-1)\)|\[(?-1)\])*)' .
// End
- '\))?/',
+ '[\)\]])?/',
$content,
$m,
PREG_SET_ORDER
);
// Extract parameter
- $hooks = array();
+ $hooks = [];
foreach ( $m as $match ) {
- $args = array();
+ $args = [];
if ( isset( $match[4] ) ) {
- $n = array();
+ $n = [];
if ( preg_match_all( '/((?:[^,\(\)]|\([^\(\)]*\))+)/', $match[4], $n ) ) {
$args = array_map( 'trim', $n[1] );
}
return $hooks;
}
- /**
- * Get hooks from the source code.
- * @param string $path Directory where the include files can be found
- * @return array Array: key => hook name; value => array of arguments or string 'unknown'
- */
- private function getHooksFromPath( $path ) {
- $hooks = array();
- $dh = opendir( $path );
- if ( $dh ) {
- while ( ( $file = readdir( $dh ) ) !== false ) {
- if ( filetype( $path . $file ) == 'file' ) {
- $hooks = array_merge( $hooks, $this->getHooksFromFile( $path . $file ) );
- }
- }
- closedir( $dh );
- }
-
- return $hooks;
- }
-
/**
* Get bad hooks (where the hook name could not be determined) from a PHP file
- * @param string $file Full filename to the PHP file.
+ * @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. :)
+ 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 = array();
+ $list = [];
foreach ( $m[0] as $match ) {
- $list[] = $match . "(" . $file . ")";
+ $list[] = $match . "(" . $filePath . ")";
}
return $list;
}
/**
- * Get bad hooks from the source code.
- * @param string $path Directory where the include files can be found
- * @return array 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();
- $dh = opendir( $path );
- if ( $dh ) {
- 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
+ * Nicely sort an print an array
* @param string $msg A message to show before the value
* @param array $arr
- * @param bool $sort Whether to sort the array (Default: true)
*/
- private function printArray( $msg, $arr, $sort = true ) {
- if ( $sort ) {
- asort( $arr );
- }
+ private function printArray( $msg, $arr ) {
+ asort( $arr );
foreach ( $arr as $v ) {
$this->output( "$msg: $v\n" );