Errores en PHP

Encontrar errores es una parte normal de escribir PHP. Cuanto más rápido puedas leer un error y entender qué nivel es, por qué PHP lo generó y cómo responder, más rápido entregarás código funcional. Esta página explica los niveles de error de PHP (las constantes E_*), la diferencia entre errores y excepciones en PHP moderno, y un flujo de trabajo práctico para reportar, registrar y manejarlos.

Niveles de Error en PHP

Cuando PHP detecta un problema, lo eleva a un nivel específico, identificado por una constante E_*. El nivel indica la gravedad del problema y si el script continúa ejecutándose. Combinas estas constantes con error_reporting() y la directiva error_reporting de php.ini para decidir qué niveles se muestran o registran.

Estas son constantes de máscara de bits, por lo que se combinan con el operador OR a nivel de bits (|) y se excluyen niveles con & más ~:

<?php
// Report everything except notices and deprecations
error_reporting(E_ALL & ~E_NOTICE & ~E_DEPRECATED);

Importante: Desde PHP 8.0, muchas advertencias y avisos anteriores fueron promovidos a excepciones Error lanzadas (por ejemplo, leer una clave de array indefinida ahora genera una advertencia, mientras que llamar a un método indefinido lanza un Error). Saber si un problema es un error elevado o una excepción lanzada determina cómo capturarlo — ver más abajo.

Errores vs. Excepciones

PHP tiene dos mecanismos relacionados pero separados:

• Errores tradicionales son elevados por el motor y se enrutan a través de error_reporting, display_errors y un manejador opcional establecido con set_error_handler(). No son objetos que puedes capturar con catch (a menos que tu manejador los convierta).
• Excepciones son objetos que lanzas y capturas con bloques try/catch. Desde PHP 7, los problemas fatales del motor también se lanzan como objetos Error (como TypeError o DivisionByZeroError), y tanto Exception como Error implementan la interfaz Throwable — así que catch (\Throwable $e) captura todo lo que se puede capturar.

<?php
try {
    // intdiv() throws a DivisionByZeroError on division by zero
    echo intdiv(10, 0);
} catch (\Throwable $e) {
    echo get_class($e) . ": " . $e->getMessage();
}
// Output: DivisionByZeroError: Division by zero

Causas Comunes de Errores en PHP

La mayoría de los errores se deben a un pequeño conjunto de causas:

• Errores de sintaxis — un punto y coma faltante o un paréntesis desbalanceado (E_PARSE).
• Símbolos indefinidos — usar una variable, constante, función o clave de array que no existe.
• Incompatibilidades de tipo — pasar el tipo incorrecto a un parámetro tipado (lanza TypeError).
• Funcionalidades obsoletas — funciones o sintaxis programadas para eliminación (E_DEPRECATED).
• Límites de recursos — agotar memory_limit o alcanzar max_execution_time.
• Fallos externos — un archivo inexistente, o una conexión a base de datos/API que se rechaza o agota el tiempo.
• Excepciones no capturadas — un throw sin ningún catch correspondiente, que se convierte en un error fatal.

<?php
// Reading an undefined variable raises an E_WARNING and yields null
echo $undefined_variable ?? "fallback";
// Output: fallback

El operador de fusión de null (??) de arriba es la forma idiomática de leer un valor que podría ser indefinido sin generar una advertencia.

Configuración del Reporte de Errores

Controla qué niveles aparecen y a dónde van. En desarrollo, muestra todo; en producción, oculta los errores a los usuarios pero regístralos.

<?php
// Development: show all errors on screen
error_reporting(E_ALL);
ini_set('display_errors', '1');

// Production: hide from users, write to the error log instead
// error_reporting(E_ALL);
// ini_set('display_errors', '0');
// ini_set('log_errors', '1');

Las configuraciones equivalentes de php.ini son error_reporting, display_errors, log_errors y error_log. Para control programático consulta error_reporting() y para inspeccionar el error más reciente usa error_get_last().

Manejo de Errores en el Código

Hay tres herramientas complementarias:

1. Captura excepciones con try/catch para que un fallo recuperable no detenga el script:

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

try {
    echo safeDivide(10, 0);
} catch (InvalidArgumentException $e) {
    echo "Handled: " . $e->getMessage();
}
// Output: Handled: Cannot divide by zero

2. Instala un manejador de errores personalizado con set_error_handler() para convertir errores tradicionales en excepciones o registrarlos en tu propio formato:

<?php
set_error_handler(function (int $level, string $message, string $file, int $line) {
    // Turn a traditional warning/notice into an ErrorException so it can be caught
    throw new ErrorException($message, 0, $level, $file, $line);
});

try {
    // Reading a missing file raises an E_WARNING, now converted to an exception
    $contents = file_get_contents('/no/such/file.txt');
} catch (\Throwable $e) {
    echo "Caught: " . $e->getMessage();
}
// Output: Caught: file_get_contents(/no/such/file.txt): Failed to open stream: No such file or directory

3. Genera tus propios errores con trigger_error() para señalar problemas a nivel de aplicación a través del mismo canal que los errores del motor.

Buenas Prácticas

• Establece display_errors en 0 en producción — los rastros de pila expuestos son un riesgo de seguridad. Usa log_errors y un error_log configurado en su lugar.
• Desarrolla con error_reporting(E_ALL) para que los avisos y las deprecaciones aparezcan pronto.
• Prefiere catch (\Throwable $e) en el nivel superior para capturar tanto Exception como Error.
• Nunca silencies problemas con el operador @; corrige la causa o manéjala explícitamente.
• Centraliza el registro con error_log() para que cada fallo quede en un solo lugar.

Conclusión

Leer un error de PHP comienza con su nivel y si es un error elevado o una excepción lanzada. Con error_reporting() ajustado por entorno, un manejador personalizado que canaliza los errores al sistema de excepciones, y try/catch alrededor del código que puede fallar, puedes diagnosticar problemas rápidamente y mantener la producción resiliente. Continúa con Excepciones de PHP y error_reporting() para profundizar.

Práctica