Swoop Contao Debug Logger Bundle
Wiederverwendbarer Debug-Logger für Contao ab 5.0.
Funktionen
- eine zentrale Debug-Konfiguration pro registrierter Source
- Einstellungen vollständig im Contao-Backend
- Debugging pro Source aktivierbar
- Credentials können bewusst unmaskiert geloggt werden (
debugCredentials)
- File-Logging mit frei einstellbarem Dateipfad
- Datenbank-Logging
- File + Datenbank gleichzeitig
- Maskierungswörter: ein Begriff pro Zeile
- Maskierungswerte: ein konkreter Wert pro Zeile
- Maskierungswerte werden mit AES-256-GCM verschlüsselt gespeichert
- zentrale Datenbank-Logansicht als Contao-Child-Tabelle
- der Logs-Button wird nur angezeigt, wenn DB-Logging für die Source aktiv ist
- Fehlerhinweis im Backend, wenn
kernel.secret / APP_SECRET geändert wurde und gespeicherte Maskierungswerte nicht mehr entschlüsselt werden können
- fail-safe: bei nicht entschlüsselbaren Maskierungswerten wird für die betreffende Source nichts geloggt, solange
Credentials loggen deaktiviert ist
Contao-5.0-Kompatibilität
Das Bundle ist auf PHP >=8.1 und contao/core-bundle ^5.0 ausgelegt. Es verwendet keine PHP-8.2-only readonly class-Syntax.
Contao 5.0 selbst unterstützt Symfony 5.4/6.x-Komponenten. Deshalb sind die direkt benötigten Symfony-Pakete entsprechend breit versioniert.
Tabellen
tl_swoop_debug_config
Eine Konfigurationszeile pro registrierter Source.
Wichtige Felder:
sourceenableddebugCredentialsfileEnabledfilePathdatabaseEnabledmaskWordsmaskValues (verschlüsselt)
tl_swoop_debug_log
Datenbank-Logs als Child-Datensätze der jeweiligen Source-Konfiguration.
Nach Installation bzw. Schemaänderung:
vendor/bin/contao-console contao:migrate --no-interaction
Parent-Bundle anbinden
Das konsumierende Bundle liefert ausschließlich Name und Label der Debug-Source.
<?php
declare(strict_types=1);
namespace Swoop\ContaoTelegramSupportBundle\Logging;
use Swoop\ContaoDebugLoggerBundle\Contract\DebugSourceInterface;
final class TelegramDebugSource implements DebugSourceInterface
{
public function getName(): string
{
return 'telegram-support';
}
public function getLabel(): string
{
return 'Telegram Support';
}
}
DebugSourceInterface trägt #[AutoconfigureTag('swoop.debug_source')]. Bei normalem Symfony autoconfigure: true ist deshalb kein manueller Service-Tag nötig.
Composer-Abhängigkeit im Parent-Bundle:
{
"require": {
"swoopde/contao-debug-logger-bundle": "^1.0"
}
}
Logging verwenden
DebugLogger injizieren:
use Swoop\ContaoDebugLoggerBundle\Logger\DebugLogger;
final class TelegramApi
{
public function __construct(
private DebugLogger $debugLogger,
) {
}
public function doSomething(string $botToken): void
{
$this->debugLogger->debug(
'telegram-support',
'Telegram request botToken=' . $botToken,
[
'botToken' => $botToken,
'method' => 'getMe',
],
);
}
}
Öffentliche Logger-Funktionen:
$logger->debug($source, $message, $context);
$logger->info($source, $message, $context);
$logger->warning($source, $message, $context);
$logger->error($source, $message, $context);
$logger->log($source, $level, $message, $context);
Alle Methoden akzeptieren als $context ein assoziatives Array.
Backend-Konfiguration
Beim Öffnen von Swoop → Debug Logger werden alle registrierten Sources automatisch nach tl_swoop_debug_config synchronisiert.
Pro Source stehen zur Verfügung:
- Debugging aktivieren
- Credentials loggen
- In Datei loggen
- Log-Datei
- In Datenbank loggen
- Zusätzliche zu maskierende Wörter – ein Begriff pro Zeile
- Zu maskierende Werte – ein konkreter Wert pro Zeile
Beispiel Maskierungswörter:
botToken
webhookSecret
password
authorization
Beispiel Maskierungswerte:
123456789:AAGxxxxxxxxxxxx
mein-geheimer-webhook-key
Wenn Credentials loggen deaktiviert ist, werden passende Keys/Wörter und konkrete Maskierungswerte durch ******** ersetzt.
Verschlüsselung und APP_SECRET / kernel.secret
maskValues werden vor dem Speichern mit DebugCredentialCrypto::encrypt() verschlüsselt. Der Schlüssel wird aus %kernel.secret% abgeleitet.
Beim Laden werden die Werte mit DebugCredentialCrypto::decrypt() entschlüsselt.
Wird APP_SECRET bzw. kernel.secret später geändert, können bereits gespeicherte Werte nicht mehr authentifiziert/entschlüsselt werden. Das Bundle zeigt dann im Backend eine Fehlermeldung:
Die gespeicherten Debug-Maskierungswerte können nicht entschlüsselt werden. Möglicherweise wurde der Symfony/Contao kernel.secret (APP_SECRET) geändert. Bitte die „Zu maskierenden Werte“ erneut eingeben und speichern.
Solange dieser Zustand besteht und Credentials loggen deaktiviert ist, schreibt DebugLogger für die betreffende Source keine Logs. Dadurch können Secrets nicht versehentlich unmaskiert persistiert werden.
Wichtige Klassen
DebugSourceInterface
Definiert eine Debug-Quelle. Das Parent-Bundle implementiert nur:
getName(): string
getLabel(): string
DebugLogger
Zentrale API zum Schreiben von Logs. Entscheidet anhand der Backend-Konfiguration automatisch über File, DB und Maskierung.
LogSanitizer
Maskiert sensitive Context-Keys sowie konfigurierte Wörter und konkrete Werte.
DebugCredentialCrypto
Verschlüsselt und entschlüsselt maskValues mit AES-256-GCM und %kernel.secret%.
DebugConfigCallback
Synchronisiert Sources, verschlüsselt/entschlüsselt das Backend-Feld maskValues, prüft die Entschlüsselbarkeit und zeigt den Backend-Fehler bei geändertem Secret an.
