WP_Async_Task()

Description #

Source #

abstract class WP_Async_Task {
 
    /**
     * Constant identifier for a task that should be available to logged-in users
     *
     * See constructor documentation for more details.
     */
    const LOGGED_IN = 1;
 
    /**
     * Constant identifier for a task that should be available to logged-out users
     *
     * See constructor documentation for more details.
     */
    const LOGGED_OUT = 2;
 
    /**
     * Constant identifier for a task that should be available to all users regardless of auth status
     *
     * See constructor documentation for more details.
     */
    const BOTH = 3;
 
    /**
     * This is the argument count for the main action set in the constructor. It
     * is set to an arbitrarily high value of twenty, but can be overridden if
     * necessary
     *
     * @var int
     */
    protected $argument_count = 20;
 
    /**
     * Priority to fire intermediate action.
     *
     * @var int
     */
    protected $priority = 10;
 
    /**
     * @var string
     */
    protected $action;
 
    /**
     * @var array
     */
    protected $_body_data;
 
    /**
     * Constructor to wire up the necessary actions
     *
     * Which hooks the asynchronous postback happens on can be set by the
     * $auth_level parameter. There are essentially three options: logged in users
     * only, logged out users only, or both. Set this when you instantiate an
     * object by using one of the three class constants to do so:
     *  - LOGGED_IN
     *  - LOGGED_OUT
     *  - BOTH
     * $auth_level defaults to BOTH
     *
     * @throws Exception If the class' $action value hasn't been set
     *
     * @param int $auth_level The authentication level to use (see above)
     */
    public function __construct( $auth_level = self::BOTH ) {
        if ( empty( $this->action ) ) {
            throw new Exception( 'Action not defined for class ' . __CLASS__ );
        }
        add_action( $this->action, array( $this, 'launch' ), (int) $this->priority, (int) $this->argument_count );
        if ( $auth_level & self::LOGGED_IN ) {
            add_action( "admin_post_wp_async_$this->action", array( $this, 'handle_postback' ) );
        }
        if ( $auth_level & self::LOGGED_OUT ) {
            add_action( "admin_post_nopriv_wp_async_$this->action", array( $this, 'handle_postback' ) );
        }
    }
 
    /**
     * Add the shutdown action for launching the real postback if we don't
     * get an exception thrown by prepare_data().
     *
     * @uses func_get_args() To grab any arguments passed by the action
     */
    public function launch() {
        $data = func_get_args();
        try {
            $data = $this->prepare_data( $data );
        } catch ( Exception $e ) {
            return;
        }
 
        $data['action'] = "wp_async_$this->action";
        $data['_nonce'] = $this->create_async_nonce();
 
        $this->_body_data = $data;
 
        if ( ! has_action( 'shutdown', array( $this, 'launch_on_shutdown' ) ) ) {
            add_action( 'shutdown', array( $this, 'launch_on_shutdown' ) );
        }
    }
 
    /**
     * Launch the request on the WordPress shutdown hook
     *
     * On VIP we got into data races due to the postback sometimes completing
     * faster than the data could propogate to the database server cluster.
     * This made WordPress get empty data sets from the database without
     * failing. On their advice, we're moving the actual firing of the async
     * postback to the shutdown hook. Supposedly that will ensure that the
     * data at least has time to get into the object cache.
     *
     * @uses $_COOKIE        To send a cookie header for async postback
     * @uses apply_filters()
     * @uses admin_url()
     * @uses wp_remote_post()
     */
    public function launch_on_shutdown() {
        if ( ! empty( $this->_body_data ) ) {
            $cookies = array();
            foreach ( $_COOKIE as $name => $value ) {
                $cookies[] = "$name=" . urlencode( is_array( $value ) ? serialize( $value ) : $value );
            }
 
            $request_args = array(
                'timeout'   => 0.01,
                'blocking'  => false,
                'sslverify' => apply_filters( 'https_local_ssl_verify', true ),
                'body'      => $this->_body_data,
                'headers'   => array(
                    'cookie' => implode( '; ', $cookies ),
                ),
                'compress'  => true,
            );
 
            $url = admin_url( 'admin-post.php' );
 
            wp_remote_post( $url, $request_args );
        }
    }
 
    /**
     * Verify the postback is valid, then fire any scheduled events.
     *
     * @uses is_user_logged_in()
     * @uses add_filter()
     * @uses wp_die()
     */
    public function handle_postback() {
        $nonce = ap_sanitize_unslash( '_nonce', 'r' );
 
        if ( ! empty( $nonce ) && false !== $this->verify_async_nonce( $nonce ) ) {
            if ( ! is_user_logged_in() ) {
                $this->action = "nopriv_$this->action";
            }
            $this->run_action();
        }
 
        add_filter(
            'wp_die_handler',
            function() {
                die();
            }
        );
        wp_die();
    }
 
    /**
     * Create a random, one time use token.
     *
     * Based entirely on wp_create_nonce() but does not tie the nonce to the
     * current logged-in user.
     *
     * @uses wp_nonce_tick()
     * @uses wp_hash()
     *
     * @return string The one-time use token
     */
    protected function create_async_nonce() {
        $action = $this->get_nonce_action();
        $i      = wp_nonce_tick();
 
        return substr( wp_hash( $i . $action . get_class( $this ), 'nonce' ), - 12, 10 );
    }
 
    /**
     * Verify that the correct nonce was used within the time limit.
     *
     * @uses wp_nonce_tick()
     * @uses wp_hash()
     *
     * @param string $nonce Nonce to be verified
     *
     * @return bool Whether the nonce check passed or failed
     */
    protected function verify_async_nonce( $nonce ) {
        $action = $this->get_nonce_action();
        $i      = wp_nonce_tick();
 
        // Nonce generated 0-12 hours ago
        if ( substr( wp_hash( $i . $action . get_class( $this ), 'nonce' ), - 12, 10 ) == $nonce ) {
            return 1;
        }
 
        // Nonce generated 12-24 hours ago
        if ( substr( wp_hash( ( $i - 1 ) . $action . get_class( $this ), 'nonce' ), - 12, 10 ) == $nonce ) {
            return 2;
        }
 
        // Invalid nonce
        return false;
    }
 
    /**
     * Get a nonce action based on the $action property of the class
     *
     * @return string The nonce action for the current instance
     */
    protected function get_nonce_action() {
        $action = $this->action;
        if ( substr( $action, 0, 7 ) === 'nopriv_' ) {
            $action = substr( $action, 7 );
        }
        $action = "wp_async_$action";
        return $action;
    }
 
    /**
     * Prepare any data to be passed to the asynchronous postback
     *
     * The array this function receives will be a numerically keyed array from
     * func_get_args(). It is expected that you will return an associative array
     * so that the $_POST values used in the asynchronous call will make sense.
     *
     * The array you send back may or may not have anything to do with the data
     * passed into this method. It all depends on the implementation details and
     * what data is needed in the asynchronous postback.
     *
     * Do not set values for 'action' or '_nonce', as those will get overwritten
     * later in launch().
     *
     * @throws Exception If the postback should not occur for any reason
     *
     * @param array $data The raw data received by the launch method
     *
     * @return array The prepared data
     */
    abstract protected function prepare_data( $data );
 
    /**
     * Run the do_action function for the asynchronous postback.
     *
     * This method needs to fetch and sanitize any and all data from the $_POST
     * superglobal and provide them to the do_action call.
     *
     * The action should be constructed as "wp_async_task_$this->action"
     */
    abstract protected function run_action();
 
}