Spamguard Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require inigopascall/spamguard
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="InigoPascall\Spamguard\SpamguardServiceProvider" --tag="spamguard-config"
   

2. Basic Usage Add the Spamguard middleware to your form request route:

   Route::post('/contact', [ContactController::class, 'store'])
       ->middleware('spamguard');
   

3. First Test Submit a form with a known spam pattern (e.g., test@example.com as email). The middleware will block it if configured.

Where to Look First

• Config File: config/spamguard.php (default rules, thresholds, and exceptions).
• Middleware: app/Http/Middleware/Spamguard.php (customize logic if needed).
• Tests: Review tests/ for edge cases (e.g., false positives/negatives).

First Use Case: Simple Form Protection

// In ContactController.php
public function store(Request $request) {
    $request->validate([...]);

    // Spamguard runs automatically via middleware.
    // If blocked, returns 429 Too Many Requests.
    return response()->json(['success' => true]);
}

Implementation Patterns

1. Rule-Based Filtering

Leverage built-in rules (e.g., email, ip, user_agent) or extend them:

// config/spamguard.php
'rules' => [
    'email' => [
        'patterns' => ['test@example.com', 'spam@domain.com'],
        'max_attempts' => 3,
    ],
    'ip' => [
        'blocked_ips' => ['192.168.1.100'],
    ],
],

2. Custom Rules

Create a custom rule class:

// app/Rules/CustomSpamRule.php
use InigoPascall\Spamguard\Rules\SpamguardRule;

class CustomSpamRule extends SpamguardRule {
    public function passes($attribute, $value) {
        return !str_contains(strtolower($value), 'free offer');
    }
}

Register it in config/spamguard.php:

'rules' => [
    'custom' => [
        'class' => \App\Rules\CustomSpamRule::class,
        'fields' => ['message'],
    ],
],

3. Integration with Forms

• Laravel Collective: Add spamguard to $middleware in FormRequest:

  public function rules() {
      return [...];
  }
  
  public function authorize() {
      return true;
  }
  
  public function middleware() {
      return ['spamguard'];
  }
  

• Livewire/Alpine: Use AJAX with 429 handling:

  form.submit(e => {
      e.preventDefault();
      fetch('/submit', { method: 'POST', body: formData })
          .then(res => {
              if (res.status === 429) showSpamWarning();
          });
  });
  

4. Logging and Analytics

Enable logging in config/spamguard.php:

'log_blocked_attempts' => true,

View logs in storage/logs/laravel.log or integrate with a monitoring tool.

Gotchas and Tips

Pitfalls

1. False Positives

   • Test with real user data before deployment. Adjust max_attempts or whitelist IPs/emails.
   • Example: A legitimate user might trigger email rules if they reuse a test address.

2. Performance Overhead

   • Avoid overloading rules (e.g., regex on large text fields). Use fields to target specific inputs:

     'rules' => [
         'message' => [
             'patterns' => ['/spam keywords/i'],
         ],
     ],
     

3. Middleware Order

   • Place spamguard before throttle or validate to avoid unnecessary processing:

     Route::post('/contact', [...])
         ->middleware(['spamguard', 'throttle:10']);
     

4. Rate-Limiting Quirks

   • The package uses Laravel’s tooManyAttempts response. Customize it in app/Exceptions/Handler.php:

     public function render($request, Throwable $exception) {
         if ($exception instanceof \Illuminate\Cache\RateLimitingException) {
             return response('Spam detected. Try again later.', 429);
         }
         return parent::render($request, $exception);
     }
     

Debugging Tips

• Check Blocked Attempts Run php artisan spamguard:clear to reset test data. Inspect the spamguard table (if using database storage):

  SELECT * FROM spamguard_attempts WHERE field='email' AND value='test@example.com';
  

• Disable Rules Temporarily Set 'enabled' => false in config/spamguard.php for testing.

• Custom Responses Override the middleware response:

  // app/Http/Middleware/Spamguard.php
  public function handle($request, Closure $next) {
      if ($this->isSpam($request)) {
          return response()->json(['error' => 'Custom spam message'], 429);
      }
      return $next($request);
  }
  

Extension Points

1. Database Storage Configure storage in config/spamguard.php to use database instead of cache:

   'storage' => 'database',
   

   Run migrations:

   php artisan migrate
   

2. Event Listeners Listen for spamguard.blocked events to trigger actions (e.g., email alerts):

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       \InigoPascall\Spamguard\Events\SpamBlocked::class => [
           \App\Listeners\LogSpamAttempt::class,
       ],
   ];
   

3. API Integration Use the package’s Spamguard facade directly in controllers:

   use InigoPascall\Spamguard\Facades\Spamguard;
   
   if (Spamguard::isSpam($request)) {
       abort(429);
   }