error_log()

Registro de errores PHP con la función de registro de errores

Imprimir errores en pantalla con echo o var_dump() está bien mientras construyes una funcionalidad, pero es la herramienta incorrecta en producción: la salida en pantalla es visible para los visitantes, se pierde en las llamadas AJAX y desaparece en el momento en que termina la solicitud. La función integrada error_log() resuelve esto enviando un mensaje a algún lugar duradero — un archivo de registro, un correo electrónico o el registrador del sistema operativo — para que puedas revisarlo más tarde.

Esta guía explica qué hace error_log(), recorre cada parámetro con ejemplos ejecutables y cubre los problemas comunes (saltos de línea al final, la directiva ini error_log, qué no registrar) que confunden a las personas en proyectos reales.

Qué hace la función error_log()

error_log() escribe un único mensaje en un destino que tú eliges. No activa la maquinaria de errores de PHP, no cambia el código de salida ni detiene el script — solo registra texto. El valor de retorno es un bool: true en caso de éxito, false si el mensaje no pudo escribirse (por ejemplo, el archivo de registro no tiene permisos de escritura).

Dado que simplemente "añade esta cadena en algún lugar", error_log() es la forma más sencilla de dejar rastros en código que se ejecuta sin que un desarrollador lo observe — trabajos cron, workers de colas, webhooks y cualquier solicitud en producción.

Firma de la función

error_log(
    string $message,
    int $message_type = 0,
    ?string $destination = null,
    ?string $additional_headers = null
): bool

El comportamiento predeterminado: registrar en el destino configurado de PHP

La llamada más común solo pasa el mensaje y deja que PHP lo dirija a donde sea que el servidor esté configurado para enviar errores (la directiva ini error_log, o el registrador SAPI/del sistema si no está configurada):

<?php

error_log("Payment gateway returned an unexpected status code");

Este es exactamente el lugar donde ya van las advertencias y avisos no capturados, por lo que tus mensajes manuales aparecen junto a los propios de PHP. Para ver el destino actual en tiempo de ejecución, lee el valor ini:

<?php

echo ini_get('error_log') ?: '(SAPI / system default)';

Registro en un archivo específico (tipo 3)

El tipo 3 agrega el mensaje a un archivo que nombras en $destination. Este es el caballo de batalla para los registros específicos de la aplicación:

<?php

$message = "Error: Unable to connect to the database";
error_log($message, 3, "/var/log/php-errors.log");

A diferencia del tipo 0, el tipo 3 escribe el mensaje exactamente como está — sin marca de tiempo, sin gravedad y, crucialmente, sin salto de línea al final. Si olvidas el salto de línea, todas las llamadas se concatenan en una sola línea:

<?php

$log = sys_get_temp_dir() . "/app.log";
error_log("first", 3, $log);
error_log("second", 3, $log);
echo file_get_contents($log); // firstsecond

Añade PHP_EOL tú mismo (y normalmente una marca de tiempo) para que cada entrada sea una línea legible:

<?php

$log = sys_get_temp_dir() . "/app.log";
$line = date('[Y-m-d H:i:s] ') . "Cache miss for user 42" . PHP_EOL;
error_log($line, 3, $log);

echo file_get_contents($log);
// [2026-06-21 10:00:00] Cache miss for user 42

Todos los tipos de mensaje

El tipo 2 (enviar por un socket TCP) existía en versiones antiguas de PHP y fue eliminado en PHP 8; no lo uses.

Envío de errores críticos por correo electrónico (tipo 1)

Para fallos poco frecuentes y de alta gravedad, puedes hacer que PHP te envíe un correo electrónico. Úsalo con moderación — un error ruidoso que se dispara una vez por solicitud puede inundar una bandeja de entrada:

<?php

error_log(
    "FATAL: order processor crashed",
    1,
    "[email protected]",
    "From: [email protected]\r\n"
);

En producción, una biblioteca de registro que agrupe y limite la tasa de alertas es más adecuada que enviar correos en cada llamada.

Un patrón realista de captura y registro

En el código de la aplicación, normalmente registras dentro de un bloque catch, guardas suficiente contexto para reproducir el problema y luego muestras al usuario un mensaje genérico:

<?php

function chargeCustomer(int $cents): bool
{
    if ($cents <= 0) {
        throw new InvalidArgumentException("Amount must be positive, got $cents");
    }
    // ... real charge logic ...
    return true;
}

try {
    chargeCustomer(-5);
} catch (Throwable $e) {
    error_log(sprintf(
        "[%s] %s in %s:%d",
        date('Y-m-d H:i:s'),
        $e->getMessage(),
        $e->getFile(),
        $e->getLine()
    ));
    echo "Sorry, we couldn't process your payment.";
}

El mensaje detallado va al registro; el visitante solo ve la línea amigable. Esta separación es el objetivo principal de error_log().

Problemas comunes

• Sin salto de línea con el tipo 3. Añade PHP_EOL tú mismo o tus entradas se concatenarán.
• La directiva ini error_log establece el destino predeterminado. Cuando omites $message_type/$destination, el mensaje va a donde apunta ini_get('error_log'). En una instalación CLI nueva, puede ser stderr; en un servidor web puede ser un archivo específico.
• El archivo debe tener permisos de escritura para el proceso PHP. Un retorno false a menudo indica un problema de permisos en el directorio o archivo.
• display_errors y error_log son independientes. Desactivar los errores en pantalla no detiene el registro, y viceversa — contrólales por separado.
• Nunca registres secretos. Las contraseñas, claves API, números de tarjeta de crédito completos y tokens de sesión nunca deben llegar a un archivo de registro. Redáctalos antes de llamar a error_log().

Funciones relacionadas

• set_error_handler() — dirige las advertencias y avisos propios de PHP a través de tu código para que puedas llamar a error_log() de forma coherente.
• set_exception_handler() — captura y registra excepciones no atrapadas en un solo lugar.
• trigger_error() — lanza un error de nivel de usuario que el manejador de errores (y por tanto el registro) captará.
• error_reporting() — elige qué niveles de error se reportan en primer lugar.
• syslog() — envía mensajes directamente al registrador del sistema con un nivel de gravedad.

Conclusión

error_log() es la forma más sencilla y duradera de registrar qué salió mal en código que ningún desarrollador está observando. Usa el tipo 3 con una marca de tiempo y PHP_EOL para archivos de registro de la aplicación, recurre al destino predeterminado para estar junto a los propios errores de PHP, y reserva el correo electrónico (tipo 1) para eventos genuinamente críticos. Combínalo con set_error_handler() y set_exception_handler() para capturar todo en un solo lugar — y nunca escribas secretos en un registro.

Práctica