Joomla-Logger einrichten. Logs in Datei schreiben. (Joomla-Klasse "Log" für's Debuggen nutzen.)

In der Joomla-Konfiguration findet sich ein Feld "Protokollverzeichnis". Im Normalfall wurde dieser Ordnerpfad durch ein Wunderwerk bereits gefüllt. Selten schaut der "normale" Benutzer in das Verzeichnis mal rein. Man findet darin gar nichts oder eine bis mehrere PHP-Dateien, so genannte Log-Dateien, die das Joomla oder Erweiterungen befüllen; mit unterschiedlichsten Infos, Warnungen, Fehlern und mehr.

Randbemerkungen

  • PHP-Dateien sind diese Log-Dateien nur, damit sie nicht direkt per Internetbrowser gelesen werden können. Sie haben eine Zeile drinnen, die den eigentlichen Inhalt der Datei davor schützt. Man liest sie im einfachsten Fall in einem stinknormalen Texteditor, nachdem man sie z.B. per FTP heruntergeladen hat. Verwendet man den unten vorgestellten Code, muss man sich um eine solche Absicherung vor "Fremdlesern" der Logbücher nicht selbst kümmern.
  • In einem Joomla gibt es meist zwei Ordner namens /logs/. Welcher der aktive ist, findet man in oben erwähntem Feld "Protokollverzeichnis" in der Joomla-Konfiguration. Meist liegt er im /administrator/-Verzeichnis. Theoretisch kann man einen eigenen eintragen, doch wozu?
  • In einem Joomla, das schon mal ein Update erlebt hat, findet man ziemlich sicher die Datei joomla_update.php. Und, welch Wunder, darin das Protokoll der letzten Joomla-Updates.
  • In Joomla 4 gibt es unterhalb des Feldes "Protokollverzeichnis" die Einstellungen "Protokollieren" und "Veraltete (deprecated) API protokollieren". Wenn man diese aktiviert, werden nahezu in jedem Joomla die Dateien everything.php und deprecated.php angelegt. Bei Interesse kann man ja mal reinschauen, sollte allerdings nicht glauben, dass besonders zweitere für das alltägliche Debuggen sonderlich hilfreich ist.
  • PHP-Logdateien im Protokollverzeichnis werden regelmäßig gelöscht. Zuständig ist dafür das Core-Plugin namens "System – Protokollrotation". Mir ist das meist zu knapp eingestellt. Muss jeder selber entscheiden. Es ist möglich, mehrere, durchnummerierte Logdateien des selben Typs vorzuhalten. Auch das bedeutet eine größere Lebenszeit der Logbücher-Einträge und die einzelnen Dateien werden nicht so groß. Muss jeder...
  • Nettes Feature, wenn man den Joomla-Logger verwendet. Server-Pfade werden in der Protokolldatei als [ROOT] maskiert. Z.B.: [ROOT]/templates/j51_robyn/less/template.less

Einen eigenen Logger einrichten und verwenden

Die Joomla-eigene PHP-Klasse Log ermöglicht es, eigene Meldungen in eine eigene Datei im konfigurierten logs/-Verzeichnis zu schreiben, ohne, dass der Seitenbesucher etwas davon mitbekommt. Zwar gibt es auch eine Variante, die sowohl Texte in die Logs schreibt als auch auf der Webseite anzeigt, aber die ist hier nicht Thema.

Im Beispiel verwende ich ein eigenes System-Plugin "lessghsvs" von mir. Ist aber wurst, da man einen Logger in nahezu jeder Joomla-PHP-Datei, in jeder Erweiterung, jedem Override, Template usw., initialisieren kann. Und danach hat jede andere PHP-Datei im Joomla-Ablauf Zugriff darauf, um zu loggende Nachrichten in's eigene Logbuch zu schreiben. Ich nutze meinen Logger allerdings nur innerhalb meines Plugins in der Hauptdatei /plugins/system/lessghsvs/lessghsvs.php., um einzelne Schritte als Infos, Warnungen oder Konfigurations-Fehler in den Plugin-Einstellungen, die zum Abbruch führten, aufzuzeichnen.

Schritt 1: Eine use-Zeile an den Anfang der initialisierenden Datei

Ich gebe im Folgenden zusätzlich Alternativen an, wenn man auf diese verzichten möchte oder nicht weiß, wo diese Zeile hingehört.

use Joomla\CMS\Log\Log;

Schritt 2: Den eigenen Logger initialiseren, dem Joomla-System bekannt machen

$options = array(
	'text_file' => 'plgSystemLessghsvs.php',
	'text_entry_format' => '{DATETIME}	{PRIORITY}	{MESSAGE}',
);

Log::addLogger(
	$options,
	Log::ALL,
	array('lessghsvs')
);

In Zeilen 1 bis 4 stelle ich die Konfigurations-Optionen für den Logger zusammen. Als text_file sollte man immer eine eigene, individuelle Datei angeben und aus Sicherheitsgründen die Endung *.php verwenden. Joomla verwendet sonst error.php, was aber durchaus zu Kuddelmuddel im Logbuch führen kann.

Das Ausgabeformat für meine Debug-Notizen, text_entry_format, in Zeile 3 gebe ich an, weil ich nur die drei Spalten Datum, Nachrichten-Art (siehe unten Log-Levels) und natürlich den Meldungstext sehen will. Lässt man diese Konfigurations-Option weg, verwendet Joomla eine Voreinstellung wie z.B.

{DATE}	{TIME}	{PRIORITY}	{CLIENTIP}	{CATEGORY}	{MESSAGE}

Da kann ja das Interessierte:Inne selber rumprobieren, was für es "hübsch" ist.

Zeilen 6 bis 10 übergeben nun an die Log-Klasse meinen Wunsch "Ich hätte gerne folgenden Logger eingerichtet.". Log::ALL in Zeile 8, auf die ich ansonsten nicht weiter eingehe, garantiert uns, dass wirklich alle übergebenen Nachrichten aufgezeichnet werden, egal welche "PRIORITY", welchen Log-Level (siehe unten) sie haben. Zeile 9 enthät ein Array mit in meinem Fall nur 1 "CATEGORY", auf die mein Loggersystem lauschen soll. Nur, wenn ich die später mitgebe, weiß die Log-Klasse, welches Logbuch verwendet werden soll. Die CATEGORY-Kürzel sind beliebig. Ich könnte auch "firlefanz" genommen haben oder "lessghvs" UND "firlefanz" UND...

Code-Alternative, wenn man keine use-Zeile verwendet
$options = array(
	'text_file' => 'plgSystemLessghsvs.php',
	'text_entry_format' => '{DATETIME}	{PRIORITY}	{MESSAGE}',
);

\Joomla\CMS\Log\Log::addLogger(
	$options,
	\Joomla\CMS\Log\Log::ALL,
	array('lessghsvs')
);

Schritt 3: Die eigene Log-Datei nutzen

So schreibt man eine Debug-Nachricht in seine Log-Datei und kann natürlich hier oder dort beliebig viele ähnliche Zeilen im System nutzen, um weitere aufzuzeichnen:

$msg = 'Keine Lust mehr. Ich breche ab!';
Log::add($msg, Log::ERROR, 'lessghsvs');

Nun finde ich in meiner Datei /administrator/logs/plgSystemLessghsvs.php die Zeile

2022-10-15T20:12:29+00:00	ERROR	Keine Lust mehr. Ich breche ab!
Code-Alternative, wenn man keine use-Zeile verwendet

Man sieht schon, dass eine use-Zeile am Anfang der Datei meist praktischer ist. Aber, dran denken, wenn man die Kurzform in anderen Dateien nutzt, brauchen die ebenso eine use-Zeile. Abwägungssache, was letzendlich mehr nervt.

$msg = 'Keine Lust mehr. Ich breche ab!';
\Joomla\CMS\Log\Log::add($msg, \Joomla\CMS\Log\Log::ERROR, 'lessghsvs');

Log-Levels, PRIORITY

Im letzten Code-Block verwende ich ein komisches Log::ERROR. In unserem einfachen Beispiel steckt da gar nicht viel Magie dahinter. In unserer Logbuch-Zeile wird das übersetzt nach "ERROR". Bei komplexer eingerichteten Logger-Instanzen, haben diese Log-Level unter Umständen tieferen Sinn. Deshalb verwende ich brav diese Log-Level-Konstanten wie in Joomla definiert. Je nachdem, wie ich meine Logzeile auszeichnen möchte-

const EMERGENCY = 'emergency';
const ALERT = 'alert';
const CRITICAL = 'critical';
const ERROR = 'error';
const WARNING = 'warning';
const NOTICE = 'notice';
const INFO = 'info';
const DEBUG = 'debug';