Mostrar errores en PHP: display_errors y E_ALL

Para mostrar los errores de PHP, pon estas líneas al principio de tu script: ini_set('display_errors', '1'); y error_reporting(E_ALL);. La primera hace que PHP imprima los mensajes de error; la segunda, que informe de todos los tipos de error, incluidos los warnings y los avisos de obsolescencia.

<?php
ini_set('display_errors', '1');
ini_set('display_startup_errors', '1');
error_reporting(E_ALL);

Con eso, un fallo como leer una variable que nunca se definió imprime un mensaje con el archivo y el número de línea en lugar de fallar en silencio:

Warning: Undefined variable $total in /home/index.php on line 7

error_reporting() llamado sin argumentos devuelve la configuración actual como número. Pulsa Ejecutar para fijar un nivel y traducirlo de vuelta a nombres:

<?php
error_reporting(E_ALL & ~E_DEPRECATED);
$level = error_reporting();

echo "Current level: $level (E_ALL is " . E_ALL . ")\n";

foreach (get_defined_constants(true)['Core'] as $name => $value) {
    if (str_starts_with($name, 'E_') && $name !== 'E_ALL') {
        echo str_pad($name, 20), ($level & $value) ? "reported" : "off", "\n";
    }
}

Cada tipo de error es un bit, así que E_ALL & ~E_DEPRECATED significa "todo menos los avisos de obsolescencia". Cambia la primera línea por error_reporting(E_ERROR | E_WARNING); y vuelve a ejecutarlo.

Mostrar errores en php.ini

Una configuración en el script solo se aplica una vez que el script empieza a ejecutarse. Para mostrar los errores de todos los scripts, incluidos los errores de sintaxis, cambia php.ini (encuéntralo con php --ini):

; Development
display_errors = On
display_startup_errors = On
error_reporting = E_ALL

Reinicia Apache o PHP-FPM después de editarlo. El servidor integrado php -S y la línea de comandos leen el archivo cada vez que arrancan. En un hosting compartido sin acceso a php.ini, Apache con mod_php también acepta líneas en .htaccess:

php_flag display_errors on
php_value error_reporting -1

-1 activa todos los bits, lo que equivale a E_ALL.

Los niveles de error

PHP 8.0 convirtió muchos warnings antiguos en excepciones: dividir por cero con / y pasar un tipo incorrecto a una función nativa ahora lanzan una subclase de Error, igual que llamar a una función no definida desde PHP 7. Puedes capturar los tres:

<?php
$attempts = [
    fn() => 10 / 0,
    fn() => strlen([]),
    fn() => undefinedFunction(),
];

foreach ($attempts as $attempt) {
    try {
        $attempt();
    } catch (Throwable $e) {
        echo get_class($e), ": ", $e->getMessage(), "\n";
    }
}

Las excepciones se explican en try y catch. Los warnings, los notices y los avisos de obsolescencia siguen pasando por el sistema de reporte de errores que se describe aquí.

Registrar los errores en lugar de mostrarlos

En un sitio en producción, los visitantes nunca deberían ver mensajes de error: revelan rutas, SQL y código. Escríbelos en un archivo de log:

; Production
display_errors = Off
log_errors = On
error_log = /var/log/php/app-errors.log
error_reporting = E_ALL

Mantén error_reporting = E_ALL en producción. Bajarlo no hace desaparecer los errores, solo hace que dejes de enterarte de ellos. Tus propios mensajes pueden ir al mismo log con error_log():

<?php
error_log("Payment failed for order 1042");

Después vigila el archivo mientras pruebas: tail -f /var/log/php/app-errors.log.

Convertir warnings en excepciones con set_error_handler

set_error_handler sustituye el manejo por defecto de PHP para warnings, notices y avisos de obsolescencia por tu propia función. Un patrón habitual convierte cada uno en una ErrorException, de modo que una clave de array olvidada detiene el código como cualquier otra excepción y se puede capturar:

<?php
set_error_handler(function (int $severity, string $message, string $file, int $line): bool {
    throw new ErrorException($message, 0, $severity, $file, $line);
});

$prices = ['bread' => 4.5, 'milk' => 1.2];

try {
    echo "Bread costs {$prices['bread']}\n";
    echo "Cheese costs {$prices['cheese']}\n";
} catch (ErrorException $e) {
    echo "Caught: ", $e->getMessage(), " on line ", $e->getLine(), "\n";
}

restore_error_handler();

El manejador recibe el nivel del error como primer argumento, así que puede tratar cada nivel de forma distinta. Este solo registra los avisos de obsolescencia y convierte todo lo demás en una excepción:

<?php
set_error_handler(function (int $severity, string $message): bool {
    if ($severity === E_DEPRECATED || $severity === E_USER_DEPRECATED) {
        echo "[log] deprecated: $message\n";
        return true; // handled, PHP does nothing more
    }
    throw new ErrorException($message, 0, $severity);
});

trigger_error("oldFunction() is deprecated, use newFunction()", E_USER_DEPRECATED);

try {
    trigger_error("Config value 'timeout' is missing", E_USER_WARNING);
} catch (ErrorException $e) {
    echo "Exception: ", $e->getMessage(), "\n";
}

Los errores fatales y los de sintaxis nunca llegan al manejador, porque el script no puede continuar después de ellos. Para registrarlos, registra una función de cierre que lea error_get_last().

Leer el último error con error_get_last

Algunas funciones devuelven false e informan del motivo solo como warning, por ejemplo file_get_contents con un archivo que no existe. error_get_last() devuelve ese warning como array, algo útil cuando quieres mostrar tu propio mensaje:

<?php
$content = @file_get_contents('missing-config.json');

if ($content === false) {
    $error = error_get_last();
    echo "Could not read the file.\n";
    echo "Type: ", $error['type'] === E_WARNING ? 'E_WARNING' : $error['type'], "\n";
    echo "Message: ", $error['message'], "\n";
}

El operador @ delante de la llamada suprime el mensaje para esa única expresión. Úsalo con moderación y solo cuando compruebes el resultado justo después, como aquí; un @ por sí solo solo esconde errores.

Error frecuente: los errores están activados, pero la página sigue en blanco

Si añadiste ini_set('display_errors', '1') y sigues viendo una página en blanco, probablemente sea un error de sintaxis. PHP analiza el archivo entero antes de ejecutar la primera línea, así que un ; o una } que falte lo detiene todo antes de que se ejecute ini_set. Comprueba el archivo desde la terminal, que siempre imprime el mensaje:

php -l index.php

Errors parsing index.php
PHP Parse error:  syntax error, unexpected token "," in index.php on line 2

El número de línea señala dónde se rindió PHP, que a menudo es la línea siguiente al error real. Corrígelo, ejecuta php -l de nuevo hasta que diga No syntax errors detected y recarga la página.