README

TenBruggencateMaintenance

Configurable branded maintenance page for Shopware 6. Admin-editable heading, lead, launch-window badge, auto-reload, SEO meta. Works standalone — no dependency on any theme.

License: MIT · Shopware: 6.7.x · PHP: 8.1 / 8.2

🇬🇧 English · 🇳🇱 Nederlands · 🇩🇪 Deutsch

📖 More context: Why we built this · How it compares

Screenshots

Maintenance page — desktop

Maintenance page — mobile (responsive)

What it does

Shopware's default maintenance page is generic and unbranded. Rolling your own in the theme plugin couples "the store is down" copy to "the store theme", which is exactly when you can't rely on the theme. This plugin ships its own page that:

• Survives theme failures — renders independently; if your theme has a SCSS compile error, maintenance still renders correctly
• Admin-editable copy — heading, lead, icon emoji, launch-window badge, social CTA, SEO meta, all per sales channel
• Returns HTTP 503 Service Unavailable + Retry-After (v1.3+) — Google's documented correct behaviour for planned downtime, paired with default noindex, follow so multi-day maintenance windows don't poison your SERP rankings or stick "we'll be back" snippets in the index
• Dynamic Retry-After from a configurable expectedBackAt datetime (v1.4+) — admins set the moment the shop will be back; crawlers, CDNs, and uptime monitors get an accurate hint instead of guessing. Per sales channel, clamped to [60s, 24h]
• Auto-reload — optional interval so visitors don't have to refresh manually when the window ends
• Snippet fallbacks — nl-NL / en-GB / de-DE built in; if the admin leaves a field blank, the snippet provides a sensible default

Install

composer require tenbruggencate/maintenance
bin/console plugin:refresh
bin/console plugin:install --activate TenBruggencateMaintenance
bin/console cache:clear

Configuration

Editable per sales channel from Settings → System → Plugins → Maintenance Page.

Standards

• Performance — no runtime JS, no external font fetch, no image dependencies. The page is ~3 KB + inline SCSS.
• SEO — emits <meta name="robots" content="noindex"> so search engines don't index the maintenance copy. metaTitle / metaDescription remain admin-editable for social previews (the page is often shared on Twitter/Instagram during launch windows).
• GDPR — stateless. No cookies, no tracking, no data stored per visitor. Analytics (TenBruggencateAnalytics) and tracker scripts are disabled on this page by design. Full data-flow documentation in GDPR.md.
• WCAG 2.2 AA — semantic headings (h1 / h2), visible focus states on the social CTA, colour contrast validated against the shipped palette. Screen readers announce the launch-window badge as regular text. Live axe-core audit is on-demand because it requires enabling maintenance mode on the whole stack: see docs/ACCESSIBILITY.md for the reproducer.
• Security — all fields are escaped via Twig; HTML is not allowed in any admin field, preventing XSS via a compromised admin account.
• Uninstall — plugin:uninstall --keep-user-data preserves every per-SC maintenance copy config; plugin:uninstall without the flag drops all TenBruggencateMaintenance.config.* rows so the destructive path leaves no trace. No owned tables.

Production-readiness checklist

A deliberately short list of things to verify before enabling the plugin on a customer-facing storefront. Not legal cover — the MIT license already disclaims warranty — but practical guidance an experienced operator would want anyway.

• [ ] Test on staging before flipping the kill-switch on prod. Especially the enabled=false fallthrough path (which renders Shopware's default maintenance page) — that branch only activates if a typo in your config breaks the override, and you do not want the first time you see Shopware's default page to be when your overridden one has crashed.
• [ ] Set expectedBackAt per sales channel before each maintenance window. Without it, Retry-After defaults to 1 hour. With it, crawlers and uptime monitors get a precise hint and re-check the moment you're back instead of waiting out a stale default.
• [ ] Confirm the metaTitle / metaDescription fields are filled for any sales channel where the maintenance URL might be shared on social during a launch window — these populate the Open Graph / Twitter card preview, which is otherwise blank.
• [ ] Update your uptime-monitoring expectations. v1.3+ returns HTTP 503 (was 200 before). Your monitor must treat 503 during planned maintenance as expected; otherwise you'll page yourself.
• [ ] enabled=false is a kill-switch, not a debugger — toggling it off in prod silently swaps to Shopware's default maintenance page. If something looks off in your branded copy, fix the copy; turning the plugin off won't tell you what was wrong.

Compatibility

Core platform

Database

Browsers (storefront)

Evergreen browsers only — the two most recent stable releases of each:

Internet Explorer and legacy Edge are not supported. The plugin emits no runtime JS (where applicable) so graceful degradation on older browsers usually still renders content, just without progressive enhancements.

Admin browsers

Same evergreen matrix — the Shopware admin is Vue-based and has its own compatibility baseline that this plugin doesn't extend or narrow.

Development

Accessibility

WCAG 2.2 level A + AA — see docs/ACCESSIBILITY.md for axe-core audit output and per-page violations.

What we test before each release

• Full PHPUnit unit suite against PHP 8.1 + 8.2 (source-inspection tests don't need a kernel)
• PHPStan level 8 + PHP-CS-Fixer (@PSR12 + @Symfony)
• Composer validate on every plugin
• Live-DB smoke tests (plugin install → activate → route render → uninstall cycle)
• axe-core audit on the primary storefront surfaces (see ACCESSIBILITY.md)

Related plugins

Part of the TenBruggencate Suite — small, focused plugins that play well together:

• MultiBrand — hostname-based brand resolver + per-brand --brand-* CSS tokens. When active, the maintenance page picks up per-host brand styling automatically.
• LegalPages — Dutch / German / English legal page templates. Legal footer links render in the maintenance footer so visitors can still reach imprint / privacy during downtime.
• Analytics — multi-backend analytics (Matomo / Plausible). Cookieless by default, GDPR-first.
• NewsletterLite — lightweight GDPR-safe newsletter signup with opaque-token unsubscribe.

Support

• Email: guy@tenbruggencatedevelopment.nl
• Docs & news: tenbruggencatedevelopment.nl
• Source / issues: Bitbucket repo
• Security vulnerabilities: see SECURITY.md — email first, no public issues, 72-hour acknowledgement SLA

License

MIT © Ten Bruggencate Development