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($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($hook) {
  80         list($callback, $func, $data) = _wfInvokeInternalGoop($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  * $hook can be: a function, an object, an array of $function and $data,
  99  * an array of just a function, an array of object and method, or an
 100  * array of object, method, and data.
 101  * If arguments are provided both as part of the hook itself, and when
 102  * calling wfCallFancyCallback, the two arrays are merged.
 103  */
 104 function wfInvoke($hook, $args = array()) {
 105         list($callback, $func, $data) = _wfInvokeInternalGoop($hook, $args);
 106
 107         /* We put the first data element on, if needed. */
 108         if ($data) {
 109                 $hook_args = array_merge(array($data), $args);
 110         } else {
 111                 $hook_args = $args;
 112         }
 113
 114         // Run autoloader (workaround for call_user_func_array bug)
 115         is_callable( $callback );
 116
 117         /* Call the hook. */
 118         wfProfileIn( $func );
 119         $retval = call_user_func_array( $callback, $hook_args );
 120         wfProfileOut( $func );
 121         return $retval;
 122 }
 123
 124
 125 /**
 126  * Because programmers assign to $wgHooks, we need to be very
 127  * careful about its contents. So, there's a lot more error-checking
 128  * in here than would normally be necessary.
 129  */
 130 function wfRunHooks($event, $args = array()) {
 131
 132         global $wgHooks;
 133
 134         if (!is_array($wgHooks)) {
 135                 throw new MWException("Global hooks array is not an array!\n");
 136                 return false;
 137         }
 138
 139         if (!array_key_exists($event, $wgHooks)) {
 140                 return true;
 141         }
 142
 143         if (!is_array($wgHooks[$event])) {
 144                 throw new MWException("Hooks array for event '$event' is not an array!\n");
 145                 return false;
 146         }
 147
 148         foreach ($wgHooks[$event] as $index => $hook) {
 149
 150                 $retval = wfInvoke($hook, $args);
 151
 152                 /* String return is an error; false return means stop processing. */
 153
 154                 if (is_string($retval)) {
 155                         global $wgOut;
 156                         $wgOut->showFatalError($retval);
 157                         return false;
 158                 } elseif( $retval === null ) {
 159                         $prettyFunc = wfFormatInvocation($hook);
 160                         throw new MWException( "Detected bug in an extension! " .
 161                                 "Hook $prettyFunc failed to return a value; " .
 162                                 "should return true to continue hook processing or false to abort." );
 163                 } else if (!$retval) {
 164                         return false;
 165                 }
 166         }
 167
 168         return true;
 169 }