Control synchronization.

Normal Eloquent saves synchronize mentions automatically. Call synchronization yourself after saveQuietly(), a bulk update, or another write that does not dispatch Eloquent's saved event. An explicit call also gives you the created, removed, retained, and unresolved results.

Synchronize one model explicitly

Call the source method after you persist its current text:

$comment->body = 'Thanks @jane and @john.';
$comment->saveQuietly();

$result = $comment->syncMentions();

The result reports created, retained, removed, and unresolved values for that source.

Disable automatic synchronization globally

Set auto_sync in config/mentions.php:

'auto_sync' => false,

Normal saves then leave mention records unchanged until syncMentions() is called.

Disable it for one model

Override the protected hook:

protected function syncsMentionsAutomatically(): bool
{
    return false;
}

This override takes precedence because the trait calls the model method during its saved listener.

Account for model-event blind spots

These writes do not trigger automatic synchronization:

• saveQuietly();
• query-builder update() calls;
• query-builder delete() calls;
• bulk inserts; and
• raw SQL writes.

After a mass update, retrieve each affected source and call syncMentions(). Plan for the parser, resolver, and diff queries per model.

Handle soft deletes and restores

Soft deleting a source leaves its mention rows in place. Restoring it does not rescan text.

If text changed while the model was deleted, restore it and sync explicitly:

$comment->restore();
$comment->syncMentions();

Force deleting through Eloquent prunes the rows without lifecycle events.

What to read next

• Synchronization for the exact diff result.
• Scan multiple attributes to control the combined input set.
• Troubleshooting when stored rows do not match source text.