CollaboratorGroupMemberMetadataChanged

CollaboratorGroupMemberMetadataChanged fires when an existing membership has its metadata rewritten. For example, an operator changes a collaborator’s position in a linear chain, or moves a collaborator under a different parent in a parent-child tree. The event only fires when the metadata actually changes. A write that produces the same array is a no-op.

It fires once per member whose metadata changed, so a single update that reorders a chain fires one event for each member whose position moved, not one event for the whole reorder. The same is true of a bulk member replacement (a PUT of the full member list): every member whose metadata differs from before fires its own event. Adding a brand-new member fires CollaboratorAddedToCollaboratorGroup instead, not this event.

The event ID is collaborator_group_member_metadata_changed, and its fully qualified class is Siren\Plus\Core\Groups\Events\CollaboratorGroupMemberMetadataChanged. To run code when it fires, register a handler with Siren’s event system. See listeners for how to register one and the events introduction for the dispatch model.

What does this event carry?

The event carries the group id, the collaborator id, the metadata array before the change, and the metadata array after the change. Both arrays are keyed by the fields the group’s structure uses. A linear chain member carries a position (an integer), and a parent-child member carries a parentCollaboratorId (an integer, or null for a root). A custom structure resolver can define its own fields.

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

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

        $groupId = $event->getGroupId();
        $collaboratorId = $event->getCollaboratorId();
        $previous = $event->getPreviousMetadata();
        $next = $event->getNewMetadata();

        // e.g. for linearChain: ['position' => 2] became ['position' => 1]
    }
}

How does it fit?

Metadata is the structural payload. It’s what tells the cascade where a member sits relative to their peers. A position swap in a linear chain re-orders the upline. A parent change in a parent-child tree re-roots a whole subtree under a new ancestor. The activity feed records the before/after so an operator can see exactly what moved.

Because one reorder can move many members, a cache or external mirror that keys off member position should refresh the whole group rather than just the one collaborator named in the event. Changing the group’s own structure is a separate CollaboratorGroupStructureChanged event. A structure change does not rewrite member metadata, so it does not fire this event. The membership rows keep their existing keys, which the new structure may simply ignore.

Related events

CollaboratorAddedToCollaboratorGroup and CollaboratorRemovedFromCollaboratorGroup cover membership, and CollaboratorGroupStructureChanged covers a structure switch. The collaborator group events reference lists the full family.