Brand resolution.

Brand resolution decides which identity the current request, command, or job uses. The package runs an ordered chain on the first read and keeps the first brand returned.

Default resolver order

The default chain is:

1. OverrideResolver returns a brand passed to Whitelabel::activate().
2. TenantResolver asks the current Spatie tenant for a brand.
3. DomainResolver finds a brand matching the HTTP request host.
4. DefaultResolver finds the identifier in whitelabel.default.

Order is behavior. Reordering the classes changes which source wins.

Lazy and retained resolution

The chain does not run during service-provider boot. The first call to current(), brand(), a Whitelabel Blade component, or branded mail resolves it.

use Byrcsc\Whitelabel\Facades\Whitelabel;

Whitelabel::isResolved(); // false
Whitelabel::current();
Whitelabel::isResolved(); // true

Later reads return the same brand without running the chain again. current() returns null when no resolver finds a brand.

Explicit activation

Activate a stored or runtime-defined brand by identifier:

$brand = Whitelabel::activate('acme');

Or pass a Brand object:

use Byrcsc\Whitelabel\Brand;

$brand = Whitelabel::activate(new Brand('preview', ['name' => 'Preview']));

A hand-built brand adopts the configured default as its fallback unless it is the default or already has a fallback. An unknown identifier throws UnknownBrand.

forget() removes the override and active brand, then leaves resolution lazy for the next read. flush() also removes every runtime definition.

Runtime definitions

Use define() for previews, tests, or other temporary brands:

$brand = Whitelabel::define('preview', [
    'name' => 'Preview',
    'colors' => ['primary' => '#be123c'],
]);

Whitelabel::activate($brand);

Runtime definitions are checked before the configured repository for both identifier and domain lookups. They are not persisted and disappear on flush() or process exit.

Eager HTTP resolution

Add EagerResolveBrand to a route group when resolution must happen before the route runs or when every view needs a shared $brand variable:

use Byrcsc\Whitelabel\Http\Middleware\EagerResolveBrand;
use Illuminate\Support\Facades\Route;

Route::middleware(EagerResolveBrand::class)->group(function (): void {
    Route::view('/dashboard', 'dashboard');
});

The middleware is optional. Without it, helpers and components still resolve the brand lazily.

Long-lived processes

The service provider flushes active state after queued jobs and after Octane requests, tasks, and ticks. It also flushes before a queue worker asks for the next job. Synchronous jobs do not clear the brand from the request that dispatched them.

What to read next

• Custom drivers and resolvers to add another source to the chain.
• Queues to restore the dispatch-time brand in asynchronous work.
• Events and listeners to react when the active brand changes.