Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Exceptions and Errors

The PHP Throwable interface

Reference for the PHP Throwable interface: the root of Exception and Error, its methods, why you cannot implement it directly and when to catch it.

Throwable is the interface that every object must implement to be thrown. PHP has exactly two branches of it: Exception for failures that your application code raises, and Error for problems the engine detects. Both implement Throwable, and so does every subclass of either.

It also extends Stringable, so any throwable can be cast to a string to get a readable report. Use Throwable as a type or in a catch block when you want to handle both branches at once, typically at the outermost layer of a program.

PHP
try {
    run();
} catch (Throwable $e) {
    error_log((string) $e);
}

Try it

PHP Catching both branches

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP The shape of Throwable

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Trying to implement it directly is a compile-time fatal error, so it cannot be caught:

PHP
class Mine implements Throwable {}
// Fatal error: Class Mine cannot implement interface Throwable,
// extend Exception or Error instead

Syntax

PHP
interface Throwable extends Stringable
{
    public function getMessage(): string;
    public function getCode(): int;
    public function getFile(): string;
    public function getLine(): int;
    public function getTrace(): array;
    public function getTraceAsString(): string;
    public function getPrevious(): ?Throwable;
    public function __toString(): string;
}

Return value (methods): the same as for Exception.

Errors: a class that tries to implement Throwable directly cannot be compiled; the engine reports a fatal error saying the class must extend Exception or Error instead.

Usage notes

  • You can't implement it directly. User classes must extend Exception or Error (usually Exception), because only those base classes fill in the file, line and trace when an object is created.
  • Use it as a type. function handle(Throwable $e): void accepts both branches, and so does catch (Throwable $e).
  • Catch it at the boundary. A top-level handler, a queue worker's job wrapper or a framework's error page may catch Throwable to log and keep running. Deeper in the code, catch the narrowest class you can recover from.
  • finally needs no catch. Cleanup in finally runs for any Throwable, even when nothing catches it.
  • Combining: catch (Exception | Error $e) is equivalent to catching Throwable for built-in code, but custom marker interfaces that extend Throwable are a better way to group your own exceptions.
  • Interfaces can extend Throwable. interface AppException extends Throwable {} plus class NotFound extends RuntimeException implements AppException {} lets callers catch every exception from your library with one catch.
  • Never catch and ignore. An empty catch (Throwable) hides real failures; at least log it.
  • Fatal errors that are not throwable (some memory-limit and timeout cases) still end the script; use register_shutdown_function() to report them.