wp_redirect() │ WP 1.5.1

Redirects to the specified URL, you can specify the redirect status (301, 302...).

For the function to work correctly, you need to specify the full URL:

http://www.example.com/blog/post_name
ftp://ftp.example.com/users/h/harriet/www/

wp_redirect() does not automatically terminate execution, so you should always also call exit;:

wp_redirect( $url );
exit;

You can also exit with a check - this check can be modified on the hook wp_redirect:

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

In WordPress, there is a similar function for redirection: wp_safe_redirect(). It differs in that it checks the provided address and compares it with a list of allowed hosts; if the host is not found, the redirection does not occur. The "whitelist" can be managed using the filter allowed_redirect_hosts.

IMPORTANT! wp_safe_redirect() is recommended to be used always, especially when $url is provided by the user.

Whereas this function should be used when we intentionally want to redirect the user to another site, usually here $url is hardcoded in the code, not provided by the user.

// we do not know for sure if the specified URL is our site or not and we need to avoid unexpected redirects.
wp_safe_redirect( $url );

// we intentionally redirect to another site, the URL is hardcoded.
wp_redirect( 'https://example.com/some/page' );

The function will trigger a PHP error (Output already started. Headers not sent.) if used after headers have been sent. That is, if we call the function in a theme file responsible for outputting content, the function will not work. In such cases, as an alternative, you can use a redirect to javascript: document.location.href = 'http://example.com';

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

wp_redirect

wp_redirect_status

x_redirect_by

Returns

true|false.

Usage

wp_redirect( $location, $status );
exit;

$location(string) (required)

URL of the page to which you need to redirect.

$status(number)

Redirect status code (HTTP status code):

300 — Multiple Choices;
301 — Moved Permanently;
302 — Found;
303 — See Other;
304 — Not Modified;
305 — Use Proxy;
306 — (reserved);
307 — Temporary Redirect.

Status 302 means a temporary change of address. If you need to indicate to the robot that the page has moved permanently, use status — 301. The full list of statuses can be found here.

Default: 302

$x_redirect_by (string) (WP 5.1)

Identifier of who made the redirect. Allows plugins to identify themselves in redirects.

The string specified here will be added to the X-Redirect-By header of the redirect response. E.g., X-Redirect-By: WordPress.

Default: 'WordPress'

Examples

#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' );

#2 Internal redirect

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

wp_redirect( home_url() );
exit;

#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;

#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;
	}

} );

#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() wp redirect` code ^{WP 6.8.1}

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;
}

wp_redirect() │ WP 1.5.1

Hooks from the function

Returns

Usage

Examples

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

#2 Internal redirect

#3 External redirect

#4 Redirect via hook template_redirect

#5 Add the nocache_headers() for temporary redirects

Notes

Changelog

wp_redirect() wp redirect code WP 6.8.1

Related Functions

redirect

Supporting (helper utility auxiliary)

Uncategorized

#4 Redirect via hook `template_redirect`

`wp_redirect() wp redirect` code ^{WP 6.8.1}