notifier / libraries / action-scheduler / functions.php

functions.php in WANotifier for Forms and Actions trunk, at libraries/action-scheduler/functions.php

514 lines 19.3 KB

Raw Download Zip

1	<?php
2	/**
3	* General API functions for scheduling actions
4	*
5	* @package ActionScheduler.
6	*/
7
8	/**
9	* Enqueue an action to run one time, as soon as possible
10	*
11	* @param string $hook The hook to trigger.
12	* @param array $args Arguments to pass when the hook triggers.
13	* @param string $group The group to assign this job to.
14	* @param bool $unique Whether the action should be unique. It will not be scheduled if another pending or running action has the same hook and group parameters.
15	* @param int $priority Lower values take precedence over higher values. Defaults to 10, with acceptable values falling in the range 0-255.
16	*
17	* @return int The action ID. Zero if there was an error scheduling the action.
18	*/
19	function as_enqueue_async_action( $hook, $args = array(), $group = '', $unique = false, $priority = 10 ) {
20	if ( ! ActionScheduler::is_initialized( __FUNCTION__ ) ) {
21	return 0;
22	}
23
24	/**
25	* Provides an opportunity to short-circuit the default process for enqueuing async
26	* actions.
27	*
28	* Returning a value other than null from the filter will short-circuit the normal
29	* process. The expectation in such a scenario is that callbacks will return an integer
30	* representing the enqueued action ID (enqueued using some alternative process) or else
31	* zero.
32	*
33	* @param int\|null $pre_option The value to return instead of the option value.
34	* @param string $hook Action hook.
35	* @param array $args Action arguments.
36	* @param string $group Action group.
37	* @param int $priority Action priority.
38	* @param bool $unique Unique action.
39	*/
40	$pre = apply_filters( 'pre_as_enqueue_async_action', null, $hook, $args, $group, $priority, $unique );
41	if ( null !== $pre ) {
42	return is_int( $pre ) ? $pre : 0;
43	}
44
45	return ActionScheduler::factory()->create(
46	array(
47	'type' => 'async',
48	'hook' => $hook,
49	'arguments' => $args,
50	'group' => $group,
51	'unique' => $unique,
52	'priority' => $priority,
53	)
54	);
55	}
56
57	/**
58	* Schedule an action to run one time
59	*
60	* @param int $timestamp When the job will run.
61	* @param string $hook The hook to trigger.
62	* @param array $args Arguments to pass when the hook triggers.
63	* @param string $group The group to assign this job to.
64	* @param bool $unique Whether the action should be unique. It will not be scheduled if another pending or running action has the same hook and group parameters.
65	* @param int $priority Lower values take precedence over higher values. Defaults to 10, with acceptable values falling in the range 0-255.
66	*
67	* @return int The action ID. Zero if there was an error scheduling the action.
68	*/
69	function as_schedule_single_action( $timestamp, $hook, $args = array(), $group = '', $unique = false, $priority = 10 ) {
70	if ( ! ActionScheduler::is_initialized( __FUNCTION__ ) ) {
71	return 0;
72	}
73
74	/**
75	* Provides an opportunity to short-circuit the default process for enqueuing single
76	* actions.
77	*
78	* Returning a value other than null from the filter will short-circuit the normal
79	* process. The expectation in such a scenario is that callbacks will return an integer
80	* representing the scheduled action ID (scheduled using some alternative process) or else
81	* zero.
82	*
83	* @param int\|null $pre_option The value to return instead of the option value.
84	* @param int $timestamp When the action will run.
85	* @param string $hook Action hook.
86	* @param array $args Action arguments.
87	* @param string $group Action group.
88	* @param int $priorities Action priority.
89	* @param bool $unique Unique action.
90	*/
91	$pre = apply_filters( 'pre_as_schedule_single_action', null, $timestamp, $hook, $args, $group, $priority, $unique );
92	if ( null !== $pre ) {
93	return is_int( $pre ) ? $pre : 0;
94	}
95
96	return ActionScheduler::factory()->create(
97	array(
98	'type' => 'single',
99	'hook' => $hook,
100	'arguments' => $args,
101	'when' => $timestamp,
102	'group' => $group,
103	'unique' => $unique,
104	'priority' => $priority,
105	)
106	);
107	}
108
109	/**
110	* Schedule a recurring action
111	*
112	* @param int $timestamp When the first instance of the job will run.
113	* @param int $interval_in_seconds How long to wait between runs.
114	* @param string $hook The hook to trigger.
115	* @param array $args Arguments to pass when the hook triggers.
116	* @param string $group The group to assign this job to.
117	* @param bool $unique Whether the action should be unique. It will not be scheduled if another pending or running action has the same hook and group parameters.
118	* @param int $priority Lower values take precedence over higher values. Defaults to 10, with acceptable values falling in the range 0-255.
119	*
120	* @return int The action ID. Zero if there was an error scheduling the action.
121	*/
122	function as_schedule_recurring_action( $timestamp, $interval_in_seconds, $hook, $args = array(), $group = '', $unique = false, $priority = 10 ) {
123	if ( ! ActionScheduler::is_initialized( __FUNCTION__ ) ) {
124	return 0;
125	}
126
127	$interval = (int) $interval_in_seconds;
128
129	// We expect an integer and allow it to be passed using float and string types, but otherwise
130	// should reject unexpected values.
131	// phpcs:ignore WordPress.PHP.StrictComparisons.LooseComparison
132	if ( ! is_numeric( $interval_in_seconds ) \|\| $interval_in_seconds != $interval ) {
133	_doing_it_wrong(
134	__METHOD__,
135	sprintf(
136	/* translators: 1: provided value 2: provided type. */
137	esc_html__( 'An integer was expected but "%1$s" (%2$s) was received.', 'action-scheduler' ),
138	esc_html( $interval_in_seconds ),
139	esc_html( gettype( $interval_in_seconds ) )
140	),
141	'3.6.0'
142	);
143
144	return 0;
145	}
146
147	/**
148	* Provides an opportunity to short-circuit the default process for enqueuing recurring
149	* actions.
150	*
151	* Returning a value other than null from the filter will short-circuit the normal
152	* process. The expectation in such a scenario is that callbacks will return an integer
153	* representing the scheduled action ID (scheduled using some alternative process) or else
154	* zero.
155	*
156	* @param int\|null $pre_option The value to return instead of the option value.
157	* @param int $timestamp When the action will run.
158	* @param int $interval_in_seconds How long to wait between runs.
159	* @param string $hook Action hook.
160	* @param array $args Action arguments.
161	* @param string $group Action group.
162	* @param int $priority Action priority.
163	* @param bool $unique Unique action.
164	*/
165	$pre = apply_filters( 'pre_as_schedule_recurring_action', null, $timestamp, $interval_in_seconds, $hook, $args, $group, $priority, $unique );
166	if ( null !== $pre ) {
167	return is_int( $pre ) ? $pre : 0;
168	}
169
170	return ActionScheduler::factory()->create(
171	array(
172	'type' => 'recurring',
173	'hook' => $hook,
174	'arguments' => $args,
175	'when' => $timestamp,
176	'pattern' => $interval_in_seconds,
177	'group' => $group,
178	'unique' => $unique,
179	'priority' => $priority,
180	)
181	);
182	}
183
184	/**
185	* Schedule an action that recurs on a cron-like schedule.
186	*
187	* @param int $timestamp The first instance of the action will be scheduled
188	* to run at a time calculated after this timestamp matching the cron
189	* expression. This can be used to delay the first instance of the action.
190	* @param string $schedule A cron-link schedule string.
191	* @see http://en.wikipedia.org/wiki/Cron
192	* * * * * * *
193	* ┬ ┬ ┬ ┬ ┬ ┬
194	* \| \| \| \| \| \|
195	* \| \| \| \| \| + year [optional]
196	* \| \| \| \| +----- day of week (0 - 7) (Sunday=0 or 7)
197	* \| \| \| +---------- month (1 - 12)
198	* \| \| +--------------- day of month (1 - 31)
199	* \| +-------------------- hour (0 - 23)
200	* +------------------------- min (0 - 59)
201	* @param string $hook The hook to trigger.
202	* @param array $args Arguments to pass when the hook triggers.
203	* @param string $group The group to assign this job to.
204	* @param bool $unique Whether the action should be unique. It will not be scheduled if another pending or running action has the same hook and group parameters.
205	* @param int $priority Lower values take precedence over higher values. Defaults to 10, with acceptable values falling in the range 0-255.
206	*
207	* @return int The action ID. Zero if there was an error scheduling the action.
208	*/
209	function as_schedule_cron_action( $timestamp, $schedule, $hook, $args = array(), $group = '', $unique = false, $priority = 10 ) {
210	if ( ! ActionScheduler::is_initialized( __FUNCTION__ ) ) {
211	return 0;
212	}
213
214	/**
215	* Provides an opportunity to short-circuit the default process for enqueuing cron
216	* actions.
217	*
218	* Returning a value other than null from the filter will short-circuit the normal
219	* process. The expectation in such a scenario is that callbacks will return an integer
220	* representing the scheduled action ID (scheduled using some alternative process) or else
221	* zero.
222	*
223	* @param int\|null $pre_option The value to return instead of the option value.
224	* @param int $timestamp When the action will run.
225	* @param string $schedule Cron-like schedule string.
226	* @param string $hook Action hook.
227	* @param array $args Action arguments.
228	* @param string $group Action group.
229	* @param int $priority Action priority.
230	* @param bool $unique Unique action.
231	*/
232	$pre = apply_filters( 'pre_as_schedule_cron_action', null, $timestamp, $schedule, $hook, $args, $group, $priority, $unique );
233	if ( null !== $pre ) {
234	return is_int( $pre ) ? $pre : 0;
235	}
236
237	return ActionScheduler::factory()->create(
238	array(
239	'type' => 'cron',
240	'hook' => $hook,
241	'arguments' => $args,
242	'when' => $timestamp,
243	'pattern' => $schedule,
244	'group' => $group,
245	'unique' => $unique,
246	'priority' => $priority,
247	)
248	);
249	}
250
251	/**
252	* Cancel the next occurrence of a scheduled action.
253	*
254	* While only the next instance of a recurring or cron action is unscheduled by this method, that will also prevent
255	* all future instances of that recurring or cron action from being run. Recurring and cron actions are scheduled in
256	* a sequence instead of all being scheduled at once. Each successive occurrence of a recurring action is scheduled
257	* only after the former action is run. If the next instance is never run, because it's unscheduled by this function,
258	* then the following instance will never be scheduled (or exist), which is effectively the same as being unscheduled
259	* by this method also.
260	*
261	* @param string $hook The hook that the job will trigger.
262	* @param array $args Args that would have been passed to the job.
263	* @param string $group The group the job is assigned to.
264	*
265	* @return int\|null The scheduled action ID if a scheduled action was found, or null if no matching action found.
266	*/
267	function as_unschedule_action( $hook, $args = array(), $group = '' ) {
268	if ( ! ActionScheduler::is_initialized( __FUNCTION__ ) ) {
269	return 0;
270	}
271	$params = array(
272	'hook' => $hook,
273	'status' => ActionScheduler_Store::STATUS_PENDING,
274	'orderby' => 'date',
275	'order' => 'ASC',
276	'group' => $group,
277	);
278	if ( is_array( $args ) ) {
279	$params['args'] = $args;
280	}
281
282	$action_id = ActionScheduler::store()->query_action( $params );
283
284	if ( $action_id ) {
285	try {
286	ActionScheduler::store()->cancel_action( $action_id );
287	} catch ( Exception $exception ) {
288	ActionScheduler::logger()->log(
289	$action_id,
290	sprintf(
291	/* translators: %1$s is the name of the hook to be cancelled, %2$s is the exception message. */
292	__( 'Caught exception while cancelling action "%1$s": %2$s', 'action-scheduler' ),
293	$hook,
294	$exception->getMessage()
295	)
296	);
297
298	$action_id = null;
299	}
300	}
301
302	return $action_id;
303	}
304
305	/**
306	* Cancel all occurrences of a scheduled action.
307	*
308	* @param string $hook The hook that the job will trigger.
309	* @param array $args Args that would have been passed to the job.
310	* @param string $group The group the job is assigned to.
311	*/
312	function as_unschedule_all_actions( $hook, $args = array(), $group = '' ) {
313	if ( ! ActionScheduler::is_initialized( __FUNCTION__ ) ) {
314	return;
315	}
316	if ( empty( $args ) ) {
317	if ( ! empty( $hook ) && empty( $group ) ) {
318	ActionScheduler_Store::instance()->cancel_actions_by_hook( $hook );
319	return;
320	}
321	if ( ! empty( $group ) && empty( $hook ) ) {
322	ActionScheduler_Store::instance()->cancel_actions_by_group( $group );
323	return;
324	}
325	}
326	do {
327	$unscheduled_action = as_unschedule_action( $hook, $args, $group );
328	} while ( ! empty( $unscheduled_action ) );
329	}
330
331	/**
332	* Check if there is an existing action in the queue with a given hook, args and group combination.
333	*
334	* An action in the queue could be pending, in-progress or async. If the is pending for a time in
335	* future, its scheduled date will be returned as a timestamp. If it is currently being run, or an
336	* async action sitting in the queue waiting to be processed, in which case boolean true will be
337	* returned. Or there may be no async, in-progress or pending action for this hook, in which case,
338	* boolean false will be the return value.
339	*
340	* @param string $hook Name of the hook to search for.
341	* @param array $args Arguments of the action to be searched.
342	* @param string $group Group of the action to be searched.
343	*
344	* @return int\|bool The timestamp for the next occurrence of a pending scheduled action, true for an async or in-progress action or false if there is no matching action.
345	*/
346	function as_next_scheduled_action( $hook, $args = null, $group = '' ) {
347	if ( ! ActionScheduler::is_initialized( __FUNCTION__ ) ) {
348	return false;
349	}
350
351	$params = array(
352	'hook' => $hook,
353	'orderby' => 'date',
354	'order' => 'ASC',
355	'group' => $group,
356	);
357
358	if ( is_array( $args ) ) {
359	$params['args'] = $args;
360	}
361
362	$params['status'] = ActionScheduler_Store::STATUS_RUNNING;
363	$action_id = ActionScheduler::store()->query_action( $params );
364	if ( $action_id ) {
365	return true;
366	}
367
368	$params['status'] = ActionScheduler_Store::STATUS_PENDING;
369	$action_id = ActionScheduler::store()->query_action( $params );
370	if ( null === $action_id ) {
371	return false;
372	}
373
374	$action = ActionScheduler::store()->fetch_action( $action_id );
375	$scheduled_date = $action->get_schedule()->get_date();
376	if ( $scheduled_date ) {
377	return (int) $scheduled_date->format( 'U' );
378	} elseif ( null === $scheduled_date ) { // pending async action with NullSchedule.
379	return true;
380	}
381
382	return false;
383	}
384
385	/**
386	* Check if there is a scheduled action in the queue but more efficiently than as_next_scheduled_action().
387	*
388	* It's recommended to use this function when you need to know whether a specific action is currently scheduled
389	* (pending or in-progress).
390	*
391	* @since 3.3.0
392	*
393	* @param string $hook The hook of the action.
394	* @param array $args Args that have been passed to the action. Null will matches any args.
395	* @param string $group The group the job is assigned to.
396	*
397	* @return bool True if a matching action is pending or in-progress, false otherwise.
398	*/
399	function as_has_scheduled_action( $hook, $args = null, $group = '' ) {
400	if ( ! ActionScheduler::is_initialized( __FUNCTION__ ) ) {
401	return false;
402	}
403
404	$query_args = array(
405	'hook' => $hook,
406	'status' => array( ActionScheduler_Store::STATUS_RUNNING, ActionScheduler_Store::STATUS_PENDING ),
407	'group' => $group,
408	'orderby' => 'none',
409	);
410
411	if ( null !== $args ) {
412	$query_args['args'] = $args;
413	}
414
415	$action_id = ActionScheduler::store()->query_action( $query_args );
416
417	return null !== $action_id;
418	}
419
420	/**
421	* Find scheduled actions
422	*
423	* @param array $args Possible arguments, with their default values.
424	* 'hook' => '' - the name of the action that will be triggered.
425	* 'args' => NULL - the args array that will be passed with the action.
426	* 'date' => NULL - the scheduled date of the action. Expects a DateTime object, a unix timestamp, or a string that can parsed with strtotime(). Used in UTC timezone.
427	* 'date_compare' => '<=' - operator for testing "date". accepted values are '!=', '>', '>=', '<', '<=', '='.
428	* 'modified' => NULL - the date the action was last updated. Expects a DateTime object, a unix timestamp, or a string that can parsed with strtotime(). Used in UTC timezone.
429	* 'modified_compare' => '<=' - operator for testing "modified". accepted values are '!=', '>', '>=', '<', '<=', '='.
430	* 'group' => '' - the group the action belongs to.
431	* 'status' => '' - ActionScheduler_Store::STATUS_COMPLETE or ActionScheduler_Store::STATUS_PENDING.
432	* 'claimed' => NULL - TRUE to find claimed actions, FALSE to find unclaimed actions, a string to find a specific claim ID.
433	* 'per_page' => 5 - Number of results to return.
434	* 'offset' => 0.
435	* 'orderby' => 'date' - accepted values are 'hook', 'group', 'modified', 'date' or 'none'.
436	* 'order' => 'ASC'.
437	*
438	* @param string $return_format OBJECT, ARRAY_A, or ids.
439	*
440	* @return array
441	*/
442	function as_get_scheduled_actions( $args = array(), $return_format = OBJECT ) {
443	if ( ! ActionScheduler::is_initialized( __FUNCTION__ ) ) {
444	return array();
445	}
446	$store = ActionScheduler::store();
447	foreach ( array( 'date', 'modified' ) as $key ) {
448	if ( isset( $args[ $key ] ) ) {
449	$args[ $key ] = as_get_datetime_object( $args[ $key ] );
450	}
451	}
452	$ids = $store->query_actions( $args );
453
454	if ( 'ids' === $return_format \|\| 'int' === $return_format ) {
455	return $ids;
456	}
457
458	$actions = array();
459	foreach ( $ids as $action_id ) {
460	$actions[ $action_id ] = $store->fetch_action( $action_id );
461	}
462
463	if ( ARRAY_A === $return_format ) {
464	foreach ( $actions as $action_id => $action_object ) {
465	$actions[ $action_id ] = get_object_vars( $action_object );
466	}
467	}
468
469	return $actions;
470	}
471
472	/**
473	* Helper function to create an instance of DateTime based on a given
474	* string and timezone. By default, will return the current date/time
475	* in the UTC timezone.
476	*
477	* Needed because new DateTime() called without an explicit timezone
478	* will create a date/time in PHP's timezone, but we need to have
479	* assurance that a date/time uses the right timezone (which we almost
480	* always want to be UTC), which means we need to always include the
481	* timezone when instantiating datetimes rather than leaving it up to
482	* the PHP default.
483	*
484	* @param mixed $date_string A date/time string. Valid formats are explained in http://php.net/manual/en/datetime.formats.php.
485	* @param string $timezone A timezone identifier, like UTC or Europe/Lisbon. The list of valid identifiers is available http://php.net/manual/en/timezones.php.
486	*
487	* @return ActionScheduler_DateTime
488	*/
489	function as_get_datetime_object( $date_string = null, $timezone = 'UTC' ) {
490	if ( is_object( $date_string ) && $date_string instanceof DateTime ) {
491	$date = new ActionScheduler_DateTime( $date_string->format( 'Y-m-d H:i:s' ), new DateTimeZone( $timezone ) );
492	} elseif ( is_numeric( $date_string ) ) {
493	$date = new ActionScheduler_DateTime( '@' . $date_string, new DateTimeZone( $timezone ) );
494	} else {
495	$date = new ActionScheduler_DateTime( null === $date_string ? 'now' : $date_string, new DateTimeZone( $timezone ) );
496	}
497	return $date;
498	}
499
500	/**
501	* Check if a specific feature is supported by the current version of Action Scheduler.
502	*
503	* @since 3.9.3
504	*
505	* @param string $feature The feature to check support for.
506	*
507	* @return bool True if the feature is supported, false otherwise.
508	*/
509	function as_supports( string $feature ): bool {
510	$supported_features = array( 'ensure_recurring_actions_hook' );
511
512	return in_array( $feature, $supported_features, true );
513	}
514