MediaWiki  master
findHooks.php
Go to the documentation of this file.
1 <?php
38 
39 require_once __DIR__ . '/Maintenance.php';
40 
46 class FindHooks extends Maintenance {
47  const FIND_NON_RECURSIVE = 0;
48  const FIND_RECURSIVE = 1;
49 
50  /*
51  * Hooks that are ignored
52  */
53  protected static $ignore = [ 'Test' ];
54 
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' );
59  }
60 
61  public function getDbType() {
62  return Maintenance::DB_NONE;
63  }
64 
65  public function execute() {
66  global $IP;
67 
68  $documentedHooks = $this->getHooksFromDoc( $IP . '/docs/hooks.txt' );
69  $potentialHooks = [];
70  $badHooks = [];
71 
72  $recurseDirs = [
73  "$IP/includes/",
74  "$IP/mw-config/",
75  "$IP/languages/",
76  "$IP/maintenance/",
77  // Omit $IP/tests/phpunit as it contains hook tests that shouldn't be documented
78  "$IP/tests/parser",
79  "$IP/tests/phpunit/suites",
80  ];
81  $nonRecurseDirs = [
82  "$IP/",
83  ];
84  $extraFiles = [
85  "$IP/tests/phpunit/MediaWikiTestCase.php",
86  ];
87 
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'] );
92  }
93  foreach ( $nonRecurseDirs as $dir ) {
94  $ret = $this->getHooksFromDir( $dir );
95  $potentialHooks = array_merge( $potentialHooks, $ret['good'] );
96  $badHooks = array_merge( $badHooks, $ret['bad'] );
97  }
98  foreach ( $extraFiles as $file ) {
99  $potentialHooks = array_merge( $potentialHooks, $this->getHooksFromFile( $file ) );
100  $badHooks = array_merge( $badHooks, $this->getBadHooksFromFile( $file ) );
101  }
102 
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 );
109 
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
115  continue;
116  }
117  $argsDoc = $documentedHooks[$hook];
118  if ( $args === 'unknown' || $argsDoc === 'unknown' ) {
119  // Could not get parameter information
120  continue;
121  }
122  if ( count( $argsDoc ) !== count( $args ) ) {
123  $badParameterCount[] = $hook . ': Doc: ' . count( $argsDoc ) . ' vs. Code: ' . count( $args );
124  } else {
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;
131  }
132  }
133  }
134  }
135 
136  // Print the results
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 );
142 
143  if ( !$todo && !$deprecated && !$badHooks
144  && !$badParameterCount && !$badParameterReference
145  ) {
146  $this->output( "Looks good!\n" );
147  } else {
148  $this->fatalError( 'The script finished with errors.' );
149  }
150  }
151 
157  private function getHooksFromDoc( $doc ) {
158  if ( $this->hasOption( 'online' ) ) {
159  return $this->getHooksFromOnlineDoc();
160  } else {
161  return $this->getHooksFromLocalDoc( $doc );
162  }
163  }
164 
170  private function getHooksFromLocalDoc( $doc ) {
171  $m = [];
172  $content = file_get_contents( $doc );
173  preg_match_all(
174  "/\n'(.*?)':.*((?:\n.+)*)/",
175  $content,
176  $m,
177  PREG_SET_ORDER
178  );
179 
180  // Extract the documented parameter
181  $hooks = [];
182  foreach ( $m as $match ) {
183  $args = [];
184  if ( isset( $match[2] ) ) {
185  $n = [];
186  if ( preg_match_all( "/\n(&?\\$\w+):.+/", $match[2], $n ) ) {
187  $args = $n[1];
188  }
189  }
190  $hooks[$match[1]] = $args;
191  }
192  return $hooks;
193  }
194 
199  private function getHooksFromOnlineDoc() {
200  $allhooks = $this->getHooksFromOnlineDocCategory( 'MediaWiki_hooks' );
201  $removed = $this->getHooksFromOnlineDocCategory( 'Removed_hooks' );
202  return array_diff_key( $allhooks, $removed );
203  }
204 
209  private function getHooksFromOnlineDocCategory( $title ) {
210  $params = [
211  'action' => 'query',
212  'list' => 'categorymembers',
213  'cmtitle' => "Category:$title",
214  'cmlimit' => 500,
215  'format' => 'json',
216  'continue' => '',
217  ];
218 
219  $retval = [];
220  while ( true ) {
221  $json = MediaWikiServices::getInstance()->getHttpRequestFactory()->get(
222  wfAppendQuery( 'https://www.mediawiki.org/w/api.php', $params ),
223  [],
224  __METHOD__
225  );
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';
231  }
232  }
233  if ( !isset( $data['continue'] ) ) {
234  return $retval;
235  }
236  $params = array_replace( $params, $data['continue'] );
237  }
238  }
239 
245  private function getHooksFromFile( $filePath ) {
246  $content = file_get_contents( $filePath );
247  $m = [];
248  preg_match_all(
249  // All functions which runs hooks
250  '/(?:Hooks\:\:run|Hooks\:\:runWithoutAbort)\s*\(\s*' .
251  // First argument is the hook name as string
252  '([\'"])(.*?)\1' .
253  // Comma for second argument
254  '(?:\s*(,))?' .
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)\])*)' .
259  // End
260  '[\)\]])?/',
261  $content,
262  $m,
263  PREG_SET_ORDER
264  );
265 
266  // Extract parameter
267  $hooks = [];
268  foreach ( $m as $match ) {
269  $args = [];
270  if ( isset( $match[4] ) ) {
271  $n = [];
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 );
276  }
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
281  $args = 'unknown';
282  }
283  $hooks[$match[2]] = $args;
284  }
285 
286  return $hooks;
287  }
288 
294  private function getBadHooksFromFile( $filePath ) {
295  $content = file_get_contents( $filePath );
296  $m = [];
297  preg_match_all( '/(?:Hooks\:\:run|Hooks\:\:runWithoutAbort)\(\s*[^\s\'"].*/', $content, $m );
298  $list = [];
299  foreach ( $m[0] as $match ) {
300  $list[] = $match . "(" . $filePath . ")";
301  }
302 
303  return $list;
304  }
305 
312  private function getHooksFromDir( $dir, $recurse = 0 ) {
313  $good = [];
314  $bad = [];
315 
316  if ( $recurse === self::FIND_RECURSIVE ) {
317  $iterator = new RecursiveIteratorIterator(
318  new RecursiveDirectoryIterator( $dir, RecursiveDirectoryIterator::SKIP_DOTS ),
319  RecursiveIteratorIterator::SELF_FIRST
320  );
321  } else {
322  $iterator = new DirectoryIterator( $dir );
323  }
324 
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__
331  ) {
332  $good = array_merge( $good, $this->getHooksFromFile( $info->getRealPath() ) );
333  $bad = array_merge( $bad, $this->getBadHooksFromFile( $info->getRealPath() ) );
334  }
335  }
336 
337  return [ 'good' => $good, 'bad' => $bad ];
338  }
339 
345  private function printArray( $msg, $arr ) {
346  asort( $arr );
347 
348  foreach ( $arr as $v ) {
349  $this->output( "$msg: $v\n" );
350  }
351  }
352 }
353 
355 require_once RUN_MAINTENANCE_IF_MAIN;
const DB_NONE
Constants for DB access type.
Definition: Maintenance.php:85
$IP
Definition: WebStart.php:41
null means default in associative array with keys and values unescaped Should be merged with default with a value of false meaning to suppress the attribute in associative array with keys and values unescaped noclasses & $ret
Definition: hooks.txt:1982
Apache License January AND DISTRIBUTION Definitions License shall mean the terms and conditions for use
if(PHP_SAPI !='cli-server') if(!isset( $_SERVER['SCRIPT_FILENAME'])) $file
Definition: router.php:42
Abstract maintenance class for quickly writing and churning out maintenance scripts with minimal effo...
Definition: maintenance.txt:39
Maintenance script that compares documented and actually present mismatches.
Definition: findHooks.php:46
getHooksFromLocalDoc( $doc)
Get hooks from a local file (for example docs/hooks.txt)
Definition: findHooks.php:170
const FIND_RECURSIVE
Definition: findHooks.php:48
injection txt This is an overview of how MediaWiki makes use of dependency injection The design described here grew from the discussion of RFC T384 The term dependency this means that anything an object needs to operate should be injected from the the object itself should only know narrow no concrete implementation of the logic it relies on The requirement to inject everything typically results in an architecture that based on two main types of and essentially stateless service objects that use other service objects to operate on the value objects As of the beginning MediaWiki is only starting to use the DI approach Much of the code still relies on global state or direct resulting in a highly cyclical dependency MediaWikiServices
Definition: injection.txt:23
hasOption( $name)
Checks to see if a particular option exists.
require_once RUN_MAINTENANCE_IF_MAIN
Definition: maintenance.txt:50
if( $line===false) $args
Definition: cdb.php:64
const FIND_NON_RECURSIVE
Definition: findHooks.php:47
wfAppendQuery( $url, $query)
Append a query string to an existing URL, which may or may not already have query string parameters a...
getBadHooksFromFile( $filePath)
Get bad hooks (where the hook name could not be determined) from a PHP file.
Definition: findHooks.php:294
static decode( $value, $assoc=false)
Decodes a JSON string.
Definition: FormatJson.php:174
addDescription( $text)
Set the description text.
$params
getHooksFromDir( $dir, $recurse=0)
Get hooks from a directory of PHP files.
Definition: findHooks.php:312
__construct()
Definition: findHooks.php:55
namespace and then decline to actually register it file or subcat img or subcat $title
Definition: hooks.txt:925
getHooksFromDoc( $doc)
Get the hook documentation, either locally or from MediaWiki.org.
Definition: findHooks.php:157
output( $out, $channel=null)
Throw some output to the user.
getHooksFromOnlineDoc()
Get hooks from www.mediawiki.org using the API.
Definition: findHooks.php:199
This document is intended to provide useful advice for parties seeking to redistribute MediaWiki to end users It s targeted particularly at maintainers for Linux since it s been observed that distribution packages of MediaWiki often break We ve consistently had to recommend that users seeking support use official tarballs instead of their distribution s and this often solves whatever problem the user is having It would be nice if this could such as
Definition: distributors.txt:9
getHooksFromOnlineDocCategory( $title)
Definition: findHooks.php:209
printArray( $msg, $arr)
Nicely sort an print an array.
Definition: findHooks.php:345
injection txt This is an overview of how MediaWiki makes use of dependency injection The design described here grew from the discussion of RFC T384 The term dependency this means that anything an object needs to operate should be injected from the the object itself should only know narrow no concrete implementation of the logic it relies on The requirement to inject everything typically results in an architecture that based on two main types of and essentially stateless service objects that use other service objects to operate on the value objects As of the beginning MediaWiki is only starting to use the DI approach Much of the code still relies on global state or direct resulting in a highly cyclical dependency which acts as the top level factory for services in MediaWiki which can be used to gain access to default instances of various services MediaWikiServices however also allows new services to be defined and default services to be redefined Services are defined or redefined by providing a callback the instantiator that will return a new instance of the service When it will create an instance of MediaWikiServices and populate it with the services defined in the files listed by thereby bootstrapping the DI framework Per $wgServiceWiringFiles lists includes ServiceWiring php
Definition: injection.txt:35
static $ignore
Definition: findHooks.php:53
you have access to all of the normal MediaWiki so you can get a DB use the etc For full docs on the Maintenance class
Definition: maintenance.txt:52
getHooksFromFile( $filePath)
Get hooks from a PHP file.
Definition: findHooks.php:245
$maintClass
Definition: findHooks.php:354
addOption( $name, $description, $required=false, $withArg=false, $shortName=false, $multiOccurrence=false)
Add a parameter to the script.
fatalError( $msg, $exitCode=1)
Output a message and terminate the current script.
$content
Definition: pageupdater.txt:72