wp_die()终断WordPress执行并显示错误HTML信息

目录

描述

译文

终断WordPress执行并显示错误HTML信息。

一个该函数的调用与PHP函数die()互为补充。区别在于,HTML是显示给用户看的。推荐仅在进程不能再继续时,再使用该函数。不推荐经常调用该函数,尽量低调处理各种错误。

原文

Kill WordPress execution and conditionally display HTML message with error message.

A call to this function complements the die() PHP function. The difference is that HTML will be displayed to the user in the case of a typical web request. 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.

If you really want to stop execution and exit the PHP script without outputting anything (and let the response time out) use exit;, the modern version of die(). The function wp_die() is designed to give output just before it dies to avoid empty or time-outing responses.

wp_die() 描述

用法

<?php wp_die$message$title$args ?>

wp_die() 用法

参数

$message

(mixed) (可选) Error message or a complete WP_Error object.

默认值: None

$title

(string) (可选) Error title, If you use a WP_Error object, the title will be by default the one you added in $data['title'] (ignored when DOING_AJAX is true).

默认值: ''

$args

(string|array) (可选) Optional arguments to control behavior (ignored when DOING_AJAX is true).

默认值: None

Arguments

response

(integer) (可选) HTML status code returned.

默认值: 500

back_link

(boolean) (可选) Whether to display a back link in the returned page.

默认值: false

text_direction

(string) (可选) Whether to set ltr or rtl as the text direction

默认值: 'ltr'

wp_die() 参数

返回值

(void) 

This function does not return a value.

wp_die() 返回值

示例

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

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */

add_filter( 'body_class', 'add_body_class_cb' );
/**
 * Add new body class.
 *
 * Testing what is in the $post variable.
 */
function add_body_class_cb( $classes ) {
    global $post;

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

wp_die() 示例

注意

  • 使用到: apply_filters() - To 过滤器 the name of the die handler function:
    • 调用 'wp_die_ajax_handler' with the default AJAX die handler function ('_ajax_wp_die_handler') if the DOING_AJAX constant is set to true.
    • 调用 'wp_die_xmlrpc_handler' with the default XML-RPC die handler function ('_xmlrpc_wp_die_handler') if the XMLRPC_REQUEST constant is set to true.
    • 调用 'wp_die_handler' in every other case, with the default die handler function ('_default_wp_die_handler').
  • 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.

    [example missing here]

wp_die() 注意

历史

wp_die() 历史

源文件

wp_die() 函数的代码位于 wp-includes/functions.php.

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
/**
 * Kill WordPress execution and display HTML message with error message.
 *
 * 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.
 *
 * @since 2.0.4
 * @since 4.1.0 The `$title` and `$args` parameters were changed to optionally accept
 *              an integer to be used as the response code.
 *
 * @param string|WP_Error  $message Optional. Error message. If this is a {@see WP_Error} object,
 *                                  the error's messages are used. Default empty.
 * @param string|int       $title   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 empty.
 * @param string|array|int $args {
 *     Optional. Arguments to control behavior. If `$args` is an integer, then it is treated
 *     as the response code. Default empty array.
 *
 *     @type int    $response       The HTTP response code. Default 500.
 *     @type bool   $back_link      Whether to include a link to go back. Default false.
 *     @type string $text_direction 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 {@see is_rtl()}.
 * }
 */
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 ( defined( 'DOING_AJAX' ) && DOING_AJAX ) {
		/**
		 * Filter callback for killing WordPress execution for AJAX requests.
		 *
		 * @since 3.4.0
		 *
		 * @param callback $function Callback function name.
		 */
		$function = apply_filters( 'wp_die_ajax_handler', '_ajax_wp_die_handler' );
	} elseif ( defined( 'XMLRPC_REQUEST' ) && XMLRPC_REQUEST ) {
		/**
		 * Filter callback for killing WordPress execution for XML-RPC requests.
		 *
		 * @since 3.4.0
		 *
		 * @param callback $function Callback function name.
		 */
		$function = apply_filters( 'wp_die_xmlrpc_handler', '_xmlrpc_wp_die_handler' );
	} else {
		/**
		 * Filter callback for killing WordPress execution for all non-AJAX, non-XML-RPC requests.
		 *
		 * @since 3.0.0
		 *
		 * @param callback $function Callback function name.
		 */
		$function = apply_filters( 'wp_die_handler', '_default_wp_die_handler' );
	}

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

wp_die() 源文件