[Summary view] [Print] [Text view]

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