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