Mention records.

Use a mention record when you need more than the model named in the text. The record gives you the mentioning model, the target model, the original handle, and the time the package created the link.

$mention = $comment->mentions()->with(['source', 'target'])->firstOrFail();

$mention->source;
$mention->target;
$mention->handle;

How the package stores the two models

The package calls the model containing the text the source. It calls the model named by the text the target.

Both sides use Eloquent polymorphic types:

The ID columns support integer, UUID, and ULID model keys. Each morph type and ID column is 191 characters long.

One row per source and target

A unique index covers source_type, source_id, target_type, and target_id. Repeating @jane in one attribute, or across several scanned attributes, still stores one row.

The synchronizer keeps the existing row when the source continues to mention the same target. Its primary key and created_at value do not change.

Handle snapshots

The regex parser stores the handle used for the match:

$mention->handle; // "jane"

The target columns remain the identity. Renaming Jane does not retarget or delete an existing row. The saved handle is a snapshot, not a live lookup.

The markup parser identifies targets by ID. Mention rows created from markup store null in handle.

Deletion ownership

Deleting a source model through Eloquent prunes its mention rows. Soft deleting a source keeps them until the model is force deleted.

Deleting a target does not prune rows that point to it. The Mentionable trait only defines a relationship. Add target cleanup in your application when it is required by your retention rules.

What to read next

• Parsing text to see how source text becomes candidates.
• Resolving targets to see how candidates find models.
• Synchronization to understand record retention and deletion.