Uma exceção, é um evento ou acontecimento não desejado que pode ocorrer durante a execução de nossos programas em PHP como: erros de acesso a memória, falhas ao abrir um arquivo e outros.

Quando esse tipo de evento acontece, um objeto de um tipo de exceção, de acordo com seu objetivo, é lançada para que seu tratamento seja feito. Esse objeto contém as informações sobre o erro como: mensagem, linha do erro e outros.

Para acompanhar esta parte do tutorial é necessário ter conhecimento do bloco Gerenciando Erros: Try-Catch.

Para lançarmos uma exceção em PHP, utilizamos a palavra reservada throw seguido da instância da exceção que desejamos como pode ser observado na sintaxe a seguir:

Sintaxe: método construtor

throw new nome_excecao(string $message = "", int $code = 0, ...)

Onde

throw: palavra reservada para lançar exceção
$message: mensagem de erro customizada para informação
$code: código do erro

Exemplo 1

//main.php
<?php
try{
       throw new Exception();
}
//catchs omitidos
?>

Saída

Fatal error: Uncaught Exception in ../code.php:2
Stack trace:
#0 {main}
  thrown in ../main.php on line 2

As classes nativas da linguagem PHP possuem suas próprias exceções que podem lançadas durante a execução de seus métodos.

Exceções em PHP herdam a classe Exception que por sua vez implementa os métodos da interface Throwable que incluindo os métodos básicos abaixo:

Sintaxe

$variavel_erro->nome_metodo();

Exemplo 1

<?php
    function funcao1(){
    	$codigoErro = -999;
    	throw new Exception("Um msg de exceção PHP",$codigoErro);
    }
    
    try{
    	funcao1();
    }
    catch(Exception $ex){
    	echo "getMessage: ",$ex->getMessage(),"\n";
    	echo "getCode: ",$ex->getCode(),"\n";
    	echo "getFile: ",$ex->getFile(),"\n";
    	echo "getLine: ",$ex->getLine(),"\n";
    	echo "__toString: ",$ex->__toString(),"\n";
    }
?>

Saída

getMessage: Um msg de exceção PHP
getCode: -999
getFile: main.php
getLine: 4
__toString: Exception: Um msg de exceção PHP in main.php:4
Stack trace:
#0 main.php(8): funcao1()
#1 {main}

O StackTrace é um pilha que armazena todas as chamadas de funções e métodos feitas em nossos programas até a linha em que a exceção foi lançada. Essas chamadas são armazenadas umas sobres as outras sendo a linha que lançou a exceção a última.

Exemplo 3

<?php
    function funcao1(){
        funcao2();
    }
    
    function funcao2(){
        funcao3();
    }
    function funcao3(){
         $var = 10/0;
    }
    
    try{
    	funcao1();
    }
    catch(DivisionByZeroError $ex){
    	echo "__toString: ",$ex->__toString(),"\n";
    }
?>

Saída

__toString: DivisionByZeroError: Division by zero in main.php:10
Stack trace:
#0 main.php(7): funcao3()
#1 main.php(3): funcao2()
#2 main.php(14): funcao1()
#3 {main}

No exemplo anterior, utilizamos o comando throw para lançar uma exceção explicitamente. Em alguns momentos, o tratamento da exceção não pode, por algum motivo, ser tratada em seu respectivo bloco catch.

Nessa situação acima, podemos relançar uma exceção para um escopo superior, para seu tratamento, utilizado o mesmo comando throw.

Sintaxe

try
{
    //código
}
catch(tipo_excecao $nome_objeto) 
{
    throw $nome_objeto; //relançando exceção
}

Exemplo 5

<?php
    function funcao1(){
        funcao2();
    }
    
    function funcao2(){
        funcao3();
    }
    function funcao3(){
        try { 
            $var = 10/0;
        }
        catch(Exception $ex){
            throw $ex;
        }
    }
    
    try
    {
    	funcao1();
    }
    catch(DivisionByZeroError $ex)
    {
    	echo "__toString: ",$ex->__toString(),"\n";
    }
?>

Saída

ERROR!
__toString: DivisionByZeroError: Division by zero in /tmp/exLM74wetK.php:11
Stack trace:
#0 /tmp/exLM74wetK.php(7): funcao3()
#1 /tmp/exLM74wetK.php(3): funcao2()
#2 /tmp/exLM74wetK.php(19): funcao1()
#3 {main}

Caso uma nova exceção seja lançada ou invés de relançada, as informações do stacktrace referentes ao erro anterior serão perdidas, "mascarando" assim o erro.

1. 22/08/2025 - revisão 3 - Ajustes: pontuais e sintaxes
2. 20/09/2024 - revisão 2 - Ajustes pontuais
3. 06/02/2024 - revisão 1 - correção em navegação e erros gramaticais
4. 04/09/2023 - versão inicial