Plugware Developer Admin Tool Bar

Shopware 6.7 plugin that adds a custom full-width bar to the top of the administration – with a freely chosen caption and up to nine buttons.

• Technical name: PlugwareAdminBar
• Version: 1.1.25
• Compatibility: Shopware 6.7 (shopware/core: ~6.7.0)
• License: MIT
• Build: no Node/npm required – the admin JavaScript is hand-written and shipped as is

What the plugin is for

The Shopware administration offers no space for your own permanently visible notices or shortcuts. This plugin fills that gap: it puts a slim bar across the full width at the top, visible on every page of the administration.

Typical uses:

• Telling systems apart – a strikingly coloured bar reading "Staging" keeps people from accidentally working in the live shop
• Maintenance commands – clear the cache or install assets with one click instead of connecting to the server over SSH
• Keeping an eye on running work – spinner, dots and the progress line show that a command is still busy, and switch colour on a long runtime

The bar is deliberately plain: no admin module of its own, no extra database table, no dependencies. Everything runs through the plugin configuration.

Requirements

• Shopware 6.7
• SSH or CLI access for the console commands
• No Node.js or npm – see the "Technical background" section

Installation

Extract the plugin directory to custom/plugins/PlugwareAdminBar, or upload the ZIP in the administration under Extensions → My extensions. Then:

bin/console plugin:refresh
bin/console plugin:install --activate PlugwareAdminBar
bin/console assets:install
bin/console cache:clear

Afterwards reload the administration once with a hard refresh (Ctrl+F5) so the JavaScript is fetched.

Update

bin/console plugin:refresh
bin/console plugin:update PlugwareAdminBar
bin/console assets:install
bin/console cache:clear

assets:install is needed on every update in which the JavaScript file changed – otherwise the old state stays in the public/ directory.

Administration white after an update? Almost always the browser still holds parts of the old admin bundle in its cache while newer files sit on the server. A hard reload (Ctrl+F5, Cmd+Shift+R on macOS) fixes it. If that does not help, a cache:clear on the server is usually missing.

When the administration no longer starts at all

If the page stays white and the browser console reports service provider already instantiated followed by an error in startBootProcess, the plugin can no longer be reached through the interface. The way out via the console:

bin/console plugin:deactivate PlugwareAdminBar
bin/console cache:clear

The administration is reachable again afterwards. This doubles as the test of whether the plugin is the cause at all: if the page stays white with it deactivated, the problem lies elsewhere.

Then install the current version – it matters that the directory under custom/plugins/ has actually been replaced before plugin:update runs:

bin/console plugin:refresh
bin/console plugin:update PlugwareAdminBar
bin/console plugin:activate PlugwareAdminBar
bin/console assets:install
bin/console cache:clear

To verify the new version took effect, check the administration's page source: the plugware-admin-bar.js entry must carry the current version number in its ?v= parameter.

What was behind it: up to 1.1.19 the admin JavaScript called Shopware.Service('loginService') twice a second as soon as that function existed at all – that is, in the middle of Shopware's own boot process. Such an access instantiates the service provider prematurely; Shopware then loses its reference and aborts the start. A try/catch wrapper did not help, because the error occurred in the core rather than in the plugin – the plugin merely triggered it. As of 1.1.20, isBooted() checks before every service access that #app is populated and that Shopware.Application.getApplicationRoot() returns a root.

As a side effect the bar builds up slightly later, since it waits for the start to finish.

Guarding against a white administration

The plugin brings two automatic measures for this:

• On the server it clears the caches itself after every update and on every activation. A forgotten cache:clear is therefore ruled out as a cause.
• In the browser the script compares its own version on startup with the one the Twig template delivers fresh. If they differ, the script came from the cache – the page is then reloaded exactly once. A marker in the session prevents a loop should a proxy stubbornly keep serving the old file; a console note appears instead in that case.

Beyond that it is built so that it cannot cause this state:

• The script is included with defer and a version parameter, so after an update the browser is forced to fetch the new file.
• It sits behind the app container and therefore does not block the administration from starting.
• Every entry point is wrapped. An error in the plugin ends up on the browser console and has no effect on the administration.
• If the browser lacks the prerequisites or assets:install was forgotten, no bar appears – with no consequences for anything else.

Uninstallation

bin/console plugin:deactivate PlugwareAdminBar
bin/console plugin:uninstall PlugwareAdminBar
bin/console cache:clear

The plugin creates no tables of its own. On uninstall, Shopware removes the configuration values from system_config.

Configuration

Settings → System → Plugins → Plugware Developer Admin Tool Bar → Configuration

The configuration is split into twelve cards: three for the bar itself and one per button.

Card "General"

Card "Appearance"

Card "Buttons: general"

The six color fields come prefilled. The values match exactly what the earlier automatic derivation produced on the default bar: semi-transparent white over #243758, resolved into a fixed color.

Clear a field and it returns to that automatic behaviour, deriving the color from the bar's text color again. That is useful when you run a different background color for the bar – otherwise the buttons will not follow along.

The hover change is animated over 0.15 seconds and is skipped when "reduce motion" is enabled in the operating system.

Cards "Button 1" to "Button 9"

A button only appears when a console command is selected. Its label comes from the command, the icon is optional.

After installation, all nine buttons are already assigned – the harmless ones first, the four marked ones behind them:

The bar is therefore usable right away. For fewer buttons, set individual cards to "No command" – the button then disappears from the bar.

Console commands

Every button triggers a maintenance command. Nine commands are available:

While the command runs, four things show it:

• The button's icon gives way to a rotating spinner.
• Three dots pulse in turn behind the name.
• The button's border takes on the signal colour and the button is disabled.
• A progress line sweeps along the bottom edge of the bar. It stays visible until every started command has finished – even when a result dialog is covering the button. Its height is configurable; 0 removes it entirely.
• If a command drags on, the progress line changes colour after a configurable time – to red after 30 seconds by default. That makes it obvious at a glance whether something is running normally or taking unusually long. The timing is measured from the first command still running.

The colour of these signals is set in the "Buttons: general" card; empty means the button's text colour is used. With "reduce motion" enabled in the operating system the animations are dropped, while the colour remains as a hint.

Afterwards a dialog shows the command's output and whether it succeeded.

The button carries the command's name – "Clear cache" or "Install assets", for instance, in the administration's language.

On security: the selection is deliberately a fixed list, not a free text field. The administration only sends a key from that list to the API; the server checks it against the same list again and runs something only then. Arguments or options cannot be passed, and no shell is involved – the command runs through the Symfony console application inside the running PHP process. Command injection is therefore impossible, and it also works where proc_open is disabled. The route sits in the API scope and is reachable only for logged-in administrators.

On marking: five commands carry a ⚠ and appear in red in the select list. They reach deeper or run long – an accidental click on dal:refresh:index can tie up a large shop for minutes. The other four are harmless and safe to run at any time.

cache:clear:all goes considerably further than cache:clear: it also empties every cache pool and the HTTP cache and removes old system and Twig directories. On a busy shop that means a noticeable load spike, since every page has to be rebuilt. The command has been available since Shopware 6.6.8.

The colouring comes from the plugin's admin JavaScript: Shopware offers no way to colour options of a select list through config.xml. Only entries starting with the plugin's own warning sign are coloured, so other select lists in the administration stay untouched. It uses the same colour as the long-runtime state of the progress line.

On runtime: dal:refresh:index, theme:compile and media:generate-thumbnails can take several minutes on large shops. The browser waits for the response meanwhile; depending on server settings the request may time out even though the command keeps running. For everyday use, cache:clear and assets:install are the obvious candidates.

When changes take effect

The bar reads its values through the admin API. After saving, it picks them up as soon as the browser window regains focus – for instance when you switch to another tab and back. To force it immediately, run this in the browser console:

plugwareAdminBar.reload();

To hide it temporarily without changing the configuration:

plugwareAdminBar.remove();

How the bar is built

The bar consists of two areas:

┌──────────────────────────────────────────────────────────────┐
│ [Icon] Caption        [Button] [Button] [Button]           (i) │
└──────────────────────────────────────────────────────────────┘

• The plugin icon sits at the far left. It is 32 pixels by default, leaving some breathing room above and below at the bar's default height of 48 pixels.
• The caption follows to its right and can be switched off without deleting the text – handy for toggling between a slim icon bar and the labelled version. the area is positioned absolutely at the left edge and capped at 40% of the bar width. Longer text is truncated with an ellipsis. The absolute positioning has a reason: it keeps the buttons exactly centered no matter how long the text is.
• The buttons follow the "Alignment" setting and show the name of their command, optionally with an icon in front.
• The font size of the buttons is configurable independently of the caption. The icon is measured in em and scales along with it.
• The horizontal padding is configurable and, together with the font size, determines how wide a button turns out.
• A button's width follows its content. Longer names are no longer truncated, and a button without text becomes square. The height stays the same for all of them: bar height minus 12 pixels.

• The button surfaces are built semi-transparently from the text color as long as no colors of your own are set in the "Buttons: general" card, so they adapt automatically to a light or dark bar.

• The info icon sits at the right edge and cannot be switched off, as it is the only way to reach this documentation. A click opens this documentation right inside the administration, switchable between German and English. Close it by clicking outside, via the cross, or with Escape.

The administration is pushed down via padding-top on <body>. If the main navigation is fixed to the viewport, it is moved along as well.

The bar does not appear on the login screen – it is only built once a session exists, and is removed again as soon as that session ends.

Structure

PlugwareAdminBar/
├── composer.json                 metadata, version, Shopware requirement
├── README.md                     German version
├── README.en.md                  this file
├── build-readme-html.py          generates the HTML versions for the info dialog
├── build-icons.py                generates the icon catalogue from the Meteor Icon Kit
├── build-version.py              writes the composer.json version into every file
└── src/
    ├── PlugwareAdminBar.php    plugin class with the update() migration
    ├── Controller/
    │   └── CommandController.php runs the allow-listed console commands
    └── Resources/
        ├── config/
        │   ├── config.xml        all configuration fields, bilingual
        │   ├── plugin.png        icon of the plugin in "My extensions"
        │   ├── services.xml      service definition of the controller
        │   └── routes.xml        route of the API action
        ├── views/
        │   └── administration/
        │       └── index.html.twig   includes the admin JS as a script tag
        └── public/
            └── administration/
                ├── js/
                │   └── plugware-admin-bar.js   builds the bar
                ├── img/
                │   └── plugin.png              icon shown in the bar
                └── readme/
                    ├── readme.de.html              content of the info dialog
                    └── readme.en.html

The two HTML files in the readme/ folder are generated from this README and the German one. They live under public/ because only that folder is shipped by assets:install – the Markdown files in the plugin root are not reachable from the browser.

Whenever a README changes, regenerate the HTML versions with the bundled script:

python3 build-readme-html.py

The script strips all links: the info dialog deliberately contains no clickable content, since links would either lead nowhere inside the administration or leave it unintentionally. The link text is kept.

Technical background

Up to Shopware 6.6 the administration automatically loaded the file placed in Resources/public/administration/js/ whose name matched the bundle name in kebab case. That no longer holds since 6.7: the admin build moved from Webpack to Vite. Shopware now asks /api/_info/config which plugin files to load, and that answer is derived from the entrypoints.json generated by Vite in Resources/public/administration/.vite/.

Without Node/npm that file does not exist, so hand-written JavaScript in administration/js/ is simply never included.

The way around it without a build chain: override the admin template index.html.twig and add the script tag yourself. The plugin uses the empty Twig block administration_templates for this and sets nonce="{{ cspNonce }}" so the administration's content security policy applies.

The path bundles/plugwareadminbar/... follows from the lowercased bundle name – that is where assets:install copies src/Resources/public.

Default values on updates

Shopware writes the defaults from config.xml into system_config only on installation. If a default changes later, existing shops would keep the old value.

The plugin class therefore contains an update() method that lifts a stored value – but only if a previous default of this plugin is still in there. Values you picked yourself are left alone. Background color, height and font size are covered; the outdated values are constants at the top of the class and can be extended there.

Maintaining the version

The version number lives in composer.json. From there a script writes it into the Twig template, the admin JavaScript and both READMEs:

python3 build-version.py

This matters because the version has two technical effects: it is the cache parameter of the script URL and the value checked against a copy cached in the browser.

Updating the icons

The icon catalogue in the admin JavaScript is generated from the official package. To move it to a newer version or change the selection, adjust the SELECTION list in build-icons.py and run:

npm pack @shopware-ag/meteor-icon-kit
tar xzf shopware-ag-meteor-icon-kit-*.tgz
python3 build-icons.py package/icons/regular

The script writes icons.generated.js; its content replaces the BUTTON_ICONS block in plugware-admin-bar.js. The options in config.xml have to be kept in sync manually.

Customising

The entire appearance is produced by a <style> block inside plugware-admin-bar.js. If you want to change something fundamental – the 40% cap on the caption, say, or the z-index – every rule sits there in one place. No build step is needed; assets:install and a hard reload are enough.

Troubleshooting

Changelog

1.1.25

• The spacing between icon and label is fixed at 6 pixels again; the setting from 1.1.24 is gone

1.1.24

• Spacing between the icon and the label inside a button is configurable, default 6 pixels

1.1.23

• Horizontal padding of the buttons is configurable, default 12 pixels

1.1.22

• The info icon is a fixed part of the bar; the "Show info icon" setting is gone

The changelog lists the substantive steps. Plain adjustments of default values – colours, sizes, presets – are not listed individually; the values in force are in the configuration tables above.

1.1.21

• The incident from 1.1.20 is documented: cause, the way out via the console and how to verify the new version took effect

1.1.20

• Fixed: the admin JavaScript accessed Shopware.Service() before the administration had finished booting. Shopware aborted its own boot process and the page stayed white. Every service access now waits for the start to complete
• Removed the onerror attribute from the script tag; the administration's content security policy blocks inline event handlers

1.1.19

• Documentation cleaned up: wording from the era of link buttons removed, changelog condensed to the substantive steps

1.1.9

• Font size of the buttons configurable separately from the caption; the icons scale with it

1.1.8

• Added cache:clear:all to the allow list and marked it as critical

1.1.4

• The icon select list in the configuration shows each symbol in front of its name

1.1.3

• All buttons ship with a console command and an icon assigned

1.1.2

• Caption can be shown or hidden with a switch, without losing the text

1.1.0

• Technical rename to PlugwareAdminBar, affecting the namespace, folder name, asset path, API route and configuration keys. Shopware treats this as a new plugin: an existing predecessor has to be uninstalled and stored settings are not carried over

1.0.0

Core functionality, built under an earlier technical name:

• Full-width bar at the top of the administration, with plugin icon, caption and buttons
• Nine buttons triggering allow-listed console commands: fixed allow list, no arguments, no shell, executed through an API route in the admin scope
• Visible running state: spinner, pulsing dots, coloured border and a progress line that changes colour on a long runtime
• Critical commands marked with ⚠ and coloured in the select lists
• Icons from Shopware's Meteor Icon Kit, shipped as inline SVG
• Info dialog with the documentation, switchable between German and English
• The admin JavaScript is included via a Twig override, since Shopware 6.7 only loads assets from entrypoints.json after the move to Vite
• Caches are cleared automatically after every update and activation; an outdated script copy in the browser is detected and reloaded once
• Configuration fully bilingual, German and English