Download the PHP package goldnead/statamic-brand-context without Composer

Brand Context

Optional multi-brand (multi-tenant) foundation for Statamic addons.

Single-brand by default. Most Statamic installs use the dependent addons exactly as before — one brand, no switcher, no visible machinery. The global scope is a no-op and every record belongs to a single default brand.

Multi-brand behind a flag. Flip brand-context.multi_brand on (optionally gated behind a license via license_check, so multi-brand can ship as a premium feature) to get hard brand isolation: the global scope filters every branded model by the current brand, new records are stamped with it, and the Control-Panel brand switcher appears.

The database schema is identical in both modes (brand_id everywhere, backfilled to the default brand), so enabling multi-brand later needs no migration.

Requirements

The Control-Panel surface (brand switcher, addon settings screen, the brand field on the user form) needs Statamic. The rest of the package boots in a plain Laravel application without it.

Installation

That is the whole install for single-brand mode. The default brand is created by the migration and the global scope is a no-op, so nothing changes visibly.

To enable multi-brand, publish the config and flip the flag:

The flag is read once at boot. Changing it takes effect on the next request, and on a deployed site you need php artisan config:clear if the config is cached.

The Control-Panel assets are published automatically by Statamic. If you have disabled that, or the switcher does not appear after an upgrade:

Publish tags

Building the Control-Panel assets

Only needed when working on this package itself. @statamic/cms resolves from the installed vendor directory, so Composer must run first:

Concepts

• Brand model — the tenant. Not itself scoped; brands are the scoping root. A default brand always exists.
• BrandMembers facade / BrandMembership — which Control Panel users belong to which brand. The one part of this package that is not about Eloquent models. See Brand members.
• HasBrand trait — add to any Eloquent model that must be brand-scoped. Applies the global BrandScope and stamps brand_id on create.
• BrandContext facade / BrandManager — multiBrandEnabled(), current(), setCurrent(), runFor(), withoutBrandScope().
• ResolveBrandFromToken middleware (brand.token) — API paths: resolves the Bearer token to a brand, fail-closed (401) in multi-brand mode.
• SetBrandFromSession middleware (brand.session) — CP paths: reads the brand the switcher stored.

Isolation guarantees (multi-brand mode)

• A query on a HasBrand model only ever returns the current brand's rows.
• With no current brand resolved and fail_mode=closed (default), reads return no rows — nothing leaks across brands. Explicit cross-brand access is opt-in via BrandContext::withoutBrandScope().
• Consent is per brand. The same email can hold independent consent/subscription state in different brands; uniqueness is enforced as (brand_id, …).

Usage

Brand members (which CP users belong to a brand)

The global scope isolates Eloquent models. A Statamic user is not one — with the file users repository it is not a database row at all — so "the users of this brand" cannot be expressed by scoping and gets its own answer:

Membership is brand affiliation, never authorisation. Consumers combine it with their own permission check:

Write access is attach() / detach(), both idempotent and both taking the same brand argument.

In the Control Panel it is a Brands field on Statamic's own user form — a multi-select of every brand, shown only when multi-brand is on and there is more than one brand to choose from. The value is never stored on the user: a Statamic user may be a yaml file rather than a database row, so the field is read from and written back to brand_user around the save. There is nothing to publish, configure or grant for it.

The rule that will surprise you

A user with no membership at all counts as a member of every brand.

Every install upgrading into this feature starts with an empty brand_user table. Strict filtering would empty every assignee dropdown, every team notification and every approval list on the day of the upgrade — and it would look exactly like a permissions bug. So nothing changes until somebody deliberately assigns a user. The first assignment is what narrows that user down, and it narrows them everywhere at once: from then on they belong only to the brands listed for them. Removing their last assignment puts them back into every brand; there is deliberately no way to express "member of nothing", which is what revoking a permission is for.

includes(), usersOf(), filter() and brandsOf() apply the rule. assignedUserIdsOf() and assignedBrandIdsOf() return the raw rows and do not — they are for rendering and auditing the assignments themselves, never for deciding who may be offered, notified or assigned.

Notes for consumers

• A user id is a string. brand_user.user_id holds $user->id(), which is a uuid under the file driver and a numeric key under the eloquent one. There is no foreign key on it — a Statamic install need not have a users table at all. attach() also accepts a Statamic user, an Authenticatable, an Eloquent model or an Identity from goldnead/statamic-identity-contracts.
• Name the brand in code without a session. With multi-brand on and no current brand (a console command, a queue worker), the membership API refuses to guess and throws. Pass the brand, or wrap the work in BrandContext::runFor() / the RunsForEachBrand trait.
• Single-brand installs are unaffected: includes() is always true and usersOf() returns every user.

Public routes

Links in an e-mail are opened without a session, so no brand is current and the fail-closed scope hides the record the link points at. The brand comes from the token instead:

The three arguments are the model, the column to look the value up in, and the route parameter (or input field) carrying it.

The column must carry a unique index across all brands. One token, one record, one brand — that is the whole safety argument. If two records answer, brandForUnique() throws AmbiguousBrandRecord rather than guessing, because guessing means serving one brand's record to another brand's visitor. Never pass a column that is unique only per brand.

Nothing is aborted by the middleware: an unknown value sets no brand, the scope stays closed, and the controller produces the response it always produced. And the brand is set explicitly on every request — never inherited from the last one, which matters the moment the app runs in a long-lived process.

Queued jobs

A worker has no request behind it, so nothing resolves a brand — and under multi-brand that is not "unscoped", it is fail-closed. Every branded query in the job returns zero rows, the job finishes successfully, and nothing anywhere says so: no exception, no failed_jobs row, no log line.

Since 1.9.0 the brand that was current when the job was pushed is written into the queue payload and set again while the job runs. Nothing has to be done for it; there is no trait and no base class.

Three properties are worth knowing:

• A job pushed with no current brand carries no key and runs exactly as before, fail-closed. The default brand is never substituted: a job silently widening from "no brand" to "the default brand" would be worse than one that does nothing.
• The previous brand is restored, not forgotten. On the sync connection a job runs inside the request that dispatched it, and clearing the brand afterwards would take it away from the rest of that request.
• A brand deleted between push and run leaves the job with no brand and one warning in the log. Fail-closed is the same answer the rest of the package gives when it cannot tell whose data it is looking at.

An explicit BrandContext::runFor() inside a job still wins, and still makes sense wherever the job knows better than its dispatcher did — a digest command looping over every brand, for instance.

Sender identity (who a brand's mail goes out as)

A mail belongs to a brand, so the address it comes from and the transport it leaves through belong to the brand too. Both live in brands.settings.mail:

Why the transport and not just the From. A relay that verifies sending domains per account (Scaleway TEM, Postmark, SES) refuses — or silently replaces — a From it does not own. Sending brand A's mail through the account that only knows brand B is how a reader ends up with brand A's newsletter under brand B's name. The two values have to be chosen together, which is why they live in one place and are resolved in one place. The SMTP credentials stay in the environment and never reach the database, a backup or a CP export.

Sending goes through BrandMailer, which puts the identity on the message and never into the config:

Four rules, and the reasons they are rules:

• A brand with no settings.mail changes nothing — the configured transport, whatever From the mailable settles on, the app locale. That is every single-brand install. Under multi-brand it also writes one warning per brand per five minutes, because there the host-wide From is somebody else's identity; refusing instead would make an install fall silent on an upgrade, which is the failure mode this whole thing is fighting.
• A brand that fills in from_name or mailer but no from_address sends nothing, and says why. Those three keys are what counts as declaring a sender; other keys under settings.mail (a host's own base URL, a locale) do not, so a brand that keeps something else there is not refused for a missing address. So does one naming a mailer that config/mail.php does not define — caught when the identity is resolved rather than at the send, because a digest stamps "delivered" on a week of items before the mail leaves.
• *`mail.from.is never written.** Laravel reads it the first time a mailer name is resolved and burns it into the cached instance (alwaysFrom), so an override escapes its ownfinally`: whichever brand sent first leaves its address standing for every later message that sets no From of its own. That is not fixable by being careful with config.
• A refusal is a return value, not an exception. A run across several brands has to skip one and carry on.

A mailable that travels this way must not overwrite a From that is already there:

A host that keeps sender identities somewhere else rebinds one contract:

Addons that send mail (statamic-marketing, -notifications, -preference-center, -automations) extend that interface in their own namespace and bind their own default, so a host can answer the question for marketing post alone without touching transactional post. Rebinding the contract above changes it for everything that has not been rebound individually.

Addon settings (one screen for every addon)

An addon that wants its values editable in the Control Panel implements Goldnead\BrandContext\Contracts\ProvidesSettings and registers the class with SettingsRegistry::register(). The screen, form, validation, storage (per brand, overrides only) and the config() values at runtime come from here; the addon declares the field list and nothing else. Required methods: settingsNamespace(), settingsConfigPath(), settingsPermission(), settingsGroups().

Four optional methods, read with method_exists() so an addon written against an older version keeps working unchanged:

Where the sidebar link goes. An addon with a Control Panel navigation of its own names that entry in settingsNavParent() (['Tools', __('Inbox')]) and gets a "Settings" child under it, which opens a page for that addon alone (no tab bar, the addon's name as title). Every other addon is a tab on one general page, "Addon Suite", with a single entry in the Settings section. If the parent entry is not found at runtime, or the user may not see it, the addon falls back to the general page, so no addon becomes unreachable. The nav is read at boot: the parent must be registered with Nav::extend() in the addon's own provider.

settingsTitle() is for a host that registers settings of its own: without it the title is derived from the namespace, and an app namespace like choirlive-mail shows up as "Choirlive Mail".

Map objects (what a map can point at)

An addon that wants its objects to appear on the funnels map implements Goldnead\BrandContext\Contracts\ProvidesMapObjects and registers it in boot():

A provider answers four questions: which objects exist (objects()), what one object is (find(): label, Control Panel link, on/off/no switch), and its single number over a period (metric(), or null when the addon has none). The map stores only type and id and asks the owning addon every time. MapObjectRegistry::lookup() returns found, missing (the reference is dead) or unavailable (no provider, or it failed). A provider that throws costs its own card, never the screen.

Testing

CI runs all of it on every push, plus a job that rebuilds resources/dist and fails if the committed bundle has drifted from its sources.

Support

Only the latest version of this addon is supported, against the Statamic major it targets. Bugs and questions go to GitHub issues; bugs in Statamic itself belong in statamic/cms.

Security reports do not go into a public issue — see SECURITY.md.

Changelog and license

LICENSE.md.