How to Handle WordPress Errors with WP_Error Class

When working with WordPress and other APIs, there will be times to handle WordPress errors or errors given by third party APIs. With WP_Error class you can handle both error and make your own custom error.

WP_Error Class

This class can be found in wp-includes/class-wp-error.php. In that file our class is defined alongside a function is_wp_error().

This function can be used if a passed variable is an instance of the WP_Error class.

The class has two attributes:

• $errors – an array that will contain error messages
• $error_data – an array that will contain data about error codes

Both arrays are associative arrays where the error code represents the array key. Because of that, each error (code) can contain more than 1 error message.

When instantiating an object of WP_Error class we have to provide at least the error code. After that, we can use that object to add various errors to our liking.

To add or remove WordPress errors, we can use public methods define within the WP_Error class:

• get_error_codes() – retrieves all the error codes
• get_error_code() – retrieves only the first error code
• get_error_messages( $code ) – retrieves the messages for the provided code or if $code is empty, retrieves all the messages
• get_error_message( $code ) – retrieves the messages for the provided code
• get_error_data( $code ) – retrieves the error data for the provided code
• add( $code, $message, $data ) – adds a new error
• add_data( $data, $code ) – adds data to an existing error code
• remove( $code ) – removes the error messages and data for the provided code

This is an example of how we are instantiating a WP_Error class:

<?php

$error_code = 'my_error_code';
$error_message = __( 'My Error Message', 'my_textdomain' );

$api_error = new WP_Error( $error_code, $error_message );

We will now see some of the examples on how we can use the class.

Handling WordPress Errors for PayPal

Let’s assume that we are creating a plugin or an add-on that will add a PayPal payment method using the Express Checkout.

PayPal API can give a lot of errors. We will go over some simple general errors. To see all of them and other types of PayPal error, please visit their API error codes.

<?php

$response_from_paypal = paypal_retrieve_approaval_link();
// We have an error
if( $response_from_paypal['ACK'] != 'SUCCESS' ) {
  $error_code = $response_from_paypal['L_ERRORCODE0'];
  $error_short_message = $response_from_paypal['L_SHORTMESSAGE0'];
  $error_long_message = $response_from_paypal['L_LONGMESSAGE0'];

  $api_error = new WP_Error( $error_code, $error_short_message ); // We have added a short message, it will be the first code
  
  // Let's add a long message with description
  $api_error->add( $error_code, $error_long_message );
}

We are checking for a PayPal parameter ACK that will gives us the information if everything passed as intended or if there were some errors. If there are errors, we then add them.

Here we are adding both short and long messages for a code.

Let’s also assume that we are saving those errors somewhere in our plugin. We would also need to retrieve them.

Retrieving the WordPress Errors

In a common scenario we would retrieve those error from another function or maybe even retrieve them from the database and instantiate them as WP_Error class.

<?php

// ...

$retrieved_error_from_plugin = did_paypal_pay();

// It is a WordPress Error
if( is_wp_error( $retrieved_error_from_plugin ) ) {
  $retrieved_error_from_plugin->get_error_codes();
  /*
   array(
    '10002'
   );
   */
  
  $retrieved_error_from_plugin->get_error_code(); 
  /*
   '10002'
   */
  
  $retrieved_error_from_plugin->get_error_messages( '10002' );
  $retrieved_error_from_plugin->get_error_message( '10002' );
  /* Same:
  array(
    'Authentication/Authorization Failed',
    'Account is locked or inactive'
   );
   */
  
  
  
  $retrieved_error_from_plugin->get_error_messages( '10005' );
  /*
  array() // Empty 
  */
}

We are here using the first error in the general PayPal errors so that you can understand it even more. In the examples above you can see how some of the methods can be used to retrieve needed information about WordPress errors.

Conclusion

WP_Error class is a great class to manage WordPress errors. Those errors can be whatever you want and come from whenever you want. But if you are creating and defining the errors within a WordPress theme or plugin, you should be using the WP_Error class.