3 * Simple script that try to find documented hook and hooks actually
4 * in the code and show what's missing.
6 * This script assumes that:
7 * - hooks names in hooks.txt are at the beginning of a line and single quoted.
8 * - hooks names in code are the first parameter of Hooks::run.
10 * if --online option is passed, the script will compare the hooks in the code
11 * with the ones at https://www.mediawiki.org/wiki/Manual:Hooks
13 * Any instance of Hooks::run that doesn't meet these requirements will be noted.
15 * Copyright © Antoine Musso
17 * This program is free software; you can redistribute it and/or modify
18 * it under the terms of the GNU General Public License as published by
19 * the Free Software Foundation; either version 2 of the License, or
20 * (at your option) any later version.
22 * This program is distributed in the hope that it will be useful,
23 * but WITHOUT ANY WARRANTY; without even the implied warranty of
24 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
25 * GNU General Public License for more details.
27 * You should have received a copy of the GNU General Public License along
28 * with this program; if not, write to the Free Software Foundation, Inc.,
29 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
30 * http://www.gnu.org/copyleft/gpl.html
33 * @ingroup Maintenance
34 * @author Antoine Musso <hashar at free dot fr>
37 use MediaWiki\MediaWikiServices
;
39 require_once __DIR__
. '/Maintenance.php';
42 * Maintenance script that compares documented and actually present mismatches.
44 * @ingroup Maintenance
46 class FindHooks
extends Maintenance
{
47 const FIND_NON_RECURSIVE
= 0;
48 const FIND_RECURSIVE
= 1;
51 * Hooks that are ignored
53 protected static $ignore = [ 'Test' ];
55 public function __construct() {
56 parent
::__construct();
57 $this->addDescription( 'Find hooks that are undocumented, missing, or just plain wrong' );
58 $this->addOption( 'online', 'Check against MediaWiki.org hook documentation' );
61 public function getDbType() {
62 return Maintenance
::DB_NONE
;
65 public function execute() {
68 $documentedHooks = $this->getHooksFromDoc( $IP . '/docs/hooks.txt' );
77 // Omit $IP/tests/phpunit as it contains hook tests that shouldn't be documented
79 "$IP/tests/phpunit/suites",
85 "$IP/tests/phpunit/MediaWikiTestCase.php",
88 foreach ( $recurseDirs as $dir ) {
89 $ret = $this->getHooksFromDir( $dir, self
::FIND_RECURSIVE
);
90 $potentialHooks = array_merge( $potentialHooks, $ret['good'] );
91 $badHooks = array_merge( $badHooks, $ret['bad'] );
93 foreach ( $nonRecurseDirs as $dir ) {
94 $ret = $this->getHooksFromDir( $dir );
95 $potentialHooks = array_merge( $potentialHooks, $ret['good'] );
96 $badHooks = array_merge( $badHooks, $ret['bad'] );
98 foreach ( $extraFiles as $file ) {
99 $potentialHooks = array_merge( $potentialHooks, $this->getHooksFromFile( $file ) );
100 $badHooks = array_merge( $badHooks, $this->getBadHooksFromFile( $file ) );
103 $documented = array_keys( $documentedHooks );
104 $potential = array_keys( $potentialHooks );
105 $potential = array_unique( $potential );
106 $badHooks = array_diff( array_unique( $badHooks ), self
::$ignore );
107 $todo = array_diff( $potential, $documented, self
::$ignore );
108 $deprecated = array_diff( $documented, $potential, self
::$ignore );
110 // Check parameter count and references
111 $badParameterCount = $badParameterReference = [];
112 foreach ( $potentialHooks as $hook => $args ) {
113 if ( !isset( $documentedHooks[$hook] ) ) {
114 // Not documented, but that will also be in $todo
117 $argsDoc = $documentedHooks[$hook];
118 if ( $args === 'unknown' ||
$argsDoc === 'unknown' ) {
119 // Could not get parameter information
122 if ( count( $argsDoc ) !== count( $args ) ) {
123 $badParameterCount[] = $hook . ': Doc: ' . count( $argsDoc ) . ' vs. Code: ' . count( $args );
125 // Check if & is equal
126 foreach ( $argsDoc as $index => $argDoc ) {
127 $arg = $args[$index];
128 if ( ( $arg[0] === '&' ) !== ( $argDoc[0] === '&' ) ) {
129 $badParameterReference[] = $hook . ': References different: Doc: ' . $argDoc .
130 ' vs. Code: ' . $arg;
137 $this->printArray( 'Undocumented', $todo );
138 $this->printArray( 'Documented and not found', $deprecated );
139 $this->printArray( 'Unclear hook calls', $badHooks );
140 $this->printArray( 'Different parameter count', $badParameterCount );
141 $this->printArray( 'Different parameter reference', $badParameterReference );
143 if ( !$todo && !$deprecated && !$badHooks
144 && !$badParameterCount && !$badParameterReference
146 $this->output( "Looks good!\n" );
148 $this->fatalError( 'The script finished with errors.' );
153 * Get the hook documentation, either locally or from MediaWiki.org
155 * @return array Array: key => hook name; value => array of arguments or string 'unknown'
157 private function getHooksFromDoc( $doc ) {
158 if ( $this->hasOption( 'online' ) ) {
159 return $this->getHooksFromOnlineDoc();
161 return $this->getHooksFromLocalDoc( $doc );
166 * Get hooks from a local file (for example docs/hooks.txt)
167 * @param string $doc Filename to look in
168 * @return array Array: key => hook name; value => array of arguments or string 'unknown'
170 private function getHooksFromLocalDoc( $doc ) {
172 $content = file_get_contents( $doc );
174 "/\n'(.*?)':.*((?:\n.+)*)/",
180 // Extract the documented parameter
182 foreach ( $m as $match ) {
184 if ( isset( $match[2] ) ) {
186 if ( preg_match_all( "/\n(&?\\$\w+):.+/", $match[2], $n ) ) {
190 $hooks[$match[1]] = $args;
196 * Get hooks from www.mediawiki.org using the API
197 * @return array Array: key => hook name; value => string 'unknown'
199 private function getHooksFromOnlineDoc() {
200 $allhooks = $this->getHooksFromOnlineDocCategory( 'MediaWiki_hooks' );
201 $removed = $this->getHooksFromOnlineDocCategory( 'Removed_hooks' );
202 return array_diff_key( $allhooks, $removed );
206 * @param string $title
209 private function getHooksFromOnlineDocCategory( $title ) {
212 'list' => 'categorymembers',
213 'cmtitle' => "Category:$title",
221 $json = MediaWikiServices
::getInstance()->getHttpRequestFactory()->get(
222 wfAppendQuery( 'https://www.mediawiki.org/w/api.php', $params ),
226 $data = FormatJson
::decode( $json, true );
227 foreach ( $data['query']['categorymembers'] as $page ) {
228 if ( preg_match( '/Manual\:Hooks\/([a-zA-Z0-9- :]+)/', $page['title'], $m ) ) {
229 // parameters are unknown, because that needs parsing of wikitext
230 $retval[str_replace( ' ', '_', $m[1] )] = 'unknown';
233 if ( !isset( $data['continue'] ) ) {
236 $params = array_replace( $params, $data['continue'] );
241 * Get hooks from a PHP file
242 * @param string $filePath Full file path to the PHP file.
243 * @return array Array: key => hook name; value => array of arguments or string 'unknown'
245 private function getHooksFromFile( $filePath ) {
246 $content = file_get_contents( $filePath );
249 // All functions which runs hooks
250 '/(?:Hooks\:\:run|Hooks\:\:runWithoutAbort)\s*\(\s*' .
251 // First argument is the hook name as string
253 // Comma for second argument
255 // Second argument must start with array to be processed
256 '(?:\s*(?:array\s*\(|\[)' .
257 // Matching inside array - allows one deep of brackets
258 '((?:[^\(\)\[\]]|\((?-1)\)|\[(?-1)\])*)' .
268 foreach ( $m as $match ) {
270 if ( isset( $match[4] ) ) {
272 if ( preg_match_all( '/((?:[^,\(\)]|\([^\(\)]*\))+)/', $match[4], $n ) ) {
273 $args = array_map( 'trim', $n[1] );
274 // remove empty entries from trailing spaces
275 $args = array_filter( $args );
277 } elseif ( isset( $match[3] ) ) {
278 // Found a parameter for Hooks::run,
279 // but could not extract the hooks argument,
280 // because there are given by a variable
283 $hooks[$match[2]] = $args;
290 * Get bad hooks (where the hook name could not be determined) from a PHP file
291 * @param string $filePath Full filename to the PHP file.
292 * @return array Array of source code lines
294 private function getBadHooksFromFile( $filePath ) {
295 $content = file_get_contents( $filePath );
297 preg_match_all( '/(?:Hooks\:\:run|Hooks\:\:runWithoutAbort)\(\s*[^\s\'"].*/', $content, $m );
299 foreach ( $m[0] as $match ) {
300 $list[] = $match . "(" . $filePath . ")";
307 * Get hooks from a directory of PHP files.
308 * @param string $dir Directory path to start at
309 * @param int $recursive Pass self::FIND_RECURSIVE
310 * @return array Array: key => hook name; value => array of arguments or string 'unknown'
312 private function getHooksFromDir( $dir, $recurse = 0 ) {
316 if ( $recurse === self
::FIND_RECURSIVE
) {
317 $iterator = new RecursiveIteratorIterator(
318 new RecursiveDirectoryIterator( $dir, RecursiveDirectoryIterator
::SKIP_DOTS
),
319 RecursiveIteratorIterator
::SELF_FIRST
322 $iterator = new DirectoryIterator( $dir );
325 /** @var SplFileInfo $info */
326 foreach ( $iterator as $info ) {
327 // Ignore directories, work only on php files,
328 if ( $info->isFile() && in_array( $info->getExtension(), [ 'php', 'inc' ] )
329 // Skip this file as it contains text that looks like a bad wfRunHooks() call
330 && $info->getRealPath() !== __FILE__
332 $good = array_merge( $good, $this->getHooksFromFile( $info->getRealPath() ) );
333 $bad = array_merge( $bad, $this->getBadHooksFromFile( $info->getRealPath() ) );
337 return [ 'good' => $good, 'bad' => $bad ];
341 * Nicely sort an print an array
342 * @param string $msg A message to show before the value
345 private function printArray( $msg, $arr ) {
348 foreach ( $arr as $v ) {
349 $this->output( "$msg: $v\n" );
354 $maintClass = FindHooks
::class;
355 require_once RUN_MAINTENANCE_IF_MAIN
;