Download the PHP package byrcsc/laravel-mentions without Composer

Laravel Mentions

Laravel Mentions adds @mentions to Eloquent models. It detects mentions in plain text or editor markup, resolves them to models, and stores queryable records. When the text changes, it syncs those records and fires an event for each mention added or removed.

Everything else stays yours. The package sends no notifications, renders no HTML, and ships no routes, controllers, or JavaScript.

Read the versioned documentation for the full installation, configuration, and usage guides.

Installation

Install the package:

Publish and run the migration:

Publish the config file to define which models handles resolve to:

How it works

Each mention record links the source model containing the text to the target model being mentioned. Both sides are polymorphic, so comments can mention users, tasks can mention teams, and your own models can mention anything you configure.

Because mentions are stored instead of parsed on demand, you can query them in either direction. Each record also snapshots the matched handle, so history stays readable after a handle changes.

The package includes two parsers:

• The regex parser detects handles such as @jane in plain text.
• The markup parser detects data-mention-id attributes emitted by rich text editors such as Tiptap and Trix.

You can choose a parser per model, replace either parser, and provide custom resolvers for tenant scoping or other lookup rules.

Quick start

Add HasMentions to a model containing mentionable text:

Add Mentionable to a model that can be mentioned:

Point the default resolver at that model and its handle column:

This uses name so it works with Laravel's default User model. In a real application, prefer a dedicated, uniquely indexed username column.

Mentions now sync whenever the source model is saved:

Syncing and events

Saving a model with HasMentions creates new mentions and removes stale ones. Call $model->syncMentions() when you need to sync explicitly, including after saveQuietly(), query-builder updates, or bulk imports that bypass Eloquent events.

Listen for MentionCreated and MentionRemoved to send notifications or run other application logic:

Deleting a source prunes its mention records without firing removal events. Soft deleting keeps them. MentionRemoved means the text stopped mentioning a target, not that a source record was cleaned up.

Querying mentions

Find source models that mention a target:

Query the underlying records from either side:

Out of scope

The package deliberately leaves these concerns to your application:

• Sending notifications
• HTTP endpoints and autocomplete
• JavaScript and editor integration
• Rendering mentions as links or HTML
• Permission checks

Versioning

The package follows semantic versioning.

• Upgrading within 1.x is safe. Nothing you use will break.
• Only a new major version, like 2.0.0, can break your code.
• If the README or the documentation describes it, it is safe to build on. If they don't, treat it as internal and expect it to change.

Bug fixes go into the newest version only. To get a fix, upgrade to it.

Questions and issues

• Stuck, or have an idea? Start a discussion. Usage questions and feature ideas both live there.
• Found a bug you can reproduce? Open an issue. A failing test is the fastest way to a fix, and a short reproduction is the next best thing.
• Found a security problem? Please don't open a public issue. See SECURITY.md for how to report it privately.
• Planning a pull request? CONTRIBUTING.md covers the setup and the three checks it needs to pass.

This package is maintained by one person, so replies can take a while. Everything gets read.

License

MIT. See CHANGELOG.md.