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>
26 class MWHookException
extends MWException
{}
31 * Used to supersede $wgHooks, because globals are EVIL.
35 protected static $handlers = array();
38 * Attach an event handler to a given hook
40 * @param $name Mixed: name of hook
41 * @param $callback Mixed: callback function to attach
44 public static function register( $name, $callback ) {
45 if( !isset( self
::$handlers[$name] ) ) {
46 self
::$handlers[$name] = array();
49 self
::$handlers[$name][] = $callback;
53 * Returns true if a hook has a function registered to it.
55 * @param $name Mixed: name of hook
56 * @return Boolean: true if a hook has a function registered to it
58 public static function isRegistered( $name ) {
59 if( !isset( self
::$handlers[$name] ) ) {
60 self
::$handlers[$name] = array();
63 return ( count( self
::$handlers[$name] ) != 0 );
67 * Returns an array of all the event functions attached to a hook
69 * @param $name Mixed: name of the hook
72 public static function getHandlers( $name ) {
73 if( !isset( self
::$handlers[$name] ) ) {
77 return self
::$handlers[$name];
81 * Call hook functions defined in Hooks::register
83 * Because programmers assign to $wgHooks, we need to be very
84 * careful about its contents. So, there's a lot more error-checking
85 * in here than would normally be necessary.
87 * @param $event String: event name
88 * @param $args Array: parameters passed to hook functions
89 * @return Boolean True if no handler aborted the hook
91 public static function run( $event, $args = array() ) {
94 // Return quickly in the most common case
95 if ( !isset( self
::$handlers[$event] ) && !isset( $wgHooks[$event] ) ) {
99 if ( !is_array( self
::$handlers ) ) {
100 throw new MWException( "Local hooks array is not an array!\n" );
103 if ( !is_array( $wgHooks ) ) {
104 throw new MWException( "Global hooks array is not an array!\n" );
107 $new_handlers = (array) self
::$handlers;
108 $old_handlers = (array) $wgHooks;
110 $hook_array = array_merge( $new_handlers, $old_handlers );
112 if ( !is_array( $hook_array[$event] ) ) {
113 throw new MWException( "Hooks array for event '$event' is not an array!\n" );
116 foreach ( $hook_array[$event] as $index => $hook ) {
126 * $hook can be: a function, an object, an array of $function and
127 * $data, an array of just a function, an array of object and
128 * method, or an array of object, method, and data.
130 if ( is_array( $hook ) ) {
131 if ( count( $hook ) < 1 ) {
132 throw new MWException( 'Empty array in hooks for ' . $event . "\n" );
133 } elseif ( is_object( $hook[0] ) ) {
134 $object = $hook_array[$event][$index][0];
135 if ( $object instanceof Closure
) {
137 if ( count( $hook ) > 1 ) {
142 if ( count( $hook ) < 2 ) {
143 $method = 'on' . $event;
146 if ( count( $hook ) > 2 ) {
152 } elseif ( is_string( $hook[0] ) ) {
154 if ( count( $hook ) > 1) {
159 throw new MWException( 'Unknown datatype in hooks for ' . $event . "\n" );
161 } elseif ( is_string( $hook ) ) { # functions look like strings, too
163 } elseif ( is_object( $hook ) ) {
164 $object = $hook_array[$event][$index];
165 if ( $object instanceof Closure
) {
168 $method = "on" . $event;
171 throw new MWException( 'Unknown datatype in hooks for ' . $event . "\n" );
174 /* We put the first data element on, if needed. */
176 $hook_args = array_merge( array( $data ), $args );
183 $func = "hook-$event-closure";
184 } elseif ( isset( $object ) ) {
185 $func = get_class( $object ) . '::' . $method;
186 $callback = array( $object, $method );
191 // Run autoloader (workaround for call_user_func_array bug)
192 is_callable( $callback );
195 * Call the hook. The documentation of call_user_func_array clearly
196 * states that FALSE is returned on failure. However this is not
197 * case always. In some version of PHP if the function signature
198 * does not match the call signature, PHP will issue an warning:
199 * Param y in x expected to be a reference, value given.
201 * In that case the call will also return null. The following code
202 * catches that warning and provides better error message. The
203 * function documentation also says that:
204 * In other words, it does not depend on the function signature
205 * whether the parameter is passed by a value or by a reference.
206 * There is also PHP bug http://bugs.php.net/bug.php?id=47554 which
207 * is unsurprisingly marked as bogus. In short handling of failures
208 * with call_user_func_array is a failure, the documentation for that
209 * function is wrong and misleading and PHP developers don't see any
213 set_error_handler( 'Hooks::hookErrorHandler' );
214 wfProfileIn( $func );
216 $retval = call_user_func_array( $callback, $hook_args );
217 } catch ( MWHookException
$e ) {
218 $badhookmsg = $e->getMessage();
220 wfProfileOut( $func );
221 restore_error_handler();
223 /* String return is an error; false return means stop processing. */
224 if ( is_string( $retval ) ) {
225 throw new FatalError( $retval );
226 } elseif( $retval === null ) {
228 $prettyFunc = "$event closure";
229 } elseif( is_array( $callback ) ) {
230 if( is_object( $callback[0] ) ) {
231 $prettyClass = get_class( $callback[0] );
233 $prettyClass = strval( $callback[0] );
235 $prettyFunc = $prettyClass . '::' . strval( $callback[1] );
237 $prettyFunc = strval( $callback );
240 throw new MWException(
241 'Detected bug in an extension! ' .
242 "Hook $prettyFunc has invalid call signature; " . $badhookmsg
245 throw new MWException(
246 'Detected bug in an extension! ' .
247 "Hook $prettyFunc failed to return a value; " .
248 'should return true to continue hook processing or false to abort.'
251 } elseif ( !$retval ) {
260 * This REALLY should be protected... but it's public for compatibility
262 * @param $errno int Unused
263 * @param $errstr String: error message
264 * @return Boolean: false
266 public static function hookErrorHandler( $errno, $errstr ) {
267 if ( strpos( $errstr, 'expected to be a reference, value given' ) !== false ) {
268 throw new MWHookException( $errstr );