includes/Hooks.php

   1 <?php
   2 /**
   3  * Hooks.php -- a tool for running hook functions
   4  * Copyright 2004, 2005 Evan Prodromou <evan@wikitravel.org>.
   5  *
   6  *  This program is free software; you can redistribute it and/or modify
   7  *  it under the terms of the GNU General Public License as published by
   8  *  the Free Software Foundation; either version 2 of the License, or
   9  *  (at your option) any later version.
  10  *
  11  *  This program is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  *  GNU General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU General Public License
  17  *  along with this program; if not, write to the Free Software
  18  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
  19  *
  20  * @author Evan Prodromou <evan@wikitravel.org>
  21  * @see hooks.txt
  22  * @file
  23  */
  24
  25 /* Private */
  26 function _wfInvokeInternalGoop($event, $hook) {
  27         $object = NULL;
  28         $method = NULL;
  29         $func = NULL;
  30         $data = NULL;
  31         $have_data = false;
  32
  33         if (is_array($hook)) {
  34                 if (count($hook) < 1) {
  35                         throw new MWException("Empty array in hooks for " . $event . "\n");
  36                 } else if (is_object($hook[0])) {
  37                         $object = $hook[0];
  38                         if (count($hook) < 2) {
  39                                 $method = "on" . $event;
  40                         } else {
  41                                 $method = $hook[1];
  42                                 if (count($hook) > 2) {
  43                                         $data = $hook[2];
  44                                         $have_data = true;
  45                                 }
  46                         }
  47                 } else if (is_string($hook[0])) {
  48                         $func = $hook[0];
  49                         if (count($hook) > 1) {
  50                                 $data = $hook[1];
  51                                 $have_data = true;
  52                         }
  53                 } else {
  54                         var_dump( $wgHooks );
  55                         throw new MWException("Unknown datatype in hooks for " . $event . "\n");
  56                 }
  57         } else if (is_string($hook)) { # functions look like strings, too
  58                 $func = $hook;
  59         } else if (is_object($hook)) {
  60                 $object = $hook;
  61                 $method = "on" . $event;
  62         } else {
  63                 throw new MWException("Unknown datatype in hooks for " . $event . "\n");
  64         }
  65
  66         if ( isset( $object ) ) {
  67                 $func = get_class( $object ) . '::' . $method;
  68                 $callback = array( $object, $method );
  69         } elseif ( false !== ( $pos = strpos( $func, '::' ) ) ) {
  70                 $callback = array( substr( $func, 0, $pos ), substr( $func, $pos + 2 ) );
  71         } else {
  72                 $callback = $func;
  73         }
  74
  75         return array($callback, $func, $data);
  76 }
  77
  78 /* Return a string describing the hook for debugging purposes. */
  79 function wfFormatInvocation($event, $hook, $args = array()) {
  80         list($callback, $func, $data) = _wfInvokeInternalGoop($event, $hook, $args);
  81
  82         if( is_array( $callback ) ) {
  83                 if( is_object( $callback[0] ) ) {
  84                         $prettyClass = get_class( $callback[0] );
  85                 } else {
  86                         $prettyClass = strval( $callback[0] );
  87                 }
  88                 $prettyFunc = $prettyClass . '::' . strval( $callback[1] );
  89         } else {
  90                 $prettyFunc = strval( $callback );
  91         }
  92         return $prettyFunc;
  93 }
  94
  95
  96 /*
  97  * Invoke a function dynamically.
  98  * $event is the name of the invocation; this is used if the hook specifies
  99  * an object but no method name; 'on$event' is then invoked on the object.
 100  * $hook can be: a function, an object, an array of $function and $data,
 101  * an array of just a function, an array of object and method, or an
 102  * array of object, method, and data.
 103  * If arguments are provided both as part of the hook itself, and when
 104  * calling wfCallFancyCallback, the two arrays are merged.
 105  */
 106 function wfInvoke($event, $hook, $args = array()) {
 107         list($callback, $func, $data) = _wfInvokeInternalGoop($event, $hook, $args);
 108
 109         /* We put the first data element on, if needed. */
 110         if ($data) {
 111                 $hook_args = array_merge(array($data), $args);
 112         } else {
 113                 $hook_args = $args;
 114         }
 115
 116         // Run autoloader (workaround for call_user_func_array bug)
 117         is_callable( $callback );
 118
 119         /* Call the hook. */
 120         wfProfileIn( $func );
 121         $retval = call_user_func_array( $callback, $hook_args );
 122         wfProfileOut( $func );
 123         return $retval;
 124 }
 125
 126
 127 /**
 128  * Because programmers assign to $wgHooks, we need to be very
 129  * careful about its contents. So, there's a lot more error-checking
 130  * in here than would normally be necessary.
 131  */
 132 function wfRunHooks($event, $args = array()) {
 133
 134         global $wgHooks;
 135
 136         if (!is_array($wgHooks)) {
 137                 throw new MWException("Global hooks array is not an array!\n");
 138                 return false;
 139         }
 140
 141         if (!array_key_exists($event, $wgHooks)) {
 142                 return true;
 143         }
 144
 145         if (!is_array($wgHooks[$event])) {
 146                 throw new MWException("Hooks array for event '$event' is not an array!\n");
 147                 return false;
 148         }
 149
 150         foreach ($wgHooks[$event] as $index => $hook) {
 151
 152                 $retval = wfInvoke($event, $hook, $args);
 153
 154                 /* String return is an error; false return means stop processing. */
 155
 156                 if (is_string($retval)) {
 157                         global $wgOut;
 158                         $wgOut->showFatalError($retval);
 159                         return false;
 160                 } elseif( $retval === null ) {
 161                         $prettyFunc = wfFormatInvocation($event, $hook, $args);
 162                         throw new MWException( "Detected bug in an extension! " .
 163                                 "Hook $prettyFunc failed to return a value; " .
 164                                 "should return true to continue hook processing or false to abort." );
 165                 } else if (!$retval) {
 166                         return false;
 167                 }
 168         }
 169
 170         return true;
 171 }