Bot Detect Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add the package via Composer:

   composer require vipx/bot-detect-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Vipx\BotDetectBundle\VipxBotDetectBundle::class => ['all' => true],
   ];
   

2. Basic Usage Inject the BotDetect service into a controller or service:

   use Vipx\BotDetect\BotDetect;
   
   public function __construct(private BotDetect $botDetect) {}
   
   public function checkRequest(Request $request): bool
   {
       return $this->botDetect->isBot($request);
   }
   

3. First Use Case: Block Bots from Forms Use middleware or a controller to block bot submissions:

   public function submitForm(Request $request)
   {
       if ($this->botDetect->isBot($request)) {
           return new Response('Bot detected. Access denied.', 403);
       }
       // Proceed with form handling...
   }
   

Implementation Patterns

Common Workflows

1. Request-Based Detection Attach the BotDetect service to middleware for global bot checks:

   namespace App\Http\Middleware;
   
   use Vipx\BotDetect\BotDetect;
   
   class BotDetectionMiddleware
   {
       public function __construct(private BotDetect $botDetect) {}
   
       public function handle(Request $request, Closure $next)
       {
           if ($this->botDetect->isBot($request)) {
               return new Response('Bot detected.', 403);
           }
           return $next($request);
       }
   }
   

   Register in app/Http/Kernel.php:

   protected $middleware = [
       // ...
       \App\Http\Middleware\BotDetectionMiddleware::class,
   ];
   

2. Conditional Logic Use detection results to modify behavior (e.g., rate-limiting, CAPTCHA enforcement):

   if ($this->botDetect->isBot($request)) {
       $this->addCaptchaToForm();
   }
   

3. Custom Bot Lists Extend the default bot list by overriding the service configuration:

   # config/packages/vipx_bot_detect.yaml
   vipx_bot_detect:
       bot_list: ['%kernel.project_dir%/config/bots_custom.txt']
   

4. Event-Driven Integration Dispatch events when bots are detected (e.g., logging, analytics):

   use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
   
   public function __construct(
       private BotDetect $botDetect,
       private EventDispatcherInterface $dispatcher
   ) {}
   
   public function handleRequest(Request $request)
   {
       if ($this->botDetect->isBot($request)) {
           $this->dispatcher->dispatch(new BotDetectedEvent($request));
       }
   }
   

Gotchas and Tips

Pitfalls

1. Outdated Bot Lists The package was last updated in 2018, so the bot list may not include modern crawlers (e.g., AI-driven scrapers). Supplement with:

   • Common Crawler User-Agents
   • Custom regex patterns in bot_list.

2. False Positives Some legitimate services (e.g., Slack, Discord webhooks) may be flagged. Whitelist them:

   $this->botDetect->addWhitelist(['Slackbot', 'Discordbot']);
   

3. Performance Overhead Avoid running detection on every request if unused. Scope checks to critical endpoints (e.g., forms, APIs).

4. Configuration Quirks

   • The bot_list config expects absolute paths to text files (one bot per line).
   • Default config is in config/packages/vipx_bot_detect.yaml. Override carefully.

Debugging Tips

1. Log Detected Bots Add debug output to verify detection:

   if ($this->botDetect->isBot($request)) {
       $this->logger->debug('Detected bot:', [
           'user_agent' => $request->headers->get('User-Agent'),
           'ip' => $request->getClientIp(),
       ]);
   }
   

2. Test with Known Bots Use tools like User-Agent Switcher to simulate bot requests during development.

3. Extend Detection Logic Override the BotDetect service to add custom rules:

   // src/Service/CustomBotDetect.php
   use Vipx\BotDetect\BotDetect as BaseBotDetect;
   
   class CustomBotDetect extends BaseBotDetect
   {
       public function isBot(Request $request): bool
       {
           if ($this->isKnownBot($request)) {
               return true;
           }
           // Add custom logic (e.g., check for suspicious headers)
           return false;
       }
   }
   

   Register the service in services.yaml:

   services:
       Vipx\BotDetect\BotDetect: '@App\Service\CustomBotDetect'
   

4. Handle Edge Cases

   • Missing User-Agent: Some bots omit headers. Add a fallback:

     $userAgent = $request->headers->get('User-Agent', '');
     if (empty($userAgent)) {
         return true; // Assume bot if no UA
     }
     

   • IP-Based Detection: Combine with IP reputation services (e.g., AbuseIPDB).

Extension Points

1. Custom Bot Patterns Extend the BotDetect class to support regex-based detection:

   public function addCustomPattern(string $pattern): void
   {
       $this->customPatterns[] = $pattern;
   }
   

2. Integration with Security Layers Pair with Symfony’s Firewall or AccessControl to block bots at the infrastructure level:

   # config/packages/security.yaml
   security:
       access_control:
           - { path: ^/admin, roles: ROLE_USER, bot_detected: false }
   

3. Rate-Limiting Bots Use the BotDetectedEvent to trigger rate-limiting:

   $this->dispatcher->dispatch(new BotDetectedEvent($request));
   // Listen for the event to apply rate limits
   

4. Analytics Integration Track bot attempts in tools like Google Analytics or custom dashboards:

   if ($this->botDetect->isBot($request)) {
       $this->analytics->track('bot_detected', [
           'path' => $request->getPathInfo(),
           'user_agent' => $request->headers->get('User-Agent'),
       ]);
   }