Synchronization.

When source text changes from @jane to @john, the stored mention must change with it. Synchronization creates John's row, removes Jane's row, and keeps any unchanged targets. It runs after a normal Eloquent save unless you disable it.

The synchronization pipeline

One synchronization follows this order:

1. Read every attribute returned by mentionableAttributes().
2. Parse each value with the selected parser.
3. Resolve the combined candidates through the resolver manager.
4. Collapse candidates that point to the same target.
5. Diff the desired targets against existing rows for the source.

The package writes the complete diff inside one database transaction.

Created, retained, and removed records

The diff creates a row for each new target and removes each target no longer in the text. It leaves unchanged rows in place.

$result = $comment->syncMentions();

$result->created;
$result->retained;
$result->removed;
$result->unresolved;

The first three properties contain arrays of Mention models. Removed models are still hydrated but have exists === false. The unresolved array contains MentionCandidate objects.

Duplicate protection

Synchronization keys desired targets by morph class and model key. One source therefore stores one row for each target even when:

• the same handle appears several times;
• several handles resolve to the same model;
• the target appears in more than one scanned attribute; or
• two processes try to create the row at the same time.

The database unique index is the final concurrency guard. If another process inserts the same pair first, createOrFirst() returns that row as retained.

Event timing

After the transaction completes, synchronization dispatches one MentionCreated event for each created row and one MentionRemoved event for each removed row.

A listener exception propagates after the package writes the diff in ordinary auto-commit use. An application-owned outer transaction can still roll back the source save and mention changes together.

Source deletion behavior

A normal delete prunes mention rows without dispatching MentionRemoved. That event means the text stopped naming a target, not that its source disappeared.

Soft deletion keeps mention rows. Restore does not rescan the source. Force deletion prunes the rows.

What to read next

• Control synchronization for explicit-only models and writes that bypass model events.
• React to lifecycle events for listener examples.
• Testing to assert each part of a diff.