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