Spatie Multitenancy.

Use the optional Spatie integration when a tenant owns or selects a brand. The package does not prescribe tenant columns. Your tenant implements one contract and returns a Brand from any source.

1. Install the optional package

composer require spatie/laravel-multitenancy:^4.0

Configure Spatie Multitenancy before adding the Whitelabel switch task.

2. Implement ProvidesBrand

A tenant can build a brand from its columns:

namespace App\Models;

use Byrcsc\Whitelabel\Brand;
use Byrcsc\Whitelabel\Contracts\ProvidesBrand;
use Spatie\Multitenancy\Models\Tenant;

final class Account extends Tenant implements ProvidesBrand
{
    public function brand(): ?Brand
    {
        if ($this->brand_name === null) {
            return null;
        }

        return new Brand((string) $this->getKey(), [
            'name' => $this->brand_name,
            'colors' => ['primary' => $this->brand_color],
        ]);
    }
}

A hand-built tenant brand receives the configured default as fallback when it becomes active.

To look up a stored identifier instead:

use Byrcsc\Whitelabel\Contracts\BrandRepository;

public function brand(): ?Brand
{
    if ($this->brand_id === null) {
        return null;
    }

    return app(BrandRepository::class)->find($this->brand_id);
}

Returning null lets resolution continue to the request domain and default.

3. Register the switch task

Add the task to config/multitenancy.php:

use Byrcsc\Whitelabel\Spatie\SwitchTenantBrandTask;

'switch_tenant_tasks' => [
    SwitchTenantBrandTask::class,
],

When a tenant becomes current, the task activates its brand. When that tenant is forgotten, the task removes only the brand it activated. A later explicit Whitelabel::activate() therefore survives tenant cleanup.

Running the task again leaves the same brand active. Spatie may repeat switch tasks in a tenant-aware queued job.

Resolver-only integration

The included TenantResolver can read the current tenant without the switch task. It uses Spatie's configured current-tenant container key and calls brand() when the object implements ProvidesBrand.

The resolver runs only when your application reads the active brand. Register the switch task when tenant changes must activate and deactivate the brand immediately, including inside Spatie tenant-aware jobs.

Cache prefixes

The database repository resolves its cache store on every call. This lets Spatie's PrefixCacheTask change cache prefixes between tenants.

Leave whitelabel.cache.store as null when using that task unless the named store is also tenant-prefixed. A shared unprefixed store can expose one tenant's cached definitions to another tenant.

What to read next

• Queues to decide between tenant restoration and BrandAware.
• Cache management for safe cache configuration in tenant apps.
• Brand resolution for the order of override, tenant, domain, and default.