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.
throw new Exception("Something went wrong", 42);
Try it
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.
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
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
newran, not wherethrowran. That is why rethrowing the same object keeps the original line and trace. - Accessor methods are
final. You cannot overridegetMessage()and friends; to change the message, pass it toparent::__construct(). The protected properties$message,$code,$fileand$linecan 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
$previousso logs show the whole story. catch (Exception $e)missesError. UseThrowableat 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_argsis 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.