image-optimization / vendor / woocommerce / action-scheduler / functions.php

functions.php in Image Optimizer – Compress Images and Convert to WebP or AVIF 1.5.4, at vendor/woocommerce/action-scheduler/functions.php

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