WordPress.org
Get WordPress

Make WordPress Core

Changeset 42216 for trunk


Ignore:
Timestamp:
11/22/2017 03:15:35 PM (7 years ago)
Author:
johnbillion
Message:

Cron API: Improvements to docblocks for the event scheduling functions.

See #42505

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/cron.php

    r40970 r42216  
    99 * Schedules an event to run only once.
    1010 *
    11  * Schedules an event which will execute once by the WordPress actions core at
    12  * a time which you specify. The action will fire off when someone visits your
    13  * WordPress site, if the schedule time has passed.
     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.
    1414 *
    1515 * Note that scheduling an event to occur within 10 minutes of an existing event
    … …  
    1717 * for each scheduled event.
    1818 *
     19 * Use wp_next_scheduled() to prevent duplicate events.
     20 *
     21 * Use wp_schedule_event() to schedule a recurring event.
     22 *
    1923 * @since 2.1.0
    2024 * @link https://codex.wordpress.org/Function_Reference/wp_schedule_single_event
    2125 *
    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.
    24  * @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.
     26 * @param int    $timestamp  Unix timestamp (UTC) for when to next run the event.
     27 * @param string $hook       Action hook to execute when the event is run.
     28 * @param array  $args       Optional. Array containing each separate argument to pass to the hook's callback function.
     29 * @return false|void False if the event did not get scheduled.
    2630 */
    2731function wp_schedule_single_event( $timestamp, $hook, $args = array()) {
    … …  
    3943    $crons = _get_cron_array();
    4044    $event = (object) array( 'hook' => $hook, 'timestamp' => $timestamp, 'schedule' => false, 'args' => $args );
     45
    4146    /**
    4247     * Filters a single event before it is scheduled.
    … …  
    4752     *     An object containing an event's data.
    4853     *
    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.
     54     *     @type string       $hook      Action hook to execute when the event is run.
     55     *     @type int          $timestamp Unix timestamp (UTC) for when to next run the event.
     56     *     @type string|false $schedule  How often the event should subsequently recur.
     57     *     @type array        $args      Array containing each separate argument to pass to the hook's callback function.
     58     *     @type int          $interval  The interval time in seconds for the schedule. Only present for recurring events.
    5359     * }
    5460     */
    … …  
    6773
    6874/**
    69  * Schedule a recurring event.
    70  *
    71  * Schedules a hook which will be executed by the WordPress actions core on a
    72  * specific interval, specified by you. The action will trigger when someone
    73  * visits your WordPress site, if the scheduled time has passed.
    74  *
    75  * Valid values for the recurrence are hourly, daily, and twicedaily. These can
     75 * Schedules a recurring event.
     76 *
     77 * Schedules a hook which will be triggered by WordPress at the specified interval.
     78 * The action will trigger when someone visits your WordPress site if the scheduled
     79 * time has passed.
     80 *
     81 * Valid values for the recurrence are 'hourly', 'daily', and 'twicedaily'. These can
    7682 * be extended using the {@see 'cron_schedules'} filter in wp_get_schedules().
    7783 *
    78  * Use wp_next_scheduled() to prevent duplicates
    79  *
    80  * @since 2.1.0
    81  *
    82  * @param int $timestamp Unix timestamp (UTC) for when to run the event.
    83  * @param string $recurrence How often the event should recur.
    84  * @param string $hook Action hook to execute when event is run.
    85  * @param array $args Optional. Arguments to pass to the hook's callback function.
    86  * @return false|void False if the event does not get scheduled.
     84 * Note that scheduling an event to occur within 10 minutes of an existing event
     85 * with the same action hook will be ignored unless you pass unique `$args` values
     86 * for each scheduled event.
     87 *
     88 * Use wp_next_scheduled() to prevent duplicate events.
     89 *
     90 * Use wp_schedule_single_event() to schedule a non-recurring event.
     91 *
     92 * @since 2.1.0
     93 * @link https://codex.wordpress.org/Function_Reference/wp_schedule_event
     94 *
     95 * @param int    $timestamp  Unix timestamp (UTC) for when to next run the event.
     96 * @param string $recurrence How often the event should subsequently recur. See wp_get_schedules() for accepted values.
     97 * @param string $hook       Action hook to execute when the event is run.
     98 * @param array  $args       Optional. Array containing each separate argument to pass to the hook's callback function.
     99 * @return false|void False if the event did not get scheduled.
    87100 */
    88101function wp_schedule_event( $timestamp, $recurrence, $hook, $args = array()) {
    … …  
    114127
    115128/**
    116  * Reschedule a recurring event.
    117  *
    118  * @since 2.1.0
    119  *
    120  * @param int $timestamp Unix timestamp (UTC) for when to run the event.
    121  * @param string $recurrence How often the event should recur.
    122  * @param string $hook Action hook to execute when event is run.
    123  * @param array $args Optional. Arguments to pass to the hook's callback function.
    124  * @return false|void False if the event does not get rescheduled.
     129 * Reschedules a recurring event.
     130 *
     131 * @since 2.1.0
     132 *
     133 * @param int    $timestamp  Unix timestamp (UTC) for when to next run the event.
     134 * @param string $recurrence How often the event should subsequently recur. See wp_get_schedules() for accepted values.
     135 * @param string $hook       Action hook to execute when the event is run.
     136 * @param array  $args       Optional. Array containing each separate argument to pass to the hook's callback function.
     137 * @return false|void False if the event did not get rescheduled.
    125138 */
    126139function wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array() ) {
    … …  
    167180 * @since 2.1.0
    168181 *
    169  * @param int $timestamp Unix timestamp (UTC) for when to run the event.
    170  * @param string $hook Action hook, the execution of which will be unscheduled.
    171  * @param array $args Arguments to pass to the hook's callback function.
    172  * Although not passed to a callback function, these arguments are used
    173  * to uniquely identify the scheduled event, so they should be the same
    174  * as those used when originally scheduling the event.
    175  * @return false|void False if the event does not get unscheduled.
     182 * @param int    $timestamp Unix timestamp (UTC) of the event.
     183 * @param string $hook      Action hook of the event.
     184 * @param array  $args      Optional. Array containing each separate argument to pass to the hook's callback function.
     185 *                          Although not passed to a callback, these arguments are used to uniquely identify the
     186 *                          event, so they should be the same as those used when originally scheduling the event.
     187 * @return false|void False if the event did not get unscheduled.
    176188 */
    177189function wp_unschedule_event( $timestamp, $hook, $args = array() ) {
    … …  
    250262 * @since 2.1.0
    251263 *
    252  * @param string $hook Action hook to execute when event is run.
    253  * @param array $args Optional. Arguments to pass to the hook's callback function.
    254  * @return false|int The Unix timestamp of the next time the scheduled event will occur.
     264 * @param string $hook Action hook of the event.
     265 * @param array  $args Optional. Array containing each separate argument to pass to the hook's callback function.
     266 *                     Although not passed to a callback, these arguments are used to uniquely identify the
     267 *                     event, so they should be the same as those used when originally scheduling the event.
     268 * @return false|int The Unix timestamp of the next time the event will occur. False if the event doesn't exist.
    255269 */
    256270function wp_next_scheduled( $hook, $args = array() ) {
Note: See TracChangeset for help on using the changeset viewer.