| [ Index ] |
PHP Cross Reference of WordPress |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * WordPress Cron API 4 * 5 * @package WordPress 6 */ 7 8 /** 9 * Schedules an event to run only once. 10 * 11 * Schedules a hook which will be triggered by WordPress at the specified time. 12 * The action will trigger when someone visits your WordPress site if the scheduled 13 * time has passed. 14 * 15 * Note that scheduling an event to occur within 10 minutes of an existing event 16 * with the same action hook will be ignored unless you pass unique `$args` values 17 * for each scheduled event. 18 * 19 * Use wp_next_scheduled() to prevent duplicate events. 20 * 21 * Use wp_schedule_event() to schedule a recurring event. 22 * 23 * @since 2.1.0 24 * @since 5.1.0 Return value modified to boolean indicating success or failure, 25 * {@see 'pre_schedule_event'} filter added to short-circuit the function. 26 * @since 5.7.0 The `$wp_error` parameter was added. 27 * 28 * @link https://developer.wordpress.org/reference/functions/wp_schedule_single_event/ 29 * 30 * @param int $timestamp Unix timestamp (UTC) for when to next run the event. 31 * @param string $hook Action hook to execute when the event is run. 32 * @param array $args Optional. Array containing arguments to pass to the 33 * hook's callback function. Each value in the array 34 * is passed to the callback as an individual parameter. 35 * The array keys are ignored. Default empty array. 36 * @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false. 37 * @return bool|WP_Error True if event successfully scheduled. False or WP_Error on failure. 38 */ 39 function wp_schedule_single_event( $timestamp, $hook, $args = array(), $wp_error = false ) { 40 // Make sure timestamp is a positive integer. 41 if ( ! is_numeric( $timestamp ) || $timestamp <= 0 ) { 42 if ( $wp_error ) { 43 return new WP_Error( 44 'invalid_timestamp', 45 __( 'Event timestamp must be a valid Unix timestamp.' ) 46 ); 47 } 48 49 return false; 50 } 51 52 $event = (object) array( 53 'hook' => $hook, 54 'timestamp' => $timestamp, 55 'schedule' => false, 56 'args' => $args, 57 ); 58 59 /** 60 * Filter to preflight or hijack scheduling an event. 61 * 62 * Returning a non-null value will short-circuit adding the event to the 63 * cron array, causing the function to return the filtered value instead. 64 * 65 * Both single events and recurring events are passed through this filter; 66 * single events have `$event->schedule` as false, whereas recurring events 67 * have this set to a recurrence from wp_get_schedules(). Recurring 68 * events also have the integer recurrence interval set as `$event->interval`. 69 * 70 * For plugins replacing wp-cron, it is recommended you check for an 71 * identical event within ten minutes and apply the {@see 'schedule_event'} 72 * filter to check if another plugin has disallowed the event before scheduling. 73 * 74 * Return true if the event was scheduled, false or a WP_Error if not. 75 * 76 * @since 5.1.0 77 * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned. 78 * 79 * @param null|bool|WP_Error $pre Value to return instead. Default null to continue adding the event. 80 * @param stdClass $event { 81 * An object containing an event's data. 82 * 83 * @type string $hook Action hook to execute when the event is run. 84 * @type int $timestamp Unix timestamp (UTC) for when to next run the event. 85 * @type string|false $schedule How often the event should subsequently recur. 86 * @type array $args Array containing each separate argument to pass to the hook's callback function. 87 * @type int $interval The interval time in seconds for the schedule. Only present for recurring events. 88 * } 89 * @param bool $wp_error Whether to return a WP_Error on failure. 90 */ 91 $pre = apply_filters( 'pre_schedule_event', null, $event, $wp_error ); 92 93 if ( null !== $pre ) { 94 if ( $wp_error && false === $pre ) { 95 return new WP_Error( 96 'pre_schedule_event_false', 97 __( 'A plugin prevented the event from being scheduled.' ) 98 ); 99 } 100 101 if ( ! $wp_error && is_wp_error( $pre ) ) { 102 return false; 103 } 104 105 return $pre; 106 } 107 108 /* 109 * Check for a duplicated event. 110 * 111 * Don't schedule an event if there's already an identical event 112 * within 10 minutes. 113 * 114 * When scheduling events within ten minutes of the current time, 115 * all past identical events are considered duplicates. 116 * 117 * When scheduling an event with a past timestamp (ie, before the 118 * current time) all events scheduled within the next ten minutes 119 * are considered duplicates. 120 */ 121 $crons = _get_cron_array(); 122 if ( ! is_array( $crons ) ) { 123 $crons = array(); 124 } 125 126 $key = md5( serialize( $event->args ) ); 127 $duplicate = false; 128 129 if ( $event->timestamp < time() + 10 * MINUTE_IN_SECONDS ) { 130 $min_timestamp = 0; 131 } else { 132 $min_timestamp = $event->timestamp - 10 * MINUTE_IN_SECONDS; 133 } 134 135 if ( $event->timestamp < time() ) { 136 $max_timestamp = time() + 10 * MINUTE_IN_SECONDS; 137 } else { 138 $max_timestamp = $event->timestamp + 10 * MINUTE_IN_SECONDS; 139 } 140 141 foreach ( $crons as $event_timestamp => $cron ) { 142 if ( $event_timestamp < $min_timestamp ) { 143 continue; 144 } 145 if ( $event_timestamp > $max_timestamp ) { 146 break; 147 } 148 if ( isset( $cron[ $event->hook ][ $key ] ) ) { 149 $duplicate = true; 150 break; 151 } 152 } 153 154 if ( $duplicate ) { 155 if ( $wp_error ) { 156 return new WP_Error( 157 'duplicate_event', 158 __( 'A duplicate event already exists.' ) 159 ); 160 } 161 162 return false; 163 } 164 165 /** 166 * Modify an event before it is scheduled. 167 * 168 * @since 3.1.0 169 * 170 * @param stdClass|false $event { 171 * An object containing an event's data, or boolean false to prevent the event from being scheduled. 172 * 173 * @type string $hook Action hook to execute when the event is run. 174 * @type int $timestamp Unix timestamp (UTC) for when to next run the event. 175 * @type string|false $schedule How often the event should subsequently recur. 176 * @type array $args Array containing each separate argument to pass to the hook's callback function. 177 * @type int $interval The interval time in seconds for the schedule. Only present for recurring events. 178 * } 179 */ 180 $event = apply_filters( 'schedule_event', $event ); 181 182 // A plugin disallowed this event. 183 if ( ! $event ) { 184 if ( $wp_error ) { 185 return new WP_Error( 186 'schedule_event_false', 187 __( 'A plugin disallowed this event.' ) 188 ); 189 } 190 191 return false; 192 } 193 194 $crons[ $event->timestamp ][ $event->hook ][ $key ] = array( 195 'schedule' => $event->schedule, 196 'args' => $event->args, 197 ); 198 uksort( $crons, 'strnatcasecmp' ); 199 200 return _set_cron_array( $crons, $wp_error ); 201 } 202 203 /** 204 * Schedules a recurring event. 205 * 206 * Schedules a hook which will be triggered by WordPress at the specified interval. 207 * The action will trigger when someone visits your WordPress site if the scheduled 208 * time has passed. 209 * 210 * Valid values for the recurrence are 'hourly', 'daily', and 'twicedaily'. These can 211 * be extended using the {@see 'cron_schedules'} filter in wp_get_schedules(). 212 * 213 * Note that scheduling an event to occur within 10 minutes of an existing event 214 * with the same action hook will be ignored unless you pass unique `$args` values 215 * for each scheduled event. 216 * 217 * Use wp_next_scheduled() to prevent duplicate events. 218 * 219 * Use wp_schedule_single_event() to schedule a non-recurring event. 220 * 221 * @since 2.1.0 222 * @since 5.1.0 Return value modified to boolean indicating success or failure, 223 * {@see 'pre_schedule_event'} filter added to short-circuit the function. 224 * @since 5.7.0 The `$wp_error` parameter was added. 225 * 226 * @link https://developer.wordpress.org/reference/functions/wp_schedule_event/ 227 * 228 * @param int $timestamp Unix timestamp (UTC) for when to next run the event. 229 * @param string $recurrence How often the event should subsequently recur. 230 * See wp_get_schedules() for accepted values. 231 * @param string $hook Action hook to execute when the event is run. 232 * @param array $args Optional. Array containing arguments to pass to the 233 * hook's callback function. Each value in the array 234 * is passed to the callback as an individual parameter. 235 * The array keys are ignored. Default empty array. 236 * @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false. 237 * @return bool|WP_Error True if event successfully scheduled. False or WP_Error on failure. 238 */ 239 function wp_schedule_event( $timestamp, $recurrence, $hook, $args = array(), $wp_error = false ) { 240 // Make sure timestamp is a positive integer. 241 if ( ! is_numeric( $timestamp ) || $timestamp <= 0 ) { 242 if ( $wp_error ) { 243 return new WP_Error( 244 'invalid_timestamp', 245 __( 'Event timestamp must be a valid Unix timestamp.' ) 246 ); 247 } 248 249 return false; 250 } 251 252 $schedules = wp_get_schedules(); 253 254 if ( ! isset( $schedules[ $recurrence ] ) ) { 255 if ( $wp_error ) { 256 return new WP_Error( 257 'invalid_schedule', 258 __( 'Event schedule does not exist.' ) 259 ); 260 } 261 262 return false; 263 } 264 265 $event = (object) array( 266 'hook' => $hook, 267 'timestamp' => $timestamp, 268 'schedule' => $recurrence, 269 'args' => $args, 270 'interval' => $schedules[ $recurrence ]['interval'], 271 ); 272 273 /** This filter is documented in wp-includes/cron.php */ 274 $pre = apply_filters( 'pre_schedule_event', null, $event, $wp_error ); 275 276 if ( null !== $pre ) { 277 if ( $wp_error && false === $pre ) { 278 return new WP_Error( 279 'pre_schedule_event_false', 280 __( 'A plugin prevented the event from being scheduled.' ) 281 ); 282 } 283 284 if ( ! $wp_error && is_wp_error( $pre ) ) { 285 return false; 286 } 287 288 return $pre; 289 } 290 291 /** This filter is documented in wp-includes/cron.php */ 292 $event = apply_filters( 'schedule_event', $event ); 293 294 // A plugin disallowed this event. 295 if ( ! $event ) { 296 if ( $wp_error ) { 297 return new WP_Error( 298 'schedule_event_false', 299 __( 'A plugin disallowed this event.' ) 300 ); 301 } 302 303 return false; 304 } 305 306 $key = md5( serialize( $event->args ) ); 307 308 $crons = _get_cron_array(); 309 if ( ! is_array( $crons ) ) { 310 $crons = array(); 311 } 312 313 $crons[ $event->timestamp ][ $event->hook ][ $key ] = array( 314 'schedule' => $event->schedule, 315 'args' => $event->args, 316 'interval' => $event->interval, 317 ); 318 uksort( $crons, 'strnatcasecmp' ); 319 320 return _set_cron_array( $crons, $wp_error ); 321 } 322 323 /** 324 * Reschedules a recurring event. 325 * 326 * Mainly for internal use, this takes the time stamp of a previously run 327 * recurring event and reschedules it for its next run. 328 * 329 * To change upcoming scheduled events, use wp_schedule_event() to 330 * change the recurrence frequency. 331 * 332 * @since 2.1.0 333 * @since 5.1.0 Return value modified to boolean indicating success or failure, 334 * {@see 'pre_reschedule_event'} filter added to short-circuit the function. 335 * @since 5.7.0 The `$wp_error` parameter was added. 336 * 337 * @param int $timestamp Unix timestamp (UTC) for when the event was scheduled. 338 * @param string $recurrence How often the event should subsequently recur. 339 * See wp_get_schedules() for accepted values. 340 * @param string $hook Action hook to execute when the event is run. 341 * @param array $args Optional. Array containing arguments to pass to the 342 * hook's callback function. Each value in the array 343 * is passed to the callback as an individual parameter. 344 * The array keys are ignored. Default empty array. 345 * @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false. 346 * @return bool|WP_Error True if event successfully rescheduled. False or WP_Error on failure. 347 */ 348 function wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array(), $wp_error = false ) { 349 // Make sure timestamp is a positive integer. 350 if ( ! is_numeric( $timestamp ) || $timestamp <= 0 ) { 351 if ( $wp_error ) { 352 return new WP_Error( 353 'invalid_timestamp', 354 __( 'Event timestamp must be a valid Unix timestamp.' ) 355 ); 356 } 357 358 return false; 359 } 360 361 $schedules = wp_get_schedules(); 362 $interval = 0; 363 364 // First we try to get the interval from the schedule. 365 if ( isset( $schedules[ $recurrence ] ) ) { 366 $interval = $schedules[ $recurrence ]['interval']; 367 } 368 369 // Now we try to get it from the saved interval in case the schedule disappears. 370 if ( 0 === $interval ) { 371 $scheduled_event = wp_get_scheduled_event( $hook, $args, $timestamp ); 372 if ( $scheduled_event && isset( $scheduled_event->interval ) ) { 373 $interval = $scheduled_event->interval; 374 } 375 } 376 377 $event = (object) array( 378 'hook' => $hook, 379 'timestamp' => $timestamp, 380 'schedule' => $recurrence, 381 'args' => $args, 382 'interval' => $interval, 383 ); 384 385 /** 386 * Filter to preflight or hijack rescheduling of events. 387 * 388 * Returning a non-null value will short-circuit the normal rescheduling 389 * process, causing the function to return the filtered value instead. 390 * 391 * For plugins replacing wp-cron, return true if the event was successfully 392 * rescheduled, false if not. 393 * 394 * @since 5.1.0 395 * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned. 396 * 397 * @param null|bool|WP_Error $pre Value to return instead. Default null to continue adding the event. 398 * @param stdClass $event { 399 * An object containing an event's data. 400 * 401 * @type string $hook Action hook to execute when the event is run. 402 * @type int $timestamp Unix timestamp (UTC) for when to next run the event. 403 * @type string|false $schedule How often the event should subsequently recur. 404 * @type array $args Array containing each separate argument to pass to the hook's callback function. 405 * @type int $interval The interval time in seconds for the schedule. Only present for recurring events. 406 * } 407 * @param bool $wp_error Whether to return a WP_Error on failure. 408 */ 409 $pre = apply_filters( 'pre_reschedule_event', null, $event, $wp_error ); 410 411 if ( null !== $pre ) { 412 if ( $wp_error && false === $pre ) { 413 return new WP_Error( 414 'pre_reschedule_event_false', 415 __( 'A plugin prevented the event from being rescheduled.' ) 416 ); 417 } 418 419 if ( ! $wp_error && is_wp_error( $pre ) ) { 420 return false; 421 } 422 423 return $pre; 424 } 425 426 // Now we assume something is wrong and fail to schedule. 427 if ( 0 == $interval ) { 428 if ( $wp_error ) { 429 return new WP_Error( 430 'invalid_schedule', 431 __( 'Event schedule does not exist.' ) 432 ); 433 } 434 435 return false; 436 } 437 438 $now = time(); 439 440 if ( $timestamp >= $now ) { 441 $timestamp = $now + $interval; 442 } else { 443 $timestamp = $now + ( $interval - ( ( $now - $timestamp ) % $interval ) ); 444 } 445 446 return wp_schedule_event( $timestamp, $recurrence, $hook, $args, $wp_error ); 447 } 448 449 /** 450 * Unschedule a previously scheduled event. 451 * 452 * The $timestamp and $hook parameters are required so that the event can be 453 * identified. 454 * 455 * @since 2.1.0 456 * @since 5.1.0 Return value modified to boolean indicating success or failure, 457 * {@see 'pre_unschedule_event'} filter added to short-circuit the function. 458 * @since 5.7.0 The `$wp_error` parameter was added. 459 * 460 * @param int $timestamp Unix timestamp (UTC) of the event. 461 * @param string $hook Action hook of the event. 462 * @param array $args Optional. Array containing each separate argument to pass to the hook's callback function. 463 * Although not passed to a callback, these arguments are used to uniquely identify the 464 * event, so they should be the same as those used when originally scheduling the event. 465 * Default empty array. 466 * @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false. 467 * @return bool|WP_Error True if event successfully unscheduled. False or WP_Error on failure. 468 */ 469 function wp_unschedule_event( $timestamp, $hook, $args = array(), $wp_error = false ) { 470 // Make sure timestamp is a positive integer. 471 if ( ! is_numeric( $timestamp ) || $timestamp <= 0 ) { 472 if ( $wp_error ) { 473 return new WP_Error( 474 'invalid_timestamp', 475 __( 'Event timestamp must be a valid Unix timestamp.' ) 476 ); 477 } 478 479 return false; 480 } 481 482 /** 483 * Filter to preflight or hijack unscheduling of events. 484 * 485 * Returning a non-null value will short-circuit the normal unscheduling 486 * process, causing the function to return the filtered value instead. 487 * 488 * For plugins replacing wp-cron, return true if the event was successfully 489 * unscheduled, false if not. 490 * 491 * @since 5.1.0 492 * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned. 493 * 494 * @param null|bool|WP_Error $pre Value to return instead. Default null to continue unscheduling the event. 495 * @param int $timestamp Timestamp for when to run the event. 496 * @param string $hook Action hook, the execution of which will be unscheduled. 497 * @param array $args Arguments to pass to the hook's callback function. 498 * @param bool $wp_error Whether to return a WP_Error on failure. 499 */ 500 $pre = apply_filters( 'pre_unschedule_event', null, $timestamp, $hook, $args, $wp_error ); 501 502 if ( null !== $pre ) { 503 if ( $wp_error && false === $pre ) { 504 return new WP_Error( 505 'pre_unschedule_event_false', 506 __( 'A plugin prevented the event from being unscheduled.' ) 507 ); 508 } 509 510 if ( ! $wp_error && is_wp_error( $pre ) ) { 511 return false; 512 } 513 514 return $pre; 515 } 516 517 $crons = _get_cron_array(); 518 $key = md5( serialize( $args ) ); 519 unset( $crons[ $timestamp ][ $hook ][ $key ] ); 520 if ( empty( $crons[ $timestamp ][ $hook ] ) ) { 521 unset( $crons[ $timestamp ][ $hook ] ); 522 } 523 if ( empty( $crons[ $timestamp ] ) ) { 524 unset( $crons[ $timestamp ] ); 525 } 526 527 return _set_cron_array( $crons, $wp_error ); 528 } 529 530 /** 531 * Unschedules all events attached to the hook with the specified arguments. 532 * 533 * Warning: This function may return Boolean FALSE, but may also return a non-Boolean 534 * value which evaluates to FALSE. For information about casting to booleans see the 535 * {@link https://www.php.net/manual/en/language.types.boolean.php PHP documentation}. Use 536 * the `===` operator for testing the return value of this function. 537 * 538 * @since 2.1.0 539 * @since 5.1.0 Return value modified to indicate success or failure, 540 * {@see 'pre_clear_scheduled_hook'} filter added to short-circuit the function. 541 * @since 5.7.0 The `$wp_error` parameter was added. 542 * 543 * @param string $hook Action hook, the execution of which will be unscheduled. 544 * @param array $args Optional. Array containing each separate argument to pass to the hook's callback function. 545 * Although not passed to a callback, these arguments are used to uniquely identify the 546 * event, so they should be the same as those used when originally scheduling the event. 547 * Default empty array. 548 * @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false. 549 * @return int|false|WP_Error On success an integer indicating number of events unscheduled (0 indicates no 550 * events were registered with the hook and arguments combination), false or WP_Error 551 * if unscheduling one or more events fail. 552 */ 553 function wp_clear_scheduled_hook( $hook, $args = array(), $wp_error = false ) { 554 // Backward compatibility. 555 // Previously, this function took the arguments as discrete vars rather than an array like the rest of the API. 556 if ( ! is_array( $args ) ) { 557 _deprecated_argument( __FUNCTION__, '3.0.0', __( 'This argument has changed to an array to match the behavior of the other cron functions.' ) ); 558 $args = array_slice( func_get_args(), 1 ); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection 559 $wp_error = false; 560 } 561 562 /** 563 * Filter to preflight or hijack clearing a scheduled hook. 564 * 565 * Returning a non-null value will short-circuit the normal unscheduling 566 * process, causing the function to return the filtered value instead. 567 * 568 * For plugins replacing wp-cron, return the number of events successfully 569 * unscheduled (zero if no events were registered with the hook) or false 570 * if unscheduling one or more events fails. 571 * 572 * @since 5.1.0 573 * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned. 574 * 575 * @param null|int|false|WP_Error $pre Value to return instead. Default null to continue unscheduling the event. 576 * @param string $hook Action hook, the execution of which will be unscheduled. 577 * @param array $args Arguments to pass to the hook's callback function. 578 * @param bool $wp_error Whether to return a WP_Error on failure. 579 */ 580 $pre = apply_filters( 'pre_clear_scheduled_hook', null, $hook, $args, $wp_error ); 581 582 if ( null !== $pre ) { 583 if ( $wp_error && false === $pre ) { 584 return new WP_Error( 585 'pre_clear_scheduled_hook_false', 586 __( 'A plugin prevented the hook from being cleared.' ) 587 ); 588 } 589 590 if ( ! $wp_error && is_wp_error( $pre ) ) { 591 return false; 592 } 593 594 return $pre; 595 } 596 597 /* 598 * This logic duplicates wp_next_scheduled(). 599 * It's required due to a scenario where wp_unschedule_event() fails due to update_option() failing, 600 * and, wp_next_scheduled() returns the same schedule in an infinite loop. 601 */ 602 $crons = _get_cron_array(); 603 if ( empty( $crons ) ) { 604 return 0; 605 } 606 607 $results = array(); 608 $key = md5( serialize( $args ) ); 609 610 foreach ( $crons as $timestamp => $cron ) { 611 if ( isset( $cron[ $hook ][ $key ] ) ) { 612 $results[] = wp_unschedule_event( $timestamp, $hook, $args, true ); 613 } 614 } 615 616 $errors = array_filter( $results, 'is_wp_error' ); 617 $error = new WP_Error(); 618 619 if ( $errors ) { 620 if ( $wp_error ) { 621 array_walk( $errors, array( $error, 'merge_from' ) ); 622 623 return $error; 624 } 625 626 return false; 627 } 628 629 return count( $results ); 630 } 631 632 /** 633 * Unschedules all events attached to the hook. 634 * 635 * Can be useful for plugins when deactivating to clean up the cron queue. 636 * 637 * Warning: This function may return Boolean FALSE, but may also return a non-Boolean 638 * value which evaluates to FALSE. For information about casting to booleans see the 639 * {@link https://www.php.net/manual/en/language.types.boolean.php PHP documentation}. Use 640 * the `===` operator for testing the return value of this function. 641 * 642 * @since 4.9.0 643 * @since 5.1.0 Return value added to indicate success or failure. 644 * @since 5.7.0 The `$wp_error` parameter was added. 645 * 646 * @param string $hook Action hook, the execution of which will be unscheduled. 647 * @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false. 648 * @return int|false|WP_Error On success an integer indicating number of events unscheduled (0 indicates no 649 * events were registered on the hook), false or WP_Error if unscheduling fails. 650 */ 651 function wp_unschedule_hook( $hook, $wp_error = false ) { 652 /** 653 * Filter to preflight or hijack clearing all events attached to the hook. 654 * 655 * Returning a non-null value will short-circuit the normal unscheduling 656 * process, causing the function to return the filtered value instead. 657 * 658 * For plugins replacing wp-cron, return the number of events successfully 659 * unscheduled (zero if no events were registered with the hook) or false 660 * if unscheduling one or more events fails. 661 * 662 * @since 5.1.0 663 * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned. 664 * 665 * @param null|int|false|WP_Error $pre Value to return instead. Default null to continue unscheduling the hook. 666 * @param string $hook Action hook, the execution of which will be unscheduled. 667 * @param bool $wp_error Whether to return a WP_Error on failure. 668 */ 669 $pre = apply_filters( 'pre_unschedule_hook', null, $hook, $wp_error ); 670 671 if ( null !== $pre ) { 672 if ( $wp_error && false === $pre ) { 673 return new WP_Error( 674 'pre_unschedule_hook_false', 675 __( 'A plugin prevented the hook from being cleared.' ) 676 ); 677 } 678 679 if ( ! $wp_error && is_wp_error( $pre ) ) { 680 return false; 681 } 682 683 return $pre; 684 } 685 686 $crons = _get_cron_array(); 687 if ( empty( $crons ) ) { 688 return 0; 689 } 690 691 $results = array(); 692 foreach ( $crons as $timestamp => $args ) { 693 if ( ! empty( $crons[ $timestamp ][ $hook ] ) ) { 694 $results[] = count( $crons[ $timestamp ][ $hook ] ); 695 } 696 unset( $crons[ $timestamp ][ $hook ] ); 697 698 if ( empty( $crons[ $timestamp ] ) ) { 699 unset( $crons[ $timestamp ] ); 700 } 701 } 702 703 /* 704 * If the results are empty (zero events to unschedule), no attempt 705 * to update the cron array is required. 706 */ 707 if ( empty( $results ) ) { 708 return 0; 709 } 710 711 $set = _set_cron_array( $crons, $wp_error ); 712 713 if ( true === $set ) { 714 return array_sum( $results ); 715 } 716 717 return $set; 718 } 719 720 /** 721 * Retrieve a scheduled event. 722 * 723 * Retrieve the full event object for a given event, if no timestamp is specified the next 724 * scheduled event is returned. 725 * 726 * @since 5.1.0 727 * 728 * @param string $hook Action hook of the event. 729 * @param array $args Optional. Array containing each separate argument to pass to the hook's callback function. 730 * Although not passed to a callback, these arguments are used to uniquely identify the 731 * event, so they should be the same as those used when originally scheduling the event. 732 * Default empty array. 733 * @param int|null $timestamp Optional. Unix timestamp (UTC) of the event. If not specified, the next scheduled event 734 * is returned. Default null. 735 * @return object|false The event object. False if the event does not exist. 736 */ 737 function wp_get_scheduled_event( $hook, $args = array(), $timestamp = null ) { 738 /** 739 * Filter to preflight or hijack retrieving a scheduled event. 740 * 741 * Returning a non-null value will short-circuit the normal process, 742 * returning the filtered value instead. 743 * 744 * Return false if the event does not exist, otherwise an event object 745 * should be returned. 746 * 747 * @since 5.1.0 748 * 749 * @param null|false|object $pre Value to return instead. Default null to continue retrieving the event. 750 * @param string $hook Action hook of the event. 751 * @param array $args Array containing each separate argument to pass to the hook's callback function. 752 * Although not passed to a callback, these arguments are used to uniquely identify 753 * the event. 754 * @param int|null $timestamp Unix timestamp (UTC) of the event. Null to retrieve next scheduled event. 755 */ 756 $pre = apply_filters( 'pre_get_scheduled_event', null, $hook, $args, $timestamp ); 757 if ( null !== $pre ) { 758 return $pre; 759 } 760 761 if ( null !== $timestamp && ! is_numeric( $timestamp ) ) { 762 return false; 763 } 764 765 $crons = _get_cron_array(); 766 if ( empty( $crons ) ) { 767 return false; 768 } 769 770 $key = md5( serialize( $args ) ); 771 772 if ( ! $timestamp ) { 773 // Get next event. 774 $next = false; 775 foreach ( $crons as $timestamp => $cron ) { 776 if ( isset( $cron[ $hook ][ $key ] ) ) { 777 $next = $timestamp; 778 break; 779 } 780 } 781 if ( ! $next ) { 782 return false; 783 } 784 785 $timestamp = $next; 786 } elseif ( ! isset( $crons[ $timestamp ][ $hook ][ $key ] ) ) { 787 return false; 788 } 789 790 $event = (object) array( 791 'hook' => $hook, 792 'timestamp' => $timestamp, 793 'schedule' => $crons[ $timestamp ][ $hook ][ $key ]['schedule'], 794 'args' => $args, 795 ); 796 797 if ( isset( $crons[ $timestamp ][ $hook ][ $key ]['interval'] ) ) { 798 $event->interval = $crons[ $timestamp ][ $hook ][ $key ]['interval']; 799 } 800 801 return $event; 802 } 803 804 /** 805 * Retrieve the next timestamp for an event. 806 * 807 * @since 2.1.0 808 * 809 * @param string $hook Action hook of the event. 810 * @param array $args Optional. Array containing each separate argument to pass to the hook's callback function. 811 * Although not passed to a callback, these arguments are used to uniquely identify the 812 * event, so they should be the same as those used when originally scheduling the event. 813 * Default empty array. 814 * @return int|false The Unix timestamp of the next time the event will occur. False if the event doesn't exist. 815 */ 816 function wp_next_scheduled( $hook, $args = array() ) { 817 $next_event = wp_get_scheduled_event( $hook, $args ); 818 if ( ! $next_event ) { 819 return false; 820 } 821 822 return $next_event->timestamp; 823 } 824 825 /** 826 * Sends a request to run cron through HTTP request that doesn't halt page loading. 827 * 828 * @since 2.1.0 829 * @since 5.1.0 Return values added. 830 * 831 * @param int $gmt_time Optional. Unix timestamp (UTC). Default 0 (current time is used). 832 * @return bool True if spawned, false if no events spawned. 833 */ 834 function spawn_cron( $gmt_time = 0 ) { 835 if ( ! $gmt_time ) { 836 $gmt_time = microtime( true ); 837 } 838 839 if ( defined( 'DOING_CRON' ) || isset( $_GET['doing_wp_cron'] ) ) { 840 return false; 841 } 842 843 /* 844 * Get the cron lock, which is a Unix timestamp of when the last cron was spawned 845 * and has not finished running. 846 * 847 * Multiple processes on multiple web servers can run this code concurrently, 848 * this lock attempts to make spawning as atomic as possible. 849 */ 850 $lock = get_transient( 'doing_cron' ); 851 852 if ( $lock > $gmt_time + 10 * MINUTE_IN_SECONDS ) { 853 $lock = 0; 854 } 855 856 // Don't run if another process is currently running it or more than once every 60 sec. 857 if ( $lock + WP_CRON_LOCK_TIMEOUT > $gmt_time ) { 858 return false; 859 } 860 861 // Sanity check. 862 $crons = wp_get_ready_cron_jobs(); 863 if ( empty( $crons ) ) { 864 return false; 865 } 866 867 $keys = array_keys( $crons ); 868 if ( isset( $keys[0] ) && $keys[0] > $gmt_time ) { 869 return false; 870 } 871 872 if ( defined( 'ALTERNATE_WP_CRON' ) && ALTERNATE_WP_CRON ) { 873 if ( 'GET' !== $_SERVER['REQUEST_METHOD'] || defined( 'DOING_AJAX' ) || defined( 'XMLRPC_REQUEST' ) ) { 874 return false; 875 } 876 877 $doing_wp_cron = sprintf( '%.22F', $gmt_time ); 878 set_transient( 'doing_cron', $doing_wp_cron ); 879 880 ob_start(); 881 wp_redirect( add_query_arg( 'doing_wp_cron', $doing_wp_cron, wp_unslash( $_SERVER['REQUEST_URI'] ) ) ); 882 echo ' '; 883 884 // Flush any buffers and send the headers. 885 wp_ob_end_flush_all(); 886 flush(); 887 888 include_once ABSPATH . 'wp-cron.php'; 889 return true; 890 } 891 892 // Set the cron lock with the current unix timestamp, when the cron is being spawned. 893 $doing_wp_cron = sprintf( '%.22F', $gmt_time ); 894 set_transient( 'doing_cron', $doing_wp_cron ); 895 896 /** 897 * Filters the cron request arguments. 898 * 899 * @since 3.5.0 900 * @since 4.5.0 The `$doing_wp_cron` parameter was added. 901 * 902 * @param array $cron_request_array { 903 * An array of cron request URL arguments. 904 * 905 * @type string $url The cron request URL. 906 * @type int $key The 22 digit GMT microtime. 907 * @type array $args { 908 * An array of cron request arguments. 909 * 910 * @type int $timeout The request timeout in seconds. Default .01 seconds. 911 * @type bool $blocking Whether to set blocking for the request. Default false. 912 * @type bool $sslverify Whether SSL should be verified for the request. Default false. 913 * } 914 * } 915 * @param string $doing_wp_cron The unix timestamp of the cron lock. 916 */ 917 $cron_request = apply_filters( 918 'cron_request', 919 array( 920 'url' => add_query_arg( 'doing_wp_cron', $doing_wp_cron, site_url( 'wp-cron.php' ) ), 921 'key' => $doing_wp_cron, 922 'args' => array( 923 'timeout' => 0.01, 924 'blocking' => false, 925 /** This filter is documented in wp-includes/class-wp-http-streams.php */ 926 'sslverify' => apply_filters( 'https_local_ssl_verify', false ), 927 ), 928 ), 929 $doing_wp_cron 930 ); 931 932 $result = wp_remote_post( $cron_request['url'], $cron_request['args'] ); 933 return ! is_wp_error( $result ); 934 } 935 936 /** 937 * Register _wp_cron() to run on the {@see 'wp_loaded'} action. 938 * 939 * If the {@see 'wp_loaded'} action has already fired, this function calls 940 * _wp_cron() directly. 941 * 942 * Warning: This function may return Boolean FALSE, but may also return a non-Boolean 943 * value which evaluates to FALSE. For information about casting to booleans see the 944 * {@link https://www.php.net/manual/en/language.types.boolean.php PHP documentation}. Use 945 * the `===` operator for testing the return value of this function. 946 * 947 * @since 2.1.0 948 * @since 5.1.0 Return value added to indicate success or failure. 949 * @since 5.7.0 Functionality moved to _wp_cron() to which this becomes a wrapper. 950 * 951 * @return bool|int|void On success an integer indicating number of events spawned (0 indicates no 952 * events needed to be spawned), false if spawning fails for one or more events or 953 * void if the function registered _wp_cron() to run on the action. 954 */ 955 function wp_cron() { 956 if ( did_action( 'wp_loaded' ) ) { 957 return _wp_cron(); 958 } 959 960 add_action( 'wp_loaded', '_wp_cron', 20 ); 961 } 962 963 /** 964 * Run scheduled callbacks or spawn cron for all scheduled events. 965 * 966 * Warning: This function may return Boolean FALSE, but may also return a non-Boolean 967 * value which evaluates to FALSE. For information about casting to booleans see the 968 * {@link https://www.php.net/manual/en/language.types.boolean.php PHP documentation}. Use 969 * the `===` operator for testing the return value of this function. 970 * 971 * @since 5.7.0 972 * @access private 973 * 974 * @return int|false On success an integer indicating number of events spawned (0 indicates no 975 * events needed to be spawned), false if spawning fails for one or more events. 976 */ 977 function _wp_cron() { 978 // Prevent infinite loops caused by lack of wp-cron.php. 979 if ( strpos( $_SERVER['REQUEST_URI'], '/wp-cron.php' ) !== false || ( defined( 'DISABLE_WP_CRON' ) && DISABLE_WP_CRON ) ) { 980 return 0; 981 } 982 983 $crons = wp_get_ready_cron_jobs(); 984 if ( empty( $crons ) ) { 985 return 0; 986 } 987 988 $gmt_time = microtime( true ); 989 $keys = array_keys( $crons ); 990 if ( isset( $keys[0] ) && $keys[0] > $gmt_time ) { 991 return 0; 992 } 993 994 $schedules = wp_get_schedules(); 995 $results = array(); 996 foreach ( $crons as $timestamp => $cronhooks ) { 997 if ( $timestamp > $gmt_time ) { 998 break; 999 } 1000 foreach ( (array) $cronhooks as $hook => $args ) { 1001 if ( isset( $schedules[ $hook ]['callback'] ) && ! call_user_func( $schedules[ $hook ]['callback'] ) ) { 1002 continue; 1003 } 1004 $results[] = spawn_cron( $gmt_time ); 1005 break 2; 1006 } 1007 } 1008 1009 if ( in_array( false, $results, true ) ) { 1010 return false; 1011 } 1012 return count( $results ); 1013 } 1014 1015 /** 1016 * Retrieve supported event recurrence schedules. 1017 * 1018 * The default supported recurrences are 'hourly', 'twicedaily', 'daily', and 'weekly'. 1019 * A plugin may add more by hooking into the {@see 'cron_schedules'} filter. 1020 * The filter accepts an array of arrays. The outer array has a key that is the name 1021 * of the schedule, for example 'monthly'. The value is an array with two keys, 1022 * one is 'interval' and the other is 'display'. 1023 * 1024 * The 'interval' is a number in seconds of when the cron job should run. 1025 * So for 'hourly' the time is `HOUR_IN_SECONDS` (60 * 60 or 3600). For 'monthly', 1026 * the value would be `MONTH_IN_SECONDS` (30 * 24 * 60 * 60 or 2592000). 1027 * 1028 * The 'display' is the description. For the 'monthly' key, the 'display' 1029 * would be `__( 'Once Monthly' )`. 1030 * 1031 * For your plugin, you will be passed an array. You can easily add your 1032 * schedule by doing the following. 1033 * 1034 * // Filter parameter variable name is 'array'. 1035 * $array['monthly'] = array( 1036 * 'interval' => MONTH_IN_SECONDS, 1037 * 'display' => __( 'Once Monthly' ) 1038 * ); 1039 * 1040 * @since 2.1.0 1041 * @since 5.4.0 The 'weekly' schedule was added. 1042 * 1043 * @return array[] 1044 */ 1045 function wp_get_schedules() { 1046 $schedules = array( 1047 'hourly' => array( 1048 'interval' => HOUR_IN_SECONDS, 1049 'display' => __( 'Once Hourly' ), 1050 ), 1051 'twicedaily' => array( 1052 'interval' => 12 * HOUR_IN_SECONDS, 1053 'display' => __( 'Twice Daily' ), 1054 ), 1055 'daily' => array( 1056 'interval' => DAY_IN_SECONDS, 1057 'display' => __( 'Once Daily' ), 1058 ), 1059 'weekly' => array( 1060 'interval' => WEEK_IN_SECONDS, 1061 'display' => __( 'Once Weekly' ), 1062 ), 1063 ); 1064 1065 /** 1066 * Filters the non-default cron schedules. 1067 * 1068 * @since 2.1.0 1069 * 1070 * @param array[] $new_schedules An array of non-default cron schedule arrays. Default empty. 1071 */ 1072 return array_merge( apply_filters( 'cron_schedules', array() ), $schedules ); 1073 } 1074 1075 /** 1076 * Retrieve the recurrence schedule for an event. 1077 * 1078 * @see wp_get_schedules() for available schedules. 1079 * 1080 * @since 2.1.0 1081 * @since 5.1.0 {@see 'get_schedule'} filter added. 1082 * 1083 * @param string $hook Action hook to identify the event. 1084 * @param array $args Optional. Arguments passed to the event's callback function. 1085 * Default empty array. 1086 * @return string|false Schedule name on success, false if no schedule. 1087 */ 1088 function wp_get_schedule( $hook, $args = array() ) { 1089 $schedule = false; 1090 $event = wp_get_scheduled_event( $hook, $args ); 1091 1092 if ( $event ) { 1093 $schedule = $event->schedule; 1094 } 1095 1096 /** 1097 * Filters the schedule for a hook. 1098 * 1099 * @since 5.1.0 1100 * 1101 * @param string|false $schedule Schedule for the hook. False if not found. 1102 * @param string $hook Action hook to execute when cron is run. 1103 * @param array $args Arguments to pass to the hook's callback function. 1104 */ 1105 return apply_filters( 'get_schedule', $schedule, $hook, $args ); 1106 } 1107 1108 /** 1109 * Retrieve cron jobs ready to be run. 1110 * 1111 * Returns the results of _get_cron_array() limited to events ready to be run, 1112 * ie, with a timestamp in the past. 1113 * 1114 * @since 5.1.0 1115 * 1116 * @return array[] Array of cron job arrays ready to be run. 1117 */ 1118 function wp_get_ready_cron_jobs() { 1119 /** 1120 * Filter to preflight or hijack retrieving ready cron jobs. 1121 * 1122 * Returning an array will short-circuit the normal retrieval of ready 1123 * cron jobs, causing the function to return the filtered value instead. 1124 * 1125 * @since 5.1.0 1126 * 1127 * @param null|array[] $pre Array of ready cron tasks to return instead. Default null 1128 * to continue using results from _get_cron_array(). 1129 */ 1130 $pre = apply_filters( 'pre_get_ready_cron_jobs', null ); 1131 if ( null !== $pre ) { 1132 return $pre; 1133 } 1134 1135 $crons = _get_cron_array(); 1136 if ( ! is_array( $crons ) ) { 1137 return array(); 1138 } 1139 1140 $gmt_time = microtime( true ); 1141 $keys = array_keys( $crons ); 1142 if ( isset( $keys[0] ) && $keys[0] > $gmt_time ) { 1143 return array(); 1144 } 1145 1146 $results = array(); 1147 foreach ( $crons as $timestamp => $cronhooks ) { 1148 if ( $timestamp > $gmt_time ) { 1149 break; 1150 } 1151 $results[ $timestamp ] = $cronhooks; 1152 } 1153 1154 return $results; 1155 } 1156 1157 // 1158 // Private functions. 1159 // 1160 1161 /** 1162 * Retrieve cron info array option. 1163 * 1164 * @since 2.1.0 1165 * @access private 1166 * 1167 * @return array[]|false Array of cron info arrays on success, false on failure. 1168 */ 1169 function _get_cron_array() { 1170 $cron = get_option( 'cron' ); 1171 if ( ! is_array( $cron ) ) { 1172 return false; 1173 } 1174 1175 if ( ! isset( $cron['version'] ) ) { 1176 $cron = _upgrade_cron_array( $cron ); 1177 } 1178 1179 unset( $cron['version'] ); 1180 1181 return $cron; 1182 } 1183 1184 /** 1185 * Updates the cron option with the new cron array. 1186 * 1187 * @since 2.1.0 1188 * @since 5.1.0 Return value modified to outcome of update_option(). 1189 * @since 5.7.0 The `$wp_error` parameter was added. 1190 * 1191 * @access private 1192 * 1193 * @param array[] $cron Array of cron info arrays from _get_cron_array(). 1194 * @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false. 1195 * @return bool|WP_Error True if cron array updated. False or WP_Error on failure. 1196 */ 1197 function _set_cron_array( $cron, $wp_error = false ) { 1198 if ( ! is_array( $cron ) ) { 1199 $cron = array(); 1200 } 1201 1202 $cron['version'] = 2; 1203 $result = update_option( 'cron', $cron ); 1204 1205 if ( $wp_error && ! $result ) { 1206 return new WP_Error( 1207 'could_not_set', 1208 __( 'The cron event list could not be saved.' ) 1209 ); 1210 } 1211 1212 return $result; 1213 } 1214 1215 /** 1216 * Upgrade a Cron info array. 1217 * 1218 * This function upgrades the Cron info array to version 2. 1219 * 1220 * @since 2.1.0 1221 * @access private 1222 * 1223 * @param array $cron Cron info array from _get_cron_array(). 1224 * @return array An upgraded Cron info array. 1225 */ 1226 function _upgrade_cron_array( $cron ) { 1227 if ( isset( $cron['version'] ) && 2 == $cron['version'] ) { 1228 return $cron; 1229 } 1230 1231 $new_cron = array(); 1232 1233 foreach ( (array) $cron as $timestamp => $hooks ) { 1234 foreach ( (array) $hooks as $hook => $args ) { 1235 $key = md5( serialize( $args['args'] ) ); 1236 $new_cron[ $timestamp ][ $hook ][ $key ] = $args; 1237 } 1238 } 1239 1240 $new_cron['version'] = 2; 1241 update_option( 'cron', $new_cron ); 1242 return $new_cron; 1243 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Thu Jul 24 01:00:02 2025 | Cross-referenced by PHPXref 0.7.1 |