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