1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
# Quick Start
Typically, you will compose an `EventManager` instance in a class.
```php
use Laminas\EventManager\EventManagerInterface;
use Laminas\EventManager\EventManager;
use Laminas\EventManager\EventManagerAwareInterface;
class Foo implements EventManagerAwareInterface
{
protected $events;
public function setEventManager(EventManagerInterface $events)
{
$events->setIdentifiers([
__CLASS__,
get_called_class(),
]);
$this->events = $events;
return $this;
}
public function getEventManager()
{
if (null === $this->events) {
$this->setEventManager(new EventManager());
}
return $this->events;
}
}
```
The above allows users to access the `EventManager` instance, or reset it with a
new instance; if one does not exist, it will be lazily instantiated on-demand.
The instance property `$events` is a convention for referring to the
EventManager instance.
An `EventManager` is really only interesting if it triggers some events.
Basic triggering via the `trigger()` method takes three arguments:
- The event *name*, which is usually the current function/method name;
- The *target*, which is usually the current object instance;
- Event *arguments*, which are usually the arguments provided to the current function/method.
```php
class Foo
{
// ... assume events definition from above
public function bar($baz, $bat = null)
{
$params = compact('baz', 'bat');
$this->getEventManager()->trigger(__FUNCTION__, $this, $params);
}
}
```
In turn, triggering events is only interesting if something is listening for the
event.
Listeners attach to the `EventManager`, specifying a named event and the
callback to notify. The callback receives an `Event` object, which has accessors
for retrieving the event name, target, and parameters. Let's add a listener, and
trigger the event.
```php
use Laminas\Log\Factory as LogFactory;
$log = LogFactory($someConfig);
$foo = new Foo();
$foo->getEventManager()->attach('bar', function ($e) use ($log) {
$event = $e->getName();
$target = get_class($e->getTarget());
$params = json_encode($e->getParams());
$log->info(sprintf(
'%s called on %s, using params %s',
$event,
$target,
$params
));
});
// The following method call:
$foo->bar('baz', 'bat');
// Results in the log message reading:
// bar called on Foo, using params {"baz" : "baz", "bat" : "bat"}"
```
Note that the second argument to `attach()` is any valid PHP callable; an
anonymous function is shown in the example in order to keep the example
self-contained.
However, you could also utilize a valid function name, a functor, a string
referencing a static method, or an array callback with a named static method or
instance method. Again, any PHP callable is valid.
Sometimes you may want to specify listeners without yet having an object
instance of the class composing an `EventManager`. Laminas enables this
through the concept of a `SharedEventManager`.
Simply put, you can inject individual `EventManager` instances with a well-known
`SharedEventManager`, and the `EventManager` instance will query it for
additional listeners.
Listeners attach to a `SharedEventManager` in roughly the same way they do to
normal event managers; the call to `attach` is identical to the `EventManager`,
but expects an additional parameter at the beginning: a named instance.
Remember the example of composing an `EventManager`, how we passed it an array
containing `__CLASS__` and `get_called_class()`? Those values are then used to
*identify* the event manager instance, and pull listeners registered with one of
those identifiers from the `SharedEventManager`.
As an example, assuming we have a `SharedEventManager` instance that we know has
been injected in our `EventManager` instances (for instance, via dependency
injection), we could change the above example to attach via the shared
collection:
```php
use Laminas\Log\Factory as LogFactory;
// Assume $sharedEvents is a Laminas\EventManager\SharedEventManager instance
$log = LogFactory($someConfig);
$sharedEvents->attach('Foo', 'bar', function ($e) use ($log) {
$event = $e->getName();
$target = get_class($e->getTarget());
$params = json_encode($e->getParams());
$log->info(sprintf(
'%s called on %s, using params %s',
$event,
$target,
$params
));
});
// Later, instantiate Foo:
$foo = new Foo();
$foo->setEventManager(new EventManager($sharedEvents, []));
// And we can still trigger the above event:
$foo->bar('baz', 'bat');
// results in log message:
// bar called on Foo, using params {"baz" : "baz", "bat" : "bat"}"
```
The `EventManager` also provides the ability to detach listeners, short-circuit
execution of an event either from within a listener or by testing return values
of listeners, test and loop through the results returned by listeners,
prioritize listeners, and more. Many of these features are detailed in the
examples.
|
