WordPress.org
Get WordPress

Make WordPress Core


Ignore:
File:
1 edited

Legend:

Unmodified
Added
Removed

  • branches/4.9/src/wp-includes/cron.php

    r42343 r42343  
    11<?php
    22/**
    3  * WordPress CRON API
     3 * WordPress Cron API
    44 *
    55 * @package WordPress
    … …  
    77
    88/**
    9  * Schedules a hook to run only once.
    10  *
    11  * Schedules a hook which will be executed once by the WordPress actions core at
     9 * Schedules an event to run only once.
     10 *
     11 * Schedules an event which will execute once by the WordPress actions core at
    1212 * a time which you specify. The action will fire off when someone visits your
    1313 * WordPress site, if the schedule time has passed.
    1414 *
    15  * @since 2.1.0
    16  * @link http://codex.wordpress.org/Function_Reference/wp_schedule_single_event
    17  *
    18  * @param int $timestamp Timestamp for when to run the event.
    19  * @param string $hook Action hook to execute when cron is run.
     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 * @since 2.1.0
     20 * @link https://codex.wordpress.org/Function_Reference/wp_schedule_single_event
     21 *
     22 * @param int $timestamp Unix timestamp (UTC) for when to run the event.
     23 * @param string $hook Action hook to execute when event is run.
    2024 * @param array $args Optional. Arguments to pass to the hook's callback function.
     25 * @return false|void False if the event does not get scheduled.
    2126 */
    2227function wp_schedule_single_event( $timestamp, $hook, $args = array()) {
    23     // don't schedule a duplicate if there's already an identical event due in the next 10 minutes
     28    // Make sure timestamp is a positive integer
     29    if ( ! is_numeric( $timestamp ) || $timestamp <= 0 ) {
     30        return false;
     31    }
     32
     33    // Don't schedule a duplicate if there's already an identical event due within 10 minutes of it
    2434    $next = wp_next_scheduled($hook, $args);
    25     if ( $next && $next <= $timestamp + 10 * MINUTE_IN_SECONDS )
    26         return;
     35    if ( $next && abs( $next - $timestamp ) <= 10 * MINUTE_IN_SECONDS ) {
     36        return false;
     37    }
    2738
    2839    $crons = _get_cron_array();
    2940    $event = (object) array( 'hook' => $hook, 'timestamp' => $timestamp, 'schedule' => false, 'args' => $args );
    3041    /**
    31      * Filter a single event before it is scheduled.
     42     * Filters a single event before it is scheduled.
    3243     *
    3344     * @since 3.1.0
    3445     *
    35      * @param object $event An object containing an event's data.
     46     * @param stdClass $event {
     47     *     An object containing an event's data.
     48     *
     49     *     @type string       $hook      Action hook to execute when event is run.
     50     *     @type int          $timestamp Unix timestamp (UTC) for when to run the event.
     51     *     @type string|false $schedule  How often the event should recur. See `wp_get_schedules()`.
     52     *     @type array        $args      Arguments to pass to the hook's callback function.
     53     * }
    3654     */
    3755    $event = apply_filters( 'schedule_event', $event );
    … …  
    4967
    5068/**
    51  * Schedule a periodic event.
     69 * Schedule a recurring event.
    5270 *
    5371 * Schedules a hook which will be executed by the WordPress actions core on a
    … …  
    5573 * visits your WordPress site, if the scheduled time has passed.
    5674 *
    57  * Valid values for the recurrence are hourly, daily and twicedaily. These can
    58  * be extended using the cron_schedules filter in wp_get_schedules().
     75 * Valid values for the recurrence are hourly, daily, and twicedaily. These can
     76 * be extended using the {@see 'cron_schedules'} filter in wp_get_schedules().
    5977 *
    6078 * Use wp_next_scheduled() to prevent duplicates
    … …  
    6280 * @since 2.1.0
    6381 *
    64  * @param int $timestamp Timestamp for when to run the event.
     82 * @param int $timestamp Unix timestamp (UTC) for when to run the event.
    6583 * @param string $recurrence How often the event should recur.
    66  * @param string $hook Action hook to execute when cron is run.
     84 * @param string $hook Action hook to execute when event is run.
    6785 * @param array $args Optional. Arguments to pass to the hook's callback function.
    68  * @return bool|null False on failure, null when complete with scheduling event.
     86 * @return false|void False if the event does not get scheduled.
    6987 */
    7088function wp_schedule_event( $timestamp, $recurrence, $hook, $args = array()) {
     89    // Make sure timestamp is a positive integer
     90    if ( ! is_numeric( $timestamp ) || $timestamp <= 0 ) {
     91        return false;
     92    }
     93
    7194    $crons = _get_cron_array();
    7295    $schedules = wp_get_schedules();
    … …  
    95118 * @since 2.1.0
    96119 *
    97  * @param int $timestamp Timestamp for when to run the event.
     120 * @param int $timestamp Unix timestamp (UTC) for when to run the event.
    98121 * @param string $recurrence How often the event should recur.
    99  * @param string $hook Action hook to execute when cron is run.
     122 * @param string $hook Action hook to execute when event is run.
    100123 * @param array $args Optional. Arguments to pass to the hook's callback function.
    101  * @return bool|null False on failure. Null when event is rescheduled.
     124 * @return false|void False if the event does not get rescheduled.
    102125 */
    103126function wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array() ) {
     127    // Make sure timestamp is a positive integer
     128    if ( ! is_numeric( $timestamp ) || $timestamp <= 0 ) {
     129        return false;
     130    }
     131
    104132    $crons = _get_cron_array();
    105133    $schedules = wp_get_schedules();
    … …  
    132160
    133161/**
    134  * Unschedule a previously scheduled cron job.
    135  *
    136  * The $timestamp and $hook parameters are required, so that the event can be
     162 * Unschedule a previously scheduled event.
     163 *
     164 * The $timestamp and $hook parameters are required so that the event can be
    137165 * identified.
    138166 *
    139167 * @since 2.1.0
    140168 *
    141  * @param int $timestamp Timestamp for when to run the event.
     169 * @param int $timestamp Unix timestamp (UTC) for when to run the event.
    142170 * @param string $hook Action hook, the execution of which will be unscheduled.
    143171 * @param array $args Arguments to pass to the hook's callback function.
    … …  
    145173 * to uniquely identify the scheduled event, so they should be the same
    146174 * as those used when originally scheduling the event.
     175 * @return false|void False if the event does not get unscheduled.
    147176 */
    148177function wp_unschedule_event( $timestamp, $hook, $args = array() ) {
     178    // Make sure timestamp is a positive integer
     179    if ( ! is_numeric( $timestamp ) || $timestamp <= 0 ) {
     180        return false;
     181    }
     182
    149183    $crons = _get_cron_array();
    150184    $key = md5(serialize($args));
    … …  
    158192
    159193/**
    160  * Unschedule all cron jobs attached to a specific hook.
     194 * Unschedules all events attached to the hook with the specified arguments.
    161195 *
    162196 * @since 2.1.0
    163197 *
    164198 * @param string $hook Action hook, the execution of which will be unscheduled.
    165  * @param array $args Optional. Arguments that were to be pass to the hook's callback function.
     199 * @param array $args Optional. Arguments that were to be passed to the hook's callback function.
    166200 */
    167201function wp_clear_scheduled_hook( $hook, $args = array() ) {
    … …  
    169203    // Previously this function took the arguments as discrete vars rather than an array like the rest of the API
    170204    if ( !is_array($args) ) {
    171         _deprecated_argument( __FUNCTION__, '3.0', __('This argument has changed to an array to match the behavior of the other cron functions.') );
     205        _deprecated_argument( __FUNCTION__, '3.0.0', __('This argument has changed to an array to match the behavior of the other cron functions.') );
    172206        $args = array_slice( func_get_args(), 1 );
    173207    }
    … …  
    189223
    190224/**
    191  * Retrieve the next timestamp for a cron event.
    192  *
    193  * @since 2.1.0
    194  *
    195  * @param string $hook Action hook to execute when cron is run.
     225 * Unschedules all events attached to the hook.
     226 *
     227 * Can be useful for plugins when deactivating to clean up the cron queue.
     228 *
     229 * @since 4.9.0
     230 *
     231 * @param string $hook Action hook, the execution of which will be unscheduled.
     232 */
     233function wp_unschedule_hook( $hook ) {
     234    $crons = _get_cron_array();
     235
     236    foreach( $crons as $timestamp => $args ) {
     237        unset( $crons[ $timestamp ][ $hook ] );
     238
     239        if ( empty( $crons[ $timestamp ] ) ) {
     240            unset( $crons[ $timestamp ] );
     241        }
     242    }
     243
     244    _set_cron_array( $crons );
     245}
     246
     247/**
     248 * Retrieve the next timestamp for an event.
     249 *
     250 * @since 2.1.0
     251 *
     252 * @param string $hook Action hook to execute when event is run.
    196253 * @param array $args Optional. Arguments to pass to the hook's callback function.
    197  * @return bool|int The UNIX timestamp of the next time the scheduled event will occur.
     254 * @return false|int The Unix timestamp of the next time the scheduled event will occur.
    198255 */
    199256function wp_next_scheduled( $hook, $args = array() ) {
    … …  
    210267
    211268/**
    212  * Send request to run cron through HTTP request that doesn't halt page loading.
    213  *
    214  * @since 2.1.0
    215  *
    216  * @return null Cron could not be spawned, because it is not needed to run.
     269 * Sends a request to run cron through HTTP request that doesn't halt page loading.
     270 *
     271 * @since 2.1.0
     272 *
     273 * @param int $gmt_time Optional. Unix timestamp (UTC). Default 0 (current time is used).
    217274 */
    218275function spawn_cron( $gmt_time = 0 ) {
    219 
    220276    if ( ! $gmt_time )
    221277        $gmt_time = microtime( true );
    … …  
    225281
    226282    /*
    227     * multiple processes on multiple web servers can run this code concurrently
    228     * try to make this as atomic as possible by setting doing_cron switch
    229     */
     283     * Get the cron lock, which is a Unix timestamp of when the last cron was spawned
     284     * and has not finished running.
     285     *
     286     * Multiple processes on multiple web servers can run this code concurrently,
     287     * this lock attempts to make spawning as atomic as possible.
     288     */
    230289    $lock = get_transient('doing_cron');
    231290
    … …  
    246305        return;
    247306
    248     if ( defined('ALTERNATE_WP_CRON') && ALTERNATE_WP_CRON ) {
    249         if ( !empty($_POST) || defined('DOING_AJAX') )
     307    if ( defined( 'ALTERNATE_WP_CRON' ) && ALTERNATE_WP_CRON ) {
     308        if ( 'GET' !== $_SERVER['REQUEST_METHOD'] || defined( 'DOING_AJAX' ) ||  defined( 'XMLRPC_REQUEST' ) ) {
    250309            return;
     310        }
    251311
    252312        $doing_wp_cron = sprintf( '%.22F', $gmt_time );
    … …  
    265325    }
    266326
     327    // Set the cron lock with the current unix timestamp, when the cron is being spawned.
    267328    $doing_wp_cron = sprintf( '%.22F', $gmt_time );
    268329    set_transient( 'doing_cron', $doing_wp_cron );
    269330
    270331    /**
    271      * Filter the cron request arguments.
     332     * Filters the cron request arguments.
    272333     *
    273334     * @since 3.5.0
     335     * @since 4.5.0 The `$doing_wp_cron` parameter was added.
    274336     *
    275337     * @param array $cron_request_array {
    … …  
    286348     *     }
    287349     * }
     350     * @param string $doing_wp_cron The unix timestamp of the cron lock.
    288351     */
    289352    $cron_request = apply_filters( 'cron_request', array(
    … …  
    293356            'timeout'   => 0.01,
    294357            'blocking'  => false,
    295             /** This filter is documented in wp-includes/class-http.php */
     358            /** This filter is documented in wp-includes/class-wp-http-streams.php */
    296359            'sslverify' => apply_filters( 'https_local_ssl_verify', false )
    297360        )
    298     ) );
     361    ), $doing_wp_cron );
    299362
    300363    wp_remote_post( $cron_request['url'], $cron_request['args'] );
    … …  
    305368 *
    306369 * @since 2.1.0
    307  *
    308  * @return null When doesn't need to run Cron.
    309370 */
    310371function wp_cron() {
    311 
    312372    // Prevent infinite loops caused by lack of wp-cron.php
    313373    if ( strpos($_SERVER['REQUEST_URI'], '/wp-cron.php') !== false || ( defined('DISABLE_WP_CRON') && DISABLE_WP_CRON ) )
    … …  
    335395
    336396/**
    337  * Retrieve supported and filtered Cron recurrences.
    338  *
    339  * The supported recurrences are 'hourly' and 'daily'. A plugin may add more by
    340  * hooking into the 'cron_schedules' filter. The filter accepts an array of
    341  * arrays. The outer array has a key that is the name of the schedule or for
     397 * Retrieve supported event recurrence schedules.
     398 *
     399 * The default supported recurrences are 'hourly', 'twicedaily', and 'daily'. A plugin may
     400 * add more by hooking into the {@see 'cron_schedules'} filter. The filter accepts an array
     401 * of arrays. The outer array has a key that is the name of the schedule or for
    342402 * example 'weekly'. The value is an array with two keys, one is 'interval' and
    343403 * the other is 'display'.
    … …  
    348408 *
    349409 * The 'display' is the description. For the 'weekly' key, the 'display' would
    350  * be <code>__('Once Weekly')</code>.
     410 * be `__( 'Once Weekly' )`.
    351411 *
    352412 * For your plugin, you will be passed an array. you can easily add your
    353413 * schedule by doing the following.
    354  * <code>
    355  * // filter parameter variable name is 'array'
    356  *  $array['weekly'] = array(
    357  *      'interval' => 604800,
    358  *      'display' => __('Once Weekly')
    359  *  );
    360  * </code>
     414 *
     415 *     // Filter parameter variable name is 'array'.
     416 *     $array['weekly'] = array(
     417 *         'interval' => 604800,
     418 *         'display'  => __( 'Once Weekly' )
     419 *     );
     420 *
    361421 *
    362422 * @since 2.1.0
    … …  
    371431    );
    372432    /**
    373      * Filter the non-default cron schedules.
     433     * Filters the non-default cron schedules.
    374434     *
    375435     * @since 2.1.0
    … …  
    381441
    382442/**
    383  * Retrieve Cron schedule for hook with arguments.
    384  *
    385  * @since 2.1.0
    386  *
    387  * @param string $hook Action hook to execute when cron is run.
    388  * @param array $args Optional. Arguments to pass to the hook's callback function.
    389  * @return string|bool False, if no schedule. Schedule on success.
     443 * Retrieve the recurrence schedule for an event.
     444 *
     445 * @see wp_get_schedules() for available schedules.
     446 *
     447 * @since 2.1.0
     448 *
     449 * @param string $hook Action hook to identify the event.
     450 * @param array $args Optional. Arguments passed to the event's callback function.
     451 * @return string|false False, if no schedule. Schedule name on success.
    390452 */
    391453function wp_get_schedule($hook, $args = array()) {
    … …  
    411473 * @access private
    412474 *
    413  * @return array CRON info array.
     475 * @return false|array CRON info array.
    414476 */
    415477function _get_cron_array()  {
    … …  
    432494 * @access private
    433495 *
    434  * @param array $cron Cron info array from {@link _get_cron_array()}.
     496 * @param array $cron Cron info array from _get_cron_array().
    435497 */
    436498function _set_cron_array($cron) {
    … …  
    447509 * @access private
    448510 *
    449  * @param array $cron Cron info array from {@link _get_cron_array()}.
     511 * @param array $cron Cron info array from _get_cron_array().
    450512 * @return array An upgraded Cron info array.
    451513 */
Note: See TracChangeset for help on using the changeset viewer.