[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3  *
   4  * @package phpBB3
   5  * @version $Id$
   6  * @copyright (c) 2007 phpBB Group
   7  * @license http://opensource.org/licenses/gpl-license.php GNU Public License
   8  *
   9  */
  10  
  11  /**
  12  * @ignore
  13  */
  14  if (!defined('IN_PHPBB'))
  15  {
  16      exit;
  17  }
  18  
  19  /**
  20  * phpBB Hook Class
  21  * @package phpBB3
  22  */
  23  class phpbb_hook
  24  {
  25      /**
  26      * Registered hooks
  27      */
  28      var $hooks = array();
  29  
  30      /**
  31      * Results returned by functions called
  32      */
  33      var $hook_result = array();
  34  
  35      /**
  36      * internal pointer
  37      */
  38      var $current_hook = NULL;
  39  
  40      /**
  41      * Initialize hook class.
  42      *
  43      * @param array $valid_hooks array containing the hookable functions/methods
  44      */
  45  	function phpbb_hook($valid_hooks)
  46      {
  47          foreach ($valid_hooks as $_null => $method)
  48          {
  49              $this->add_hook($method);
  50          }
  51  
  52          if (function_exists('phpbb_hook_register'))
  53          {
  54              phpbb_hook_register($this);
  55          }
  56      }
  57  
  58      /**
  59      * Register function/method to be called within hook
  60      * This function is normally called by the modification/application to attach/register the functions.
  61      *
  62      * @param mixed $definition Declaring function (with __FUNCTION__) or class with array(__CLASS__, __FUNCTION__)
  63      * @param mixed $hook The replacement function/method to be called. Passing function name or array with object/class definition
  64      * @param string $mode Specify the priority/chain mode. 'normal' -> hook gets appended to the chain. 'standalone' -> only the specified hook gets called - later hooks are not able to overwrite this (E_NOTICE is triggered then). 'first' -> hook is called as the first one within the chain. 'last' -> hook is called as the last one within the chain.
  65      */
  66  	function register($definition, $hook, $mode = 'normal')
  67      {
  68          $class = (!is_array($definition)) ? '__global' : $definition[0];
  69          $function = (!is_array($definition)) ? $definition : $definition[1];
  70  
  71          // Method able to be hooked?
  72          if (isset($this->hooks[$class][$function]))
  73          {
  74              switch ($mode)
  75              {
  76                  case 'standalone':
  77                      if (!isset($this->hooks[$class][$function]['standalone']))
  78                      {
  79                          $this->hooks[$class][$function] = array('standalone' => $hook);
  80                      }
  81                      else
  82                      {
  83                          trigger_error('Hook not able to be called standalone, previous hook already standalone.', E_NOTICE);
  84                      }
  85                  break;
  86  
  87                  case 'first':
  88                  case 'last':
  89                      $this->hooks[$class][$function][$mode][] = $hook;
  90                  break;
  91  
  92                  case 'normal':
  93                  default:
  94                      $this->hooks[$class][$function]['normal'][] = $hook;
  95                  break;
  96              }
  97          }
  98      }
  99  
 100      /**
 101      * Calling all functions/methods attached to a specified hook.
 102      * Called by the function allowing hooks...
 103      *
 104      * @param mixed $definition Declaring function (with __FUNCTION__) or class with array(__CLASS__, __FUNCTION__)
 105      * @return bool False if no hook got executed, true otherwise
 106      */
 107  	function call_hook($definition)
 108      {
 109          $class = (!is_array($definition)) ? '__global' : $definition[0];
 110          $function = (!is_array($definition)) ? $definition : $definition[1];
 111  
 112          if (!empty($this->hooks[$class][$function]))
 113          {
 114              // Developer tries to call a hooked function within the hooked function...
 115              if ($this->current_hook !== NULL && $this->current_hook['class'] === $class && $this->current_hook['function'] === $function)
 116              {
 117                  return false;
 118              }
 119  
 120              // Call the hook with the arguments attached and store result
 121              $arguments = func_get_args();
 122              $this->current_hook = array('class' => $class, 'function' => $function);
 123              $arguments[0] = &$this;
 124  
 125              // Call the hook chain...
 126              if (isset($this->hooks[$class][$function]['standalone']))
 127              {
 128                  $this->hook_result[$class][$function] = call_user_func_array($this->hooks[$class][$function]['standalone'], $arguments);
 129              }
 130              else
 131              {
 132                  foreach (array('first', 'normal', 'last') as $mode)
 133                  {
 134                      if (!isset($this->hooks[$class][$function][$mode]))
 135                      {
 136                          continue;
 137                      }
 138  
 139                      foreach ($this->hooks[$class][$function][$mode] as $hook)
 140                      {
 141                          $this->hook_result[$class][$function] = call_user_func_array($hook, $arguments);
 142                      }
 143                  }
 144              }
 145  
 146              $this->current_hook = NULL;
 147              return true;
 148          }
 149  
 150          $this->current_hook = NULL;
 151          return false;
 152      }
 153  
 154      /**
 155      * Get result from previously called functions/methods for the same hook
 156      *
 157      * @param mixed $definition Declaring function (with __FUNCTION__) or class with array(__CLASS__, __FUNCTION__)
 158      * @return mixed False if nothing returned if there is no result, else array('result' => ... )
 159      */
 160  	function previous_hook_result($definition)
 161      {
 162          $class = (!is_array($definition)) ? '__global' : $definition[0];
 163          $function = (!is_array($definition)) ? $definition : $definition[1];
 164  
 165          if (!empty($this->hooks[$class][$function]) && isset($this->hook_result[$class][$function]))
 166          {
 167              return array('result' => $this->hook_result[$class][$function]);
 168          }
 169  
 170          return false;
 171      }
 172  
 173      /**
 174      * Check if the called functions/methods returned something.
 175      *
 176      * @param mixed $definition Declaring function (with __FUNCTION__) or class with array(__CLASS__, __FUNCTION__)
 177      * @return bool True if results are there, false if not
 178      */
 179  	function hook_return($definition)
 180      {
 181          $class = (!is_array($definition)) ? '__global' : $definition[0];
 182          $function = (!is_array($definition)) ? $definition : $definition[1];
 183  
 184          if (!empty($this->hooks[$class][$function]) && isset($this->hook_result[$class][$function]))
 185          {
 186              return true;
 187          }
 188  
 189          return false;
 190      }
 191  
 192      /**
 193      * Give actual result from called functions/methods back.
 194      *
 195      * @param mixed $definition Declaring function (with __FUNCTION__) or class with array(__CLASS__, __FUNCTION__)
 196      * @return mixed The result
 197      */
 198  	function hook_return_result($definition)
 199      {
 200          $class = (!is_array($definition)) ? '__global' : $definition[0];
 201          $function = (!is_array($definition)) ? $definition : $definition[1];
 202  
 203          if (!empty($this->hooks[$class][$function]) && isset($this->hook_result[$class][$function]))
 204          {
 205              $result = $this->hook_result[$class][$function];
 206              unset($this->hook_result[$class][$function]);
 207              return $result;
 208          }
 209  
 210          return;
 211      }
 212  
 213      /**
 214      * Add new function to the allowed hooks.
 215      *
 216      * @param mixed $definition Declaring function (with __FUNCTION__) or class with array(__CLASS__, __FUNCTION__)
 217      */
 218  	function add_hook($definition)
 219      {
 220          if (!is_array($definition))
 221          {
 222              $definition = array('__global', $definition);
 223          }
 224  
 225          $this->hooks[$definition[0]][$definition[1]] = array();
 226      }
 227  
 228      /**
 229      * Remove function from the allowed hooks.
 230      *
 231      * @param mixed $definition Declaring function (with __FUNCTION__) or class with array(__CLASS__, __FUNCTION__)
 232      */
 233  	function remove_hook($definition)
 234      {
 235          $class = (!is_array($definition)) ? '__global' : $definition[0];
 236          $function = (!is_array($definition)) ? $definition : $definition[1];
 237  
 238          if (isset($this->hooks[$class][$function]))
 239          {
 240              unset($this->hooks[$class][$function]);
 241  
 242              if (isset($this->hook_result[$class][$function]))
 243              {
 244                  unset($this->hook_result[$class][$function]);
 245              }
 246          }
 247      }
 248  }
 249  
 250  ?>