1: <?php
 2: /**
 3:  * PHP version 5
 4:  * @package    generalDriver
 5:  * @author     Christian Schiffler <c.schiffler@cyberspectrum.de>
 6:  * @author     Stefan Heimes <stefan_heimes@hotmail.com>
 7:  * @author     Tristan Lins <tristan.lins@bit3.de>
 8:  * @copyright  The MetaModels team.
 9:  * @license    LGPL.
10:  * @filesource
11:  */
12: 
13: namespace DcGeneral\Event;
14: 
15: /**
16:  * Generic event propagator.
17:  *
18:  * The event propagator is used to dispatch an event to the attached event dispatcher.
19:  *
20:  * When propagating an event, one can pass an array of suffixes that will get appended to the event name in a loop.
21:  *
22:  * @package DcGeneral\Event
23:  */
24: interface EventPropagatorInterface
25: {
26:     /**
27:      * Propagate an event to the defined event dispatcher.
28:      *
29:      * The given suffixes will get appended to the event name and the resulting event name will get fired.
30:      *
31:      * For each round of firing, the last element from the suffixes get's dropped and the event fired again.
32:      *
33:      * The loop stops as soon as the passed event has isPropagationStopped() === true
34:      *
35:      * Example:
36:      *   Eventname: dc-general.some.event
37:      *   Suffixes:  array('param1', 'param2')
38:      * Resulting Events:
39:      *   1. dc-general.some.event[param1][param2]
40:      *   2. dc-general.some.event[param1]
41:      *   3. dc-general.some.event
42:      *
43:      * @param string                                   $eventName The event name of the event to propagate.
44:      *
45:      * @param \Symfony\Component\EventDispatcher\Event $event     The Event to propagate (optional).
46:      *
47:      * @param string[]                                 $suffixes  Suffixes to attach to the event.
48:      *
49:      * @return \Symfony\Component\EventDispatcher\Event
50:      */
51:     public function propagate($eventName, $event = null, $suffixes = array());
52: 
53:     /**
54:      * Propagate an event to the defined event dispatcher.
55:      *
56:      * The given suffixes will get appended to the event name and the resulting event name will get fired.
57:      *
58:      * @param string                                   $eventName The event name of the event to propagate.
59:      *
60:      * @param \Symfony\Component\EventDispatcher\Event $event     The Event to propagate.
61:      *
62:      * @param string[]                                 $suffixes  Suffixes to attach to the event.
63:      *
64:      * @return \Symfony\Component\EventDispatcher\Event
65:      */
66:     public function propagateExact($eventName, $event, $suffixes = array());
67: }
68: