Fehler gehören zur Softwareentwicklung. Entscheidend ist, wie sie protokolliert und analysiert werden. Die PHP-Funktion error_log() schreibt Fehlermeldungen und Debugging-Informationen in Logdateien, an den Syslog-Dienst oder per E-Mail. In Kombination mit der richtigen php.ini-Konfiguration bildet sie die Grundlage für professionelles Error Logging. In diesem Tutorial lernst du die Syntax, die verschiedenen Logging-Ziele, die Konfiguration für Produktion und Entwicklung sowie Best Practices für strukturiertes Logging.
Beginnen wir mit der Funktion selbst und ihrer Aufgabe im PHP-Fehlerbehandlungssystem.
Was ist error_log()?
Die Funktion error_log() sendet eine Nachricht an den konfigurierten Fehlerprotokoll-Handler. Sie ist eine der grundlegendsten Funktionen für das Logging in PHP und in jeder PHP-Installation verfügbar. Im Gegensatz zu echo oder var_dump() ist error_log() für den Einsatz in Produktionsumgebungen gedacht, da die Ausgabe nicht an den Browser gesendet wird.
Syntax und Parameter
Die vollständige Signatur der Funktion lautet:
error_log(string $message, int $message_type = 0, ?string $destination = null, ?string $additional_headers = null): bool
Parameter message
Der erste Parameter ist die Nachricht, die protokolliert werden soll. Es handelt sich um einen einfachen String. Für strukturiertes Logging sollte die Nachricht Datum, Schweregrad und Kontext-Informationen enthalten.
Parameter message_type
Der zweite Parameter bestimmt das Ziel der Nachricht:
0 (Standard): Die Nachricht wird an den System-Logger gesendet, also an die in php.ini konfigurierte Logdatei.
1: Die Nachricht wird per E-Mail an die im Parameter destination angegebene Adresse gesendet.
3: Die Nachricht wird direkt an die im Parameter destination angegebene Datei angehängt.
4: Die Nachricht wird an den SAPI Logging Handler gesendet.
Parameter destination
Bei message_type 1 enthält dieser Parameter die E-Mail-Adresse, bei message_type 3 den Dateipfad.
Parameter additional_headers
Wird nur bei message_type 1 (E-Mail) verwendet und enthält zusätzliche E-Mail-Header.
error_log() in eine Datei schreiben
Der häufigste Anwendungsfall ist das Schreiben in eine bestimmte Logdatei mit message_type 3.
<?php
/* Nachricht an den konfigurierten System-Logger senden */
error_log('Datenbankverbindung fehlgeschlagen');
/* Mit Kontext-Informationen */
$userId = 42;
error_log('Login fehlgeschlagen fuer User-ID: ' . $userId);
Der Standard-Typ 0 ist die einfachste Variante, da die Nachricht automatisch an den konfigurierten Logger weitergeleitet wird, ohne dass ein Dateipfad angegeben werden muss. Für das Schreiben in eine spezifische Datei wird message_type 3 verwendet:
<?php
$logDatei = __DIR__ . '/logs/app.log';
error_log(
date('Y-m-d H:i:s') . ' Fehler: Datei nicht gefunden' . PHP_EOL,
3,
$logDatei
);
/* Schreibt direkt in die angegebene Datei.
Parameter 3 bedeutet: an Datei anhaengen. */
Wichtig ist der Zeilenumbruch PHP_EOL am Ende der Nachricht. Bei message_type 3 fügt PHP keinen automatischen Zeilenumbruch hinzu.
error_log() an Syslog senden
Mit message_type 0 wird die Nachricht an den System-Logger gesendet. Auf Linux-Systemen ist das in der Regel Syslog, auf Windows das Event Log. Die Nachricht landet dann in der Datei, die in der php.ini-Direktive error_log konfiguriert ist. Alternativ lässt sich PHP direkt mit dem Syslog-Dienst verbinden, indem die Funktionen openlog(), syslog() und closelog() verwendet werden. Das bietet eine feinere Kontrolle über Facility und Severity der Nachrichten.
error_log() per E-Mail versenden
Mit message_type 1 kann eine Fehlermeldung per E-Mail versendet werden. Diese Option sollte mit Vorsicht verwendet werden: Bei häufigen Fehlern kann der Mailserver überlastet werden. Sinnvoll ist der E-Mail-Versand nur für kritische Fehler, die sofortige Aufmerksamkeit erfordern.
<?php
error_log(
'KRITISCH: Datenbank nicht erreichbar',
1,
'admin@example.com',
'From: php-errors@example.com'
);
Der vierte Parameter enthält zusätzliche E-Mail-Header. In der Praxis wird der E-Mail-Versand über error_log() selten eingesetzt. Monitoring-Tools und externe Logging-Dienste sind für diesen Zweck besser geeignet.
Wo finde ich die PHP Error Logs?
Der Speicherort der Logdateien hängt von der Serverkonfiguration ab.
Linux/Apache
Auf Linux-Systemen mit Apache liegen die Logs typischerweise unter /var/log/apache2/error.log oder /var/log/php_errors.log. Der genaue Pfad wird in der php.ini-Direktive error_log festgelegt.
Windows
Unter Windows liegt das Standardlog häufig im PHP-Installationsverzeichnis oder im Eventlog des Systems.
CLI
Bei der Ausführung über die Kommandozeile gehen Fehlermeldungen standardmäßig an stderr, also direkt in die Konsole. Das ist für Cronjobs und CLI-Skripte relevant, da die Fehlerausgabe separat von der normalen Ausgabe (stdout) umgeleitet werden kann.
Der aktuelle Pfad lässt sich programmatisch mit ini_get('error_log') abfragen. Auf der Kommandozeile zeigt php -i | grep error_log den konfigurierten Pfad an. Unter Linux können die letzten Einträge einer Logdatei mit tail -f /var/log/php_errors.log in Echtzeit verfolgt werden, was bei der Fehlersuche sehr hilfreich ist.
php.ini-Konfiguration für Error Logging
Die php.ini enthält mehrere Direktiven, die das Verhalten von Error Logging steuern.
error_log Direktive
Legt den Pfad zur Logdatei fest. Wenn kein Pfad angegeben ist, werden Fehler an den SAPI-Handler (z.B. das Apache-Errorlog) gesendet.
error_reporting
Bestimmt, welche Fehlertypen überhaupt beachtet werden. Für Entwicklung empfiehlt sich E_ALL, für Produktion E_ALL & ~E_DEPRECATED & ~E_STRICT.
log_errors
Muss auf On gesetzt sein, damit PHP Fehler überhaupt in Logs schreibt. Ohne diese Einstellung werden Fehler nur angezeigt, aber nicht protokolliert.
display_errors
Steuert, ob Fehler im Browser angezeigt werden. In Produktion muss diese Einstellung auf Off stehen, da Fehlermeldungen sensible Informationen wie Dateipfade, Datenbankzugangsdaten oder interne Strukturen preisgeben können.
/* php.ini Einstellungen fuer Produktion: */
/* error_log = /var/log/php_errors.log */
/* log_errors = On */
/* display_errors = Off */
/* error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT */
/* In PHP pruefbar mit: */
echo ini_get('error_log');
echo ini_get('display_errors');
error_log() vs. trigger_error()
Während error_log() eine Nachricht direkt an den Logger sendet, löst trigger_error() einen PHP-Fehler aus, der vom Error-Reporting-System verarbeitet wird. Der Unterschied ist: trigger_error() durchläuft das gesamte PHP-Fehlerbehandlungssystem inklusive Error-Level und registrierter Error-Handler. error_log() schreibt die Nachricht direkt ins Log, ohne den PHP-Fehlermechanismus zu involvieren. In der Praxis ist error_log() die bessere Wahl für eigene Lognachrichten und Debugging-Ausgaben, während trigger_error() für Situationen gedacht ist, in denen ein PHP-konformer Fehler ausgelöst werden soll, der durch Error-Level und registrierte Handler verarbeitet wird.
Best Practices für Error Logging
Für professionelles Error Logging gelten einige bewährte Regeln:
Strukturiertes Logging
Statt roher Strings sollten Lognachrichten ein einheitliches Format mit Zeitstempel, Schweregrad und Kontext verwenden.
<?php
function logNachricht(string $level, string $nachricht, array $kontext = []): void
{
$eintrag = sprintf(
'[%s] %s: %s %s',
date('Y-m-d H:i:s'),
strtoupper($level),
$nachricht,
$kontext ? json_encode($kontext) : ''
);
error_log($eintrag);
}
logNachricht('error', 'Bestellung fehlgeschlagen', ['bestell_id' => 1234]);
/* [2026-03-06 14:30:00] ERROR: Bestellung fehlgeschlagen {"bestell_id":1234} */
Custom Error Handler
Mit set_error_handler() lässt sich ein eigener Error Handler registrieren, der alle PHP-Fehler abfängt und strukturiert protokolliert.
<?php
set_error_handler(function (
int $errno,
string $errstr,
string $errfile,
int $errline
): bool {
$nachricht = sprintf(
'%s in %s on line %d',
$errstr,
$errfile,
$errline
);
error_log($nachricht);
/* false: PHP-Standard-Fehlerbehandlung ausfuehren */
return false;
});
Produktion vs. Entwicklung
In der Entwicklung sollten Fehler sowohl im Browser angezeigt als auch geloggt werden. In der Produktion dürfen Fehler niemals im Browser erscheinen. Stattdessen werden sie ausschließlich in Logdateien geschrieben. Die Logdatei muss vom Webserver-Benutzer beschreibbar sein, und die Berechtigungen sollten so gesetzt sein, dass nur berechtigte Benutzer die Logs lesen können.
Für größere Projekte empfiehlt sich der Einsatz einer Logging-Bibliothek wie Monolog, die den PSR-3-Standard implementiert und verschiedene Handler für Dateien, Datenbanken und externe Dienste bietet.
Logdateien rotieren
Logdateien können bei hohem Traffic schnell anwachsen. Unter Linux sorgt das Tool logrotate dafür, dass Logdateien regelmäßig archiviert und alte Dateien gelöscht werden. Alternativ kann in PHP eine eigene Rotation implementiert werden, indem die Logdatei regelmäßig geprüft und bei Überschreiten einer Größe umbenannt wird. Ohne Rotation können Logdateien den verfügbaren Speicherplatz aufbrauchen und den Server zum Stillstand bringen.
Kontextdaten mitloggen
Fehlermeldungen ohne Kontext sind schwer zu analysieren. Neben der eigentlichen Fehlermeldung sollten immer relevante Daten wie die Benutzer-ID, die aufgerufene URL, die Request-Methode oder die betroffene Ressource mitgeloggt werden. Die Codierung als JSON hat sich bewährt, da JSON maschinell auswertbar ist und von Log-Analyse-Tools wie ELK Stack oder Graylog direkt verarbeitet werden kann.
<?php
function logMitKontext(string $nachricht, array $kontext = []): void
{
$kontext['timestamp'] = date('c');
$kontext['message'] = $nachricht;
error_log(json_encode($kontext));
}
logMitKontext('Zugriff verweigert', [
'user_id' => 42,
'url' => '/admin/dashboard',
'ip' => '192.168.1.100'
]);
flowchart TD
A["error_log() aufrufen"] --> B{"message_type?"}
B -->|"0 (Standard)"| C["System-Logger
(php.ini error_log)"]
B -->|"1"| D["E-Mail senden"]
B -->|"3"| E["In Datei schreiben"]
B -->|"4"| F["SAPI Handler"]
C --> G["Logdatei / syslog / stderr"]
Fazit
Die Funktion error_log() ist das Fundament für Error Logging in PHP. Sie ermöglicht das Schreiben von Fehlermeldungen in Logdateien, an Syslog oder per E-Mail. Die korrekte Konfiguration der php.ini-Direktiven error_log, log_errors, display_errors und error_reporting ist entscheidend für den sicheren Betrieb in Produktionsumgebungen. Mit strukturiertem Logging und einem Custom Error Handler lässt sich die Fehlerprotokollierung professionell gestalten. Wer die Grundlagen von error_log() beherrscht, hat die Basis für zuverlässiges Debugging und Monitoring in PHP gelegt. Für fortgeschrittene Anforderungen bieten Bibliotheken wie Monolog und der PSR-3-Standard zusätzliche Möglichkeiten wie Handler-Ketten und die Anbindung an externe Monitoring-Dienste. Die Grundprinzipien bleiben jedoch dieselben: Fehler protokollieren statt anzeigen, strukturierte Nachrichten mit Kontext schreiben und die Konfiguration an die jeweilige Umgebung anpassen. Wer diese Grundlagen beherrscht, kann auch komplexere Logging-Systeme sicher aufbauen und betreiben.
