wp_die( string|WP_Error $message = '', string|int $title = '', string|array|int $args = array() )
Kills WordPress execution and displays HTML page with an error message.
Contents
Description
This function complements the die()
PHP function. The difference is that HTML will be displayed to the user. It is recommended to use this function only when the execution should not continue any further. It is not recommended to call this function very often, and try to handle as many errors as possible silently or more gracefully.
As a shorthand, the desired HTTP response code may be passed as an integer to the $title
parameter (the default title would apply) or the $args
parameter.
Parameters
-
$message
string|WP_Error Optional -
Error message. If this is a WP_Error object, and not an Ajax or XML-RPC request, the error's messages are used.
Default:
''
-
$title
string|int Optional -
Error title. If
$message
is aWP_Error
object, error data with the key'title'
may be used to specify the title.
If$title
is an integer, then it is treated as the response code.
Default:
''
-
$args
string|array|int Optional -
Arguments to control behavior. If
$args
is an integer, then it is treated as the response code.
response
intThe HTTP response code. Default 200 for Ajax requests, 500 otherwise.link_url
stringA URL to include a link to. Only works in combination with $link_text.
Default empty string.link_text
stringA label for the link to include. Only works in combination with $link_url.
Default empty string.back_link
boolWhether to include a link to go back. Default false.text_direction
stringThe text direction. This is only useful internally, when WordPress is still loading and the site's locale is not set up yet. Accepts'rtl'
and'ltr'
.
Default is the value of is_rtl() .charset
stringCharacter set of the HTML output. Default'utf-8'
.code
stringError code to use. Default is'wp_die'
, or the main error code if $message is a WP_Error.exit
boolWhether to exit the process after completion. Default true.
Default:
array()
More Information
You can add a WP_Error object. If you’ve done so, you can add $data['title'] to the error object and it will automatically be taken as (default/overwriteable) title for the die page
Source
File: wp-includes/functions.php
.
View all references
function wp_die( $message = '', $title = '', $args = array() ) {
global $wp_query;
if ( is_int( $args ) ) {
$args = array( 'response' => $args );
} elseif ( is_int( $title ) ) {
$args = array( 'response' => $title );
$title = '';
}
if ( wp_doing_ajax() ) {
/**
* Filters the callback for killing WordPress execution for Ajax requests.
*
* @since 3.4.0
*
* @param callable $callback Callback function name.
*/
$callback = apply_filters( 'wp_die_ajax_handler', '_ajax_wp_die_handler' );
} elseif ( wp_is_json_request() ) {
/**
* Filters the callback for killing WordPress execution for JSON requests.
*
* @since 5.1.0
*
* @param callable $callback Callback function name.
*/
$callback = apply_filters( 'wp_die_json_handler', '_json_wp_die_handler' );
} elseif ( defined( 'REST_REQUEST' ) && REST_REQUEST && wp_is_jsonp_request() ) {
/**
* Filters the callback for killing WordPress execution for JSONP REST requests.
*
* @since 5.2.0
*
* @param callable $callback Callback function name.
*/
$callback = apply_filters( 'wp_die_jsonp_handler', '_jsonp_wp_die_handler' );
} elseif ( defined( 'XMLRPC_REQUEST' ) && XMLRPC_REQUEST ) {
/**
* Filters the callback for killing WordPress execution for XML-RPC requests.
*
* @since 3.4.0
*
* @param callable $callback Callback function name.
*/
$callback = apply_filters( 'wp_die_xmlrpc_handler', '_xmlrpc_wp_die_handler' );
} elseif ( wp_is_xml_request()
|| isset( $wp_query ) &&
( function_exists( 'is_feed' ) && is_feed()
|| function_exists( 'is_comment_feed' ) && is_comment_feed()
|| function_exists( 'is_trackback' ) && is_trackback() ) ) {
/**
* Filters the callback for killing WordPress execution for XML requests.
*
* @since 5.2.0
*
* @param callable $callback Callback function name.
*/
$callback = apply_filters( 'wp_die_xml_handler', '_xml_wp_die_handler' );
} else {
/**
* Filters the callback for killing WordPress execution for all non-Ajax, non-JSON, non-XML requests.
*
* @since 3.0.0
*
* @param callable $callback Callback function name.
*/
$callback = apply_filters( 'wp_die_handler', '_default_wp_die_handler' );
}
call_user_func( $callback, $message, $title, $args );
}
Hooks
-
apply_filters( 'wp_die_ajax_handler',
callable $callback ) -
Filters the callback for killing WordPress execution for Ajax requests.
-
apply_filters( 'wp_die_handler',
callable $callback ) -
Filters the callback for killing WordPress execution for all non-Ajax, non-JSON, non-XML requests.
-
apply_filters( 'wp_die_jsonp_handler',
callable $callback ) -
Filters the callback for killing WordPress execution for JSONP REST requests.
-
apply_filters( 'wp_die_json_handler',
callable $callback ) -
Filters the callback for killing WordPress execution for JSON requests.
-
apply_filters( 'wp_die_xmlrpc_handler',
callable $callback ) -
Filters the callback for killing WordPress execution for XML-RPC requests.
-
apply_filters( 'wp_die_xml_handler',
callable $callback ) -
Filters the callback for killing WordPress execution for XML requests.
Changelog
Version | Description |
---|---|
5.5.0 | The $text_direction argument has a priority over get_language_attributes() in the default handler. |
5.3.0 | The $charset argument was added. |
5.1.0 | The $link_url , $link_text , and $exit arguments were added. |
4.1.0 | The $title and $args parameters were changed to optionally accept an integer to be used as the response code. |
2.0.4 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
Test to see what is in the
$post
variable in a filter:You can use
wp_die()
at the end of function to close an AJAX request. You receive HTML code for example and you can use it by JS. But consider usingwp_send_json()
instead if you need to return a correct string value to an AJAX request. (I assume you can return also arrays or objects). Codex indicates thatwp_send_json()
useswp_die()
.