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