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                         throw new MWException( "Unknown datatype in hooks for " . $event . "\n" );
  55                 }
  56         } else if ( is_string( $hook ) ) { # functions look like strings, too
  57                 $func = $hook;
  58         } else if ( is_object( $hook ) ) {
  59                 $object = $hook;
  60                 $method = "on" . $event;
  61         } else {
  62                 throw new MWException("Unknown datatype in hooks for " . $event . "\n");
  63         }
  64
  65         if ( isset( $object ) ) {
  66                 $func = get_class( $object ) . '::' . $method;
  67                 $callback = array( $object, $method );
  68         } elseif ( false !== ( $pos = strpos( $func, '::' ) ) ) {
  69                 $callback = array( substr( $func, 0, $pos ), substr( $func, $pos + 2 ) );
  70         } else {
  71                 $callback = $func;
  72         }
  73
  74         return array($callback, $func, $data);
  75 }
  76
  77 /* Return a string describing the hook for debugging purposes. */
  78 function wfFormatInvocation( $event, $hook, $args = array() ) {
  79         list( $callback, $func, $data ) = _wfInvokeInternalGoop( $event, $hook, $args );
  80
  81         if( is_array( $callback ) ) {
  82                 if( is_object( $callback[0] ) ) {
  83                         $prettyClass = get_class( $callback[0] );
  84                 } else {
  85                         $prettyClass = strval( $callback[0] );
  86                 }
  87                 $prettyFunc = $prettyClass . '::' . strval( $callback[1] );
  88         } else {
  89                 $prettyFunc = strval( $callback );
  90         }
  91         return $prettyFunc;
  92 }
  93
  94
  95 /*
  96  * Invoke a function dynamically.
  97  * $event is the name of the invocation; this is used if the hook specifies
  98  * an object but no method name; 'on$event' is then invoked on the object.
  99  * $hook can be: a function, an object, an array of $function and $data,
 100  * an array of just a function, an array of object and method, or an
 101  * array of object, method, and data.
 102  * If arguments are provided both as part of the hook itself, and when
 103  * calling wfCallFancyCallback, the two arrays are merged.
 104  */
 105 function wfInvoke( $event, $hook, $args = array() ) {
 106         list( $callback, $func, $data ) = _wfInvokeInternalGoop( $event, $hook, $args );
 107
 108         /* We put the first data element on, if needed. */
 109         if ( $data ) {
 110                 $hook_args = array_merge( array( $data ), $args );
 111         } else {
 112                 $hook_args = $args;
 113         }
 114
 115         // Run autoloader (workaround for call_user_func_array bug)
 116         is_callable( $callback );
 117
 118         /* Call the hook. */
 119         wfProfileIn( $func );
 120         $retval = call_user_func_array( $callback, $hook_args );
 121         wfProfileOut( $func );
 122         return $retval;
 123 }
 124
 125
 126 /**
 127  * Because programmers assign to $wgHooks, we need to be very
 128  * careful about its contents. So, there's a lot more error-checking
 129  * in here than would normally be necessary.
 130  */
 131 function wfRunHooks( $event, $args = array() ) {
 132
 133         global $wgHooks;
 134
 135         if ( !is_array( $wgHooks ) ) {
 136                 throw new MWException( "Global hooks array is not an array!\n" );
 137                 return false;
 138         }
 139
 140         if (!array_key_exists( $event, $wgHooks ) ) {
 141                 return true;
 142         }
 143
 144         if ( !is_array( $wgHooks[$event] ) ) {
 145                 throw new MWException( "Hooks array for event '$event' is not an array!\n" );
 146                 return false;
 147         }
 148
 149         foreach ( $wgHooks[$event] as $index => $hook ) {
 150
 151                 $retval = wfInvoke( $event, $hook, $args );
 152
 153                 /* String return is an error; false return means stop processing. */
 154
 155                 if ( is_string( $retval ) ) {
 156                         global $wgOut;
 157                         $wgOut->showFatalError( $retval );
 158                         return false;
 159                 } elseif( $retval === null ) {
 160                         $prettyFunc = wfFormatInvocation( $event, $hook, $args );
 161                         throw new MWException( "Detected bug in an extension! " .
 162                                 "Hook $prettyFunc failed to return a value; " .
 163                                 "should return true to continue hook processing or false to abort." );
 164                 } else if ( !$retval ) {
 165                         return false;
 166                 }
 167         }
 168
 169         return true;
 170 }