do_parse_request │ filter-hook │ WP 3.5.0

Allows you to completely disable processing of the current request.

The hook's behavior was improved in version 6.0; see the note.

The hook fires in WP::parse_request(). If it returns false, the function does not parse the current request parameters and also returns false. This in turn cancels the main database query, 404 handling, and setup of global query variables:

class WP {
	// ...

	public function main( $query_args = '' ) {
		$this->init();

		$parsed = $this->parse_request( $query_args );

		$this->send_headers();

		if ( $parsed ) {
			$this->query_posts();
			$this->handle_404();
			$this->register_globals();
		}

		do_action_ref_array( 'wp', array( &$this ) );
	}

	// ...
}

Usage

add_filter( 'do_parse_request', 'wp_kama_do_parse_request_filter', 10, 3 );

/**
 * Function for `do_parse_request` filter-hook.
 * 
 * @param bool         $bool             Whether or not to parse the request.
 * @param WP           $wp               Current WordPress environment instance.
 * @param array|string $extra_query_vars Extra passed query variables.
 *
 * @return bool
 */
function wp_kama_do_parse_request_filter( $bool, $wp, $extra_query_vars ){

	// filter...
	return $bool;
}

$bool(true|false)

Whether to parse the request.
Default: true

$wp(WP)

Current WordPress environment instance, an instance of the WP class.

$extra_query_vars(array|string)

Additional query variables.

Examples

#1 What happens when current request processing is simply disabled

add_filter( 'do_parse_request', '__return_false' );

After this hook is added:

• The current URL is not processed in any way, including rewrite and pretty permalink rules. Accordingly, no WordPress query variables are set; see get_query_var().
• The basic WordPress query is not run.
• Every site URL returns a 200 response and uses the index.php template file.
• The request and parse_request hooks do not fire.

Thus, nearly everything WordPress normally does with a front-end request is disabled.

After disabling it, the URL must be processed manually, a 404 status returned when necessary, and a template file selected.

This behavior can be useful when URLs need to be processed in a radically different way.

#2 Filter usage example

If processing of the current URL should be completely disabled and replaced with custom handling, the following code can serve as a foundation:

add_filter( 'do_parse_request', 'wp_kama_add_custom_query', 10, 3 );

function wp_kama_add_custom_query( $do_parse, $wp, $extra_query_vars ) {

	if ( str_starts_with( $_SERVER['REQUEST_URI'], '/myroute' ) ) {

		add_action( 'wp', 'my_parse_request' );

		return false;
	}

	return $do_parse;
}

function my_parse_request( $wp ){

	// Perform the required work.
	// die( print_r( $wp ) );
}

After this code is added, WordPress does not process a URL such as https://example.com/myroute/foo..., allowing it to be handled manually in my_parse_request().