wp_redirect() │ WP 1.5.1

Redirects to another page.

Note: wp_redirect() does not exit automatically, and should almost always be followed by a call to exit;:

wp_redirect( $url );
exit;

Exiting can also be selectively manipulated by using wp_redirect() as a conditional in conjunction with the wp_redirect and wp_redirect_status filters:

if ( wp_redirect( $url ) ) {
	exit;
}

Pluggable function — this function can be replaced from a plugin. It means that this function is defined (works) only after all plugins are loaded (included), but before this moment this function has not defined. Therefore, you cannot call this and all functions depended on this function directly from a plugin code. They need to be called on plugins_loaded hook or later, for example on init hook.

Function replacement (override) — in must-use or regular plugin you can create a function with the same name, then it will replace this function.

Used By: wp_safe_redirect()
Hooks from the function

Return

true|false. False if the redirect was canceled, true otherwise.

Usage

wp_redirect( $location, $status, $x_redirect_by );
$location(string) (required)
The path or URL to redirect to.
$status(int)
HTTP response status code to use. (Moved Temporarily).
Default: '302'
$x_redirect_by(string|false)
The application doing the redirect or false to omit.
Default: 'WordPress'

Examples

1

#1 Use this function for hard-coded URLs only!

wp_redirect() does not validate that the $location is a reference to the current host. This means that this function is vulnerable to open redirects if you pass it a $location supplied by the user.

For this reason, it is best practice to always use wp_safe_redirect() instead, since it will use wp_validate_redirect() to ensure that the $location refers to the current host. Only use wp_redirect() when you are specifically trying to redirect to another site, and then you can hard-code the URL.

// We don't know for sure whether this is a URL for this site,
// so we use wp_safe_redirect() to avoid an open redirect.
wp_safe_redirect( $url );

// We are trying to redirect to another site, using a hard-coded URL.
wp_redirect( 'https://example.com/some/page' );
0

#2 Internal redirect

An example of a redirect to the main page of the site:

wp_redirect( home_url() );
exit;
0

#3 External redirect

The redirect can also be external. In the example, we set the redirect status code to 301, which means that this page (the page from which we redirect) is moved forever:

wp_redirect( 'http://www.example.com', 301 );
exit;
0

#4 Redirect via hook template_redirect

This example shows how in WordPress to redirect the user to another page, with the ability to check what page of the site he is on now. Use template_redirect action for this purpose. That is, at the moment of redirection, WP has already detected the displayed page.

For example, let's say we need to redirect the user if he visited a page with ID 10:

add_action( 'template_redirect', function() {

	if( is_page(10) ){
		wp_redirect( 'http://example.org/path/to/subscribe', 301 );
		exit;
	}

} );
0

#5 Add the nocache_headers() for temporary redirects

Add a call to nocache_headers() before redirect when redirects imply that they will not be in the future. This will make sure that the browser will not cache the redirect itself (caching can happen even if a 302 redirect is set).

For example, this can be problematic when using a redirect to a login page when trying to access protected content, because a visitor might log in and find that when they try to go back to the page they tried to go to, they still end up on the login page because the redirect has been cached by the browser.

nocache_headers();
wp_redirect( $url, 302 );
exit;

Notes

  • Global. true|false. $is_IIS

Changelog

Since 1.5.1 Introduced.
Since 5.1.0 The $x_redirect_by parameter was added.
Since 5.4.0 On invalid status codes, wp_die() is called.

wp_redirect() code WP 6.6.2

wp-includes/pluggable.php 
function wp_redirect( $location, $status = 302, $x_redirect_by = 'WordPress' ) {
	global $is_IIS;

	/**
	 * Filters the redirect location.
	 *
	 * @since 2.1.0
	 *
	 * @param string $location The path or URL to redirect to.
	 * @param int    $status   The HTTP response status code to use.
	 */
	$location = apply_filters( 'wp_redirect', $location, $status );

	/**
	 * Filters the redirect HTTP response status code to use.
	 *
	 * @since 2.3.0
	 *
	 * @param int    $status   The HTTP response status code to use.
	 * @param string $location The path or URL to redirect to.
	 */
	$status = apply_filters( 'wp_redirect_status', $status, $location );

	if ( ! $location ) {
		return false;
	}

	if ( $status < 300 || 399 < $status ) {
		wp_die( __( 'HTTP redirect status code must be a redirection code, 3xx.' ) );
	}

	$location = wp_sanitize_redirect( $location );

	if ( ! $is_IIS && 'cgi-fcgi' !== PHP_SAPI ) {
		status_header( $status ); // This causes problems on IIS and some FastCGI setups.
	}

	/**
	 * Filters the X-Redirect-By header.
	 *
	 * Allows applications to identify themselves when they're doing a redirect.
	 *
	 * @since 5.1.0
	 *
	 * @param string|false $x_redirect_by The application doing the redirect or false to omit the header.
	 * @param int          $status        Status code to use.
	 * @param string       $location      The path to redirect to.
	 */
	$x_redirect_by = apply_filters( 'x_redirect_by', $x_redirect_by, $status, $location );
	if ( is_string( $x_redirect_by ) ) {
		header( "X-Redirect-By: $x_redirect_by" );
	}

	header( "Location: $location", true, $status );

	return true;
}

redirect

Supporting (helper utility auxiliary)

Uncategorized