Comment Mentions: Added core back-end logic

- Added new user notification preference, opt-in by default
- Added parser to extract mentions from comment HTML, with tests to
  cover.
- Added notification and notification handling

Not yet tested, needs testing coverage.

Author: ssddanbrown

app/Activity/Notifications/NotificationManager.php

@@ -6,6 +6,7 @@
 use BookStack\Activity\Models\Activity;
 use BookStack\Activity\Models\Loggable;
 use BookStack\Activity\Notifications\Handlers\CommentCreationNotificationHandler;
+use BookStack\Activity\Notifications\Handlers\CommentMentionNotificationHandler;
 use BookStack\Activity\Notifications\Handlers\NotificationHandler;
 use BookStack\Activity\Notifications\Handlers\PageCreationNotificationHandler;
 use BookStack\Activity\Notifications\Handlers\PageUpdateNotificationHandler;
@@ -48,5 +49,7 @@ public function loadDefaultHandlers(): void
         $this->registerHandler(ActivityType::PAGE_CREATE, PageCreationNotificationHandler::class);
         $this->registerHandler(ActivityType::PAGE_UPDATE, PageUpdateNotificationHandler::class);
         $this->registerHandler(ActivityType::COMMENT_CREATE, CommentCreationNotificationHandler::class);
+        $this->registerHandler(ActivityType::COMMENT_CREATE, CommentMentionNotificationHandler::class);
+        $this->registerHandler(ActivityType::COMMENT_UPDATE, CommentMentionNotificationHandler::class);
     }
 }

app/Activity/Tools/MentionParser.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace BookStack\Activity\Tools;
+
+use BookStack\Util\HtmlDocument;
+use DOMElement;
+
+class MentionParser
+{
+    public function parseUserIdsFromHtml(string $html): array
+    {
+        $doc = new HtmlDocument($html);
+
+        $ids = [];
+        $mentionLinks = $doc->queryXPath('//a[@data-mention-user-id]');
+
+        foreach ($mentionLinks as $link) {
+            if ($link instanceof DOMElement) {
+                $id = intval($link->getAttribute('data-mention-user-id'));
+                if ($id > 0) {
+                    $ids[] = $id;
+                }
+            }
+        }
+
+        return array_values(array_unique($ids));
+    }
+}

app/App/Providers/AppServiceProvider.php

@@ -3,6 +3,7 @@
 namespace BookStack\App\Providers;
 
 use BookStack\Access\SocialDriverManager;
+use BookStack\Activity\Models\Comment;
 use BookStack\Activity\Tools\ActivityLogger;
 use BookStack\Entities\Models\Book;
 use BookStack\Entities\Models\Bookshelf;
@@ -73,6 +74,7 @@ public function boot(): void
             'book'      => Book::class,
             'chapter'   => Chapter::class,
             'page'      => Page::class,
+            'comment'   => Comment::class,
         ]);
     }
 }

app/Config/setting-defaults.php

@@ -41,6 +41,7 @@
         'bookshelves_view_type' => env('APP_VIEWS_BOOKSHELVES', 'grid'),
         'bookshelf_view_type'   => env('APP_VIEWS_BOOKSHELF', 'grid'),
         'books_view_type'       => env('APP_VIEWS_BOOKS', 'grid'),
+        'notifications#comment-mentions' => true,
     ],
 
 ];

app/Settings/UserNotificationPreferences.php

@@ -26,9 +26,14 @@ public function notifyOnCommentReplies(): bool
         return $this->getNotificationSetting('comment-replies');
     }
 
+    public function notifyOnCommentMentions(): bool
+    {
+        return $this->getNotificationSetting('comment-mentions');
+    }
+
     public function updateFromSettingsArray(array $settings)
     {
-        $allowList = ['own-page-changes', 'own-page-comments', 'comment-replies'];
+        $allowList = ['own-page-changes', 'own-page-comments', 'comment-replies', 'comment-mentions'];
         foreach ($settings as $setting => $status) {
             if (!in_array($setting, $allowList)) {
                 continue;

lang/en/notifications.php

@@ -11,6 +11,8 @@
     'updated_page_subject' => 'Updated page: :pageName',
     'updated_page_intro' => 'A page has been updated in :appName:',
     'updated_page_debounce' => 'To prevent a mass of notifications, for a while you won\'t be sent notifications for further edits to this page by the same editor.',
+    'comment_mention_subject' => 'You were mentioned in a comment on :pageName',
+    'comment_mention_intro' => 'You were mentioned in a comment on :appName:',
 
     'detail_page_name' => 'Page Name:',
     'detail_page_path' => 'Page Path:',

lang/en/preferences.php

@@ -23,6 +23,7 @@
     'notifications_desc' => 'Control the email notifications you receive when certain activity is performed within the system.',
     'notifications_opt_own_page_changes' => 'Notify upon changes to pages I own',
     'notifications_opt_own_page_comments' => 'Notify upon comments on pages I own',
+    'notifications_opt_comment_mentions' => 'Notify when I\'m mentioned in a comment',
     'notifications_opt_comment_replies' => 'Notify upon replies to my comments',
     'notifications_save' => 'Save Preferences',
     'notifications_update_success' => 'Notification preferences have been updated!',

resources/views/users/account/notifications.blade.php

@@ -33,6 +33,13 @@
                                 'label' => trans('preferences.notifications_opt_comment_replies'),
                             ])
                         </div>
+                        <div>
+                            @include('form.toggle-switch', [
+                                'name' => 'preferences[comment-mentions]',
+                                'value' => $preferences->notifyOnCommentMentions(),
+                                'label' => trans('preferences.notifications_opt_comment_mentions'),
+                            ])
+                        </div>
                     @endif
                 </div>
 

tests/Activity/MentionParserTest.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace Tests\Activity;
+
+use BookStack\Activity\Tools\MentionParser;
+use Tests\TestCase;
+
+class MentionParserTest extends TestCase
+{
+    public function test_it_extracts_mentions()
+    {
+        $parser = new MentionParser();
+
+        // Test basic mention extraction
+        $html = '<p>Hello <a href="/user/5" data-mention-user-id="5">@User</a></p>';
+        $result = $parser->parseUserIdsFromHtml($html);
+        $this->assertEquals([5], $result);
+
+        // Test multiple mentions
+        $html = '<p><a data-mention-user-id="1">@Alice</a> and <a data-mention-user-id="2">@Bob</a></p>';
+        $result = $parser->parseUserIdsFromHtml($html);
+        $this->assertEquals([1, 2], $result);
+
+        // Test filtering out invalid IDs (zero and negative)
+        $html = '<p><a data-mention-user-id="0">@Invalid</a> <a data-mention-user-id="-5">@Negative</a> <a data-mention-user-id="3">@Valid</a></p>';
+        $result = $parser->parseUserIdsFromHtml($html);
+        $this->assertEquals([3], $result);
+
+        // Test non-mention links are ignored
+        $html = '<p><a href="/page/1">Normal Link</a> <a data-mention-user-id="7">@User</a></p>';
+        $result = $parser->parseUserIdsFromHtml($html);
+        $this->assertEquals([7], $result);
+
+        // Test empty HTML
+        $result = $parser->parseUserIdsFromHtml('');
+        $this->assertEquals([], $result);
+
+        // Test duplicate user IDs
+        $html = '<p><a data-mention-user-id="4">@User</a> mentioned <a data-mention-user-id="4">@User</a> again</p>';
+        $result = $parser->parseUserIdsFromHtml($html);
+        $this->assertEquals([4], $result);
+    }
+}