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

1. Publish the migrations

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:

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.

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 the Commenter avatar

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

Translations

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

Publish the language files into your application:

php artisan vendor:publish --tag="commentions-lang"
``

This will copy the language files to:

- `lang/vendor/commentions/{locale}/comments.php`

Override only the keys you need. Example (English):

### Events

Two events are dispatched when a comment is created or reacted to:

- `Kirschbaum\Commentions\Events\UserWasMentionedEvent`
- `Kirschbaum\Commentions\Events\CommentWasCreatedEvent`
- `Kirschbaum\Commentions\Events\CommentWasReactedEvent`

### Sending notifications when a user is mentioned

Every time a user is mentioned, the `Kirschbaum\Commentions\Events\UserWasMentionedEvent` is dispatched. You can listen to this event and send notifications to the mentioned user.

Example usage:

If you have [event auto-discovery](https://laravel.com/docs/11.x/events#registering-events-and-listeners), this should be enough. Otherwise, make sure to register your listener on the `EventServiceProvider`.

### Resolving the authenticated user

By default, when a new comment is made, the `Commenter` is automatically set to the current user logged in user (`auth()->user()`). If you want to change this behavior, you can implement your own resolver:

### Getting the mentioned Commenters from an existing comment

### Polling for new comments

Commentions supports polling for new comments. You can enable it on any component by calling the `poll` method and passing the desired interval.

### 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.

***

## 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.