1: <?php
2:
3: namespace Charcoal\Queue;
4:
5: // Dependencies from `PHP`
6: use \DateTime;
7: use \DateTimeInterface;
8: use \Exception;
9: use \InvalidArgumentException;
10:
11: /**
12: *
13: */
14: trait QueueItemTrait
15: {
16: /**
17: * The queue ID.
18: *
19: * @var mixed $queueId
20: */
21: private $queueId;
22:
23: /**
24: * Whether the item has been processed.
25: *
26: * @var boolean $processed
27: */
28: private $processed = false;
29:
30: /**
31: * When the item was queued.
32: *
33: * @var DateTimeInterface $queuedDate
34: */
35: private $queuedDate;
36:
37: /**
38: * When the item should be processed.
39: *
40: * The date/time at which this queue item job should be ran.
41: * If NULL, 0, or a past date/time, then it should be performed immediately.
42: *
43: * @var DateTimeInterface $processingDate
44: */
45: private $processingDate;
46:
47: /**
48: * When the item was processed.
49: *
50: * @var DateTimeInterface $processedDate
51: */
52: private $processedDate;
53:
54: /**
55: * Process the item.
56: *
57: * @param callable $callback An optional callback routine executed after the item is processed.
58: * @param callable $successCallback An optional callback routine executed when the item is resolved.
59: * @param callable $failureCallback An optional callback routine executed when the item is rejected.
60: * @return boolean Success / Failure
61: */
62: abstract public function process(
63: callable $callback = null,
64: callable $successCallback = null,
65: callable $failureCallback = null
66: );
67:
68: /**
69: * Set the queue item's data.
70: *
71: * @param array $data The queue item data to set.
72: * @return QueueItemTrait Chainable
73: */
74: public function setQueueItemData(array $data)
75: {
76: if (isset($data['queue_id'])) {
77: $this->setQueueId($data['queue_id']);
78: }
79:
80: if (isset($data['processed'])) {
81: $this->setProcessed($data['processed']);
82: }
83:
84: if (isset($data['queued_date'])) {
85: $this->setQueuedDate($data['queue_date']);
86: }
87:
88: if (isset($data['processed_date'])) {
89: $this->setProcessedDate($data['processed_date']);
90: }
91:
92: return $this;
93: }
94:
95: /**
96: * Set the queue's ID.
97: *
98: * @param mixed $id The unique queue identifier.
99: * @return QueueItemInterface Chainable
100: */
101: public function setQueueId($id)
102: {
103: $this->queueId = $id;
104: return $this;
105: }
106:
107: /**
108: * Get the queue's ID.
109: *
110: * @return mixed
111: */
112: public function queueId()
113: {
114: return $this->queueId;
115: }
116:
117: /**
118: * Set the item's processed status.
119: *
120: * @param boolean $processed Whether the item has been processed.
121: * @return QueueItemInterface Chainable
122: */
123: public function setProcessed($processed)
124: {
125: $this->processed = !!$processed;
126: return $this;
127: }
128:
129: /**
130: * Determine if the item has been processed.
131: *
132: * @return boolean
133: */
134: public function processed()
135: {
136: return $this->processed;
137: }
138:
139: /**
140: * Set the date/time the item was queued at.
141: *
142: * @param null|string|DateTimeInterface $ts A date/time string or object.
143: * @throws InvalidArgumentException If the date/time is invalid.
144: * @return QueueItemInterface Chainable
145: */
146: public function setQueuedDate($ts)
147: {
148: if ($ts === null) {
149: $this->queuedDate = null;
150: return $this;
151: }
152:
153: if (is_string($ts)) {
154: try {
155: $ts = new DateTime($ts);
156: } catch (Exception $e) {
157: throw new InvalidArgumentException(
158: sprintf('Can not set queued date: %s', $e->getMessage())
159: );
160: }
161: }
162:
163: if (!($ts instanceof DateTimeInterface)) {
164: throw new InvalidArgumentException(
165: 'Invalid "Queued Date" value. Must be a date/time string or a DateTime object.'
166: );
167: }
168:
169: $this->queuedDate = $ts;
170:
171: return $this;
172: }
173:
174: /**
175: * Retrieve the date/time the item was queued at.
176: *
177: * @return null|DateTimeInterface
178: */
179: public function queuedDate()
180: {
181: return $this->queuedDate;
182: }
183:
184: /**
185: * Set the date/time the item should be processed at.
186: *
187: * @param null|string|DateTimeInterface $ts A date/time string or object.
188: * @throws InvalidArgumentException If the date/time is invalid.
189: * @return QueueItemInterface Chainable
190: */
191: public function setProcessingDate($ts)
192: {
193: if ($ts === null) {
194: $this->processingDate = null;
195: return $this;
196: }
197:
198: if (is_string($ts)) {
199: try {
200: $ts = new DateTime($ts);
201: } catch (Exception $e) {
202: throw new InvalidArgumentException(
203: sprintf('%s (%s)', $e->getMessage(), $ts)
204: );
205: }
206: }
207:
208: if (!($ts instanceof DateTimeInterface)) {
209: throw new InvalidArgumentException(
210: 'Invalid "Processing Date" value. Must be a date/time string or a DateTime object.'
211: );
212: }
213:
214: $this->processingDate = $ts;
215:
216: return $this;
217: }
218:
219: /**
220: * Retrieve the date/time the item should be processed at.
221: *
222: * @return null|DateTimeInterface
223: */
224: public function processingDate()
225: {
226: return $this->processingDate;
227: }
228:
229: /**
230: * Set the date/time the item was processed at.
231: *
232: * @param null|string|DateTimeInterface $ts A date/time string or object.
233: * @throws InvalidArgumentException If the date/time is invalid.
234: * @return QueueItemInterface Chainable
235: */
236: public function setProcessedDate($ts)
237: {
238: if ($ts === null) {
239: $this->processedDate = null;
240: return $this;
241: }
242:
243: if (is_string($ts)) {
244: try {
245: $ts = new DateTime($ts);
246: } catch (Exception $e) {
247: throw new InvalidArgumentException(
248: sprintf('%s (%s)', $e->getMessage(), $ts)
249: );
250: }
251: }
252:
253: if (!($ts instanceof DateTimeInterface)) {
254: throw new InvalidArgumentException(
255: 'Invalid "Processed Date" value. Must be a date/time string or a DateTime object.'
256: );
257: }
258:
259: $this->processedDate = $ts;
260:
261: return $this;
262: }
263:
264: /**
265: * Retrieve the date/time the item was processed at.
266: *
267: * @return null|DateTimeInterface
268: */
269: public function processedDate()
270: {
271: return $this->processedDate;
272: }
273:
274: /**
275: * Hook called before saving the item.
276: *
277: * Presets the item as _to-be_ processed and queued now.
278: *
279: * @return QueueItemInterface Chainable
280: */
281: public function preSaveQueueItem()
282: {
283: $this->setProcessed(false);
284: $this->setQueuedDate('now');
285:
286: return $this;
287: }
288: }
289: