PHP Reference ยท Standard PHP Library and Classes
SPL exceptions
Reference for the PHP SPL exception classes: LogicException and RuntimeException families, which to throw for bad arguments, ranges, state and lookups, with examples.
PHP's Standard PHP Library defines a set of exception classes so that you do not need to invent a type for every common failure. They fall into two families. Logic exceptions describe mistakes a programmer could have prevented: the code was called wrongly. Runtime exceptions describe problems that can only be found while the program runs, such as a value that turned out to be out of range.
Throwing a specific class lets callers catch exactly what they care about, and you can still catch the whole family with the parent class.
Exception
โโโ LogicException
โ โโโ BadFunctionCallException
โ โ โโโ BadMethodCallException
โ โโโ DomainException
โ โโโ InvalidArgumentException
โ โโโ LengthException
โ โโโ OutOfRangeException
โโโ RuntimeException
โโโ OutOfBoundsException
โโโ OverflowException
โโโ RangeException
โโโ UnderflowException
โโโ UnexpectedValueException
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
throw new InvalidArgumentException(string $message = "", int $code = 0, ?Throwable $previous = null);
Every SPL exception uses the constructor of Exception.
| Class | Typical use |
|---|---|
InvalidArgumentException |
An argument has the right type but an unacceptable value. |
DomainException |
A value is outside the valid domain of an operation (for example a state that has no meaning). |
LengthException |
A length is invalid, such as an empty or oversized string. |
OutOfRangeException |
Illegal index requested in code that should have checked it (logic). |
BadFunctionCallException |
A callback is missing or cannot be called. |
BadMethodCallException |
A magic method such as __call() receives an unknown method. |
RuntimeException |
Generic problem discovered at run time. |
OutOfBoundsException |
Invalid key or index discovered at run time. |
RangeException |
A computed value falls outside an expected range. |
OverflowException / UnderflowException |
Adding to a full or removing from an empty container. |
UnexpectedValueException |
A value does not match the expected set, such as unexpected data from a file. |
Return value: the constructor creates the exception object; getMessage(), getCode(), getPrevious(), getFile() and getLine() read it back.
Usage notes
OutOfRangeExceptionis not anOutOfBoundsException. They are siblings in different branches (logic versus runtime), as the second example confirms. Catch the one you throw.- Pick the family by who can prevent it. Bad input from your own caller is logic; bad data from outside (files, networks) is runtime.
- Do not overthink the choice.
InvalidArgumentExceptionandRuntimeExceptioncover most needs. For domain rules, custom exception classes that extend them read better. - Built-in functions mostly throw other types.
TypeError,ValueErrorandArgumentCountError(allErrorsubclasses, notException) are what the engine uses in PHP 8, socatch (Exception)does not catch them. - Keep the cause. Pass the original as
$previouswhen you wrap an exception. - Catch order. List specific classes before parents, or the parent swallows them.
- SPL data structures throw these:
SplStack::pop()on an empty stack throwsRuntimeException, andSplFixedArrayrejects invalid indexes with an exception from this family.