getCode()

O Método PHP getCode()

Quando você captura uma exceção em PHP, muitas vezes precisa saber qual erro ocorreu para reagir de forma diferente a cada um. O método Exception::getCode() fornece exatamente isso: ele retorna o código de erro inteiro que foi vinculado à exceção quando ela foi criada. Esta página aborda o que é o código, como defini-lo e lê-lo, como ele se comporta na hierarquia padrão de exceções e os problemas comuns que costumam confundir os desenvolvedores.

Se você é novo no tratamento de erros, comece com exceções PHP e a instrução try-catch, e depois volte aqui.

O que é o código de exceção

Todo objeto de exceção PHP carrega três informações principais: uma mensagem (lida com getMessage()), uma linha/arquivo (lida com getLine()) e um código. O código é um valor definido pelo desenvolvedor que você passa como o segundo argumento para o construtor da exceção:

new Exception(string $message = "", int $code = 0, ?Throwable $previous = null)

getCode() simplesmente retorna esse segundo argumento. É um rótulo que você escolhe, não algo que PHP preenche automaticamente. Se você não passar um código, o padrão é 0.

Sintaxe

public Exception::getCode(): mixed

• Parâmetros: nenhum.
• Valor de retorno: o código passado ao construtor. Para a classe base Exception, é um int (padrão 0).

Nota: o tipo de retorno é documentado como mixed porque ErrorException e algumas exceções PDO usam códigos string (por exemplo, valores SQLSTATE). Para uma Exception simples, espere um inteiro.

Exemplo básico

Aqui lançamos uma exceção com o código 100 e depois o lemos no bloco catch:

<?php

try {
    throw new Exception("Database connection failed", 100);
} catch (Exception $e) {
    echo "Message: " . $e->getMessage() . "\n";
    echo "Code: " . $e->getCode() . "\n";
}

Saída:

Message: Database connection failed
Code: 100

Observe que getCode() retorna 100 — o valor que passamos — enquanto getMessage() retorna o texto. Os dois são independentes.

Ramificando pelo código

O objetivo de um código é permitir que um único bloco catch direcione erros diferentes para tratamentos distintos. Os códigos abaixo são constantes arbitrárias escolhidas para a aplicação:

<?php

const ERR_DB        = 100;
const ERR_NOT_FOUND = 404;

function loadUser(int $id): string
{
    if ($id < 1) {
        throw new Exception("Invalid user id", ERR_NOT_FOUND);
    }
    // ...imagine a DB lookup that fails...
    throw new Exception("Could not reach the database", ERR_DB);
}

try {
    echo loadUser(0);
} catch (Exception $e) {
    switch ($e->getCode()) {
        case ERR_NOT_FOUND:
            echo "404: " . $e->getMessage();
            break;
        case ERR_DB:
            echo "500: " . $e->getMessage();
            break;
        default:
            echo "Unknown error: " . $e->getMessage();
    }
}

Saída:

404: Invalid user id

Como chamamos loadUser(0), a verificação $id < 1 lança primeiro com ERR_NOT_FOUND (404), então esse case é executado.

O código padrão é 0

Se você criar uma exceção sem um código, getCode() retorna 0, não null:

<?php

try {
    throw new Exception("Something went wrong");
} catch (Exception $e) {
    var_dump($e->getCode());
}

Saída:

int(0)

Isso importa quando você ramifica pelo código: if ($e->getCode()) trata um código ausente (0) como falso, o que normalmente é o comportamento desejado, mas seja deliberado sobre isso.

Classes de exceção personalizadas

Um padrão comum é incorporar o código em uma classe de exceção dedicada para que os chamadores nunca precisem lembrar o número mágico:

<?php

class HttpException extends Exception {}

class NotFoundException extends HttpException
{
    public function __construct(string $message = "Not Found")
    {
        parent::__construct($message, 404);
    }
}

try {
    throw new NotFoundException("User profile not found");
} catch (HttpException $e) {
    echo $e->getCode() . " " . $e->getMessage();
}

Saída:

404 User profile not found

O construtor de NotFoundException encaminha 404 para parent::__construct(), então getCode() retorna 404 mesmo que o código chamador nunca tenha digitado esse número.

getCode() vs. getMessage() vs. getPrevious()

Esses métodos são complementares — a maioria dos manipuladores reais lê os três.

Problemas comuns

• O código deve ser um inteiro para Exception. Passar uma string (ex.: new Exception("x", "ABC")) lança um TypeError no PHP moderno. Use uma constante em vez disso.
• getCode() não é o código de status HTTP. É apenas um código de status se você escolheu armazenar um lá. O PHP não faz nada com o valor em si.
• Exceções integradas raramente definem um código significativo. A maioria das exceções do núcleo do PHP o deixa em 0; não confie que ele esteja preenchido a menos que você o tenha definido.
• Códigos de PDOException são strings SQLSTATE. Ao capturar erros de banco de dados, getCode() pode retornar algo como "42S02" (uma string), razão pela qual o tipo de retorno é mixed.

Boas práticas

1. Defina constantes nomeadas (ou classes de exceção baseadas em classe) para os códigos em vez de espalhar números brutos.
2. Mantenha os códigos estáveis — outros códigos e logs podem depender deles.
3. Registre o código junto com getMessage() e getLine() para que as falhas sejam rastreáveis.
4. Não exponha códigos ou mensagens internas aos usuários finais; mapeie-os para respostas genéricas e seguras.

Conclusão

Exception::getCode() retorna o código inteiro que você vinculou quando a exceção foi criada, fornecendo uma maneira confiável e legível por máquina de distinguir um erro de outro. Combine-o com getMessage() para detalhes legíveis por humanos, prefira constantes nomeadas ou classes de exceção personalizadas em vez de números mágicos, e lembre-se de que alguns tipos de exceção (como PDOException) usam códigos string.

Prática