kirschbaum-development / commentions
A package to allow you to create comments, tag users and more
Installs: 1 062
Dependents: 0
Suggesters: 0
Security: 0
Stars: 77
Watchers: 12
Forks: 6
Open Issues: 8
Requires
- filament/filament: ^3.2|^4.0
- filament/notifications: ^3.2|^4.0
- filament/support: ^3.2|^4.0
- illuminate/database: ^11.0|^12.0
- illuminate/support: ^11.0|^12.0
- league/html-to-markdown: ^5.1
- livewire/livewire: ^3.5
- spatie/laravel-package-tools: ^1.18
Requires (Dev)
- illuminate/auth: ^11.0|^12.0
- larastan/larastan: ^3.0
- laravel/pint: ^1.21
- orchestra/testbench: ^9.9|^10.0
- pestphp/pest: ^3.7
- pestphp/pest-plugin-laravel: ^3.1
- pestphp/pest-plugin-livewire: ^3.0
README
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
composer require kirschbaum-development/commentions
Usage
- Publish the migrations
php artisan vendor:publish --tag="commentions-migrations"
- In your
User
model implement theCommenter
interface.
use Kirschbaum\Commentions\Contracts\Commenter; class User extends Model implements Commenter { // ... }
- In the model you want to add comments, implement the
Commentable
interface and theHasComments
trait.
use Kirschbaum\Commentions\HasComments; use Kirschbaum\Commentions\Contracts\Commentable; class Project extends Model implements Commentable { use HasComments; }
Usage with Filament
There are a couple of ways to use Commentions with Filament.
- Register the component in your Filament Infolists:
This works for Filament 3 and 4.
Infolists\Components\Section::make('Comments') ->schema([ CommentsEntry::make('comments') ->mentionables(fn (Model $record) => User::all()), ]),
- Or in your table actions:
If you are using Filament 3, you must use CommentsTableAction
in your table's actions
array:
use Kirschbaum\Commentions\Filament\Actions\CommentsTableAction; ->actions([ CommentsTableAction::make() ->mentionables(User::all()) ])
If you are using Filament 4, you should use CommentsAction
in recordActions
instead:
use Kirschbaum\Commentions\Filament\Actions\CommentsAction; ->recordActions([ CommentsAction::make() ->mentionables(User::all()) ])
- Or as a header action:
This works for Filament 3 and 4.
use Kirschbaum\Commentions\Filament\Actions\CommentsAction; protected function getHeaderActions(): array { return [ CommentsAction::make(), ]; }
Configuration
You can publish the configuration file to make changes.
php artisan vendor:publish --tag="commentions-config"
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
:
'commenter' => [ 'model' => \App\Domains\Users\User::class, ],
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:
'comment' => [ 'model' => \App\Models\Comment::class, // ... ],
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
namespace App\Policies; use Kirschbaum\Commentions\Comment; use Kirschbaum\Commentions\Contracts\Commenter; use Kirschbaum\Commentions\Policies\CommentPolicy as CommentionsPolicy; class CommentPolicy extends CommentionsPolicy { public function create(Commenter $user): bool { // TODO: Implement custom permission logic. } public function update($user, Comment $comment): bool { // TODO: Implement custom permission logic. } public function delete($user, Comment $comment): bool { // TODO: Implement custom permission logic. } }
2) Register your policy in the configuration file
Update the comment.policy
option in your config/commentions.php
file:
'comment' => [ // ... 'policy' => \App\Policies\CommentPolicy::class, ],
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.
use Filament\Models\Contracts\HasName; use Kirschbaum\Commentions\Contracts\Commenter; class User extends Model implements Commenter, HasName { public function getFilamentName(): string { return (string) '#' . $this->id . ' - ' . $this->name; } }
use Kirschbaum\Commentions\Contracts\Commenter; class User extends Model implements Commenter { public function getCommenterName(): string { return (string) '#' . $this->id . ' - ' . $this->name; } }
Configuring the Commenter avatar
To configure the avatar, make sure your User model implements Filament's HasAvatar
interface.
use Filament\Models\Contracts\HasAvatar; class User extends Authenticatable implements Commenter, HasName, HasAvatar { public function getFilamentAvatarUrl(): ?string { return $this->avatar_url; } }
Events
Two events are dispatched when a comment is created or reacted to:
Kirschbaum\Commentions\Events\UserWasMentionedEvent
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:
namespace App\Listeners; use Illuminate\Queue\InteractsWithQueue; use Illuminate\Contracts\Queue\ShouldQueue; use App\Notifications\UserMentionedInCommentNotification; use Kirschbaum\Commentions\Events\UserWasMentionedEvent; class SendUserMentionedNotification implements ShouldQueue { use InteractsWithQueue; public function handle(UserWasMentionedEvent $event): void { $event->user->notify( new UserMentionedInCommentNotification($event->comment) ); } }
If you have event auto-discovery, 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:
use Kirschbaum\Commentions\Config; Config::resolveAuthenticatedUserUsing( fn () => auth()->guard('my-guard')->user() )
Getting the mentioned Commenters from an existing comment
$comment->getMentioned()->each(function (Commenter $commenter) { // do something with $commenter... });
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.
Infolists\Components\Section::make('Comments') ->schema([ CommentsEntry::make('comments') ->poll('10s') ]),
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.
use Kirschbaum\Commentions\RenderableComment; public function getComments(): Collection { $statusHistory = $this->statusHistory()->get()->map(fn (StatusHistory $statusHistory) => new RenderableComment( id: $statusHistory->id, authorName: $statusHistory->user->name, body: sprintf('Status changed from %s to %s', $statusHistory->old_status, $statusHistory->new_status), createdAt: $statusHistory->created_at, )); $comments = $this->comments()->latest()->with('author')->get(); return $statusHistory->merge($comments); }
Security
If you discover any security related issues, please email security@kirschbaumdevelopment.com instead of using the issue tracker.
Credits
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 or join us!
License
The MIT License (MIT). Please see License File for more information.