From de9c02190ce45b8d40abbd33fafd6d2896fd1df9 Mon Sep 17 00:00:00 2001 From: Alexandre Emsenhuber Date: Sat, 5 Jul 2008 11:36:55 +0000 Subject: [PATCH] * Added $IP in dirs for OpenSearchUrls hook * getHooksFromDoc() now returns an unique array * 80 chars per line in docs/hooks.txt --- docs/hooks.txt | 186 ++++++++++++++++++-------------------- maintenance/findhooks.php | 3 +- 2 files changed, 91 insertions(+), 98 deletions(-) diff --git a/docs/hooks.txt b/docs/hooks.txt index 65802d68ef..39cbd01742 100644 --- a/docs/hooks.txt +++ b/docs/hooks.txt @@ -1,39 +1,38 @@ hooks.txt -This document describes how event hooks work in MediaWiki; how to add -hooks for an event; and how to run hooks for an event. +This document describes how event hooks work in MediaWiki; how to add hooks for +an event; and how to run hooks for an event. ==Glossary== event - Something that happens with the wiki. For example: a user logs - in. A wiki page is saved. A wiki page is deleted. Often there are - two events associated with a single action: one before the code - is run to make the event happen, and one after. Each event has a - name, preferably in CamelCase. For example, 'UserLogin', - 'ArticleSave', 'ArticleSaveComplete', 'ArticleDelete'. + Something that happens with the wiki. For example: a user logs in. A wiki + page is saved. A wiki page is deleted. Often there are two events + associated with a single action: one before the code is run to make the + event happen, and one after. Each event has a name, preferably in + CamelCase. For example, 'UserLogin', 'ArticleSave', 'ArticleSaveComplete', + 'ArticleDelete'. hook - A clump of code and data that should be run when an event - happens. This can be either a function and a chunk of data, or an - object and a method. + A clump of code and data that should be run when an event happens. This can + be either a function and a chunk of data, or an object and a method. hook function The function part of a hook. ==Rationale== -Hooks allow us to decouple optionally-run code from code that is run -for everyone. It allows MediaWiki hackers, third-party developers and -local administrators to define code that will be run at certain points -in the mainline code, and to modify the data run by that mainline -code. Hooks can keep mainline code simple, and make it easier to -write extensions. Hooks are a principled alternative to local patches. +Hooks allow us to decouple optionally-run code from code that is run for +everyone. It allows MediaWiki hackers, third-party developers and local +administrators to define code that will be run at certain points in the mainline +code, and to modify the data run by that mainline code. Hooks can keep mainline +code simple, and make it easier to write extensions. Hooks are a principled +alternative to local patches. -Consider, for example, two options in MediaWiki. One reverses the -order of a title before displaying the article; the other converts the -title to all uppercase letters. Currently, in MediaWiki code, we -would handle this as follows (note: not real code, here): +Consider, for example, two options in MediaWiki. One reverses the order of a +title before displaying the article; the other converts the title to all +uppercase letters. Currently, in MediaWiki code, we would handle this as follows +(note: not real code, here): function showAnArticle($article) { global $wgReverseTitle, $wgCapitalizeTitle; @@ -49,31 +48,30 @@ would handle this as follows (note: not real code, here): # code to actually show the article goes here } -An extension writer, or a local admin, will often add custom code to -the function -- with or without a global variable. For example, -someone wanting email notification when an article is shown may add: +An extension writer, or a local admin, will often add custom code to the +function -- with or without a global variable. For example, someone wanting +email notification when an article is shown may add: function showAnArticle($article) { - global $wgReverseTitle, $wgCapitalizeTitle; + global $wgReverseTitle, $wgCapitalizeTitle, $wgNotifyArticle; - if ($wgReverseTitle) { - wfReverseTitle($article); - } + if ($wgReverseTitle) { + wfReverseTitle($article); + } - if ($wgCapitalizeTitle) { - wfCapitalizeTitle($article); - } + if ($wgCapitalizeTitle) { + wfCapitalizeTitle($article); + } - # code to actually show the article goes here + # code to actually show the article goes here - if ($wgNotifyArticle) { - wfNotifyArticleShow($article)); - } + if ($wgNotifyArticle) { + wfNotifyArticleShow($article)); + } } -Using a hook-running strategy, we can avoid having all this -option-specific stuff in our mainline code. Using hooks, the function -becomes: +Using a hook-running strategy, we can avoid having all this option-specific +stuff in our mainline code. Using hooks, the function becomes: function showAnArticle($article) { @@ -85,16 +83,15 @@ becomes: } } -We've cleaned up the code here by removing clumps of weird, -infrequently used code and moving them off somewhere else. It's much -easier for someone working with this code to see what's _really_ going -on, and make changes or fix bugs. +We've cleaned up the code here by removing clumps of weird, infrequently used +code and moving them off somewhere else. It's much easier for someone working +with this code to see what's _really_ going on, and make changes or fix bugs. -In addition, we can take all the code that deals with the little-used -title-reversing options (say) and put it in one place. Instead of -having little title-reversing if-blocks spread all over the codebase -in showAnArticle, deleteAnArticle, exportArticle, etc., we can -concentrate it all in an extension file: +In addition, we can take all the code that deals with the little-used +title-reversing options (say) and put it in one place. Instead of having little +title-reversing if-blocks spread all over the codebase in showAnArticle, +deleteAnArticle, exportArticle, etc., we can concentrate it all in an extension +file: function reverseArticleTitle($article) { # ... @@ -104,8 +101,8 @@ concentrate it all in an extension file: # ... } -The setup function for the extension just has to add its hook -functions to the appropriate events: +The setup function for the extension just has to add its hook functions to the +appropriate events: setupTitleReversingExtension() { global $wgHooks; @@ -115,23 +112,21 @@ functions to the appropriate events: $wgHooks['ArticleExport'][] = 'reverseForExport'; } -Having all this code related to the title-reversion option in one -place means that it's easier to read and understand; you don't have to -do a grep-find to see where the $wgReverseTitle variable is used, say. +Having all this code related to the title-reversion option in one place means +that it's easier to read and understand; you don't have to do a grep-find to see +where the $wgReverseTitle variable is used, say. -If the code is well enough isolated, it can even be excluded when not -used -- making for some slight savings in memory and load-up -performance at runtime. Admins who want to have all the reversed -titles can add: +If the code is well enough isolated, it can even be excluded when not used -- +making for some slight savings in memory and load-up performance at runtime. +Admins who want to have all the reversed titles can add: require_once('extensions/ReverseTitle.php'); -...to their LocalSettings.php file; those of us who don't want or need -it can just leave it out. +...to their LocalSettings.php file; those of us who don't want or need it can +just leave it out. -The extensions don't even have to be shipped with MediaWiki; they -could be provided by a third-party developer or written by the admin -him/herself. +The extensions don't even have to be shipped with MediaWiki; they could be +provided by a third-party developer or written by the admin him/herself. ==Writing hooks== @@ -140,8 +135,8 @@ A hook is a chunk of code run at some particular event. It consists of: * a function with some optional accompanying data, or * an object with a method and some optional accompanying data. -Hooks are registered by adding them to the global $wgHooks array for a -given event. All the following are valid ways to define hooks: +Hooks are registered by adding them to the global $wgHooks array for a given +event. All the following are valid ways to define hooks: $wgHooks['EventName'][] = 'someFunction'; # function, no data $wgHooks['EventName'][] = array('someFunction', $someData); @@ -152,10 +147,9 @@ given event. All the following are valid ways to define hooks: $wgHooks['EventName'][] = array($object, 'someMethod', $someData); $wgHooks['EventName'][] = array($object); # weird but OK -When an event occurs, the function (or object method) will be called -with the optional data provided as well as event-specific parameters. -The above examples would result in the following code being executed -when 'EventName' happened: +When an event occurs, the function (or object method) will be called with the +optional data provided as well as event-specific parameters. The above examples +would result in the following code being executed when 'EventName' happened: # function, no data someFunction($param1, $param2) @@ -169,31 +163,30 @@ when 'EventName' happened: # object with method and data $object->someMethod($someData, $param1, $param2) -Note that when an object is the hook, and there's no specified method, -the default method called is 'onEventName'. For different events this -would be different: 'onArticleSave', 'onUserLogin', etc. +Note that when an object is the hook, and there's no specified method, the +default method called is 'onEventName'. For different events this would be +different: 'onArticleSave', 'onUserLogin', etc. -The extra data is useful if we want to use the same function or object -for different purposes. For example: +The extra data is useful if we want to use the same function or object for +different purposes. For example: $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'TimStarling'); $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'brion'); -This code would result in ircNotify being run twice when an article is -saved: once for 'TimStarling', and once for 'brion'. +This code would result in ircNotify being run twice when an article is saved: +once for 'TimStarling', and once for 'brion'. Hooks can return three possible values: * true: the hook has operated successfully - * "some string": an error occurred; processing should - stop and the error should be shown to the user - * false: the hook has successfully done the work - necessary and the calling function should skip + * "some string": an error occurred; processing should stop and the error + should be shown to the user + * false: the hook has successfully done the work necessary and the calling + function should skip -The last result would be for cases where the hook function replaces -the main functionality. For example, if you wanted to authenticate -users to a custom system (LDAP, another PHP program, whatever), you -could do: +The last result would be for cases where the hook function replaces the main +functionality. For example, if you wanted to authenticate users to a custom +system (LDAP, another PHP program, whatever), you could do: $wgHooks['UserLogin'][] = array('ldapLogin', $ldapServer); @@ -202,13 +195,13 @@ could do: return false; } -Returning false makes less sense for events where the action is -complete, and will normally be ignored. +Returning false makes less sense for events where the action is complete, and +will normally be ignored. ==Using hooks== -A calling function or method uses the wfRunHooks() function to run -the hooks related to a particular event, like so: +A calling function or method uses the wfRunHooks() function to run the hooks +related to a particular event, like so: class Article { # ... @@ -221,22 +214,21 @@ the hooks related to a particular event, like so: } } -wfRunHooks() returns true if the calling function should continue -processing (the hooks ran OK, or there are no hooks to run), or false -if it shouldn't (an error occurred, or one of the hooks handled the -action already). Checking the return value matters more for "before" -hooks than for "complete" hooks. +wfRunHooks() returns true if the calling function should continue processing +(the hooks ran OK, or there are no hooks to run), or false if it shouldn't (an +error occurred, or one of the hooks handled the action already). Checking the +return value matters more for "before" hooks than for "complete" hooks. Note that hook parameters are passed in an array; this is a necessary -inconvenience to make it possible to pass reference values (that can -be changed) into the hook code. Also note that earlier versions of -wfRunHooks took a variable number of arguments; the array() calling -protocol came about after MediaWiki 1.4rc1. +inconvenience to make it possible to pass reference values (that can be changed) +into the hook code. Also note that earlier versions of wfRunHooks took a +variable number of arguments; the array() calling protocol came about after +MediaWiki 1.4rc1. ==Events and parameters== -This is a list of known events and parameters; please add to it if -you're going to add events to the MediaWiki code. +This is a list of known events and parameters; please add to it if you're going +to add events to the MediaWiki code. 'AbortAutoblock': Return false to cancel an autoblock. $autoblockip: The IP going to be autoblocked. diff --git a/maintenance/findhooks.php b/maintenance/findhooks.php index c2b1d75b25..7a2ba53f66 100644 --- a/maintenance/findhooks.php +++ b/maintenance/findhooks.php @@ -27,6 +27,7 @@ include('commandLine.inc'); $doc = $IP . '/docs/hooks.txt'; $pathinc = array( + $IP.'/', $IP.'/includes/', $IP.'/includes/api/', $IP.'/includes/db/', @@ -53,7 +54,7 @@ function getHooksFromDoc() { $content = file_get_contents( $doc ); preg_match_all( "/\n'(.*?)'/", $content, $m ); } - return $m[1]; + return array_unique( $m[1] ); } /** -- 2.20.1