[Sommaire] [Imprimer]

   1  <?php // $Id: class.event.php,v 1.14 2007/01/31 14:07:51 zefredz Exp $
   2  if ( count( get_included_files() ) == 1 ) die( '---' );
   3  // +----------------------------------------------------------------------+
   4  // | EventDriven Programming                                              |
   5  // | PHP version 4                                                        |
   6  // | version 0.1  - 2005-01-14                                            |
   7  // | author Frederic Minne                                                |
   8  // +----------------------------------------------------------------------+
   9  // | Copyright (c) 2004 Frederic Minne                                    |
  10  // +----------------------------------------------------------------------+
  11  // | This program is free software; you can redistribute it and/or modify |
  12  // | it under the terms of the GNU General Public License as published by |
  13  // | the Free Software Foundation; either version 2 of the License, or    |
  14  // | (at your option) any later version.                                  |
  15  // |                                                                      |
  16  // | This program is distributed in the hope that it will be useful,      |
  17  // | but WITHOUT ANY WARRANTY; without even the implied warranty of       |
  18  // | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the        |
  19  // | GNU General Public License for more details.                         |
  20  // |                                                                      |
  21  // | You should have received a copy of the GNU General Public License    |
  22  // | along with this program; if not, write to the Free Software          |
  23  // | Foundation, Inc., 59 Temple Place, Suite 330, Boston,                |
  24  // | MA  02111-1307  USA                                                  |
  25  // +----------------------------------------------------------------------+
  26  // | Authors: Frederic Minne <zefredz@gmail.com>                          |
  27  // |          Guillaume Lederer <guillaume@claroline.net>                 |
  28  // +----------------------------------------------------------------------+
  29  
  30  // TODO : modify the code to use Event class instead of string to represent events
  31  // ie:
  32  //      - pass additonnal arguments to event listeners
  33  //      - modify event manager to use $event->type instead of $event in eventOccurs
  34  
  35  // ---------------------- Functions ----------------------
  36  
  37  /**
  38   * Compute size of arrays containing object reference with possible
  39   * recursion
  40   * @param $arry (array)
  41   * @return (int) size of the array, -1 if $arry is not an array
  42   * @access global
  43   */
  44  function array_size( $arry )
  45  {
  46      if ( !is_array( $arry ) )
  47      {
  48          return -1;
  49      }
  50      $size = 0;
  51      
  52      // do not use count because it poduces some mysterious 
  53      // values with self referencing objects
  54      foreach ( $arry as $value )
  55      {
  56          $size++;
  57      }
  58  
  59      return $size;
  60  }
  61  
  62  
  63  // ------------------- Classes ------------------------
  64  
  65  /**
  66  * class to manage events and dispatch them to event listeners
  67  * @access public
  68  */
  69  class EventManager
  70  {
  71      // protected fields
  72      var $_registry;
  73  
  74      /**
  75          * Constructor
  76          * @access public
  77          */
  78      function EventManager()
  79      {
  80          $this->_registry = array();
  81      }
  82  
  83      /**
  84       * register new event listener for a given event
  85       * @access public
  86       * @param $event (string) event identifier
  87       * @param $listener (object) reference to the event listener
  88       * @return (string) event listener ID
  89       */
  90      function register( $event, &$listener )
  91      {
  92          if( ! isset( $this->_registry[$event] ) )
  93          {
  94              $this->_registry[$event] = array();
  95          }
  96          $id = md5( serialize($listener) );
  97          $this->_registry[$event][$id] = & $listener;
  98          return $id;
  99      }
 100  
 101      /**
 102       * unregister event listener
 103       * @access public
 104       * @param $event (string) event watching by the listener
 105       * @param $id (string) listener ID
 106       */
 107      function unregister( $event, $id )
 108      {
 109          unset($this->_registry[$event][$id]);
 110          if( array_size( $this->_registry[$event] ) == 0 )
 111          {
 112              unset( $this->_registry[$event] );
 113          }
 114      }
 115  
 116      /**
 117       * notify occurence of an event to the event manager
 118       * @access package private
 119       * @param $event (string) the occured event
 120       */
 121      function eventOccurs( $event )
 122      {
 123          if ( isset( $this->_registry[$event->getEventType()] )
 124              && is_array( $this->_registry[$event->getEventType()] )
 125              && array_size( $this->_registry[$event->getEventType()] ) != 0 )
 126          {
 127              foreach( $this->_registry[$event->getEventType()] as $listener )
 128              {
 129                  if( !is_null( $listener ) )
 130                  {
 131                      $listener->handle($event);
 132                  }
 133              }
 134          }
 135          else
 136          {
 137              if ( defined( "DEBUG_MODE" ) && DEBUG_MODE )
 138              {
 139                  $errmsg = __CLASS__
 140                      . "{no listener found for EVENT["
 141                      . $event->getEventType()
 142                      . "]}"
 143                      ;
 144                  pushClaroMessage( $errmsg, 'debug' );
 145              }
 146          }
 147      }
 148  
 149      // debugging methods
 150  
 151      /**
 152       * list all registered events and the number of listeners for each
 153       * @access public
 154       */
 155      function listRegiteredEvents()
 156      {
 157          if ( is_array( $this->_registry )
 158          && array_size( $this->_registry ) != 0 )
 159          {
 160              foreach( $this->_registry as $event => $listeners )
 161              {
 162                  echo "$event(" . array_size( $listeners ) . ")\n";
 163              }
 164          }
 165          else
 166          {
 167              echo "none\n";
 168          }
 169      }
 170  
 171      /**
 172       * list all registered listeners and their ID
 173       * @access public
 174       */
 175      function listRegisteredListeners()
 176      {
 177          if ( is_array( $this->_registry )
 178          && array_size( $this->_registry ) != 0 )
 179          {
 180              foreach( $this->_registry as $event => $listeners )
 181              {
 182                  echo "$event(" . array_size( $listeners ) . ")\n";
 183                  foreach( $listeners as $id => $listener )
 184                  {
 185                      echo "\t$id\n";
 186                  }
 187              }
 188          }
 189          else
 190          {
 191              echo "none\n";
 192          }
 193      }
 194  
 195  }
 196  
 197  /**
 198   * listen to a particular event
 199   * @access public
 200   */
 201  class EventListener
 202  {
 203      // protected fields
 204      var $_event;
 205      var $_obj;
 206      var $_callback;
 207  
 208      /**
 209          * constructor
 210          * @access public
 211          * @param $obj (object) reference to the creator
 212          * @param $callback (string) name of the callback method of the creator
 213          *       object to call when event occurs
 214          */
 215      function EventListener( &$obj, $callback )
 216      {
 217          $this->_obj = & $obj;
 218          $this->_callback = $callback;
 219      }
 220  
 221      /**
 222          * notification of event occurence
 223          * @access package private
 224          */
 225      function handle($event)
 226      {
 227          call_user_func( array( &$this->_obj, $this->_callback ),$event );
 228      }
 229  }
 230  
 231  
 232  /**
 233   * generic event generator for test purpose
 234   * @access public
 235   */
 236  class EventGenerator
 237  {
 238      // protected fields
 239      var $_registry;
 240  
 241      /**
 242          * constructor
 243          * @access public
 244          * @param $registry (object) reference to an event manager
 245          */
 246      function EventGenerator( &$registry )
 247      {
 248          $this->_registry =& $registry;
 249      }
 250  
 251      /**
 252       * notify the event manager for an event occurence
 253       * @access public
 254       * @param $event the event that occurs; an instance of the event class
 255       */
 256      function sendEvent( $event )
 257      {
 258          $this->_registry->eventOccurs($event);
 259      }
 260  
 261      /**
 262       * public function to notify manager that an event occured,
 263       * using this function instead of sendEvent allow to let the class create the Event instance for you
 264       *
 265       * @param $eventType (string) the type of the event
 266       * @param $args an array contening any parameters needed to describe the event occurence
 267       */
 268  
 269      function notifyEvent($eventType, $args )
 270      {
 271          $myEvent = new Event( $eventType, $args);
 272          $this->sendEvent($myEvent);
 273      }
 274  
 275      /**
 276       * Public function to notify manager that an event occured IN A COURSE TOOL
 277       * using this function allow to notify an event in any tool of any course into Claroline,
 278       * it allows to use only one call to this function in the Claroline code
 279       *
 280       * @param eventType (string)
 281       * @param cid identifier of the COURSE concerned by the event    (should always be set)
 282       * @param tid identifier of the TOOL concerned by the event      (0 if not used)
 283       * @param rid identifier of the RESSOURCE concerned by the event (0 if not used)
 284       * @param gid identifier of the GROUP concerned by the event     (0 if not used)
 285       * @param uid identifier of the USER concerned by the event      
 286       *           - 0 if every users are concerned,
 287       *           - uid of the user if notification should only concerns himself
 288       */
 289  
 290      function notifyCourseEvent($eventType, $cid, $tid, $rid, $gid, $uid)
 291      {
 292          $eventArgs = array();
 293          $eventArgs['cid'] = $cid;
 294          $eventArgs['tid'] = $tid;
 295          $eventArgs['rid'] = $rid;
 296          $eventArgs['gid'] = $gid;
 297          $eventArgs['uid'] = $uid;
 298          $eventArgs['date'] = date("Y-m-d H:i:00");
 299  
 300          $this->notifyEvent($eventType, $eventArgs);
 301      }
 302  
 303  }
 304  
 305  /**
 306   * generic event driven application
 307   * @access public
 308   * @abstract
 309   */
 310  class EventDriven
 311  {
 312      // protected fields
 313      var $_registry;
 314      var $_listeners;
 315  
 316      /**
 317       * constructor
 318       * @access public
 319       * @param $registry (object) reference to the event manager
 320       */
 321      function EventDriven( &$registry )
 322      {
 323          $this->_registry =& $registry;
 324          $this->_listeners = array();
 325      }
 326  
 327      /**
 328       * add an event listener to the event driven application
 329       * @access public
 330       * @param $callback (string) callback method
 331       * @param $event (string) event
 332       * @return $id (string) eventlistener ID
 333       */
 334      function addListener( $callback, $eventType )
 335      {
 336          $listener = new EventListener( $this, $callback );
 337          $id = $this->_registry->register($eventType, $listener );
 338          $this->_listeners[$eventType][$id] =& $listener;
 339          return $id;
 340      }
 341  
 342      /**
 343       * remove an event listener from the application
 344       * @access public
 345       * @param $event (string) event
 346       * @param $id (string) eventlistener ID
 347       */
 348      function removeListener( $event, $id )
 349      {
 350          unset( $this->_listeners[$event][$id] );
 351          $this->_registry->unregister($event, $id);
 352          if( is_array( $this->_listeners[$event] )
 353              && array_size( $this->_listeners[$event] ) == 0 )
 354          {
 355              unset( $this->_listeners[$event] );
 356          }
 357      }
 358  
 359      // ----------- Debugging methods ----------
 360  
 361      /**
 362       * list all registered listeners
 363       * @access public
 364       */
 365      function listListeners()
 366      {
 367          if ( is_array( $this->_listeners )
 368          && array_size( $this->_listeners ) != 0 )
 369          {
 370              foreach( $this->_listeners as $event => $listeners )
 371              {
 372                  echo "$event(" . array_size( $listeners ) . ")\n";
 373                  foreach( $listeners as $id => $listener )
 374                  {
 375                      echo "\t$id\n";
 376                  }
 377              }
 378          }
 379          else
 380          {
 381              echo "none\n";
 382          }
 383      }
 384  }
 385  
 386  class Event
 387  {
 388      // event type
 389      var $_type;
 390      // additionnal arguments needed by event listeners
 391      var $_args;
 392  
 393      function Event( $type, $args = null )
 394      {
 395          $this->_type = $type;
 396          $this->_args = $args;
 397      }
 398  
 399      function getEventType()
 400      {
 401          return $this->_type;
 402      }
 403  
 404      function getArgs()
 405      {
 406          return $this->_args;
 407      }
 408  }
 409  ?>