[收起] 文章目录

WordPress 的运行中难免会产生一些错误,我们不希望错误直接阻止了用户对网站的顺畅访问。

这里指的错误并不是 PHP 代码错误。而是在处理一些数据的时候产生的,尤其是处理表单数据,因为不可能所有用户都会完全按照我们的要求提交数据。

比如,在注册用户的时候需要用户填写电子邮件。用户可能会输入不符合电子邮件格式的内容,或者这个电子邮件已经有用户使用,那么就会产生一个错误,导致用户无法顺利注册。

由于错误多种多样,WordPress 使用了一个 WP_Error 类来统一错误的保存方式,有了统一的方式,插件和主题就能更好的读取和添加一些错误,也能简化错误的储存代码。

属性
$errors

用于储存所有的错误。

$error_data

储存错误的额外数据。

这些属性均为类私有(private)。
方法
get_error_codes()

获取所有错误代码。

get_error_code()

获取第一个可用的错误代码,如果没有则返回空。

get_error_messages( $code = '' )

获取一个错误的所有错误消息。

get_error_message( $code = '' )

获取一个错误的第一个错误消息。

get_error_data( $code = '' )

获取错误的额外数据,没有额外数据返回 null.

add( $code, $message, $data = '' )

添加一个错误信息。

add_data( $data, $code = '' )

添加错误的额外数据。

WP_Error( $code = '', $message = '', $data = '' ), __construct( $code = '', $message = '', $data = '' )

WP_Error 的构造函数,实例化类的时候自动运行,所有的参数都是可选的。可以直接在实例化类的时候添加一个错误。

使用方法

比如下边这个邮件发送函数,如果发生错误,就会把错误返回出去。任何错误都没产生,而且邮件发送顺利则返回 True.


function Bing_send_mail( $email ){
    if( empty( $email ) ) return new WP_Error( 'empty_email', '邮箱不能为空' );
    if( !is_email( $email ) ) return new WP_Error( 'invalid_email', '邮箱格式不正确' );
    
    if( wp_mail( $email, '测试邮件', 'Hello World' ) ) return true;
 
    return new WP_Error( 'send_error', '邮件发送失败' );
}

下方是一个注册表单的处理函数,里边多次使用了 WP_Error:


function Bing_register_user(){
    $sanitized_user_login = sanitize_user( $_POST['username'] );
    $user_email = apply_filters( 'user_registration_email', $_POST['email'] );
    $register_errors = new WP_Error;
 
    //验证用户名
    if( empty( $sanitized_user_login ) ) $register_errors->add( 'empty_username', __( '用户名不能为空', 'Bing' ) );
    elseif( !validate_username( $sanitized_user_login ) ) $register_errors->add( 'invalid_username', __( '用户名包含无效字符', 'Bing' ) );
    elseif( username_exists( $sanitized_user_login ) ) $register_errors->add( 'username_exists', __( '用户名已经存在', 'Bing' ) );
 
    //验证邮箱
    if( empty( $user_email ) ) $register_errors->add( 'empty_email', __( '邮箱不能为空', 'Bing' ) );
    elseif( !is_email( $user_email ) ) $register_errors->add( 'invalid_email', __( '邮箱格式不正确', 'Bing' ) );
    elseif( email_exists( $user_email ) ) $register_errors->add( 'email_exists', __( '邮箱已经存在', 'Bing' ) );
 
    //注册表单提交事件
    do_action( 'register_post', $sanitized_user_login, $user_email, $register_errors );
 
    //错误过滤器
    $register_errors = apply_filters( 'registration_errors', $register_errors, $sanitized_user_login, $user_email );
 
    //注册用户
    if( !$register_errors->get_error_message() ){
        $register_new_user = register_new_user( $sanitized_user_login, $user_email );
        if( is_wp_error( $register_new_user ) ) return $register_new_user;
        return true;
    }
 
    return $register_errors;
}

判断 WP_Error

在很多时候我们要判断函数返回的到底是 WP_Error 还是其它内容,因为 WP_Error 是一个类,所以无法通过 True 或 False 直接判断。

WordPress 提供了一个 is_wp_error() 函数,用它我们就能判断变量是否是 WP_Error:


$register = Bing_register_user();
if( is_wp_error( $register ) ) wp_die( '注册失败:' . $register->get_error_message() );

其它

此类位于:wp-includes/class-wp-error.php