README

Multi-Brand Lite

Hostname-driven brand layer for Shopware 6. One Shopware instance serves multiple brand domains; each request resolves to a brandKey in Twig and a set of --brand-* CSS custom properties in the page head.

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

🇬🇧 English · 🇳🇱 Nederlands · 🇩🇪 Deutsch

Lite tier — and what's coming in Pro

Multi-Brand Lite (this package, tenbruggencate/multibrand-lite) is the free tier of the Multi-Brand family. It handles the foundation: hostname-based brand resolution, per-brand theme variables (CSS custom properties), Twig helpers, and per-sales-channel config. If you just need "serve brand A from brand-a.tld and brand B from brand-b.tld with their own colours, fonts and logo", Lite is the whole answer.

Multi-Brand Pro (coming as tenbruggencate/multibrand-pro) will layer on the per-brand content + commerce surfaces that the Lite tier deliberately leaves out:

Per-brand CMS pages — distinct landing pages, About, FAQ etc. per brand without forking the sales channel
Per-brand email templates — order confirmations, shipping notifications, password resets all branded per host
Per-brand checkout & shipping rules — different payment methods, shipping costs or thresholds per brand
Brand-specific analytics — segment Matomo / Plausible dashboards per brand for clean per-brand reporting
Brand A/B testing — run experiments scoped to one brand without polluting the others

Pro is on the roadmap, not yet released. Lite alone is production-ready for the "shared catalogue, separate visual identity" use case and stays free.

Screenshots

_{Storefront homepage — desktop, multibrand resolved per host}

_{Storefront homepage — mobile (responsive)}

What it does

Serving two or three brand domains from a single Shopware install normally forces you to either (a) fork templates per brand or (b) duplicate the whole store as separate sales channels. Both paths are expensive to maintain. This plugin takes the middle path:

One host → one brandKey — configure which hostnames resolve to which brand in the admin
Per-brand CSS tokens — amethyst vs forest vs whatever you want, emitted as var(--brand-primary) etc. so the same SCSS compiles once and renders differently per host
Twig helper — {{ brand() }} returns the current brand object; templates stay simple

No per-brand plugins, no duplicate theme compilation, no forked templates. Just a thin resolution layer and a token system.

Install

Multi-Brand Lite is free and distributable via Composer / Packagist or via the Shopware Store.

composer require tenbruggencate/multibrand-lite
bin/console plugin:refresh
bin/console plugin:install --activate TenBruggencateMultiBrand
bin/console cache:clear

The plugin class name stays TenBruggencateMultiBrand (grandfathered from v1.x — only the composer package name changed in v2.0.0). If you're upgrading from v1.x see the v2.0.0 changelog entry for the one-line composer manifest update.

Configuration

Configurable per sales channel from Settings → System → Plugins → Multi-Brand Layer.

Field	Purpose
`brands`	JSON-editable list of `{ key, label, hosts[], tokens{} }` entries
`defaultBrand`	Fallback `brandKey` when no host matches (e.g. on admin preview URLs)
`tokenPrefix`	CSS custom-property prefix (default `--brand-`)

Tokens in each brand entry are free-form — ship whatever your theme reads. Common examples: primary, secondary, surface, text-strong, accent-1, accent-2.

Usage

In any Twig template:

{% set brand = brand() %}
<body data-brand="{{ brand.key }}">
  <h1>Welcome to {{ brand.label }}</h1>
</body>

meta.html.twig automatically emits the <style> block with --brand-* tokens; your SCSS reads them with graceful fallbacks:

.button--primary {
  background: var(--brand-primary, #7C5BA5); // amethyst fallback
}

Standards

Performance — resolution happens once per request, cached per host. Token block adds ~400 bytes to <head>; no runtime JS.
SEO — no impact on URL structure, canonicals, or sitemaps. Each brand's sales channel retains its own SEO settings.
WCAG — CSS custom properties are a progressive enhancement; colour-contrast guarantees must be satisfied per-brand by the theme consuming the tokens (this plugin doesn't enforce them). Axe audit on a storefront page with the resolver active (0 violations on the plugin's own injection; theme-owned violations out of scope): docs/ACCESSIBILITY.md.
GDPR — stateless. No cookies, no tracking, no data stored per visitor. Full data-flow + subject-rights documentation in GDPR.md.
Security — host resolution uses Request::getHost() (trusted-proxy aware); no user-controllable input touches the brand lookup.
Uninstall — plugin:uninstall --keep-user-data preserves all brand config; plugin:uninstall without the flag drops every TenBruggencateMultiBrand.config.* row 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.

[ ] Configure trusted_proxies if you sit behind a CDN / load balancer. Request::getHost() reads the Host header (or X-Forwarded-Host when proxies are trusted). Without trusted proxies set, the wrong hostname can resolve and visitors see the default brand instead of yours.
[ ] Set defaultBrand to a valid existing brand key. This is the fallback for admin preview URLs and unmatched hostnames; pointing it at a non-existent key means the storefront renders with empty tokens and a broken data-brand attribute.
[ ] Test each brand domain on staging. Hit curl -I https://brand-a.staging.tld/ and grep the response for data-brand="brand-a" and the brand-specific --brand-primary token; if either is missing, host resolution isn't matching.
[ ] Don't try to use hreflang between brand hostnames — see the GEO note below for why. If your "brands" are actually locale-variants, use Shopware's SalesChannelDomain per-language config instead and uninstall this plugin.
[ ] Theme contrast is per-brand, not per-plugin. This plugin injects tokens; your theme has to satisfy WCAG colour-contrast for every brand combination. Run an axe-core audit on each brand domain before launch.

Compatibility

Core platform

Shopware	PHP	Status
6.7.x — tested against 6.7.8, 6.7.9	8.1, 8.2	Stable
6.6.x	—	Not supported
6.5.x and earlier	—	Not supported

Database

Engine	Version	Notes
MySQL	8.0+	Primary target; JSON functions used for config-row manipulation in migrations
MariaDB	10.11+	Tested end-to-end; earlier versions lack some JSON operator support

Browsers (storefront)

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

Browser	Desktop	Mobile
Chrome / Chromium	✅	✅
Firefox	✅	✅
Safari	✅ (macOS)	✅ (iOS 16+)
Edge	✅	—

Internet Explorer and legacy Edge are not supported. The plugin emits no runtime JS, 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

Tool	Version	Scope
PHP	≥ 8.1	Runtime + test suite
Composer	2.x	Dependency management
Node.js	≥ 18	Only needed if you edit SCSS and re-run the theme compile

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
Live-DB smoke tests (plugin install → activate → brand resolves per host → uninstall cycle) against Shopware 6.7.8

Uninstall note

If you also install a theme plugin or another plugin that declares a composer dependency on tenbruggencate/multibrand-lite (or, for legacy installs, the pre-v2.0.0 name tenbruggencate/multibrand), Shopware's plugin manager will refuse to uninstall MultiBrand while that dependant is still active — you'll see PluginHasActiveDependantsException. This is correct Shopware behaviour, not a MultiBrand bug: uninstalling MultiBrand first would break the dependant plugin at runtime.

To uninstall MultiBrand cleanly:

Uninstall the dependant plugin(s) first, or remove the require entry from their composer.json and re-run composer update.
Then bin/console plugin:uninstall TenBruggencateMultiBrand.

For vanilla MultiBrand installs (no composer-dependant plugin on top), uninstall runs unblocked: the plugin drops all TenBruggencateMultiBrand.config.* rows from system_config and removes itself.

GEO / multi-region note — why there is no `hreflang`

This plugin deliberately does NOT emit hreflang alternate links between the configured brand hostnames. That is correct, not an oversight:

hreflang is the signal for "the same canonical content is served in multiple languages or regions" — e.g. example.com/product (en) vs. example.de/product (de) for the same product.
The domains MultiBrand is designed for are separate brands with their own catalogues, copy, and identity, not locale-variants of the same storefront. They just share a single Shopware instance for operational reasons.
Cross-linking them via hreflang would tell Google "these are equivalent pages, pick one" — which is the opposite of what multi-brand storefronts want.

If your brands really ARE locale-variants (e.g. you have shop.nl / shop.de / shop.fr serving the same products in different languages), Shopware's native SalesChannelDomain per-language config is the right tool — leave this plugin out of that use case.

Related plugins

Free Packagist-distributed siblings from the same publisher:

TenBruggencateAnalytics — multi-backend analytics (Matomo + Plausible) with optional per-brand custom dimensions
TenBruggencateNewsletterLite — GDPR-safe newsletter signup with double opt-in; stores the resolved brand with each subscriber
TenBruggencateMaintenance — branded maintenance page with HTTP 503 + Retry-After
TenBruggencateLegalPages — drop-in legal templates (privacy / terms / shipping / returns / disclaimer) with merge fields

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

tenbruggencate / multibrand-lite

Maintainers

Package info

Statistics

Security

README

Multi-Brand Lite

Lite tier — and what's coming in Pro

Screenshots

What it does

Install

Configuration

Usage

Standards

Production-readiness checklist

Compatibility

Core platform

Database

Browsers (storefront)

Admin browsers

Development

Accessibility

What we test before each release

Uninstall note

GEO / multi-region note — why there is no `hreflang`

Related plugins

Support

License

More from Ten Bruggencate Development

tenbruggencate / multibrand-lite

Maintainers

Package info

Statistics

Security

README

Multi-Brand Lite

Lite tier — and what's coming in Pro

Screenshots

What it does

Install

Configuration

Usage

Standards

Production-readiness checklist

Compatibility

Core platform

Database

Browsers (storefront)

Admin browsers

Development

Accessibility

What we test before each release

Uninstall note

GEO / multi-region note — why there is no hreflang

Related plugins

Support

License

More from Ten Bruggencate Development

GEO / multi-region note — why there is no `hreflang`