🎓 A1Learner
🔍
0 of 38 lessons completed

Custom Exceptions

A custom exception is an exception class that a program defines for its own kind of failure. The class extends Exception, so throw and catch work with it in the usual way.

A custom exception thrown and caught

TooSmall extends Exception, so it is a new kind of exception. checkSize throws it when the value is under 10.

<?php
class TooSmall extends Exception {
}
function checkSize(int $n) {
  if ($n < 10) {
    throw new TooSmall("Value is too small");
  }
  echo $n, "\n";
}
try {
  checkSize(4);
} catch (TooSmall $e) {
  echo $e->getMessage(), "\n";
}

The code rides along with the message

The number 7 is passed after the message when the exception is made. getCode reads that number back in the catch block.

<?php
class TooSmall extends Exception {
}
function checkSize(int $n) {
  if ($n < 10) {
    throw new TooSmall("Value is too small", 7);
  }
  echo $n, "\n";
}
try {
  checkSize(4);
} catch (TooSmall $e) {
  echo $e->getMessage(), "\n";
  echo $e->getCode(), "\n";
}

Two custom types, two catch blocks

TooShort and TooLong are two separate custom types. Each try below is followed by both catch blocks, and the block that matches the thrown type answers.

<?php
class TooShort extends Exception {
}
class TooLong extends Exception {
}
function checkCode(string $code) {
  if (strlen($code) < 3) {
    throw new TooShort("Code is too short");
  }
  if (strlen($code) > 5) {
    throw new TooLong("Code is too long");
  }
  echo $code, "\n";
}
try {
  checkCode("ab");
} catch (TooShort $e) {
  echo $e->getMessage(), "\n";
} catch (TooLong $e) {
  echo $e->getMessage(), "\n";
}
try {
  checkCode("abcdef");
} catch (TooShort $e) {
  echo $e->getMessage(), "\n";
} catch (TooLong $e) {
  echo $e->getMessage(), "\n";
}

Example

<?php
class UnderAge extends Exception {
}
class OverAge extends Exception {
}
function registerAge(int $age) {
  if ($age < 18) {
    throw new UnderAge("Too young to register");
  }
  if ($age > 120) {
    throw new OverAge("Age is too high to register");
  }
  echo "Age accepted\n";
}
try {
  registerAge(15);
} catch (UnderAge $e) {
  echo $e->getMessage(), "\n";
} catch (OverAge $e) {
  echo $e->getMessage(), "\n";
}
try {
  registerAge(150);
} catch (UnderAge $e) {
  echo $e->getMessage(), "\n";
} catch (OverAge $e) {
  echo $e->getMessage(), "\n";
}
try {
  registerAge(30);
} catch (UnderAge $e) {
  echo $e->getMessage(), "\n";
} catch (OverAge $e) {
  echo $e->getMessage(), "\n";
}

Key points

  • A custom exception class is written with the word extends and the name Exception.
  • Use throw with a new exception object to raise it at that line.
  • The text passed when the exception is made is its message, and getMessage reads it back.
  • A number passed after the message is its code, and getCode reads it back.
  • Each custom type can have its own catch block, so each failure gets its own response.

In this example, registerAge checks an age against two limits. An age of 15 throws UnderAge, and its catch block prints the message. An age of 150 throws OverAge, and its own catch block prints that message. An age of 30 passes both checks, so the accepted line prints.

Note

A custom exception can carry any fixed code a program chooses, and the code has no set meaning on its own.

Try it Yourself

Edit the code, then press Run.

Running is simulated

Exercise

How does a program read the message stored in a caught exception?