Events and listeners.

Use package events when another part of your application must react after a brand becomes active, stops being active, or changes in the database.

Listen for active-brand transitions

namespace App\Listeners;

use Byrcsc\Whitelabel\Events\BrandActivated;

final class ConfigureBrandTelemetry
{
    public function handle(BrandActivated $event): void
    {
        $brandId = $event->brand->id();

        // Add the identifier to telemetry context.
    }
}

BrandActivated fires after resolution or explicit activation changes the active identifier. BrandDeactivated fires for the previous brand when it is replaced or forgotten.

Activating the same identifier again updates the retained Brand object but does not dispatch another transition event.

Listen for repository writes

The database driver dispatches these events after successful writes:

Each event has one public readonly property:

public readonly Brand $brand

For deletion, the property contains the last stored brand. Deleting an absent identifier returns false and dispatches nothing.

The config driver cannot write and therefore never dispatches repository write events. Runtime define() calls create temporary definitions instead of repository writes, so they do not dispatch these events either.

Register listeners

Use Laravel's normal event discovery or explicit listener mapping. Keep queued listeners brand-aware when they need the brand from the dispatching process:

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

final class RebuildBrandTheme implements ShouldQueue
{
    use BrandAware;

    public function handle(BrandUpdated $event): void
    {
        // The changed brand is always available on $event->brand.
    }
}

For repository events, prefer $event->brand over the active brand. A brand being edited does not have to be active.

What to read next

• Queues to restore dispatch-time context in queued listeners.
• Manage database brands for write behavior and failures.
• Public API for all event class names.