wp_redirect()
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.
Hooks from the function
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. |