3 * A tool for running hook functions.
5 * Copyright 2004, 2005 Evan Prodromou <evan@wikitravel.org>.
7 * This program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 2 of the License, or
10 * (at your option) any later version.
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
17 * You should have received a copy of the GNU General Public License
18 * along with this program; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
21 * @author Evan Prodromou <evan@wikitravel.org>
28 * Call hook functions defined in $wgHooks
30 * Because programmers assign to $wgHooks, we need to be very
31 * careful about its contents. So, there's a lot more error-checking
32 * in here than would normally be necessary.
34 * @param $event String: event name
35 * @param $args Array: parameters passed to hook functions
38 function wfRunHooks( $event, $args = array() ) {
39 return Hooks
::run( $event, $args );
42 function hookErrorHandler( $errno, $errstr ) {
43 return Hooks
::hookErrorHandler( $errno, $errstr );
46 class MWHookException
extends MWException
{}
52 * Used to supersede $wgHooks, because globals are EVIL.
57 protected static $handlers = array();
60 * Attach an event handler to a given hook
63 * @param mixed $name Name of hook
64 * @param mixed $callback Callback function to attach
67 public static function register( $name, $callback ) {
69 if( !isset( self
::$handlers[$name] ) ) {
70 self
::$handlers[$name] = array();
73 self
::$handlers[$name][] = $callback;
78 * Returns true if a hook has a function registered to it.
81 * @param mixed $name Name of hook
84 public static function isRegistered( $name ) {
86 if( !isset( self
::$handlers[$name] ) ) {
87 self
::$handlers[$name] = array();
90 return ( count( self
::$handlers[$name] ) != 0 );
95 * Returns an array of all the event functions attached to a hook
98 * @param mixed $name Name of hook
101 public static function getHandlers( $name ) {
103 if( !isset( self
::$handlers[$name] ) ) {
107 return self
::$handlers[$name];
115 * Call hook functions defined in Hooks::register
117 * Because programmers assign to $wgHooks, we need to be very
118 * careful about its contents. So, there's a lot more error-checking
119 * in here than would normally be necessary.
121 * @param $event String: event name
122 * @param $args Array: parameters passed to hook functions
125 public static function run( $event, $args = array() ) {
129 // Return quickly in the most common case
130 if ( !isset( self
::$handlers[$event] ) && !isset( $wgHooks[$event] ) ) {
134 if (!is_array(self
::$handlers)) {
135 throw new MWException("Local hooks array is not an array!\n");
138 if (!is_array($wgHooks)) {
139 throw new MWException("Global hooks array is not an array!\n");
142 $new_handlers = (array) self
::$handlers;
143 $old_handlers = (array) $wgHooks;
145 $hook_array = array_merge( $new_handlers, $old_handlers );
147 if ( !is_array($hook_array[$event]) ) {
148 throw new MWException("Hooks array for event '$event' is not an array!\n");
151 foreach ($hook_array[$event] as $index => $hook) {
161 /* $hook can be: a function, an object, an array of $function and $data,
162 * an array of just a function, an array of object and method, or an
163 * array of object, method, and data.
166 if ( is_array( $hook ) ) {
167 if ( count( $hook ) < 1 ) {
168 throw new MWException("Empty array in hooks for " . $event . "\n");
169 } else if ( is_object( $hook[0] ) ) {
170 $object = $hook_array[$event][$index][0];
171 if ( $object instanceof Closure
) {
173 if ( count( $hook ) > 1 ) {
178 if ( count( $hook ) < 2 ) {
179 $method = "on" . $event;
182 if ( count( $hook ) > 2 ) {
188 } else if ( is_string( $hook[0] ) ) {
190 if ( count( $hook ) > 1) {
195 throw new MWException( "Unknown datatype in hooks for " . $event . "\n" );
197 } else if ( is_string( $hook ) ) { # functions look like strings, too
199 } else if ( is_object( $hook ) ) {
200 $object = $hook_array[$event][$index];
201 if ( $object instanceof Closure
) {
204 $method = "on" . $event;
207 throw new MWException( "Unknown datatype in hooks for " . $event . "\n" );
210 /* We put the first data element on, if needed. */
213 $hook_args = array_merge(array($data), $args);
220 $func = "hook-$event-closure";
221 } elseif ( isset( $object ) ) {
222 $func = get_class( $object ) . '::' . $method;
223 $callback = array( $object, $method );
224 } elseif ( false !== ( $pos = strpos( $func, '::' ) ) ) {
225 $callback = array( substr( $func, 0, $pos ), substr( $func, $pos +
2 ) );
230 // Run autoloader (workaround for call_user_func_array bug)
231 is_callable( $callback );
233 /* Call the hook. The documentation of call_user_func_array clearly
234 * states that FALSE is returned on failure. However this is not
235 * case always. In some version of PHP if the function signature
236 * does not match the call signature, PHP will issue an warning:
237 * Param y in x expected to be a reference, value given.
239 * In that case the call will also return null. The following code
240 * catches that warning and provides better error message. The
241 * function documentation also says that:
242 * In other words, it does not depend on the function signature
243 * whether the parameter is passed by a value or by a reference.
244 * There is also PHP bug http://bugs.php.net/bug.php?id=47554 which
245 * is unsurprisingly marked as bogus. In short handling of failures
246 * with call_user_func_array is a failure, the documentation for that
247 * function is wrong and misleading and PHP developers don't see any
251 set_error_handler( array( 'Hooks', 'hookErrorHandler' ) );
252 wfProfileIn( $func );
254 $retval = call_user_func_array( $callback, $hook_args );
255 } catch ( MWHookException
$e ) {
256 $badhookmsg = $e->getMessage();
258 wfProfileOut( $func );
259 restore_error_handler();
261 /* String return is an error; false return means stop processing. */
262 if ( is_string( $retval ) ) {
264 $wgOut->showFatalError( $retval );
266 } elseif( $retval === null ) {
268 $prettyFunc = "$event closure";
269 } elseif( is_array( $callback ) ) {
270 if( is_object( $callback[0] ) ) {
271 $prettyClass = get_class( $callback[0] );
273 $prettyClass = strval( $callback[0] );
275 $prettyFunc = $prettyClass . '::' . strval( $callback[1] );
277 $prettyFunc = strval( $callback );
280 throw new MWException( "Detected bug in an extension! " .
281 "Hook $prettyFunc has invalid call signature; " . $badhookmsg );
283 throw new MWException( "Detected bug in an extension! " .
284 "Hook $prettyFunc failed to return a value; " .
285 "should return true to continue hook processing or false to abort." );
287 } else if ( !$retval ) {
295 //This REALLY should be protected... but it's public for compatibility
296 public static function hookErrorHandler( $errno, $errstr ) {
297 if ( strpos( $errstr, 'expected to be a reference, value given' ) !== false ) {
298 throw new MWHookException( $errstr );