.PHP File Format – Exceptions

The Throwable hierarchy

Every object that can be thrown implements Throwable (PHP 7.0). A class cannot implement it directly: it must extend Exception or Error. An interface may extend Throwable.

Throwable
├── Error                         engine and programming errors
│   ├── ArithmeticError
│   │   └── DivisionByZeroError
│   ├── AssertionError
│   ├── CompileError
│   │   └── ParseError
│   ├── FiberError
│   ├── TypeError
│   │   └── ArgumentCountError
│   ├── UnhandledMatchError
│   └── ValueError
└── Exception                     conditions a program may want to handle
    ├── ErrorException
    ├── ClosedGeneratorException
    ├── JsonException
    ├── RequestParseBodyException
    ├── LogicException
    │   ├── BadFunctionCallException
    │   │   └── BadMethodCallException
    │   ├── DomainException
    │   ├── InvalidArgumentException
    │   ├── LengthException
    │   └── OutOfRangeException
    └── RuntimeException
        ├── OutOfBoundsException
        ├── OverflowException
        ├── RangeException
        ├── UnderflowException
        └── UnexpectedValueException

Throwable declares getMessage(), getCode(), getFile(), getLine(), getTrace(), getTraceAsString(), getPrevious() and __toString(). The Exception constructor takes an optional message, code and previous exception, the last of which chains one exception to its cause.

try, catch and finally

try { statements }
{catch ( Class {| Class} [$var] ) { statements }}
[finally { statements }]

try {
    $data = load($path);
} catch (FileNotFound | Forbidden $e) {
    log_warning($e->getMessage());
    $data = [];
} catch (Exception) {
    throw new RuntimeException('load failed');
} finally {
    release_lock();
}

• A try needs at least one catch or a finally.
• catch clauses are tried in order, and the first matching one runs.
• A catch can name several types separated by | (PHP 7.1).
• The variable may be left out (PHP 8.0) if the exception is not used.
• To catch everything use catch (Throwable $e). A catch (Exception $e) does not catch an Error.
• A finally block (PHP 5.5) runs whether or not an exception was thrown and even after a return. A return inside finally replaces any earlier return value and discards an exception in flight.

throw

throw raises an object that implements Throwable; throwing anything else is an Error. Since PHP 8.0 it is an expression, so it can be used in arrow functions and on the right of ??, ?: and match.

$value = $input ?? throw new InvalidArgumentException('missing');
$fail  = fn() => throw new LogicException('not implemented');

An uncaught exception ends the script with a fatal error unless a handler has been set with set_exception_handler(). Finally blocks and shutdown functions still run.

Error levels

Traditional errors are not objects. Each has a level, and error_reporting selects which levels are reported.

Values combine as a bitmask: error_reporting(E_ALL & ~E_DEPRECATED).