Laravel Stopforumspam Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require vigstudio/laravel-stopforumspam
   

   Publish the config file:

   php artisan vendor:publish --provider="Vigstudio\StopForumSpam\StopForumSpamServiceProvider" --tag="config"
   

2. Configure API Key: Edit config/stopforumspam.php and add your StopForumSpam API key.

3. First Use Case: Check an email during registration:

   use Vigstudio\StopForumSpam\Facades\StopForumSpam;
   
   $email = 'spammer@example.com';
   $result = StopForumSpam::checkEmail($email);
   
   if ($result->isSpam()) {
       abort(422, 'Email is flagged as spam.');
   }
   

Implementation Patterns

Validation Integration

Form Request Validation:

use Vigstudio\StopForumSpam\Rules\Email;
use Vigstudio\StopForumSpam\Rules\Ip;
use Vigstudio\StopForumSpam\Rules\Username;

public function rules()
{
    return [
        'email' => ['required', new Email],
        'ip' => ['required', new Ip],
        'username' => ['required', new Username],
    ];
}

Custom Rule Logic:

public function passes($attribute, $value)
{
    $result = StopForumSpam::checkEmail($value);
    return !$result->isSpam() || config('stopforumspam.allow_suspicious');
}

Workflow Patterns

1. Registration Flow:

   $user = User::create([
       'email' => $request->email,
       'username' => $request->username,
   ]);
   
   $ip = $request->ip();
   $emailResult = StopForumSpam::checkEmail($user->email);
   $ipResult = StopForumSpam::checkIp($ip);
   
   if ($emailResult->isSpam() || $ipResult->isSpam()) {
       $user->delete();
       return back()->withErrors(['spam' => 'Account blocked due to spam flags.']);
   }
   

2. Comment System:

   $comment = new Comment();
   $comment->user_id = auth()->id();
   $comment->ip = $request->ip();
   $comment->content = $request->content;
   
   $ipResult = StopForumSpam::checkIp($comment->ip);
   if ($ipResult->isSpam()) {
       return back()->with('error', 'Your IP is flagged as spam.');
   }
   

Integration Tips

• Cache Responses: Reduce API calls by caching results for 24 hours:

  $result = Cache::remember("sfspam:{$email}", now()->addHours(24), fn() =>
      StopForumSpam::checkEmail($email)
  );
  

• Rate Limiting: Use Laravel’s throttle middleware to limit API calls.
• Logging: Log blocked attempts for moderation:

  if ($result->isSpam()) {
      \Log::warning('Spam attempt detected', [
          'type' => $result->type,
          'value' => $value,
          'score' => $result->score,
      ]);
  }
  

Gotchas and Tips

Pitfalls

1. API Rate Limits:

   • StopForumSpam’s free tier has strict rate limits. Exceeding limits may temporarily block your IP.
   • Fix: Cache responses aggressively and implement local fallback checks (e.g., block known spammer IPs from a local list).

2. False Positives:

   • New or legitimate users may be flagged as "suspicious" due to shared IPs or emails.
   • Fix: Use config('stopforumspam.threshold') to adjust sensitivity (default: 50). Lower values (e.g., 30) reduce false positives but may miss spam.

3. IPv6 Support:

   • The package may not handle IPv6 addresses gracefully. Test thoroughly if your app supports IPv6.
   • Fix: Normalize IPs before checking:

     $ip = filter_var($request->ip(), FILTER_VALIDATE_IP, FILTER_FLAG_IPV4);
     

4. Username Checks:

   • StopForumSpam’s username database is less comprehensive than IP/email. Rely on it as a secondary check.
   • Fix: Combine with other rules (e.g., min:3 length, alphanumeric).

Debugging

• Enable Debug Mode: Set debug to true in config/stopforumspam.php to log raw API responses:

  'debug' => env('SFSPAM_DEBUG', false),
  

• Inspect Responses: The StopForumSpam facade returns a Vigstudio\StopForumSpam\Response object with:
  • isSpam(): Boolean.
  • score(): Numeric confidence (0–100).
  • type(): "email", "ip", or "username".
  • raw(): Full API response (for debugging).

Extension Points

1. Custom Actions: Override the default behavior by extending the StopForumSpam facade:

   StopForumSpam::extend(function ($result) {
       if ($result->score() > 70) {
           event(new SpamDetected($result));
       }
   });
   

2. Local Overrides: Whitelist/blacklist entries locally to supplement StopForumSpam:

   // config/stopforumspam.php
   'local_whitelist' => [
       'emails' => ['trusted@example.com'],
       'ips' => ['192.168.1.1'],
   ],
   

3. Async Checks: Use Laravel Queues to offload checks for performance-critical paths:

   dispatch(new CheckSpamJob($email, $ip, $username));
   

Config Quirks

• Thresholds:
  • threshold: Minimum score to trigger a block (default: 50).
  • allow_suspicious: If true, allows scores below threshold but logs them (default: false).
• API Endpoint: Override the default endpoint if needed (e.g., for self-hosted StopForumSpam instances):

  'api_url' => env('SFSPAM_API_URL', 'https://www.stopforumspam.com/api'),