Virtnet.bond/extensions/Others/SocialBase/docs/MESSAGE_REPORTING.md

Message Reporting System

The SocialBase messaging system includes comprehensive message reporting functionality with automatic notifications.

Table of Contents

• How to Report a Message
• Notification System
• Admin Workflow
• Programmatic Usage

How to Report a Message

Using the Livewire Component

In your Blade views, you can add a report button for any message:

<livewire:socialbase.report-message :messageId="$message->id" />

This will render a "Report" button that opens a modal with:

• Reason selection (spam, harassment, inappropriate, scam, other)
• Optional description field (500 chars max)
• Submit and cancel buttons

Using PHP/Helper Method

use Paymenter\Extensions\Others\SocialBase\Helpers\MessagingHelper;

// Report a message
MessagingHelper::reportMessage(
    $messageId,           // ID of the message to report
    $reportedByUserId,    // ID of the user reporting
    'spam',               // Reason: spam, harassment, inappropriate, scam, other
    'Optional description' // Additional details (optional)
);

Notification System

When a User Reports a Message

The reporter automatically receives a confirmation message:

Subject: "Report Received - We're Reviewing It"

Content:

Thank you for reporting a message. We take all reports seriously and our moderation team will review it shortly.

Report Details:
- Reason: [Spam/Harassment/etc]
- Report ID: #123

You will receive another message once our team has reviewed your report.

Message Type: message_report_confirmation

When Admin Reviews the Report

If Report is Dismissed (No Action)

Subject: "Report Update: No Action Taken"

Content:

Thank you for your report (ID: #123).

After review, our moderation team has determined that the reported message does not violate our community guidelines. The message will remain visible.

Report Reason: [Reason]

If you believe this decision was made in error, please contact our support team.

If Action is Taken

Subject: "Report Update: Action Taken"

Content:

Thank you for your report (ID: #123).

Our moderation team has reviewed your report and taken action.

Action Taken: [The reported message has been removed/flagged/etc]
Report Reason: [Reason]

We appreciate your help in keeping our community safe and respectful.

Message Type: message_report_decision

Admin Workflow

1. Viewing Reports

Navigate to Admin → Messaging → Message Reports

The admin panel shows:

• Reporter information
• Reported message content
• Message sender
• Report reason and description
• Current status (pending/reviewed/dismissed)

2. Reviewing a Report

1. Click the edit icon on a report
2. Review the report details
3. Check the message content and context
4. Update the Status field:
   • Pending - Not yet reviewed
   • Reviewed - Action taken
   • Dismissed - No action needed
5. Optionally moderate the message itself (flag/delete/approve)
6. Click Save

3. Automatic Notifications

When you save a report with status changed from "pending":

• The reporter is automatically notified
• Notification includes action taken (based on message moderation status)
• Event socialbase.message.report_reviewed is dispatched

Programmatic Usage

Listening for Report Events

When Message is Reported

Event::listen('socialbase.message.reported', function ($report) {
    // $report->id - Report ID
    // $report->message_id - Reported message ID
    // $report->reported_by - Reporter user ID
    // $report->reason - Report reason
    // $report->description - Additional details
});

When Report is Reviewed

Event::listen('socialbase.message.report_reviewed', function ($report, $decision) {
    // $report - MessageReport model
    // $decision - 'reviewed' or 'dismissed'
    
    // Access related data
    $message = $report->message;
    $reporter = $report->reporter;
    $reviewer = $report->reviewer;
});

Auto-Flagging

Messages with 3 or more pending reports are automatically flagged for review:

// This happens automatically in MessagingService::reportMessage()
$pendingReports = MessageReport::where('message_id', $messageId)
    ->where('status', 'pending')
    ->count();

if ($pendingReports >= 3) {
    $message->update(['moderation_status' => 'flagged']);
}

Report Reasons

Available report reasons:

Reason	Description
spam	Unsolicited or repetitive messages
harassment	Abusive or threatening content
inappropriate	Content that violates guidelines
scam	Fraudulent or phishing attempts
other	Other violations not listed

Database Schema

ext_social_message_reports

Column	Type	Description
id	bigint	Primary key
message_id	bigint	FK to ext_social_messages
reported_by	bigint	FK to users
reason	string	Report reason enum
description	text	Additional details (optional)
status	string	pending/reviewed/dismissed
reviewed_by	bigint	FK to users (nullable)
reviewed_at	timestamp	When reviewed (nullable)
created_at	timestamp	When reported
updated_at	timestamp	Last modified

Best Practices

For Developers

1. Always use the helper method instead of creating reports directly
2. Don't send duplicate reports - check if user already reported before allowing
3. Include context in description field when possible
4. Respect privacy - only show necessary information to reporters

For Administrators

1. Review reports promptly to maintain user trust
2. Be consistent with moderation decisions
3. Document patterns - use moderation notes
4. Communicate clearly - notifications explain your decisions
5. Monitor auto-flagged messages - 3+ reports deserve attention

Security Considerations

• Users can only report messages in conversations they participate in
• System messages cannot be reported
• Reports are visible only to administrators with proper permissions
• Reporter identity is kept confidential from message sender
• All reports are logged for audit purposes

Permissions

Required permissions for report management:

• socialbase.reports.view - View message reports
• socialbase.reports.review - Update report status
• socialbase.reports.delete - Delete reports

Set these in Admin → Roles & Permissions → [Role] → Social Base section.

Integration Example

Adding Report Button to Custom UI

<div class="message">
    <div class="message-content">{{ $message->content }}</div>
    <div class="message-actions">
        <!-- Other actions -->
        @if(!$message->is_system && Auth::id() !== $message->sender_id)
            <livewire:socialbase.report-message :messageId="$message->id" />
        @endif
    </div>
</div>

Custom Report Handler

use Paymenter\Extensions\Others\SocialBase\Helpers\MessagingHelper;

class CustomReportHandler
{
    public function reportSpam($messageId, $userId)
    {
        // Add custom logic before reporting
        $this->logReport($userId, $messageId);
        
        // Report the message
        MessagingHelper::reportMessage(
            $messageId,
            $userId,
            'spam',
            'Automated spam detection'
        );
        
        // Add custom logic after reporting
        $this->notifyModerators($messageId);
    }
}

Troubleshooting

Reports Not Sending Notifications

1. Check that socialbase.message.reported event is dispatched
2. Verify MessagingHelper is available
3. Check logs for error messages
4. Ensure user has valid email/account

Auto-Flagging Not Working

1. Verify the reportMessage() method is being used
2. Check if message already flagged
3. Ensure at least 3 pending reports exist
4. Review logs for any errors

Report Modal Not Showing

1. Ensure Livewire is properly loaded
2. Check JavaScript console for errors
3. Verify component is registered
4. Clear cache: php artisan optimize:clear

---

For more information about the messaging system, see MESSAGING_SYSTEM.md