summaryrefslogtreecommitdiff
path: root/includes/Hooks.php
blob: dd08d03bf563d2984e23f90f07f223b1c3b0cb14 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
<?php
/**
 * A tool for running hook functions.
 *
 * Copyright 2004, 2005 Evan Prodromou <evan@wikitravel.org>.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
 *
 * @author Evan Prodromou <evan@wikitravel.org>
 * @see hooks.txt
 * @file
 */

class MWHookException extends MWException {}

/**
 * Hooks class.
 *
 * Used to supersede $wgHooks, because globals are EVIL.
 */
class Hooks {

	protected static $handlers = array();

	/**
	 * Attach an event handler to a given hook
	 *
	 * @param $name Mixed: name of hook
	 * @param $callback Mixed: callback function to attach
	 * @return void
	 */
	public static function register( $name, $callback ) {
		if( !isset( self::$handlers[$name] ) ) {
			self::$handlers[$name] = array();
		}

		self::$handlers[$name][] = $callback;
	}

	/**
	 * Returns true if a hook has a function registered to it.
	 *
	 * @param $name Mixed: name of hook
	 * @return Boolean: true if a hook has a function registered to it
	 */
	public static function isRegistered( $name ) {
		if( !isset( self::$handlers[$name] ) ) {
			self::$handlers[$name] = array();
		}

		return ( count( self::$handlers[$name] ) != 0 );
	}

	/**
	 * Returns an array of all the event functions attached to a hook
	 *
	 * @param $name Mixed: name of the hook
	 * @return array
	 */
	public static function getHandlers( $name ) {
		if( !isset( self::$handlers[$name] ) ) {
			return array();
		}

		return self::$handlers[$name];
	}

	/**
	 * Call hook functions defined in Hooks::register
	 *
	 * Because programmers assign to $wgHooks, we need to be very
	 * careful about its contents. So, there's a lot more error-checking
	 * in here than would normally be necessary.
	 *
	 * @param $event String: event name
	 * @param $args Array: parameters passed to hook functions
	 * @return Boolean
	 */
	public static function run( $event, $args = array() ) {
		global $wgHooks;

		// Return quickly in the most common case
		if ( !isset( self::$handlers[$event] ) && !isset( $wgHooks[$event] ) ) {
			return true;
		}

		if ( !is_array( self::$handlers ) ) {
			throw new MWException( "Local hooks array is not an array!\n" );
		}

		if ( !is_array( $wgHooks ) ) {
			throw new MWException( "Global hooks array is not an array!\n" );
		}

		$new_handlers = (array) self::$handlers;
		$old_handlers = (array) $wgHooks;

		$hook_array = array_merge( $new_handlers, $old_handlers );

		if ( !is_array( $hook_array[$event] ) ) {
			throw new MWException( "Hooks array for event '$event' is not an array!\n" );
		}

		foreach ( $hook_array[$event] as $index => $hook ) {
			$object = null;
			$method = null;
			$func = null;
			$data = null;
			$have_data = false;
			$closure = false;
			$badhookmsg = false;

			/**
			 * $hook can be: a function, an object, an array of $function and
			 * $data, an array of just a function, an array of object and
			 * method, or an array of object, method, and data.
			 */
			if ( is_array( $hook ) ) {
				if ( count( $hook ) < 1 ) {
					throw new MWException( 'Empty array in hooks for ' . $event . "\n" );
				} elseif ( is_object( $hook[0] ) ) {
					$object = $hook_array[$event][$index][0];
					if ( $object instanceof Closure ) {
						$closure = true;
						if ( count( $hook ) > 1 ) {
							$data = $hook[1];
							$have_data = true;
						}
					} else {
						if ( count( $hook ) < 2 ) {
							$method = 'on' . $event;
						} else {
							$method = $hook[1];
							if ( count( $hook ) > 2 ) {
								$data = $hook[2];
								$have_data = true;
							}
						}
					}
				} elseif ( is_string( $hook[0] ) ) {
					$func = $hook[0];
					if ( count( $hook ) > 1) {
						$data = $hook[1];
						$have_data = true;
					}
				} else {
					throw new MWException( 'Unknown datatype in hooks for ' . $event . "\n" );
				}
			} elseif ( is_string( $hook ) ) { # functions look like strings, too
				$func = $hook;
			} elseif ( is_object( $hook ) ) {
				$object = $hook_array[$event][$index];
				if ( $object instanceof Closure ) {
					$closure = true;
				} else {
					$method = "on" . $event;
				}
			} else {
				throw new MWException( 'Unknown datatype in hooks for ' . $event . "\n" );
			}

			/* We put the first data element on, if needed. */
			if ( $have_data ) {
				$hook_args = array_merge( array( $data ), $args );
			} else {
				$hook_args = $args;
			}

			if ( $closure ) {
				$callback = $object;
				$func = "hook-$event-closure";
			} elseif ( isset( $object ) ) {
				$func = get_class( $object ) . '::' . $method;
				$callback = array( $object, $method );
			} else {
				$callback = $func;
			}

			// Run autoloader (workaround for call_user_func_array bug)
			is_callable( $callback );

			/**
			 * Call the hook. The documentation of call_user_func_array clearly
			 * states that FALSE is returned on failure. However this is not
			 * case always. In some version of PHP if the function signature
			 * does not match the call signature, PHP will issue an warning:
			 * Param y in x expected to be a reference, value given.
			 *
			 * In that case the call will also return null. The following code
			 * catches that warning and provides better error message. The
			 * function documentation also says that:
			 *     In other words, it does not depend on the function signature
			 *     whether the parameter is passed by a value or by a reference.
			 * There is also PHP bug http://bugs.php.net/bug.php?id=47554 which
			 * is unsurprisingly marked as bogus. In short handling of failures
			 * with call_user_func_array is a failure, the documentation for that
			 * function is wrong and misleading and PHP developers don't see any
			 * problem here.
			 */
			$retval = null;
			set_error_handler( 'Hooks::hookErrorHandler' );
			wfProfileIn( $func );
			try {
				$retval = call_user_func_array( $callback, $hook_args );
			} catch ( MWHookException $e ) {
				$badhookmsg = $e->getMessage();
			}
			wfProfileOut( $func );
			restore_error_handler();

			/* String return is an error; false return means stop processing. */
			if ( is_string( $retval ) ) {
				global $wgOut;
				$wgOut->showFatalError( $retval );
				return false;
			} elseif( $retval === null ) {
				if ( $closure ) {
					$prettyFunc = "$event closure";
				} elseif( is_array( $callback ) ) {
					if( is_object( $callback[0] ) ) {
						$prettyClass = get_class( $callback[0] );
					} else {
						$prettyClass = strval( $callback[0] );
					}
					$prettyFunc = $prettyClass . '::' . strval( $callback[1] );
				} else {
					$prettyFunc = strval( $callback );
				}
				if ( $badhookmsg ) {
					throw new MWException(
						'Detected bug in an extension! ' .
						"Hook $prettyFunc has invalid call signature; " . $badhookmsg
					);
				} else {
					throw new MWException(
						'Detected bug in an extension! ' .
						"Hook $prettyFunc failed to return a value; " .
						'should return true to continue hook processing or false to abort.'
					);
				}
			} elseif ( !$retval ) {
				return false;
			}
		}

		return true;
	}

	/**
	 * This REALLY should be protected... but it's public for compatibility
	 *
	 * @param $errno Unused
	 * @param $errstr String: error message
	 * @return Boolean: false
	 */
	public static function hookErrorHandler( $errno, $errstr ) {
		if ( strpos( $errstr, 'expected to be a reference, value given' ) !== false ) {
			throw new MWHookException( $errstr );
		}
		return false;
	}
}