Skip to content
Tutorials Center
My learning

Topics

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.

TEXT
Exception
โ”œโ”€โ”€ LogicException
โ”‚   โ”œโ”€โ”€ BadFunctionCallException
โ”‚   โ”‚   โ””โ”€โ”€ BadMethodCallException
โ”‚   โ”œโ”€โ”€ DomainException
โ”‚   โ”œโ”€โ”€ InvalidArgumentException
โ”‚   โ”œโ”€โ”€ LengthException
โ”‚   โ””โ”€โ”€ OutOfRangeException
โ””โ”€โ”€ RuntimeException
    โ”œโ”€โ”€ OutOfBoundsException
    โ”œโ”€โ”€ OverflowException
    โ”œโ”€โ”€ RangeException
    โ”œโ”€โ”€ UnderflowException
    โ””โ”€โ”€ UnexpectedValueException

Try it

PHP Throwing the right class

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 Catching a whole family

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
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

  • OutOfRangeException is not an OutOfBoundsException. 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. InvalidArgumentException and RuntimeException cover most needs. For domain rules, custom exception classes that extend them read better.
  • Built-in functions mostly throw other types. TypeError, ValueError and ArgumentCountError (all Error subclasses, not Exception) are what the engine uses in PHP 8, so catch (Exception) does not catch them.
  • Keep the cause. Pass the original as $previous when 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 throws RuntimeException, and SplFixedArray rejects invalid indexes with an exception from this family.