PHP throw Exception

Summary: in this tutorial, you will learn about the Exception class in detail and how to throw a new exception in PHP.

Introduction to the Exception class

When encountering a situation from which you cannot recover, you can throw an exception.

An exception is an instance of the Exception class. Like other PHP objects, you use the new keyword to create an instance of the Exception class.

An Exception object has two main properties: a message and a numeric code. The message describes the exception. The numeric code is optional, which specifies the context for a specific exception.

When you create a new exception, you provide the mesage the optional numeric code. For example:

<?php

$exception = new Exception('Invalid username or password', 100);Code language: HTML, XML (xml)

The Exception object has the getMessage() and getCode() that returns the message and numeric code:

<?php

$exception = new Exception('Invalid username or password', 100);

$message =  $exception->getMessage();
$code =  $exception->getCode();Code language: HTML, XML (xml)

The throw statement

In practice, you rarely assign an exception to a variable. Instead, you raise (or throw) the Exception object using the throw statement:

<?php

throw new Exception('Invalid username or password', 100);Code language: HTML, XML (xml)

The throw statement accepts an instance of the Exception class or the subclass of the Exception class. In fact, it accepts any object that implements the Throwable interface. Note that the Exception class also implements the Throwable interface.

When PHP encounters a throw statement, it immediately halts the code execution. Therefore, the code after the throw statement won’t execute.

Throwing an exception example

The following example defines a function called divide() that uses the the throw statement:

function divide($x, $y)
{
    if (!is_numeric($x) || !is_numeric($y)) {
        throw new InvalidArgumentException('Both arguments must be numbers or numeric strings');
    }

    if ($y == 0) {
        throw new Exception('Division by zero, y cannot be zero');
    }
    return $x / $y;
}Code language: PHP (php)

How the define() function works.

• First, throw the InvalidArgumentException exception if $x and $y are not numbers or numeric strings.
• Second, throw the division by zero exception if $y is zero.
• Third, return the division of $x and $y.

PHP built-in exception classes

The standard PHP library (SPL) provides many subclasses of the Exception class. For example, you can use the InvalidArgumentException when an argument of a function or method is not valid.

The following shows the exception classes in PHP 8.0:

Exception
   ClosedGeneratorException
   DOMException
   ErrorException
   IntlException
   JsonException
   LogicException
      BadFunctionCallException
         BadMethodCallException
      DomainException
      InvalidArgumentException
      LengthException
      OutOfRangeException
   PharException
   ReflectionException
   RuntimeException
      OutOfBoundsException
      OverflowException
      PDOException
      RangeException
      UnderflowException
      UnexpectedValueException
   SodiumExceptionCode language: plaintext (plaintext)

Summary

• An exception is an instance of the Exception class that implements the Throwable interface.
• Use the throw statement to raise an exception. The throw statement accepts an exception object that implements the Throwable interface.