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