Exceptions

Table of Contents

PHP 5 has an exception model similar to that of other programming languages. An exception can be thrown, and caught ("catched") within PHP. Code may be surrounded in a try block, to facilitate the catching of potential exceptions. Each try must have at least one corresponding catch or finally block.

The thrown object must be an instance of the Exception class or a subclass of Exception. Trying to throw an object that is not will result in a PHP Fatal Error.

catch

Multiple catch blocks can be used to catch different classes of exceptions. Normal execution (when no exception is thrown within the try block) will continue after that last catch block defined in sequence. Exceptions can be thrown (or re-thrown) within a catch block.

When an exception is thrown, code following the statement will not be executed, and PHP will attempt to find the first matching catch block. If an exception is not caught, a PHP Fatal Error will be issued with an "Uncaught Exception ..." message, unless a handler has been defined with set_exception_handler().

In PHP 7.1 and later, a catch block may specify multiple exceptions using the pipe (|) character. This is useful for when different exceptions from different class hierarchies are handled the same.

finally

In PHP 5.5 and later, a finally block may also be specified after or instead of catch blocks. Code within the finally block will always be executed after the try and catch blocks, regardless of whether an exception has been thrown, and before normal execution resumes.

Notes

Note:

Internal PHP functions mainly use Error reporting, only modern Object oriented extensions use exceptions. However, errors can be simply translated to exceptions with ErrorException.

Tip

The Standard PHP Library (SPL) provides a good number of built-in exceptions.

Examples

Example #3 Throwing an Exception

<?php
function inverse($x) {
    if (!
$x) {
        throw new 
Exception('Division by zero.');
    }
    return 
1/$x;
}

try {
    echo 
inverse(5) . "\n";
    echo 
inverse(0) . "\n";
} catch (
Exception $e) {
    echo 
'Caught exception: ',  $e->getMessage(), "\n";
}

// Continue execution
echo "Hello World\n";
?>

The above example will output:

0.2
Caught exception: Division by zero.
Hello World

Example #4 Exception handling with a finally block

<?php
function inverse($x) {
    if (!
$x) {
        throw new 
Exception('Division by zero.');
    }
    return 
1/$x;
}

try {
    echo 
inverse(5) . "\n";
} catch (
Exception $e) {
    echo 
'Caught exception: ',  $e->getMessage(), "\n";
finally {
    echo 
"First finally.\n";
}

try {
    echo 
inverse(0) . "\n";
} catch (
Exception $e) {
    echo 
'Caught exception: ',  $e->getMessage(), "\n";
finally {
    echo 
"Second finally.\n";
}

// Continue execution
echo "Hello World\n";
?>

The above example will output:

0.2
First finally.
Caught exception: Division by zero.
Second finally.
Hello World

Example #5 Nested Exception

<?php

class MyException extends Exception { }

class 
Test {
    public function 
testing() {
        try {
            try {
                throw new 
MyException('foo!');
            } catch (
MyException $e) {
                
// rethrow it
                
throw $e;
            }
        } catch (
Exception $e) {
            
var_dump($e->getMessage());
        }
    }
}

$foo = new Test;
$foo->testing();

?>

The above example will output:

string(4) "foo!"

Example #6 Multi catch exception handling

<?php

class MyException extends Exception { }

class 
MyOtherException extends Exception { }

class 
Test {
    public function 
testing() {
        try {
            throw new 
MyException();
        } catch (
MyException MyOtherException $e) {
            
var_dump(get_class($e));
        }
    }
}

$foo = new Test;
$foo->testing();

?>

The above example will output:

string(11) "MyException"
add a note add a note

User Contributed Notes 28 notes

up
185
zmunoz at gmail dot com
7 years ago
When catching an exception inside a namespace it is important that you escape to the global space:

<?php
namespace SomeNamespace;

class
SomeClass {

  function
SomeFunction() {
   try {
    throw new
Exception('Some Error Message');
   } catch (\
Exception $e) {
   
var_dump($e->getMessage());
   }
  }

}
?>
up
61
ask at nilpo dot com
8 years ago
If you intend on creating a lot of custom exceptions, you may find this code useful.  I've created an interface and an abstract exception class that ensures that all parts of the built-in Exception class are preserved in child classes.  It also properly pushes all information back to the parent constructor ensuring that nothing is lost.  This allows you to quickly create new exceptions on the fly.  It also overrides the default __toString method with a more thorough one.

<?php
interface IException
{
   
/* Protected methods inherited from Exception class */
   
public function getMessage();                 // Exception message
   
public function getCode();                    // User-defined Exception code
   
public function getFile();                    // Source filename
   
public function getLine();                    // Source line
   
public function getTrace();                   // An array of the backtrace()
   
public function getTraceAsString();           // Formated string of trace
   
    /* Overrideable methods inherited from Exception class */
   
public function __toString();                 // formated string for display
   
public function __construct($message = null, $code = 0);
}

abstract class
CustomException extends Exception implements IException
{
    protected
$message = 'Unknown exception';     // Exception message
   
private   $string;                            // Unknown
   
protected $code    = 0;                       // User-defined exception code
   
protected $file;                              // Source filename of exception
   
protected $line;                              // Source line of exception
   
private   $trace;                             // Unknown

   
public function __construct($message = null, $code = 0)
    {
        if (!
$message) {
            throw new
$this('Unknown '. get_class($this));
        }
       
parent::__construct($message, $code);
    }
   
    public function
__toString()
    {
        return
get_class($this) . " '{$this->message}' in {$this->file}({$this->line})\n"
                               
. "{$this->getTraceAsString()}";
    }
}
?>

Now you can create new exceptions in one line:

<?php
class TestException extends CustomException {}
?>

Here's a test that shows that all information is properly preserved throughout the backtrace.

<?php
function exceptionTest()
{
    try {
        throw new
TestException();
    }
    catch (
TestException $e) {
        echo
"Caught TestException ('{$e->getMessage()}')\n{$e}\n";
    }
    catch (
Exception $e) {
        echo
"Caught Exception ('{$e->getMessage()}')\n{$e}\n";
    }
}

echo
'<pre>' . exceptionTest() . '</pre>';
?>

Here's a sample output:

Caught TestException ('Unknown TestException')
TestException 'Unknown TestException' in C:\xampp\htdocs\CustomException\CustomException.php(31)
#0 C:\xampp\htdocs\CustomException\ExceptionTest.php(19): CustomException->__construct()
#1 C:\xampp\htdocs\CustomException\ExceptionTest.php(43): exceptionTest()
#2 {main}
up
68
Johan
6 years ago
Custom error handling on entire pages can avoid half rendered pages for the users:

<?php
ob_start
();
try {
   
/*contains all page logic
    and throws error if needed*/
   
...
} catch (
Exception $e) {
 
ob_end_clean();
 
displayErrorPage($e->getMessage());
}
?>
up
10
ohcc at 163 dot com
11 months ago
If a TRY has a FINALLY, a RETURN either in the TRY or a CATCH won't terminate the script. Code in the same block after the RETURN will not be executed, and the RETURN itself will be "copied" to the bottom of the FINALLY block to be executed.

a RETURN in the FINALLY block will override value(s) returned from the TRY or a CATCH block.

An EXIT or a DIE always terminate the script after themselves.

code 1

<?php
   
function foo(){
       
$bar = 1;
        try{
            throw new
Exception('I am Wu Xiancheng.');
        }catch(
Exception $e){
            return
$bar;
           
$bar--; // this line will be ignored
       
}finally{
           
$bar++;
        }
    }
    echo
foo(); // 2
?>

code 2

<?php
   
function foo(){
       
$bar = 1;
        try{
            throw new
Exception('I am Wu Xiancheng.');
        }catch(
Exception $e){
            return
$bar;
           
$bar--; // this line will be ignored
       
}finally{
           
$bar++;
            return
$bar;
        }
    }
    echo
foo(); //2
?>

code 3

<?php
   
function foo(){
       
$bar = 1;
        try{
            throw new
Exception('I am Wu Xiancheng.');
        }catch(
Exception $e){
            return
$bar;
           
$bar--; // this line will be ignored
       
}finally{
            return
100;
        }
    }
    echo
foo(); //100
?>
up
12
hweidmann at online dot de
1 year ago
catch doesn't check for the existence of the Exception class, so avoid typo.

<?php
  
class MyException extends Exception
  
{
      ...
   }

   try
   {
      throw new
MyException(...);
   }
   catch (
MuException $e) // <--- typo
  
{
      ...
   }
?>

You WON'T get
   Fatal error: Class MuException could not be loaded ...

You WILL get
   Fatal error: Uncaught exception 'MyException' ...
up
9
ohcc at 163 dot com
1 year ago
Type declarations will trigger Uncaught TypeError when a different type is passed. And it cannot be caught with the Exception class.
<?php
   
function xc(array $a){       
    }   
    try{
       
xc(4);
    }catch (
Exception $e){ // failed to catch it
       
echo $e->getMessage();
    }
?>

You should use TypeError instead for PHP 7+,

<?php
   
function xc(array $a){   
    }   
    try{
       
xc(4);
    }catch (
TypeError $e){
        echo
$e->getMessage();
    }
?>

In php version prior to 7.0, you should translate Catchable fatal errors to an exception and then catch it.

<?php
   
function exceptionErrorHandler($errNumber, $errStr, $errFile, $errLine ) {
        throw new
ErrorException($errStr, 0, $errNumber, $errFile, $errLine);
    }
   
set_error_handler('exceptionErrorHandler');
    function
s(array $a){       
    }
    try{
       
s(4);
    }catch (
Exception $e){
        echo
$e->getMessage();
    }
?>
up
24
php at marcuspope dot com
3 years ago
Using a return statement inside a finally block will override any other return statement or thrown exception from the try block and all defined catch blocks.   Code execution in the parent stack will continue as if the exception was never thrown. 

Frankly this is a good design decision because it means I can optionally dismiss all thrown exceptions from 1 or more catch blocks in one place, without having to nest my whole try block inside an additional (and otherwise needless) try/catch block.

This is the same behavior as Java, whereas C# throws a compile time error when a return statement exists inside a finally block.  So I figured it was worth pointing out to PHP devs who may not have any exposure to finally blocks or how other languages do it.

<?php

function asdf()
{
    try {
        throw new
Exception('error');
    }
    catch(
Exception $e) {
        echo
"An error occurred";
        throw
$e;
    }
   
finally {
               
//This overrides the exception as if it were never thrown
       
return "\nException erased";
    }
}

try {
    echo
asdf();
}
catch(
Exception $e) {
    echo
"\nResult: " . $e->getMessage();
}
?>

The output from above will look like this:

    An error occurred
    Exception erased

Without the return statement in the finally block it would look like this:

    An error occurred
    Result: error
up
21
jazfresh at hotmail.com
10 years ago
Sometimes you want a single catch() to catch multiple types of Exception. In a language like Python, you can specify multiple types in a catch(), but in PHP you can only specify one. This can be annoying when you want handle many different Exceptions with the same catch() block.

However, you can replicate the functionality somewhat, because catch(<classname> $var) will match the given <classname> *or any of it's sub-classes*.

For example:

<?php
class DisplayException extends Exception {};
class
FileException extends Exception {};
class
AccessControl extends FileException {}; // Sub-class of FileException
class IOError extends FileException {}; // Sub-class of FileException

try {
  if(!
is_readable($somefile))
     throw new
IOError("File is not readable!");
  if(!
user_has_access_to_file($someuser, $somefile))
     throw new
AccessControl("Permission denied!");
  if(!
display_file($somefile))
     throw new
DisplayException("Couldn't display file!");

} catch (
FileException $e) {
 
// This block will catch FileException, AccessControl or IOError exceptions, but not Exceptions or DisplayExceptions.
 
echo "File error: ".$e->getMessage();
  exit(
1);
}
?>

Corollary: If you want to catch *any* exception, no matter what the type, just use "catch(Exception $var)", because all exceptions are sub-classes of the built-in Exception.
up
14
jim at anderos dot com
3 years ago
If you are using a namespace, you must indicate the global namespace when using Exceptions.
<?php
namespace alpha;
function
foo(){
    throw new \
Exception("Something is wrong!");
   
// throw new Exception(""); will fail
}

try {
   
foo();
} catch( \
Exception $e ) {
   
// catch( Exception $e ) will give no warning, but will not catch Exception
   
echo "ERROR: $e";
}

?>
up
14
sander at rotorsolutions dot nl
4 years ago
Just an example why finally blocks are usefull (5.5)

<?php

//without catch
function example() {
  try {
   
//do something that throws an exeption
 
}
 
finally {
   
//this code will be executed even when the exception is executed
 
}
}

function
example2() {
  try {
    
//open sql connection check user as example
    
if(condition) {
        return
false;
     }
  }
 
finally {
   
//close the sql connection, this will be executed even if the return is called.
 
}
}

?>