Fallback and clearing.

Fallback lets each brand define only what differs from the default. Use it when most brands share assets, colours, mail details, or settings.

'default' => 'default',

'brands' => [
    'default' => [
        'name' => 'Example',
        'logo' => ['disk' => 'public', 'path' => 'brands/default/logo.svg'],
        'colors' => [
            'primary' => '#111827',
            'secondary' => '#64748b',
        ],
    ],
    'acme' => [
        'name' => 'Acme',
        'colors' => ['primary' => '#7c3aed'],
    ],
],

Acme inherits the logo and secondary colour. Its own name and primary colour replace the defaults.

Maps merge by key

The colors, mail, settings, and asset maps merge recursively by key. A brand can override one nested value without repeating its siblings.

Lists replace instead of merging:

'settings' => [
    'enabled_regions' => [],
],

That empty list clears an inherited list. An empty map such as 'colors' => [] carries no keys and therefore changes nothing. Clear an inherited colour by setting that colour to an empty string.

Empty clears and missing inherits

An omitted key inherits. An empty string or empty list is a value, so it wins over the fallback:

'acme' => [
    'logo' => '',
    'mail' => ['from_address' => ''],
    'settings' => ['tags' => []],
],

The logo and sender address then return null through their typed accessors. The tags remain an empty list.

Do not set a value to null. Definitions reject null because it cannot express whether you meant inheritance or clearing.

Domains never inherit

domain belongs only to the brand that defines it. A brand without a domain does not claim the default brand's host.

This constraint lets findByDomain() and the domain resolver maintain a one-host-to-one-brand relationship.

Fallback stays current

Drivers apply the current default whenever they build a non-default Brand. The cache stores definitions before fallback values are applied, so an update to the default brand changes inherited values on the next read.

Runtime definitions also rebuild against the current default. Calling define() before redefining the default does not freeze the earlier fallback.

Inspect own and effective values

definition() returns only the brand's own validated definition:

$own = $brand->definition();

toArray() returns the identifier plus the effective, inherited definition:

$effective = $brand->toArray();

Use fallback() to inspect the attached default brand. Use withFallback(?Brand $fallback): Brand when constructing an equivalent brand against another default.

What to read next

• Brand resolution to see how one of these brands becomes active.
• Brand repositories to understand how drivers apply the fallback.
• Manage database brands for how missing and empty values map to database columns.