1: <?php
2: /**
3: * CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
4: * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
5: *
6: * Licensed under The MIT License
7: * For full copyright and license information, please see the LICENSE.txt
8: * Redistributions of files must retain the above copyright notice.
9: *
10: * @copyright Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
11: * @link https://cakephp.org CakePHP(tm) Project
12: * @since 2.1.0
13: * @license https://opensource.org/licenses/mit-license.php MIT License
14: */
15: namespace Cake\Event;
16:
17: /**
18: * Class Event
19: */
20: class Event implements EventInterface
21: {
22: /**
23: * Name of the event
24: *
25: * @var string
26: */
27: protected $_name;
28:
29: /**
30: * The object this event applies to (usually the same object that generates the event)
31: *
32: * @var object|null
33: */
34: protected $_subject;
35:
36: /**
37: * Custom data for the method that receives the event
38: *
39: * @var array
40: */
41: protected $_data;
42:
43: /**
44: * Property used to retain the result value of the event listeners
45: *
46: * Note: Public access is deprecated, use setResult() and getResult() instead.
47: *
48: * @var mixed
49: */
50: public $result;
51:
52: /**
53: * Flags an event as stopped or not, default is false
54: *
55: * @var bool
56: */
57: protected $_stopped = false;
58:
59: /**
60: * Constructor
61: *
62: * ### Examples of usage:
63: *
64: * ```
65: * $event = new Event('Order.afterBuy', $this, ['buyer' => $userData]);
66: * $event = new Event('User.afterRegister', $UserModel);
67: * ```
68: *
69: * @param string $name Name of the event
70: * @param object|null $subject the object that this event applies to (usually the object that is generating the event)
71: * @param array|\ArrayAccess|null $data any value you wish to be transported with this event to it can be read by listeners
72: */
73: public function __construct($name, $subject = null, $data = null)
74: {
75: $this->_name = $name;
76: $this->_subject = $subject;
77: $this->_data = (array)$data;
78: }
79:
80: /**
81: * Provides read-only access for the name and subject properties.
82: *
83: * @param string $attribute Attribute name.
84: * @return mixed
85: * @deprecated 3.4.0 Public properties will be removed.
86: */
87: public function __get($attribute)
88: {
89: if (!in_array($attribute, ['name', 'subject', 'data', 'result'])) {
90: return $this->{$attribute};
91: }
92:
93: $method = 'get' . ucfirst($attribute);
94: deprecationWarning(
95: "Event::\${$attribute} is deprecated. " .
96: "Use Event::{$method}() instead."
97: );
98: if ($attribute === 'name' || $attribute === 'subject') {
99: return $this->{$attribute}();
100: }
101: if ($attribute === 'data') {
102: return $this->_data;
103: }
104: if ($attribute === 'result') {
105: return $this->result;
106: }
107: }
108:
109: /**
110: * Provides backward compatibility for write access to data and result properties.
111: *
112: * @param string $attribute Attribute name.
113: * @param mixed $value The value to set.
114: * @return void
115: * @deprecated 3.4.0 Public properties will be removed.
116: */
117: public function __set($attribute, $value)
118: {
119: $method = 'set' . ucfirst($attribute);
120: deprecationWarning(
121: "Event::\${$attribute} is deprecated. " .
122: "Use Event::{$method}() instead."
123: );
124: if ($attribute === 'data') {
125: $this->_data = (array)$value;
126: }
127: if ($attribute === 'result') {
128: $this->result = $value;
129: }
130: }
131:
132: /**
133: * Returns the name of this event. This is usually used as the event identifier
134: *
135: * @return string
136: * @deprecated 3.4.0 use getName() instead.
137: */
138: public function name()
139: {
140: deprecationWarning('Event::name() is deprecated. Use Event::getName() instead.');
141:
142: return $this->_name;
143: }
144:
145: /**
146: * Returns the name of this event. This is usually used as the event identifier
147: *
148: * @return string
149: */
150: public function getName()
151: {
152: return $this->_name;
153: }
154:
155: /**
156: * Returns the subject of this event
157: *
158: * @return object
159: * @deprecated 3.4.0 use getSubject() instead.
160: */
161: public function subject()
162: {
163: deprecationWarning('Event::subject() is deprecated. Use Event::getSubject() instead.');
164:
165: return $this->_subject;
166: }
167:
168: /**
169: * Returns the subject of this event
170: *
171: * @return object
172: */
173: public function getSubject()
174: {
175: return $this->_subject;
176: }
177:
178: /**
179: * Stops the event from being used anymore
180: *
181: * @return void
182: */
183: public function stopPropagation()
184: {
185: $this->_stopped = true;
186: }
187:
188: /**
189: * Check if the event is stopped
190: *
191: * @return bool True if the event is stopped
192: */
193: public function isStopped()
194: {
195: return $this->_stopped;
196: }
197:
198: /**
199: * The result value of the event listeners
200: *
201: * @return mixed
202: * @deprecated 3.4.0 use getResult() instead.
203: */
204: public function result()
205: {
206: deprecationWarning('Event::result() is deprecated. Use Event::getResult() instead.');
207:
208: return $this->result;
209: }
210:
211: /**
212: * The result value of the event listeners
213: *
214: * @return mixed
215: */
216: public function getResult()
217: {
218: return $this->result;
219: }
220:
221: /**
222: * Listeners can attach a result value to the event.
223: *
224: * @param mixed $value The value to set.
225: * @return $this
226: */
227: public function setResult($value = null)
228: {
229: $this->result = $value;
230:
231: return $this;
232: }
233:
234: /**
235: * Access the event data/payload.
236: *
237: * @param string|null $key The data payload element to return, or null to return all data.
238: * @return array|mixed|null The data payload if $key is null, or the data value for the given $key. If the $key does not
239: * exist a null value is returned.
240: * @deprecated 3.4.0 use getData() instead.
241: */
242: public function data($key = null)
243: {
244: deprecationWarning('Event::data() is deprecated. Use Event::getData() instead.');
245:
246: return $this->getData($key);
247: }
248:
249: /**
250: * Access the event data/payload.
251: *
252: * @param string|null $key The data payload element to return, or null to return all data.
253: * @return array|mixed|null The data payload if $key is null, or the data value for the given $key. If the $key does not
254: * exist a null value is returned.
255: */
256: public function getData($key = null)
257: {
258: if ($key !== null) {
259: return isset($this->_data[$key]) ? $this->_data[$key] : null;
260: }
261:
262: return (array)$this->_data;
263: }
264:
265: /**
266: * Assigns a value to the data/payload of this event.
267: *
268: * @param array|string $key An array will replace all payload data, and a key will set just that array item.
269: * @param mixed $value The value to set.
270: * @return $this
271: */
272: public function setData($key, $value = null)
273: {
274: if (is_array($key)) {
275: $this->_data = $key;
276: } else {
277: $this->_data[$key] = $value;
278: }
279:
280: return $this;
281: }
282: }
283: