repository·main·Indexed 40 days ago
https://github.com/kirschbaum-development/commentionsA drop-in package for Filament that adds commenting capabilities to resources, featuring user mentions, event dispatching, and subscription management. It supports Filament 3 and 4, providing components like CommentsEntry, CommentsAction, and CommentsTableAction for infolists and tables. Key features include emoji reactions, file attachments, star ratings, and customizable author avatars.
Commentions is a drop-in package for Filament that enables users to add comments to your resources. Key features include:
Commentions includes a subscription system where users can receive notifications for new comments on a resource.
Add these to your Filament resources:
SubscriptionAction: For header actions (Filament 3/4).SubscriptionTableAction: For table actions in Filament 3.SubscriptionAction: For record actions in Filament 4.The HasComments trait provides methods to manage subscriptions via code:
$commentable->subscribe($user)$commentable->unsubscribe($user)$commentable->isSubscribed($user)$commentable->getSubscribers()If using the commentions::comments (or commentions.comments in v4) Livewire component directly, use these properties:
sidebarEnabled (bool): Toggles the subscription sidebar.showSubscribers (bool): Toggles the list of current subscribers within the sidebar.// Programmatic subscription
$project->subscribe($user);
// Livewire component usage (Filament 4 style)
<livewire:commentions.comments
:record="$record"
:mentionables="App\Models\User::all()"
:sidebar-enabled="false"
/>To add commenting capabilities to your Filament resources, install the package using Composer and then run the provided Artisan installer to set up the necessary components.
composer require kirschbaum-development/commentions
php artisan commentions:installYou can display comments in Filament Infolists using the CommentsEntry component. This works for both Filament 3 and 4.
Register the entry and provide a list of mentionables (users who can be tagged).
By default, it uses the page's record. To comment on a different model (like a pivot or related record), use the record() method.
For better visual distinction, wrap the CommentsEntry in a Section component. Note that the Section class path differs between Filament 3 and 4.
// Filament 3 & 4 Infolist usage
CommentsEntry::make('comments')
->mentionables(fn (Model $record) => User::all()),
// Overriding the record
CommentsEntry::make('comments')
->record(fn () => $pivot)
->mentionables(User::all());Depending on your Filament version, use the appropriate action class in your table or header actions.
Use CommentsTableAction in your actions() array.
Use CommentsAction in your recordActions() array.
CommentsAction can also be used in the getHeaderActions() method for both Filament 3 and 4.
// Filament 3 Table Action
use Kirschbaum\Commentions\Filament\Actions\CommentsTableAction;
->actions([
CommentsTableAction::make()
->mentionables(User::all())
]);
// Filament 4 Record Action
use Kirschbaum\Commentions\Filament\Actions\CommentsAction;
->recordActions([
CommentsAction::make()
->mentionables(User::all())
]);
// Header Action (Filament 3 & 4)
protected function getHeaderActions(): array
{
return [
CommentsAction::make()
->mentionables(User::all()),
];
}To enable commenting, you must configure your models to implement the necessary interfaces and traits.
Kirschbaum\Commentions\Contracts\Commenter interface so the system knows who is making comments.Kirschbaum\Commentions\Contracts\Commentable interface and use the Kirschbaum\Commentions\HasComments trait on the model you want to allow comments on (e.g., a Project model).```php
use Kirschbaum\Commentions\Contracts\Commenter;
class User extends Model implements Commenter
{
// ...
}
use Kirschbaum\Commentions\HasComments;
use Kirschbaum\Commentions\Contracts\Commentable;
class Project extends Model implements Commentable
{
use HasComments;
}
```埋入```Publish the configuration file using:
php artisan vendor:publish --tag="commentions-config"
Control how comments are loaded in Filament components:
disablePagination(): Disables pagination entirely.perPage(int): Sets the number of comments per page.loadMoreIncrementsBy(int): Sets how many comments are appended when clicking 'Show more'.loadMoreLabel(string): Customizes the 'Show more' button text.commenter.model: Set the class for your User model if it's not App\Models\User.comment.model: Set a custom Comment model class.comment.policy: Set a custom Policy class for comment permissions.reactions.allowed: Array of allowed emoji strings.avatars.enabled: Boolean to enable/disable avatars globally.ratings.enabled: Boolean to enable/disable star ratings.attachments.enabled: Boolean to enable/disable file attachments.toolbar.buttons: Array of allowed TipTap editor buttons (can be grouped for separators).notifications.mentions.enabled: Enable/disable built-in mention notifications.notifications.mentions.channels: Array of channels (e.g., ['mail', 'database']).The CommentSubscription model is used to track which users (subscribers) are following which entities (subscribables) for comment notifications. It uses Laravel's polymorphic relationships to allow any model to be a subscriber or a subscribable entity.
Key properties available on the model:
subscribable: The entity being watched for comments (e.g., a Post, a Video).subscriber: The user or entity receiving the notifications.The table name for this model is configurable via Config::getCommentSubscriptionTable().
/**
* @property-read Model $subscribable
* @property-read Model $subscriber
*/The CommentReaction model represents a user's reaction to a specific comment. It tracks which comment was reacted to, who performed the reaction (reactor), and the type of reaction used.
Key properties and relationships:
comment: A BelongsTo relationship to the comment being reacted to. The specific model class is determined by Config::getCommentModel().reactor: A MorphTo relationship representing the entity that performed the reaction (the Commenter).reaction: A field storing the reaction type.The table name used by this model is configurable via Config::getCommentReactionTable().
// Example of accessing properties on a CommentReaction instance
$reaction = CommentReaction::first();
echo $reaction->reaction; // The reaction type
echo $reaction->comment->body; // Accessing the related comment
echo $reaction->reactor->name; // Accessing the related commenter (e.g., User)The package includes an installation command that automates the setup process. Running this command will:
php artisan commentions:installYou can publish the package's translation files to your application's language directory using the commentions-lang tag.
php artisan vendor:publish --tag=commentions-langBy default, the name property is used for mentions. To customize this, either:
HasName interface on your User model.getCommenterName() method on your User model.To use custom avatars, ensure your User model implements Filament's HasAvatar interface and provides a getFilamentAvatarUrl() method.
If users don't implement HasAvatar, the package uses an avatar provider (defaulting to the current Filament panel's provider) or falls back to ui-avatars.com. You can force a specific provider globally in config/commentions.php using the avatar_provider key.
use Filament\Models\Contracts\HasName;
use Filament\Models\Contracts\HasAvatar;
class User extends Model implements Commenter, HasName, HasAvatar
{
public function getFilamentName(): string
{
return (string) '#' . $this->id . ' - ' . $this->name;
}
public function getFilamentAvatarUrl(): ?string
{
return $this->avatar_url;
}
}