Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Exceptions and Errors

The PHP Exception class

Reference for the PHP Exception class: constructor arguments, getMessage, getCode, getPrevious, getLine, getTraceAsString, chaining and subclassing.

Exception is the base class for exceptions that application code throws and catches. It implements the Throwable interface and carries a message, an integer code, the file and line where it was created, a stack trace and an optional previous exception that caused it.

You usually throw one of the specific subclasses (InvalidArgumentException, RuntimeException, JsonException...) or one of your own. PHP's engine errors (type errors, division by zero) are not Exceptions: they extend Error, so catch (Exception $e) does not catch them. Catch Throwable to catch both.

PHP
throw new Exception("Something went wrong", 42);

Try it

PHP What an exception knows

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 Chaining and subclassing

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.

Syntax

PHP
class Exception implements Throwable
{
    public function __construct(string $message = "", int $code = 0, ?Throwable $previous = null);

    final public function getMessage(): string;
    final public function getCode(): int;
    final public function getPrevious(): ?Throwable;
    final public function getFile(): string;
    final public function getLine(): int;
    final public function getTrace(): array;
    final public function getTraceAsString(): string;
    public function __toString(): string;
}
Name Description
$message A human-readable description of what went wrong.
$code An integer for your own use, such as an error number or HTTP status.
$previous The exception that caused this one, used for chaining.

Return value (methods): getMessage(), getFile() and getTraceAsString() return strings; getCode() an int; getLine() the line where the exception object was created; getTrace() an array of frames with keys such as file, line, function, class and args; getPrevious() the cause or null.

Errors: the constructor throws a TypeError for arguments of the wrong type.

Usage notes

  • The location is where new ran, not where throw ran. That is why rethrowing the same object keeps the original line and trace.
  • Accessor methods are final. You cannot override getMessage() and friends; to change the message, pass it to parent::__construct(). The protected properties $message, $code, $file and $line can be set in a subclass.
  • Always call parent::__construct() in a subclass constructor, or the message, code and previous exception stay at their defaults.
  • Chain, don't swallow. When you translate a low-level exception into a domain exception, pass the original as $previous so logs show the whole story.
  • catch (Exception $e) misses Error. Use Throwable at top-level boundaries only; catching everything deeper hides bugs.
  • Multiple types: catch (A | B $e) handles several classes with one block (PHP 7.1+), and since PHP 8.0 you can omit the variable: catch (Exception).
  • Don't put secrets in messages. Messages often reach logs and, on misconfigured servers, the browser. Stack traces also include argument values unless zend.exception_ignore_args is on, which is the production default.
  • __toString() returns the class, message, file, line and trace as text, which is what you see for uncaught exceptions.
  • Use specific subclasses so callers can catch what they can handle; see SPL exceptions and Custom exceptions.