React to lifecycle events.

Use lifecycle events to start notification or audit work when source text gains or loses a target.

Listen for a created mention

Register a listener for MentionCreated:

namespace App\Listeners;

use Byrcsc\Mentions\Events\MentionCreated;

final class NotifyMentionedTarget
{
    public function handle(MentionCreated $event): void
    {
        $source = $event->mention->source;
        $target = $event->mention->target;

        // Authorize and send the application notification.
    }
}

The event carries a persisted Mention in its public readonly $mention property. An unchanged mention does not dispatch another created event.

Listen for a removed mention

MentionRemoved fires when synchronization deletes a row because the current text no longer identifies its target:

namespace App\Listeners;

use Byrcsc\Mentions\Events\MentionRemoved;

final class RecordRemovedMention
{
    public function handle(MentionRemoved $event): void
    {
        $mention = $event->mention;

        logger()->info('Mention removed from source text', [
            'source_type' => $mention->source_type,
            'source_id' => $mention->source_id,
            'target_type' => $mention->target_type,
            'target_id' => $mention->target_id,
        ]);
    }
}

The event retains the hydrated model after deletion. Its source() and target() morph relations can still load models from the stored columns.

Keep listeners retry-safe

The package dispatches events after its transaction returns. A thrown listener exception propagates, but the mention diff remains written in ordinary auto-commit use.

Keep synchronous listeners short. Dispatch application jobs with the scalar source and target identity when work should run later. If the source save and listener side effects must share one rollback boundary, own that transaction in the application.

Distinguish text changes from deletion

Pruning rows during source deletion dispatches no MentionRemoved events. Soft deletion does not prune them.

Listen to your source model's deletion events when source lifecycle changes need separate application behavior.

What to read next

• Synchronization for event ordering and transaction behavior.
• Control synchronization for deletion and restore rules.
• Testing to fake and assert lifecycle events.