Added support for message to orElseThrow method

[petrknap]

• This pull request does not contain any breaking change.
• I asked the AI to briefly summarize, use and improve the feature(s), and I'm okay with the output:

Could you briefly summarize the meaning of $message argument in following code for me?

class Optional implements JavaSe8\Optional
{
    # ...

    /**
     * @template E of Throwable
     *
     * @param null|class-string<E>|callable(string|null $message): E $exceptionSupplier
     *
     * @return T
     *
     * @throws E
     */
    public function orElseThrow(
        null|string|callable $exceptionSupplier = null,
        string|null $message = null,
    ): mixed {/*...*/}
}

Of course! In this code, the $message argument in the orElseThrow method serves as an optional error message to be used when an exception is thrown.

Here's a breakdown of its role:

• Type: The $message argument is of type string|null, meaning it can either be a string (containing the error message) or null (indicating no specific error message).
• Usage: When the orElseThrow method is called, if the exceptionSupplier is provided and an exception needs to be thrown, the $message can be used as the error message for the exception.
• Optional: The $message argument is optional, as indicated by the = null default value. If no specific message is provided, a default behavior or message can be used.

So, the $message argument essentially allows you to customize the error message when throwing an exception using the orElseThrow method.

Could you show me how to use it?

Sure! Here's an example of how you might use the orElseThrow method in the Optional class with the $message argument to customize the error message for the thrown exception:

try {
    // Assume $optional is an instance of Optional that is empty (value is null)
    $optional = new Optional();
    
    // Using a class-string exception supplier with a custom message
    $value = $optional->orElseThrow(\InvalidArgumentException::class, 'Custom error message');
    
} catch (\InvalidArgumentException $e) {
    echo 'Caught exception: ', $e->getMessage(); // Outputs: Caught exception: Custom error message
}

try {
    // Using a callable exception supplier with a custom message
    $value = $optional->orElseThrow(function ($message) {
        return new \Exception($message);
    }, 'Another custom error message');
    
} catch (\Exception $e) {
    echo 'Caught exception: ', $e->getMessage(); // Outputs: Caught exception: Another custom error message
}

Is there any way to name $message better?

Definitely! Naming variables for clarity and purpose is essential for maintainability. For the $message argument, you might consider names that reflect its role as an error or exception message. Here are a few suggestions:

• $errorMessage
• $exceptionMessage
• $customMessage

Each of these names clearly indicates that the variable is related to the message used when throwing an exception.