357 lines
10 KiB
Markdown
357 lines
10 KiB
Markdown
# Auto-Moderation Hooks System
|
|
|
|
The SocialBase messaging system includes a powerful hooking system that allows extensions to automatically moderate messages using custom filters and AI.
|
|
|
|
## 🎯 Overview
|
|
|
|
When a message is sent, the system dispatches a `socialbase.message.moderation` event that extensions can listen to. Extensions can analyze the message and return an action to take.
|
|
|
|
## 📋 Available Actions
|
|
|
|
Extensions can return one of the following actions:
|
|
|
|
- **`flag`** - Flag the message for manual review
|
|
- **`delete`** - Automatically delete the message
|
|
- **`approve`** - Pre-approve the message
|
|
- **`keep`** or `null` - Do nothing, allow the message
|
|
|
|
## 🔧 Implementation
|
|
|
|
### Basic Example
|
|
|
|
```php
|
|
use Illuminate\Support\Facades\Event;
|
|
|
|
// In your extension's boot() method
|
|
Event::listen('socialbase.message.moderation', function ($message) {
|
|
// Analyze the message
|
|
$content = strtolower($message->content);
|
|
|
|
// Check for spam keywords
|
|
$spamKeywords = ['casino', 'viagra', 'lottery', 'winner'];
|
|
foreach ($spamKeywords as $keyword) {
|
|
if (str_contains($content, $keyword)) {
|
|
return [
|
|
'action' => 'flag',
|
|
'reason' => "Message contains spam keyword: {$keyword}",
|
|
];
|
|
}
|
|
}
|
|
|
|
// Allow the message
|
|
return ['action' => 'keep'];
|
|
});
|
|
```
|
|
|
|
### Advanced Example with AI
|
|
|
|
```php
|
|
Event::listen('socialbase.message.moderation', function ($message) {
|
|
// Use OpenAI or similar to analyze message
|
|
$analysis = analyzeMessageWithAI($message->content);
|
|
|
|
if ($analysis['is_toxic'] && $analysis['confidence'] > 0.9) {
|
|
return [
|
|
'action' => 'delete',
|
|
'reason' => 'Toxic content detected with high confidence',
|
|
];
|
|
}
|
|
|
|
if ($analysis['is_spam'] && $analysis['confidence'] > 0.7) {
|
|
return [
|
|
'action' => 'flag',
|
|
'reason' => 'Possible spam detected',
|
|
];
|
|
}
|
|
|
|
return ['action' => 'keep'];
|
|
});
|
|
```
|
|
|
|
### URL Filter Example
|
|
|
|
```php
|
|
Event::listen('socialbase.message.moderation', function ($message) {
|
|
// Check for URLs
|
|
if (preg_match('/(https?:\/\/[^\s]+)/', $message->content, $matches)) {
|
|
$url = $matches[1];
|
|
|
|
// Check against blacklist
|
|
$blacklistedDomains = ['spam-site.com', 'phishing-site.com'];
|
|
foreach ($blacklistedDomains as $domain) {
|
|
if (str_contains($url, $domain)) {
|
|
return [
|
|
'action' => 'delete',
|
|
'reason' => "Blacklisted URL: {$domain}",
|
|
];
|
|
}
|
|
}
|
|
|
|
// Flag messages with multiple URLs
|
|
$urlCount = substr_count($message->content, 'http');
|
|
if ($urlCount > 2) {
|
|
return [
|
|
'action' => 'flag',
|
|
'reason' => "Message contains {$urlCount} URLs",
|
|
];
|
|
}
|
|
}
|
|
|
|
return ['action' => 'keep'];
|
|
});
|
|
```
|
|
|
|
### Rate Limiting Example
|
|
|
|
```php
|
|
Event::listen('socialbase.message.moderation', function ($message) {
|
|
if (!$message->sender_id) {
|
|
return ['action' => 'keep']; // System messages
|
|
}
|
|
|
|
// Check messages sent in last minute
|
|
$recentMessages = \Paymenter\Extensions\Others\SocialBase\Models\Message::where('sender_id', $message->sender_id)
|
|
->where('created_at', '>', now()->subMinute())
|
|
->count();
|
|
|
|
if ($recentMessages > 10) {
|
|
return [
|
|
'action' => 'flag',
|
|
'reason' => 'User sent too many messages ({$recentMessages} in 1 minute)',
|
|
];
|
|
}
|
|
|
|
return ['action' => 'keep'];
|
|
});
|
|
```
|
|
|
|
### Content Length Filter
|
|
|
|
```php
|
|
Event::listen('socialbase.message.moderation', function ($message) {
|
|
$length = strlen($message->content);
|
|
|
|
// Flag very short messages (potential spam)
|
|
if ($length < 3) {
|
|
return [
|
|
'action' => 'flag',
|
|
'reason' => 'Message too short (possible spam)',
|
|
];
|
|
}
|
|
|
|
// Flag extremely long messages
|
|
if ($length > 5000) {
|
|
return [
|
|
'action' => 'flag',
|
|
'reason' => 'Message exceeds maximum length',
|
|
];
|
|
}
|
|
|
|
return ['action' => 'keep'];
|
|
});
|
|
```
|
|
|
|
## 🚨 User Reporting System
|
|
|
|
Users can report messages directly. When a message receives 3 or more reports, it's automatically flagged for review.
|
|
|
|
### Report a Message (For Extensions)
|
|
|
|
```php
|
|
use Paymenter\Extensions\Others\SocialBase\Helpers\MessagingHelper;
|
|
|
|
MessagingHelper::reportMessage(
|
|
messageId: 123,
|
|
reportedBy: $userId,
|
|
reason: 'spam',
|
|
description: 'This message contains unwanted advertising'
|
|
);
|
|
```
|
|
|
|
### Report Reasons
|
|
|
|
Common report reasons:
|
|
- `spam` - Unwanted or repetitive content
|
|
- `harassment` - Bullying or threatening behavior
|
|
- `inappropriate` - Offensive or adult content
|
|
- `scam` - Fraudulent or phishing attempt
|
|
- `other` - Other reason (requires description)
|
|
|
|
## 📊 Available Message Data
|
|
|
|
The `$message` object passed to the hook contains:
|
|
|
|
```php
|
|
$message->id // Message ID
|
|
$message->conversation_id // Conversation ID
|
|
$message->sender_id // Sender user ID (null for system messages)
|
|
$message->sender // Sender user object
|
|
$message->content // Message text content
|
|
$message->type // 'text' or 'system'
|
|
$message->is_system // Boolean
|
|
$message->system_type // Type if system message
|
|
$message->metadata // Additional data (array)
|
|
$message->created_at // Timestamp
|
|
$message->conversation // Conversation object with participants
|
|
```
|
|
|
|
## 🔔 Available Events
|
|
|
|
### Message Events
|
|
|
|
```php
|
|
// When a message is sent
|
|
Event::listen('socialbase.message.sent', function ($message) {
|
|
// Handle message sent
|
|
});
|
|
|
|
// When a message is reported by a user
|
|
Event::listen('socialbase.message.reported', function ($message, $report) {
|
|
// Handle message report
|
|
// $report contains: reporter, reason, description
|
|
});
|
|
|
|
// When a message is flagged for moderation
|
|
Event::listen('socialbase.message.flagged', function ($message, $flaggedBy) {
|
|
// Handle message flagged
|
|
});
|
|
|
|
// When a message is approved by moderator
|
|
Event::listen('socialbase.message.approved', function ($message, $moderatorId) {
|
|
// Handle message approved
|
|
});
|
|
|
|
// When a message is deleted by moderator
|
|
Event::listen('socialbase.message.deleted', function ($message, $moderatorId) {
|
|
// Handle message deleted
|
|
});
|
|
```
|
|
|
|
## 🎓 Best Practices
|
|
|
|
1. **Return Early** - Only return an action if you need to moderate the message
|
|
2. **Provide Reasons** - Always include a clear reason for moderation actions
|
|
3. **Don't Block Execution** - Keep your analysis fast (<100ms recommended)
|
|
4. **Log Actions** - Log your moderation decisions for debugging
|
|
5. **Test Thoroughly** - Test with various message types before deploying
|
|
6. **Avoid False Positives** - Be conservative with auto-delete actions
|
|
7. **Use Confidence Scores** - For AI-based moderation, require high confidence
|
|
|
|
## ⚙️ Configuration Example
|
|
|
|
Create a config file for your moderation extension:
|
|
|
|
```php
|
|
return [
|
|
'enabled' => true,
|
|
'auto_flag_spam' => true,
|
|
'auto_delete_toxic' => false, // Safer to flag first
|
|
'spam_keywords' => ['casino', 'viagra', 'lottery'],
|
|
'max_urls_per_message' => 2,
|
|
'min_message_length' => 3,
|
|
'max_message_length' => 2000,
|
|
'rate_limit_messages_per_minute' => 10,
|
|
];
|
|
```
|
|
|
|
## 🔒 Security Considerations
|
|
|
|
- **Never trust user input** - Always sanitize and validate
|
|
- **Rate limit API calls** - If using external AI services
|
|
- **Cache results** - Cache analysis results to avoid repeated processing
|
|
- **Monitor performance** - Track execution time of your filters
|
|
- **Fail safely** - If your filter errors, return `['action' => 'keep']`
|
|
|
|
## 📈 Example: Complete Moderation Extension
|
|
|
|
```php
|
|
namespace Paymenter\Extensions\Others\MyModerationExtension;
|
|
|
|
use App\Classes\Extension\Extension;
|
|
use Illuminate\Support\Facades\Event;
|
|
|
|
class MyModerationExtension extends Extension
|
|
{
|
|
public function boot()
|
|
{
|
|
Event::listen('socialbase.message.moderation', function ($message) {
|
|
// Skip system messages
|
|
if ($message->is_system) {
|
|
return ['action' => 'keep'];
|
|
}
|
|
|
|
$content = strtolower($message->content);
|
|
$config = $this->getConfig();
|
|
|
|
// Check spam keywords
|
|
foreach ($config['spam_keywords'] as $keyword) {
|
|
if (str_contains($content, $keyword)) {
|
|
return [
|
|
'action' => 'flag',
|
|
'reason' => "Spam keyword detected: {$keyword}",
|
|
];
|
|
}
|
|
}
|
|
|
|
// Check URL count
|
|
$urlCount = substr_count($message->content, 'http');
|
|
if ($urlCount > $config['max_urls_per_message']) {
|
|
return [
|
|
'action' => 'flag',
|
|
'reason' => "Too many URLs ({$urlCount})",
|
|
];
|
|
}
|
|
|
|
// Check message length
|
|
$length = strlen($message->content);
|
|
if ($length > $config['max_message_length']) {
|
|
return [
|
|
'action' => 'flag',
|
|
'reason' => "Message too long ({$length} characters)",
|
|
];
|
|
}
|
|
|
|
return ['action' => 'keep'];
|
|
});
|
|
}
|
|
|
|
public function getConfig($values = [])
|
|
{
|
|
return [
|
|
[
|
|
'name' => 'spam_keywords',
|
|
'type' => 'textarea',
|
|
'label' => 'Spam Keywords (one per line)',
|
|
'description' => 'Messages containing these words will be flagged',
|
|
],
|
|
[
|
|
'name' => 'max_urls_per_message',
|
|
'type' => 'number',
|
|
'label' => 'Maximum URLs per message',
|
|
'default' => 2,
|
|
],
|
|
[
|
|
'name' => 'max_message_length',
|
|
'type' => 'number',
|
|
'label' => 'Maximum message length',
|
|
'default' => 2000,
|
|
],
|
|
];
|
|
}
|
|
}
|
|
```
|
|
|
|
## 🎉 Summary
|
|
|
|
The auto-moderation hooks system allows you to:
|
|
- ✅ Automatically filter spam and toxic content
|
|
- ✅ Implement custom business rules
|
|
- ✅ Integrate AI-based content analysis
|
|
- ✅ Rate limit users
|
|
- ✅ Block malicious URLs
|
|
- ✅ Track and handle user reports
|
|
- ✅ Build sophisticated content filters without touching core code
|
|
|
|
Happy moderating! 🛡️
|
|
|