notifier / libraries / action-scheduler / functions.php

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

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