DistributorUnboundFromCollaboratorGroup

DistributorUnboundFromCollaboratorGroup fires when an operator clears a distributor’s collaborator group binding. After this event, the distributor still runs its scheduled distribution periods, but a cascade-style allocation calc now has no group to walk. It fails closed: the period allocates nothing to anyone and raises no error, so the distributor keeps running periods that pay no one until it is bound to a group again. That silent zero-payout is the main reason to handle this event.

The event ID is distributor_unbound_from_collaborator_group, and its fully qualified class is Siren\Plus\Core\Groups\Events\DistributorUnboundFromCollaboratorGroup. It fires after the binding is cleared, from the distributor edit endpoint. To run code when it fires, register a handler with Siren’s event system. See listeners and the events introduction.

What does this event carry?

The event carries the distributor id and the group id that the distributor was previously bound to. The previous group id stays in the payload so audit logs can describe the change as “unbound from group #42” rather than “unbound from something.”

use PHPNomad\Events\Interfaces\CanHandle;
use PHPNomad\Events\Interfaces\Event;
use Siren\Plus\Core\Groups\Events\DistributorUnboundFromCollaboratorGroup;

class HandleDistributorUnbinding implements CanHandle
{
    public function handle(Event $event): void
    {
        if (!$event instanceof DistributorUnboundFromCollaboratorGroup) {
            return;
        }

        $distributorId = $event->getDistributorId();
        $previousGroupId = $event->getGroupId();

        // The next distribution period for this distributor has no group to walk
    }
}

How does it fit?

The unbind only broadcasts when there was a real prior binding to clear, so idempotent edits don’t generate phantom activity entries. Re-binding to a different group produces an unbind for the old group id followed immediately by a DistributorBoundToCollaboratorGroup for the new one. Both fire synchronously in the same request, so a transition listener always sees the unbind before the bind.

This event tracks the deliberate unbind or rebind action, not the liveness of the binding. Deleting the bound group does not fire it: the binding row stays on the distributor, now pointing at a group that is gone, and a cascade bound to it fails closed. Deleting the distributor does not fire it either. So a system that mirrors which distributors point at which groups must reconcile group and distributor deletions on its own rather than rely on this event alone.

Related events

DistributorBoundToCollaboratorGroup is the bind side, and ProgramBoundToCollaboratorGroup and ProgramUnboundFromCollaboratorGroup are the program-side pair. The collaborator group events reference lists the full family.