Error handling

Two failure styles#

Each function in RTLY-Kit uses one of two styles, so you always know what to guard:

• Validators never throw. NationalCode, Sheba, BankCard, Mobile, PostalCode and VehiclePlate (and the is_* and validate_* helpers) accept any value and answer with false or an invalid Result. See Validators overview.
• Everything else throws a RtlyKit\Exceptions\RtlyKitException (or a subclass) for input it cannot accept. A TypeError, ValueError or PHP DateMalformed* exception never escapes for bad input. If you see one, it is a library bug, and we would like a report.

Exception hierarchy#

\InvalidArgumentException
 └─ RtlyKit\Exceptions\RtlyKitException        implements RtlyKitThrowable
     ├─ InvalidDateException
     ├─ InvalidNumberException
     ├─ InvalidPrayerConfigException
     └─ UnsupportedLocaleException

RtlyKitThrowable is a marker interface. It declares getErrorCode(): ErrorCode and getContext(): array. Catch it, or RtlyKitException, to handle the whole library with one clause. RtlyKitException extends \InvalidArgumentException, so existing catch (\InvalidArgumentException) and catch (\LogicException) code keeps working.

Error codes#

Exception messages are for people and may be reworded in any release. The error code is the stable part. It is an ErrorCode backed string enum, and its case names and values are public API (see API stability).

Reading the code and the context#

Every library exception has getErrorCode() and getContext(). The context is an array of facts about the failure that a program can read (a limit, the locale, the name of the argument). It never contains secrets and may be empty. This script feeds five bad inputs to number_to_words():

<?php
require __DIR__.'/vendor/autoload.php';

use function RtlyKit\number_to_words;
use RtlyKit\Exceptions\RtlyKitThrowable;

foreach ([1.5, NAN, 'abc', str_repeat('9', 22), str_repeat('1', 5000)] as $input) {
    try {
        number_to_words($input);
    } catch (RtlyKitThrowable $e) {
        echo (new ReflectionClass($e))->getShortName(), ' ',
            $e->getErrorCode()->value, ' ',
            json_encode($e->getContext()), "\n";
    }
}
// InvalidNumberException invalid_number []
// InvalidNumberException non_finite_number []
// InvalidNumberException invalid_number []
// InvalidNumberException number_too_large {"limit":"10^21 - 1"}
// InvalidNumberException input_too_long {"limit":4096}

Catching patterns#

Branch on the code, not on the message. Use match with a default arm, because a minor release may add new cases.

<?php
require __DIR__.'/vendor/autoload.php';

use RtlyKit\Calendar\Jalali;
use RtlyKit\Exceptions\{ErrorCode, InvalidDateException, RtlyKitThrowable};

function category(RtlyKitThrowable $e): string
{
    return match ($e->getErrorCode()) {
        ErrorCode::InvalidDate, ErrorCode::DateOutOfRange => 'date',
        ErrorCode::InputTooLong => 'too-long',
        default => 'other',
    };
}

try {
    Jalali::create(1404, 13, 1);          // there is no month 13
} catch (RtlyKitThrowable $e) {
    echo category($e), "\n";               // date
}

$e = InvalidDateException::because(ErrorCode::DateOutOfRange, 'Year is out of range', ['year' => 99999]);
echo $e->getErrorCode()->value, ' ', json_encode($e->getContext()), "\n";
// date_out_of_range {"year":99999}

try {
    Jalali::create(1404, 13, 1);
} catch (\InvalidArgumentException $e) {   // old-style catch still works
    echo get_class($e), ' ', $e instanceof RtlyKitThrowable ? 'is RtlyKitThrowable' : '', "\n";
    // RtlyKit\Exceptions\InvalidDateException is RtlyKitThrowable
}

RtlyKitException::because(ErrorCode, string $message, array $context = [], ?Throwable $previous = null) is the named constructor the library uses to raise an exception with a specific code. You can use it for your own failures too. The code you add this way is your own and not part of the contract of the library.

When you log, write the code and the context and not the message text:

catch (RtlyKitThrowable $e) {
    error_log($e->getErrorCode()->value.' '.json_encode($e->getContext()));
}

What never throws#

The validators accept any PHP value. They raise no exception for bad input, whatever its type or size:

<?php
require __DIR__.'/vendor/autoload.php';

use function RtlyKit\validate_national_code;
use RtlyKit\Validation\Sheba;

var_dump(Sheba::isValid(null));                                  // bool(false)
echo json_encode(validate_national_code([])->errors()), "\n";                    // ["invalid_type"]
echo json_encode(validate_national_code(str_repeat('1', 5000))->errors()), "\n"; // ["input_too_long"]
echo json_encode(validate_national_code('0013542418')->errors()), "\n";          // ["invalid_checksum"]
var_dump(validate_national_code('0013542419')->isValid());       // bool(true)

The Laravel validation rules and the Globals::register() opt-in follow the same rule. The rules return a boolean, and Globals::register() never throws. It returns the names it skipped.

Input caps#

Every call that takes untrusted text has a size cap, so a hostile input cannot cost much. Going over a cap raises input_too_long, as an exception or as a validator error. The full list is on Limits.

The calendar range rule#

Every calendar entry point (make, create, createFromFormat, timestamps, add* and sub*, the helpers and the Carbon macros) either returns a valid date or throws InvalidDateException. Nothing wraps around, and no other exception type is used. The ranges are Jalali -620 to 9377, Hijri 1 to 9665 and Hebrew 3762 to 13759, all within Gregorian years 1 to 9999. See Limits.

A complete example#

use function RtlyKit\jdate;
use function RtlyKit\number_to_words;
use RtlyKit\Exceptions\InvalidDateException;
use RtlyKit\Exceptions\RtlyKitThrowable;

try {
    $date  = jdate($userInput);
    $words = number_to_words($userAmount);
} catch (InvalidDateException $e) {
    echo "Please enter a valid date.\n";
} catch (RtlyKitThrowable $e) {
    error_log($e->getErrorCode()->value.' '.json_encode($e->getContext()));
}