wp_die( string|WP_Error $message = '', string|int $title = '', string|array|int $args = array() )

Kill WordPress execution and display HTML message with error message.

Contents

Description 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 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 value: ''

$title

(string|int) (Optional) Error title. If $message is a WP_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 value: ''

$args

(string|array|int) (Optional) Arguments to control behavior. If $args is an integer, then it is treated as the response code.

  • 'response'
    (int) The HTTP response code. Default 200 for Ajax requests, 500 otherwise.
  • 'link_url'
    (string) A URL to include a link to. Only works in combination with $link_text. Default empty string.
  • 'link_text'
    (string) A label for the link to include. Only works in combination with $link_url. Default empty string.
  • 'back_link'
    (bool) Whether to include a link to go back. Default false.
  • 'text_direction'
    (string) The text direction. This is only useful internally, when WordPress is still loading and the site's locale is not set up yet. Accepts 'rtl'. Default is the value of is_rtl().
  • 'code'
    (string) Error code to use. Default is 'wp_die', or the main error code if $message is a WP_Error.
  • 'exit'
    (bool) Whether to exit the process after completion. Default true.

Default value: array()

Top ↑

Source Source

File: wp-includes/functions.php 

function wp_die( $message = '', $title = '', $args = array() ) {

	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 $function Callback function name.
		 */
		$function = 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 $function Callback function name.
		 */
		$function = apply_filters( 'wp_die_json_handler', '_json_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 $function Callback function name.
		 */
		$function = apply_filters( 'wp_die_xmlrpc_handler', '_xmlrpc_wp_die_handler' );
	} else {
		/**
		 * Filters the callback for killing WordPress execution for all non-Ajax, non-XML-RPC requests.
		 *
		 * @since 3.0.0
		 *
		 * @param callable $function Callback function name.
		 */
		$function = apply_filters( 'wp_die_handler', '_default_wp_die_handler' );
	}

	call_user_func( $function, $message, $title, $args );
}

Expand full source code Collapse full source code View on Trac

Top ↑

Changelog Changelog

Changelog
Version Description
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.

Top ↑

Top ↑

Uses Uses

Uses
Uses Description
wp-includes/functions.php: wp_die_json_handler

Filters the callback for killing WordPress execution for JSON requests.
wp-includes/load.php: wp_is_json_request()

Checks whether current request is a JSON request, or is expecting a JSON response.
wp-includes/load.php: wp_doing_ajax()

Determines whether the current request is a WordPress Ajax request.
wp-includes/functions.php: wp_die_ajax_handler

Filters the callback for killing WordPress execution for Ajax requests.
wp-includes/functions.php: wp_die_xmlrpc_handler

Filters the callback for killing WordPress execution for XML-RPC requests.
wp-includes/functions.php: wp_die_handler

Filters the callback for killing WordPress execution for all non-Ajax, non-XML-RPC requests.
wp-includes/plugin.php: apply_filters()

Call the functions added to a filter hook.
Show 2 more uses Hide more uses

Top ↑

Used By Used By

Used By
Used By Description
wp-admin/includes/user.php: _wp_personal_data_export_page()

Personal data export.
wp-admin/includes/user.php: _wp_personal_data_removal_page()

Personal data anonymization.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::handle_load_themes_request()

Load themes into the theme browsing/installation UI.
wp-admin/press-this.php: wp_load_press_this()
wp-includes/comment.php: wp_check_comment_flood()

Checks whether comment flooding is occurring.
wp-admin/includes/ajax-actions.php: wp_ajax_get_post_thumbnail_html()

Ajax handler for retrieving HTML for the featured image.
wp-admin/includes/ajax-actions.php: wp_ajax_delete_inactive_widgets()

Ajax handler for removing inactive widgets.
wp-includes/class-wp-customize-nav-menus.php: WP_Customize_Nav_Menus::ajax_load_available_items()

Ajax handler for loading available menu items.
wp-includes/class-wp-customize-nav-menus.php: WP_Customize_Nav_Menus::ajax_search_available_items()

Ajax handler for searching available menu items.
wp-admin/includes/media.php: wp_media_attach_action()

Encapsulate logic for Attach/Detach actions
wp-login.php: retrieve_password()

Handles sending password retrieval email to user.
wp-admin/includes/class-file-upload-upgrader.php: File_Upload_Upgrader::__construct()

Construct the upgrader for a form.
wp-admin/includes/class-wp-screen.php: WP_Screen::get()

Fetches a screen object.
wp-admin/includes/theme-install.php: install_theme_information()

Display theme information in dialog box form.
wp-admin/includes/ms.php: _access_denied_splash()

Displays an access denied message when a user tries to view a site’s dashboard they do not have access to.
wp-admin/includes/ms.php: check_upload_size()

Determine if uploaded file exceeds space quota.
wp-admin/includes/class-wp-theme-install-list-table.php: WP_Theme_Install_List_Table::prepare_items()
wp-admin/includes/plugin-install.php: install_plugin_information()

Display plugin information in dialog box form.
wp-admin/includes/user.php: edit_user()

Edit user settings based on contents of $_POST
wp-admin/includes/post.php: post_preview()

Saves a draft or manually autosaves for the purpose of showing a post preview.
wp-admin/includes/post.php: write_post()

Calls wp_write_post() and handles the errors.
wp-admin/includes/post.php: edit_post()

Update an existing post with values provided in $_POST.
wp-admin/includes/post.php: bulk_edit_posts()

Process the post data for the bulk editing of posts.
wp-admin/includes/ajax-actions.php: wp_ajax_save_widget()

Ajax handler for saving a widget.
wp-admin/includes/ajax-actions.php: wp_ajax_upload_attachment()

Ajax handler for uploading attachments
wp-admin/includes/ajax-actions.php: wp_ajax_image_editor()

Ajax handler for image editing.
wp-admin/includes/ajax-actions.php: wp_ajax_set_post_thumbnail()

Ajax handler for setting the featured image.
wp-admin/includes/ajax-actions.php: wp_ajax_date_format()

Ajax handler for date formatting.
wp-admin/includes/ajax-actions.php: wp_ajax_time_format()

Ajax handler for time formatting.
wp-admin/includes/ajax-actions.php: wp_ajax_wp_remove_post_lock()

Ajax handler for removing a post lock.
wp-admin/includes/ajax-actions.php: wp_ajax_dismiss_wp_pointer()

Ajax handler for dismissing a WordPress pointer.
wp-admin/includes/ajax-actions.php: wp_ajax_add_menu_item()

Ajax handler for adding a menu item.
wp-admin/includes/ajax-actions.php: wp_ajax_add_meta()

Ajax handler for adding meta.
wp-admin/includes/ajax-actions.php: wp_ajax_add_user()

Ajax handler for adding a user.
wp-admin/includes/ajax-actions.php: wp_ajax_closed_postboxes()

Ajax handler for closed post boxes.
wp-admin/includes/ajax-actions.php: wp_ajax_hidden_columns()

Ajax handler for hidden columns.
wp-admin/includes/ajax-actions.php: wp_ajax_update_welcome_panel()

Ajax handler for updating whether to display the welcome panel.
wp-admin/includes/ajax-actions.php: wp_ajax_menu_get_metabox()

Ajax handler for retrieving menu meta boxes.
wp-admin/includes/ajax-actions.php: wp_ajax_wp_link_ajax()

Ajax handler for internal linking.
wp-admin/includes/ajax-actions.php: wp_ajax_menu_locations_save()

Ajax handler for menu locations save.
wp-admin/includes/ajax-actions.php: wp_ajax_meta_box_order()

Ajax handler for saving the meta box order.
wp-admin/includes/ajax-actions.php: wp_ajax_menu_quick_search()

Ajax handler for menu quick searching.
wp-admin/includes/ajax-actions.php: wp_ajax_get_permalink()

Ajax handler to retrieve a permalink.
wp-admin/includes/ajax-actions.php: wp_ajax_sample_permalink()

Ajax handler to retrieve a sample permalink.
wp-admin/includes/ajax-actions.php: wp_ajax_inline_save()

Ajax handler for Quick Edit saving a post from a list table.
wp-admin/includes/ajax-actions.php: wp_ajax_inline_save_tax()

Ajax handler for quick edit saving for a term.
wp-admin/includes/ajax-actions.php: wp_ajax_widgets_order()

Ajax handler for saving the widgets order.
wp-admin/includes/ajax-actions.php: wp_ajax_dashboard_widgets()

Ajax handler for dashboard widgets.
wp-admin/includes/ajax-actions.php: wp_ajax_logged_in()

Ajax handler for Customizer preview logged-in status.
wp-admin/includes/ajax-actions.php: _wp_ajax_add_hierarchical_term()

Ajax handler for adding a hierarchical term.
wp-admin/includes/ajax-actions.php: wp_ajax_delete_comment()

Ajax handler for deleting a comment.
wp-admin/includes/ajax-actions.php: wp_ajax_delete_tag()

Ajax handler for deleting a tag.
wp-admin/includes/ajax-actions.php: wp_ajax_delete_link()

Ajax handler for deleting a link.
wp-admin/includes/ajax-actions.php: wp_ajax_delete_meta()

Ajax handler for deleting meta.
wp-admin/includes/ajax-actions.php: wp_ajax_delete_post()

Ajax handler for deleting a post.
wp-admin/includes/ajax-actions.php: wp_ajax_trash_post()

Ajax handler for sending a post to the trash.
wp-admin/includes/ajax-actions.php: wp_ajax_delete_page()

Ajax handler to delete a page.
wp-admin/includes/ajax-actions.php: wp_ajax_dim_comment()

Ajax handler to dim a comment.
wp-admin/includes/ajax-actions.php: wp_ajax_add_link_category()

Ajax handler for adding a link category.
wp-admin/includes/ajax-actions.php: wp_ajax_add_tag()

Ajax handler to add a tag.
wp-admin/includes/ajax-actions.php: wp_ajax_get_tagcloud()

Ajax handler for getting a tagcloud.
wp-admin/includes/ajax-actions.php: wp_ajax_get_comments()

Ajax handler for getting comments.
wp-admin/includes/ajax-actions.php: wp_ajax_replyto_comment()

Ajax handler for replying to a comment.
wp-admin/includes/ajax-actions.php: wp_ajax_edit_comment()

Ajax handler for editing a comment.
wp-admin/includes/ajax-actions.php: wp_ajax_fetch_list()

Ajax handler for fetching a list table.
wp-admin/includes/ajax-actions.php: wp_ajax_ajax_tag_search()

Ajax handler for tag search.
wp-admin/includes/ajax-actions.php: wp_ajax_wp_compression_test()

Ajax handler for compression testing.
wp-admin/includes/ajax-actions.php: wp_ajax_imgedit_preview()

Ajax handler for image editor previews.
wp-admin/includes/ajax-actions.php: wp_ajax_oembed_cache()

Ajax handler for oEmbed caching.
wp-admin/includes/ajax-actions.php: wp_ajax_autocomplete_user()

Ajax handler for user autocomplete.
wp-admin/includes/bookmark.php: wp_link_manager_disabled_message()

Outputs the ‘disabled’ message for the WordPress Link Manager.
wp-admin/includes/bookmark.php: edit_link()

Updates or inserts a link using values provided in $_POST.
wp-admin/includes/ms-deprecated.php: wpmu_checkAvailableSpace()

Determines if the available space defined by the admin has been exceeded by the user.
wp-admin/includes/class-wp-terms-list-table.php: WP_Terms_List_Table::__construct()

Constructor.
wp-admin/includes/file.php: validate_file_to_edit()

Makes sure that the file that was requested to be edited is allowed to be edited.
wp-admin/includes/comment.php: edit_comment()

Update a comment with values provided in $_POST.
wp-admin/custom-header.php: Custom_Image_Header::step_2()

Display second step of custom header image page.
wp-admin/custom-header.php: Custom_Image_Header::step_2_manage_upload()

Upload the file to be cropped in the second step.
wp-admin/custom-header.php: Custom_Image_Header::step_3()

Display third step of custom header image page.
wp-admin/custom-header.php: Custom_Image_Header::admin_page()

Display the page based on the current step.
wp-admin/includes/ms.php: confirm_delete_users()
wp-admin/custom-background.php: Custom_Background::handle_upload()

Handle an Image upload for the background image.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::wp_die()

Custom wp_die wrapper. Returns either the standard message for UI or the Ajax message.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::setup_theme()

Start preview and customize theme.
wp-includes/pluggable.php: check_ajax_referer()

Verifies the Ajax request to prevent processing requests external of the blog.
wp-includes/class-wp.php: WP::parse_request()

Parse request to find correct WordPress query.
wp-includes/load.php: wp_set_wpdb_vars()

Set the database table prefix and the format specifiers for database table columns.
wp-includes/load.php: wp_not_installed()

Redirect to the installer if WordPress is not installed.
wp-includes/functions.php: wp_send_json()

Send a JSON response back to an Ajax request.
wp-includes/functions.php: dead_db()

Load custom DB error or display WordPress DB error.
wp-includes/functions.php: wp_nonce_ays()

Display “Are You Sure” message to confirm the action being taken.
wp-includes/functions.php: do_feed()

Load the feed template from the use of an action hook.
wp-includes/class-wp-ajax-response.php: WP_Ajax_Response::send()

Display XML formatted responses.
wp-includes/option.php: wp_protect_special_option()

Protect WordPress special option from being modified.
wp-includes/revision.php: _show_post_preview()

Filters the latest content for preview from the post autosave.
wp-includes/ms-functions.php: maybe_add_existing_user_to_blog()

Add a new user to a blog by visiting /newbloguser/{key}/.
wp-includes/ms-load.php: ms_not_installed()

Displays a failure message.
wp-includes/ms-load.php: ms_site_check()

Checks status of current blog.
wp-includes/ms-deprecated.php: wpmu_admin_do_redirect()

Redirect a user based on $_GET or $_POST arguments.
wp-includes/wp-db.php: wpdb::bail()

Wraps errors in a nice header and footer and dies.
wp-includes/wp-db.php: wpdb::print_error()

Print SQL/DB error.
wp-includes/class-wp-customize-widgets.php: WP_Customize_Widgets::wp_ajax_update_widget()

Updates widget settings asynchronously.
wp-includes/comment.php: wp_allow_comment()

Validates whether this comment is allowed to be made.
Show 98 more used by Hide more used by

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Test to see what is in the $post variable in a filter:

    /**
 * Add new body class.
 *
 * Testing what is in the $post variable.
 *
 * @param array $classes Body classes.
 */
function wpdocs_add_body_class( $classes ) {
	/** @global WP_Post $post */
	global $post;

	wp_die( '<pre>' . var_export( $post, true ) . '</pre>' );
}
add_filter( 'body_class', 'wpdocs_add_body_class' );

    Expand full source codeCollapse full source code

You must log in before being able to contribute a note or feedback.