Manejo de Exceções PHP

A exceção (Exception) é usada para alterar o fluxo normal do script em situações de erro específicas.

O que é exceção?

O PHP 5 oferece um novo método de tratamento de erros orientado a objetos.

O tratamento de exceções é usado para alterar o fluxo normal do script em situações de erro (exceções) específicas. Essa situação é chamada de exceção.

Quando uma exceção é acionada, geralmente ocorre:

  • O estado atual do código é salvo
  • A execução do código é transferida para a função de gerenciador de exceções pré-definida
  • De acordo com a situação, o processador pode reiniciar a execução do código a partir do estado salvo, encerrar a execução do script ou continuar a execução do script de outra parte do código

Vamos mostrar diferentes métodos de tratamento de erros:

  • Uso básico de exceções
  • Criação de um gerenciador de exceções personalizado
  • Múltiplas exceções
  • Lançar exceção novamente
  • Configuração do gerenciador de exceções superior

Uso básico de exceções

Quando uma exceção é lançada, o código subsequente não continuará a ser executado; o PHP tentará encontrar um bloco de código "catch" correspondente.

Se a exceção não for capturada e não houver uso de set_exception_handler() para lidar com ela, ocorrerá um erro grave (erro fatal) e a mensagem de erro "Uncaught Exception" (exceção não capturada) será exibida.

Vamos tentar lançar uma exceção sem capturá-la:

<?php
//criar função com exceção
function checkNum($number)
 {
 if($number>1)
  {
  throw new Exception("O valor deve ser 1 ou abaixo");
  }
 return true;
 }
//acionar exceção
checkNum(2);
?>

O código acima gerará um erro semelhante ao seguinte:

Erro fatal: exceção não capturada 'Exception' 
com a mensagem 'Value must be 1 or below' em C:\webfolder\test.php:6 
Trace de pilha: #0 C:\webfolder\test.php(12): 
checkNum(28) #1 {main} lançado em C:\webfolder\test.php na linha 6

Try, throw e catch

Para evitar os erros apresentados no exemplo acima, precisamos criar código apropriado para lidar com exceções.

O gerenciador correto deve incluir:

  1. Tente - As funções que podem gerar exceções devem estar dentro de um bloco "try". Se nenhuma exceção for acionada, o código continuará a ser executado normalmente. No entanto, se uma exceção for acionada, uma exceção será lançada.
  2. Throw - Aqui se define como lançar uma exceção. Cada "throw" deve ter pelo menos um "catch" correspondente
  3. Catch - O bloco "catch" captura a exceção e cria um objeto que contém informações sobre a exceção

Vamos lançar uma exceção:

<?php
//Criar uma função que pode lançar uma exceção
function checkNum($number)
 {
 if($number>1)
  {
  throw new Exception("O valor deve ser 1 ou abaixo");
  }
 return true;
 }
//Lançar exceção dentro do bloco "try"
try
 {
 checkNum(2);
 //Se a exceção for lançada, esse texto não será exibido
 echo 'Se você vir isso, o número é 1 ou abaixo';
 }
//Capturar exceção
catch(Exception $e)
 {
 echo 'Mensagem: ' . $e->getMessage();
 }
?>

O código acima gerará um erro semelhante a este:

Mensagem: O valor deve ser 1 ou abaixo

Exemplo de explicação:

O código acima lança uma exceção e a captura:

  1. Criamos a função checkNum(). Ela verifica se o número é maior que 1. Se for, lança uma exceção.
  2. Chamamos a função checkNum() dentro do bloco "try".
  3. A exceção no função checkNum() é lançada
  4. O bloco "catch" recebe essa exceção e cria um objeto que contém informações sobre a exceção ($e).
  5. Através da chamada $e->getMessage() do objeto exception, você pode exibir a mensagem de erro dessa exceção.

No entanto, para seguir o princípio de "cada throw deve ter um catch correspondente", você pode configurar um manipulador de exceções de nível superior para lidar com erros omitidos.

Criar uma classe Exception personalizada

Criar um manipulador de exceções personalizado é muito simples. Criamos simplesmente uma classe específica que pode chamar suas funções quando ocorrer uma exceção no PHP. Essa classe deve ser uma extensão da classe exception.

Essa classe exception personalizada herda todas as propriedades da classe exception do PHP, você pode adicionar funções personalizadas a ela.

Começamos a criar a classe exception:

<?php
class customException extends Exception
 {
 public function errorMessage()
  {
  //mensagem de erro
  $errorMsg = 'Erro na linha '.$this->getLine().' no arquivo '.$this->getFile()
  : <b>'.$this->getMessage().'</b> não é um endereço de e-mail válido
  return $errorMsg;
  }
 }
$email = "someone@example...com";
try
 {
 //verificar se 
 if(filter_var($email, FILTER_VALIDATE_EMAIL) === FALSE)
  {
  //lança exceção se o e-mail não for válido
  throw new customException($email);
  }
 }
catch (customException $e)
 {
 //exibir mensagem personalizada
 echo $e->errorMessage();
 }
?>

Essa nova classe é uma cópia da antiga classe de exceção, mais a função errorMessage(). Devido a ser uma cópia da antiga classe, ela herda atributos e métodos da antiga classe, podemos usar métodos da classe exceção, como getLine(), getFile() e getMessage().

Exemplo de explicação:

O código acima lançou uma exceção e a capturou através de uma classe de exceção personalizada:

  1. A classe customException foi criada como uma extensão da antiga classe exception. Dessa forma, ela herda todas as propriedades e métodos da classe antiga.
  2. Crie a função errorMessage(). Se o endereço de e-mail for inválido, essa função retorna uma mensagem de erro
  3. Defina a variável $email como uma string de e-mail inválida
  4. Execute o bloco de código "try", devido ao endereço de e-mail ser inválido, uma exceção será lançada
  5. O bloco "catch" captura a exceção e exibe a mensagem de erro

Múltiplas exceções

Você pode usar várias exceções para um único script para detectar várias situações.

Você pode usar vários blocos if..else ou um bloco switch, ou aninhar várias exceções. Essas exceções podem usar diferentes classes de exceção e retornar mensagens de erro diferentes:

<?php
class customException extends Exception
{
public function errorMessage()
{
//mensagem de erro
$errorMsg = 'Erro na linha '.$this->getLine().' no arquivo '.$this->getFile()
: <b>'.$this->getMessage().'</b> não é um endereço de e-mail válido
return $errorMsg;
}
}
$email = "someone@example.com";
try
 {
 //verificar se 
 if(filter_var($email, FILTER_VALIDATE_EMAIL) === FALSE)
  {
  //lança exceção se o e-mail não for válido
  throw new customException($email);
  }
 //verificar se "example" está presente no endereço de e-mail
 if(strpos($email, "example") !== FALSE)
  {
  throw new Exception("$email é um e-mail exemplo");
  }
 }
catch (customException $e)
 {
 echo $e->errorMessage();
 }
catch(Exception $e)
 {
 echo $e->getMessage();
 }
?>

Exemplo de explicação:

O código acima testou duas condições, e se nenhuma das condições for cumprida, uma exceção será lançada:

  1. A classe customException foi criada como uma extensão da antiga classe exception. Dessa forma, ela herda todas as propriedades e métodos da classe antiga.
  2. Foi criada a função errorMessage(). Se o endereço de e-mail não for válido, a função retorna uma mensagem de erro.
  3. Execute o bloco de código "try", sob a primeira condição, não será lançada exceção.
  4. Devido ao e-mail conter a string "example", a segunda condição acionará a exceção.
  5. O bloco "catch" captura a exceção e exibe a mensagem de erro apropriada

Se não capturou a exceção customException e apenas capturou a exceção base, então é lá que você deve lidar com a exceção.

Lançar exceção novamente

Às vezes, quando uma exceção é lançada, você pode desejar tratá-la de uma maneira diferente da padrão. Você pode lançar a exceção novamente dentro de um bloco "catch".

O script deve ocultar os erros do sistema para o usuário. Embora os erros do sistema possam ser importantes para os programadores, os usuários não se interessam por eles. Para tornar o uso mais fácil para o usuário, você pode lançar exceções com mensagens mais amigáveis para o usuário:

<?php
class customException extends Exception
 {
 public function errorMessage()
  {
  //mensagem de erro
  $errorMsg = $this->getMessage().' não é um endereço de e-mail válido.';
  return $errorMsg;
  }
 }
$email = "someone@example.com";
try
 {
 try
  {
  //verificar se "example" está presente no endereço de e-mail
  if(strpos($email, "example") !== FALSE)
   {
   //lança exceção se o e-mail não for válido
   throw new Exception($email);
   }
  }
 catch(Exception $e)
  {
  //re-throw exceção
  throw new customException($email);
  }
 }
catch (customException $e)
 {
 //exibir mensagem personalizada
 echo $e->errorMessage();
 }
?>

Exemplo de explicação:

O código acima detecta se a string "example" está presente no endereço de e-mail. Se estiver, lança a exceção novamente:

  1. A classe customException foi criada como uma extensão da antiga classe exception. Dessa forma, ela herda todas as propriedades e métodos da classe antiga.
  2. Foi criada a função errorMessage(). Se o endereço de e-mail não for válido, a função retorna uma mensagem de erro.
  3. A variável $email foi configurada como um endereço de e-mail válido, mas contém a string "example".
  4. O bloco de código "try" contém outro bloco "try", permitindo que a exceção seja lançada novamente.
  5. A exceção foi acionada devido à string "example" contida no e-mail.
  6. "catch" capturou a exceção e re-throwou "customException".
  7. Capturado "customException" e exibido uma mensagem de erro.

Se uma exceção não for capturada no bloco try atual, ela será procurada em níveis superiores para um bloco catch.

Configuração do Tratador de Exceções de Nível Superior

A função set_exception_handler() pode definir um função personalizada para tratar todas as exceções não capturadas.

<?php
function myException($exception)
{
echo "<b>Exception:</b> " , $exception->getMessage();
}
set_exception_handler('myException');
throw new Exception('Exceção Não Capturada Ocorreu');
?>

A saída do código acima deve ser semelhante a esta:

Exception: Exceção Não Capturada Ocorreu

No código acima, não existe bloco catch, mas é acionado o programa de tratamento de exceções de nível superior. Deve-se usar essa função para capturar todas as exceções não capturadas.

Regras de Exceção

  • O código que necessita de tratamento de exceções deve ser colocado dentro de um bloco try, para que possam ser capturadas exceções potenciais.
  • Cada bloco try ou throw deve ter pelo menos um bloco catch correspondente.
  • A utilização de múltiplos blocos catch permite capturar diferentes tipos de exceções.
  • É possível lançar novamente (re-throw) uma exceção dentro do bloco de código catch.

Em resumo: se uma exceção for lançada, ela deve ser capturada.