PHP try catch: capturar exceções, finally e Throwable

Q: Como funciona o try catch no PHP?

O PHP executa o código dentro de try { }. Se algo ali lançar uma exceção, o PHP pula o resto do bloco try e executa o primeiro bloco catch cujo tipo bate, com o objeto lançado na variável: catch (Exception $e) { echo $e->getMessage(); }. Se nada for lançado, os blocos catch são pulados.

Q: Como capturo todas as exceções e erros no PHP?

Capture Throwable: catch (Throwable $e). catch (Exception $e) só captura exceções, não erros do motor como TypeError, ValueError ou DivisionByZeroError, que estendem Error. Tanto Exception quanto Error implementam Throwable.

Q: Como capturo várias exceções num único bloco catch no PHP?

Separe os tipos com uma barra vertical: catch (InvalidArgumentException | RangeException $e). Você também pode escrever vários blocos catch em sequência; o PHP usa o primeiro que bate, então coloque os tipos mais específicos primeiro.

Q: O finally roda se houver um return no try?

Sim. O finally roda depois de try e catch, tenha o código retornado, lançado uma exceção ou terminado normalmente, inclusive quando o try contém return. Se o próprio finally retornar um valor, esse valor substitui o do try, então evite return dentro do finally.

No PHP, você coloca o código que pode falhar dentro de try { ... } e trata a falha em catch (Exception $e) { ... }. Se qualquer coisa no bloco try lançar uma exceção, o PHP pula direto para o catch correspondente, e $e->getMessage() diz o que deu errado. Se nada for lançado, o bloco catch é pulado.

<?php
function divide(int $a, int $b): float
{
    if ($b === 0) {
        throw new InvalidArgumentException('Cannot divide by zero');
    }
    return $a / $b;
}

try {
    echo divide(10, 4), "\n";
    echo divide(10, 0), "\n";      // exception: the next line never runs
    echo "not printed\n";
} catch (InvalidArgumentException $e) {
    echo 'Error: ', $e->getMessage(), "\n";
}

echo "The script keeps going\n";

Troque divide(10, 0) por divide(10, 5) e rode de novo: nenhuma exceção, então not printed é impresso e o bloco catch é pulado. Sem try, a exceção encerraria o script com um erro fatal "Uncaught". Como lançar as suas próprias exceções e escrever classes de exceção está na página sobre exceções.

A sintaxe do try catch

A forma completa tem três partes. Só o try é obrigatório, mais pelo menos um catch ou um finally:

try {
    // code that may throw
} catch (SomeException $e) {
    // runs if SomeException (or a subclass) was thrown
} catch (OtherException | ThirdException $e) {
    // runs for either of these types
} finally {
    // always runs, thrown or not
}

O tipo no catch decide o que ele captura: a própria classe e todas as classes que a estendem. Desde o PHP 8.0, a variável é opcional quando você não precisa dela: catch (JsonException) { ... }.

Capturar Exception, Error ou Throwable

Desde o PHP 7, falhas que o próprio PHP detecta (chamar um método que não existe, um tipo de argumento errado, divisão por zero) lançam um Error, não uma Exception, e o PHP 8 transformou muitos warnings antigos em TypeError e ValueError. Os dois implementam a interface Throwable, mas nenhum estende o outro, então catch (Exception $e) não captura um Error:

Throwable
├── Exception                 (problems a program expects and handles)
│   ├── InvalidArgumentException, RuntimeException, JsonException, ...
└── Error                     (engine errors, usually a bug in the code)
    ├── TypeError
    ├── ValueError
    ├── ArithmeticError
    │   └── DivisionByZeroError
    └── UnhandledMatchError, ...

Rode isto para ver qual catch trata cada problema:

<?php
$problems = [
    'divide by zero' => fn () => 10 % 0,
    'wrong type'     => fn () => strlen([]),
    'bad value'      => fn () => str_repeat('x', -1),
    'missing method' => fn () => (new stdClass())->save(),
    'own exception'  => fn () => throw new RuntimeException('disk full'),
];

foreach ($problems as $label => $run) {
    try {
        $run();
    } catch (Exception $e) {
        echo "$label: caught as Exception (", get_class($e), ")\n";
    } catch (Error $e) {
        echo "$label: caught as Error (", get_class($e), ")\n";
    }
}

Então qual capturar?

catch (SomeSpecificException $e) quando você sabe o que pode dar errado e o que fazer a respeito. Isso é a maior parte do código.
catch (Exception $e) para "qualquer coisa que uma biblioteca ou o meu código lançou de propósito".
catch (Throwable $e) no nível mais externo (um handler de requisições, um executor de jobs) para registrar toda falha, incluindo os erros do próprio PHP, e mostrar uma mensagem amigável.

Capturar vários tipos de exceção

Escreva vários blocos catch para tratar tipos diferentes de jeitos diferentes. O PHP os testa de cima para baixo e usa o primeiro que bate, então um tipo específico precisa vir antes da classe pai, senão a classe pai captura tudo primeiro. Quando vários tipos recebem o mesmo tratamento, junte-os num catch com |:

<?php
function loadUser(mixed $id): array
{
    if (!is_int($id)) {
        throw new InvalidArgumentException("ID must be an integer, got " . get_debug_type($id));
    }
    if ($id < 1) {
        throw new DomainException("ID must be positive, got $id");
    }
    if ($id > 100) {
        throw new OutOfBoundsException("No user with ID $id");
    }
    return ['id' => $id, 'name' => 'User ' . $id];
}

foreach ([7, 'abc', -5, 500] as $id) {
    try {
        $user = loadUser($id);
        echo "Found {$user['name']}\n";
    } catch (OutOfBoundsException $e) {
        echo "404: {$e->getMessage()}\n";
    } catch (InvalidArgumentException | DomainException $e) {
        echo '400: ', $e->getMessage(), ' (', get_class($e), ")\n";
    }
}

As três classes estendem Exception, então um único catch (Exception $e) também as capturaria, mas aí o código não conseguiria mais responder 404 para uma e 400 para as outras.

finally: código que sempre roda

Um bloco finally roda depois de try e catch, não importa como terminaram: normalmente, com uma exceção capturada, com uma exceção que ninguém capturou ou com um return. É o lugar para liberar o que o bloco try adquiriu: fechar um arquivo, liberar um lock, parar um cronômetro.

<?php
function process(string $file): string
{
    $handle = fopen($file, 'w');
    echo "opened $file\n";
    try {
        fwrite($handle, "data\n");
        if ($file === 'bad.txt') {
            throw new RuntimeException('write check failed');
        }
        return 'saved';           // finally still runs before returning
    } finally {
        fclose($handle);
        echo "closed $file\n";
    }
}

echo process('good.txt'), "\n\n";

try {
    echo process('bad.txt'), "\n";
} catch (RuntimeException $e) {
    echo 'Failed: ', $e->getMessage(), "\n";
}

Para good.txt, o arquivo é fechado antes de saved ser impresso, porque o finally roda antes de a função de fato retornar. Para bad.txt não há catch dentro de process(): o finally fecha o arquivo, e depois a exceção continua até o catch de quem chamou.

Evite return dentro do finally: ele substitui o valor que o bloco try retornou e descarta em silêncio uma exceção que estava a caminho:

function f(): string
{
    try {
        return 'from try';
    } finally {
        return 'from finally';
    }
}

function g(): string
{
    try {
        throw new RuntimeException('lost');
    } finally {
        return 'no exception reaches the caller';
    }
}

echo f(); // from finally
echo g(); // no exception reaches the caller

Relançar ou envolver uma exceção

Às vezes um bloco catch só consegue tratar parte de um problema: registrar, limpar e depois deixá-lo seguir. throw $e; relança a mesma exceção. Mais comum é você querer adicionar contexto mantendo a causa original, e é para isso que serve o terceiro argumento do construtor, $previous:

<?php
class ConfigException extends RuntimeException {}

function readConfig(string $json): array
{
    try {
        return json_decode($json, true, flags: JSON_THROW_ON_ERROR);
    } catch (JsonException $e) {
        // Wrap: a clearer message, the original kept as "previous"
        throw new ConfigException('config.json is not valid JSON', 0, $e);
    }
}

try {
    print_r(readConfig('{"debug": true}'));
    readConfig('{"debug": true,}');
} catch (ConfigException $e) {
    echo $e->getMessage(), "\n";
    echo 'Caused by: ', get_class($e->getPrevious()), ': ', $e->getPrevious()->getMessage(), "\n";
}

Quem chama lida com uma ConfigException e não precisa saber que a configuração é JSON, enquanto getPrevious() guarda o detalhe de baixo nível para o log.

Exceções não capturadas e um handler global

Uma exceção que nenhum catch trata encerra o script com um erro fatal que inclui a classe, a mensagem, o arquivo e a linha, e um stack trace:

<?php
// No try/catch anywhere in this file
function charge(int $cents): void
{
    if ($cents <= 0) {
        throw new DomainException("Amount must be positive, got $cents");
    }
}

charge(500);
echo "first charge ok\n";
charge(-1);
echo "never printed\n";

O PHP imprime first charge ok e depois:

PHP Fatal error:  Uncaught DomainException: Amount must be positive, got -1 in /home/index.php:6
Stack trace:
#0 /home/index.php(12): charge()
#1 {main}
  thrown in /home/index.php on line 6

Num site no ar, essa mensagem nunca deve chegar aos visitantes. set_exception_handler() registra uma função que recebe qualquer exceção que ninguém capturou, um único lugar para registrá-la e imprimir uma página educada:

<?php
set_exception_handler(function (Throwable $e) {
    // In production: write $e to a log file here
    echo "<h1>Something went wrong</h1>\n";
    echo "<p>We have been notified. Please try again later.</p>\n";
    echo '<!-- ', get_class($e), ': ', htmlspecialchars($e->getMessage()), " -->\n";
});

echo "<p>Loading your dashboard...</p>\n";
throw new RuntimeException('Database timeout');

O handler roda e depois o script para; não há como continuar depois do throw. Se o texto de erro do próprio PHP aparece ou não na página é controlado pelo display_errors, explicado em exibição de erros.

Warnings não são exceções

O try/catch só vê o que é lançado. Muitas funções antigas do PHP não lançam nada: retornam false ou null e, no máximo, imprimem um warning. O json_decode() é um caso típico, e envolvê-lo num try não muda nada até você pedir que ele lance exceções:

<?php
$broken = '{"name": "Ada",}';

try {
    $data = json_decode($broken, true);
    var_dump($data);                    // NULL, and no exception
    echo 'Error: ', json_last_error_msg(), "\n";
} catch (JsonException $e) {
    echo "never reached\n";
}

try {
    $data = json_decode($broken, true, flags: JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo 'Caught: ', $e->getMessage(), "\n";
}

Para funções sem essa flag, verifique o valor de retorno (if ($handle === false)) ou verifique a pré-condição antes (file_exists(), isset()). Um set_error_handler() que lança ErrorException transforma todo warning numa exceção de verdade, se você quiser uma regra única para tudo.

Receita: validar entrada de formulário com exceções

Um padrão prático: as funções de validação lançam exceções, a página as captura e mostra a mensagem ao lado do formulário. Rode, digite uma idade no formulário e clique em Send: o mesmo script roda de novo com $_POST preenchido.

<?php
function validAge(string $raw): int
{
    if (trim($raw) === '') {
        throw new InvalidArgumentException('Please enter your age.');
    }
    $age = filter_var($raw, FILTER_VALIDATE_INT);
    if ($age === false) {
        throw new InvalidArgumentException('Age must be a whole number.');
    }
    if ($age < 13) {
        throw new RangeException('You must be at least 13 to sign up.');
    }
    return $age;
}

$raw = $_POST['age'] ?? '';
$message = '';

if (($_SERVER['REQUEST_METHOD'] ?? 'GET') === 'POST') {
    try {
        $age = validAge($raw);
        $message = "<p style=\"color:green\">Welcome, age $age accepted.</p>";
    } catch (InvalidArgumentException | RangeException $e) {
        $message = '<p style="color:red">' . htmlspecialchars($e->getMessage()) . '</p>';
    }
}
?>
<form method="post">
    <label>Age <input name="age" value="<?= htmlspecialchars($raw) ?>"></label>
    <button>Send</button>
</form>
<?= $message ?>

Teste um campo vazio, twelve, 9 e 30. Cada regra que falha lança uma exceção com a própria mensagem, e um único catch transforma todas na mesma linha vermelha. A página sobre formulários parte daqui com vários campos e erros ao lado de cada um.

Perguntas frequentes

Como funciona o try catch no PHP?

O PHP executa o código dentro de try { }. Se algo ali lançar uma exceção, o PHP pula o resto do bloco try e executa o primeiro bloco catch cujo tipo bate, com o objeto lançado na variável: catch (Exception $e) { echo $e->getMessage(); }. Se nada for lançado, os blocos catch são pulados.

Como capturo todas as exceções e erros no PHP?

Capture Throwable: catch (Throwable $e). catch (Exception $e) só captura exceções, não erros do motor como TypeError, ValueError ou DivisionByZeroError, que estendem Error. Tanto Exception quanto Error implementam Throwable.

Como capturo várias exceções num único bloco catch no PHP?

Separe os tipos com uma barra vertical: catch (InvalidArgumentException | RangeException $e). Você também pode escrever vários blocos catch em sequência; o PHP usa o primeiro que bate, então coloque os tipos mais específicos primeiro.

O finally roda se houver um return no try?

Sim. O finally roda depois de try e catch, tenha o código retornado, lançado uma exceção ou terminado normalmente, inclusive quando o try contém return. Se o próprio finally retornar um valor, esse valor substitui o do try, então evite return dentro do finally.

O try catch captura warnings no PHP?

Não. Warnings e notices (como ler uma chave de array ausente) não são exceções, então o catch nunca os vê. Verifique a condição antes da chamada, use o modo de exceção da função quando ela tiver um (json_decode(..., flags: JSON_THROW_ON_ERROR)), ou converta os warnings com set_error_handler() e ErrorException.

Conceitos relacionados