getCode()

El método PHP getCode()

Cuando capturas una excepción en PHP, a menudo necesitas saber qué error ocurrió para poder reaccionar de forma diferente ante cada uno. El método Exception::getCode() te da exactamente eso: devuelve el código de error entero que se adjuntó a la excepción cuando fue creada. Esta página explica qué es el código, cómo establecerlo y leerlo, cómo se comporta en la jerarquía estándar de excepciones y los errores comunes que confunden a los desarrolladores.

Si eres nuevo en el manejo de errores, comienza con las excepciones de PHP y la sentencia try-catch, y luego vuelve aquí.

Qué es el código de excepción

Cada objeto de excepción de PHP lleva tres elementos de información esenciales: un mensaje (leído con getMessage()), una línea/archivo (leído con getLine()) y un código. El código es un valor definido por el desarrollador que se pasa como segundo argumento al constructor de la excepción:

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

getCode() simplemente devuelve ese segundo argumento. Es una etiqueta que tú eliges, no algo que PHP rellena automáticamente. Si no pasas un código, el valor predeterminado es 0.

Sintaxis

public Exception::getCode(): mixed

• Parámetros: ninguno.
• Valor de retorno: el código pasado al constructor. Para la clase base Exception, es un int (predeterminado 0).

Nota: el tipo de retorno está documentado como mixed porque ErrorException y algunas excepciones de PDO usan códigos string (por ejemplo, valores SQLSTATE). Para una Exception simple, espera un entero.

Ejemplo básico

Aquí lanzamos una excepción con el código 100 y luego lo leemos en el bloque catch:

<?php

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

Salida:

Message: Database connection failed
Code: 100

Observa que getCode() devuelve 100 — el valor que pasamos — mientras que getMessage() devuelve el texto. Los dos son independientes.

Bifurcación según el código

El propósito principal de un código es permitir que un único bloque catch dirija diferentes errores a diferentes manejadores. Los códigos de abajo son constantes arbitrarias elegidas para la aplicación:

<?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();
    }
}

Salida:

404: Invalid user id

Como llamamos a loadUser(0), la comprobación $id < 1 lanza primero con ERR_NOT_FOUND (404), por lo que ese case se ejecuta.

El código predeterminado es 0

Si creas una excepción sin un código, getCode() devuelve 0, no null:

<?php

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

Salida:

int(0)

Esto importa cuando bifurcas según el código: if ($e->getCode()) trata un código ausente (0) como falso, que generalmente es lo que quieres, pero sé deliberado al respecto.

Clases de excepción personalizadas

Un patrón común es integrar el código en una clase de excepción dedicada para que los llamadores nunca tengan que recordar el 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();
}

Salida:

404 User profile not found

El constructor de NotFoundException reenvía 404 a parent::__construct(), por lo que getCode() devuelve 404 aunque el código llamador nunca escribió ese número.

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

Estos son complementarios — la mayoría de los manejadores reales leen los tres.

Errores comunes

• El código debe ser un entero para Exception. Pasar un string (por ejemplo, new Exception("x", "ABC")) lanza un TypeError en PHP moderno. Usa una constante en su lugar.
• getCode() no es el código de estado HTTP. Solo es un código de estado si tú decidiste almacenar uno allí. PHP no hace nada con el valor en sí.
• Las excepciones integradas rara vez establecen un código significativo. La mayoría de las excepciones internas de PHP lo dejan en 0; no confíes en que esté relleno a menos que tú lo hayas establecido.
• Los códigos de PDOException son strings SQLSTATE. Al capturar errores de base de datos, getCode() puede devolver algo como "42S02" (un string), razón por la cual el tipo de retorno es mixed.

Buenas prácticas

1. Define constantes con nombre (o excepciones basadas en clases) para los códigos en lugar de dispersar números sin sentido.
2. Mantén los códigos estables — otro código y los registros pueden depender de ellos.
3. Registra el código junto con getMessage() y getLine() para que los fallos sean trazables.
4. No expongas códigos o mensajes internos a los usuarios finales; mapéalos a respuestas seguras y genéricas.

Conclusión

Exception::getCode() devuelve el código entero que adjuntaste cuando se creó la excepción, dándote una forma confiable y legible por máquina para distinguir un error de otro. Combínalo con getMessage() para obtener detalles legibles por humanos, prefiere constantes con nombre o clases de excepción personalizadas en lugar de números mágicos, y recuerda que algunos tipos de excepción (como PDOException) usan códigos string.

Práctica