easystream/docs/COMMENTS.md

Enhanced Comment System

Threaded comments with reactions, mentions, and moderation features.

Features

• 💬 Threaded Replies - Nested comment threads (up to 5 levels deep)
• 👍 Reactions - Like, heart, laugh, thinking, sad, angry
• 📢 Mentions - Tag users with @username
• 📌 Pinned Comments - Video owners can pin top comments
• ✏️ Edit Support - Edit comments with edit indicator
• 🛡️ Moderation - Approve, reject, delete, flag comments
• 🔔 Notifications - Get notified when mentioned
• 🔢 Reaction Counts - Cached aggregated counts for performance

Database Setup

docker-compose exec db mysql -u easystream -peasystream easystream < __install/migrations/006_enhance_comments.sql

API Endpoints

List Comments (Threaded)

GET /api/comments_enhanced.php?action=list&video_id=123&sort=top&limit=50&offset=0

Sort options: top (most reactions), newest, oldest

Response:

{
  "success": true,
  "comments": [
    {
      "comment_id": 1,
      "usr_user": "john",
      "comment": "Great video! @mary check this out",
      "depth": 0,
      "is_pinned": 1,
      "is_edited": 0,
      "like_count": 42,
      "total_reactions": 55,
      "reply_count": 3,
      "replies": [...]
    }
  ]
}

Post Comment/Reply

POST /api/comments_enhanced.php?action=post
Content-Type: application/json

{
  "video_id": 123,
  "comment": "Great video!",
  "parent_comment_id": null
}

Add Reaction

POST /api/comments_enhanced.php?action=react
Content-Type: application/json

{
  "comment_id": 456,
  "reaction_type": "heart"
}

Reaction types: like, heart, laugh, thinking, sad, angry

Remove Reaction

POST /api/comments_enhanced.php?action=unreact
Content-Type: application/json

{
  "comment_id": 456,
  "reaction_type": "heart"
}

Edit Comment

POST /api/comments_enhanced.php?action=edit
Content-Type: application/json

{
  "comment_id": 456,
  "comment": "Updated comment text"
}

Pin Comment

POST /api/comments_enhanced.php?action=pin
Content-Type: application/json

{
  "comment_id": 456
}

Only video owners can pin comments.

Usage

PHP Backend

require_once 'f_core/f_classes/class.comments_enhanced.php';
$comments = new VCommentsEnhanced();

// Post a comment
$comment_id = $comments->postComment($video_id, $user_id, "Great video!", $parent_id);

// Add a reaction
$comments->addReaction($comment_id, $user_id, 'like');

// Get threaded comments
$data = $comments->getThreadedComments($video_id, 50, 0, 'top');

// Pin a comment (as video owner)
$comments->pinComment($comment_id, $video_owner_id);

// Edit a comment
$comments->editComment($comment_id, $user_id, "Updated text");

// Moderate a comment
$comments->moderateComment($comment_id, $moderator_id, 'delete', 'Spam');

Features Explained

Threading

Comments support unlimited nesting, but depth is limited to 5 levels for UI/UX:

Comment (depth 0)
└─ Reply (depth 1)
   └─ Reply to reply (depth 2)
      └─ ... (up to depth 5)

Mentions

Use @username to mention users:

• System automatically detects mentions
• Creates notification for mentioned user
• Highlights mentioned users in UI

Reactions

Six reaction types with aggregated counts:

• Counts cached in db_comment_reaction_counts for performance
• One reaction per user per type
• Updating a reaction changes the type

Pinning

• Only video owners can pin comments
• Only one pinned comment per video
• Pinned comments appear first

Editing

• Users can edit their own comments
• Edited comments show "(edited)" indicator
• Edit timestamp tracked

Moderation

Actions tracked in db_comment_moderation:

• Approve - Approve pending comment
• Reject - Hide comment (not deleted)
• Delete - Permanently remove comment
• Flag - Mark for review
• Unflag - Clear flag

Performance

• Reaction counts pre-aggregated
• Top-level comments fetched separately from replies
• Indexes on video_id, parent_comment_id, is_pinned
• Depth limiting prevents deep recursion

Database Schema

db_comments (enhanced)

Added columns:

• parent_comment_id - Parent comment for threading
• depth - Nesting level (0-5)
• is_pinned - Pinned by video owner
• is_edited - Comment was edited
• edited_at - Edit timestamp

db_comment_reactions

Column	Type	Description
reaction_id	INT	Primary key
comment_id	INT	Comment ID
usr_id	INT	User who reacted
reaction_type	ENUM	like/heart/laugh/thinking/sad/angry
created_at	DATETIME	Reaction timestamp

db_comment_mentions

Column	Type	Description
mention_id	INT	Primary key
comment_id	INT	Comment with mention
mentioned_user_id	INT	User who was mentioned

db_comment_moderation

Column	Type	Description
moderation_id	INT	Primary key
comment_id	INT	Moderated comment
moderator_id	INT	Moderator user
action	ENUM	approve/reject/delete/flag/unflag
reason	TEXT	Moderation reason

Future Enhancements

• Rich text formatting (markdown)
• GIF/emoji picker
• Comment sorting (controversial, best)
• Spam detection (ML-based)
• Comment search
• User blocking
• Shadow banning
• Auto-moderation rules
• Report abuse workflow
• Moderator dashboard