CollaboratorGroupStructureChanged

CollaboratorGroupStructureChanged fires when an operator swaps the structure of an existing collaborator group, for example moving a group from flat to linearChain so it can support cascades. Per-member metadata is not migrated automatically when the structure changes, so listeners that depend on the new shape should expect to read fresh metadata for each member.

The event ID is collaborator_group_structure_changed, and its fully qualified class is Siren\Plus\Core\Groups\Events\CollaboratorGroupStructureChanged. It is fired by the update-group REST endpoint when the structure field changes. 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 group id, the previous structure resolver id (the string identifier like flat or linearChain), and the new structure resolver id.

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

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

        $groupId = $event->getGroupId();
        $from = $event->getPreviousStructure();
        $to = $event->getNewStructure();

        // The calc-picker capability set may have changed for any
        // program or distributor bound to this group
    }
}

How does it fit?

A structure swap can quietly invalidate downstream choices. Calc strategies that require the hasLayer capability (upline cascade, downline cascade) only make sense against linearChain and parentChild groups. Flipping a group back to flat hides those options in the picker on the next page load, but it does not touch a cascade calc that is already saved against the group. That saved cascade stays bound and fails closed at payout time, crediting no one, until an operator picks a compatible calc or restores a layered structure. So a layer-losing swap is a payout-breaking change, not a cosmetic one, and a handler should treat it as an alert rather than a quiet log.

Going the other way has its own catch. A swap from flat to a layered structure does not fill in member positions or parents, so until an operator sets them, every member sits at the default (position 0, or no parent), and a cascade runs in that degenerate order rather than the hierarchy the operator intends. See linear chain and parent-child for how to set them.

This event carries no per-member detail, and the member rows are not rewritten by the swap, so no per-member metadata-changed events fire alongside it. If you mirror Siren state, treat this event as a signal to re-read the whole group’s members and re-interpret their metadata under the new structure.

Related events

A structure swap and a rename made in one request fire both events. CollaboratorGroupCreated and CollaboratorGroupDeleted cover the rest of the lifecycle. The collaborator group events reference lists the full family.