feat: ticket watchers, fulltext search, single-query pagination, watcher notifications

Ticket watchers:
- api/watch_ticket.php: GET (watch state) + POST (watch/unwatch toggle)
- index.php: route for /api/watch_ticket.php
- TicketView: WATCH/UNWATCH button with live state fetch and toggle
- NotificationHelper::notifyWatchers(): fetches watchers from DB, resolves
  Matrix IDs via Synapse, fires notification to watchers + global list
- add_comment.php, update_ticket.php: call notifyWatchers on comment and
  status-change events respectively

Fulltext search:
- TicketModel::hasFulltextIndex(): detects FULLTEXT index via information_schema
- getAllTickets(): uses MATCH...AGAINST when fulltext index exists, LIKE fallback
  when not yet applied — zero-downtime rollout

Single-query pagination:
- getAllTickets() replaces separate COUNT + SELECT with COUNT(*) OVER() window
  function — one round trip to DB per page load instead of two

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

api/add_comment.php

@@ -144,6 +144,13 @@ try {
             NotificationHelper::sendCommentNotification($ticketId, $ticketTitle, $commentText, $authorDisplay);
         }
 
+        // Notify watchers of the new comment
+        NotificationHelper::notifyWatchers(
+            $conn, $ticketId, $ticketTitle, 'comment_added',
+            ['author' => $authorDisplay, 'preview' => mb_strimwidth($commentText, 0, 200, '…')],
+            (int)$userId
+        );
+
         // Add mentioned users to result for frontend
         $result['mentions'] = array_map(function($u) {
             return $u['username'];

api/update_ticket.php

@@ -54,6 +54,7 @@ try {
 
     // Updated controller class that handles partial updates
     class ApiTicketController {
+        private $conn;
         private $ticketModel;
         private $commentModel;
         private $auditLog;
@@ -63,6 +64,7 @@ try {
         private $currentUser;
 
         public function __construct($conn, $userId = null, $isAdmin = false, $currentUser = []) {
+            $this->conn = $conn;
             $this->ticketModel = new TicketModel($conn);
             $this->commentModel = new CommentModel($conn);
             $this->auditLog = new AuditLogModel($conn);
@@ -208,7 +210,7 @@ try {
                 }
             }
 
-            // Notify on status change
+            // Notify on status change (global notify list + watchers)
             if ($currentTicket['status'] !== $updateData['status']) {
                 $changedBy = $this->currentUser['display_name'] ?? $this->currentUser['username'] ?? null;
                 NotificationHelper::sendStatusChangeNotification(
@@ -218,6 +220,14 @@ try {
                     $updateData['title'],
                     $changedBy
                 );
+                NotificationHelper::notifyWatchers(
+                    $this->conn,
+                    $id,
+                    $updateData['title'],
+                    'status_changed',
+                    ['old_status' => $currentTicket['status'], 'new_status' => $updateData['status'], 'changed_by' => $changedBy],
+                    (int)$this->userId
+                );
             }
 
             return [

api/watch_ticket.php

@@ -0,0 +1,100 @@
+<?php
+/**
+ * Watch / Unwatch Ticket API
+ *
+ * GET  ?ticket_id=N  → returns { watching: bool, watcher_count: int }
+ * POST { ticket_id, action: 'watch'|'unwatch' } → toggles watcher row
+ */
+require_once __DIR__ . '/bootstrap.php';
+require_once dirname(__DIR__) . '/models/TicketModel.php';
+
+$ticketId = isset($_GET['ticket_id'])
+    ? (int)$_GET['ticket_id']
+    : (isset($data['ticket_id']) ? (int)$data['ticket_id'] : 0);
+
+if ($_SERVER['REQUEST_METHOD'] === 'POST') {
+    $data     = json_decode(file_get_contents('php://input'), true) ?? [];
+    $ticketId = (int)($data['ticket_id'] ?? 0);
+    $action   = $data['action'] ?? '';
+
+    if ($ticketId <= 0 || !in_array($action, ['watch', 'unwatch'], true)) {
+        http_response_code(400);
+        echo json_encode(['success' => false, 'error' => 'Invalid parameters']);
+        exit;
+    }
+
+    $ticketModel = new TicketModel($conn);
+    $ticket = $ticketModel->getTicketById($ticketId);
+    if (!$ticket || !$ticketModel->canUserAccessTicket($ticket, $currentUser)) {
+        http_response_code(404);
+        echo json_encode(['success' => false, 'error' => 'Ticket not found']);
+        exit;
+    }
+
+    if ($action === 'watch') {
+        $stmt = $conn->prepare(
+            "INSERT IGNORE INTO ticket_watchers (ticket_id, user_id) VALUES (?, ?)"
+        );
+        $stmt->bind_param("ii", $ticketId, $userId);
+        $stmt->execute();
+        $stmt->close();
+    } else {
+        $stmt = $conn->prepare(
+            "DELETE FROM ticket_watchers WHERE ticket_id = ? AND user_id = ?"
+        );
+        $stmt->bind_param("ii", $ticketId, $userId);
+        $stmt->execute();
+        $stmt->close();
+    }
+
+    // Return updated state
+    $countStmt = $conn->prepare(
+        "SELECT COUNT(*) as cnt FROM ticket_watchers WHERE ticket_id = ?"
+    );
+    $countStmt->bind_param("i", $ticketId);
+    $countStmt->execute();
+    $count = (int)$countStmt->get_result()->fetch_assoc()['cnt'];
+    $countStmt->close();
+
+    echo json_encode([
+        'success'       => true,
+        'watching'      => $action === 'watch',
+        'watcher_count' => $count,
+    ]);
+    exit;
+}
+
+// GET — return current watch state for this user
+if ($_SERVER['REQUEST_METHOD'] !== 'GET') {
+    http_response_code(405);
+    echo json_encode(['success' => false, 'error' => 'Method not allowed']);
+    exit;
+}
+
+if ($ticketId <= 0) {
+    http_response_code(400);
+    echo json_encode(['success' => false, 'error' => 'ticket_id required']);
+    exit;
+}
+
+$watchingStmt = $conn->prepare(
+    "SELECT COUNT(*) as cnt FROM ticket_watchers WHERE ticket_id = ? AND user_id = ?"
+);
+$watchingStmt->bind_param("ii", $ticketId, $userId);
+$watchingStmt->execute();
+$watching = (bool)$watchingStmt->get_result()->fetch_assoc()['cnt'];
+$watchingStmt->close();
+
+$countStmt = $conn->prepare(
+    "SELECT COUNT(*) as cnt FROM ticket_watchers WHERE ticket_id = ?"
+);
+$countStmt->bind_param("i", $ticketId);
+$countStmt->execute();
+$count = (int)$countStmt->get_result()->fetch_assoc()['cnt'];
+$countStmt->close();
+
+echo json_encode([
+    'success'       => true,
+    'watching'      => $watching,
+    'watcher_count' => $count,
+]);

helpers/NotificationHelper.php

@@ -136,6 +136,63 @@ class NotificationHelper {
         ]);
     }
 
+    /**
+     * Notify all watchers of a ticket about an update event.
+     *
+     * Fetches watchers from the DB, resolves their Matrix IDs via Synapse,
+     * and fires the appropriate event notification with them in notify_users.
+     *
+     * @param \mysqli     $conn
+     * @param string|int  $ticketId
+     * @param string      $ticketTitle
+     * @param string      $event        One of: status_changed, comment_added, assigned
+     * @param array       $extraData    Merged into the payload (old_status/new_status, author, etc.)
+     * @param int|null    $excludeUserId  Don't notify the actor themselves
+     */
+    public static function notifyWatchers(\mysqli $conn, $ticketId, string $ticketTitle, string $event, array $extraData = [], ?int $excludeUserId = null): void {
+        $webhookUrl = $GLOBALS['config']['MATRIX_WEBHOOK_URL'] ?? null;
+        $domain     = $GLOBALS['config']['MATRIX_DOMAIN']      ?? null;
+        if (!$webhookUrl || !$domain) {
+            return;
+        }
+
+        // Fetch watcher usernames
+        $sql  = "SELECT u.username FROM ticket_watchers tw JOIN users u ON tw.user_id = u.user_id WHERE tw.ticket_id = ?";
+        $stmt = $conn->prepare($sql);
+        $stmt->bind_param("i", $ticketId);
+        $stmt->execute();
+        $result = $stmt->get_result();
+        $stmt->close();
+
+        $usernames = [];
+        while ($row = $result->fetch_assoc()) {
+            $usernames[] = $row['username'];
+        }
+
+        if (empty($usernames)) {
+            return;
+        }
+
+        // Resolve to Matrix IDs — skip users without Synapse accounts
+        $matrixIds = SynapseHelper::resolveUsernames($usernames);
+        if (empty($matrixIds)) {
+            return;
+        }
+
+        // Remove the global notify list duplicates and build payload
+        $allNotify = array_unique(array_merge($matrixIds, self::notifyUsers()));
+
+        $payload = array_merge($extraData, [
+            'event'        => $event,
+            'ticket_id'    => $ticketId,
+            'title'        => $ticketTitle,
+            'url'          => UrlHelper::ticketUrl($ticketId),
+            'notify_users' => array_values($allNotify),
+        ]);
+
+        self::fire($payload);
+    }
+
     /**
      * Ticket assigned (or reassigned) to a user.
      *

index.php

@@ -119,6 +119,10 @@ switch (true) {
         require_once 'api/get_comments.php';
         break;
 
+    case $requestPath == '/api/watch_ticket.php':
+        require_once 'api/watch_ticket.php';
+        break;
+
     case $requestPath == '/api/assign_ticket.php':
         require_once 'api/assign_ticket.php';
         break;

models/TicketModel.php

@@ -77,13 +77,21 @@ class TicketModel {
             $paramTypes .= str_repeat('s', count($types));
         }
 
-        // Search Functionality
+        // Search Functionality — use FULLTEXT when available, fall back to LIKE
         if ($search && !empty($search)) {
-            $whereConditions[] = "(title LIKE ? OR description LIKE ? OR ticket_id LIKE ? OR category LIKE ? OR type LIKE ?)";
+            if ($this->hasFulltextIndex()) {
+                // MATCH...AGAINST for indexed full-text search (much faster at scale)
+                $whereConditions[] = "(MATCH(t.title, t.description) AGAINST (? IN BOOLEAN MODE) OR t.ticket_id LIKE ? OR t.category LIKE ? OR t.type LIKE ?)";
+                $searchTerm = "%$search%";
+                $params = array_merge($params, [$search . '*', $searchTerm, $searchTerm, $searchTerm]);
+                $paramTypes .= 'ssss';
+            } else {
+                $whereConditions[] = "(t.title LIKE ? OR t.description LIKE ? OR t.ticket_id LIKE ? OR t.category LIKE ? OR t.type LIKE ?)";
                 $searchTerm = "%$search%";
                 $params = array_merge($params, [$searchTerm, $searchTerm, $searchTerm, $searchTerm, $searchTerm]);
                 $paramTypes .= 'sssss';
             }
+        }
 
         // Advanced search filters
         // Date range - created_at
@@ -166,53 +174,44 @@ class TicketModel {
         // Validate sort direction
         $sortDirection = strtolower($sortDirection) === 'asc' ? 'ASC' : 'DESC';
 
-        // Get total count for pagination
+        // Single query: use COUNT(*) OVER() window function to get total + page in one pass
-        $countSql = "SELECT COUNT(*) as total FROM tickets t $whereClause";
-        $countStmt = $this->conn->prepare($countSql);
-
-        if (!empty($params)) {
-            $countStmt->bind_param($paramTypes, ...$params);
-        }
-
-        $countStmt->execute();
-        $totalResult = $countStmt->get_result();
-        $totalTickets = $totalResult->fetch_assoc()['total'];
-
-        // Get tickets with pagination and creator info
         $sql = "SELECT t.*,
                 u_created.username as creator_username,
                 u_created.display_name as creator_display_name,
                 u_assigned.username as assigned_username,
-                u_assigned.display_name as assigned_display_name
+                u_assigned.display_name as assigned_display_name,
+                COUNT(*) OVER() as _total_count
                 FROM tickets t
                 LEFT JOIN users u_created ON t.created_by = u_created.user_id
                 LEFT JOIN users u_assigned ON t.assigned_to = u_assigned.user_id
                 $whereClause
                 ORDER BY $sortExpression $sortDirection
                 LIMIT ? OFFSET ?";
-        $stmt = $this->conn->prepare($sql);
 
-        // Add limit and offset parameters
         $params[] = $limit;
         $params[] = $offset;
         $paramTypes .= 'ii';
 
+        $stmt = $this->conn->prepare($sql);
         if (!empty($params)) {
             $stmt->bind_param($paramTypes, ...$params);
         }
-        
         $stmt->execute();
         $result = $stmt->get_result();
 
         $tickets     = [];
+        $totalTickets = 0;
         while ($row = $result->fetch_assoc()) {
+            $totalTickets = (int)$row['_total_count'];
+            unset($row['_total_count']);
             $tickets[] = $row;
         }
+        $stmt->close();
 
         return [
             'tickets' => $tickets,
             'total' => $totalTickets,
-            'pages' => ceil($totalTickets / $limit),
+            'pages' => $totalTickets > 0 ? ceil($totalTickets / $limit) : 0,
             'current_page' => $page
         ];
     }
@@ -701,4 +700,24 @@ class TicketModel {
         $stmt->close();
         return $result;
     }
+
+    /**
+     * Check whether the FULLTEXT index on tickets(title, description) exists.
+     * Result is cached for the process lifetime (static).
+     */
+    private function hasFulltextIndex(): bool {
+        static $result = null;
+        if ($result !== null) {
+            return $result;
+        }
+        $r = $this->conn->query(
+            "SELECT COUNT(*) as cnt FROM information_schema.STATISTICS
+             WHERE table_schema = DATABASE()
+               AND table_name = 'tickets'
+               AND index_type = 'FULLTEXT'
+               AND index_name = 'ft_title_description'"
+        );
+        $result = $r && (int)$r->fetch_assoc()['cnt'] > 0;
+        return $result;
+    }
 }

views/TicketView.php

@@ -132,6 +132,8 @@ include __DIR__ . '/layout_header.php';
         </option>
       <?php endforeach ?>
     </select>
+    <button type="button" id="watchButton" class="lt-btn lt-btn-ghost lt-btn-sm"
+            title="Watch this ticket to receive Matrix notifications on updates">WATCH</button>
     <button type="button" id="editButton" class="lt-btn lt-btn-primary lt-btn-sm">EDIT</button>
     <button type="button" id="cloneButton" class="lt-btn lt-btn-sm">CLONE</button>
     <a id="exportFullBtn"
@@ -768,6 +770,49 @@ document.addEventListener('DOMContentLoaded', function () {
         });
     }
 
+    // Watch / Unwatch button
+    var watchBtn = document.getElementById('watchButton');
+    if (watchBtn) {
+        var _watching = false;
+        // Fetch initial state
+        lt.api.get('/api/watch_ticket.php?ticket_id=' + window.ticketData.ticket_id)
+            .then(function (d) {
+                if (d.success) {
+                    _watching = d.watching;
+                    watchBtn.textContent = _watching ? 'UNWATCH' : 'WATCH';
+                    watchBtn.title = _watching
+                        ? 'You are watching this ticket. Click to stop.'
+                        : 'Watch this ticket for Matrix notifications on updates.';
+                    if (_watching) watchBtn.classList.add('lt-btn-active');
+                }
+            })
+            .catch(function () {});
+
+        watchBtn.addEventListener('click', function () {
+            var action = _watching ? 'unwatch' : 'watch';
+            watchBtn.disabled = true;
+            lt.api.post('/api/watch_ticket.php', { ticket_id: window.ticketData.ticket_id, action: action })
+                .then(function (d) {
+                    if (d.success) {
+                        _watching = d.watching;
+                        watchBtn.textContent = _watching ? 'UNWATCH' : 'WATCH';
+                        watchBtn.title = _watching
+                            ? 'You are watching this ticket. Click to stop.'
+                            : 'Watch this ticket for Matrix notifications on updates.';
+                        watchBtn.classList.toggle('lt-btn-active', _watching);
+                        lt.toast.success(_watching ? 'Watching ticket' : 'Stopped watching ticket');
+                    } else {
+                        lt.toast.error('Failed: ' + (d.error || 'Unknown error'));
+                    }
+                    watchBtn.disabled = false;
+                })
+                .catch(function () {
+                    lt.toast.error('Failed to update watch status');
+                    watchBtn.disabled = false;
+                });
+        });
+    }
+
     // Add comment button
     var addCommentBtn = document.getElementById('addCommentBtn');
     if (addCommentBtn) {