Skip to main content

Configuration

You can publish the configuration file to make changes.

php artisan vendor:publish --tag="commentions-config"

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:

use Kirschbaum\Commentions\Filament\Actions\CommentsAction;

->recordActions([
    CommentsAction::make()
        ->mentionables(User::all())
        ->perPage(10)

])

Without Pagination:

use Kirschbaum\Commentions\Filament\Actions\CommentsAction;

->recordActions([
    CommentsAction::make()
        ->mentionables(User::all())
        ->disablePagination();

])

Advanced Usage:

use Kirschbaum\Commentions\Filament\Infolists\Components\CommentsEntry;

Infolists\Components\Section::make('Comments')
    ->schema([
        CommentsEntry::make('comments')
            ->mentionables(fn (Model $record) => User::all())
            ->perPage(8)
            ->loadMoreIncrementsBy(8)
            ->loadMoreLabel('Show older'),
    ])

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:

    '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.
    }
}
  1. 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 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' => [
        'enabled' => env('COMMENTIONS_REACTIONS_ENABLED', true),

        'allowed' => ['👍', '❤️', '😂', '🎉', '👀'],
    ],

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

CommentsEntry::make('comments')
    ->mentionables(User::all())
    ->disableReactions();

CommentsAction::make()
    ->mentionables(User::all())
    ->disableReactions();

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:

    'avatars' => [
        'enabled' => env('COMMENTIONS_AVATARS_ENABLED', true),
    ],
CommentsEntry::make('comments')
    ->mentionables(User::all())
    ->disableAvatars();

CommentsAction::make()
    ->mentionables(User::all())
    ->disableAvatars();

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.

use Filament\Models\Contracts\HasAvatar;

class User extends Authenticatable implements Commenter, HasName, HasAvatar
{
    public function getFilamentAvatarUrl(): ?string
    {
        return $this->avatar_url;
    }
}

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:

// config/commentions.php
use Filament\AvatarProviders\GravatarProvider;

return [
    // ...
    'avatar_provider' => GravatarProvider::class,
];

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

Configuring Custom Actions​

Add additional actions next to edit/delete:

use Kirschbaum\Commentions\Config;
use Filament\Actions\Action;

Config::registerCommentActions(fn ($comment) => Action::make('activityLogs')
    ->icon('heroicon-s-clock')
    ->iconButton()
    ->modalContent(/* ... */)
);

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):

    'ratings' => [
        'enabled' => env('COMMENTIONS_RATINGS_ENABLED', false),

        'max' => (int) env('COMMENTIONS_RATINGS_MAX', 5),
    ],

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

CommentsEntry::make('comments')
    ->mentionables(fn (Model $record) => User::all())
    ->enableRatings()
    ->maxRating(10)

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):

    'attachments' => [
        'enabled' => env('COMMENTIONS_ATTACHMENTS_ENABLED', false),

        // Filesystem disk and directory used to store uploads.
        'disk' => env('COMMENTIONS_ATTACHMENTS_DISK', 'public'),
        'directory' => env('COMMENTIONS_ATTACHMENTS_DIRECTORY', 'commentions-attachments'),

        // Maximum size per file, in kilobytes.
        'max_size' => (int) env('COMMENTIONS_ATTACHMENTS_MAX_SIZE', 10240),

        // Maximum number of files per comment.
        'max_files' => (int) env('COMMENTIONS_ATTACHMENTS_MAX_FILES', 5),

        // Accepted MIME types, validated against the file's actual contents.
        'accepted_mime_types' => [
            'image/jpeg', 'image/png', 'image/gif', 'image/webp', 'application/pdf',
            // ...
        ],
    ],

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

use Kirschbaum\Commentions\Filament\Infolists\Components\CommentsEntry;

CommentsEntry::make('comments')->mentionables(User::all())->enableAttachments();
CommentsEntry::make('comments')->mentionables(User::all())->enableAttachments(fn () => auth()->user()->isAdmin());
CommentsEntry::make('comments')->mentionables(User::all())->disableAttachments();

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.

use Kirschbaum\Commentions\Config;

Config::resolveTipTapCssClassesUsing(function () {
    return 'prose max-w-none focus:outline-none p-4';
});

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

use Kirschbaum\Commentions\Filament\Infolists\Components\CommentsEntry;

CommentsEntry::make('comments')
    ->mentionables(fn (Model $record) => User::all())
    ->tipTapCssClasses('prose max-w-none focus:outline-none p-4')

Or with actions:

use Kirschbaum\Commentions\Filament\Actions\CommentsAction;

CommentsAction::make()
    ->mentionables(User::all())
    ->tipTapCssClasses('prose max-w-none focus:outline-none p-4')

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

  1. 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:

    'toolbar' => [
        'enabled' => env('COMMENTIONS_TOOLBAR_ENABLED', true),

        'buttons' => [
            ['bold', 'italic', 'underline'],
            ['bulletList', 'orderedList'],
            ['link'],
        ],
    ],

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:

use Kirschbaum\Commentions\Filament\Infolists\Components\CommentsEntry;

CommentsEntry::make('comments')
    ->mentionables(fn (Model $record) => User::all())
    ->toolbarButtons([['bold', 'italic'], ['link']])

Or with actions:

use Kirschbaum\Commentions\Filament\Actions\CommentsAction;

CommentsAction::make()
    ->mentionables(User::all())
    ->toolbarButtons(['bold', 'italic', 'link'])

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