So behebst du den Fehler: Did you forget a use statement for another namespace? in Shopware 6.

Prüfe die vollständige Fehlermeldung und die betroffene PHP-Datei

Die Meldung „Did you forget a use statement for another namespace?“ entsteht meist beim Kompilieren oder Ausführen eines eigenen Plugins. Entscheidend ist nicht der komplette Log, sondern die erste konkrete Dateiangabe mit Pfad, Zeilennummer und Klassennamen.

Suche im Fehlerprotokoll nach einem Eintrag wie src/Subscriber/OrderSubscriber.php:42. Öffne diese Datei und prüfe die genannte Zeile sowie den Bereich direkt darüber. Der Fehler sitzt oft nicht in der markierten Zeile selbst. Ein Methodenaufruf wie new Context() kann korrekt aussehen, obwohl die zugehörige Klasse im Namespace der Datei nicht gefunden wird.

• Notiere den vollständigen Klassennamen aus der Fehlermeldung.
• Prüfe, ob die betroffene Datei wirklich zum aktiven Plugin gehört.
• Vergleiche den Namespace in der ersten Zeile der Datei mit dem Ordnerpfad.
• Kontrolliere Groß- und Kleinschreibung bei Datei- und Klassennamen.
• Beachte, ob der Fehler aus src/, vendor/ oder dem Cache stammt.

Ein unbekannter Klassenname ohne führenden Backslash wird zunächst im Namespace der aktuellen Datei gesucht. Befindet sich die Klasse etwa unter App\Storefront, sucht PHP Context dort und nicht automatisch unter dem Namespace der benötigten Shopware-Klasse.

Finde die nicht aufgelöste Klasse im Shopware-6-Code

Suche den nicht aufgelösten Klassennamen direkt im betroffenen PHP-Code. Typische Auslöser sind new, Rückgabetypen, Parameter, Eigenschaften sowie instanceof.

Nutze die Suchfunktion deiner Entwicklungsumgebung und suche nach dem exakten Namen aus der Fehlermeldung. Prüfe dabei alle Schreibweisen. EntityRepository, Entityrepository und EntityRepositoryInterface sind für PHP drei verschiedene Bezeichner. Auch ein fehlendes Interface am Ende führt schnell in die falsche Richtung.

• Markiere jede Verwendung des Klassennamens in der Datei.
• Prüfe, ob ein Alias mit as den erwarteten Namen ersetzt.
• Suche nach gleichnamigen Klassen im Plugin und im Shopware-Core.
• Kontrolliere, ob ein Trait, Interface oder eine konkrete Klasse gemeint ist.
• Beziehe generierte Dateien und ältere Plugin-Kopien nicht in die Korrektur ein.

Für die Zuordnung hilft die IDE-Funktion „Gehe zur Definition“. Führt sie zu keiner Datei, ist der Import vermutlich nicht vorhanden oder die Abhängigkeit fehlt. Führt sie zu einer unerwarteten Klasse, liegt oft ein Namenskonflikt vor. Der vollständig aufgelöste Namespace zeigt dann, welcher Typ tatsächlich verwendet werden soll.

Bei Shopware-6-Services lohnt sich außerdem ein Blick auf den Konstruktor. Wird dort etwa ein Repository, ein Event oder ein Verkaufskanal-Kontext typisiert, muss genau der dafür vorgesehene Interface-Name verwendet werden. Eine ähnlich benannte Klasse aus einem anderen Modul kann syntaktisch plausibel wirken, aber beim Container-Aufbau scheitern.

Ergänze die passende use-Anweisung am Anfang der Datei

Setze die passende use-Anweisung nach der Namespace-Deklaration und vor der ersten Klassen- oder Funktionsdefinition. Verwende den vollständigen Namespace der benötigten Klasse:

use Shopware\Core\Framework\Context;

Danach kann der Code den kurzen Namen Context verwenden. Der Import gilt für die gesamte Datei, nicht nur für eine einzelne Methode. Mehrere Klassen erhalten jeweils eine eigene Zeile:

use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;

Vermeide doppelte Imports. Bei gleichen kurzen Namen nutzt du Aliase:

use Vendor\First\Mailer as FirstMailer;
use Vendor\Second\Mailer as SecondMailer;

Im Code rufst du anschließend FirstMailer oder SecondMailer auf. Der Alias darf nur Buchstaben, Zahlen und Unterstriche enthalten und sollte den Ursprung verständlich machen.

• Importe stehen außerhalb der Klasse.
• Nach jeder use-Anweisung folgt ein Semikolon.
• Eine use-Zeile importiert eine Klasse, ein Interface oder einen Trait.
• Funktions- und Konstantenimporte benötigen bei Bedarf die Zusätze function oder const.

Für Shopware-Plugins sind einzelne, klar lesbare Imports meist die robustere Wahl. Dadurch erkennst du schneller, welche Abhängigkeiten die Datei tatsächlich nutzt.

Korrigiere Namespace und Klassennamen bei eigenen Plugins

Bei eigenen Plugins müssen Namespace, Ordner und Composer-Autoloading zusammenpassen. Prüfe zuerst die PSR-4-Zuordnung in der composer.json. Für das Plugin Acme\Demo sieht sie zum Beispiel so aus:

"autoload": { "psr-4": { "Acme\\Demo\\": "src/" } }

Eine Datei unter src/Service/PriceService.php beginnt dann mit:

namespace Acme\Demo\Service;

Die Klasse muss exakt PriceService heißen. Daraus ergibt sich der vollständige Klassenname Acme\Demo\Service\PriceService. Schon ein abweichender Buchstabe, ein falscher Unterordner oder ein zusätzlicher Namespace-Teil genügt, damit der Autoloader die Klasse nicht findet.

• Der Namespace endet passend zum Ordner unter src/.
• Der Klassenname entspricht dem Dateinamen.
• Die Groß- und Kleinschreibung bleibt überall gleich.
• Die Datei enthält nur eine passende Namespace-Deklaration.
• Der Klassenname im Service-Container stimmt mit dem PHP-Namespace überein.

Prüfe außerdem Verweise in services.xml, services.yaml und den PHP-Attributen. Ein alter Namespace in der Service-Konfiguration kann denselben Fehler auslösen, obwohl die PHP-Datei korrekt aussieht. Nach einer Umbenennung müssen daher alle Referenzen angepasst werden.

Falls das Plugin einen Hersteller-Namespace wie Acme\Demo verwendet, darf es nicht versehentlich mit einem generischen Namen wie Plugin beginnen. Solche Namen führen leicht zu Kollisionen mit anderen Erweiterungen. Die PSR-4-Struktur ist die Landkarte, nach der PHP die Klasse findet.

Verwende den vollständigen Namespace als schnelle Alternative

Als schnelle Zwischenlösung kannst du den vollständigen Namespace direkt an der Verwendungsstelle schreiben. Dadurch entfällt der Import am Dateianfang:

$context = new \Shopware\Core\Framework\Context();

Der führende Backslash startet die Auflösung im globalen Namespace. Ohne ihn würde PHP den angegebenen Pfad zunächst relativ zum Namespace der aktuellen Datei interpretieren.

Auch bei Typdeklarationen funktioniert diese Schreibweise:

public function load(\Shopware\Core\Framework\Context $context): void

Sie eignet sich vor allem für eine kurze Prüfung oder einen selten verwendeten Typ. In dauerhaftem Plugin-Code wird die lange Schreibweise schnell unübersichtlich; mehrere Vorkommen erhöhen zudem den Änderungsaufwand.

• Nutze den vollständigen Namespace, wenn nur eine einzelne Stelle betroffen ist.
• Setze den führenden Backslash bei einer globalen Auflösung.
• Verwende die Schreibweise nicht innerhalb eines Strings.
• Prüfe bei verschachtelten Namespaces die exakte Reihenfolge aller Bestandteile.

Bei Rückgabetypen, Eigenschaften und Konstruktorparametern ist die direkte Angabe ebenfalls möglich. Sie hilft besonders, wenn ein kurzer Klassenname mit einer anderen Abhängigkeit kollidiert. Sobald der Code stabil läuft, kannst du die lange Angabe bei Bedarf durch einen klaren Import ersetzen.

Prüfe Unterschiede zwischen Shopware-Versionen und Dokumentation

Prüfe, ob der verwendete Klassenpfad zur installierten Shopware-Version passt. Shopware 6 verändert interne Strukturen zwischen Minor-Releases. Klassen aus dem Storefront-, Administration- oder Core-Bereich können verschoben, umbenannt oder durch Interfaces ersetzt werden. Eine Dokumentationsseite für 6.6 muss daher nicht unverändert für 6.5 gelten.

Ermittle zuerst die exakte Version mit composer show shopware/core. Vergleiche sie anschließend mit dem passenden Branch der offiziellen Shopware-Dokumentation und mit der installierten Datei unter vendor/shopware/core/. Entscheidend ist der Code, den Composer tatsächlich installiert hat, nicht ein Suchtreffer aus einer anderen Version.

• Vergleiche den Namespace der Zielklasse mit dem Versionszweig der Dokumentation.
• Prüfe, ob die Klasse in deiner Version noch existiert.
• Kontrolliere, ob ein Interface an die Stelle einer konkreten Klasse getreten ist.
• Beachte Hinweise zur Abwärtskompatibilität und zu entfernten APIs.
• Verwende keine Beispiel-Namespaces aus einer älteren Plugin-Anleitung ungeprüft.

Auch die PHP-Version spielt eine Rolle. Shopware 6.6 setzt je nach Unterversion andere PHP-Versionen voraus als ältere Releases. Läuft das Plugin mit einer nicht unterstützten Kombination, können Fehlermeldungen an Stellen erscheinen, die zunächst wie ein reiner Namespace-Fehler wirken. Die Kompatibilitätsangaben in composer.json und der Shopware-Upgrade-Dokumentation schaffen hier Klarheit.

Wenn Dokumentation und Quellcode abweichen, hat die konkrete Installation Vorrang. Notiere die Shopware- und PHP-Version im Fehlerbericht, damit sich später ein Upgrade, eine veraltete Anleitung oder eine geänderte API als Ursache nachvollziehen lässt.

Leere Cache und Autoloader nach der Änderung

Nach einer Namespace-Änderung können Shopware und Composer noch alte Klassenpfade verwenden. Leere deshalb zuerst den Shopware-Cache im Projektverzeichnis:

bin/console cache:clear

Für eine Entwicklungsumgebung kannst du den Cache auch über bin/console cache:clear --env=dev löschen. In einer produktiven Umgebung sollte der Befehl im passenden Wartungsfenster laufen, weil Shopware den Cache danach neu aufbaut.

Erstelle anschließend den Composer-Autoloader neu:

composer dump-autoload

Bei einer optimierten Produktionsinstallation ist zusätzlich folgende Variante sinnvoll:

composer dump-autoload --optimize

Prüfe danach, ob der Plugin-Code aktiviert und installiert ist. Falls die Erweiterung zuvor deaktiviert wurde, helfen je nach Änderung diese Befehle:

• bin/console plugin:refresh erkennt geänderte Plugin-Metadaten.
• bin/console plugin:update DeinPlugin führt das Update des Plugins aus.
• bin/console plugin:activate DeinPlugin aktiviert die Erweiterung erneut.

Bei einem laufenden PHP-FPM-Prozess kann zusätzlich ein Neustart nötig sein, wenn OPcache alte Bytecodes hält. Starte PHP-FPM nur nach den Regeln deiner Hosting- oder Serverumgebung neu. Bleibt danach dieselbe Zeilennummer mit dem alten Klassennamen bestehen, wurde meist noch ein Cache oder Prozess nicht neu geladen.

Teste das Plugin und behebe weitere Namespace-Fehler

Starte das Plugin nach der Korrektur mit einem gezielten Test. Rufe zuerst den Bereich auf, in dem die betroffene Klasse verwendet wird. Bei einem Subscriber oder Service reicht ein Seitenaufruf oft nicht aus: Führe den passenden Warenkorb-, Bestell- oder API-Ablauf aus.

• Teste den normalen Ablauf mit gültigen Daten.
• Prüfe auch einen leeren Warenkorb oder fehlende optionale Werte.
• Führe einen CLI-Befehl aus, wenn der Fehler aus einem Command stammt.
• Kontrolliere den Log auf neue Klassennamen und Dateipfade.

Bleibt ein Fehler bestehen, bearbeite immer den ersten neuen Namespace-Hinweis. Folgefehler entstehen oft, weil PHP beim Laden einer abhängigen Klasse abbricht. Eine lange Liste ähnlicher Meldungen bedeutet daher nicht automatisch, dass jede Datei separat defekt ist.

Für eine schnelle Eingrenzung hilft ein kleiner isolierter Test. Instanziiere den betroffenen Service über den Shopware-Container oder führe den zugehörigen PHPUnit-Test aus. So trennst du einen Fehler beim Klassenladen von Problemen in Geschäftslogik, Datenbankzugriff oder Ereignisverarbeitung.

Prüfe nach erfolgreichem Start außerdem die Service-Definition. Wird der Dienst zwar geladen, aber nicht aufgelöst, fehlen möglicherweise ein Konstruktor-Argument, ein Interface-Binding oder eine korrekte Sichtbarkeit. Erst wenn Laden und konkreter Ablauf funktionieren, ist die Korrektur abgeschlossen.

Beispiel: Eine Klasse aus dem Shopware-Core korrekt einbinden

Ein häufiger Fall ist ein Subscriber, der auf ein Shopware-Ereignis reagiert und dafür den Warenkorb-Kontext benötigt. Die Klasse wird oben in der PHP-Datei eingebunden:

use Shopware\Core\Framework\Context;

Danach kann der Typ in einer Methode verwendet werden:

public function readData(Context $context): void
{
    // Daten mit dem Kontext verarbeiten
}

Context dient hier nur als Beispiel für einen Core-Typ. Die Methode muss zum tatsächlichen Service passen. Wird der Parameter in einem Subscriber verwendet, prüfe zusätzlich, ob das ausgelöste Ereignis wirklich einen passenden Kontext liefert. Ein Event-Objekt und ein Framework-Kontext sind nicht austauschbar, auch wenn beide im gleichen Ablauf auftreten.

Bei einem Repository sieht ein typischer Konstruktor so aus:

use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;

final class ProductReader
{
    public function __construct(
        private readonly EntityRepository $productRepository
    ) {
    }
}

Die konkrete Repository-Instanz wird in der Service-Konfiguration festgelegt. Der PHP-Typ allein entscheidet also nicht, welches Repository injiziert wird. Prüfe deshalb, ob der konfigurierte Service zum erwarteten Datenobjekt gehört. Sonst ist der Namespace zwar korrekt, aber die Anwendung arbeitet später mit dem falschen Dienst.

• Importiere die Core-Klasse aus ihrem tatsächlichen Modul.
• Nutze bei Parametern den passenden Interface- oder Klassentyp.
• Stimme PHP-Signatur und Service-Konfiguration aufeinander ab.
• Verwende keine Storefront-Klasse, wenn der Dienst im Admin- oder API-Kontext läuft.

Der Namespace-Import löst den Klassennamen auf. Die Dependency-Injection-Konfiguration entscheidet anschließend, welches Objekt Shopware zur Laufzeit liefert.

Fazit: Namespace prüfen, use ergänzen und Plugin testen

Der Fehler „Did you forget a use statement for another namespace?“ ist in Shopware 6 meist schnell eingegrenzt: PHP kann einen verwendeten Typ nicht eindeutig auflösen. Eine saubere Abschlussprüfung verhindert, dass die Änderung nur den aktuellen Fehler verdeckt.

• Code: Der verwendete Typ stammt aus dem erwarteten Namespace und passt zur Shopware-Version.
• Abhängigkeiten: Die Klasse ist im Plugin tatsächlich verfügbar und wird nicht nur durch eine alte Referenz angesprochen.
• Laufzeit: Der Dienst wird im vorgesehenen Shopware-Kontext geladen und erhält die richtigen Argumente.
• Qualität: Ein automatisierter Test oder ein reproduzierbarer Fachablauf deckt die betroffene Funktion ab.

Entferne nach der Behebung ungenutzte Imports und provisorische vollständige Klassennamen. Das hält die Datei übersichtlich und verhindert, dass ein späteres Upgrade alte Abhängigkeiten unbemerkt weiterträgt. Bei wiederkehrenden Fehlern lohnt sich außerdem eine feste PHPStan- oder Psalm-Prüfung in der CI-Pipeline. Solche Werkzeuge erkennen viele unbekannte Klassen bereits vor dem Deployment.

Führt die Korrektur in der Entwicklungsumgebung zum Erfolg, sollte derselbe Commit in einer möglichst ähnlichen Testumgebung geprüft werden. So fallen Unterschiede bei PHP-Erweiterungen, Composer-Abhängigkeiten oder der Plugin-Konfiguration auf, bevor der Fehler im Shopbetrieb landet.

FAQ zur Behebung von Namespace-Fehlern in Shopware 6