error_log()

PHP-Fehler mit der Error-Log-Funktion protokollieren

Fehler mit echo oder var_dump() auf dem Bildschirm auszugeben ist während der Entwicklung praktisch, aber im Produktionsbetrieb das falsche Werkzeug: Die Ausgabe ist für Besucher sichtbar, geht bei AJAX-Aufrufen verloren und verschwindet, sobald die Anfrage endet. Die eingebaute Funktion error_log() löst dieses Problem, indem sie eine Nachricht an einen dauerhaften Ort sendet – eine Protokolldatei, eine E-Mail oder den Systemlogger –, sodass man sie später einsehen kann.

Diese Anleitung erklärt, was error_log() tut, erläutert jeden Parameter mit ausführbaren Beispielen und behandelt die Fallstricke (fehlende Zeilenumbrüche, die error_log-ini-Direktive, was man nicht protokollieren sollte), über die Entwickler in echten Projekten stolpern.

Was die Funktion error_log() tut

error_log() schreibt eine einzelne Nachricht an ein selbst gewähltes Ziel. Sie löst nicht PHPs Fehlermechanismus aus, ändert den Exit-Code nicht und beendet das Skript nicht – sie zeichnet lediglich Text auf. Der Rückgabewert ist ein bool: true bei Erfolg, false, wenn die Nachricht nicht geschrieben werden konnte (zum Beispiel, weil die Protokolldatei nicht beschreibbar ist).

Da es sich dabei nur um „diesen String irgendwo anhängen" handelt, ist error_log() der einfachste Weg, Spuren in Code zu hinterlassen, der ohne Entwickleraufsicht läuft – Cron-Jobs, Queue-Worker, Webhooks und jede Produktionsanfrage.

Funktionssignatur

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

Standard: An PHPs konfigurierten Zielort protokollieren

Der häufigste Aufruf übergibt nur die Nachricht und lässt PHP sie an den vom Server konfigurierten Zielort für Fehler weiterleiten (die error_log-ini-Direktive oder der SAPI/System-Logger, wenn diese nicht gesetzt ist):

<?php

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

Genau dort landen bereits abgefangene Warnungen und Hinweise, sodass eigene Nachrichten direkt neben PHPs eigenen erscheinen. Um das aktuelle Ziel zur Laufzeit zu ermitteln, liest man den ini-Wert:

<?php

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

In eine bestimmte Datei protokollieren (Typ 3)

Typ 3 hängt die Nachricht an eine in $destination angegebene Datei an. Dies ist der Standardfall für anwendungsspezifische Protokolle:

<?php

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

Anders als Typ 0 schreibt Typ 3 die Nachricht wortwörtlich – ohne Zeitstempel, ohne Schweregrad und entscheidend: ohne abschließenden Zeilenumbruch. Vergisst man den Zeilenumbruch, werden alle Aufrufe in einer einzigen Zeile zusammengefügt:

<?php

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

Man fügt PHP_EOL selbst hinzu (und üblicherweise einen Zeitstempel), damit jeder Eintrag als lesbare Zeile erscheint:

<?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

Alle Nachrichtentypen

Typ 2 (Senden über einen TCP-Socket) existierte in alten PHP-Versionen und wurde in PHP 8 entfernt; man sollte sich nicht darauf verlassen.

Kritische Fehler per E-Mail senden (Typ 1)

Bei seltenen, schwerwiegenden Fehlern kann PHP eine E-Mail versenden. Sparsam verwenden – ein häufig auftretender Fehler, der einmal pro Anfrage ausgelöst wird, kann einen Posteingang überfluten:

<?php

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

In der Produktion ist eine Protokollierungsbibliothek, die Benachrichtigungen bündelt und ratenbegrenzt, besser geeignet als das E-Mail-Versenden bei jedem Aufruf.

Ein realistisches Fang-und-Protokollier-Muster

Im Anwendungscode protokolliert man üblicherweise innerhalb eines catch-Blocks, zeichnet genügend Kontext auf, um das Problem zu reproduzieren, und zeigt dem Benutzer eine generische Meldung:

<?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.";
}

Die detaillierte Nachricht geht ins Protokoll; der Besucher sieht nur die benutzerfreundliche Zeile. Diese Trennung ist der eigentliche Zweck von error_log().

Häufige Fallstricke

• Kein Zeilenumbruch bei Typ 3. PHP_EOL selbst anhängen, sonst werden die Einträge zusammengefügt.
• Die error_log-ini-Direktive legt das Standardziel fest. Wenn $message_type/$destination weggelassen werden, geht die Nachricht dorthin, worauf ini_get('error_log') zeigt. Bei einer frischen CLI-Installation kann das stderr sein; auf einem Webserver kann es eine bestimmte Datei sein.
• Die Datei muss vom PHP-Prozess beschreibbar sein. Ein false-Rückgabewert bedeutet oft ein Berechtigungsproblem für das Verzeichnis oder die Datei.
• display_errors und error_log sind unabhängig voneinander. Das Deaktivieren der Bildschirmausgabe stoppt die Protokollierung nicht, und umgekehrt – beide werden separat gesteuert.
• Niemals Geheimnisse protokollieren. Passwörter, API-Schlüssel, vollständige Kreditkartennummern und Session-Tokens dürfen niemals in eine Protokolldatei gelangen. Vor dem Aufruf von error_log() müssen diese unkenntlich gemacht werden.

Verwandte Funktionen

• set_error_handler() — PHPs eigene Warnungen und Hinweise durch eigenen Code leiten, um error_log() konsistent aufrufen zu können.
• set_exception_handler() — Anderweitig nicht abgefangene Ausnahmen an einer Stelle abfangen und protokollieren.
• trigger_error() — Einen benutzerdefinierten Fehler auslösen, den der Fehler-Handler (und damit die Protokollierung) aufgreift.
• error_reporting() — Auswählen, welche Fehlerstufen überhaupt gemeldet werden.
• syslog() — Nachrichten mit einem Schweregrad direkt an den Systemlogger senden.

Fazit

error_log() ist der einfachste dauerhafte Weg, um aufzuzeichnen, was in Code schiefgelaufen ist, dem kein Entwickler zusieht. Typ 3 mit Zeitstempel und PHP_EOL für anwendungsspezifische Protokolldateien verwenden, auf das Standardziel zurückgreifen, um neben PHPs eigenen Fehlern zu erscheinen, und E-Mail (Typ 1) für wirklich kritische Ereignisse reservieren. In Kombination mit set_error_handler() und set_exception_handler() lässt sich alles an einem Ort erfassen – und niemals Geheimnisse in ein Protokoll schreiben.

Übungen