Download the PHP package kirschbaum-development/commentions without Composer

Commentions is a drop-in package for Filament that allows you to add comments to your resources. You can configure it so your users are mentionable in the comments, and it dispatches events so you can handle mentions in your own application however you like.

• Installation
• Usage
• Upgrading
• Security
• Credits
• Sponsorship
• License

Installation

1. Install the package via Composer:

2. Run the installer

Usage

1. Register the assets

2. In your User model implement the Commenter interface.

3. In the model you want to add comments, implement the Commentable interface and the HasComments trait.

Usage with Filament

There are a couple of ways to use Commentions with Filament.

1. Register the component in your Filament Infolists:

This works for Filament 3 and 4.

If you wish to make the comments more distinct from the rest of the page, we recommend wrapping them in a Section.

For Filament 3:

For Filament 4:

By default the entry uses the page's record. To comment on a different model (e.g. a pivot or a related record in a table modal), override it explicitly:

2. Or in your table actions:

If you are using Filament 3, you must use CommentsTableAction in your table's actions array:

If you are using Filament 4, you should use CommentsAction in recordActions instead:

3. Or as a header action:

This works for Filament 3 and 4.

4. Or directly in form schemas for Edit pages (Filament 4):

View file contents

Filament 3:

Filament 4:

To make the form comments readonly, pass the readonly flag in the viewData:

Note: For View pages, continue using the infolist approach (option 1) as it works perfectly in that context.

Readonly Mode

You can make comments readonly by chaining the readonly() method on the action. In readonly mode:

• Users cannot add new comments
• Users cannot edit existing comments
• Users cannot delete comments
• Users cannot react to comments (reactions are displayed but not interactive)

This is useful for scenarios like:

• Archived or closed records where no further comments should be allowed
• View-only access for certain user roles
• Historical comment viewing
• Audit trails where comments should be preserved but not modified

Subscription Management

Commentions includes a subscription system that allows users to subscribe to receive notifications when new comments are added to a commentable resource.

Subscription Actions

You can add subscription actions to your Filament resources:

Subscription Sidebar

When using comments in modals, a subscription sidebar is automatically displayed showing:

• Subscribe/unsubscribe button for the current user
• List of users currently subscribed to the commentable
• Real-time updates when subscription status changes

Livewire options

When using the commentions::comments Livewire component directly, you can control the sidebar and its contents via component properties:

• sidebarEnabled (bool, default: true): toggles the entire subscription sidebar
• showSubscribers (bool, default: config('commentions.subscriptions.show_subscribers', true)): toggles the subscribers list within the sidebar

Examples:

For Livewire 3:

For Livewire 4:

Inside the component/template you can also rely on these computed properties:

• canSubscribe: whether the current user can subscribe
• isSubscribed: whether the current user is subscribed to the current record
• subscribers: a collection of current subscribers

The component exposes a toggleSubscription() action which subscribes/unsubscribes the current user.

Disabling the Subscription Sidebar

You can disable the subscription sidebar if you don't want subscription functionality:

Subscription Methods

The HasComments trait provides methods for managing subscriptions programmatically:

Configuration

You can publish the configuration file to make changes.

Pagination (Filament)

Commentions supports built-in pagination for the embedded list of comments and it is enabled by default. You can disable it or control the number of comments shown per page and per click.

• Enabled by default
• Disable via disablePagination()
• Configure page size
• Customize the load more label
• Control how many comments are appended per click (defaults to the page size)

Examples:

Default Usage:

Without Pagination:

Advanced Usage:

When pagination is enabled, a "Show more" button is displayed to load additional comments incrementally.

Configuring the User model and the mentionables

If your User model lives in a different namespace than App\Models\User, you can configure it in config/commentions.php:

Configuring the Comment model

If you need to customize the Comment model, you can extend the \Kirschbaum\Commentions\Comment class and then update the comment.model option in your config/commentions.php file:

Configuring Comment permissions

By default, users can create comments, as well as edit and delete their own comments. You can adjust these permissions by implementing your own policy:

1) Create a custom policy

2) Register your policy in the configuration file

Update the comment.policy option in your config/commentions.php file:

Configuring the Commenter name

By default, the name property will be used to render the mention names. You can customize it either by implementing the Filament HasName interface OR by implementing the optional getCommenterName method.

Configuring Reactions

By default, Commentions ships with the following reactions: ['👍', '❤️', '😂', '😮', '😢', '🤔']. You can customize which reactions are available by updating the reactions.allowed option in your config/commentions.php file:

Reactions are enabled by default. Disable them globally via reactions.enabled, or per component:

You can re-enable per component with ->enableReactions() when disabled globally.

Configuring Avatars

Avatars are enabled by default. Disable them globally, or per component when you want comments flush to the left:

You can re-enable per component with ->enableAvatars() when disabled globally.

Configuring the Commenter avatar

To configure the avatar, make sure your User model implements Filament's HasAvatar interface.

If your users do not implement HasAvatar, Commentions will consult an avatar provider before falling back to ui-avatars.com. By default it uses the current Filament panel's default provider (set via Panel::defaultAvatarProvider(...)). To force a specific provider regardless of panel context, set the avatar_provider config key:

Any class exposing a get(Model|Authenticatable $user): string method works.

Configuring Custom Actions

Add additional actions next to edit/delete:

Custom actions default to size('xs') so they match the built-in edit/delete buttons. Override with ->size() if needed. Use visible() / hidden() to show or hide an action; hidden actions are not rendered.

Configuring Comment Ratings

Commentions can attach an optional star rating to a comment, review-style. Ratings are disabled by default.

Enable them globally in your config/commentions.php file (or via the matching environment variables):

You can also enable ratings per component, which overrides the global config. This works on CommentsEntry, CommentsAction, and CommentsTableAction:

Available methods:

• enableRatings(bool|Closure $condition = true) — enable the rating input for this component.
• disableRatings() — disable the rating input, even if enabled globally.
• maxRating(int|Closure $max) — set the highest selectable rating (defaults to ratings.max).

When ratings are enabled, commenters can pick a rating while writing or editing a comment, and each rated comment renders its score as filled stars. The rating is stored in a nullable rating column added by the package's add_rating_to_commentions_comments_table migration.

Configuring Attachments

Commentions can let users attach files to their comments. Attachments are disabled by default.

Enable attachments globally in config/commentions.php (or via the COMMENTIONS_ATTACHMENTS_ENABLED env variable):

You can also toggle attachments per component instead of globally, which overrides the config value:

The same enableAttachments() / disableAttachments() methods are available on CommentsAction and CommentsTableAction.

[!WARNING] accepted_mime_types ships with a safe set of image types and file types. Leaving it empty allows any file type, which is dangerous on a public disk. Types that browsers execute in-origin (such as image/svg+xml or text/html) would be served directly from your application's URL and could be used for stored XSS. Keep an explicit allowlist, or store attachments on a private disk.

Attachments are deleted from both the database and the underlying disk when their parent comment is deleted through the model ($comment->delete()).

Customizing TipTap Editor

1. Style

You can customize the TipTap editor CSS classes used using the Config class.

And you can also override the classes on a per-component basis using the tipTapCssClasses() method:

Or with actions:

Important: Make sure to whitelist the classes in your Tailwind config if you override them.

2. Toolbar

The comment editor shows a formatting toolbar above the input. The available buttons are:

bold, italic, underline, strike, h1, h2, h3, blockquote, bulletList, orderedList, code, link.

You can configure which buttons appear globally via the toolbar option in your config/commentions.php file. Buttons may be a flat list, or grouped into arrays to render visual separators between groups:

To hide the toolbar entirely, set enabled to false (or set COMMENTIONS_TOOLBAR_ENABLED=false in your .env).

You can also override the buttons on a per-component basis using the toolbarButtons() method:

Or with actions:

Pass an empty array (->toolbarButtons([])) to hide the toolbar for a single component.

Translations

You can publish the package translation files and override any strings used by the UI.

Publish the language files into your application:

js Livewire.dispatch('commentions:refresh')

### Rendering non-Comments in the list

Sometimes you might want to render non-Comments in the list of comments. For example, you might want to render when the status of a project is changed. For this, you can override the `getComments` method in your model, and return instances of the `Kirschbaum\Commentions\RenderableComment` data object.

***

## Upgrading

See [UPGRADE.md](UPGRADE.md) for upgrade instructions.

***

## Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

## Credits

- [Luis Dalmolin](https://github.com/luisdalmolin)
- [All contributors](https://github.com/kirschbaum-development/commentions/graphs/contributors)

## Sponsorship

Development of this package is sponsored by Kirschbaum Development Group, a developer driven company focused on problem solving, team building, and community. Learn more [about us](https://kirschbaumdevelopment.com?utm_source=github) or [join us](https://careers.kirschbaumdevelopment.com?utm_source=github)!

## License

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.