Skip to content

7. Exceções e erros

Quando um método de uma classe encontra um erro irrecuperável (arquivo inexistente, banco de dados não conectado, conexão de rede interrompida), ele não exibe um erro em um console (arquivo, banco de dados), mas lança uma exceção. As exceções estendem a classe [\Exception]. Além das exceções, o funcionamento interno do PHP também lança erros cuja classe base é [\Error]. Ambas as classes implementam a interface [\Throwable].

O PHP 8 mudou fundamentalmente o tratamento de erros: muitas situações que produziam um simples aviso (e muitas vezes um resultado absurdo) no PHP 7 agora lançam um erro que pode ser capturado. Veremos isso ao longo dos exemplos.

7.1. Estrutura de diretórios dos scripts

Os scripts deste capítulo estão na pasta [scripts-console/exceptions]:

1
2
3
4
5
6
php8-oct-2026/scripts-console/exceptions
├── exceptions-01.php
├── exceptions-02.php
├── ...
├── exceptions-11.php
└── throwables.php

7.2. A interface [\Throwable]

A interface [\Throwable] é a seguinte (veja a documentação):

interface Throwable extends Stringable
{
    public function getMessage(): string;
    public function getCode(): int;
    public function getFile(): string;
    public function getLine(): int;
    public function getTrace(): array;
    public function getTraceAsString(): string;
    public function getPrevious(): ?Throwable;
    public function __toString(): string;
}

As funções dos métodos da interface são as seguintes:

Método
Finalidade
[getMessage]
Retorna a mensagem de erro
[getCode]
retorna o código de erro (um inteiro)
[getFile]
retorna o nome do arquivo em que o objeto foi criado
[getLine]
retorna o número da linha em que o objeto foi criado
[getTrace]
retorna a pilha de chamadas de funções como um array
[getTraceAsString]
retorna a pilha de chamadas como uma string
[getPrevious]
retorna o objeto [Throwable] anterior (encapsulado) ou [null]
[__toString]
retorna uma representação em string do objeto

Observe que a interface [Throwable] estende a interface [Stringable] discutida no capítulo sobre classes. Uma classe não pode implementar diretamente a interface [Throwable]; ela deve derivar de [\Exception] ou de [\Error].

7.3. Exceções e erros predefinidos no PHP 8

O script [throwables.php] a seguir exibe a estrutura em árvore das classes predefinidas que implementam a interface [Throwable]. Nós o usamos para obter uma lista exata, a do PHP 8.5, em vez de copiá-la da documentação. O leitor não perderá nada se não tentar entender seu código, que usa a API de reflexão do PHP (a classe [ReflectionClass] permite consultar o PHP sobre uma classe: seu nome, sua extensão de origem, suas interfaces etc.) e uma função recursiva:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// exibe a árvore das classes predefinidas que implementam a interface [Throwable]
// limitamo-nos às extensões sempre presentes no PHP 8.5:
// o núcleo (Core), a biblioteca padrão, a biblioteca SPL, JSON e Random
$extensions = ["Core", "standard", "SPL", "json", "random"];

// as classes predefinidas dessas extensões que implementam [Throwable]
$classes = array_filter(
    get_declared_classes(),
    function (string $class) use ($extensions): bool {
        $reflection = new ReflectionClass($class);
        return $reflection->isInternal()
            && $reflection->implementsInterface(Throwable::class)
            && in_array($reflection->getExtensionName(), $extensions, true);
    }
);
sort($classes);

// exibição recursiva das classes filhas da classe [$parent]
function display(?string $parent, array $classes, string $indentation): void
{
    // os filhos diretos de [$parent]
    $children = array_values(array_filter(
        $classes,
        fn(string $class): bool => (get_parent_class($class) ?: null) === $parent
    ));
    foreach ($children as $i => $child) {
        $last = $i === count($children) - 1;
        print $indentation . ($last ? "└── " : "├── ") . $child . "\n";
        display($child, $classes, $indentation . ($last ? "    " : "│   "));
    }
}

print "Throwable\n";
display(null, $classes, "");

Resultados:

> php throwables.php
Throwable
├── Error
│   ├── ArithmeticError
│   │   └── DivisionByZeroError
│   ├── AssertionError
│   ├── CompileError
│   │   └── ParseError
│   ├── FiberError
│   ├── Random\RandomError
│   │   └── Random\BrokenRandomEngineError
│   ├── TypeError
│   │   └── ArgumentCountError
│   ├── UnhandledMatchError
│   └── ValueError
└── Exception
    ├── ClosedGeneratorException
    ├── ErrorException
    ├── JsonException
    ├── LogicException
    │   ├── BadFunctionCallException
    │   │   └── BadMethodCallException
    │   ├── DomainException
    │   ├── InvalidArgumentException
    │   ├── LengthException
    │   └── OutOfRangeException
    ├── Random\RandomException
    ├── RequestParseBodyException
    └── RuntimeException
        ├── OutOfBoundsException
        ├── OverflowException
        ├── RangeException
        ├── UnderflowException
        └── UnexpectedValueException

Comentários

  • linha 13: a função [get_declared_classes] retorna uma lista de todas as classes conhecidas neste ponto, sejam predefinidas ou não;
  • Linhas 16–18: apenas as classes predefinidas (internas) são mantidas, aquelas que implementam a interface [Throwable] e pertencem a extensões sempre presentes no PHP 8.5 (linha 9). Outras extensões adicionam suas próprias exceções (por exemplo, [PDOException] para acesso a bancos de dados, que encontraremos mais adiante);
  • linhas 24–36: uma função recursiva que exibe as classes filhas diretas da classe [$parent], depois as filhas de cada uma delas, e assim por diante. A função [get_parent_class] retorna [false] para uma classe sem pai: o operador [?:] então transforma [false] em [null];
  • linha 29: uma arrow function (PHP 7.4), uma forma abreviada de função anônima reduzida a uma expressão;
  • linha 39: começamos pelas classes sem pai: [Error] e [Exception].

Os resultados mostram duas famílias:

  • a família [Exception]: são as exceções lançadas por bibliotecas e pelo código da aplicação. Ela inclui:
    • [ErrorException], que converte um aviso do PHP em uma exceção (vamos usá-la no final do capítulo);
    • [JsonException] (PHP 7.3), lançada por [json_encode] e [json_decode] com a opção [JSON_THROW_ON_ERROR];
    • [Random\RandomException] (PHP 8.2), disparada pelas funções de geração de números aleatórios;
    • as exceções da biblioteca SPL (Standard PHP Library), um conjunto de classes e interfaces criado para resolver problemas frequentemente encontrados pelos desenvolvedores. Elas formam duas subfamílias:
    • [LogicException] e suas derivadas: erros de programação que podem ser resolvidos corrigindo o código: argumento inválido ([InvalidArgumentException]), valor fora do intervalo esperado ([DomainException]), método inexistente ([BadMethodCallException])...;
    • [RuntimeException] e suas variantes: erros que só podem ser detectados em tempo de execução: índice fora dos limites ([OutOfBoundsException]), valor inesperado ([UnexpectedValueException]), capacidade excedida ([OverflowException])... ;
  • a família [Error]: são os erros lançados pelo próprio engine do PHP. Ela inclui:
    • [TypeError]: um valor não é do tipo esperado (parâmetro de função, atributo tipado, valor de retorno, operando de um operador etc.). Sua derivada, [ArgumentCountError], indica um número insuficiente de argumentos;
    • [ValueError] (PHP 8.0): um valor é do tipo correto, mas tem um valor inválido (por exemplo, um comprimento negativo ou zero);
    • [ArithmeticError] e sua derivada [DivisionByZeroError]: erros em operações aritméticas;
    • [UnhandledMatchError] (PHP 8.0): nenhum ramo da expressão [match] é adequado;
    • [AssertionError]: falha na asserção [assert];
    • [CompileError] e sua derivada [ParseError]: erro de sintaxe em um arquivo carregado por [require] ou [include];
    • [FiberError] (PHP 8.1) e [Random\RandomError] (PHP 8.2): erros relacionados a fibers e a geradores de números aleatórios, que não utilizaremos.

As duas famílias não têm relação entre si: uma cláusula [catch (\Exception $e)] não intercepta um erro [Error]. Apenas a interface [Throwable] as une.

7.4. Exemplo 1

O primeiro exemplo, [exceptions-01.php], mostra tanto um aviso quanto um erro do PHP:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// exibição de todos os erros
error_reporting(E_ALL);
ini_set("display_errors", "1");
// código --------
$var = [];
// chave desconhecida
print $var["abcd"];
// divisão por zero
$var = 7 / 0;
var_dump($var);
// array de limites fixos
$array = new \SplFixedArray(5);
$array[1] = 2;
$array[4] = "foo";
// índice fora dos limites
$array[5] = 8;

Comentários

  • Linha 7: o PHP é instruído a relatar todos os erros. O parâmetro da função [error_reporting] é o nível de relatório de erros. É uma combinação das seguintes constantes (as principais):
Constante
Significado
[E_ERROR]
Erro fatal em tempo de execução: o script é encerrado
[E_WARNING]
Aviso: o script continua
[E_PARSE]
Erro de sintaxe detectado durante a compilação
[E_NOTICE]
Nota: algo que pode ser um erro
[E_DEPRECATED]
Uso de um recurso obsoleto, que será removido em uma versão futura
[E_USER_WARNING], [E_USER_NOTICE], [E_USER_DEPRECATED]
Os mesmos níveis, disparados pelo código por meio da função [trigger_error]
[E_ALL]
todos os níveis
  • a constante [E_STRICT], que não corresponde mais a nenhuma mensagem desde o PHP 8.0, está obsoleta desde o PHP 8.4, assim como o uso do nível [E_USER_ERROR] com [trigger_error]: para sinalizar um erro fatal, o código lança uma exceção;
  • linha 8: o código é configurado para exibir os erros no console. Em produção, faz-se o oposto: os erros são gravados em um arquivo de log e não são exibidos;
  • linha 12: tenta-se acessar um elemento inexistente do array [$var];
  • linha 14: ocorre uma divisão por zero;
  • linha 17: é criada uma instância da classe [SplFixedArray] da biblioteca SPL. Essa classe permite criar um array de tamanho fixo com índices inteiros;
  • linha 21: tenta-se acessar um elemento inexistente do array.

Resultados:

1
2
3
4
5
6
7
8
> php exceptions-01.php

Warning: Undefined array key "abcd" in .../php8-oct-2026/scripts-console/exceptions/exceptions-01.php on line 12

Fatal error: Uncaught DivisionByZeroError: Division by zero in .../php8-oct-2026/scripts-console/exceptions/exceptions-01.php:14
Stack trace:
#0 {main}
  thrown in .../php8-oct-2026/scripts-console/exceptions/exceptions-01.php on line 14

Comentários sobre os resultados

  • linha 3: acessar uma chave inexistente em um array dispara um aviso de nível [E_WARNING] (era uma simples nota [E_NOTICE] no PHP 7). Isso não interrompe a execução do script;
  • Linhas 5–8: no PHP 7, dividir um número por zero disparava um aviso [E_WARNING] e retornava o valor [INF] (infinito). No PHP 8, o operador [/] dispara um erro do tipo [DivisionByZeroError]. Como ele não é capturado, interrompe a execução do script: trata-se de um erro fatal (Fatal error: Uncaught...). A mensagem exibe a pilha de chamadas (Stack trace) no momento do erro;
  • o código que segue a divisão não é executado: a tentativa de acessar um índice inexistente no array [SplFixedArray] não ocorre. Voltaremos a ver isso nos próximos exemplos.

7.5. Tratamento de exceções

O script [exceptions-02.php] demonstra como tratar exceções:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// exibimos todos os erros
error_reporting(E_ALL);
ini_set("display_errors", "1");
// envolvemos o código em um try / catch
try {
    $var = [];
    // chave desconhecida
    print $var["abcd"];
    // divisão por zero
    $var = 7 / 0;
    var_dump($var);
    // array de limites fixos
    $array = new \SplFixedArray(5);
    $array[1] = 2;
    $array[4] = "foo";
    // índice fora dos limites
    $array[5] = 8;
    // verificação
    print "this message will not be displayed\n";
} catch (\Throwable $ex) {
    // \Throwable é a interface implementada por todos os erros e exceções
    // exibimos a exceção
    print "error, message: " . $ex->getMessage() . ", type: " . $ex::class . "\n";
}

Comentários

  • O script é o apresentado no parágrafo anterior. No entanto, agora colocamos o código que pode causar erros dentro de uma estrutura [try / catch]: se o código das linhas 11–24 causar (lançar) uma exceção ou um erro, ele será tratado pela cláusula [catch] das linhas 25–29;
  • Linha 25: o parâmetro da cláusula [catch] é o tipo de exceção ou erro a tratar. Ao definir o tipo como [\Throwable], que é uma interface, indicamos que queremos tratar qualquer instância de classe que implemente a interface [\Throwable]. Como todas as classes de erro e de exceção implementam essa interface, a cláusula [catch] trata aqui todos os erros e exceções;
  • linha 15: a instrução que dispara o erro. Assim que ocorre uma exceção, o controle é transferido para a cláusula [catch]. O código que vem em seguida em [try] não é, portanto, executado;
  • linha 28: a notação [$ex::class] retorna o nome da classe do objeto [$ex].

Resultados:

1
2
3
4
> php exceptions-02.php

Warning: Undefined array key "abcd" in .../php8-oct-2026/scripts-console/exceptions/exceptions-02.php on line 13
error, message: Division by zero, type: DivisionByZeroError

Comentários sobre os resultados

  • Linha 3: vemos o aviso de nível [E_WARNING]. Um aviso não é uma exceção e, portanto, não é tratado pela cláusula [catch]. Veremos no final deste capítulo como converter avisos em exceções;
  • Linha 4: a mensagem de erro é escrita na cláusula [catch]. Isso significa que ocorreu uma exceção derivada de [\Exception] ou um erro derivado de [\Error] . Aqui vemos que se trata da classe [DivisionByZeroError]. O script terminou normalmente.

7.6. Parâmetros da cláusula [catch]

Vamos examinar o seguinte script [exceptions-03.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// exibimos todos os erros
error_reporting(E_ALL);
ini_set("display_errors", "1");

// um array de limites fixos
$array = new \SplFixedArray(5);
try {
    // índice fora dos limites
    $array[5] = 8;
} catch (\Throwable $ex) {
    // exibição da mensagem de erro
    print "Error 1: " . $ex->getMessage() . " (" . $ex::class . ")\n";
}

try {
    // índice fora dos limites
    $array[5] = 8;
} catch (\Exception $ex) {
    // exibição da mensagem de erro
    print "Error 2: " . $ex->getMessage() . "\n";
}

try {
    // índice fora dos limites
    $array[5] = 8;
} catch (\RuntimeException $ex) {
    // exibição da mensagem de erro
    print "Error 3: " . $ex->getMessage() . "\n";
}

try {
    // índice fora dos limites
    $array[5] = 8;
} catch (\OutOfBoundsException $ex) {
    // exibição da mensagem de erro
    print "Error 4: " . $ex->getMessage() . "\n";
}

try {
    // divisão por 0
    intdiv(5, 0);
} catch (\Throwable $ex) {
    // exibição da mensagem de erro
    print "Error 5: " . $ex->getMessage() . " (" . $ex::class . ")\n";
}

try {
    // divisão por 0
    intdiv(5, 0);
} catch (\DivisionByZeroError $ex) {
    // exibição da mensagem de erro
    print "Error 6: " . $ex->getMessage() . "\n";
}

try {
    // divisão por 0
    intdiv(5, 0);
} catch (\ArithmeticError $ex) {
    // exibição da mensagem de erro
    print "Error 7: " . $ex->getMessage() . "\n";
}

try {
    // divisão por 0
    intdiv(5, 0);
} catch (\Error $ex) {
    // exibição da mensagem de erro
    print "Error 8: " . $ex->getMessage() . "\n";
}

try {
    // divisão por 0
    intdiv(5, 0);
} catch (\Exception $ex) {
    // exibição da mensagem de erro
    print "Error 9: " . $ex->getMessage() . "\n";
}

Comentários

  • Linhas 11–41: quatro maneiras diferentes de tratar a exceção gerada pelo uso de um índice incorreto com a classe [\SplFixedArray]. A execução mostra que esse erro gera uma exceção do tipo [OutOfBoundsException] (linha 2 dos resultados). No curso de PHP 7 (e ainda no PHP 8.3), era uma exceção [RuntimeException]. A mudança não quebrou o código existente, pois a classe [OutOfBoundsException] deriva da classe [RuntimeException];
    • linha 15: trata um erro do tipo [\Throwable]. Isso é válido porque o tipo [OutOfBoundsException] deriva do tipo [\Exception], que implementa a interface [\Throwable];
    • linha 23: trata um erro do tipo [\Exception]. Isso é válido porque o tipo [OutOfBoundsException] deriva do tipo [\Exception];
    • linha 31: trata um erro do tipo [\RuntimeException]. Isso é válido porque o tipo [OutOfBoundsException] deriva do tipo [\RuntimeException]. É uma boa escolha: o código funciona independentemente da versão do PHP;
    • linha 39: trata o tipo exato da exceção gerada;
  • linhas 46–81: 5 maneiras diferentes de tratar o erro gerado pela função [intdiv] quando se passa a ela um divisor igual a 0. A função [intdiv(int $dividend, int $divisor): int] realiza a divisão inteira [$dividend / $divisor]. Quando o divisor é zero, o erro [\DivisionByZeroError] é lançado;
    • linha 47: qualquer erro que implemente a interface [\Throwable] é capturado. Isso é válido;
    • linha 55: o tipo exato do erro é interceptado; este é o método preferido;
    • linha 63: o tipo [\ArithmeticError] é capturado. Isso é válido, pois a classe [DivisionByZeroError] estende a classe [ArithmeticError];
    • Linha 71: o tipo [\Error] é interceptado. Isso é válido porque a classe [DivisionByZeroError] deriva da classe [Error];
    • Linha 79: o tipo [\Exception] é interceptado. Isso é inválido porque a classe [DivisionByZeroError] não tem nenhuma relação com a classe [\Exception].

Resultados:

> php exceptions-03.php
Error 1: Index invalid or out of range (OutOfBoundsException)
Error 2: Index invalid or out of range
Error 3: Index invalid or out of range
Error 4: Index invalid or out of range
Error 5: Division by zero (DivisionByZeroError)
Error 6: Division by zero
Error 7: Division by zero
Error 8: Division by zero

Fatal error: Uncaught DivisionByZeroError: Division by zero in .../php8-oct-2026/scripts-console/exceptions/exceptions-03.php:78
Stack trace:
#0 .../php8-oct-2026/scripts-console/exceptions/exceptions-03.php(78): intdiv(5, 0)
#1 {main}
  thrown in .../php8-oct-2026/scripts-console/exceptions/exceptions-03.php on line 78

As linhas 11–15 dos resultados mostram que o erro [DivisionByZeroError] não foi capturado pela última cláusula [catch (\Exception $ex)]: trata-se de um erro fatal.

7.7. A cláusula [finally]

A estrutura [try / catch] pode ter um terceiro elemento e tornar-se uma estrutura [try / catch / finally]. O código da cláusula [finally] é executado nos dois casos seguintes:

  • a cláusula [try] não lança uma exceção. Ela é então executada por inteiro, após o que a execução passa para a cláusula [finally], que é executada por inteiro;
  • a cláusula [try] lança uma exceção. Ela é então executada até a instrução que lança a exceção. A execução passa então para a cláusula [catch], que é executada por inteiro. Em seguida, a execução passa para a cláusula [finally], que é executada por inteiro.

Por fim, o código da cláusula [finally] ainda é executado. Esse cenário é útil no seguinte caso:

  • Na cláusula [try], o código adquiriu recursos (arquivos, bancos de dados, conexões de rede, filas). Esses recursos geralmente são caros. Eles devem, portanto, ser liberados (na maioria das vezes dizemos “fechados”) o mais rápido possível;
  • se os recursos foram adquiridos em [try], sua liberação será feita em [finally]. Isso garante que, em todos os casos (ocorrendo ou não um erro), os recursos adquiridos sejam devolvidos ao sistema.

O script a seguir, [exceptions-04.php], demonstra o funcionamento da cláusula [finally] em diversas situações:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// criamos uma instância de exceção
$e = new \Exception("Error...");

// primeiro teste
try {
    print "First test\n";
    throw $e;
} catch (\Exception $ex1) {
    print $ex1->getMessage() . "\n";
} finally {
    print "Done\n";
}

// segundo teste
try {
    print "Second test\n";
} catch (\Exception $ex1) {
    print $ex1->getMessage() . "\n";
} finally {
    print "Done\n";
}

// terceiro teste
try {
    print "Third test\n";
    return;
} catch (\Exception $ex1) {
    print $ex1->getMessage() . "\n";
} finally {
    print "Done\n";
}

Comentários sobre o código

  • Linha 7: [$e] é uma instância da classe predefinida [\Exception]. Vamos instanciá-la em diferentes pontos;
  • Linhas 11–12: a exceção [$e] é lançada em [try] pela instrução [throw];
  • linha 13: a exceção [\Exception] é capturada e sua mensagem de erro é escrita no console;
  • Linhas 15–16: a cláusula [finally] escreve uma mensagem. De acordo com o que foi dito anteriormente, essa mensagem deve ser sempre escrita, haja ou não um erro em [try];
  • linha 21: não há erro em [try]. Aqui também o programa deve passar para [finally];
  • Linha 31: há uma instrução [return] na cláusula [try], e nenhum erro. Surge a questão de saber se o script passará para a cláusula [finally]. A execução mostra que sim. Quando usada fora de uma função, a instrução [return] encerra o script.

Resultados:

1
2
3
4
5
6
7
8
> php exceptions-04.php
First test
Error...
Done
Second test
Done
Third test
Done

Vamos examinar outro caso, [exceptions-05.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// quarto teste
try {
    print "Fourth test\n";
    exit;
} finally {
    print "Done\n";
}

Comentários

  • Linha 9: a instrução [exit] encerra imediatamente a execução do script: a cláusula [finally] não é executada;
  • Linhas 7–12: um exemplo de [try / finally] sem a cláusula [catch]. Isso é possível.

Resultados:

> php exceptions-05.php
Fourth test

7.8. Criação de suas próprias classes de exceção

Em um projeto um pouco maior, é útil diferenciar os vários erros encapsulando-os em diferentes classes de exceção. Nos scripts anteriores, vimos que qualquer exceção podia ser capturada por uma cláusula [catch (\Throwable $ex)]. Isso é recomendado quando não se tem ideia do erro interceptado e o tratamento é o mesmo para todos os erros. Às vezes é o caso, mas muitas vezes é preciso adaptar o tratamento ao tipo exato de erro. Nesse caso, é necessário distinguir os diferentes erros.

Vamos examinar o seguinte script [exceptions-06.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// definimos nossa própria família de exceções
class Exception1 extends \RuntimeException
{
}

class Exception2 extends \RuntimeException
{
}

// usamos nossas exceções
$e1 = new Exception1("Error1...");
var_dump($e1);
$e2 = new Exception2("Error2...", 2);

// primeiro teste
print "first test\n";
try {
    // lançamos uma exceção do tipo Exception1
    throw $e1;
} catch (Exception1 $ex1) {
    print "Exception 1\n";
    print $ex1->getMessage() . "\n";
} catch (Exception2 $ex2) {
    print "Exception 2\n";
    print $ex2->getMessage() . "\n";
}

// segundo teste
print "second test\n";
try {
    // lançamos uma exceção do tipo Exception2
    throw $e2;
} catch (Exception1 $ex1) {
    print "Exception 1\n";
    print $ex1->getMessage() . "\n";
} catch (Exception2 $ex2) {
    print "Exception 2\n";
    print $ex2->getMessage() . "\n";
}

// terceiro teste
print "third test\n";
try {
    // lançamos uma exceção do tipo Exception1
    throw $e1;
} catch (Exception1 | Exception2 $ex) {
    print "Exception 1 or 2\n";
    print $ex->getMessage() . "\n";
}

// quarto teste
print "fourth test\n";
try {
    // lançamos uma exceção do tipo Exception2
    throw $e2;
} catch (Exception1 | Exception2 $ex) {
    print "Exception 1 or 2: " . $ex::class . "\n";
    // as informações transportadas pela exceção
    print "message: " . $ex->getMessage() . "\n";
    print "code: " . $ex->getCode() . "\n";
    print "file: " . basename($ex->getFile()) . "\n";
    print "line: " . $ex->getLine() . "\n";
}

Comentários

  • Linhas 7–9: definimos duas classes, *[Exception1] e *[Exception2], ambas derivadas da classe predefinida ***[\\RuntimeException]***. O corpo dessas classes é vazio. Em outras palavras, elas servem apenas por seus tipos: é porque têm tipos diferentes que poderemos distinguir essas duas exceções nas cláusulas [catch];
  • linhas 16–18: definimos duas variáveis, [$e1] e [$e2], que têm os tipos [Exception1] e [Exception2], respectivamente. O construtor utilizado é o da classe [Exception], cuja assinatura é [__construct(string $message = "", int $code = 0, ?Throwable $previous = null)]. Para [$e2], foi especificado um código de erro;
  • linhas 21–31: há uma estrutura [try / catch / catch]. Ela permite tratar diferentes tipos de exceção com diferentes cláusulas [catch]. A primeira cláusula cujo tipo corresponde é executada; as demais são ignoradas;
  • linha 25: intercepta exceções do tipo [Exception1];
  • linha 28: intercepta exceções do tipo [Exception2];
  • linha 51: intercepta exceções do tipo [Exception1] ou ([|]) [Exception2]. Essa sintaxe está disponível desde o PHP 7.1;
  • linha 62: o nome da classe da exceção interceptada;
  • linhas 64–67: as informações contidas na exceção, obtidas por meio dos métodos da interface [Throwable]. A função [basename] retorna um nome de arquivo sem o caminho da pasta.

Resultados:

> php exceptions-06.php
object(Exception1)#1 (7) {
  ["message":protected]=>
  string(9) "Error1..."
  ["string":"Exception":private]=>
  string(0) ""
  ["code":protected]=>
  int(0)
  ["file":protected]=>
  string(76) ".../php8-oct-2026/scripts-console/exceptions/exceptions-06.php"
  ["line":protected]=>
  int(16)
  ["trace":"Exception":private]=>
  array(0) {
  }
  ["previous":"Exception":private]=>
  NULL
}
first test
Exception 1
Error1...
second test
Exception 2
Error2...
third test
Exception 1 or 2
Error1...
fourth test
Exception 1 or 2: Exception2
message: Error2...
code: 2
file: exceptions-06.php
line: 18

Comentários sobre os resultados

  • Linhas 2–18: o “conteúdo” de uma exceção, exibido por [var_dump]:
    • linhas 3–4: a mensagem de erro;
    • linhas 7–8: o código de erro;
    • linhas 9–10: o nome do arquivo em que a exceção foi lançada. O comprimento indicado (string(76)) é o do caminho completo do arquivo: ele depende da pasta em que o script está localizado;
    • linhas 11–12: a linha em que a exceção foi lançada;
    • linhas 13–15: a pilha de chamadas no momento em que a exceção foi lançada. Ela está vazia aqui porque a exceção foi lançada no script principal e não dentro de uma função;
    • linhas 16–17: a exceção anterior. Uma exceção pode encapsular outra exceção, definindo assim uma pilha de exceções. O atributo [previous] permite analisar essa pilha;
  • linhas 29–33: observe que o arquivo e o número da linha da exceção são os da sua criação por [new] (linha 18) e não os do seu lançamento por [throw].

7.9. Relançamento de uma exceção

Uma exceção pode ser lançada várias vezes, como mostra o script a seguir, [exceptions-07.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

try {
    try {
        // lançamos uma exceção
        throw new \Exception("test");
    } catch (\Exception $ex) {
        // relançamos a exceção capturada
        throw $ex;
    } finally {
        // passamos pelo finally
        print "finally 1\n";
    }
} catch (\Exception $ex2) {
    // recuperamos a exceção inicial
    print $ex2->getMessage() . " in outer try / catch / finally\n";
} finally {
    // passamos pelo finally
    print "finally 2\n";
}

Comentários

  • linha 9: uma exceção é lançada;
  • linha 10: a exceção é capturada;
  • linha 12: a exceção é relançada. Ela é então repassada à estrutura [try / catch / finally] de nível superior. Esse cenário é comum: o código intercepta uma exceção para realizar um tratamento local (escrever um log, desfazer uma transação etc.) e depois a relança para que o código chamador também seja notificado;
  • linha 17: ela é interceptada novamente;
  • Linhas 13–15: a execução mostra que, mesmo após o [throw] da linha 12, o programa passa de fato para a cláusula [finally] do [try / catch / finally] interno.

Resultados:

1
2
3
4
> php exceptions-07.php
finally 1
test in outer try / catch / finally
finally 2

7.10. Tratamento de uma pilha de exceções

Uma exceção pode encapsular outra exceção, que por sua vez pode encapsular outra, formando por fim uma pilha de exceções. Eis um exemplo: [exceptions-08.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// definimos nossa própria família de exceções
class Exception1 extends \RuntimeException
{
}

class Exception2 extends \RuntimeException
{
}

class Exception3 extends \RuntimeException
{
}

// usamos nossas exceções
$e1 = new Exception1("Error 1...", 1, new Exception2("Error 2...", 2, new Exception3("Error 3...")));
var_dump($e1);
// uso da pilha de exceções
$e = $e1;
do {
    // mensagem de erro da exceção atual
    print $e::class . ": " . $e->getMessage() . "\n";
    // passamos para a exceção anterior (null se não houver)
    $e = $e->getPrevious();
} while ($e !== null);

Comentários

  • Linhas 7–15: definem três classes de exceção derivadas da exceção predefinida [RuntimeException];
  • linha 20: uma instância da classe [Exception3] é encapsulada dentro de uma instância da classe [Exception2], que por sua vez é encapsulada dentro de uma instância da classe [Exception1]. O construtor utilizado aqui é o da classe [Exception]: [__construct(string $message = "", int $code = 0, ?Throwable $previous = null)]. O terceiro parâmetro do construtor permite encapsular uma exceção. Isso pode ser útil no seguinte cenário:
    • define-se um método M que pode lançar uma exceção do tipo [Exception1], e somente desse tipo, por razões de compatibilidade, por exemplo com uma interface;
    • no entanto, outros tipos de exceção podem ocorrer dentro do método M. Para propagar um erro ao código que chama o método M, essas exceções são então encapsuladas no tipo [Exception1], que é então lançado. Isso garante que as informações contidas na exceção encapsulada, que foi a causa original do erro, não se percam;
  • Linhas 24–29: demonstram como percorrer a pilha de exceções aninhadas em uma exceção. O método [getPrevious] retorna a exceção encapsulada ou [null] se não houver nenhuma. O laço [do ... while] executa seu corpo pelo menos uma vez e depois continua enquanto a condição for verdadeira.

Resultados:

> php exceptions-08.php
object(Exception1)#1 (7) {
  ["message":protected]=>
  string(10) "Error 1..."
  ["string":"Exception":private]=>
  string(0) ""
  ["code":protected]=>
  int(1)
  ["file":protected]=>
  string(76) ".../php8-oct-2026/scripts-console/exceptions/exceptions-08.php"
  ["line":protected]=>
  int(20)
  ["trace":"Exception":private]=>
  array(0) {
  }
  ["previous":"Exception":private]=>
  object(Exception2)#2 (7) {
    ["message":protected]=>
    string(10) "Error 2..."
    ["string":"Exception":private]=>
    string(0) ""
    ["code":protected]=>
    int(2)
    ["file":protected]=>
    string(76) ".../php8-oct-2026/scripts-console/exceptions/exceptions-08.php"
    ["line":protected]=>
    int(20)
    ["trace":"Exception":private]=>
    array(0) {
    }
    ["previous":"Exception":private]=>
    object(Exception3)#3 (7) {
      ["message":protected]=>
      string(10) "Error 3..."
      ["string":"Exception":private]=>
      string(0) ""
      ["code":protected]=>
      int(0)
      ["file":protected]=>
      string(76) ".../php8-oct-2026/scripts-console/exceptions/exceptions-08.php"
      ["line":protected]=>
      int(20)
      ["trace":"Exception":private]=>
      array(0) {
      }
      ["previous":"Exception":private]=>
      NULL
    }
  }
}
Exception1: Error 1...
Exception2: Error 2...
Exception3: Error 3...
  • linhas 2–50: a exceção [$e1] contém, em seu atributo [previous], a exceção [Exception2] (linhas 17–49), que por sua vez contém a exceção [Exception3] (linhas 32–48);
  • linhas 51–53: o rastreamento da pilha da exceção.

7.11. Avisos do PHP 7 que se tornaram erros no PHP 8

Vimos que a divisão por zero, que produzia um aviso no PHP 7, dispara um erro no PHP 8. Esse não é um caso isolado: o PHP 8 converteu muitos avisos, que antes permitiam continuar a execução com um resultado falso, em erros. O script [exceptions-09.php] ilustra alguns deles:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// exibe o tipo e a mensagem de um erro
function display(int $n, \Throwable $ex): void
{
    print "$n - " . $ex::class . ": " . $ex->getMessage() . "\n";
}

// uma função com dois parâmetros
function sum(int $a, int $b): int
{
    return $a + $b;
}

// 1 - variável indefinida: um simples aviso (Notice no PHP 7, Warning no PHP 8)
print "1 - [" . $unknown . "]\n";
// 2 - módulo por zero: aviso + resultado errado no PHP 7, erro no PHP 8
try {
    print 1 % 0;
} catch (\DivisionByZeroError $ex) {
    display(2, $ex);
}
// 3 - operação aritmética sobre um array
try {
    print [] + 1;
} catch (\TypeError $ex) {
    display(3, $ex);
}
// 4 - operação aritmética sobre uma string não numérica
try {
    print "abc" * 2;
} catch (\TypeError $ex) {
    display(4, $ex);
}
// 5 - tipo de parâmetro incorreto para uma função predefinida
try {
    print strlen([1, 2]);
} catch (\TypeError $ex) {
    display(5, $ex);
}
// 6 - parâmetro do tipo certo, mas com um valor inválido
try {
    print_r(array_chunk([1, 2, 3], 0));
} catch (\ValueError $ex) {
    display(6, $ex);
}
// 7 - argumentos insuficientes
try {
    print sum(1);
} catch (\ArgumentCountError $ex) {
    display(7, $ex);
}
// 8 - expressão [match] sem um braço correspondente (PHP 8.0)
try {
    $day = 8;
    print match ($day) {
        6, 7 => "weekend",
        1, 2, 3, 4, 5 => "weekday",
    };
} catch (\UnhandledMatchError $ex) {
    display(8, $ex);
}
// 9 - método chamado em null
try {
    $object = null;
    $object->method();
} catch (\Error $ex) {
    display(9, $ex);
}
// 10 - o operador nullsafe ?-> evita o erro anterior: o resultado é null
var_dump($object?->method());

Resultados:

> php exceptions-09.php

Warning: Undefined variable $unknown in .../php8-oct-2026/scripts-console/exceptions/exceptions-09.php on line 19
1 - []
2 - DivisionByZeroError: Modulo by zero
3 - TypeError: Unsupported operand types: array + int
4 - TypeError: Unsupported operand types: string * int
5 - TypeError: strlen(): Argument #1 ($string) must be of type string, array given
6 - ValueError: array_chunk(): Argument #2 ($length) must be greater than 0
7 - ArgumentCountError: Too few arguments to function sum(), 1 passed in .../php8-oct-2026/scripts-console/exceptions/exceptions-09.php on line 52 and exactly 2 expected
8 - UnhandledMatchError: Unhandled match case 8
9 - Error: Call to a member function method() on null
NULL

Comentários

  • Linha 19: o uso de uma variável não definida continua sendo um simples aviso, mas no nível [E_WARNING] (era uma nota [E_NOTICE] no PHP 7). A variável é definida como [null], e o script continua (linhas 2–4 dos resultados);
  • linha 22: a divisão por zero dispara um erro [DivisionByZeroError] (linha 5). Isso já ocorria no PHP 7: apenas a divisão por zero com [/] produzia ali um simples aviso;
  • linha 28: uma operação aritmética sobre um array causa um erro [TypeError] (linha 6);
  • linha 34: no PHP 7, uma operação aritmética sobre uma string não numérica disparava o aviso “A non-numeric value encountered” e a string valia 0. No PHP 8, isso é um erro [TypeError] (linha 7). Uma string numérica (["12" * 2]) continua sendo aceita;
  • linha 40: no PHP 7, passar um parâmetro do tipo errado a uma função predefinida disparava um aviso, e a função retornava [null]. No PHP 8, todas as funções predefinidas lançam um erro [TypeError], assim como as funções escritas pelo desenvolvedor (linha 8). A mensagem identifica o parâmetro por seu número e nome;
  • linha 46: o parâmetro tem o tipo correto ([int]), mas um valor inválido (um comprimento deve ser positivo): trata-se do erro [ValueError], novo no PHP 8.0 (linha 9). No PHP 7, isso era um aviso;
  • linha 52: a função [sum] espera dois argumentos, mas recebe apenas um: erro [ArgumentCountError] (linha 10);
  • Linhas 59–62: a expressão [match] não tem nenhum ramo para o valor 8 e não tem ramo [default]: erro [UnhandledMatchError] (linha 11). Essa é uma diferença significativa em relação à instrução [switch], que não faz nada quando nenhum [case] é adequado;
  • linha 69: chamar um método em [null] resulta em um erro [Error] (linha 12). Isso já ocorria no PHP 7;
  • Linha 74: o operador null-safe [?->] (PHP 8.0) retorna [null] se o objeto for [null], em vez de chamar o método. Isso evita ter de escrever um teste [if ($object !== null)] (linha 13).

Essas mudanças tornam os programas PHP 8 mais seguros: um erro interrompe o processamento em vez de permitir que ele continue com dados incorretos. Elas também exigem que o desenvolvedor inclua as cláusulas [catch] correspondentes.

7.12. Vários [catch], [catch] sem variável e expressão [throw]

O script [exceptions-10.php] oferece três recursos do PHP 8 e um uso comum do tratamento de exceções:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// [throw] é uma expressão desde o PHP 8.0: pode ser usado após ?? ou em uma arrow function
function readAge(array $data): int
{
    $age = $data["age"] ?? throw new \InvalidArgumentException("The age is missing");
    return is_int($age) && $age >= 0 ? $age : throw new \DomainException("Invalid age [$age]");
}

// uma arrow function que apenas lança uma exceção
$forbidden = fn(string $operation) => throw new \LogicException("Operation [$operation] forbidden");

// dados de teste
$tests = [["age" => 48], [], ["age" => -4]];
foreach ($tests as $i => $data) {
    try {
        print "test $i: age=" . readAge($data) . "\n";
    } catch (\InvalidArgumentException | \DomainException $ex) {
        // uma única cláusula [catch] para dois tipos de exceção
        print "test $i: " . $ex::class . ": " . $ex->getMessage() . "\n";
    }
}

try {
    $forbidden("deletion");
} catch (\LogicException) {
    // desde o PHP 8.0, a variável da cláusula [catch] é opcional
    print "the operation was refused\n";
}

// encapsulamento de uma exceção de baixo nível em uma exceção da aplicação
class DaoException extends \RuntimeException
{
}

function readConfiguration(string $json): array
{
    try {
        return json_decode($json, true, flags: JSON_THROW_ON_ERROR);
    } catch (\JsonException $ex) {
        // a causa original é passada como 3º parâmetro: ela não se perde
        throw new DaoException("Unreadable configuration", 10, $ex);
    }
}

try {
    readConfiguration('{"dsn": "mysql:host=localhost"');
} catch (DaoException $ex) {
    print $ex::class . ": " . $ex->getMessage() . " (code " . $ex->getCode() . ")\n";
    print "cause: " . $ex->getPrevious()::class . ": " . $ex->getPrevious()->getMessage() . "\n";
}

Resultados:

1
2
3
4
5
6
7
> php exceptions-10.php
test 0: age=48
test 1: InvalidArgumentException: The age is missing
test 2: DomainException: Invalid age [-4]
the operation was refused
DaoException: Unreadable configuration (code 10)
cause: JsonException: Syntax error

Comentários

  • Linha 9: a partir do PHP 8.0, [throw] é uma expressão e não mais apenas uma instrução. Ela pode, portanto, ser usada onde quer que um valor seja esperado: aqui, após o operador [??]. Se a chave [age] não existir, uma exceção é lançada; caso contrário, [$age] recebe o valor dela;
  • linha 10: [throw] usado em uma expressão condicional [? :];
  • linha 14: uma arrow function cujo corpo simplesmente lança uma exceção. Antes do PHP 8.0, isso não era possível: uma arrow function só pode conter uma expressão;
  • linha 21: uma única cláusula [catch] para dois tipos de exceção (linhas 3–4 dos resultados). Observe que [InvalidArgumentException] e [DomainException] derivam ambas de [LogicException]: um [catch (\LogicException $ex)] teria tido o mesmo efeito;
  • linha 29: a partir do PHP 8.0, a variável da cláusula [catch] é opcional quando não precisamos da exceção em si, apenas do seu tipo (linha 5);
  • linhas 35–37: uma exceção específica da aplicação. Nos próximos capítulos, escreveremos camadas de acesso a dados (DAO, Data Access Object) que lançarão apenas esse tipo de exceção, independentemente da origem do erro (arquivo, JSON, banco de dados);
  • linhas 39–47: a função [readConfiguration] decodifica uma string JSON. A exceção de baixo nível [JsonException] é interceptada e encapsulada (linha 45) em uma exceção [DaoException]. A causa original é passada como terceiro parâmetro ao construtor;
  • linha 53: o código chamador conhece apenas [DaoException], mas pode recuperar a causa original do erro por meio do método [getPrevious] (linhas 6–7 dos resultados).

7.13. Converter avisos em exceções: [ErrorException]

Apesar das melhorias do PHP 8, certas anomalias continuam sendo meros avisos: chave de array inexistente, variável não definida, arquivo que não pode ser aberto com [fopen]... Esses avisos não podem ser interceptados por um [try / catch]. No entanto, é possível instalar um manipulador de erros que os converte em exceções [ErrorException]. É isso que o script [exceptions-11.php] faz:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// manipulador de erros: transforma os avisos do PHP em exceções [ErrorException]
set_error_handler(function (int $level, string $message, string $file, int $line): bool {
    throw new \ErrorException($message, 0, $level, $file, $line);
});

// uma chave desconhecida não causa mais um simples aviso, mas uma exceção
$person = ["lastName" => "Langevin"];
try {
    print $person["firstName"] . "\n";
} catch (\ErrorException $ex) {
    print "Error: " . $ex->getMessage() . " (line " . $ex->getLine() . ")\n";
    print "level E_WARNING: " . var_export($ex->getSeverity() === E_WARNING, true) . "\n";
}
// o mesmo vale para a abertura de um arquivo inexistente
try {
    $stream = fopen(__DIR__ . "/nonexistent.txt", "r");
} catch (\ErrorException $ex) {
    print "Error: " . $ex->getMessage() . "\n";
}
// voltamos ao manipulador de erros do PHP
restore_error_handler();
print "end\n";

Resultados:

1
2
3
4
5
> php exceptions-11.php
Error: Undefined array key "firstName" (line 14)
level E_WARNING: true
Error: fopen(.../php8-oct-2026/scripts-console/exceptions/nonexistent.txt): Failed to open stream: No such file or directory
end

Comentários

  • Linhas 7–9: a função [set_error_handler] define um manipulador de erros, uma função que o PHP chamará sempre que ocorrer um aviso, uma nota ou uma depreciação, em vez de exibir a mensagem. Ela recebe o nível do erro, a mensagem de erro, o arquivo e a linha em que o erro ocorreu. Aqui, ela lança uma exceção [ErrorException] que armazena essas informações. O tipo de retorno [bool] é o especificado na documentação de [set_error_handler]: a função retornaria [false] para deixar o PHP tratar o erro normalmente. Aqui ela nunca retorna nada, pois sempre lança uma exceção;
  • linha 14: a chave [firstName] não existe. Em vez de um aviso, é lançada uma exceção [ErrorException], que é capturada (linha 2 dos resultados);
  • linha 17: o método [getSeverity], específico da classe [ErrorException], retorna o nível do erro original (linha 3);
  • linha 21: tentar abrir um arquivo inexistente também resulta em uma exceção (linha 4);
  • linha 26: restaura o manipulador de erros anterior, neste caso o do PHP.

Essa técnica é usada por muitos frameworks PHP (Symfony, Laravel): durante o desenvolvimento, qualquer aviso se torna uma exceção, o que obriga o desenvolvedor a corrigir o código. A ferramenta de testes [PHPUnit] que usaremos mais adiante funciona de maneira semelhante: ela pode fazer um teste falhar se ele produzir um aviso ou uma depreciação.