[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * WordPress CRON API
   4   *
   5   * @package WordPress
   6   */
   7  
   8  /**
   9   * Schedules a hook to run only once.
  10   *
  11   * Schedules a hook which will be executed 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.
  14   *
  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.
  20   * @param array $args Optional. Arguments to pass to the hook's callback function.
  21   */
  22  function 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
  24      $next = wp_next_scheduled($hook, $args);
  25      if ( $next && $next <= $timestamp + 600 )
  26          return;
  27  
  28      $crons = _get_cron_array();
  29      $key = md5(serialize($args));
  30      $crons[$timestamp][$hook][$key] = array( 'schedule' => false, 'args' => $args );
  31      uksort( $crons, "strnatcasecmp" );
  32      _set_cron_array( $crons );
  33  }
  34  
  35  /**
  36   * Schedule a periodic event.
  37   *
  38   * Schedules a hook which will be executed by the WordPress actions core on a
  39   * specific interval, specified by you. The action will trigger when someone
  40   * visits your WordPress site, if the scheduled time has passed.
  41   *
  42   * Valid values for the recurrence are hourly, daily and twicedaily.  These can
  43   * be extended using the cron_schedules filter in wp_get_schedules().
  44   *
  45   * @since 2.1.0
  46   *
  47   * @param int $timestamp Timestamp for when to run the event.
  48   * @param string $recurrence How often the event should recur.
  49   * @param string $hook Action hook to execute when cron is run.
  50   * @param array $args Optional. Arguments to pass to the hook's callback function.
  51   * @return bool|null False on failure, null when complete with scheduling event.
  52   */
  53  function wp_schedule_event( $timestamp, $recurrence, $hook, $args = array()) {
  54      $crons = _get_cron_array();
  55      $schedules = wp_get_schedules();
  56      $key = md5(serialize($args));
  57      if ( !isset( $schedules[$recurrence] ) )
  58          return false;
  59      $crons[$timestamp][$hook][$key] = array( 'schedule' => $recurrence, 'args' => $args, 'interval' => $schedules[$recurrence]['interval'] );
  60      uksort( $crons, "strnatcasecmp" );
  61      _set_cron_array( $crons );
  62  }
  63  
  64  /**
  65   * Reschedule a recurring event.
  66   *
  67   * @since 2.1.0
  68   *
  69   * @param int $timestamp Timestamp for when to run the event.
  70   * @param string $recurrence How often the event should recur.
  71   * @param string $hook Action hook to execute when cron is run.
  72   * @param array $args Optional. Arguments to pass to the hook's callback function.
  73   * @return bool|null False on failure. Null when event is rescheduled.
  74   */
  75  function wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array()) {
  76      $crons = _get_cron_array();
  77      $schedules = wp_get_schedules();
  78      $key = md5(serialize($args));
  79      $interval = 0;
  80  
  81      // First we try to get it from the schedule
  82      if ( 0 == $interval )
  83          $interval = $schedules[$recurrence]['interval'];
  84      // Now we try to get it from the saved interval in case the schedule disappears
  85      if ( 0 == $interval )
  86          $interval = $crons[$timestamp][$hook][$key]['interval'];
  87      // Now we assume something is wrong and fail to schedule
  88      if ( 0 == $interval )
  89          return false;
  90  
  91      $now = time();
  92  
  93      if ( $timestamp >= $now )
  94          $timestamp = $now + $interval;
  95      else
  96          $timestamp = $now + ($interval - (($now - $timestamp) % $interval));
  97  
  98      wp_schedule_event( $timestamp, $recurrence, $hook, $args );
  99  }
 100  
 101  /**
 102   * Unschedule a previously scheduled cron job.
 103   *
 104   * The $timestamp and $hook parameters are required, so that the event can be
 105   * identified.
 106   *
 107   * @since 2.1.0
 108   *
 109   * @param int $timestamp Timestamp for when to run the event.
 110   * @param string $hook Action hook, the execution of which will be unscheduled.
 111   * @param array $args Arguments to pass to the hook's callback function.
 112   * Although not passed to a callback function, these arguments are used
 113   * to uniquely identify the scheduled event, so they should be the same
 114   * as those used when originally scheduling the event.
 115   */
 116  function wp_unschedule_event( $timestamp, $hook, $args = array() ) {
 117      $crons = _get_cron_array();
 118      $key = md5(serialize($args));
 119      unset( $crons[$timestamp][$hook][$key] );
 120      if ( empty($crons[$timestamp][$hook]) )
 121          unset( $crons[$timestamp][$hook] );
 122      if ( empty($crons[$timestamp]) )
 123          unset( $crons[$timestamp] );
 124      _set_cron_array( $crons );
 125  }
 126  
 127  /**
 128   * Unschedule all cron jobs attached to a specific hook.
 129   *
 130   * @since 2.1.0
 131   *
 132   * @param string $hook Action hook, the execution of which will be unscheduled.
 133   * @param array $args Optional. Arguments that were to be pass to the hook's callback function.
 134   */
 135  function wp_clear_scheduled_hook( $hook, $args = array() ) {
 136      // Backward compatibility
 137      // Previously this function took the arguments as discrete vars rather than an array like the rest of the API
 138      if ( !is_array($args) ) {
 139          _deprecated_argument( __FUNCTION__, '3.0.0', __('This argument has changed to an array to match the behavior of the other cron functions.') );
 140          $args = array_slice( func_get_args(), 1 );
 141      }
 142  
 143      while ( $timestamp = wp_next_scheduled( $hook, $args ) )
 144          wp_unschedule_event( $timestamp, $hook, $args );
 145  }
 146  
 147  /**
 148   * Retrieve the next timestamp for a cron event.
 149   *
 150   * @since 2.1.0
 151   *
 152   * @param string $hook Action hook to execute when cron is run.
 153   * @param array $args Optional. Arguments to pass to the hook's callback function.
 154   * @return bool|int The UNIX timestamp of the next time the scheduled event will occur.
 155   */
 156  function wp_next_scheduled( $hook, $args = array() ) {
 157      $crons = _get_cron_array();
 158      $key = md5(serialize($args));
 159      if ( empty($crons) )
 160          return false;
 161      foreach ( $crons as $timestamp => $cron ) {
 162          if ( isset( $cron[$hook][$key] ) )
 163              return $timestamp;
 164      }
 165      return false;
 166  }
 167  
 168  /**
 169   * Send request to run cron through HTTP request that doesn't halt page loading.
 170   *
 171   * @since 2.1.0
 172   *
 173   * @return null Cron could not be spawned, because it is not needed to run.
 174   */
 175  function spawn_cron( $local_time = 0 ) {
 176  
 177      if ( !$local_time )
 178          $local_time = time();
 179  
 180      if ( defined('DOING_CRON') || isset($_GET['doing_wp_cron']) )
 181          return;
 182  
 183      /*
 184       * do not even start the cron if local server timer has drifted
 185       * such as due to power failure, or misconfiguration
 186       */
 187      $timer_accurate = check_server_timer( $local_time );
 188      if ( !$timer_accurate )
 189          return;
 190  
 191      /*
 192      * multiple processes on multiple web servers can run this code concurrently
 193      * try to make this as atomic as possible by setting doing_cron switch
 194      */
 195      $flag = get_transient('doing_cron');
 196  
 197      if ( $flag > $local_time + 10*60 )
 198          $flag = 0;
 199  
 200      // don't run if another process is currently running it or more than once every 60 sec.
 201      if ( $flag + 60 > $local_time )
 202          return;
 203  
 204      //sanity check
 205      $crons = _get_cron_array();
 206      if ( !is_array($crons) )
 207          return;
 208  
 209      $keys = array_keys( $crons );
 210      if ( isset($keys[0]) && $keys[0] > $local_time )
 211          return;
 212  
 213      if ( defined('ALTERNATE_WP_CRON') && ALTERNATE_WP_CRON ) {
 214          if ( !empty($_POST) || defined('DOING_AJAX') )
 215              return;
 216  
 217          set_transient( 'doing_cron', $local_time );
 218  
 219          ob_start();
 220          wp_redirect( add_query_arg('doing_wp_cron', '', stripslashes($_SERVER['REQUEST_URI'])) );
 221          echo ' ';
 222  
 223          // flush any buffers and send the headers
 224          while ( @ob_end_flush() );
 225          flush();
 226  
 227          @include_once (ABSPATH . 'wp-cron.php');
 228          return;
 229      }
 230  
 231      set_transient( 'doing_cron', $local_time );
 232  
 233      $cron_url = get_option( 'siteurl' ) . '/wp-cron.php?doing_wp_cron';
 234      wp_remote_post( $cron_url, array('timeout' => 0.01, 'blocking' => false, 'sslverify' => apply_filters('https_local_ssl_verify', true)) );
 235  }
 236  
 237  /**
 238   * Run scheduled callbacks or spawn cron for all scheduled events.
 239   *
 240   * @since 2.1.0
 241   *
 242   * @return null When doesn't need to run Cron.
 243   */
 244  function wp_cron() {
 245  
 246      // Prevent infinite loops caused by lack of wp-cron.php
 247      if ( strpos($_SERVER['REQUEST_URI'], '/wp-cron.php') !== false || ( defined('DISABLE_WP_CRON') && DISABLE_WP_CRON ) )
 248          return;
 249  
 250      if ( false === $crons = _get_cron_array() )
 251          return;
 252  
 253      $local_time = time();
 254      $keys = array_keys( $crons );
 255      if ( isset($keys[0]) && $keys[0] > $local_time )
 256          return;
 257  
 258      $schedules = wp_get_schedules();
 259      foreach ( $crons as $timestamp => $cronhooks ) {
 260          if ( $timestamp > $local_time ) break;
 261          foreach ( (array) $cronhooks as $hook => $args ) {
 262              if ( isset($schedules[$hook]['callback']) && !call_user_func( $schedules[$hook]['callback'] ) )
 263                  continue;
 264              spawn_cron( $local_time );
 265              break 2;
 266          }
 267      }
 268  }
 269  
 270  /**
 271   * Retrieve supported and filtered Cron recurrences.
 272   *
 273   * The supported recurrences are 'hourly' and 'daily'. A plugin may add more by
 274   * hooking into the 'cron_schedules' filter. The filter accepts an array of
 275   * arrays. The outer array has a key that is the name of the schedule or for
 276   * example 'weekly'. The value is an array with two keys, one is 'interval' and
 277   * the other is 'display'.
 278   *
 279   * The 'interval' is a number in seconds of when the cron job should run. So for
 280   * 'hourly', the time is 3600 or 60*60. For weekly, the value would be
 281   * 60*60*24*7 or 604800. The value of 'interval' would then be 604800.
 282   *
 283   * The 'display' is the description. For the 'weekly' key, the 'display' would
 284   * be <code>__('Once Weekly')</code>.
 285   *
 286   * For your plugin, you will be passed an array. you can easily add your
 287   * schedule by doing the following.
 288   * <code>
 289   * // filter parameter variable name is 'array'
 290   *    $array['weekly'] = array(
 291   *        'interval' => 604800,
 292   *        'display' => __('Once Weekly')
 293   *    );
 294   * </code>
 295   *
 296   * @since 2.1.0
 297   *
 298   * @return array
 299   */
 300  function wp_get_schedules() {
 301      $schedules = array(
 302          'hourly' => array( 'interval' => 3600, 'display' => __('Once Hourly') ),
 303          'twicedaily' => array( 'interval' => 43200, 'display' => __('Twice Daily') ),
 304          'daily' => array( 'interval' => 86400, 'display' => __('Once Daily') ),
 305      );
 306      return array_merge( apply_filters( 'cron_schedules', array() ), $schedules );
 307  }
 308  
 309  /**
 310   * Retrieve Cron schedule for hook with arguments.
 311   *
 312   * @since 2.1.0
 313   *
 314   * @param string $hook Action hook to execute when cron is run.
 315   * @param array $args Optional. Arguments to pass to the hook's callback function.
 316   * @return string|bool False, if no schedule. Schedule on success.
 317   */
 318  function wp_get_schedule($hook, $args = array()) {
 319      $crons = _get_cron_array();
 320      $key = md5(serialize($args));
 321      if ( empty($crons) )
 322          return false;
 323      foreach ( $crons as $timestamp => $cron ) {
 324          if ( isset( $cron[$hook][$key] ) )
 325              return $cron[$hook][$key]['schedule'];
 326      }
 327      return false;
 328  }
 329  
 330  //
 331  // Private functions
 332  //
 333  
 334  /**
 335   * Retrieve cron info array option.
 336   *
 337   * @since 2.1.0
 338   * @access private
 339   *
 340   * @return array CRON info array.
 341   */
 342  function _get_cron_array()  {
 343      $cron = get_option('cron');
 344      if ( ! is_array($cron) )
 345          return false;
 346  
 347      if ( !isset($cron['version']) )
 348          $cron = _upgrade_cron_array($cron);
 349  
 350      unset($cron['version']);
 351  
 352      return $cron;
 353  }
 354  
 355  /**
 356   * Updates the CRON option with the new CRON array.
 357   *
 358   * @since 2.1.0
 359   * @access private
 360   *
 361   * @param array $cron Cron info array from {@link _get_cron_array()}.
 362   */
 363  function _set_cron_array($cron) {
 364      $cron['version'] = 2;
 365      update_option( 'cron', $cron );
 366  }
 367  
 368  /**
 369   * Upgrade a Cron info array.
 370   *
 371   * This function upgrades the Cron info array to version 2.
 372   *
 373   * @since 2.1.0
 374   * @access private
 375   *
 376   * @param array $cron Cron info array from {@link _get_cron_array()}.
 377   * @return array An upgraded Cron info array.
 378   */
 379  function _upgrade_cron_array($cron) {
 380      if ( isset($cron['version']) && 2 == $cron['version'])
 381          return $cron;
 382  
 383      $new_cron = array();
 384  
 385      foreach ( (array) $cron as $timestamp => $hooks) {
 386          foreach ( (array) $hooks as $hook => $args ) {
 387              $key = md5(serialize($args['args']));
 388              $new_cron[$timestamp][$hook][$key] = $args;
 389          }
 390      }
 391  
 392      $new_cron['version'] = 2;
 393      update_option( 'cron', $new_cron );
 394      return $new_cron;
 395  }
 396  
 397  // stub for checking server timer accuracy, using outside standard time sources
 398  function check_server_timer( $local_time ) {
 399      return true;
 400  }