[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3  * @version        $Id: dispatcher.php 14401 2010-01-26 14:10:00Z louis $
   4  * @package        Joomla.Framework
   5  * @subpackage    Event
   6  * @copyright    Copyright (C) 2005 - 2010 Open Source Matters. All rights reserved.
   7  * @license        GNU/GPL, see LICENSE.php
   8  * Joomla! is free software. This version may have been modified pursuant
   9  * to the GNU General Public License, and as distributed it includes or
  10  * is derivative of works licensed under the GNU General Public License or
  11  * other free or open source software licenses.
  12  * See COPYRIGHT.php for copyright notices and details.
  13  */
  14  
  15  // Check to ensure this file is within the rest of the framework
  16  defined('JPATH_BASE') or die();
  17  
  18  jimport('joomla.base.observable');
  19  
  20  /**
  21   * Class to handle dispatching of events.
  22   *
  23   * This is the Observable part of the Observer design pattern
  24   * for the event architecture.
  25   *
  26   * @package     Joomla.Framework
  27   * @subpackage    Event
  28   * @since    1.5
  29   * @see        JPlugin
  30   * @link http://docs.joomla.org/Tutorial:Plugins Plugin tutorials
  31   */
  32  class JDispatcher extends JObservable
  33  {
  34      /**
  35       * Constructor
  36       *
  37       * @access    protected
  38       */
  39  	function __construct()
  40      {
  41          parent::__construct();
  42      }
  43  
  44      /**
  45       * Returns a reference to the global Event Dispatcher object, only creating it
  46       * if it doesn't already exist.
  47       *
  48       * This method must be invoked as:
  49       *         <pre>  $dispatcher = &JDispatcher::getInstance();</pre>
  50       *
  51       * @access    public
  52       * @return    JDispatcher    The EventDispatcher object.
  53       * @since    1.5
  54       */
  55      function & getInstance()
  56      {
  57          static $instance;
  58  
  59          if (!is_object($instance)) {
  60              $instance = new JDispatcher();
  61          }
  62  
  63          return $instance;
  64      }
  65  
  66      /**
  67       * Registers an event handler to the event dispatcher
  68       *
  69       * @access    public
  70       * @param    string    $event        Name of the event to register handler for
  71       * @param    string    $handler    Name of the event handler
  72       * @return    void
  73       * @since    1.5
  74       */
  75  	function register($event, $handler)
  76      {
  77          // Are we dealing with a class or function type handler?
  78          if (function_exists($handler))
  79          {
  80              // Ok, function type event handler... lets attach it.
  81              $method = array ('event' => $event, 'handler' => $handler);
  82              $this->attach($method);
  83          }
  84          elseif (class_exists($handler))
  85          {
  86               //Ok, class type event handler... lets instantiate and attach it.
  87              $this->attach(new $handler($this));
  88          }
  89          else
  90          {
  91              JError::raiseWarning('SOME_ERROR_CODE', 'JDispatcher::register: Event handler not recognized.', 'Handler: '.$handler );
  92          }
  93      }
  94  
  95      /**
  96       * Triggers an event by dispatching arguments to all observers that handle
  97       * the event and returning their return values.
  98       *
  99       * @access    public
 100       * @param    string    $event            The event name
 101       * @param    array    $args            An array of arguments
 102       * @param    boolean    $doUnpublished    [DEPRECATED]
 103       * @return    array    An array of results from each function call
 104       * @since    1.5
 105       */
 106  	function trigger($event, $args = null, $doUnpublished = false)
 107      {
 108          // Initialize variables
 109          $result = array ();
 110  
 111          /*
 112           * If no arguments were passed, we still need to pass an empty array to
 113           * the call_user_func_array function.
 114           */
 115          if ($args === null) {
 116              $args = array ();
 117          }
 118  
 119          /*
 120           * We need to iterate through all of the registered observers and
 121           * trigger the event for each observer that handles the event.
 122           */
 123          foreach ($this->_observers as $observer)
 124          {
 125              if (is_array($observer))
 126              {
 127                  /*
 128                   * Since we have gotten here, we know a little something about
 129                   * the observer.  It is a function type observer... lets see if
 130                   * it handles our event.
 131                   */
 132                  if ($observer['event'] == $event)
 133                  {
 134                      if (function_exists($observer['handler']))
 135                      {
 136                          $result[] = call_user_func_array($observer['handler'], $args);
 137                      }
 138                      else
 139                      {
 140                          /*
 141                           * Couldn't find the function that the observer specified..
 142                           * wierd, lets throw an error.
 143                           */
 144                          JError::raiseWarning('SOME_ERROR_CODE', 'JDispatcher::trigger: Event Handler Method does not exist.', 'Method called: '.$observer['handler']);
 145                      }
 146                  }
 147                  else
 148                  {
 149                       // Handler doesn't handle this event, move on to next observer.
 150                      continue;
 151                  }
 152              }
 153              elseif (is_object($observer))
 154              {
 155                  /*
 156                   * Since we have gotten here, we know a little something about
 157                   * the observer.  It is a class type observer... lets see if it
 158                   * is an object which has an update method.
 159                   */
 160                  if (method_exists($observer, 'update'))
 161                  {
 162                      /*
 163                       * Ok, now we know that the observer is both not an array
 164                       * and IS an object.  Lets trigger its update method if it
 165                       * handles the event and return any results.
 166                       */
 167                      if (method_exists($observer, $event))
 168                      {
 169                          $args['event'] = $event;
 170                          $result[] = $observer->update($args);
 171                      }
 172                      else
 173                      {
 174                          /*
 175                           * Handler doesn't handle this event, move on to next
 176                           * observer.
 177                           */
 178                          continue;
 179                      }
 180                  }
 181                  else
 182                  {
 183                      /*
 184                       * At this point, we know that the registered observer is
 185                       * neither a function type observer nor an object type
 186                       * observer.  PROBLEM, lets throw an error.
 187                       */
 188                      JError::raiseWarning('SOME_ERROR_CODE', 'JDispatcher::trigger: Unknown Event Handler.', $observer );
 189                  }
 190              }
 191          }
 192          return $result;
 193      }
 194  }