Queues.

Use the BrandAware trait when queued work must run under the brand that was active when it was dispatched. Without it, the worker resolves the brand again and usually selects the configured default.

Add the trait to a job

namespace App\Jobs;

use Byrcsc\Whitelabel\Queue\BrandAware;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;

final class GenerateInvoice implements ShouldQueue
{
    use BrandAware;
    use Queueable;

    public function handle(): void
    {
        $name = brand('name');

        // Generate the invoice for this brand.
    }
}

Dispatch normally:

GenerateInvoice::dispatch();

The package adds the active identifier to the queue payload. Before a worker runs a class using BrandAware, it finds and activates that identifier.

Queue mail and notifications

The same trait works on your mailable, notification, or queued listener, even though Laravel wraps those objects in framework jobs:

use Byrcsc\Whitelabel\Queue\BrandAware;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Notification;

final class WelcomeNotification extends Notification implements ShouldQueue
{
    use BrandAware;
    use Queueable;
}

The restored brand is available to mail views, Markdown branding, and the optional sender override.

Missing and absent brands

If no brand was active at dispatch, no identifier is added. The worker then resolves normally.

If a captured identifier no longer exists when the job starts, the package throws CapturedBrandMissing. It does not silently use the default because that would produce customer-facing work under the wrong identity. Restore the brand and retry, or dispatch replacement work without that brand.

Jobs without the trait

All outgoing payloads may carry the identifier, but restoration is opt-in. Jobs without BrandAware ignore it and resolve the brand again in the worker.

The package flushes state after each asynchronous job and before the worker requests another. A synchronous job runs inside its caller and does not clear the caller's active brand.

Spatie tenant-aware jobs

Do not add BrandAware when a Spatie tenant-aware job should use the restored tenant's brand. Register SwitchTenantBrandTask and let Spatie restore the tenant first.

Use both only when the dispatch-time brand must override the tenant brand. The captured override wins, matching the default resolver order.

What to read next

• Spatie Multitenancy to derive brands from current tenants.
• Troubleshooting for missing captured brands or leaked worker state.
• Events and listeners for activation events inside workers.