notifier / libraries / action-scheduler / classes / ActionScheduler_ActionFactory.php

ActionScheduler_ActionFactory.php in WANotifier for Forms and Actions 2.7.5, at libraries/action-scheduler/classes/ActionScheduler_ActionFactory.php

260 lines 11.2 KB

Raw Download Zip

1	<?php
2
3	/**
4	* Class ActionScheduler_ActionFactory
5	*/
6	class ActionScheduler_ActionFactory {
7
8	/**
9	* Return stored actions for given params.
10	*
11	* @param string $status The action's status in the data store.
12	* @param string $hook The hook to trigger when this action runs.
13	* @param array $args Args to pass to callbacks when the hook is triggered.
14	* @param ActionScheduler_Schedule $schedule The action's schedule.
15	* @param string $group A group to put the action in.
16	*
17	* @return ActionScheduler_Action An instance of the stored action.
18	*/
19	public function get_stored_action( $status, $hook, array $args = array(), ActionScheduler_Schedule $schedule = null, $group = '' ) {
20
21	switch ( $status ) {
22	case ActionScheduler_Store::STATUS_PENDING:
23	$action_class = 'ActionScheduler_Action';
24	break;
25	case ActionScheduler_Store::STATUS_CANCELED:
26	$action_class = 'ActionScheduler_CanceledAction';
27	if ( ! is_null( $schedule ) && ! is_a( $schedule, 'ActionScheduler_CanceledSchedule' ) && ! is_a( $schedule, 'ActionScheduler_NullSchedule' ) ) {
28	$schedule = new ActionScheduler_CanceledSchedule( $schedule->get_date() );
29	}
30	break;
31	default:
32	$action_class = 'ActionScheduler_FinishedAction';
33	break;
34	}
35
36	$action_class = apply_filters( 'action_scheduler_stored_action_class', $action_class, $status, $hook, $args, $schedule, $group );
37
38	$action = new $action_class( $hook, $args, $schedule, $group );
39
40	/**
41	* Allow 3rd party code to change the instantiated action for a given hook, args, schedule and group.
42	*
43	* @param ActionScheduler_Action $action The instantiated action.
44	* @param string $hook The instantiated action's hook.
45	* @param array $args The instantiated action's args.
46	* @param ActionScheduler_Schedule $schedule The instantiated action's schedule.
47	* @param string $group The instantiated action's group.
48	*/
49	return apply_filters( 'action_scheduler_stored_action_instance', $action, $hook, $args, $schedule, $group );
50	}
51
52	/**
53	* Enqueue an action to run one time, as soon as possible (rather a specific scheduled time).
54	*
55	* This method creates a new action using the NullSchedule. In practice, this results in an action scheduled to
56	* execute "now". Therefore, it will generally run as soon as possible but is not prioritized ahead of other actions
57	* that are already past-due.
58	*
59	* @param string $hook The hook to trigger when this action runs.
60	* @param array $args Args to pass when the hook is triggered.
61	* @param string $group A group to put the action in.
62	*
63	* @return int The ID of the stored action.
64	*/
65	public function async( $hook, $args = array(), $group = '' ) {
66	return $this->async_unique( $hook, $args, $group, false );
67	}
68
69	/**
70	* Same as async, but also supports $unique param.
71	*
72	* @param string $hook The hook to trigger when this action runs.
73	* @param array $args Args to pass when the hook is triggered.
74	* @param string $group A group to put the action in.
75	* @param bool $unique Whether to ensure the action is unique.
76	*
77	* @return int The ID of the stored action.
78	*/
79	public function async_unique( $hook, $args = array(), $group = '', $unique = true ) {
80	$schedule = new ActionScheduler_NullSchedule();
81	$action = new ActionScheduler_Action( $hook, $args, $schedule, $group );
82	return $unique ? $this->store_unique_action( $action, $unique ) : $this->store( $action );
83	}
84
85	/**
86	* Create single action.
87	*
88	* @param string $hook The hook to trigger when this action runs.
89	* @param array $args Args to pass when the hook is triggered.
90	* @param int $when Unix timestamp when the action will run.
91	* @param string $group A group to put the action in.
92	*
93	* @return int The ID of the stored action.
94	*/
95	public function single( $hook, $args = array(), $when = null, $group = '' ) {
96	return $this->single_unique( $hook, $args, $when, $group, false );
97	}
98
99	/**
100	* Create single action only if there is no pending or running action with same name and params.
101	*
102	* @param string $hook The hook to trigger when this action runs.
103	* @param array $args Args to pass when the hook is triggered.
104	* @param int $when Unix timestamp when the action will run.
105	* @param string $group A group to put the action in.
106	* @param bool $unique Whether action scheduled should be unique.
107	*
108	* @return int The ID of the stored action.
109	*/
110	public function single_unique( $hook, $args = array(), $when = null, $group = '', $unique = true ) {
111	$date = as_get_datetime_object( $when );
112	$schedule = new ActionScheduler_SimpleSchedule( $date );
113	$action = new ActionScheduler_Action( $hook, $args, $schedule, $group );
114	return $unique ? $this->store_unique_action( $action ) : $this->store( $action );
115	}
116
117	/**
118	* Create the first instance of an action recurring on a given interval.
119	*
120	* @param string $hook The hook to trigger when this action runs.
121	* @param array $args Args to pass when the hook is triggered.
122	* @param int $first Unix timestamp for the first run.
123	* @param int $interval Seconds between runs.
124	* @param string $group A group to put the action in.
125	*
126	* @return int The ID of the stored action.
127	*/
128	public function recurring( $hook, $args = array(), $first = null, $interval = null, $group = '' ) {
129	return $this->recurring_unique( $hook, $args, $first, $interval, $group, false );
130	}
131
132	/**
133	* Create the first instance of an action recurring on a given interval only if there is no pending or running action with same name and params.
134	*
135	* @param string $hook The hook to trigger when this action runs.
136	* @param array $args Args to pass when the hook is triggered.
137	* @param int $first Unix timestamp for the first run.
138	* @param int $interval Seconds between runs.
139	* @param string $group A group to put the action in.
140	* @param bool $unique Whether action scheduled should be unique.
141	*
142	* @return int The ID of the stored action.
143	*/
144	public function recurring_unique( $hook, $args = array(), $first = null, $interval = null, $group = '', $unique = true ) {
145	if ( empty( $interval ) ) {
146	return $this->single_unique( $hook, $args, $first, $group, $unique );
147	}
148	$date = as_get_datetime_object( $first );
149	$schedule = new ActionScheduler_IntervalSchedule( $date, $interval );
150	$action = new ActionScheduler_Action( $hook, $args, $schedule, $group );
151	return $unique ? $this->store_unique_action( $action ) : $this->store( $action );
152	}
153
154	/**
155	* Create the first instance of an action recurring on a Cron schedule.
156	*
157	* @param string $hook The hook to trigger when this action runs.
158	* @param array $args Args to pass when the hook is triggered.
159	* @param int $base_timestamp The first instance of the action will be scheduled
160	* to run at a time calculated after this timestamp matching the cron
161	* expression. This can be used to delay the first instance of the action.
162	* @param int $schedule A cron definition string.
163	* @param string $group A group to put the action in.
164	*
165	* @return int The ID of the stored action.
166	*/
167	public function cron( $hook, $args = array(), $base_timestamp = null, $schedule = null, $group = '' ) {
168	return $this->cron_unique( $hook, $args, $base_timestamp, $schedule, $group, false );
169	}
170
171
172	/**
173	* Create the first instance of an action recurring on a Cron schedule only if there is no pending or running action with same name and params.
174	*
175	* @param string $hook The hook to trigger when this action runs.
176	* @param array $args Args to pass when the hook is triggered.
177	* @param int $base_timestamp The first instance of the action will be scheduled
178	* to run at a time calculated after this timestamp matching the cron
179	* expression. This can be used to delay the first instance of the action.
180	* @param int $schedule A cron definition string.
181	* @param string $group A group to put the action in.
182	* @param bool $unique Whether action scheduled should be unique.
183	*
184	* @return int The ID of the stored action.
185	**/
186	public function cron_unique( $hook, $args = array(), $base_timestamp = null, $schedule = null, $group = '', $unique = true ) {
187	if ( empty( $schedule ) ) {
188	return $this->single_unique( $hook, $args, $base_timestamp, $group, $unique );
189	}
190	$date = as_get_datetime_object( $base_timestamp );
191	$cron = CronExpression::factory( $schedule );
192	$schedule = new ActionScheduler_CronSchedule( $date, $cron );
193	$action = new ActionScheduler_Action( $hook, $args, $schedule, $group );
194	return $unique ? $this->store_unique_action( $action ) : $this->store( $action );
195	}
196
197	/**
198	* Create a successive instance of a recurring or cron action.
199	*
200	* Importantly, the action will be rescheduled to run based on the current date/time.
201	* That means when the action is scheduled to run in the past, the next scheduled date
202	* will be pushed forward. For example, if a recurring action set to run every hour
203	* was scheduled to run 5 seconds ago, it will be next scheduled for 1 hour in the
204	* future, which is 1 hour and 5 seconds from when it was last scheduled to run.
205	*
206	* Alternatively, if the action is scheduled to run in the future, and is run early,
207	* likely via manual intervention, then its schedule will change based on the time now.
208	* For example, if a recurring action set to run every day, and is run 12 hours early,
209	* it will run again in 24 hours, not 36 hours.
210	*
211	* This slippage is less of an issue with Cron actions, as the specific run time can
212	* be set for them to run, e.g. 1am each day. In those cases, and entire period would
213	* need to be missed before there was any change is scheduled, e.g. in the case of an
214	* action scheduled for 1am each day, the action would need to run an entire day late.
215	*
216	* @param ActionScheduler_Action $action The existing action.
217	*
218	* @return string The ID of the stored action
219	* @throws InvalidArgumentException If $action is not a recurring action.
220	*/
221	public function repeat( $action ) {
222	$schedule = $action->get_schedule();
223	$next = $schedule->get_next( as_get_datetime_object() );
224
225	if ( is_null( $next ) \|\| ! $schedule->is_recurring() ) {
226	throw new InvalidArgumentException( __( 'Invalid action - must be a recurring action.', 'action-scheduler' ) );
227	}
228
229	$schedule_class = get_class( $schedule );
230	$new_schedule = new $schedule( $next, $schedule->get_recurrence(), $schedule->get_first_date() );
231	$new_action = new ActionScheduler_Action( $action->get_hook(), $action->get_args(), $new_schedule, $action->get_group() );
232	return $this->store( $new_action );
233	}
234
235	/**
236	* Save action to database.
237	*
238	* @param ActionScheduler_Action $action Action object to save.
239	*
240	* @return int The ID of the stored action
241	*/
242	protected function store( ActionScheduler_Action $action ) {
243	$store = ActionScheduler_Store::instance();
244	return $store->save_action( $action );
245	}
246
247	/**
248	* Store action if it's unique.
249	*
250	* @param ActionScheduler_Action $action Action object to store.
251	*
252	* @return int ID of the created action. Will be 0 if action was not created.
253	*/
254	protected function store_unique_action( ActionScheduler_Action $action ) {
255	$store = ActionScheduler_Store::instance();
256	return method_exists( $store, 'save_unique_action' ) ?
257	$store->save_unique_action( $action ) : $store->save_action( $action );
258	}
259	}
260