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.2+

🇬🇧 English · 🇳🇱 Nederlands · 🇩🇪 Deutsch

Lite tier — and what Pro adds

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 a five-slot brand config screen. If you just need "serve brand A from brand-a.tld and brand B from brand-b.tld with their own colours, favicons and structured-data logo", Lite is the whole answer. Fonts and the storefront header logo come from your theme: Lite gives it the brand key (data-brand) and colour tokens to switch on.

Multi-Brand Pro (tenbruggencate/multibrand-pro) is released and installs side by side with Lite — it requires Lite and extends it rather than replacing it. Pro is not published on Packagist: it is delivered directly today, and a Shopware Store listing is in preparation. What it adds:

Per brand its own subject, sender name, HTML body and plain-text body for every transactional email type
Applied automatically at send time on every path (Flow Builder or direct); the brand is derived from the sales channel's domain
Override only what you want: empty fields fall back to the Shopware default; a toggle to pre-stage overrides before arming them
Fail-safe: on any error the email goes out unchanged and the error is logged; Shopware's mail templates are never touched
Managed under Settings → Multi-Brand Pro with list and form, including hints for brand keys and template types; EN/NL/DE
Export all data button: JSON with overrides and configuration, also via API; keep or remove data on uninstall

→ What's in Multi-Brand Pro

Lite alone is production-ready for the "shared catalogue, separate visual identity" use case and stays free.

Screenshots

_{Brand A — host localhost, green tokens}	_{Brand B — host 127.0.0.1, same shop, red tokens — buttons, links and the header line use var(--brand-primary) through a theme rule like the SCSS example below}
_{Admin configuration — global settings, one card per brand slot}

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 (substring match, not case-sensitive)
Per-brand CSS tokens — matcha green for one brand, Darjeeling amber for the other, or whatever you want, emitted as var(--brand-primary) etc. so the same SCSS compiles once and renders differently per host
Twig helpers — brand_key(), brand_config(field), is_brand(key) and brand_css_properties(); they also work in mail templates (the mail's sales channel decides the brand)

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

Configured from Settings → System → Plugins → Multi-Brand Lite → Config. Brand definitions are read from the global config namespace and are deliberately not overridable per sales channel — a brand is hostname-derived, so two sales channels on the same host share one brand by definition (see the design-decision note in BrandResolver). Since v2.3.0 the getting-started card says so on the screen itself; values saved against a specific sales channel are ignored at render time. The screen has a getting-started card, one card per brand slot — Brand 1 (default) through Brand 5 — and a JSON backup/restore card. Each slot N (1–5) holds:

Field	Purpose
`brandNKey`	Machine key for the brand, e.g. `north` — returned by `brand_key()` and rendered as `data-brand`
`brandNHostnamePattern`	Hostname fragment that resolves to this brand (substring match, not case-sensitive, first match wins; saved in lowercase)
`brandNName`, `brandNEmail`	Display name and contact address for templates and the Organization / WebSite JSON-LD. Left empty, they are omitted from the JSON-LD (no placeholder)
`brandNLogoPath`, `brandNFaviconBasePath`	Logo (used in the structured data) and favicon folder. Must start with `/` (site root, e.g. `/media/acme/logo.png`) or `https://`; anything else is ignored and logged
`brandNLegalName`	Registered company name, emitted as schema.org `legalName` when it differs from the display name
`brandNStreetAddress`, `brandNPostalCode`, `brandNCity`, `brandNCountry`	The `PostalAddress` block. `brandNCountry` must be an ISO 3166-1 alpha-2 code (two letters, normalised to upper case); anything else is dropped with a log warning
`brandNTelephone`, `brandNVatId`	schema.org `telephone` and `vatID`
`brandNSameAs`	Textarea, one absolute http(s) URL per line — the brand's own social profiles and its Wikidata / Wikipedia entry. Lines that are not http(s) URLs are skipped, the rest are kept
`brandNPrimary`, `brandNSecondary`, `brandNSurface`, `brandNAccent1`–`3`, `brandNTextStrong`, `brandNTextSoft`	The eight colour tokens, emitted as `--brand-*` CSS custom properties

The eight organisation fields (brandNLegalName through brandNSameAs) are optional and feed the per-brand Organization JSON-LD in meta.html.twig. Every one of them is omitted from the emitted data when empty, so a shop that never fills them in gets the basic organisation data — plus the logo, emitted as an ImageObject. Logo fallback rule: the brand's own brandNLogoPath wins whenever it is set (a /… path is made absolute against the request's scheme + host, an https:// URL is passed through untouched); the shared theme logo (theme_config('sw-logo-desktop')) is only used when the resolved brand has no logo path. On a multi-brand shop the theme logo is the same image for every brand, which is exactly the problem this rule solves.

Colour values must be 6-digit hex; anything else is replaced by a neutral default instead of being emitted into the page. Brand 1 is the fallback — when no hostname pattern matches (admin preview URLs, direct IP access), brand 1 renders and a warning is logged once per host (not on a single-brand shop without patterns). Overlapping patterns between slots are logged.

Usage

In any Twig template:

<body data-brand="{{ brand_key() }}">
  <h1>Welcome to {{ brand_config('name') }}</h1>
  {% if is_brand('north') %}<p>Only on the north brand.</p>{% endif %}
</body>

brand_config() reads one field of the resolved brand: key, name, email, primary, secondary, surface, accent1–accent3, textStrong, textSoft, logoPath, faviconBasePath, legalName, streetAddress, postalCode, city, country, telephone, vatId and sameAs (a list of validated URLs, every other field a string). brand_css_properties() returns the colour tokens as a --brand-* map; the routing config (hostnamePattern) is deliberately not exposed to templates.

Mails, CLI and workers

The Twig functions also run in mail templates, which are rendered outside a storefront request (from the admin, a message worker or the CLI). There the brand comes from the mail's sales channel: Shopware passes salesChannel / salesChannelId to every mail template, and the plugin matches that sales channel's domain URLs against the hostname patterns. On a storefront request for the same sales channel the visitor's host still wins. Without a request and without a sales channel the plugin falls back (request host or brand 1) and logs one warning per process, so a wrong brand is never silent.

For developers: the public API

TenBruggencateMultiBrand\Service\BrandResolver is a public service. Inject it to resolve brands in your own code (Multi-Brand Pro does):

$resolver->matchHost('Shop.Acme.com');                     // ?Brand — no fallback
$resolver->resolve($request);                              // Brand — brand 1 fallback
$resolver->resolveForSalesChannel($salesChannelId, $host); // Brand — host, then the channel's domains
$resolver->resolveForContext($salesChannelContext);        // Brand — also accepts a Context
$resolver->resolveCurrent($salesChannelId);                // Brand — what the Twig functions use

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

.button--primary {
  background: var(--brand-primary, #5B7F3A); // green-tea fallback
}

Standards

Performance — the brand config is read once per request (memoised, reset between requests on workers); matching is a loop over at most five patterns. Nothing is 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.
[ ] Make brand 1 your default brand. There is no separate default setting: brand 1 is the fallback for admin preview URLs and unmatched hostnames. Watch the log for "matches no brand hostname pattern" warnings after launch.
[ ] Let your CDN / Varnish / reverse-proxy cache vary on Host. The page HTML differs per brand host (tokens, data-brand, JSON-LD). A cache that keys only on the path serves brand A's page on brand B's domain. Shopware's own HTTP cache keys on the full URL including the host; check any cache in front of it.
[ ] 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 with 6.7.15	8.2 or newer	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.2	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 on PHP 8.2 or newer (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.15

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

Package info

Security

Statistics

README

Multi-Brand Lite

Lite tier — and what Pro adds

Screenshots

What it does

Install

Configuration

Usage

Mails, CLI and workers

For developers: the public API

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

Package info

Security

Statistics

README

Multi-Brand Lite

Lite tier — and what Pro adds

Screenshots

What it does

Install

Configuration

Usage

Mails, CLI and workers

For developers: the public API

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`