notifier / libraries / action-scheduler / functions.php

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

334 lines 11.9 KB

Raw Download Zip

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