PHP Exceptions

An Exception is a special object that describes an error or unexpected behavior of a script. We use them when we want to safely stop or redirect code execution if we encounter a problem that the program cannot automatically handle. We trigger an exception using the throw statement, and we catch it using a try...catch structure, resolving it in time to prevent the entire webpage from crashing.

EXAMPLE

[file:Uncaught exception]
<?php
 // Example of an unhandled exception - triggers a fatal error
 function checkDivision($number, $divider) {
 if ($divider == 0) {
 throw new Exception("Division by zero is not possible.");
 }
 return $number / $divider;
 }

echo checkDivision(10, 0);
?>

[file:Basic try-catch]
<?php
 // Using try...catch to catch the error and continue execution
 function safeDivision($number, $divider) {
 if ($divider == 0) {
 throw new Exception("Division by zero!");
 }
 return $number / $divider;
 }
 
 try {
 echo safeDivision(10, 0);
 } catch (Exception $e) {
 echo "Error caught: " . $e->getMessage();
 }
?>

[file:Exception()]
<?php
 // The Exception constructor allows setting a message and a code
 try {
 throw new Exception("Error description", 404);
 } catch (Exception $e) {
 echo "Message: " . $e->getMessage() . " ";
 echo "Code: " . $e->getCode();
 }
?>

[file:getCode()]
<?php
 // getCode() returns the numeric error code
 try {
 throw new Exception("Page not found", 404);
 } catch (Exception $e) {
 echo "Error identification (Code): " . $e->getCode();
 }
?>

[file:getFile()]
<?php
 try {
 throw new Exception("Error in code!");
 } catch (Exception $e) {
 $fileName = str_contains($e->getFile(), "eval") ? "index.php" : basename($e->getFile());
 echo "File: " . $fileName;
 }
?>

[file:getLine()]
<?php
 // getLine() returns the line number
 try {
 throw new Exception("Invalid input!");
 } catch (Exception $e) {
 echo "The error occurred on line: " . $e->getLine();
 }
?>

[file:getMessage()]
<?php
 // getMessage() returns the error description
 try {
 throw new Exception("User does not exist.");
 } catch (Exception $e) {
 echo "Exception description: " . $e->getMessage();
 }
?>

[file:getPrevious()]
<?php
 // getPrevious() helps us with exception chaining
 try {
 try {
 throw new Exception("Original error", 1);
 } catch (Exception $first) {
 throw new Exception("Secondary error", 2, $first);
 }
 } catch (Exception $second) {
 echo "Current: " . $second->getMessage() . " ";
 if ($previous = $second->getPrevious()) {
 echo "Source error: " . $previous->getMessage();
 }
 }
?>

[file:getTrace()]
<?php
 function testFunction() {
 throw new Exception("Tracing the call!");
 }

try {
 testFunction();
 } catch (Exception $error) {
 echo "Stack trace (Array): ";
 $trace = $error->getTrace();
 foreach ($trace as &$step) {
 if (isset($step["file"])) {
 $step["file"] = basename($step["file"]);
 }
 }
 print_r($trace); echo " ";
 }
?>

[file:getTraceAsString()]
<?php
 function testString() {
 throw new Exception("Trace as string!");
 }

try {
 testString();
 } catch (Exception $error) {
 $traceString = $error->getTraceAsString();
 
 echo "Trace as string: ";
 
 $parts = explode(":", $traceString);
 if (count($parts) > 2) {
 echo "#0 " . end($parts);
 } else {
 echo $traceString;
 }
 }
?>

[file:try-catch-finally]
<?php
 // The finally block executes in any case
 try {
 echo "Attempting execution... ";
 throw new Exception("Something went wrong.");
 } catch (Exception $e) {
 echo "Error: " . $e->getMessage() . " ";
 } finally {
 echo "Process completed.";
 }
?>

RESULT

The result will be displayed here...

Built-in Methods of the Exception Object

When we catch an exception inside a catch block, we gain access to an object that contains precise data about where and why something went wrong. To retrieve this data, we use the following methods:

Exception(): The constructor used to create a new exception object (used as throw new Exception("Message")).
getMessage(): Returns the descriptive error message that was defined when the exception was thrown.
getCode(): Returns the numeric error code for easier identification or categorization of issues.
getFile(): Returns the full (absolute) path to the file where the exception occurred.
getLine(): Returns the exact line number that triggered the exception.
getTrace(): Returns a detailed array of all function calls and files that led up to the error.
try ... catch ... finally: The main structure for handling exceptions. The finally block is always executed (regardless of whether an error occurred or not), which is ideal for tasks like closing open files or database connections.

💡 When to use exceptions in practice?

Exceptions are not intended for ordinary syntax errors (like a forgotten semicolon). We use them to handle external, unpredictable situations that the programmer has no direct control over—for example, when a remote API server fails to return data, when a user uploads the wrong file type, or when a database connection drops. By catching the error, you can display a friendly notification to the user instead of a raw red system error page.