Merge branch 'master' of git://git.zendframework.com/zf

src/Event.php

@@ -36,7 +36,7 @@
  * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  */
-class Event
+class Event implements EventDescription
 {
     /**
      * @var string Event name
@@ -68,11 +68,19 @@ class Event
      * @param  array|ArrayAccess $params 
      * @return void
      */
-    public function __construct($name, $target, $params)
+    public function __construct($name = null, $target = null, $params = null)
     {
-        $this->name   = $name;
-        $this->target = $target;
-        $this->setParams($params);
+        if (null !== $name) {
+            $this->setName($name);
+        }
+
+        if (null !== $target) {
+            $this->setTarget($target);
+        }
+
+        if (null !== $params) {
+            $this->setParams($params);
+        }
     }
 
     /**
@@ -155,6 +163,30 @@ public function getParam($name, $default = null)
         return $this->params->{$name};
     }
 
+    /**
+     * Set the event name
+     * 
+     * @param  string $name 
+     * @return Event
+     */
+    public function setName($name)
+    {
+        $this->name = (string) $name;
+        return $this;
+    }
+
+    /**
+     * Set the event target/context
+     * 
+     * @param  null|string|object $target 
+     * @return Event
+     */
+    public function setTarget($target)
+    {
+        $this->target = $target;
+        return $this;
+    }
+
     /**
      * Set an individual parameter to a value
      * 
@@ -180,7 +212,7 @@ public function setParam($name, $value)
      * @param  bool $flag 
      * @return void
      */
-    public function stopPropagation($flag)
+    public function stopPropagation($flag = true)
     {
         $this->stopPropagation = (bool) $flag;
     }

src/EventCollection.php

@@ -37,63 +37,78 @@ interface EventCollection
 {
     /**
      * Trigger an event
+     *
+     * Should allow handling the following scenarios:
+     * - Passing Event object only
+     * - Passing event name and Event object only
+     * - Passing event name, target, and Event object
+     * - Passing event name, target, and array|ArrayAccess of arguments
+     *
+     * Can emulate triggerUntil() if the last argument provided is a callback.
      * 
      * @param  string $event 
-     * @param  object|string $context 
+     * @param  object|string $target 
      * @param  array|object $argv 
+     * @param  null|callback $callback 
      * @return ResponseCollection
      */
-    public function trigger($event, $context, $argv = array());
+    public function trigger($event, $target = null, $argv = array(), $callback = null);
 
     /**
      * Trigger an event until the given callback returns a boolean false
+     *
+     * Should allow handling the following scenarios:
+     * - Passing Event object and callback only
+     * - Passing event name, Event object, and callback only
+     * - Passing event name, target, Event object, and callback
+     * - Passing event name, target, array|ArrayAccess of arguments, and callback
      * 
      * @param  string $event 
-     * @param  object|string $context 
+     * @param  object|string $target 
      * @param  array|object $argv 
      * @param  callback $callback 
      * @return ResponseCollection
      */
-    public function triggerUntil($event, $context, $argv, $callback);
+    public function triggerUntil($event, $target, $argv = null, $callback = null);
 
     /**
-     * Attach a handler to an event
+     * Attach a listener to an event
      * 
      * @param  string $event 
      * @param  callback $callback
-     * @param  int $priority Priority at which to register handler
+     * @param  int $priority Priority at which to register listener
      * @return CallbackHandler
      */
     public function attach($event, $callback, $priority = 1);
 
     /**
-     * Detach an event handler
+     * Detach an event listener
      * 
-     * @param  CallbackHandler $handle 
+     * @param  CallbackHandler $listener 
      * @return void
      */
-    public function detach(CallbackHandler $handle);
+    public function detach(CallbackHandler $listener);
 
     /**
-     * Get a list of events for which this collection has handlers
+     * Get a list of events for which this collection has listeners
      * 
      * @return array
      */
     public function getEvents();
 
     /**
-     * Retrieve a list of handlers registered to a given event
+     * Retrieve a list of listeners registered to a given event
      * 
      * @param  string $event 
      * @return array|object
      */
-    public function getHandlers($event);
+    public function getListeners($event);
 
     /**
-     * Clear all handlers for a given event
+     * Clear all listeners for a given event
      * 
      * @param  string $event 
      * @return void
      */
-    public function clearHandlers($event);
+    public function clearListeners($event);
 }

src/EventDescription.php

@@ -0,0 +1,113 @@
+<?php
+/**
+ * Zend Framework
+ *
+ * LICENSE
+ *
+ * This source file is subject to the new BSD license that is bundled
+ * with this package in the file LICENSE.txt.
+ * It is also available through the world-wide-web at this URL:
+ * http://framework.zend.com/license/new-bsd
+ * If you did not receive a copy of the license and are unable to
+ * obtain it through the world-wide-web, please send an email
+ * to license@zend.com so we can send you a copy immediately.
+ *
+ * @category   Zend
+ * @package    Zend_EventManager
+ * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ */
+
+/**
+ * @namespace
+ */
+namespace Zend\EventManager;
+
+/**
+ * Representation of an event
+ *
+ * @category   Zend
+ * @package    Zend_EventManager
+ * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ */
+interface EventDescription
+{
+    /**
+     * Get event name
+     * 
+     * @return string
+     */
+    public function getName();
+
+    /**
+     * Get target/context from which event was triggered
+     * 
+     * @return null|string|object
+     */
+    public function getTarget();
+
+    /**
+     * Get parameters passed to the event
+     * 
+     * @return array|ArrayAccess
+     */
+    public function getParams();
+
+    /**
+     * Get a single parameter by name
+     * 
+     * @param  string $name 
+     * @param  mixed $default Default value to return if parameter does not exist
+     * @return mixed
+     */
+    public function getParam($name, $default = null);
+
+    /**
+     * Set the event name
+     * 
+     * @param  string $name 
+     * @return void
+     */
+    public function setName($name);
+
+    /**
+     * Set the event target/context
+     * 
+     * @param  null|string|object $target 
+     * @return void
+     */
+    public function setTarget($target);
+
+    /**
+     * Set event parameters
+     * 
+     * @param  string $params 
+     * @return void
+     */
+    public function setParams($params);
+
+    /**
+     * Set a single parameter by key
+     * 
+     * @param  string $name 
+     * @param  mixed $value 
+     * @return void
+     */
+    public function setParam($name, $value);
+
+    /**
+     * Indicate whether or not the parent EventCollection should stop propagating events
+     * 
+     * @param  bool $flag 
+     * @return void
+     */
+    public function stopPropagation($flag = true);
+
+    /**
+     * Has this event indicated event propagation should stop?
+     * 
+     * @return bool
+     */
+    public function propagationIsStopped();
+}