WordPress.org
Get WordPress

Make WordPress Core

Ticket #32656: with-return-codes.diff

File with-return-codes.diff, 12.5 KB (added by DavidAnderson, 8 years ago)

New patch incorporating both the suggested filters, and return codes for all relevant functions

  • wp-includes/cron.php

     
    1818 * @param int $timestamp Timestamp for when to run the event.
    1919 * @param string $hook Action hook to execute when cron is run.
    2020 * @param array $args Optional. Arguments to pass to the hook's callback function.
    21  * @return false|void False when an event is not scheduled.
     21 * @return bool Whether or not the requested event has been scheduled.
    2222 */
    2323function wp_schedule_single_event( $timestamp, $hook, $args = array()) {
    2424        // Make sure timestamp is a positive integer
    … …  
    2626                return false;
    2727        }
    2828
     29        $event = (object) array( 'hook' => $hook, 'timestamp' => $timestamp, 'schedule' => false, 'args' => $args );
     30
     31        /**
     32         * Filter to preflight or hijack scheduling an event.
     33         *
     34         * Passing a non-null value will short-circuit adding the event to the cron
     35         * array, returning the passed value instead.
     36         *
     37         * Both single events and recurring events are passed through this filter;
     38         * single events have `$event->schedule` as false, whereas recurring events
     39         * have this set to a recurrence from {@see wp_get_schedules}. Recurring
     40         * events also have the integer recurrence interval set as `$event->interval`
     41         *
     42         * @param null|bool $pre Value to return instead. Default null to continue adding the event.
     43         * @param object $event An object containing the event's data.
     44         */
     45        $pre = apply_filters( 'pre_schedule_event', null, $event );
     46        if ( null !== $pre ) {
     47                return $pre;
     48        }
     49       
    2950        // Don't schedule a duplicate if there's already an identical event due within 10 minutes of it
    3051        $next = wp_next_scheduled($hook, $args);
    3152        if ( $next && abs( $next - $timestamp ) <= 10 * MINUTE_IN_SECONDS ) {
    … …  
    3253                return false;
    3354        }
    3455
    35         $crons = _get_cron_array();
    36         $event = (object) array( 'hook' => $hook, 'timestamp' => $timestamp, 'schedule' => false, 'args' => $args );
    3756        /**
    3857         * Filter a single event before it is scheduled.
    3958         *
    … …  
    4968
    5069        $key = md5(serialize($event->args));
    5170
     71        $crons = _get_cron_array();
    5272        $crons[$event->timestamp][$event->hook][$key] = array( 'schedule' => $event->schedule, 'args' => $event->args );
    5373        uksort( $crons, "strnatcasecmp" );
    54         _set_cron_array( $crons );
     74        return _set_cron_array( $crons );
    5575}
    5676
    5777/**
    … …  
    7292 * @param string $recurrence How often the event should recur.
    7393 * @param string $hook Action hook to execute when cron is run.
    7494 * @param array $args Optional. Arguments to pass to the hook's callback function.
    75  * @return false|void False when an event is not scheduled.
     95 * @return bool Whether or not the requested event has been scheduled.
    7696 */
    7797function wp_schedule_event( $timestamp, $recurrence, $hook, $args = array()) {
    7898        // Make sure timestamp is a positive integer
    … …  
    80100                return false;
    81101        }
    82102
    83         $crons = _get_cron_array();
    84103        $schedules = wp_get_schedules();
    85104
    86105        if ( !isset( $schedules[$recurrence] ) )
    … …  
    87106                return false;
    88107
    89108        $event = (object) array( 'hook' => $hook, 'timestamp' => $timestamp, 'schedule' => $recurrence, 'args' => $args, 'interval' => $schedules[$recurrence]['interval'] );
     109       
    90110        /** This filter is documented in wp-includes/cron.php */
     111        $pre = apply_filters( 'pre_schedule_event', null, $event );
     112        if ( null !== $pre ) {
     113                return $pre;
     114        }
     115
     116        /** This filter is documented in wp-includes/cron.php */
    91117        $event = apply_filters( 'schedule_event', $event );
    92118
    93119        // A plugin disallowed this event
    … …  
    96122
    97123        $key = md5(serialize($event->args));
    98124
     125        $crons = _get_cron_array();
    99126        $crons[$event->timestamp][$event->hook][$key] = array( 'schedule' => $event->schedule, 'args' => $event->args, 'interval' => $event->interval );
    100127        uksort( $crons, "strnatcasecmp" );
    101         _set_cron_array( $crons );
     128        return _set_cron_array( $crons );
    102129}
    103130
    104131/**
    … …  
    110137 * @param string $recurrence How often the event should recur.
    111138 * @param string $hook Action hook to execute when cron is run.
    112139 * @param array $args Optional. Arguments to pass to the hook's callback function.
    113  * @return false|void False when an event is not scheduled.
     140 * @return bool Whether or not the requested event has been rescheduled.
    114141 */
    115142function wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array() ) {
    116143        // Make sure timestamp is a positive integer
    … …  
    118145                return false;
    119146        }
    120147
     148        /**
     149         * Filter to preflight or hijack rescheduling of events.
     150         *
     151         * Passing a non-null value will short-circuit the normal rescheduling
     152         * process, returning the passed value instead.
     153         *
     154         * Note that `$recurrence` is the original stored value. This is not
     155         * guaranteed to exist when the event is rescheduled, so plugins should
     156         * store the interval value and fall back to this if needed.
     157         *
     158         * @param null|bool $pre Value to return instead. Default null to continue rescheduling the event.
     159         * @param int $timestamp Timestamp for when the event originally ran.
     160         * @param string $recurrence How often the event should recur.
     161         * @param string $hook Action hook to execute when cron is run.
     162         * @param array $args Optional. Arguments to pass to the hook's callback function.
     163         */
     164        $pre = apply_filters( 'pre_reschedule_event', null, $timestamp, $recurrence, $hook, $args );
     165        if ( $pre !== null ) {
     166                return $pre;
     167        }
     168       
    121169        $crons = _get_cron_array();
    122170        $schedules = wp_get_schedules();
    123171        $key = md5( serialize( $args ) );
    … …  
    144192                $timestamp = $now + ( $interval - ( ( $now - $timestamp ) % $interval ) );
    145193        }
    146194
    147         wp_schedule_event( $timestamp, $recurrence, $hook, $args );
     195        return wp_schedule_event( $timestamp, $recurrence, $hook, $args );
    148196}
    149197
    150198/**
    … …  
    161209 * Although not passed to a callback function, these arguments are used
    162210 * to uniquely identify the scheduled event, so they should be the same
    163211 * as those used when originally scheduling the event.
    164  * @return false|void False when an event is not unscheduled.
     212 * @return bool Whether or not the requested event has been rescheduled.
    165213 */
    166214function wp_unschedule_event( $timestamp, $hook, $args = array() ) {
    167215        // Make sure timestamp is a positive integer
    … …  
    169217                return false;
    170218        }
    171219
     220        /**
     221         * Filter to preflight or hijack unscheduling of events.
     222         *
     223         * Passing a non-null value will short-circuit the normal unscheduling
     224         * process, returning the passed value instead.
     225         *
     226         * @param null|bool $pre Value to return instead. Default null to continue unscheduling the event.
     227         * @param int $timestamp Timestamp for when to run the event.
     228         * @param string $hook Action hook, the execution of which will be unscheduled.
     229         * @param array $args Arguments to pass to the hook's callback function.
     230         */
     231        $pre = apply_filters( 'pre_unschedule_event', null, $timestamp, $hook, $args );
     232        if ( $pre !== null ) {
     233                return $pre;
     234        }
     235       
    172236        $crons = _get_cron_array();
    173237        $key = md5(serialize($args));
    174238        unset( $crons[$timestamp][$hook][$key] );
    … …  
    176240                unset( $crons[$timestamp][$hook] );
    177241        if ( empty($crons[$timestamp]) )
    178242                unset( $crons[$timestamp] );
    179         _set_cron_array( $crons );
     243        return _set_cron_array( $crons );
    180244}
    181245
    182246/**
    … …  
    186250 *
    187251 * @param string $hook Action hook, the execution of which will be unscheduled.
    188252 * @param array $args Optional. Arguments that were to be pass to the hook's callback function.
     253 * @return array Boolean values, indicating the result of attempting to unschedule each indicated event, with timestamps as keys.
    189254 */
    190255function wp_clear_scheduled_hook( $hook, $args = array() ) {
    191256        // Backward compatibility
    … …  
    195260                $args = array_slice( func_get_args(), 1 );
    196261        }
    197262
     263        /**
     264         * Filter to preflight or hijack clearing a scheduled hook.
     265         *
     266         * Passing a non-null value will short-circuit the normal unscheduling
     267         * process, returning the passed value instead.
     268         *
     269         * @param null|array $pre Value to return instead. Default null to continue unscheduling the event.
     270         * @param string $hook Action hook, the execution of which will be unscheduled.
     271         * @param array $args Arguments to pass to the hook's callback function.
     272         */
     273        $pre = apply_filters( 'pre_clear_scheduled_hook', null, $hook, $args );
     274        if ( $pre !== null ) {
     275                return $pre;
     276        }
     277
    198278        // This logic duplicates wp_next_scheduled()
    199279        // It's required due to a scenario where wp_unschedule_event() fails due to update_option() failing,
    200280        // and, wp_next_scheduled() returns the same schedule in an infinite loop.
    201281        $crons = _get_cron_array();
    202282        if ( empty( $crons ) )
    203                 return;
     283                return array();
    204284
     285        $results = array();
    205286        $key = md5( serialize( $args ) );
    206287        foreach ( $crons as $timestamp => $cron ) {
    207288                if ( isset( $cron[ $hook ][ $key ] ) ) {
    208                         wp_unschedule_event( $timestamp, $hook, $args );
     289                        $results[ $timestamp ] = wp_unschedule_event( $timestamp, $hook, $args );
    209290                }
    210291        }
     292        return $results;
    211293}
    212294
    213295/**
    … …  
    222304function wp_next_scheduled( $hook, $args = array() ) {
    223305        $crons = _get_cron_array();
    224306        $key = md5(serialize($args));
    225         if ( empty($crons) )
    226                 return false;
    227         foreach ( $crons as $timestamp => $cron ) {
    228                 if ( isset( $cron[$hook][$key] ) )
    229                         return $timestamp;
     307        $next = false;
     308
     309        if ( ! empty($crons) ) {
     310                foreach ( $crons as $timestamp => $cron ) {
     311                        if ( isset( $cron[$hook][$key] ) ) {
     312                                $next = $timestamp;
     313                                break;
     314                        }
     315                }
    230316        }
    231         return false;
     317
     318        /**
     319         * Filter the next scheduled event timestamp.
     320         *
     321         * @param int|boolean The UNIX timestamp when the scheduled event will next occur, or false if not found.
     322         * @param string $hook Action hook to execute when cron is run.
     323         * @param array $args Arguments to be passed to the callback function. Used for deduplicating events.
     324         */
     325        return apply_filters( 'next_scheduled', $next, $hook, $args );
    232326}
    233327
    234328/**
    … …  
    237331 * @since 2.1.0
    238332 *
    239333 * @param int $gmt_time Optional. Unix timestamp. Default 0 (current time is used).
     334 * @return null|WP_Error|array Null when cron could not be spawned, because it is not needed to run.
     335 * When cron runs, return the result of {@see wp_remote_post}
    240336 */
    241337function spawn_cron( $gmt_time = 0 ) {
    242338        if ( ! $gmt_time )
    … …  
    326422                )
    327423        ), $doing_wp_cron );
    328424
    329         wp_remote_post( $cron_request['url'], $cron_request['args'] );
     425        return wp_remote_post( $cron_request['url'], $cron_request['args'] );
    330426}
    331427
    332428/**
    … …  
    333429 * Run scheduled callbacks or spawn cron for all scheduled events.
    334430 *
    335431 * @since 2.1.0
     432 * @return array Array of spawn_cron() results for any cron jobs that were run, with cron timestamps as keys.
    336433 */
    337434function wp_cron() {
    338435        // Prevent infinite loops caused by lack of wp-cron.php
    339436        if ( strpos($_SERVER['REQUEST_URI'], '/wp-cron.php') !== false || ( defined('DISABLE_WP_CRON') && DISABLE_WP_CRON ) )
    340                 return;
     437                return array();
    341438
    342439        if ( false === $crons = _get_cron_array() )
    343                 return;
     440                return array();
    344441
    345442        $gmt_time = microtime( true );
    346443        $keys = array_keys( $crons );
    347444        if ( isset($keys[0]) && $keys[0] > $gmt_time )
    348                 return;
     445                return array();
    349446
     447        $results = array();
    350448        $schedules = wp_get_schedules();
    351449        foreach ( $crons as $timestamp => $cronhooks ) {
    352450                if ( $timestamp > $gmt_time ) break;
    … …  
    353451                foreach ( (array) $cronhooks as $hook => $args ) {
    354452                        if ( isset($schedules[$hook]['callback']) && !call_user_func( $schedules[$hook]['callback'] ) )
    355453                                continue;
    356                         spawn_cron( $gmt_time );
     454                        $results[$timestamp] = spawn_cron( $gmt_time );
    357455                        break 2;
    358456                }
    359457        }
     458        return $results;
    360459}
    361460
    362461/**
    … …  
    417516function wp_get_schedule($hook, $args = array()) {
    418517        $crons = _get_cron_array();
    419518        $key = md5(serialize($args));
    420         if ( empty($crons) )
    421                 return false;
    422         foreach ( $crons as $timestamp => $cron ) {
    423                 if ( isset( $cron[$hook][$key] ) )
    424                         return $cron[$hook][$key]['schedule'];
     519        $schedule = false;
     520        if ( ! empty($crons) ) {
     521                foreach ( $crons as $timestamp => $cron ) {
     522                        if ( isset( $cron[$hook][$key] ) ) {
     523                                $schedule = $cron[$hook][$key]['schedule'];
     524                                break;
     525                        }
     526                }
    425527        }
    426         return false;
     528
     529        /**
     530         * Filter the schedule for a hook.
     531         *
     532         * @param string|boolean $schedule Schedule for the hook. False if not found.
     533         * @param string $hook Action hook to execute when cron is run.
     534         * @param array $args Optional. Arguments to pass to the hook's callback function.
     535         */
     536        return apply_filters( 'get_schedule', $schedule, $hook, $args );
    427537}
    428538
    429539//
    … …  
    458568 * @access private
    459569 *
    460570 * @param array $cron Cron info array from {@link _get_cron_array()}.
     571 * @return bool Whether the update of the cron option succeeded (according to {@see update_option})
    461572 */
    462573function _set_cron_array($cron) {
    463574        $cron['version'] = 2;
    464         update_option( 'cron', $cron );
     575        return update_option( 'cron', $cron );
    465576}
    466577
    467578/**