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>
29 class MWHookException
extends MWException
{}
34 * Used to supersede $wgHooks, because globals are EVIL.
40 protected static $handlers = array();
43 * Clears hooks registered via Hooks::register(). Does not touch $wgHooks.
44 * This is intended for use while testing and will fail if MW_PHPUNIT_TEST is not defined.
48 * @param $name String: the name of the hook to clear.
50 * @throws MWException if not in testing mode.
52 public static function clear( $name ) {
53 if ( !defined( 'MW_PHPUNIT_TEST' ) ) {
54 throw new MWException( 'can not reset hooks in operation.' );
57 unset( self
::$handlers[$name] );
62 * Attach an event handler to a given hook
66 * @param $name String: name of hook
67 * @param $callback Mixed: callback function to attach
69 public static function register( $name, $callback ) {
70 if( !isset( self
::$handlers[$name] ) ) {
71 self
::$handlers[$name] = array();
74 self
::$handlers[$name][] = $callback;
78 * Returns true if a hook has a function registered to it.
79 * The function may have been registered either via Hooks::register or in $wgHooks.
83 * @param $name String: name of hook
84 * @return Boolean: true if the hook has a function registered to it
86 public static function isRegistered( $name ) {
89 return !empty( $wgHooks[$name] ) ||
!empty( self
::$handlers[$name] );
93 * Returns an array of all the event functions attached to a hook
94 * This combines functions registered via Hooks::register and with $wgHooks.
99 * @param $name String: name of the hook
103 public static function getHandlers( $name ) {
106 // Return quickly in the most common case
107 if ( empty( self
::$handlers[$name] ) && empty( $wgHooks[$name] ) ) {
111 if ( !is_array( self
::$handlers ) ) {
112 throw new MWException( "Local hooks array is not an array!\n" );
115 if ( !is_array( $wgHooks ) ) {
116 throw new MWException( "Global hooks array is not an array!\n" );
119 if ( empty( Hooks
::$handlers[$name] ) ) {
120 $hooks = $wgHooks[$name];
121 } elseif ( empty( $wgHooks[$name] ) ) {
122 $hooks = Hooks
::$handlers[$name];
124 // so they are both not empty...
125 $hooks = array_merge( Hooks
::$handlers[$name], $wgHooks[$name] );
128 if ( !is_array( $hooks ) ) {
129 throw new MWException( "Hooks array for event '$name' is not an array!\n" );
136 * Call hook functions defined in Hooks::register
138 * @param $event String: event name
139 * @param $args Array: parameters passed to hook functions
141 * @return Boolean True if no handler aborted the hook
143 public static function run( $event, $args = array() ) {
146 // Return quickly in the most common case
147 if ( empty( self
::$handlers[$event] ) && empty( $wgHooks[$event] ) ) {
151 $hooks = self
::getHandlers( $event );
153 foreach ( $hooks as $hook ) {
163 * $hook can be: a function, an object, an array of $function and
164 * $data, an array of just a function, an array of object and
165 * method, or an array of object, method, and data.
167 if ( is_array( $hook ) ) {
168 if ( count( $hook ) < 1 ) {
169 throw new MWException( 'Empty array in hooks for ' . $event . "\n" );
170 } elseif ( is_object( $hook[0] ) ) {
172 if ( $object instanceof Closure
) {
174 if ( count( $hook ) > 1 ) {
179 if ( count( $hook ) < 2 ) {
180 $method = 'on' . $event;
183 if ( count( $hook ) > 2 ) {
189 } elseif ( is_string( $hook[0] ) ) {
191 if ( count( $hook ) > 1) {
196 throw new MWException( 'Unknown datatype in hooks for ' . $event . "\n" );
198 } elseif ( is_string( $hook ) ) { # functions look like strings, too
200 } elseif ( is_object( $hook ) ) {
202 if ( $object instanceof Closure
) {
205 $method = "on" . $event;
208 throw new MWException( 'Unknown datatype in hooks for ' . $event . "\n" );
211 /* 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 );
228 // Run autoloader (workaround for call_user_func_array bug)
229 is_callable( $callback );
232 * Call the hook. The documentation of call_user_func_array clearly
233 * states that FALSE is returned on failure. However this is not
234 * case always. In some version of PHP if the function signature
235 * does not match the call signature, PHP will issue an warning:
236 * Param y in x expected to be a reference, value given.
238 * In that case the call will also return null. The following code
239 * catches that warning and provides better error message. The
240 * function documentation also says that:
241 * In other words, it does not depend on the function signature
242 * whether the parameter is passed by a value or by a reference.
243 * There is also PHP bug http://bugs.php.net/bug.php?id=47554 which
244 * is unsurprisingly marked as bogus. In short handling of failures
245 * with call_user_func_array is a failure, the documentation for that
246 * function is wrong and misleading and PHP developers don't see any
250 set_error_handler( 'Hooks::hookErrorHandler' );
251 wfProfileIn( $func );
253 $retval = call_user_func_array( $callback, $hook_args );
254 } catch ( MWHookException
$e ) {
255 $badhookmsg = $e->getMessage();
257 wfProfileOut( $func );
258 restore_error_handler();
260 /* String return is an error; false return means stop processing. */
261 if ( is_string( $retval ) ) {
262 throw new FatalError( $retval );
263 } elseif( $retval === null ) {
265 $prettyFunc = "$event closure";
266 } elseif( is_array( $callback ) ) {
267 if( is_object( $callback[0] ) ) {
268 $prettyClass = get_class( $callback[0] );
270 $prettyClass = strval( $callback[0] );
272 $prettyFunc = $prettyClass . '::' . strval( $callback[1] );
274 $prettyFunc = strval( $callback );
277 throw new MWException(
278 'Detected bug in an extension! ' .
279 "Hook $prettyFunc has invalid call signature; " . $badhookmsg
282 throw new MWException(
283 '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.'
288 } elseif ( !$retval ) {
297 * This REALLY should be protected... but it's public for compatibility
301 * @param $errno int Unused
302 * @param $errstr String: error message
303 * @throws MWHookException
304 * @return Boolean: false
306 public static function hookErrorHandler( $errno, $errstr ) {
307 if ( strpos( $errstr, 'expected to be a reference, value given' ) !== false ) {
308 throw new MWHookException( $errstr );