Shopware-6.7-Plugin, das im Adminbereich eine eigene Leiste über die volle Breite am oberen Rand einblendet – mit frei wählbarer Beschriftung und bis zu neun Buttons.
PlugwareAdminBar shopware/core: ~6.7.0)Der Shopware-Adminbereich bietet keinen Platz für eigene, dauerhaft sichtbare Hinweise oder Schnellzugriffe. Genau diese Lücke schließt das Plugin: Es setzt eine schmale Leiste über die gesamte Breite an den oberen Rand, die auf jeder Seite des Adminbereichs sichtbar bleibt.
Typische Einsatzzwecke:
Die Leiste ist bewusst schlicht gehalten: kein eigenes Admin-Modul, keine zusätzliche Datenbanktabelle, keine Abhängigkeiten. Alles läuft über die Plugin-Konfiguration.
Das Plugin-Verzeichnis nach custom/plugins/PlugwareAdminBar entpacken oder
das ZIP im Adminbereich unter Erweiterungen → Meine Erweiterungen hochladen.
Danach:
bin/console plugin:refresh
bin/console plugin:install --activate PlugwareAdminBar
bin/console assets:install
bin/console cache:clear
Anschließend den Adminbereich einmal hart neu laden (Strg+F5), damit das JavaScript geladen wird.
bin/console plugin:refresh
bin/console plugin:update PlugwareAdminBar
bin/console assets:install
bin/console cache:clear
assets:install ist bei jedem Update nötig, sobald sich die JS-Datei geändert
hat – sonst liegt im public/-Verzeichnis weiterhin der alte Stand.
Bleibt der Adminbereich nach einem Update weiß? Das liegt fast immer daran,
dass der Browser noch Teile des alten Admin-Bundles im Cache hat, während auf
dem Server bereits neue Dateien liegen. Ein harter Neuladen (Strg+F5, unter
macOS Cmd+Shift+R) löst das. Hilft das nicht, fehlt meist ein cache:clear auf
dem Server.
Bleibt die Seite weiß und die Browser-Konsole meldet
service provider already instantiated gefolgt von einem Fehler in
startBootProcess, kommt man über die Oberfläche nicht mehr an das Plugin
heran. Der Weg über die Konsole:
bin/console plugin:deactivate PlugwareAdminBar
bin/console cache:clear
Danach ist der Adminbereich wieder erreichbar. Das ist zugleich die Probe, ob das Plugin überhaupt die Ursache ist: Bleibt die Seite auch deaktiviert weiß, liegt es woanders.
Anschließend die aktuelle Fassung einspielen – wichtig ist, dass das
Verzeichnis unter custom/plugins/ wirklich ausgetauscht ist, bevor
plugin:update läuft:
bin/console plugin:refresh
bin/console plugin:update PlugwareAdminBar
bin/console plugin:activate PlugwareAdminBar
bin/console assets:install
bin/console cache:clear
Ob die neue Fassung greift, lässt sich im Seitenquelltext des Adminbereichs
prüfen: Beim Eintrag plugware-admin-bar.js muss die aktuelle Versionsnummer im
Parameter ?v= stehen.
Was dahintersteckte: Bis 1.1.19 hat das Admin-JS im Sekundentakt
Shopware.Service('loginService') aufgerufen, sobald diese Funktion überhaupt
existierte – also mitten in Shopwares eigenem Bootvorgang. Ein solcher Zugriff
instanziiert den Service-Provider vorzeitig; Shopware verliert daraufhin seine
Referenz und bricht den Start ab. Eine try/catch-Kapselung half dagegen nicht,
weil der Fehler nicht im Plugin auftrat, sondern im Kern – das Plugin lieferte
nur den Auslöser. Seit 1.1.20 prüft isBooted() vor jedem Service-Zugriff, ob
#app gefüllt ist und Shopware.Application.getApplicationRoot() eine Wurzel
liefert.
Als Nebeneffekt baut sich die Leiste seither etwas später auf, weil sie den Start abwartet.
Das Plugin bringt dafür zwei Automatismen mit:
cache:clear scheidet damit als Ursache aus.Darüber hinaus ist es so gebaut, dass es diesen Zustand nicht auslösen kann:
defer und einem Versionsparameter eingebunden. Nach
einem Update lädt der Browser dadurch zwingend die neue Datei.assets:install vergessen,
erscheint schlicht keine Leiste – ohne Folgen für den Rest.bin/console plugin:deactivate PlugwareAdminBar
bin/console plugin:uninstall PlugwareAdminBar
bin/console cache:clear
Das Plugin legt keine eigenen Tabellen an. Beim Deinstallieren entfernt Shopware
die Konfigurationswerte aus system_config.
Einstellungen → System → Plugins → Plugware Developer Admin Tool Bar → Konfiguration
Die Konfiguration ist in zwölf Karten unterteilt: drei für die Leiste selbst und je eine pro Button.
| Feld | Bedeutung | Standard |
|---|---|---|
| Leiste anzeigen | Schaltet die Leiste ein und aus, ohne das Plugin zu deaktivieren | an |
| Beschriftung anzeigen | Blendet den Text links in der Leiste ein und aus | an |
| Beschriftung | Einzeiliger Text am linken Rand. Einfaches HTML ist erlaubt, z. B. <a href="/">Zum Shop</a> oder <strong>Testsystem</strong> |
Plugware |
| Plugin-Icon anzeigen | Zeigt das Icon des Plugins links vor der Beschriftung | an |
| Größe des Plugin-Icons in Pixel | Kantenlänge des Icons | 32 |
| Ausrichtung | Links, zentriert oder rechts. Gilt für die Buttons – die Beschriftung steht immer links | zentriert |
| Feld | Bedeutung | Standard |
|---|---|---|
| Höhe in Pixel | Höhe der Leiste. Der Adminbereich rückt entsprechend nach unten | 48 |
| Hintergrundfarbe | Farbe der Leiste | #243758 |
| Schriftfarbe | Farbe des Textes. Aus ihr leiten sich auch die Buttonflächen ab | #ffffff |
| Schriftgröße in Pixel | Schriftgröße der Beschriftung | 16 |
| Feld | Bedeutung | Standard |
|---|---|---|
| Schriftgröße der Buttons in Pixel | Gilt für Beschriftung und Icon, 0 übernimmt die Schriftgröße der Leiste |
12 |
| Seitlicher Innenabstand der Buttons in Pixel | Abstand zwischen Rahmen und Inhalt, links und rechts | 12 |
| Hintergrundfarbe | Fläche der Buttons | #3E4F6C |
| Schriftfarbe | Text auf den Buttons | #FFFFFF |
| Rahmenfarbe | Rahmen der Buttons | #616F87 |
| Hintergrundfarbe beim Überfahren | Fläche, während die Maus darüber steht | #596780 |
| Schriftfarbe beim Überfahren | Text, während die Maus darüber steht | #FFFFFF |
| Rahmenfarbe beim Überfahren | Rahmen, während die Maus darüber steht | #8791A3 |
| Farbe bei laufendem Befehl | Spinner, Punkte, Rahmen und Fortschrittslinie während der Ausführung | #00FF00 |
| Höhe der Fortschrittslinie in Pixel | Stärke der Linie am unteren Rand der Leiste, 0 blendet sie aus |
5 |
| Lange Laufzeit ab Sekunden | Ab dieser Dauer wechselt die Fortschrittslinie ihre Farbe, 0 schaltet den Wechsel ab |
30 |
| Farbe bei langer Laufzeit | Farbe der Linie nach Überschreiten dieser Dauer | #FF0000 |
Die sechs Farbfelder sind vorbelegt. Die Werte entsprechen genau dem Bild, das
die frühere Automatik auf der Standardleiste erzeugt hat: halbtransparentes
Weiß über #243758, ausgerechnet als feste Farbe.
Leerst du ein Feld, kehrt es zu dieser Automatik zurück und leitet die Farbe wieder aus der Schriftfarbe der Leiste ab. Das ist dann sinnvoll, wenn du eine abweichende Hintergrundfarbe der Leiste verwendest – die Buttons passen sich sonst nicht mit an.
Der Wechsel beim Überfahren ist mit einer Übergangszeit von 0,15 Sekunden animiert und wird bei aktivierter Einstellung "Bewegung reduzieren" im Betriebssystem übersprungen.
| Feld | Bedeutung |
|---|---|
| Icon | Symbol auf dem Button, per Auswahlliste. Standard ist "Aktualisieren" |
| Konsolenbefehl | Befehl, der beim Klick ausgeführt wird. Vorbelegt, siehe unten |
Ein Button erscheint nur, wenn ein Konsolenbefehl gewählt ist. Seine Beschriftung ergibt sich aus dem Befehl, das Icon ist optional.
Nach der Installation sind alle neun Buttons bereits belegt – die unkritischen zuerst, die vier markierten dahinter:
| Karte | Befehl |
|---|---|
| Button 1 | cache:clear |
| Button 2 | cache:warmup |
| Button 3 | assets:install |
| Button 4 | plugin:refresh |
| Button 5 | ⚠ theme:compile |
| Button 6 | ⚠ dal:refresh:index |
| Button 7 | ⚠ sitemap:generate |
| Button 8 | ⚠ media:generate-thumbnails |
| Button 9 | ⚠ cache:clear:all |
Damit ist die Leiste sofort einsatzbereit. Wer weniger möchte, stellt einzelne Karten auf "Kein Befehl" – der Button verschwindet dann aus der Leiste.
Jeder Button löst einen Wartungsbefehl aus. Zur Auswahl stehen neun Befehle:
| Auswahl | Befehl |
|---|---|
| Cache leeren | cache:clear |
| ⚠ Alle Caches leeren | cache:clear:all |
| Cache aufwärmen | cache:warmup |
| Assets installieren | assets:install |
| ⚠ Theme kompilieren | theme:compile |
| Plugin-Liste aktualisieren | plugin:refresh |
| ⚠ Indizes neu aufbauen | dal:refresh:index |
| ⚠ Sitemap erzeugen | sitemap:generate |
| ⚠ Thumbnails erzeugen | media:generate-thumbnails |
Solange der Befehl läuft, ist das an vier Stellen zu sehen:
0
entfällt sie ganz.Die Farbe dieser Signale wird in der Karte "Buttons: Allgemein" eingestellt; leer bedeutet, dass die Schriftfarbe des Buttons verwendet wird. Bei aktivierter Systemeinstellung "Bewegung reduzieren" entfallen die Animationen, die Farbe bleibt als Hinweis erhalten.
Danach erscheint ein Dialog mit der Ausgabe des Befehls und einem Hinweis, ob er erfolgreich war.
Der Button trägt die Bezeichnung des Befehls – etwa "Cache leeren" oder "Assets installieren", in der Sprache des Adminbereichs.
Zur Sicherheit: Die Auswahl ist bewusst eine feste Liste, keine freie
Eingabe. Der Adminbereich schickt lediglich einen Schlüssel aus dieser Liste an
die API; der Server prüft ihn erneut gegen dieselbe Liste und führt nur dann
etwas aus. Argumente oder Optionen lassen sich nicht mitgeben, und es wird keine
Shell benutzt – der Befehl läuft über die Symfony-Console-Anwendung im
laufenden PHP-Prozess. Eine Befehlsinjektion ist damit ausgeschlossen, und der
Betrieb funktioniert auch dort, wo proc_open gesperrt ist. Die Route liegt im
API-Scope und ist nur für angemeldete Administratoren erreichbar.
Zur Kennzeichnung: Fünf Befehle sind mit ⚠ markiert und in der Auswahlliste
rot dargestellt. Sie greifen tiefer ein oder laufen lange – ein versehentlicher
Klick auf dal:refresh:index legt einen großen Shop für Minuten lahm. Die
übrigen vier sind unkritisch und jederzeit gefahrlos ausführbar.
cache:clear:all geht deutlich weiter als cache:clear: Es leert zusätzlich
alle Cache-Pools und den HTTP-Cache und entfernt alte System- und
Twig-Verzeichnisse. Auf einem gut besuchten Shop bedeutet das kurzzeitig deutlich
mehr Last, weil jede Seite neu aufgebaut wird. Der Befehl steht seit Shopware
6.6.8 zur Verfügung.
Die Einfärbung stammt aus dem Admin-JS des Plugins: Shopware bietet keine
Möglichkeit, Optionen einer Auswahlliste über die config.xml einzufärben.
Eingefärbt wird ausschließlich, was mit dem Warnzeichen des Plugins beginnt –
fremde Auswahllisten im Adminbereich bleiben unberührt. Verwendet wird dieselbe
Farbe wie für die lange Laufzeit der Fortschrittslinie.
Zur Laufzeit: dal:refresh:index, theme:compile und
media:generate-thumbnails können bei großen Shops mehrere Minuten dauern. Der
Browser wartet währenddessen auf die Antwort; je nach Servereinstellung kann die
Anfrage vorher abbrechen, obwohl der Befehl weiterläuft. Für den Alltag sind
cache:clear und assets:install die naheliegenden Kandidaten.
Die Leiste liest ihre Werte über die Admin-API. Nach dem Speichern übernimmt sie diese, sobald das Browserfenster wieder den Fokus bekommt – also etwa beim Wechsel in einen anderen Tab und zurück. Sofort erzwingen lässt sich das in der Browser-Konsole mit:
plugwareAdminBar.reload();
Zum vorübergehenden Ausblenden ohne Konfigurationsänderung:
plugwareAdminBar.remove();
Die Leiste besteht aus zwei Bereichen:
┌──────────────────────────────────────────────────────────────┐
│ [Icon] Beschriftung [Button] [Button] [Button] (i) │
└──────────────────────────────────────────────────────────────┘
em bemessen und wächst deshalb mit.Die Buttonflächen entstehen halbtransparent aus der Schriftfarbe, solange in der Karte "Buttons: Allgemein" keine eigenen Farben gesetzt sind. Dadurch passen sie sich automatisch an, ob die Leiste hell oder dunkel eingestellt ist.
Das Info-Icon sitzt fest am rechten Rand und lässt sich nicht abschalten, da es der einzige Weg zu dieser Dokumentation ist. Ein Klick öffnet sie Dokumentation direkt im Adminbereich, umschaltbar zwischen Deutsch und Englisch. Schließen per Klick daneben, über das Kreuz oder mit Escape.
Der Adminbereich wird über ein padding-top am <body> nach unten geschoben.
Hängt die Hauptnavigation fix am Viewport, wird sie zusätzlich nachgezogen.
Auf der Login-Maske erscheint die Leiste nicht – sie wird erst aufgebaut, wenn eine Anmeldung besteht, und wieder entfernt, sobald diese endet.
PlugwareAdminBar/
├── composer.json Metadaten, Version, Shopware-Anforderung
├── README.md diese Datei
├── README.en.md englische Fassung
├── build-readme-html.py erzeugt die HTML-Fassungen für den Info-Dialog
├── build-icons.py erzeugt den Icon-Katalog aus dem Meteor Icon Kit
├── build-version.py trägt die Version aus der composer.json überall ein
└── src/
├── PlugwareAdminBar.php Plugin-Klasse mit der update()-Migration
├── Controller/
│ └── CommandController.php führt die freigegebenen Konsolenbefehle aus
└── Resources/
├── config/
│ ├── config.xml alle Konfigurationsfelder, zweisprachig
│ ├── plugin.png Icon des Plugins in "Meine Erweiterungen"
│ ├── services.xml Service-Definition des Controllers
│ └── routes.xml Route der API-Aktion
├── views/
│ └── administration/
│ └── index.html.twig bindet das Admin-JS als Script-Tag ein
└── public/
└── administration/
├── js/
│ └── plugware-admin-bar.js erzeugt die Leiste
├── img/
│ └── plugin.png Icon in der Leiste
└── readme/
├── readme.de.html Inhalt des Info-Dialogs
└── readme.en.html
Die beiden HTML-Dateien im Ordner readme/ sind aus dieser README und der
englischen Fassung erzeugt. Sie liegen unter public/, weil nur dieser Ordner
von assets:install ausgeliefert wird – die Markdown-Dateien im Plugin-Wurzel-
verzeichnis sind über den Browser nicht erreichbar.
Ändert sich eine README, werden die HTML-Fassungen mit dem beiliegenden Skript neu erzeugt:
python3 build-readme-html.py
Das Skript entfernt dabei alle Links: Der Info-Dialog enthält bewusst keine klickbaren Inhalte, weil sie im Adminbereich entweder ins Leere führen oder ihn ungewollt verlassen würden. Der Text der Links bleibt erhalten.
Bis Shopware 6.6 hat der Adminbereich automatisch die Datei geladen, die unter
Resources/public/administration/js/ liegt und dem Bundle-Namen in Kebab-Case
entspricht. Seit 6.7 gilt das nicht mehr: der Admin-Build wurde von Webpack
auf Vite umgestellt. Shopware fragt jetzt über /api/_info/config ab, welche
Plugin-Dateien geladen werden sollen, und die Antwort stammt aus der von Vite
erzeugten Resources/public/administration/.vite/entrypoints.json.
Ohne Node/npm gibt es diese Datei nicht – ein handgeschriebenes JS in
administration/js/ wird deshalb schlicht nie eingebunden.
Der Ausweg ohne Build-Kette: das Admin-Template index.html.twig überschreiben
und das Skript selbst als <script>-Tag einhängen. Das Plugin nutzt dafür den
leeren Twig-Block administration_templates und setzt nonce="{{ cspNonce }}",
damit die Content-Security-Policy des Adminbereichs greift.
Der Pfad bundles/plugwareadminbar/... ergibt sich aus dem Bundle-Namen in
Kleinbuchstaben – dorthin kopiert assets:install den Ordner
src/Resources/public.
Shopware schreibt die Standardwerte aus der config.xml nur bei der
Installation in die system_config. Ändert sich später ein Standard, bliebe
in bestehenden Shops der alte Wert stehen.
Deshalb enthält die Plugin-Klasse eine update()-Methode, die einen
gespeicherten Wert anhebt – aber nur, wenn dort noch ein früherer Standard des
Plugins steht. Selbst gewählte Werte bleiben unangetastet. Abgedeckt sind
Hintergrundfarbe, Höhe und Schriftgröße; die jeweils überholten Werte stehen als
Konstanten am Anfang der Klasse und lassen sich dort erweitern.
Die Versionsnummer steht in der composer.json. Von dort trägt ein Skript sie
in das Twig-Template, das Admin-JS und beide READMEs ein:
python3 build-version.py
Das ist nötig, weil die Version an zwei Stellen technisch wirkt: als Cache-Parameter der Skript-URL und als Abgleich gegen eine im Browser zwischengespeicherte Fassung.
Der Icon-Katalog im Admin-JS wird aus dem offiziellen Paket erzeugt. Um ihn auf
einen neueren Stand zu bringen oder die Auswahl zu ändern, die Liste SELECTION
in build-icons.py anpassen und dann:
npm pack @shopware-ag/meteor-icon-kit
tar xzf shopware-ag-meteor-icon-kit-*.tgz
python3 build-icons.py package/icons/regular
Das Skript schreibt icons.generated.js; dessen Inhalt ersetzt den Block
BUTTON_ICONS in plugware-admin-bar.js. Die Optionen in der config.xml
müssen passend dazu gepflegt werden.
Das gesamte Erscheinungsbild entsteht in einem <style>-Block innerhalb von
plugware-admin-bar.js. Wer etwas grundlegend ändern möchte – etwa die
40-%-Begrenzung der Beschriftung oder den z-index – findet dort alle Regeln an
einer Stelle. Ein Build-Schritt ist nicht nötig, es genügen assets:install und
ein harter Reload.
| Symptom | Ursache und Lösung |
|---|---|
| Leiste erscheint gar nicht | Im Netzwerk-Tab prüfen, ob plugware-admin-bar.js geladen wird. Kein Request bedeutet, der Twig-Override greift nicht – cache:clear ausführen. Ein 404 bedeutet, assets:install fehlt |
| Leiste erscheint, bleibt aber leer | Die Beschriftung ist leer und es sind keine Buttons gepflegt. Das ist das erwartete Verhalten |
| Geänderte Einstellung wirkt nicht | Fenster kurz verlassen und zurückkehren oder plugwareAdminBar.reload() ausführen |
| Neue Standardwerte kommen nicht an | Es steht bereits ein eigener Wert in der Konfiguration. Feld leeren oder von Hand setzen |
| Konfiguration erscheint auf Englisch | Sollte ab 1.0.8 behoben sein. Falls nicht, cache:clear ausführen |
| Adminbereich bleibt weiß, Konsole meldet "service provider already instantiated" | Ein Skript greift zu früh auf Shopware.Service() zu. Ab 1.1.20 wartet das Plugin auf den fertigen Bootvorgang |
| Info-Dialog bleibt leer | Die Datei unter administration/readme/ wurde nicht ausgeliefert – assets:install ausführen |
| Befehl bricht mit Zeitüberschreitung ab | Der Befehl läuft zu lange für eine Webanfrage – über SSH ausführen |
| Befehl meldet "not allowed" | Der gewählte Schlüssel steht nicht in der Freigabeliste des Controllers |
| Buttons laufen über die Leistenbreite hinaus | Zu viele oder zu lange Buttons – Anzahl reduzieren oder Schriftgröße verringern |
| Etwas im Adminbereich verrutscht | Die CSS-Regeln im <style>-Block der JS-Datei nachjustieren |
Der Changelog nennt die inhaltlichen Schritte. Reine Anpassungen von Standardwerten – Farben, Größen, Vorbelegungen – sind nicht einzeln aufgeführt; die geltenden Werte stehen oben in den Konfigurationstabellen.
Shopware.Service() zu, bevor der
Adminbereich fertig hochgefahren war. Shopware brach den eigenen Bootvorgang
daraufhin ab und die Seite blieb weiß. Sämtliche Service-Zugriffe warten jetzt
auf den abgeschlossenen Startonerror-Attribut am Script-Tag entfernt; die Content-Security-Policy des
Adminbereichs blockiert Inline-Event-Handlercache:clear:all in die Freigabeliste aufgenommen und als kritisch
markiertPlugwareAdminBar. Betroffen sind Namespace,
Ordnername, Asset-Pfad, API-Route und die Konfigurationsschlüssel. Shopware
sieht das als neues Plugin: eine bestehende Vorgängerfassung muss deinstalliert
werden, gespeicherte Einstellungen werden nicht übernommenGrundfunktionen, entstanden unter einem früheren technischen Namen:
entrypoints.json lädt