notifier / libraries / action-scheduler / classes / abstracts / ActionScheduler_Store.php

ActionScheduler_Store.php in WANotifier for Forms and Actions 1.0.0, at libraries/action-scheduler/classes/abstracts/ActionScheduler_Store.php

423 lines 12.3 KB

Raw Download Zip

1	<?php
2
3	/**
4	* Class ActionScheduler_Store
5	* @codeCoverageIgnore
6	*/
7	abstract class ActionScheduler_Store extends ActionScheduler_Store_Deprecated {
8	const STATUS_COMPLETE = 'complete';
9	const STATUS_PENDING = 'pending';
10	const STATUS_RUNNING = 'in-progress';
11	const STATUS_FAILED = 'failed';
12	const STATUS_CANCELED = 'canceled';
13	const DEFAULT_CLASS = 'ActionScheduler_wpPostStore';
14
15	/** @var ActionScheduler_Store */
16	private static $store = NULL;
17
18	/** @var int */
19	protected static $max_args_length = 191;
20
21	/**
22	* @param ActionScheduler_Action $action
23	* @param DateTime $scheduled_date Optional Date of the first instance
24	* to store. Otherwise uses the first date of the action's
25	* schedule.
26	*
27	* @return int The action ID
28	*/
29	abstract public function save_action( ActionScheduler_Action $action, DateTime $scheduled_date = NULL );
30
31	/**
32	* @param string $action_id
33	*
34	* @return ActionScheduler_Action
35	*/
36	abstract public function fetch_action( $action_id );
37
38	/**
39	* Find an action.
40	*
41	* Note: the query ordering changes based on the passed 'status' value.
42	*
43	* @param string $hook Action hook.
44	* @param array $params Parameters of the action to find.
45	*
46	* @return string\|null ID of the next action matching the criteria or NULL if not found.
47	*/
48	public function find_action( $hook, $params = array() ) {
49	$params = wp_parse_args(
50	$params,
51	array(
52	'args' => null,
53	'status' => self::STATUS_PENDING,
54	'group' => '',
55	)
56	);
57
58	// These params are fixed for this method.
59	$params['hook'] = $hook;
60	$params['orderby'] = 'date';
61	$params['per_page'] = 1;
62
63	if ( ! empty( $params['status'] ) ) {
64	if ( self::STATUS_PENDING === $params['status'] ) {
65	$params['order'] = 'ASC'; // Find the next action that matches.
66	} else {
67	$params['order'] = 'DESC'; // Find the most recent action that matches.
68	}
69	}
70
71	$results = $this->query_actions( $params );
72
73	return empty( $results ) ? null : $results[0];
74	}
75
76	/**
77	* Query for action count or list of action IDs.
78	*
79	* @since 3.3.0 $query['status'] accepts array of statuses instead of a single status.
80	*
81	* @param array $query {
82	* Query filtering options.
83	*
84	* @type string $hook The name of the actions. Optional.
85	* @type string\|array $status The status or statuses of the actions. Optional.
86	* @type array $args The args array of the actions. Optional.
87	* @type DateTime $date The scheduled date of the action. Used in UTC timezone. Optional.
88	* @type string $date_compare Operator for selecting by $date param. Accepted values are '!=', '>', '>=', '<', '<=', '='. Defaults to '<='.
89	* @type DateTime $modified The last modified date of the action. Used in UTC timezone. Optional.
90	* @type string $modified_compare Operator for comparing $modified param. Accepted values are '!=', '>', '>=', '<', '<=', '='. Defaults to '<='.
91	* @type string $group The group the action belongs to. Optional.
92	* @type bool\|int $claimed TRUE to find claimed actions, FALSE to find unclaimed actions, an int to find a specific claim ID. Optional.
93	* @type int $per_page Number of results to return. Defaults to 5.
94	* @type int $offset The query pagination offset. Defaults to 0.
95	* @type int $orderby Accepted values are 'hook', 'group', 'modified', 'date' or 'none'. Defaults to 'date'.
96	* @type string $order Accepted values are 'ASC' or 'DESC'. Defaults to 'ASC'.
97	* }
98	* @param string $query_type Whether to select or count the results. Default, select.
99	*
100	* @return string\|array\|null The IDs of actions matching the query. Null on failure.
101	*/
102	abstract public function query_actions( $query = array(), $query_type = 'select' );
103
104	/**
105	* Run query to get a single action ID.
106	*
107	* @since 3.3.0
108	*
109	* @see ActionScheduler_Store::query_actions for $query arg usage but 'per_page' and 'offset' can't be used.
110	*
111	* @param array $query Query parameters.
112	*
113	* @return int\|null
114	*/
115	public function query_action( $query ) {
116	$query['per_page'] = 1;
117	$query['offset'] = 0;
118	$results = $this->query_actions( $query );
119
120	if ( empty( $results ) ) {
121	return null;
122	} else {
123	return (int) $results[0];
124	}
125	}
126
127	/**
128	* Get a count of all actions in the store, grouped by status
129	*
130	* @return array
131	*/
132	abstract public function action_counts();
133
134	/**
135	* @param string $action_id
136	*/
137	abstract public function cancel_action( $action_id );
138
139	/**
140	* @param string $action_id
141	*/
142	abstract public function delete_action( $action_id );
143
144	/**
145	* @param string $action_id
146	*
147	* @return DateTime The date the action is schedule to run, or the date that it ran.
148	*/
149	abstract public function get_date( $action_id );
150
151
152	/**
153	* @param int $max_actions
154	* @param DateTime $before_date Claim only actions schedule before the given date. Defaults to now.
155	* @param array $hooks Claim only actions with a hook or hooks.
156	* @param string $group Claim only actions in the given group.
157	*
158	* @return ActionScheduler_ActionClaim
159	*/
160	abstract public function stake_claim( $max_actions = 10, DateTime $before_date = null, $hooks = array(), $group = '' );
161
162	/**
163	* @return int
164	*/
165	abstract public function get_claim_count();
166
167	/**
168	* @param ActionScheduler_ActionClaim $claim
169	*/
170	abstract public function release_claim( ActionScheduler_ActionClaim $claim );
171
172	/**
173	* @param string $action_id
174	*/
175	abstract public function unclaim_action( $action_id );
176
177	/**
178	* @param string $action_id
179	*/
180	abstract public function mark_failure( $action_id );
181
182	/**
183	* @param string $action_id
184	*/
185	abstract public function log_execution( $action_id );
186
187	/**
188	* @param string $action_id
189	*/
190	abstract public function mark_complete( $action_id );
191
192	/**
193	* @param string $action_id
194	*
195	* @return string
196	*/
197	abstract public function get_status( $action_id );
198
199	/**
200	* @param string $action_id
201	* @return mixed
202	*/
203	abstract public function get_claim_id( $action_id );
204
205	/**
206	* @param string $claim_id
207	* @return array
208	*/
209	abstract public function find_actions_by_claim_id( $claim_id );
210
211	/**
212	* @param string $comparison_operator
213	* @return string
214	*/
215	protected function validate_sql_comparator( $comparison_operator ) {
216	if ( in_array( $comparison_operator, array('!=', '>', '>=', '<', '<=', '=') ) ) {
217	return $comparison_operator;
218	}
219	return '=';
220	}
221
222	/**
223	* Get the time MySQL formated date/time string for an action's (next) scheduled date.
224	*
225	* @param ActionScheduler_Action $action
226	* @param DateTime $scheduled_date (optional)
227	* @return string
228	*/
229	protected function get_scheduled_date_string( ActionScheduler_Action $action, DateTime $scheduled_date = NULL ) {
230	$next = null === $scheduled_date ? $action->get_schedule()->get_date() : $scheduled_date;
231	if ( ! $next ) {
232	return '0000-00-00 00:00:00';
233	}
234	$next->setTimezone( new DateTimeZone( 'UTC' ) );
235
236	return $next->format( 'Y-m-d H:i:s' );
237	}
238
239	/**
240	* Get the time MySQL formated date/time string for an action's (next) scheduled date.
241	*
242	* @param ActionScheduler_Action $action
243	* @param DateTime $scheduled_date (optional)
244	* @return string
245	*/
246	protected function get_scheduled_date_string_local( ActionScheduler_Action $action, DateTime $scheduled_date = NULL ) {
247	$next = null === $scheduled_date ? $action->get_schedule()->get_date() : $scheduled_date;
248	if ( ! $next ) {
249	return '0000-00-00 00:00:00';
250	}
251
252	ActionScheduler_TimezoneHelper::set_local_timezone( $next );
253	return $next->format( 'Y-m-d H:i:s' );
254	}
255
256	/**
257	* Validate that we could decode action arguments.
258	*
259	* @param mixed $args The decoded arguments.
260	* @param int $action_id The action ID.
261	*
262	* @throws ActionScheduler_InvalidActionException When the decoded arguments are invalid.
263	*/
264	protected function validate_args( $args, $action_id ) {
265	// Ensure we have an array of args.
266	if ( ! is_array( $args ) ) {
267	throw ActionScheduler_InvalidActionException::from_decoding_args( $action_id );
268	}
269
270	// Validate JSON decoding if possible.
271	if ( function_exists( 'json_last_error' ) && JSON_ERROR_NONE !== json_last_error() ) {
272	throw ActionScheduler_InvalidActionException::from_decoding_args( $action_id, $args );
273	}
274	}
275
276	/**
277	* Validate a ActionScheduler_Schedule object.
278	*
279	* @param mixed $schedule The unserialized ActionScheduler_Schedule object.
280	* @param int $action_id The action ID.
281	*
282	* @throws ActionScheduler_InvalidActionException When the schedule is invalid.
283	*/
284	protected function validate_schedule( $schedule, $action_id ) {
285	if ( empty( $schedule ) \|\| ! is_a( $schedule, 'ActionScheduler_Schedule' ) ) {
286	throw ActionScheduler_InvalidActionException::from_schedule( $action_id, $schedule );
287	}
288	}
289
290	/**
291	* InnoDB indexes have a maximum size of 767 bytes by default, which is only 191 characters with utf8mb4.
292	*
293	* Previously, AS wasn't concerned about args length, as we used the (unindex) post_content column. However,
294	* with custom tables, we use an indexed VARCHAR column instead.
295	*
296	* @param ActionScheduler_Action $action Action to be validated.
297	* @throws InvalidArgumentException When json encoded args is too long.
298	*/
299	protected function validate_action( ActionScheduler_Action $action ) {
300	if ( strlen( json_encode( $action->get_args() ) ) > static::$max_args_length ) {
301	throw new InvalidArgumentException( sprintf( __( 'ActionScheduler_Action::$args too long. To ensure the args column can be indexed, action args should not be more than %d characters when encoded as JSON.', 'action-scheduler' ), static::$max_args_length ) );
302	}
303	}
304
305	/**
306	* Cancel pending actions by hook.
307	*
308	* @since 3.0.0
309	*
310	* @param string $hook Hook name.
311	*
312	* @return void
313	*/
314	public function cancel_actions_by_hook( $hook ) {
315	$action_ids = true;
316	while ( ! empty( $action_ids ) ) {
317	$action_ids = $this->query_actions(
318	array(
319	'hook' => $hook,
320	'status' => self::STATUS_PENDING,
321	'per_page' => 1000,
322	'orderby' => 'action_id',
323	)
324	);
325
326	$this->bulk_cancel_actions( $action_ids );
327	}
328	}
329
330	/**
331	* Cancel pending actions by group.
332	*
333	* @since 3.0.0
334	*
335	* @param string $group Group slug.
336	*
337	* @return void
338	*/
339	public function cancel_actions_by_group( $group ) {
340	$action_ids = true;
341	while ( ! empty( $action_ids ) ) {
342	$action_ids = $this->query_actions(
343	array(
344	'group' => $group,
345	'status' => self::STATUS_PENDING,
346	'per_page' => 1000,
347	'orderby' => 'action_id',
348	)
349	);
350
351	$this->bulk_cancel_actions( $action_ids );
352	}
353	}
354
355	/**
356	* Cancel a set of action IDs.
357	*
358	* @since 3.0.0
359	*
360	* @param array $action_ids List of action IDs.
361	*
362	* @return void
363	*/
364	private function bulk_cancel_actions( $action_ids ) {
365	foreach ( $action_ids as $action_id ) {
366	$this->cancel_action( $action_id );
367	}
368
369	do_action( 'action_scheduler_bulk_cancel_actions', $action_ids );
370	}
371
372	/**
373	* @return array
374	*/
375	public function get_status_labels() {
376	return array(
377	self::STATUS_COMPLETE => __( 'Complete', 'action-scheduler' ),
378	self::STATUS_PENDING => __( 'Pending', 'action-scheduler' ),
379	self::STATUS_RUNNING => __( 'In-progress', 'action-scheduler' ),
380	self::STATUS_FAILED => __( 'Failed', 'action-scheduler' ),
381	self::STATUS_CANCELED => __( 'Canceled', 'action-scheduler' ),
382	);
383	}
384
385	/**
386	* Check if there are any pending scheduled actions due to run.
387	*
388	* @param ActionScheduler_Action $action
389	* @param DateTime $scheduled_date (optional)
390	* @return string
391	*/
392	public function has_pending_actions_due() {
393	$pending_actions = $this->query_actions( array(
394	'date' => as_get_datetime_object(),
395	'status' => ActionScheduler_Store::STATUS_PENDING,
396	'orderby' => 'none',
397	) );
398
399	return ! empty( $pending_actions );
400	}
401
402	/**
403	* Callable initialization function optionally overridden in derived classes.
404	*/
405	public function init() {}
406
407	/**
408	* Callable function to mark an action as migrated optionally overridden in derived classes.
409	*/
410	public function mark_migrated( $action_id ) {}
411
412	/**
413	* @return ActionScheduler_Store
414	*/
415	public static function instance() {
416	if ( empty( self::$store ) ) {
417	$class = apply_filters( 'action_scheduler_store_class', self::DEFAULT_CLASS );
418	self::$store = new $class();
419	}
420	return self::$store;
421	}
422	}
423