How to use WP_Error $data argument?

Question

The Call

$error = new WP_Error( $code, $message, $data );

The Output

Say I added three messages (msg A, msg B, msg C) to the code my_code and with the last message I added "Data" as $data, which overwrote all $data added with the previous calls to the error class.

WP_Error Object
(
    [errors] => Array
        (
            [my_code] => Array
                (
                    [0] => "msg A"
                    [1] => "msg B"
                    [2] => "msg C"
                )
        )
    [error_data] => Array
        (
            [my_code] => "Data"
        )
)

After inspecting & playing around with the wp error class, I came to the following Qs:

Problem

I can pass an unlimited number of $codes to the class and then pass an unlimited number of $messages to each code. Point is that I can't pass more than one $data per $code.

Q: What is the intended use case of $data?¹⁾

---

^{1) Currently I'm trying to build a pretty simple WP_Error wrapper API (basically a set of easy-to-use functions). The Goal is to make a trac ticket out of it and move it to WP core.}

---

Edit #1

I found a pretty strange behaviour in /wp-includes/functions.php with the wp_die(); function: If you provide an error object, the function automatically fills the title provided by $data['title']. So from looking at this I thought that $data could be an associative array that can hold any amount of additional, dynamic data.

Q: But - and this is only valid if this is the intended use case - if $data is a) an array and b) I successfully added additional data in there: How would I connect that to the according messages?

Q: Further: Why doesn't wp_die(); abort if I have no error? This makes using it as dynamically - in case - added error output completely invalid.

---

Edit #2

You can find the ticket to fix the wp_die() handler here.

---

Edit #3

A draft of a first "Theme Errors API" can be found here on github. Forking, etc. and commenting is highly appreciated.

Answer 1

$this->error_data[$code] ... the WP_Error object holds $data in an array and $code is the key. The add_data method clearly states:

The error code can only contain one error data. But the $data (mixed) can be an array or an object and carry as many keys/properties as you need. It's up to your handlers how they interpret it.

Error $data is a bonus for further custom processing of the error. Your own special function can throw a WP_Error and you can add custom data into the $data that can be interpreted by your error own handler.

wp_die(); is the same as die; only that it shows formatted output before doing so. It is expected TO DIE. die; in PHP is not conditional. It's meant to stop there and wp_die(); is designed to mimic functionality with advanced pre-death output capabilities.

The 'title' in the $data support is just a bonus allowing built-in title support for the WP_Error(). It's designed so they don't need to choose which error_code's message is the title if multiple are present. They just use the default one's title attribute. NEVER RELY ON SUCH DEFAULT FUNCTIONALITY! Always use your own title in wp_die().

No errors here, just intended behavior... if I understood your question right.

Answer 2

/**
 * Creates a static global shared WP_Error object.
 * The object is contained safely inside function body as static variable.
 * It's also protected from external influence.
 * 
 * @return WP_Error
 */
function theme_errors(){
    static $wp_error; // Will hold global variable safely
    return isset($wp_error) ? $wp_error : ($wp_error = new WP_Error(null, null, null));
}
// This is how you add errors (first call initializes the object).
theme_errors()->add($code = 'code', $message = 'message', $data = 'some data');
theme_errors()->add($code = 'code', $message = 'message', $data = 'some data');
// And then do some display stuff on shutdown
add_action('shutdown', function(){
    // If conditions are met and errors exist:
    if(!theme_errors()->get_error_codes()) return;
    // Loop error codes and display errors
    foreach(($codes = theme_errors()->get_error_codes()) as $code){
        $message = theme_errors()->get_error_message($code);
        $data = theme_errors()->get_error_data($code);
        // Display stuff here
    }
});

Much easier alternative. Theme name independent (we only work with active theme). Protected global variable inside function.