Comprensión del método Exception::getLine() en PHP

Cuando algo falla en PHP, lo primero que generalmente necesitas saber es dónde falló. El método Exception::getLine() responde exactamente eso: te indica el número de línea en el que se creó el objeto de excepción. Combinado con getMessage() y getFile(), te proporciona un "qué y dónde" preciso para cualquier error que captures — lo cual es la base del registro y la depuración útiles.

Esta página cubre la firma del método, qué mide realmente, un ejemplo completo ejecutable y los errores comunes que confunden a los desarrolladores.

Sintaxis

final public Exception::getLine(): int

El método no recibe argumentos y devuelve un int. Está definido en la clase base Exception, por lo que toda excepción integrada (RuntimeException, InvalidArgumentException, TypeError, etc.) y cualquier excepción personalizada que escribas lo heredan. Como está declarado como final, no puedes sobreescribirlo en una subclase.

Qué significa realmente "línea"

Este es el aspecto más importante que debes comprender: getLine() devuelve la línea donde el objeto de excepción fue construido (el sitio de new Exception(...) / throw new ...), no la línea del problema subyacente ni la línea donde fue capturada.

Por lo tanto, si tu código llama a una función que lanza internamente, getLine() apunta a la instrucción throw dentro de esa función, no a tu llamada. Para rastrear el camino completo desde tu llamada hasta el lanzamiento, usa getTrace() o getTraceAsString() en su lugar.

Un ejemplo completo y ejecutable

El siguiente ejemplo define una función que lanza una excepción cuando falta un archivo, luego la captura e informa la ubicación:

<?php

function readFileContents(string $path): string
{
    if (!file_exists($path)) {
        throw new Exception("File not found: $path"); // this is line 6
    }

    return file_get_contents($path);
}

try {
    echo readFileContents('/no/such/file.txt');
} catch (Exception $e) {
    echo "Error on line " . $e->getLine() . ": " . $e->getMessage();
}

Salida:

Error on line 6: File not found: /no/such/file.txt

Observa que la línea reportada es 6 — la instrucción throw dentro de readFileContents() — aunque la llamada que la desencadenó está en la línea 13. Esa es la regla "sitio de construcción, no sitio de llamada" en acción.

Combinar getLine() con getFile()

Un número de línea solo es ambiguo en un proyecto de múltiples archivos, por lo que en el código real casi siempre lo imprimes junto con el nombre del archivo proveniente de getFile():

<?php

try {
    $age = -5;

    if ($age < 0) {
        throw new InvalidArgumentException("Age cannot be negative");
    }
} catch (Exception $e) {
    printf(
        "[%s] %s (line %d in %s)\n",
        get_class($e),
        $e->getMessage(),
        $e->getLine(),
        basename($e->getFile())
    );
}

Salida (el nombre del archivo depende de cómo nombres el script):

[InvalidArgumentException] Age cannot be negative (line 5 in script.php)

Aquí getLine() devuelve 5, la línea del throw dentro del bloque try. Capturar Exception funciona para InvalidArgumentException porque todo tipo de excepción extiende en última instancia Exception.

Cuándo usarlo

• Registro. Escribe getLine() y getFile() en tus entradas de registro para que un mensaje sin traza de pila siga siendo rastreable.
• Páginas de error personalizadas. En un entorno de desarrollo podrías mostrar la línea al desarrollador; en producción, regístrala pero muestra al usuario un mensaje genérico.
• Reenvolver excepciones. Cuando capturas una excepción de bajo nivel y relanzas una específica del dominio, registra el getLine()/getFile() original (o encadena con getPrevious()) para que no se pierda la causa raíz.

Errores comunes

• Esperar el sitio de llamada. Como se muestra arriba, getLine() es la ubicación del lanzamiento, no donde llamaste al código que lanza. Usa una traza para el camino completo.
• Leerlo sin capturar. getLine() es un método de instancia — solo puedes llamarlo en un objeto de excepción al que tengas referencia, típicamente el $e de un bloque catch.
• Confundirlo con getCode(). getCode() devuelve el código numérico de la excepción, un valor no relacionado que estableces al construir la excepción; no tiene nada que ver con los números de línea.

Conclusión

Exception::getLine() devuelve el número de línea entero donde se creó una excepción — una pieza de información de depuración pequeña pero esencial. Usado junto con getMessage(), getFile() y una traza de pila completa, te permite localizar y registrar errores con precisión. Para una visión más amplia sobre lanzar y capturar excepciones, consulta la guía sobre excepciones en PHP.

Práctica