Merge pull request #45 from kirschbaum-development/issue-10-subscribed-users

ISSUE-10: Implement comment subscription feature with event dispatching

Author: navneetrai

.gitignore

@@ -4,5 +4,5 @@ node_modules
 .pint.cache
 .repomix/output
 .cursor/rules/local.mdc
-
+.idea
 **/.claude/settings.local.json

README.md

@@ -103,7 +103,7 @@ use Kirschbaum\Commentions\Filament\Actions\CommentsAction;
     CommentsAction::make()
         ->mentionables(User::all())
 ])
-````
+```
 
 3. Or as a header action:
 
@@ -120,6 +120,100 @@ protected function getHeaderActions(): array
 }
 ```
 
+### Subscription Management
+
+Commentions includes a subscription system that allows users to subscribe to receive notifications when new comments are added to a commentable resource.
+
+#### Subscription Actions
+
+You can add subscription actions to your Filament resources:
+
+```php
+use Kirschbaum\Commentions\Filament\Actions\SubscriptionAction;
+
+// In header actions
+protected function getHeaderActions(): array
+{
+    return [
+        SubscriptionAction::make(),
+    ];
+}
+
+// In table actions (Filament 3)
+->actions([
+    SubscriptionTableAction::make(),
+])
+
+// In record actions (Filament 4)
+->recordActions([
+    SubscriptionAction::make(),
+])
+```
+
+#### Subscription Sidebar
+
+When using comments in modals, a subscription sidebar is automatically displayed showing:
+- Subscribe/unsubscribe button for the current user
+- List of users currently subscribed to the commentable
+- Real-time updates when subscription status changes
+
+##### Livewire options
+
+When using the `commentions::comments` Livewire component directly, you can control the sidebar and its contents via component properties:
+
+- `sidebarEnabled` (bool, default: true): toggles the entire subscription sidebar
+- `showSubscribers` (bool, default: `config('commentions.subscriptions.show_subscribers', true)`): toggles the subscribers list within the sidebar
+
+Examples:
+
+```php
+// Hide the sidebar entirely
+<livewire:commentions::comments :record="$record" :sidebar-enabled="false" />
+
+// Keep the sidebar, but hide the subscribers list (uses config default if omitted)
+<livewire:commentions::comments :record="$record" :show-subscribers="false" />
+```
+
+Inside the component/template you can also rely on these computed properties:
+
+- `canSubscribe`: whether the current user can subscribe
+- `isSubscribed`: whether the current user is subscribed to the current record
+- `subscribers`: a collection of current subscribers
+
+The component exposes a `toggleSubscription()` action which subscribes/unsubscribes the current user.
+
+#### Disabling the Subscription Sidebar
+
+You can disable the subscription sidebar if you don't want subscription functionality:
+
+```php
+use Kirschbaum\Commentions\Filament\Actions\CommentsAction;
+
+->recordActions([
+    CommentsAction::make()
+        ->mentionables(User::all())
+        ->disableSidebar()
+])
+```
+
+#### Subscription Methods
+
+The `HasComments` trait provides methods for managing subscriptions programmatically:
+
+```php
+// Subscribe a user
+$commentable->subscribe($user);
+
+// Unsubscribe a user
+$commentable->unsubscribe($user);
+
+// Check if a user is subscribed
+$isSubscribed = $commentable->isSubscribed($user);
+
+// Get all subscribers
+$subscribers = $commentable->getSubscribers();
+```
+
 ***
 
 ### Configuration
@@ -322,12 +416,38 @@ return [
 
 ### Events
 
-Two events are dispatched when a comment is created or reacted to:
+Events are dispatched when a comment is created, reacted to, or when users are mentioned or subscribed:
 
 - `Kirschbaum\Commentions\Events\UserWasMentionedEvent`
+- `Kirschbaum\Commentions\Events\UserIsSubscribedToCommentableEvent`
 - `Kirschbaum\Commentions\Events\CommentWasCreatedEvent`
 - `Kirschbaum\Commentions\Events\CommentWasReactedEvent`
 
+#### Subscription Events
+
+When a new comment is created, all subscribed users receive notifications through the `UserIsSubscribedToCommentableEvent`. You can listen to this event to send custom notifications:
+
+```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)
+        );
+    }
+}
+```
+
 ### 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.

config/commentions.php

@@ -9,6 +9,7 @@
     'tables' => [
         'comments' => 'comments',
         'comment_reactions' => 'comment_reactions',
+        'comment_subscriptions' => 'comment_subscriptions',
     ],
 
     /*
@@ -38,4 +39,22 @@
     'reactions' => [
         'allowed' => ['👍', '❤️', '😂', '😮', '😢', '🤔'],
     ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Subscriptions
+    |--------------------------------------------------------------------------
+    */
+    'subscriptions' => [
+        // When true, subscribed users will also receive the same event as mentions
+        // (UserWasMentionedEvent). When false, a distinct
+        // UserIsSubscribedToCommentableEvent will be dispatched instead.
+        'dispatch_as_mention' => false,
+        // Controls whether the subscribers list is shown in the sidebar UI
+        'show_subscribers' => true,
+        // Automatically subscribe the author when they add a comment
+        'auto_subscribe_on_comment' => true,
+        // Automatically subscribe a user when they are mentioned in a comment
+        'auto_subscribe_on_mention' => true,
+    ],
 ];

database/migrations/create_commentions_subscriptions_table.php.stub

@@ -0,0 +1,29 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up()
+    {
+        Schema::create(config('commentions.tables.comment_subscriptions', 'comment_subscriptions'), function (Blueprint $table) {
+            $table->id();
+            $table->morphs('subscribable');
+            $table->morphs('subscriber');
+            $table->timestamps();
+
+            $table->unique([
+                'subscribable_type', 'subscribable_id', 'subscriber_type', 'subscriber_id'
+            ], 'commentions_subscriptions_unique');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists(config('commentions.tables.comment_subscriptions', 'comment_subscriptions'));
+    }
+};
+
+

phpstan.neon

@@ -7,9 +7,10 @@ parameters:
         - database/
         - src/
         - tests/
-    
+
     excludePaths:
         - src/Filament/Actions/CommentsTableAction.php
+        - src/Filament/Actions/SubscriptionTableAction.php
 
     # Level 10 is the highest level
     level: 1

resources/dist/commentions.css

@@ -8,5 +8,7 @@
         :per-page="$perPage ?? 5"
         :load-more-label="$loadMoreLabel ?? 'Show more'"
         :per-page-increment="$perPageIncrement ?? null"
+        :sidebar-enabled="$sidebarEnabled ?? true"
+        :show-subscribers="$showSubscribers ?? true"
     />
 </div>

resources/views/comments-modal.blade.php

@@ -1,16 +1,18 @@
 @use('\Kirschbaum\Commentions\Config')
 
-<div class="comm:space-y-2" x-data="{ wasFocused: false }">
-    @if (Config::resolveAuthenticatedUser()?->can('create', Config::getCommentModel()))
-        <form wire:submit.prevent="save" x-cloak>
-            {{-- tiptap editor --}}
-            <div class="comm:relative tip-tap-container comm:mb-2" x-on:click="wasFocused = true" wire:ignore>
-                <div
-                    x-data="editor(@js($commentBody), @js($this->mentions), 'comments')"
-                >
-                    <div x-ref="element"></div>
+<div class="comm:flex comm:gap-4 comm:h-full" x-data="{ wasFocused: false }">
+    {{-- Main Comments Area --}}
+    <div class="comm:flex-1 comm:space-y-2">
+        @if (Config::resolveAuthenticatedUser()?->can('create', Config::getCommentModel()))
+            <form wire:submit.prevent="save" x-cloak>
+                {{-- tiptap editor --}}
+                <div class="comm:relative tip-tap-container comm:mb-2" x-on:click="wasFocused = true" wire:ignore>
+                    <div
+                        x-data="editor(@js($commentBody), @js($this->mentions), 'comments')"
+                    >
+                        <div x-ref="element"></div>
+                    </div>
                 </div>
-            </div>
 
             <template x-if="wasFocused">
                 <div>
@@ -30,13 +32,22 @@
         </form>
     @endif
 
-    <livewire:commentions::comment-list
-        :record="$record"
-        :mentionables="$this->mentions"
-        :polling-interval="$pollingInterval"
-        :paginate="$paginate ?? true"
-        :per-page="$perPage ?? 5"
-        :load-more-label="$loadMoreLabel ?? 'Show more'"
-        :per-page-increment="$perPageIncrement ?? null"
-    />
+        <livewire:commentions::comment-list
+            :record="$record"
+            :mentionables="$this->mentions"
+            :polling-interval="$pollingInterval"
+            :paginate="$paginate ?? true"
+            :per-page="$perPage ?? 5"
+            :load-more-label="$loadMoreLabel ?? 'Show more'"
+            :per-page-increment="$perPageIncrement ?? null"
+        />
+    </div>
+
+    {{-- Subscription Sidebar --}}
+    @if ($this->canSubscribe && $this->resolvedSidebarEnabled)
+        <livewire:commentions::subscription-sidebar
+            :record="$record"
+            :show-subscribers="$this->resolvedShowSubscribers"
+        />
+    @endif
 </div>

resources/views/comments.blade.php

@@ -0,0 +1,90 @@
+<div class="comm:w-48 comm:flex-shrink-0 comm:pl-2 comm:ml-2">
+    <div class="comm:sticky comm:top-4">
+        <div class="comm:bg-gray-50 comm:dark:bg-gray-800 comm:rounded-lg comm:p-4 comm:border comm:border-gray-200 comm:dark:border-gray-700">
+            <div class="comm:flex comm:items-center comm:gap-2 comm:mb-3">
+                <x-filament::icon
+                    icon="heroicon-o-bell"
+                    class="comm:w-4 comm:h-4 comm:text-gray-700 comm:dark:text-gray-300"
+                />
+                <h3 class="comm:text-sm comm:font-bold comm:text-gray-900 comm:dark:text-gray-100">
+                    Notifications
+                </h3>
+            </div>
+
+            @if ($this->isSubscribed)
+                <x-filament::button
+                    wire:click="toggleSubscription"
+                    wire:target="toggleSubscription"
+                    wire:loading.attr="disabled"
+                    color="gray"
+                    size="xs"
+                    class="comm:w-full comm:mb-2"
+                >
+                    <x-filament::icon
+                        icon="heroicon-s-bell-slash"
+                        class="comm:w-3 comm:h-3 comm:mr-1"
+                    />
+                    Unsubscribe
+                </x-filament::button>
+            @else
+                <x-filament::button
+                    wire:click="toggleSubscription"
+                    wire:target="toggleSubscription"
+                    wire:loading.attr="disabled"
+                    color="gray"
+                    size="xs"
+                    class="comm:w-full comm:mb-2"
+                >
+                    <x-filament::icon
+                        icon="heroicon-o-bell"
+                        class="comm:w-3 comm:h-3 comm:mr-1"
+                    />
+                    Subscribe
+                </x-filament::button>
+            @endif
+
+            {{-- Subscribers List --}}
+            @if ($showSubscribers && $this->subscribers->isNotEmpty())
+                <div class="comm:border-t comm:border-gray-200 comm:dark:border-gray-600 comm:pt-3">
+                    <div class="comm:flex comm:items-center comm:gap-2 comm:mb-3">
+                        <x-filament::icon
+                            icon="heroicon-o-users"
+                            class="comm:w-4 comm:h-4 comm:text-gray-700 comm:dark:text-gray-300"
+                        />
+                        <span class="comm:text-sm comm:font-bold comm:text-gray-900 comm:dark:text-gray-100">
+                            Subscribers ({{ $this->subscribers->count() }})
+                        </span>
+                    </div>
+                    <div class="comm:space-y-1">
+                        @foreach ($this->subscribers->take(5) as $subscriber)
+                            <div class="comm:flex comm:items-center comm:gap-2">
+                                @if ($subscriber instanceof \Filament\Models\Contracts\HasAvatar && $subscriber->getFilamentAvatarUrl())
+                                    <img 
+                                        src="{{ $subscriber->getFilamentAvatarUrl() }}" 
+                                        alt="{{ $subscriber->name }}"
+                                        class="comm:w-4 comm:h-4 comm:rounded-full comm:object-cover comm:flex-shrink-0"
+                                    />
+                                @else
+                                    <div class="comm:w-4 comm:h-4 comm:rounded-full comm:bg-gray-300 comm:dark:bg-gray-600 comm:flex-shrink-0 comm:flex comm:items-center comm:justify-center">
+                                        <span class="comm:text-xs comm:font-medium comm:text-gray-600 comm:dark:text-gray-300">
+                                            {{ substr($subscriber->name, 0, 1) }}
+                                        </span>
+                                    </div>
+                                @endif
+                                <span class="comm:text-xs comm:text-gray-600 comm:dark:text-gray-400 comm:truncate">
+                                    {{ $subscriber->name }}
+                                </span>
+                            </div>
+                        @endforeach
+                        @if ($this->subscribers->count() > 5)
+                            <div class="comm:text-xs comm:text-gray-500 comm:dark:text-gray-400 comm:pl-6">
+                                +{{ $this->subscribers->count() - 5 }} more
+                            </div>
+                        @endif
+                    </div>
+                </div>
+            @endif
+        </div>
+    </div>
+</div>
+