A captura de erros na linguagem PHP é feito utilizando o bloco try-catch que pode ser visto na sintaxe abaixo:

Sintaxe

try
{
 //código que será testado
}
catch( tipo_excecao $variavel_erro )
{
 //código para tratamento de erro
}

Onde

try: possui um corpo de código que será executado
tipo_excecao: tipo de dado da exceção lançada, nativa ou do criada pelo usuário
$variavel_erro: nome do objeto que irá armazenar os dados do erro ocorrido
catch: possui um corpo de código que será executado caso algum erro ocorra em try

Quando esse bloco try-catch é utilizado, as declarações dentro do corpo do bloco try são executadas. Caso algum erro ocorra na execução, uma Exceção(Exception) é gerada e o fluxo de execução é desviado para o bloco catch que deve realizar os tratamentos.

O bloco catch é "alimentado" por um objeto, $variavel_erro, que contem as informações sobre a exceção ocorrida como mensagem, linha do erro, stacktrace e outros.

A linguagem PHP, além das diversas exceções nativas, permite a criação de exceções customizadas com atributos e métodos próprios.

Exemplo 1

<?php
try
{
	$var = 10/0; //divisão por zero
}
catch(DivisionByZeroError $ex)
{
	echo "ocorreu um erro";
}

Saída

ocorreu um erro

Como o bloco try pode conter várias declarações de código e essas podem gerar diferentes tipos de exceções, é possível capturar diferentes exceções no bloco catch. Isso é feito declarando um bloco catch para cada tipo de possível exceção.

Sintaxe

try
{
  //omitido
}
catch( tipo_excecao1 $variavel_erro )
{
 //tratamento
}
catch( tipo_excecao2 $variavel_erro )
{
 //tratamento
}
catch( tipo_excecaoN $variavel_erro )
{
 //tratamento
}

Onde

tipo_excecao: tipo de dado da exceção lançada.
$variavel_erro: nome do objeto que irá armazenar os dados do erro ocorrido.

Exemplo 2

<?php
try
{
	//$var = 10/0; //descomentar para DivisionByZeroError

    $var = 4;
    $var = $var >> -1; //-1 não é permitido ser utilizado com >> ou <<
}
catch(DivisionByZeroError $ex)
{
	echo "DivisionByZeroError";
}
catch(ArithmeticError $ex)
{
	echo "ArithmeticError";
}
?>

Saída

ArithmeticError

Os blocos catch devem ser declarados a partir das exceçòes menos genéricas até as mais genéricas. Dessa forma, uma exceção lançada no bloco try não seja capturada de forma errada. A exceção Exception é a "classe mãe" e é herdada por todas as exceptions.

Exemplo 3

//main.php
<?php
    try{
    //omitido
    }
    catch(ArithmeticException e ){
        //mais específica
    }
    catch(Exception e ){
        //mais genérica
    }
?>

Saída

-

Além dos blocos de código try e catch, existe mais um bloco de código chamado finally que nos permite que um bloco código sempre seja executado independente de ter ocorrido uma exceção ou não.

Após a execução do try ou catch, ocorrendo ou não uma exceção, o fluxo de execução é desviado para o bloco finally.

Sintaxe

try
{
   //corpo
}
catch( tipo_excecao $variavel_erro )
{
   //corpo
}
finally
{
  //corpo
}

O bloco finally, normalmente, é utilizado para liberar recursos como alocação de memória, arquivos físicos e outros recursos que estão sendo trabalhados no bloco try/catch.

Exemplo 4

<?php
    try
    {
    	$var = 10/0; //comentar para ArithmeticError
    
        $var = 4;
    }
    catch(DivisionByZeroError $ex){
    	echo "DivisionByZeroError\n";
    }
    finally {
        echo "finally";
    }
?>

Saída

DivisionByZeroError
finally

O bloco try-catch não deve ser codificado em todos os métodos de uma aplicação. Esse bloco deve ficar em pontos centrais em arquivos .php para exitar excessos de blocos try-catch e também facilitar o log dos erros.

Exemplo 5

<?php
//classe1.php
class classe1
{
	function metodo(){
		echo "classe1::metodo\n";
		//pode gerar exception
	}
}

//classe2.php
class classe2
{
	function metodo(){
		echo "classe2::metodo\n";
		//pode gerar exception
	}
}

function main()
{
	$cls1 = new classe1();
	$cls2 = new classe2();
	
	try
	{
		$cls1->metodo();
		$cls2->metodo();
	}
	catch(Exception $ex)
	{
		echo "ocorreu um erro";
		//tratamento
		//log
	}
}
main();
?>

Saída

metodo1
metodo2

O bloco try-catch não deve ser utilizar para tratamento de entrada de dados do usuário como campos vazios ou valores com formato inválidos que são condições normais de ocorrer.

Exemplo 6: uso incorreto

<?php
class classe1
{
	public $codigo;
	public $nome;
}

$cls = new classe1();

try
{
	//ENTRADA DO USUÁRIO OMITIDA
	
	if($cls->codigo == null)
	{
		//lançar exceção: "codigo não preenchido!"
	}
	if($cls->nome == null)
	{
		//lançar exceção: "nome não preenchido!"
	}
}
catch(Exception $ex)
{
	echo "ocorreu um erro";
	//tratamento
	//log
}
?>

1. 22/08/2025 - revisão 3 - Ajustes: pontuais e sintaxes; Adição: uso de try-catch
2. 20/09/2024 - revisão 2 - Ajustes pontuais em 'try-catch' e 'finally'; outros ajustes
3. 06/02/2024 - revisão 1 - correção em navegação e erros gramaticais
4. 04/09/2023 - versão inicial