includes/Hooks.php

   1 <?php
   2 /**
   3  * A tool for running hook functions.
   4  *
   5  * Copyright 2004, 2005 Evan Prodromou <evan@wikitravel.org>.
   6  *
   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.
  11  *
  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.
  16  *
  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
  20  *
  21  * @author Evan Prodromou <evan@wikitravel.org>
  22  * @see hooks.txt
  23  * @file
  24  */
  25
  26
  27 /**
  28  * Call hook functions defined in $wgHooks
  29  *
  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.
  33  *
  34  * @param $event String: event name
  35  * @param $args Array: parameters passed to hook functions
  36  * @return Boolean
  37  */
  38 function wfRunHooks($event, $args = array()) {
  39
  40         global $wgHooks;
  41
  42         // Return quickly in the most common case
  43         if ( !isset( $wgHooks[$event] ) ) {
  44                 return true;
  45         }
  46
  47         if (!is_array($wgHooks)) {
  48                 throw new MWException("Global hooks array is not an array!\n");
  49                 return false;
  50         }
  51
  52         if (!is_array($wgHooks[$event])) {
  53                 throw new MWException("Hooks array for event '$event' is not an array!\n");
  54                 return false;
  55         }
  56
  57         foreach ($wgHooks[$event] as $index => $hook) {
  58
  59                 $object = null;
  60                 $method = null;
  61                 $func = null;
  62                 $data = null;
  63                 $have_data = false;
  64                 $closure = false;
  65                 $badhookmsg = false;
  66
  67                 /* $hook can be: a function, an object, an array of $function and $data,
  68                  * an array of just a function, an array of object and method, or an
  69                  * array of object, method, and data.
  70                  */
  71
  72                 if ( is_array( $hook ) ) {
  73                         if ( count( $hook ) < 1 ) {
  74                                 throw new MWException("Empty array in hooks for " . $event . "\n");
  75                         } else if ( is_object( $hook[0] ) ) {
  76                                 $object = $wgHooks[$event][$index][0];
  77                                 if ( $object instanceof Closure ) {
  78                                         $closure = true;
  79                                         if ( count( $hook ) > 1 ) {
  80                                                 $data = $hook[1];
  81                                                 $have_data = true;
  82                                         }
  83                                 } else {
  84                                         if ( count( $hook ) < 2 ) {
  85                                                 $method = "on" . $event;
  86                                         } else {
  87                                                 $method = $hook[1];
  88                                                 if ( count( $hook ) > 2 ) {
  89                                                         $data = $hook[2];
  90                                                         $have_data = true;
  91                                                 }
  92                                         }
  93                                 }
  94                         } else if ( is_string( $hook[0] ) ) {
  95                                 $func = $hook[0];
  96                                 if ( count( $hook ) > 1) {
  97                                         $data = $hook[1];
  98                                         $have_data = true;
  99                                 }
 100                         } else {
 101                                 throw new MWException( "Unknown datatype in hooks for " . $event . "\n" );
 102                         }
 103                 } else if ( is_string( $hook ) ) { # functions look like strings, too
 104                         $func = $hook;
 105                 } else if ( is_object( $hook ) ) {
 106                         $object = $wgHooks[$event][$index];
 107                         if ( $object instanceof Closure ) {
 108                                 $closure = true;
 109                         } else {
 110                                 $method = "on" . $event;
 111                         }
 112                 } else {
 113                         throw new MWException( "Unknown datatype in hooks for " . $event . "\n" );
 114                 }
 115
 116                 /* We put the first data element on, if needed. */
 117
 118                 if ( $have_data ) {
 119                         $hook_args = array_merge(array($data), $args);
 120                 } else {
 121                         $hook_args = $args;
 122                 }
 123
 124                 if ( $closure ) {
 125                         $callback = $object;
 126                         $func = "hook-$event-closure";
 127                 } elseif ( isset( $object ) ) {
 128                         $func = get_class( $object ) . '::' . $method;
 129                         $callback = array( $object, $method );
 130                 } elseif ( false !== ( $pos = strpos( $func, '::' ) ) ) {
 131                         $callback = array( substr( $func, 0, $pos ), substr( $func, $pos + 2 ) );
 132                 } else {
 133                         $callback = $func;
 134                 }
 135
 136                 // Run autoloader (workaround for call_user_func_array bug)
 137                 is_callable( $callback );
 138
 139                 /* Call the hook. The documentation of call_user_func_array clearly
 140                  * states that FALSE is returned on failure. However this is not
 141                  * case always. In some version of PHP if the function signature
 142                  * does not match the call signature, PHP will issue an warning:
 143                  * Param y in x expected to be a reference, value given.
 144                  *
 145                  * In that case the call will also return null. The following code
 146                  * catches that warning and provides better error message. The
 147                  * function documentation also says that:
 148                  *     In other words, it does not depend on the function signature
 149                  *     whether the parameter is passed by a value or by a reference.
 150                  * There is also PHP bug http://bugs.php.net/bug.php?id=47554 which
 151                  * is unsurprisingly marked as bogus. In short handling of failures
 152                  * with call_user_func_array is a failure, the documentation for that
 153                  * function is wrong and misleading and PHP developers don't see any
 154                  * problem here.
 155                  */
 156                 $retval = null;
 157                 set_error_handler( 'hookErrorHandler' );
 158                 wfProfileIn( $func );
 159                 try {
 160                         $retval = call_user_func_array( $callback, $hook_args );
 161                 } catch ( MWHookException $e ) {
 162                         $badhookmsg = $e->getMessage();
 163                 }
 164                 wfProfileOut( $func );
 165                 restore_error_handler();
 166
 167                 /* String return is an error; false return means stop processing. */
 168                 if ( is_string( $retval ) ) {
 169                         global $wgOut;
 170                         $wgOut->showFatalError( $retval );
 171                         return false;
 172                 } elseif( $retval === null ) {
 173                         if ( $closure ) {
 174                                 $prettyFunc = "$event closure";
 175                         } elseif( is_array( $callback ) ) {
 176                                 if( is_object( $callback[0] ) ) {
 177                                         $prettyClass = get_class( $callback[0] );
 178                                 } else {
 179                                         $prettyClass = strval( $callback[0] );
 180                                 }
 181                                 $prettyFunc = $prettyClass . '::' . strval( $callback[1] );
 182                         } else {
 183                                 $prettyFunc = strval( $callback );
 184                         }
 185                         if ( $badhookmsg ) {
 186                                 throw new MWException( "Detected bug in an extension! " .
 187                                 "Hook $prettyFunc has invalid call signature; " . $badhookmsg );
 188                         } else {
 189                                 throw new MWException( "Detected bug in an extension! " .
 190                                         "Hook $prettyFunc failed to return a value; " .
 191                                         "should return true to continue hook processing or false to abort." );
 192                         }
 193                 } else if ( !$retval ) {
 194                         return false;
 195                 }
 196         }
 197
 198         return true;
 199 }
 200
 201 function hookErrorHandler( $errno, $errstr ) {
 202         if ( strpos( $errstr, 'expected to be a reference, value given' ) !== false ) {
 203                 throw new MWHookException( $errstr );
 204         }
 205         return false;
 206 }
 207
 208 class MWHookException extends MWException {}