### Install Commentions Package and Publish Migrations

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Install the package via Composer, then publish and run the migrations to create the necessary database tables. Optional configuration and language files can also be published.

```bash
composer require kirschbaum-development/commentions

php artisan vendor:publish --tag="commentions-migrations"
php artisan migrate

# Optional: publish config and language files
php artisan vendor:publish --tag="commentions-config"
php artisan vendor:publish --tag="commentions-lang"
```

--------------------------------

### Install JavaScript Dependencies with npm

Source: https://github.com/kirschbaum-development/commentions/blob/main/CLAUDE.md

Use this command to install frontend JavaScript dependencies.

```bash
npm install
```

--------------------------------

### Install PHP Dependencies with Composer

Source: https://github.com/kirschbaum-development/commentions/blob/main/CLAUDE.md

Use this command to install PHP dependencies for the project.

```bash
composer install
```

--------------------------------

### Install Commentions Package

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Use Composer to install the Commentions package. This is the first step to integrate comment functionality into your application.

```bash
composer require kirschbaum-development/commentions
```

--------------------------------

### Implement HasName for Commenter Name

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Implement the Filament `HasName` interface to customize how commenter names are rendered. This example shows formatting the name with the user's ID.

```php
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;
    }
}
```

--------------------------------

### Handle User Subscribed to Commentable Event

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Listen for the `UserIsSubscribedToCommentableEvent` to send custom notifications when a new comment is created. This example uses a `NewCommentNotification`.

```php
namespace App\Listeners;

use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use App\Notifications\NewCommentNotification;
use Kirschbaum\Commentions\Events\UserIsSubscribedToCommentableEvent;

class SendSubscribedUserNotification implements ShouldQueue
{
    use InteractsWithQueue;

    public function handle(UserIsSubscribedToCommentableEvent $event): void
    {
        $event->user->notify(
            new NewCommentNotification($event->comment)
        );
    }
}
```

--------------------------------

### Implement HasAvatar for Commenter Avatar

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Ensure your User model implements Filament's `HasAvatar` interface to configure commenter avatars. This example returns the user's avatar URL.

```php
use Filament\Models\Contracts\HasAvatar;

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

--------------------------------

### Register Comments Entry in Filament Infolists

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Add the `CommentsEntry` component to your Filament Infolists to display comments. This example shows how to make users mentionable within the comments.

```php
CommentsEntry::make('comments')
    ->mentionables(fn (Model $record) => User::all()),
```

--------------------------------

### Get Mentioned Commenters

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Retrieve a collection of Commenter objects that were mentioned in a given comment. You can then iterate over this collection to perform actions.

```php
$comment->getMentioned()->each(function (Commenter $commenter) {
    // do something with $commenter...
});
```

--------------------------------

### Override Comment Translations

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Override specific translation keys for comments by editing the `lang/vendor/commentions/{locale}/comments.php` file. This example shows English overrides.

```php
// lang/vendor/commentions/en/comments.php
return [
    'label' => 'Notes',
    'no_comments_yet' => 'No notes yet.',
    'add_reaction' => 'Add a reaction',
    'cancel' => 'Close',
    'delete' => 'Remove',
    'save' => 'Update',
];
```

--------------------------------

### Build Frontend Assets for Production

Source: https://github.com/kirschbaum-development/commentions/blob/main/CLAUDE.md

Build frontend assets optimized for production.

```bash
npm run build
```

--------------------------------

### Build Frontend Assets for Development

Source: https://github.com/kirschbaum-development/commentions/blob/main/CLAUDE.md

Build frontend assets in development mode with watch mode enabled.

```bash
npm run dev
```

--------------------------------

### Build CSS Assets for Production

Source: https://github.com/kirschbaum-development/commentions/blob/main/CLAUDE.md

Build CSS assets optimized for production.

```bash
npm run build:styles
```

--------------------------------

### Build JavaScript Assets for Production

Source: https://github.com/kirschbaum-development/commentions/blob/main/CLAUDE.md

Build JavaScript assets optimized for production.

```bash
npm run build:scripts
```

--------------------------------

### Build CSS Assets in Development Mode

Source: https://github.com/kirschbaum-development/commentions/blob/main/CLAUDE.md

Build CSS assets in development mode with watch enabled.

```bash
npm run dev:styles
```

--------------------------------

### Perform Static Analysis

Source: https://github.com/kirschbaum-development/commentions/blob/main/CLAUDE.md

Run static analysis tools to catch potential issues.

```bash
composer static-analysis
```

--------------------------------

### Build JavaScript Assets in Development Mode

Source: https://github.com/kirschbaum-development/commentions/blob/main/CLAUDE.md

Build JavaScript assets in development mode with watch enabled.

```bash
npm run dev:scripts
```

--------------------------------

### Configure Commentions Package - PHP

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Customize global settings for authentication, comment URLs, and TipTap CSS classes using the static `Config` class. These configurations are typically set in `AppServiceProvider::boot()`.

```php
use Kirschbaum\Commentions\Config;

// Use a non-default auth guard
Config::resolveAuthenticatedUserUsing(
    fn () => auth()->guard('api')->user()
);

// Generate deep-link URLs for mention notification emails
Config::resolveCommentUrlUsing(function (Comment $comment): string {
    return route('projects.show', $comment->commentable)
        . '#comment-' . $comment->getId();
});

// Override TipTap editor CSS globally
Config::resolveTipTapCssClassesUsing(function (): string {
    return 'prose max-w-none focus:outline-none p-4 min-h-[100px]';
});

// Check Livewire version compatibility
Config::isLivewireV4();   // bool — used internally for component prefix
Config::getComponentPrefix();  // "commentions." (v4) or "commentions::" (v3)
```

--------------------------------

### Publish Commentions Migrations

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Run this Artisan command to publish the necessary database migrations for the Commentions package. Ensure you have configured your database connection.

```bash
php artisan vendor:publish --tag="commentions-migrations"
```

--------------------------------

### Publish Commentions Language Files

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Publish the package's translation files to your application using the `vendor:publish` Artisan command.

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

--------------------------------

### Enable Mention Notifications in Config

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Configure Commentions to enable built-in notifications for user mentions. Specify the notification channels to use.

```php
    'notifications' => [
        'mentions' => [
            'enabled' => true,
            'channels' => ['mail', 'database'],
        ],
    ],
```

--------------------------------

### Run Pest PHP Tests

Source: https://github.com/kirschbaum-development/commentions/blob/main/CLAUDE.md

Execute all tests using the Pest testing framework.

```bash
./vendor/bin/pest
```

--------------------------------

### Check Code Style with Composer Lint

Source: https://github.com/kirschbaum-development/commentions/blob/main/CLAUDE.md

Run code style checks to ensure consistency.

```bash
composer lint:check
```

--------------------------------

### Configure Allowed Reactions

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Customize the available reactions by updating the `allowed` option in `config/commentions.php`.

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

--------------------------------

### Publish Commentions Configuration File

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Publish the commentions configuration file to your application's config directory using the provided Artisan command. This allows for customization of package settings.

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

--------------------------------

### Config Class - Global Resolvers

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Provides static methods to customize global settings such as authentication, comment URLs, and TipTap CSS classes.

```APIDOC
## Config Class — Global Resolvers

**Customise authentication, URLs, and TipTap styles globally**

The static `Config` class provides hooks that override default package behaviour throughout the application lifecycle, typically called in `AppServiceProvider::boot()`.

```php
use Kirschbaum\Commentions\Config;

// Use a non-default auth guard
Config::resolveAuthenticatedUserUsing(
    fn () => auth()->guard('api')->user()
);

// Generate deep-link URLs for mention notification emails
Config::resolveCommentUrlUsing(function (Comment $comment): string {
    return route('projects.show', $comment->commentable)
        . '#comment-' . $comment->getId();
});

// Override TipTap editor CSS globally
Config::resolveTipTapCssClassesUsing(function (): string {
    return 'prose max-w-none focus:outline-none p-4 min-h-[100px]';
});

// Check Livewire version compatibility
Config::isLivewireV4();   // bool — used internally for component prefix
Config::getComponentPrefix();  // "commentions." (v4) or "commentions::" (v3)
```
```

--------------------------------

### Manage Subscriptions Directly in PHP

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Manage user subscriptions to records directly within a controller or Livewire component. Allows subscribing, unsubscribing, and checking subscription status.

```php
// In a controller or Livewire component — manage subscriptions directly
$project = Project::find(1);
$user    = auth()->user();

$project->subscribe($user);
echo $project->isSubscribed($user) ? 'Watching' : 'Not watching';

$project->getSubscribers()->each(fn ($u) => dump($u->name));

$project->unsubscribe($user);
```

--------------------------------

### Configure Built-in Mention Notifications

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Configuration for enabling and customizing mention notifications, including channels and mail subject.

```php
// config/commentions.php
'notifications' => [
    'mentions' => [
        'enabled'  => true,                    // COMMENTIONS_NOTIFICATIONS_MENTIONS_ENABLED=true
        'channels' => ['mail', 'database'],    // COMMENTIONS_NOTIFICATIONS_MENTIONS_CHANNELS=mail,database
        'mail'     => [
            'subject' => 'You were mentioned in a comment',
        ],
    ],
],
```

--------------------------------

### Listen for User Mentioned Event

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Implement this listener to handle the UserWasMentionedEvent. It sends a notification to the mentioned user. Ensure the listener is registered in your EventServiceProvider if auto-discovery is not enabled.

```php
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)
        );
    }
}
```

--------------------------------

### Commentions Configuration Reference

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Full configuration options for `config/commentions.php`, covering table names, models, reactions, subscriptions, and notifications.

```php
use Kirschbaum\Commentions\Comment;
use Kirschbaum\Commentions\Listeners\SendUserMentionedNotification;
use Kirschbaum\Commentions\Notifications\UserMentionedInComment;
use Kirschbaum\Commentions\Policies\CommentPolicy;

return [
    'tables' => [
        'comments'              => 'comments',
        'comment_reactions'     => 'comment_reactions',
        'comment_subscriptions' => 'comment_subscriptions',
    ],

    'commenter' => [
        'model' => \App\Models\User::class,   // Override if User lives elsewhere
    ],

    'comment' => [
        'model'  => Comment::class,
        'policy' => CommentPolicy::class,
    ],

    'reactions' => [
        'allowed' => ['👍', '❤️', '😂', '😮', '😢', '🤔'],
    ],

    'subscriptions' => [
        'dispatch_as_mention'       => false,  // env: COMMENTIONS_SUBSCRIPTIONS_DISPATCH_AS_MENTION
        'show_subscribers'          => true,   // env: COMMENTIONS_SUBSCRIPTIONS_SHOW_SUBSCRIBERS
        'show_sidebar'              => true,   // env: COMMENTIONS_SUBSCRIPTIONS_SHOW_SIDEBAR
        'auto_subscribe_on_comment' => true,   // env: COMMENTIONS_SUBSCRIPTIONS_AUTO_SUBSCRIBE_ON_COMMENT
        'auto_subscribe_on_mention' => true,   // env: COMMENTIONS_SUBSCRIPTIONS_AUTO_SUBSCRIBE_ON_MENTION
    ],

    'notifications' => [
        'mentions' => [
            'enabled'      => false,                          // env: COMMENTIONS_NOTIFICATIONS_MENTIONS_ENABLED
            'channels'     => ['mail'],                       // env: COMMENTIONS_NOTIFICATIONS_MENTIONS_CHANNELS
            'listener'     => SendUserMentionedNotification::class,
            'notification' => UserMentionedInComment::class,
            'mail'         => [
                'subject' => 'You were mentioned in a comment',
            ],
        ],
    ],
];
```

--------------------------------

### Convert HTML to Markdown with Mentions

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Converts TipTap HTML output to Markdown. Optionally, custom handlers can transform mentions into different formats like Slack's user IDs.

```php
use Kirschbaum\Commentions\Actions\HtmlToMarkdown;

$html = '<p>Hey <span class="mention" data-id="5" data-label="Alice" data-type="mention">@Alice</span>, check this out!</p>';

// Default: mentions become *@Alice*
$markdown = HtmlToMarkdown::run($html);
// "Hey *@Alice*, check this out!"

// Custom mention handler (e.g., Slack-style user IDs)
$markdown = HtmlToMarkdown::run($html, function (string $id, string $label): string {
    return "<@U{$id}>"; // Slack mention format
});
// "Hey <@U5>, check this out!"
```

--------------------------------

### Implement Commenter Interface in User Model

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Your User model must implement the `Commenter` interface from the Commentions package to enable user mention functionality. Ensure the `use` statement is present.

```php
use Kirschbaum\Commentions\Contracts\Commenter;

class User extends Model implements Commenter
{
    // ...
}
```

--------------------------------

### Handle User Mentioned Event Listener

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Listens for the `UserWasMentionedEvent` to notify the mentioned user.

```php
// app/Listeners/HandleUserMentioned.php
use Kirschbaum\Commentions\Events\UserWasMentionedEvent;

class HandleUserMentioned implements ShouldQueue
{
    public function handle(UserWasMentionedEvent $event): void
    {
        $event->user->notify(new YouWereMentionedNotification($event->comment));
    }
}
```

--------------------------------

### Apply Code Style Fixes with Composer Lint

Source: https://github.com/kirschbaum-development/commentions/blob/main/CLAUDE.md

Automatically apply code style fixes to the project.

```bash
composer lint
```

--------------------------------

### Filament SubscriptionAction for Subscribe/Unsubscribe

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Implement SubscriptionAction to allow users to subscribe or unsubscribe from commentable records. Customize labels and icons for subscribe and unsubscribe states. This action works for header, record, and table actions.

```php
use Kirschbaum\Commentions\Filament\Actions\SubscriptionAction;
use Kirschbaum\Commentions\Filament\Actions\SubscriptionTableAction;

// Header action
protected function getHeaderActions(): array
{
    return [
        SubscriptionAction::make()
            ->subscribeLabel('Watch project')
            ->unsubscribeLabel('Stop watching')
            ->subscribeIcon('heroicon-o-eye')
            ->unsubscribeIcon('heroicon-o-eye-slash'),
    ];
}

// Filament 4 record action
->recordActions([
    SubscriptionAction::make(),
])

// Filament 3 table action
->actions([
    SubscriptionTableAction::make(),
])
```

--------------------------------

### Programmatic Comment Creation with SaveComment

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Create comments programmatically using SaveComment::run(). This action enforces policies, persists comments, fires events, handles mentions, auto-subscribes users, and notifies subscribers. It returns the created comment object.

```php
use Kirschbaum\Commentions\Actions\SaveComment;
use Kirschbaum\Commentions\Comment;
use Illuminate\Auth\Access\AuthorizationException;

$project = Project::findOrFail(42);
$bot     = User::where('email', 'bot@example.com')->first();

try {
    // Body is stored as TipTap HTML; plain-text is fine too
    $comment = SaveComment::run(
        commentable: $project,
        author: $bot,
        body: 'Deployment finished successfully at ' . now()->toTimeString(),
    );

    echo $comment->getId();           // int primary key
    echo $comment->getAuthorName();   // "bot"
    echo $comment->getBody();         // raw HTML body
    echo $comment->getParsedBody();   // HTML with mention spans styled
    echo $comment->body_markdown;     // Markdown version via HtmlToMarkdown
} catch (AuthorizationException $e) {
    // Thrown when the policy's create() returns false
    logger()->error('Bot cannot post comments', ['error' => $e->getMessage()]);
}
```

--------------------------------

### Comment Model - Key Methods

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Provides methods for interacting with an existing Comment record, including reading content, managing reactions, and extracting mentions.

```APIDOC
## Comment Model - Key Methods

**Interact with an existing Comment record**

The `Comment` Eloquent model implements `RenderableComment` and exposes helpers for reading content, managing reactions, and extracting mentions.

```php
$comment = Comment::with('reactions.reactor', 'author')->find(7);

// Reading content
$comment->getBody();           // raw TipTap HTML
$comment->getParsedBody();     // HTML with styled mention spans
$comment->body_markdown;       // Markdown string (computed attribute)
$comment->body_parsed;         // alias for getParsedBody() as attribute
$comment->getAuthorName();     // author's display name
$comment->getAuthorAvatar();   // URL or ui-avatars.com fallback
$comment->getCreatedAt();      // Carbon instance
$comment->isAuthor($user);     // bool — is $user the author?

// Mentions
$comment->getMentioned()->each(function (Commenter $user) {
    // Collection of Commenter instances referenced in body via data-id spans
    Mail::to($user)->send(new MentionMail($comment));
});

// Custom mention transformation when converting to Markdown
$markdown = $comment->getBodyMarkdown(function (string $id, string $label): string {
    return "[@{$label}](https://example.com/users/{$id})";
});

// Reactions
$comment->toggleReaction('👍');   // adds or removes the reaction for auth user
$comment->reactions;              // HasMany relation
```
```

--------------------------------

### Wrap Comments Entry in Filament Section (Filament 3)

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

For Filament 3, use `
Filament
Infolists
Components
Section` to visually group the comments entry within your infolist.

```php
\Filament\Infolists\Components\Section::make('Comments')
    ->schema([
        CommentsEntry::make('comments'),
    ]),
```

--------------------------------

### Handle Comment Reaction Event Listener

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Listens for the `CommentWasReactedEvent` to log reaction details.

```php
// app/Listeners/HandleReaction.php
use Kirschbaum\Commentions\Events\CommentWasReactedEvent;

class HandleReaction
{
    public function handle(CommentWasReactedEvent $event): void
    {
        logger('Reaction added', [
            'comment_id' => $event->comment->getId(),
            'reaction'   => $event->reaction->reaction,
        ]);
    }
}
```

--------------------------------

### Wrap Comments Entry in Filament Section (Filament 4)

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

For Filament 4, use `
Filament
Schemas
Components
Section` to visually group the comments entry within your infolist.

```php
\Filament\Schemas\Components\Section::make('Comments')
    ->components([
        CommentsEntry::make('comments'),
    ]),
```

--------------------------------

### Enable Polling for New Comments

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Enable real-time polling for new comments on a component by calling the `poll` method with the desired interval. This is useful for keeping comment sections up-to-date.

```php
Infolists\Components\Section::make('Comments')
    ->schema([
        CommentsEntry::make('comments')
            ->poll('10s')
    ]),
```

--------------------------------

### Implement Commenter Interface on User Model

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Mark your User model as a commenter by implementing the `Commenter` contract. Optionally implement `HasName` and `HasAvatar` for custom display names and avatars in the comment UI.

```php
use FilamentleauContracts\u0002HasAvatar;
use FilamentleauContracts\u0002HasName;
use Kirschbaum\u0002Commentions\u0002Contracts\u0002Commenter;

class User extends Authenticatable implements Commenter, HasName, HasAvatar
{
    // Custom display name shown in @mention suggestions and comment headers
    public function getFilamentName(): string
    {
        return '#' . $this->id . ' - ' . $this->name;
    }

    // Avatar URL; falls back to ui-avatars.com initials if null
    public function getFilamentAvatarUrl(): ?string
    {
        return $this->avatar_url;
    }
}
```

--------------------------------

### Configure Comment Pagination in Filament

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Control comment pagination within Filament using the `CommentsAction` or `CommentsEntry`. Set `perPage` to define items per page, `loadMoreIncrementsBy` for appended items, and `loadMoreLabel` for the button text. Use `disablePagination()` to turn off pagination entirely.

```php
use Kirschbaum\Commentions\Filament\Actions\CommentsAction;

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

])
```

```php
use Kirschbaum\Commentions\Filament\Actions\CommentsAction;

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

])
```

```php
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'),
    ])
```

--------------------------------

### Add SubscriptionAction in Filament Header Actions

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Include the `SubscriptionAction` in your Filament resource's header actions to allow users to subscribe or unsubscribe from comment notifications.

```php
use Kirschbaum\Commentions\Filament\Actions\SubscriptionAction;

// In header actions
protected function getHeaderActions(): array
{
    return [
        SubscriptionAction::make(),
    ];
}
```

--------------------------------

### Create Custom Comment Policy

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Implement a custom policy by extending `Kirschbaum\Commentions\Policies\CommentPolicy` and defining `create`, `update`, and `delete` methods for custom permission logic. Register this policy in `config/commentions.php` under the `comment.policy` option.

```php
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.
    }
}
```

```php
    'comment' => [
        // ...
        'policy' => \App\Policies\CommentPolicy::class,
    ],
```

--------------------------------

### Manage Subscriptions Programmatically with HasComments Trait

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Utilize the `HasComments` trait methods to subscribe, unsubscribe, check subscription status, or retrieve all subscribers for a commentable entity. These methods provide direct control over user subscriptions.

```php
// Subscribe a user
$commentable->subscribe($user);
```

```php
// Unsubscribe a user
$commentable->unsubscribe($user);
```

```php
// Check if a user is subscribed
$isSubscribed = $commentable->isSubscribed($user);
```

```php
// Get all subscribers
$subscribers = $commentable->getSubscribers();
```

--------------------------------

### Customize TipTap Editor CSS Classes Globally

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Globally customize the CSS classes used by the TipTap editor by resolving them using `Config::resolveTipTapCssClassesUsing`.

```php
use Kirschbaum\Commentions\Config;

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

--------------------------------

### Resolve Authenticated User

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Customize the resolver for the authenticated user if you are not using the default `auth()->user()`. This allows specifying a custom authentication guard.

```php
use Kirschbaum\Commentions\Config;

Config::resolveAuthenticatedUserUsing(
    fn () => auth()->guard('my-guard')->user()
)
```

--------------------------------

### Add CommentsAction as a Header Action

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Display a comment action in the header of your Filament resource pages. This provides a prominent place for users to initiate or view comments.

```php
use Kirschbaum\Commentions\Filament\Actions\CommentsAction;

protected function getHeaderActions(): array
{
    return [
        CommentsAction::make(),
    ];
}
```

--------------------------------

### Control Livewire Commentions Component Properties

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Control the visibility of the subscription sidebar and the subscribers list within the Livewire commentions component. Set `sidebar-enabled` to false to hide the entire sidebar, or `show-subscribers` to false to hide only the subscribers list.

```php
<livewire:commentions::comments :record="$record" :sidebar-enabled="false" />
```

```php
<livewire:commentions::comments :record="$record" :show-subscribers="false" />
```

--------------------------------

### Configure Custom User Model Namespace

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Update the `commenter.model` option in `config/commentions.php` if your User model is located in a different namespace than the default `App\Models\User`.

```php
    'commenter' => [
        'model' => \App\Domains\Users\User::class,
    ],
```

--------------------------------

### Handle Comment Creation Event Listener

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Listens for the `CommentWasCreatedEvent` to perform actions like logging activity on the commentable model.

```php
// app/Listeners/HandleCommentCreated.php
use Kirschbaum\Commentions\Events\CommentWasCreatedEvent;

class HandleCommentCreated implements ShouldQueue
{
    use InteractsWithQueue;

    public function handle(CommentWasCreatedEvent $event): void
    {
        $comment = $event->comment;
        // $comment->commentable — the parent model (Project, Ticket, etc.)
        // $comment->author      — the Commenter who posted it
        activity()->on($comment->commentable)->log('New comment added');
    }
}
```

--------------------------------

### Handle Subscriber Notification Event Listener

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Listens for the `UserIsSubscribedToCommentableEvent` to notify users about new comments on watched records.

```php
// app/Listeners/HandleSubscriberNotification.php
use Kirschbaum\Commentions\Events\UserIsSubscribedToCommentableEvent;

class HandleSubscriberNotification implements ShouldQueue
{
    public function handle(UserIsSubscribedToCommentableEvent $event): void
    {
        $event->user->notify(new NewCommentOnWatchedRecord($event->comment));
    }
}
```

--------------------------------

### Filament CommentsAction for Header and Record Actions

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Use CommentsAction to open a comment modal from header or record actions. Configure mentionables, pagination, and polling. The disableSidebar option hides the subscription sidebar.

```php
use Kirschbaum\Commentions\Filament\Actions\CommentsAction;
use Kirschbaum\Commentions\Filament\Actions\CommentsTableAction; // Filament 3 table

// Header action (Filament 3 & 4)
protected function getHeaderActions(): array
{
    return [
        CommentsAction::make()
            ->mentionables(User::all())
            ->perPage(10)
            ->poll('15s')
            ->disableSidebar(),          // hides subscription sidebar
    ];
}

// Filament 4 record action in table
->recordActions([
    CommentsAction::make()
        ->mentionables(fn ($record) => User::where('team_id', $record->team_id)->get())
        ->perPage(5)
        ->loadMoreIncrementsBy(5),
])

// Filament 3 table action
->actions([
    CommentsTableAction::make()
        ->mentionables(User::all()),
])
```

--------------------------------

### Implement Commentable Interface and HasComments Trait

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Models that should be commentable must implement the `Commentable` interface and use the `HasComments` trait. This enables the comment functionality for those models.

```php
use Kirschbaum\Commentions\HasComments;
use Kirschbaum\Commentions\Contracts\Commentable;

class Project extends Model implements Commentable
{
    use HasComments;
}
```

--------------------------------

### Livewire Subscription Sidebar Component

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Use the subscription sidebar independently outside a modal. Supports Livewire 3 and Livewire 4 with different namespace conventions.

```blade
{{-- Livewire 3 --}}
<livewire:commentions::subscription-sidebar
    :record="$project"
    :show-subscribers="true"
/>

{{-- Livewire 4 --}}
<livewire:commentions.subscription-sidebar
    :record="$project"
    :show-subscribers="false"
/>
```

--------------------------------

### Customize TipTap Editor CSS Classes Per Component

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Override TipTap editor CSS classes on a per-component basis using the `tipTapCssClasses()` method in `CommentsEntry`.

```php
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')
```

--------------------------------

### Implement Commentable Interface and HasComments Trait on Eloquent Model

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Add commenting capability to any Eloquent model by implementing the `Commentable` contract and using the `HasComments` trait. This provides methods for posting, retrieving, and managing comments and subscriptions.

```php
use Kirschbaum\u0002Commentions\u0002Contracts\u0002Commentable;
use Kirschbaum\u0002Commentions\u0002HasComments;

class Project extends Model implements Commentable
{
    use HasComments;
}

// --- Programmatic usage ---

$project = Project::find(1);
$user    = User::find(1);

// Post a comment programmatically
$comment = $project->comment('This looks great!', $user);

// Retrieve comments (all or limited)
$all    = $project->getComments();
$latest = $project->getComments(limit: 10);

// Subscription management
$project->subscribe($user);
$project->isSubscribed($user);  // true
$project->getSubscribers();     // Collection<Commenter>
$project->unsubscribe($user);
```

--------------------------------

### Configure Custom Comment Model

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Extend the `Kirschbaum\Commentions\Comment` class and update the `comment.model` option in `config/commentions.php` to use your custom Comment model.

```php
    'comment' => [
        'model' => \App\Models\Comment::class,
        // ...
    ],
```

--------------------------------

### Add CommentsTableAction in Filament 3 Table Actions

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Integrate comments into your Filament 3 tables by adding `CommentsTableAction` to the `actions` array. This allows users to interact with comments directly from the table.

```php
use Kirschbaum\Commentions\Filament\Actions\CommentsTableAction;

->actions([
    CommentsTableAction::make()
        ->mentionables(User::all())
])
```

--------------------------------

### Register Custom Comment Model in Config

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Specifies the custom `Comment` model to be used by the Commentions package.

```php
// config/commentions.php
'comment' => [
    'model' => \App\Models\Comment::class,
],
```

--------------------------------

### Embed CommentsEntry in Filament Infolist

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Embed a full comment thread within a Filament resource's infolist using the `CommentsEntry` component. Configure mentionables, pagination, polling, and TipTap CSS.

```php
use Filament\u0002Infolists\u0002Components\u0002Section;
use Kirschbaum\u0002Commentions\u0002Filament\u0002Infolists\u0002Components\u0002CommentsEntry;

// In your Filament resource ViewPage or infolist() method:
public function infolist(Infolist $infolist): Infolist
{
    return $infolist->schema([
        Section::make('Comments')        // Filament 3 — use schema(); Filament 4 — use components()
            ->schema([
                CommentsEntry::make('comments')
                    ->mentionables(fn (Model $record) => User::all())
                    ->perPage(8)
                    ->loadMoreIncrementsBy(8)
                    ->loadMoreLabel('Load older comments')
                    ->poll('30s')
                    ->tipTapCssClasses('prose max-w-none focus:outline-none p-4'),
            ]),
    ]);
}
```

--------------------------------

### Add SubscriptionTableAction in Filament 3 Table Actions

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

For Filament 3, use `SubscriptionTableAction` within the `actions` array of your table to manage comment subscriptions on a per-record basis.

```php
use Kirschbaum\Commentions\Filament\Actions\SubscriptionTableAction;

// In table actions (Filament 3)
->actions([
    SubscriptionTableAction::make(),
])
```

--------------------------------

### Implement getCommenterName for Commenter Name

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Implement the `getCommenterName` method to customize commenter names. This method provides an alternative to implementing the `HasName` interface.

```php
use Kirschbaum\Commentions\Contracts\Commenter;

class User extends Model implements Commenter
{
    public function getCommenterName(): string
    {
        return (string) '#' . $this->id . ' - ' . $this->name;
    }
}
```

--------------------------------

### Custom Comment Model with Relationships and Scopes

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Extends the base `Comment` model to add custom relationships and query scopes.

```php
// app/Models/Comment.php
namespace App\Models;

use Kirschbaum\Commentions\Comment as BaseComment;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Comment extends BaseComment
{
    public function project(): BelongsTo
    {
        return $this->belongsTo(Project::class, 'commentable_id')
            ->where('commentable_type', Project::getMorphClass());
    }

    public function scopeInternal($query)
    {
        return $query->where('is_internal', true);
    }
}
```

--------------------------------

### Interact with Comment Model - PHP

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Access raw and parsed comment content, author details, timestamps, and reaction information. Use `isAuthor` to check if a user authored the comment. Reactions can be toggled directly on the comment object.

```php
$comment = Comment::with('reactions.reactor', 'author')->find(7);

// Reading content
$comment->getBody();           // raw TipTap HTML
$comment->getParsedBody();     // HTML with styled mention spans
$comment->body_markdown;       // Markdown string (computed attribute)
$comment->body_parsed;         // alias for getParsedBody() as attribute
$comment->getAuthorName();     // author's display name
$comment->getAuthorAvatar();   // URL or ui-avatars.com fallback
$comment->getCreatedAt();      // Carbon instance
$comment->isAuthor($user);     // bool — is $user the author?

// Mentions
$comment->getMentioned()->each(function (Commenter $user) {
    // Collection of Commenter instances referenced in body via data-id spans
    Mail::to($user)->send(new MentionMail($comment));
});

// Custom mention transformation when converting to Markdown
$markdown = $comment->getBodyMarkdown(function (string $id, string $label): string {
    return "[@{$label}](https://example.com/users/{$id})";
});

// Reactions
$comment->toggleReaction('👍');   // adds or removes the reaction for auth user
$comment->reactions;              // HasMany relation
```

--------------------------------

### Render Custom Items in Comment List - PHP

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Integrate non-comment entries, such as status changes, into the comment thread by overriding the `getComments()` method on a `Commentable` model. Merge `RenderableComment` objects with actual comments.

```php
use Kirschbaum\Commentions\RenderableComment;
use Illuminate\Support\Collection;

class Project extends Model implements Commentable
{
    use HasComments;

    public function getComments(?int $limit = null): Collection
    {
        $history = $this->statusHistory()->with('user')->get()
            ->map(fn (StatusHistory $h) => new RenderableComment(
                id:          'status-' . $h->id,
                authorName:  $h->user->name,
                body:        "Status changed: {$h->old_status} → {$h->new_status}",
                authorAvatar: $h->user->avatar_url,
                createdAt:   $h->created_at,
                updatedAt:   $h->created_at,
                isComment:   false,           // hides edit/delete/reaction controls
                label:       'Status Update', // badge shown in comment header
            ));

        $comments = $this->commentsQuery()->get();

        $merged = $history->merge($comments)->sortByDesc(
            fn ($item) => $item->getCreatedAt()
        );

        return $limit ? $merged->take($limit) : $merged;
    }
}
```

--------------------------------

### Add SubscriptionAction in Filament 4 Record Actions

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

For Filament 4, use `SubscriptionAction` within the `recordActions` array of your table to manage comment subscriptions for each record.

```php
use Kirschbaum\Commentions\Filament\Actions\SubscriptionAction;

// In record actions (Filament 4)
->recordActions([
    SubscriptionAction::make(),
])
```

--------------------------------

### Provide Deep-Link URL for Email CTA

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Configures a custom URL resolver for comment links within email notifications.

```php
// AppServiceProvider::boot() — provide a deep-link URL for the email CTA
use Kirschbaum\Commentions\Config;

Config::resolveCommentUrlUsing(fn (Comment $comment) =>
    route('filament.admin.resources.projects.view', $comment->commentable)
    . '#comment-' . $comment->getId()
);
```

--------------------------------

### Customize TipTap Editor CSS Classes with Actions

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Override TipTap editor CSS classes when using `CommentsAction` by applying the `tipTapCssClasses()` method.

```php
use Kirschbaum\Commentions\Filament\Actions\CommentsAction;

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

--------------------------------

### Register Custom Comment Policy in Config

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Specifies the custom `CommentPolicy` to be used by the Commentions package.

```php
// config/commentions.php
'comment' => [
    'model'  => \Kirschbaum\Commentions\Comment::class,
    'policy' => \App\Policies\CommentPolicy::class,
],
```

--------------------------------

### Disable Subscription Sidebar in Filament Action

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Use the `disableSidebar()` method on the `CommentsAction` to remove the subscription sidebar functionality from Filament record actions. Ensure the `CommentsAction` is correctly instantiated and configured with mentionables.

```php
use Kirschbaum\Commentions\Filament\Actions\CommentsAction;

->recordActions([
    CommentsAction::make()
        ->mentionables(User::all())
        ->disableSidebar()
])
```

--------------------------------

### ToggleCommentReaction Action

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Allows toggling an emoji reaction on a comment for a specific user. It validates the reaction, applies it, and dispatches an event.

```APIDOC
## ToggleCommentReaction — React to a Comment

**Toggle an emoji reaction on a comment for a specific user**

Validates the reaction against the configured allow-list, toggles it, and dispatches `CommentWasReactedEvent`.

```php
use Kirschbaum\Commentions\Actions\ToggleCommentReaction;
use Kirschbaum\Commentions\Comment;

$comment = Comment::find(3);
$user    = auth()->user();

// Adds reaction if not present, removes it if already present
ToggleCommentReaction::run($comment, '❤️', $user);

// Load the reaction summary manually
$summary = $comment->reactions()
    ->get()
    ->groupBy('reaction')
    ->map(fn ($group) => [
        'emoji'   => $group->first()->reaction,
        'count'   => $group->count(),
        'mine'    => $group->contains('reactor_id', $user->getKey()),
    ]);
// [['emoji' => '❤️', 'count' => 1, 'mine' => true], ...]
```
```

--------------------------------

### Custom Comment Policy for Create, Update, Delete

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Extends the base `CommentPolicy` to define custom authorization logic for comment actions.

```php
// app/Policies/CommentPolicy.php
namespace App\Policies;

use Kirschbaum\Commentions\Comment;
use Kirschbaum\Commentions\Contracts\Commenter;
use Kirschbaum\Commentions\Policies\CommentPolicy as Base;

class CommentPolicy extends Base
{
    public function create(Commenter $user): bool
    {
        // Only active, verified users may post
        return $user->is_active && $user->hasVerifiedEmail();
    }

    public function update($user, Comment $comment): bool
    {
        // Author can edit within 15 minutes of posting
        return $comment->isAuthor($user)
            && $comment->created_at->gt(now()->subMinutes(15));
    }

    public function delete($user, Comment $comment): bool
    {
        // Admins can always delete; authors can delete their own
        return $user->isAdmin() || $comment->isAuthor($user);
    }
}
```

--------------------------------

### Toggle Comment Reaction - PHP

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Use the `ToggleCommentReaction` action to add or remove an emoji reaction for a specific user on a comment. The action validates the reaction and dispatches an event. Manually load reaction summaries if needed.

```php
use Kirschbaum\Commentions\Actions\ToggleCommentReaction;
use Kirschbaum\Commentions\Comment;

$comment = Comment::find(3);
$user    = auth()->user();

// Adds reaction if not present, removes it if already present
ToggleCommentReaction::run($comment, '❤️', $user);

// Load the reaction summary manually
$summary = $comment->reactions()
    ->get()
    ->groupBy('reaction')
    ->map(fn ($group) => [
        'emoji'   => $group->first()->reaction,
        'count'   => $group->count(),
        'mine'    => $group->contains('reactor_id', $user->getKey()),
    ]);
// [['emoji' => '❤️', 'count' => 1, 'mine' => true], ...]
```

--------------------------------

### Standalone Livewire Comments Component

Source: https://context7.com/kirschbaum-development/commentions/llms.txt

Embed comments outside of Filament panels using the Livewire component. Supports Livewire 3 (:: prefix) and Livewire 4 (. prefix). Configure record, mentionables, polling, pagination, and sidebar visibility.

```blade
{{-- Livewire 3 --}}
<livewire:commentions::comments
    :record="$project"
    :mentionables="$users"
    polling-interval="20s"
    :paginate="true"
    :per-page="10"
    :sidebar-enabled="true"
    :show-subscribers="true"
/>

{{-- Livewire 4 --}}
<livewire:commentions.comments
    :record="$project"
    :mentionables="$users"
    :sidebar-enabled="false"
/>
```

--------------------------------

### Resolve Comment URL

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Optionally provide a URL resolver function to generate links to comments, useful for email notifications. This function receives a Comment object and should return a URL.

```php
use Kirschbaum\Commentions\Config;

Config::resolveCommentUrlUsing(function (\Kirschbaum\Commentions\Comment $comment) {
    // Return a URL to view the record and scroll to the comment
    return route('projects.show', $comment->commentable) . '#comment-' . $comment->getId();
});
```

--------------------------------

### Render Non-Comments in Comment List

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

Override the `getComments` method in your model to include custom objects, like status history, in the comment list. Map your custom data to `RenderableComment` instances.

```php
use Kirschbaum\Commentions\RenderableComment;

public function getComments(?int $limit = null): 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();

    $mergedCollection = $statusHistory->merge($comments);

    if ($limit) {
        return $mergedCollection->take($limit);
    }

    return $mergedCollection;
}
```

--------------------------------

### Add CommentsAction in Filament 4 Record Actions

Source: https://github.com/kirschbaum-development/commentions/blob/main/README.md

For Filament 4, use `CommentsAction` within the `recordActions` array of your table to provide comment functionality for each record.

```php
use Kirschbaum\Commentions\Filament\Actions\CommentsAction;

->recordActions([
    CommentsAction::make()
        ->mentionables(User::all())
])
```