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 * Attach an event handler to a given hook
47 * @param $name Mixed: name of hook
48 * @param $callback Mixed: callback function to attach
50 public static function register( $name, $callback ) {
51 if( !isset( self
::$handlers[$name] ) ) {
52 self
::$handlers[$name] = array();
55 self
::$handlers[$name][] = $callback;
59 * Returns true if a hook has a function registered to it.
63 * @param $name Mixed: name of hook
64 * @return Boolean: true if a hook has a function registered to it
66 public static function isRegistered( $name ) {
67 if( !isset( self
::$handlers[$name] ) ) {
68 self
::$handlers[$name] = array();
71 return ( count( self
::$handlers[$name] ) != 0 );
75 * Returns an array of all the event functions attached to a hook
79 * @param $name Mixed: name of the hook
82 public static function getHandlers( $name ) {
83 if( !isset( self
::$handlers[$name] ) ) {
87 return self
::$handlers[$name];
91 * Call hook functions defined in Hooks::register
93 * Because programmers assign to $wgHooks, we need to be very
94 * careful about its contents. So, there's a lot more error-checking
95 * in here than would normally be necessary.
99 * @param $event String: event name
100 * @param $args Array: parameters passed to hook functions
101 * @throws MWException
103 * @return Boolean True if no handler aborted the hook
105 public static function run( $event, $args = array() ) {
108 // Return quickly in the most common case
109 if ( !isset( self
::$handlers[$event] ) && !isset( $wgHooks[$event] ) ) {
113 if ( !is_array( self
::$handlers ) ) {
114 throw new MWException( "Local hooks array is not an array!\n" );
117 if ( !is_array( $wgHooks ) ) {
118 throw new MWException( "Global hooks array is not an array!\n" );
121 $new_handlers = (array) self
::$handlers;
122 $old_handlers = (array) $wgHooks;
124 $hook_array = array_merge( $new_handlers, $old_handlers );
126 if ( !is_array( $hook_array[$event] ) ) {
127 throw new MWException( "Hooks array for event '$event' is not an array!\n" );
130 foreach ( $hook_array[$event] as $index => $hook ) {
140 * $hook can be: a function, an object, an array of $function and
141 * $data, an array of just a function, an array of object and
142 * method, or an array of object, method, and data.
144 if ( is_array( $hook ) ) {
145 if ( count( $hook ) < 1 ) {
146 throw new MWException( 'Empty array in hooks for ' . $event . "\n" );
147 } elseif ( is_object( $hook[0] ) ) {
148 $object = $hook_array[$event][$index][0];
149 if ( $object instanceof Closure
) {
151 if ( count( $hook ) > 1 ) {
156 if ( count( $hook ) < 2 ) {
157 $method = 'on' . $event;
160 if ( count( $hook ) > 2 ) {
166 } elseif ( is_string( $hook[0] ) ) {
168 if ( count( $hook ) > 1) {
173 throw new MWException( 'Unknown datatype in hooks for ' . $event . "\n" );
175 } elseif ( is_string( $hook ) ) { # functions look like strings, too
177 } elseif ( is_object( $hook ) ) {
178 $object = $hook_array[$event][$index];
179 if ( $object instanceof Closure
) {
182 $method = "on" . $event;
185 throw new MWException( 'Unknown datatype in hooks for ' . $event . "\n" );
188 /* We put the first data element on, if needed. */
190 $hook_args = array_merge( array( $data ), $args );
197 $func = "hook-$event-closure";
198 } elseif ( isset( $object ) ) {
199 $func = get_class( $object ) . '::' . $method;
200 $callback = array( $object, $method );
205 // Run autoloader (workaround for call_user_func_array bug)
206 is_callable( $callback );
209 * Call the hook. The documentation of call_user_func_array clearly
210 * states that FALSE is returned on failure. However this is not
211 * case always. In some version of PHP if the function signature
212 * does not match the call signature, PHP will issue an warning:
213 * Param y in x expected to be a reference, value given.
215 * In that case the call will also return null. The following code
216 * catches that warning and provides better error message. The
217 * function documentation also says that:
218 * In other words, it does not depend on the function signature
219 * whether the parameter is passed by a value or by a reference.
220 * There is also PHP bug http://bugs.php.net/bug.php?id=47554 which
221 * is unsurprisingly marked as bogus. In short handling of failures
222 * with call_user_func_array is a failure, the documentation for that
223 * function is wrong and misleading and PHP developers don't see any
227 set_error_handler( 'Hooks::hookErrorHandler' );
228 wfProfileIn( $func );
230 $retval = call_user_func_array( $callback, $hook_args );
231 } catch ( MWHookException
$e ) {
232 $badhookmsg = $e->getMessage();
234 wfProfileOut( $func );
235 restore_error_handler();
237 /* String return is an error; false return means stop processing. */
238 if ( is_string( $retval ) ) {
239 throw new FatalError( $retval );
240 } elseif( $retval === null ) {
242 $prettyFunc = "$event closure";
243 } elseif( is_array( $callback ) ) {
244 if( is_object( $callback[0] ) ) {
245 $prettyClass = get_class( $callback[0] );
247 $prettyClass = strval( $callback[0] );
249 $prettyFunc = $prettyClass . '::' . strval( $callback[1] );
251 $prettyFunc = strval( $callback );
254 throw new MWException(
255 'Detected bug in an extension! ' .
256 "Hook $prettyFunc has invalid call signature; " . $badhookmsg
259 throw new MWException(
260 'Detected bug in an extension! ' .
261 "Hook $prettyFunc failed to return a value; " .
262 'should return true to continue hook processing or false to abort.'
265 } elseif ( !$retval ) {
274 * This REALLY should be protected... but it's public for compatibility
278 * @param $errno int Unused
279 * @param $errstr String: error message
280 * @throws MWHookException
281 * @return Boolean: false
283 public static function hookErrorHandler( $errno, $errstr ) {
284 if ( strpos( $errstr, 'expected to be a reference, value given' ) !== false ) {
285 throw new MWHookException( $errstr );