DistributorBoundToCollaboratorGroup

DistributorBoundToCollaboratorGroup fires when an operator wires a distributor to a collaborator group. The binding is what makes a distribution period’s cascade traverse the group when it allocates the reward pool. A distributor without a bound group has no cascade to run, regardless of which calc strategy is selected.

The event ID is distributor_bound_to_collaborator_group, and its fully qualified class is Siren\Plus\Core\Groups\Events\DistributorBoundToCollaboratorGroup. It fires after the binding is saved, 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 was just bound to it. A distributor can be wired to at most one collaborator group at a time. This event is the distributor twin of ProgramBoundToCollaboratorGroup: the same payload shape and one-group rule, and the same config pattern with type=distributor and subtype=<distributorId> in place of the program equivalents.

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

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

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

        // The next distribution period for this distributor will walk this group
    }
}

How does it fit?

The binding is stored as a config row keyed (type='distributor', subtype=<distributorId>, configKey='collaboratorGroupId'). The activity feed records the new pairing. Reporting layers that surface “which distributors point at this group” rebuild off the same event. Switching a distributor to a different group fires this event with the new id, after firing DistributorUnboundFromCollaboratorGroup for the previous one. Both fire synchronously in the same request, so the unbind always precedes the bind.

If a distribution period runs while the distributor has no bound group, the cascade has nothing to walk, so the period completes with no cascade allocations and raises no error. If the bound group’s structure cannot support the selected calc (a cascade calc on a flat group, for example), the calc fails closed at run time and credits no one, so a bind-time handler is a good place to catch an incompatible pairing early.

Related events

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