[Summary view] [Print] [Text view]

   1  <?php
   2  # MantisBT - A PHP based bugtracking system
   3  
   4  # MantisBT is free software: you can redistribute it and/or modify
   5  # it under the terms of the GNU General Public License as published by
   6  # the Free Software Foundation, either version 2 of the License, or
   7  # (at your option) any later version.
   8  #
   9  # MantisBT is distributed in the hope that it will be useful,
  10  # but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  # GNU General Public License for more details.
  13  #
  14  # You should have received a copy of the GNU General Public License
  15  # along with MantisBT.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  /**
  18   * Event API
  19   *
  20   * @package CoreAPI
  21   * @subpackage EventAPI
  22   * @author John Reese
  23   * @copyright Copyright (C) 2002 - 2011  MantisBT Team - mantisbt-dev@lists.sourceforge.net
  24   * @link http://www.mantisbt.org
  25   *
  26   * @uses constant_inc.php
  27   * @uses error_api.php
  28   * @uses events_inc.php
  29   * @uses plugin_api.php
  30   */
  31  
  32  require_api( 'constant_inc.php' );
  33  require_api( 'error_api.php' );
  34  require_api( 'events_inc.php' );
  35  require_api( 'plugin_api.php' );
  36  
  37  /**
  38   *
  39   * @global array $g_event_cache
  40   */
  41  $g_event_cache = array();
  42  
  43  /**
  44   * Declare an event of a given type.
  45   * Will do nothing if event already exists.
  46   * @param string Event name
  47   * @param int Event type
  48   * @access public
  49   */
  50  function event_declare( $p_name, $p_type = EVENT_TYPE_DEFAULT ) {
  51      global $g_event_cache;
  52  
  53      if( !isset( $g_event_cache[$p_name] ) ) {
  54  
  55          $g_event_cache[$p_name] = array(
  56              'type' => $p_type,
  57              'callbacks' => array(),
  58          );
  59      }
  60  }
  61  
  62  /**
  63   * Convenience function for decleare multiple events.
  64   * @param array Events
  65   * @access public
  66   */
  67  function event_declare_many( $p_events ) {
  68      foreach( $p_events as $t_name => $t_type ) {
  69          event_declare( $t_name, $t_type );
  70      }
  71  }
  72  
  73  /**
  74   * Hook a callback function to a given event.
  75   * A plugin's basename must be specified for proper handling of plugin callbacks.
  76   * @param string Event name
  77   * @param string Callback function
  78   * @param string Plugin basename
  79   * @access public
  80   */
  81  function event_hook( $p_name, $p_callback, $p_plugin = 0 ) {
  82      global $g_event_cache;
  83  
  84      if( !isset( $g_event_cache[$p_name] ) ) {
  85          error_parameters( $p_name );
  86          trigger_error( ERROR_EVENT_UNDECLARED, WARNING );
  87          return null;
  88      }
  89  
  90      $g_event_cache[$p_name]['callbacks'][$p_plugin][] = $p_callback;
  91  }
  92  
  93  /**
  94   * Hook multiple callback functions to multiple events.
  95   * @param array Event name/callback pairs
  96   * @param string Plugin basename
  97   * @access public
  98   */
  99  function event_hook_many( $p_hooks, $p_plugin = 0 ) {
 100      if( !is_array( $p_hooks ) ) {
 101          return;
 102      }
 103  
 104      foreach( $p_hooks as $t_name => $t_callbacks ) {
 105          if( !is_array( $t_callbacks ) ) {
 106              event_hook( $t_name, $t_callbacks, $p_plugin );
 107              continue;
 108          }
 109  
 110          foreach( $t_callbacks as $t_callback ) {
 111              event_hook( $t_name, $t_callback, $p_plugin );
 112          }
 113      }
 114  }
 115  
 116  /**
 117   * In the case of errors that halt execution, it is useful to
 118   * clear the list of event callbacks so that no other callbacks
 119   * are executed while the error message is being displayed.
 120   */
 121  function event_clear_callbacks() {
 122      global $g_event_cache;
 123  
 124      foreach( $g_event_cache as $t_name => $t_event_info ) {
 125          $g_event_cache[$t_name]['callbacks'] = array();
 126      }
 127  }
 128  
 129  /**
 130   * Signal an event to execute and handle callbacks as necessary.
 131   * @param string Event name
 132   * @param multi Event parameters
 133   * @param int Event type override
 134   * @return multi Null if event undeclared, appropriate return value otherwise
 135   * @access public
 136   */
 137  function event_signal( $p_name, $p_params = null, $p_params_dynamic = null, $p_type = null ) {
 138      global $g_event_cache;
 139  
 140      if( !isset( $g_event_cache[$p_name] ) ) {
 141          error_parameters( $p_name );
 142          trigger_error( ERROR_EVENT_UNDECLARED, WARNING );
 143          return null;
 144      }
 145  
 146      if( is_null( $p_type ) ) {
 147          $t_type = $g_event_cache[$p_name]['type'];
 148      } else {
 149          $t_type = $p_type;
 150      }
 151      $t_callbacks = $g_event_cache[$p_name]['callbacks'];
 152  
 153      switch( $t_type ) {
 154          case EVENT_TYPE_EXECUTE:
 155              return event_type_execute( $p_name, $t_callbacks, $p_params );
 156          case EVENT_TYPE_OUTPUT:
 157              return event_type_output( $p_name, $t_callbacks, $p_params );
 158          case EVENT_TYPE_CHAIN:
 159              return event_type_chain( $p_name, $t_callbacks, $p_params, $p_params_dynamic );
 160          case EVENT_TYPE_FIRST:
 161              return event_type_first( $p_name, $t_callbacks, $p_params );
 162          default:
 163              return event_type_default( $p_name, $t_callbacks, $p_params );
 164      }
 165  }
 166  
 167  /**
 168   * Executes a plugin's callback function for a given event.
 169   * @param string Event name
 170   * @param string Callback name
 171   * @param string Plugin basename
 172   * @param multi Parameters for event callback
 173   * @return multi Null if callback not found, value from callback otherwise
 174   * @access public
 175   */
 176  function event_callback( $p_event, $p_callback, $p_plugin, $p_params = null ) {
 177      $t_value = null;
 178      if( !is_array( $p_params ) ) {
 179          $p_params = array(
 180              $p_params,
 181          );
 182      }
 183  
 184      if( $p_plugin !== 0 ) {
 185          global $g_plugin_cache;
 186  
 187          plugin_push_current( $p_plugin );
 188  
 189          if( method_exists( $g_plugin_cache[$p_plugin], $p_callback ) ) {
 190              $t_value = call_user_func_array( array( $g_plugin_cache[$p_plugin], $p_callback ), array_merge( array( $p_event ), $p_params ) );
 191          }
 192  
 193          plugin_pop_current();
 194      } else {
 195          if( function_exists( $p_callback ) ) {
 196              $t_value = call_user_func_array( $p_callback, array_merge( array( $p_event ), $p_params ) );
 197          }
 198      }
 199  
 200      return $t_value;
 201  }
 202  
 203  /**
 204   * Process an execute event type.
 205   * All callbacks will be called with parameters, and their
 206   * return values will be ignored.
 207   * @param string Event name
 208   * @param array Array of callback function/plugin basename key/value pairs
 209   * @param array Callback parameters
 210   * @access public
 211   */
 212  function event_type_execute( $p_event, $p_callbacks, $p_params ) {
 213      foreach( $p_callbacks as $t_plugin => $t_callbacks ) {
 214          foreach( $t_callbacks as $t_callback ) {
 215              event_callback( $p_event, $t_callback, $t_plugin, $p_params );
 216          }
 217      }
 218  }
 219  
 220  /**
 221   * Process an output event type.
 222   * All callbacks will be called with the given parameters, and their
 223   * return values will be echoed to the client, separated by a given string.
 224   * If there are no callbacks, then nothing will be sent as output.
 225   * @param string Event name
 226   * @param array Array of callback function/plugin basename key/value pairs
 227   * @param multi Output separator (if single string) or indexed array of pre, mid, and post strings
 228   * @access public
 229   */
 230  function event_type_output( $p_event, $p_callbacks, $p_params = null ) {
 231      $t_prefix = '';
 232      $t_separator = '';
 233      $t_postfix = '';
 234  
 235      if( is_array( $p_params ) ) {
 236          switch( count( $p_params ) ) {
 237              case 3:
 238                  $t_postfix = $p_params[2];
 239              case 2:
 240                  $t_separator = $p_params[1];
 241              case 1:
 242                  $t_prefix = $p_params[0];
 243          }
 244      } else {
 245          $t_separator = $p_params;
 246      }
 247  
 248      $t_output = array();
 249      foreach( $p_callbacks as $t_plugin => $t_callbacks ) {
 250          foreach( $t_callbacks as $t_callback ) {
 251              $t_output[] = event_callback( $p_event, $t_callback, $t_plugin, $p_params );
 252          }
 253      }
 254      if( count( $p_callbacks ) > 0 ) {
 255          echo $t_prefix, implode( $t_separator, $t_output ), $t_postfix;
 256      }
 257  }
 258  
 259  /**
 260   * Process a chained event type.
 261   * The first callback with be called with the given input.  All following
 262   * callbacks will be called with the previous's output as its input.  The
 263   * final callback's return value will be returned to the event origin.
 264   * @param string Event name
 265   * @param array Array of callback function/plugin basename key/value pairs
 266   * @param string Input string
 267   * @return string Output string
 268   * @access public
 269   */
 270  function event_type_chain( $p_event, $p_callbacks, $p_input, $p_params ) {
 271      if( !is_array( $p_params ) ) {
 272          $p_params = array(
 273              $p_params,
 274          );
 275      }
 276      $t_output = $p_input;
 277  
 278      foreach( $p_callbacks as $t_plugin => $t_callbacks ) {
 279          foreach( $t_callbacks as $t_callback ) {
 280              if( !is_array( $t_output ) ) {
 281                  $t_output = array(
 282                      $t_output,
 283                  );
 284              }
 285  
 286              $t_params = array_merge( $t_output, $p_params );
 287              $t_output = event_callback( $p_event, $t_callback, $t_plugin, $t_params );
 288          }
 289      }
 290      return $t_output;
 291  }
 292  
 293  /**
 294   * Process a first-return event.
 295   * Callbacks will be called with the given parameters until a callback
 296   * returns a non-null value; at this point, no other callbacks will be
 297   * processed, and the return value be passed back to the event origin.
 298   * @param string Event name
 299   * @param array Array of callback function/plugin basename key/value pairs
 300   * @param multi Parameters passed to callbacks
 301   * @return multi The first non-null callback result, or null otherwise
 302   * @access public
 303   */
 304  function event_type_first( $p_event, $p_callbacks, $p_params ) {
 305      $t_output = null;
 306  
 307      foreach( $p_callbacks as $t_plugin => $t_callbacks ) {
 308          foreach( $t_callbacks as $t_callback ) {
 309              $t_output = event_callback( $p_event, $t_callback, $t_plugin, $p_params );
 310  
 311              if( !is_null( $t_output ) ) {
 312                  return $t_output;
 313              }
 314          }
 315      }
 316  
 317      return null;
 318  }
 319  
 320  /**
 321   * Process a default event type.
 322   * All callbacks will be called with the given data parameters.  The
 323   * return value of each callback will be appended to an array with the callback's
 324   * basename as the key.  This array will then be returned to the event origin.
 325   * @param string Event name
 326   * @param array Array of callback function/plugin basename key/value pairs
 327   * @param multi Data
 328   * @return array Array of callback/return key/value pairs
 329   * @access public
 330   */
 331  function event_type_default( $p_event, $p_callbacks, $p_data ) {
 332      $t_output = array();
 333      foreach( $p_callbacks as $t_plugin => $t_callbacks ) {
 334          foreach( $t_callbacks as $t_callback ) {
 335              $t_output[$t_plugin][$t_callback] = event_callback( $p_event, $t_callback, $t_plugin, $p_data );
 336          }
 337      }
 338      return $t_output;
 339  }