webart-IT - Wissensdatenbank

Joomla: „Class JPlugin, JFactory oder JComponentHelper not found“ – so beheben Sie den Fehler

Nach einem Joomla-Update funktioniert die Website plötzlich nicht mehr. Statt der gewohnten Inhalte erscheint eine Fehlermeldung, das Backend lässt sich nicht mehr öffnen oder der Browser zeigt nur noch eine weiße Seite.

Besonders häufig begegnen Joomla-Administratoren dabei diesen PHP-Fehlermeldungen:

Class "JPlugin" not found
Class "JFactory" not found
Class "JComponentHelper" not found

Die gute Nachricht: In vielen Fällen ist nicht die gesamte Joomla-Installation beschädigt. Vielmehr versucht eine ältere Erweiterung, eine PHP-Klasse aufzurufen, die unter der eingesetzten Joomla-Version nicht mehr unter ihrem bisherigen Namen verfügbar ist.

Wir erklären, woher diese Fehler kommen, wie Sie den Verursacher finden und welche Lösungen für Joomla 4, Joomla 5 und Joomla 6 infrage kommen.

Warum findet Joomla diese Klassen nicht mehr?

Joomla wurde in den vergangenen Jahren technisch umfassend modernisiert. Dabei hat sich unter anderem geändert, wie PHP-Klassen organisiert und angesprochen werden.

In älteren Joomla-Versionen wurden zahlreiche Klassen über kurze Namen wie JFactory, JPlugin oder JComponentHelper aufgerufen.

Heute verwendet Joomla überwiegend sogenannte Namespaces. Damit erhalten Klassen eine eindeutige Zuordnung innerhalb der Joomla-Architektur.

Ein Beispiel:

Früher:

$app = JFactory::getApplication();

Heute:

use Joomla\CMS\Factory;

$app = Factory::getApplication();

Beide Varianten verfolgen grundsätzlich dasselbe Ziel. Der Unterschied liegt darin, wie die benötigte PHP-Klasse angesprochen wird.

Damit vorhandene Erweiterungen nicht sofort angepasst werden mussten, hat Joomla über längere Zeit die alten Klassennamen weiterhin unterstützt.

Diese Abwärtskompatibilität ist jedoch nicht unbegrenzt verfügbar. Insbesondere beim Wechsel auf eine neue Joomla-Hauptversion können ältere Klassennamen wegfallen.

Wichtig: Nicht jede „Class not found“-Meldung entsteht durch einen entfernten Klassennamen. Auch unvollständige Updates, fehlerhafte Autoloader oder PHP-Dateien, die außerhalb der regulären Joomla-Umgebung ausgeführt werden, können solche Fehler verursachen.

1. Fehler: Class "JPlugin" not found

Diese Fehlermeldung weist häufig auf ein älteres Joomla-Plugin hin.

Viele Plugins wurden ursprünglich mit der Basisklasse JPlugin programmiert. In modernen Joomla-Versionen wird dafür die Klasse CMSPlugin verwendet.

Ein älteres Plugin kann beispielsweise folgende Anweisung enthalten:

class PlgSystemExample extends JPlugin
{
}

Die modernisierte Schreibweise lautet:

use Joomla\CMS\Plugin\CMSPlugin;

class PlgSystemExample extends CMSPlugin
{
}

Wie lässt sich der Fehler beheben?

Prüfen Sie zuerst, welches Plugin die Meldung auslöst.

Im PHP-Fehlerprotokoll finden Sie normalerweise einen Hinweis auf die betreffende Datei. Beispielsweise:

/plugins/system/example/example.php

In diesem Fall sollten Sie kontrollieren, ob für das System-Plugin example eine neuere Version verfügbar ist.

Ist die Erweiterung mit Ihrer Joomla-Version kompatibel, installieren Sie das entsprechende Update.

Handelt es sich um eine selbst entwickelte Erweiterung, muss der PHP-Code angepasst werden.

Beachten Sie dabei, dass moderne Joomla-Plugins weitere Anforderungen erfüllen können. Es reicht deshalb nicht in jedem Fall aus, lediglich JPlugin durch CMSPlugin zu ersetzen.

2. Fehler: Class "JFactory" not found

JFactory ist einer der bekanntesten Klassennamen aus älteren Joomla-Versionen.

Die Klasse wurde beispielsweise verwendet, um auf die Joomla-Anwendung zuzugreifen.

Ein typischer älterer Aufruf lautet:

$app = JFactory::getApplication();

Der entsprechende moderne Aufruf:

use Joomla\CMS\Factory;

$app = Factory::getApplication();

Alternativ kann die Klasse über ihren vollständigen Namen angesprochen werden:

$app = \Joomla\CMS\Factory::getApplication();

Woher kommt der Fehler?

Häufig steckt der Aufruf in einer PHP-Datei, die seit längerer Zeit nicht mehr aktualisiert wurde.

Typische Fundstellen sind:

Ältere Joomla-Komponenten, Module und Plugins
Individuell angepasste Templates
Selbst erstellte Template-Overrides
Eigene PHP-Skripte oder ältere Erweiterungen von Drittanbietern

Besonders bei Template-Overrides lohnt sich eine genauere Kontrolle.

Ein Override wird durch ein Update der ursprünglichen Erweiterung nicht automatisch modernisiert. Deshalb kann ein Template auch dann noch veralteten PHP-Code enthalten, wenn Joomla und die betreffende Erweiterung bereits auf dem aktuellen Stand sind.

So beheben Sie den Fehler

Ermitteln Sie anhand des Fehlerprotokolls die betreffende PHP-Datei.

Prüfen Sie anschließend, ob die Datei JFactory verwendet und ob sie zu einer Erweiterung gehört, für die bereits ein Update existiert.

Bei selbst entwickeltem Code lässt sich der Klassenaufruf in vielen Fällen auf Joomla\CMS\Factory umstellen.

Achtung: Verwenden Sie nicht einfach eine globale Suchen-und-Ersetzen-Funktion über die gesamte Joomla-Installation. Änderungen sollten gezielt in den betroffenen eigenen Dateien durchgeführt werden.

3. Fehler: Class "JComponentHelper" not found

Die Klasse JComponentHelper wurde früher verwendet, um unter anderem Konfigurationswerte von Joomla-Komponenten auszulesen.

Ein Beispiel:

$params = JComponentHelper::getParams('com_content');

Der moderne Aufruf lautet:

use Joomla\CMS\Component\ComponentHelper;

$params = ComponentHelper::getParams('com_content');

Was ist hier besonders zu beachten?

Anders als manche anderen früheren Klassennamen wurde der Alias JComponentHelper in Joomla 5 zunächst weiterhin direkt bereitgestellt.

Deshalb bedeutet diese Fehlermeldung nicht automatisch, dass das Backward-Compatibility-Plugin deaktiviert ist.

Mögliche Ursachen sind unter anderem:

Die PHP-Datei wird außerhalb der regulären Joomla-Umgebung ausgeführt.
Die Joomla-Installation wurde nicht vollständig aktualisiert.
Eine Erweiterung verwendet einen nicht mehr unterstützten Klassenaufruf.
Der Autoloading-Mechanismus funktioniert nicht ordnungsgemäß.

Auch hier sollte der vollständige Fehlerbericht überprüft werden, bevor Änderungen vorgenommen werden.

Bei einer eigenen Erweiterung empfiehlt sich die Umstellung auf Joomla\CMS\Component\ComponentHelper.

4. Joomla 5: Das Backward-Compatibility-Plugin prüfen

Joomla 5 enthält eine wichtige Funktion, um ältere Erweiterungen vorübergehend weiter betreiben zu können.

Das Plugin heißt:

Behaviour – Backward Compatibility

Es kann unter anderem frühere Klassennamen bereitstellen, die in älteren Erweiterungen noch verwendet werden.

So kontrollieren Sie das Plugin

Öffnen Sie die Joomla-Administration.
Navigieren Sie zu System → Plugins.
Suchen Sie nach Backward Compatibility.
Öffnen Sie das Plugin Behaviour – Backward Compatibility.
Kontrollieren Sie, ob es aktiviert ist und die Einstellung zum Laden älterer Klassen-Aliase aktiv ist.

Ist das Plugin deaktiviert, kann dies erklären, warum bestimmte ältere Erweiterungen plötzlich nicht mehr funktionieren.

Eine Aktivierung kann in solchen Fällen helfen, die Website zunächst wieder lauffähig zu machen.

Allerdings ist das keine dauerhafte Problemlösung.

Langfristig sollten sämtliche installierten Erweiterungen ohne die alten Klassen-Aliase funktionieren.

5. Joomla 6: Warum ältere Erweiterungen erneut Probleme verursachen können

Mit Joomla 6 wurde die Abwärtskompatibilität weiter angepasst.

Besonders wichtig ist die Unterscheidung zwischen zwei Plugins:

Behaviour – Backward Compatibility

Dieses Plugin dient der Kompatibilität zwischen Joomla 4 und Joomla 5. Vor einem Upgrade auf Joomla 6 muss es deaktiviert werden.

Behaviour – Backward Compatibility 6

Dieses Plugin unterstützt die Kompatibilität zwischen Joomla 5 und Joomla 6.

Es ist bereits in Joomla 5.4 enthalten und wird bei einem Upgrade auf Joomla 6 benötigt.

Was bedeutet das für ein Joomla-Upgrade?

Eine ältere Erweiterung, die unter Joomla 5 nur durch das erste Kompatibilitäts-Plugin funktioniert, ist nicht automatisch für Joomla 6 geeignet.

Vor dem Wechsel auf Joomla 6 sollten Sie deshalb prüfen, ob Ihre Website unter Joomla 5.4 auch dann noch funktioniert, wenn das bisherige Plugin Behaviour – Backward Compatibility deaktiviert ist.

Unsere Empfehlung: Führen Sie diesen Test ausschließlich in einer Testumgebung durch. So verhindern Sie, dass eine inkompatible Erweiterung die produktive Website lahmlegt.

Erst wenn Joomla und die installierten Erweiterungen ohne das alte Plugin funktionieren, sollte das Upgrade auf Joomla 6 erfolgen.

6. Wie finde ich heraus, welche Erweiterung den Fehler verursacht?

Wenn Sie nicht wissen, welche Erweiterung für die Fehlermeldung verantwortlich ist, hilft häufig ein Blick in das PHP-Fehlerprotokoll.

Eine typische Meldung könnte so aussehen:

Fatal error: Uncaught Error:
Class "JFactory" not found

in /plugins/system/example/example.php
on line 125

Entscheidend sind der Dateipfad und die Zeilennummer.

In unserem Beispiel wird der Fehler in einem System-Plugin namens example ausgelöst.

Schritt 1: PHP-Fehlerprotokoll öffnen

Wenn Ihre Website über Plesk verwaltet wird, finden Sie entsprechende Informationen normalerweise unter:

Websites & Domains → Protokolle

Dort können Sie nach PHP-Fehlern und dem betroffenen Dateipfad suchen.

Achten Sie auch auf den vollständigen Stack-Trace. Er zeigt, über welche Dateien und Funktionen der Fehler entstanden ist.

Schritt 2: Erweiterung kontrollieren

Sobald der Verursacher bekannt ist, prüfen Sie, ob ein Update angeboten wird.

Vergewissern Sie sich, dass die neue Version ausdrücklich mit Ihrer eingesetzten Joomla-Version kompatibel ist.

Schritt 3: Fehlerhafte Erweiterung deaktivieren

Ist das Joomla-Backend noch erreichbar, können Sie die betroffene Erweiterung gegebenenfalls über die Erweiterungsverwaltung deaktivieren.

Wenn Sie keinen Zugriff mehr auf die Administration haben, kann im Notfall eine Deaktivierung über die Datenbank notwendig sein.

Die installierten Erweiterungen werden in Joomla in folgender Tabelle verwaltet:

#__extensions

Das Zeichen #__ steht dabei für das Tabellenpräfix Ihrer Installation.

Bei einer eindeutig identifizierten Erweiterung kann der Datenbankwert enabled von 1 auf 0 geändert werden.

Dadurch wird der betreffende Erweiterungseintrag deaktiviert.

Wichtig: Sichern Sie vorher die Datenbank. Verändern Sie keine Einträge, deren Funktion Sie nicht eindeutig zuordnen können. Eine falsche Änderung kann weitere Fehler verursachen.

Schritt 4: Website erneut testen

Kontrollieren Sie nach der Aktualisierung oder Deaktivierung, ob Frontend und Backend wieder funktionieren.

Prüfen Sie anschließend auch Funktionen, die von der betroffenen Erweiterung abhängig sein könnten.

7. Was tun, wenn Joomla nur noch eine weiße Seite zeigt?

Nicht jeder PHP-Fehler wird direkt im Browser ausgegeben.

Manchmal erscheint lediglich eine weiße Seite oder ein HTTP-500-Fehler.

Auch dahinter kann sich eine der beschriebenen Fehlermeldungen verbergen.

Prüfen Sie deshalb zuerst das PHP-Fehlerprotokoll Ihres Servers.

Falls die Joomla-Administration weiterhin erreichbar ist, können Sie unter System → Konfiguration → Server die Fehlerausgabe vorübergehend anpassen.

Auf öffentlich erreichbaren Websites sollte eine ausführliche PHP-Fehlerausgabe allerdings nicht dauerhaft aktiviert bleiben.

Fehlermeldungen können interne Dateipfade und andere technische Details offenlegen, die nicht für Besucher bestimmt sind.

8. Wie lassen sich diese Fehler künftig vermeiden?

Viele Kompatibilitätsprobleme lassen sich bereits vor einem Joomla-Upgrade erkennen.

Dafür empfehlen wir einige grundlegende Maßnahmen.

Joomla-Erweiterungen regelmäßig aktualisieren

Halten Sie installierte Komponenten, Module, Plugins und Templates aktuell. Achten Sie darauf, ob der jeweilige Hersteller die eingesetzte Joomla-Version offiziell unterstützt.

Template-Overrides überprüfen

Individuelle Overrides können veralteten PHP-Code enthalten. Deshalb sollten diese bei einem größeren Versionswechsel ebenfalls kontrolliert werden.

Joomla-Upgrades vorher testen

Insbesondere der Wechsel zwischen Hauptversionen sollte auf einer Kopie der produktiven Website getestet werden.

Kompatibilitäts-Plugins nicht als Dauerlösung betrachten

Wenn eine Erweiterung nur mithilfe eines alten Kompatibilitäts-Plugins funktioniert, ist das ein Hinweis auf technischen Anpassungsbedarf.

Regelmäßige Backups erstellen

Eine aktuelle, überprüfte Datensicherung erleichtert die Wiederherstellung, falls während eines Updates unerwartete Probleme auftreten.

Fazit: Meist ist nicht Joomla selbst das Problem

Die Fehlermeldungen Class "JPlugin" not found, Class "JFactory" not found und Class "JComponentHelper" not found sehen zunächst nach einem schwerwiegenden Defekt der Joomla-Installation aus.

Häufig steckt jedoch eine ältere Erweiterung, ein veralteter Template-Override oder eine nicht mehr unterstützte PHP-Anweisung dahinter.

Entscheidend ist, die tatsächliche Ursache anhand des Fehlerprotokolls zu ermitteln.

Das Backward-Compatibility-Plugin kann unter Joomla 5 bei bestimmten Problemen helfen. Für Joomla 6 gelten allerdings andere Voraussetzungen.

Eine dauerhaft zuverlässige Lösung besteht darin, ältere Erweiterungen auf einen aktuellen Stand zu bringen und nicht mehr unterstützten PHP-Code zu modernisieren.

Sie benötigen Unterstützung bei einem Joomla-Update oder einer nicht mehr funktionierenden Erweiterung?

Wir von webart-it.de unterstützen Sie bei der Analyse und Behebung von Joomla-Fehlern, bei der Anpassung älterer Erweiterungen und bei der sicheren Aktualisierung Ihrer Joomla-Website.