How to use WP_Error $data argument?

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.

$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.