Fehler-Handling und Logging

Erste Schritte – Fehler-Handling und Logging: Exception-Handling in PHP

Das phpFK – PHP Framework bietet von Haus aus Mechanismen, um Fehler effektiv zu erfassen und zu protokollieren.
Gerade in großen Projekten ist es enorm wichtig, den Überblick über Fehlermeldungen, Ausnahmen (Exceptions)
und Warnungen zu behalten. In diesem Tutorial lernst du, wie du das integrierte Fehler-Handling nutzen
und für deine Bedürfnisse anpassen kannst.

Wofür ist Fehler-Handling überhaupt wichtig?

Fehler-Handling sorgt dafür, dass sich deine Anwendung bei Laufzeitfehlern oder unerwarteten Situationen
nicht einfach mit einer leeren Seite verabschiedet. Stattdessen können Fehler gezielt abgefangen,
dem Entwickler gemeldet und notfalls eine Benutzerfreundliche Antwort (z. B. ein 500-Error-Template)
zurückgegeben werden.
So verhinderst du, dass User kryptische PHP-Fehlermeldungen sehen oder dass sensible Interna nach außen dringen.

Überblick über das phpFK-Fehler-Handling

Im phpFK – PHP Framework wird standardmäßig eine ErrorHandler-Klasse (oder ähnliche Mechanismen) eingesetzt,
die bei einem kritischen Fehler ein Logfile in deinem storage/logs/-Ordner anlegt.
Außerdem bekommen die Nutzer eine generische Fehlermeldung angezeigt, damit keine sensiblen
Interna preisgegeben werden.

Konfiguration & Orte

Die wichtigsten Konfigurationen findest du in diesen Bereichen:

  • core/ErrorHandler.php – Verantwortlich für das Abfangen von Ausnahmen, Warnings, Notices etc.
  • storage/logs/ – Standardordner, in dem Logdateien pro Tag oder Ereignis abgelegt werden.
  • config/app.php (bzw. config/security.php) – Falls dort eine Einstellung
    zum Fehler-Modus (z. B. debug) vorhanden ist, kann man sie anpassen.

Beispiel: ErrorHandler-Klasse

Ein vereinfachter Ausschnitt könnte so aussehen: 

// core/ErrorHandler.php

namespace Core;

class ErrorHandler
{
    public static function register()
    {
        // Alle PHP-Fehler abfangen
        set_error_handler([__CLASS__, 'handleError']);
        set_exception_handler([__CLASS__, 'handleException']);
        register_shutdown_function([__CLASS__, 'handleShutdown']);
    }

    public static function handleError($errno, $errstr, $errfile, $errline)
    {
        // Fehler in Logs speichern
        Logger::write("ERROR: [$errno] $errstr in $errfile on line $errline");
        // Je nach Schweregrad ggf. weiterleitung zu handleException oder 500-Seite
    }

    public static function handleException($exception)
    {
        // Fehlermeldung und Stacktrace in Logs
        Logger::write("EXCEPTION: " . $exception->getMessage());
        
        // Nutzer bekommt eine 500-Fehlerseite
        http_response_code(500);
        echo "Ein interner Fehler ist aufgetreten. Bitte probiere es später erneut.";
    }

    public static function handleShutdown()
    {
        // Falls z. B. ein Fatal Error aufgetreten ist
        $error = error_get_last();
        if ($error !== null) {
            Logger::write("FATAL: {$error['message']} in {$error['file']} on line {$error['line']}");
            http_response_code(500);
            echo "Ein schwerwiegender Fehler ist aufgetreten.";
        }
    }
}

1. register() sorgt dafür, dass alle Fehler an unsere Methoden delegiert werden.
2. handleError() fängt klassische PHP-Warnungen, Notices und andere Error-Levels ab.
3. handleException() kümmert sich um Exceptions (inklusive throw im eigenen Code).
4. handleShutdown() prüft, ob beim Shutdown ein Fatal Error oder Parse Error gemeldet wurde.

Das Logger-System

Der ErrorHandler ruft häufig eine Logger-Klasse auf, um die eigentliche Arbeit des Protokollierens
zu erledigen. Diese Klasse schreibt die Fehler in ein Logfile ab – meist mit Datumsstempel, damit du
Fehler schnell zeitlich zuordnen kannst.

Beispiel: Logger-Klasse

// core/Logger.php

namespace Core;

class Logger
{
    public static function write($message)
    {
        $date = date("Y-m-d H:i:s");
        $logFile = STORAGE_PATH . 'logs/' . date("Y-m-d") . '.log';

        // Ein Zeilenende anhängen, je nach Betriebssystem
        $logEntry = "[{$date}] " . $message . PHP_EOL;
        file_put_contents($logFile, $logEntry, FILE_APPEND);
    }
}

1. Die Methode write erzeugt eine Zeile mit Datum/Uhrzeit.
2. Der Dateiname des Logfiles orientiert sich oft an Y-m-d (z. B. „2025-03-23.log“).
3. Per file_put_contents wird im APP_PATH/storage/logs/-Ordner (oder eben
STORAGE_PATH/logs/) ein Eintrag angefügt.

Ausnahmebehandlung in deinem eigenen Code

Wenn du aktiv Exceptions werfen möchtest, um z. B. Validierungsfehler oder abnormale Zustände anzuzeigen,
kannst du das so machen: 

// In einem Controller oder Service
if (empty($username)) {
    throw new \Exception("Username darf nicht leer sein!");
}

Der handleException-Handler fängt diese Exception ab und schreibt sie ins Logfile.
In der Produktionsumgebung sehen Besucher nur eine generische Meldung, du als Entwickler aber
kannst die Details im Log nachschlagen.

Debugmodus vs. Produktion

In vielen Projekten möchtest du in der Entwicklungsphase alle Fehler direkt im Browser sehen,
um schnell Bugs zu beheben. Im Produktivbetrieb hingegen sollen User keine Interna erfahren.
Typischerweise schaltest du dazu in einer Konfigurationsdatei einen debug-Flag um: 

// config/app.php (Beispiel)
return [
    'DEBUG' => true, // oder false im Live-System
    ...
];

Im ErrorHandler (oder in public/index.php) kann dann unterschieden werden: 

if ($config['DEBUG'] === true) {
    ini_set('display_errors', 1);
    error_reporting(E_ALL);
} else {
    ini_set('display_errors', 0);
    error_reporting(E_ALL & ~E_NOTICE & ~E_WARNING);
}

So hast du volle Flexibilität, was im Browser angezeigt wird, während im Hintergrund immer
geloggt wird. Auf einem Liveserver sollten „display_errors“ ausgeschaltet sein,
damit sensible Daten nicht nach außen dringen.

Rechte & Schutz der Logdateien

Achte darauf, dass der storage/logs/-Ordner:

  • Beschreibbar für den Webserver-Benutzer ist (z. B. chmod 775 oder chmod 755 je nach Hosting).
  • Von außen nicht frei abrufbar ist. Meist wird dafür eine .htaccess (Deny from all)
    oder eine ähnliche Serverkonfiguration genutzt.

Logdateien enthalten oft kritische Informationen wie Fehlermeldungen, Datenbanktabellen,
Name des Servers usw. Deshalb ist es wichtig, sie vor direktem Zugriff zu schützen.

Fazit

Fehler-Handling & Logging sind entscheidende Bestandteile jeder stabilen Anwendung.
Das phpFK – PHP Framework setzt auf set_error_handler, set_exception_handler und
Logger-Klassen, um Fehler zu erfassen und geordnet zu protokollieren.
Egal ob Warnungen, Exceptions oder Fatal Errors – alles landet in storage/logs/,
während Besucher nur eine generische Meldung sehen.
Dank Debugmodus kannst du im Entwicklungsstadium aktiv Fehler im Browser verfolgen
und in der Produktivphase trotzdem alle Details einsehen, ohne die Sicherheit zu gefährden.
Erweitere oder optimiere das System nach Bedarf, um noch präzisere Log-Einträge,
E-Mail-Benachrichtigungen bei kritischen Ausfällen oder Tools wie Sentry in dein Projekt zu integrieren.