Darvin Bot Detector Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require darvinstudio/darvin-bot-detector-bundle
   

   Enable the bundle in config/bundles.php:

   DarvinStudio\DarvinBotDetectorBundle\DarvinBotDetectorBundle::class => ['all' => true],
   

2. Configuration Publish the default config (if needed) and update config/packages/darvin_bot_detector.yaml:

   darvin_bot_detector:
       enabled: true
       user_agents: ['bot1', 'bot2']  # Customize bot detection patterns
   

3. First Use Case Detect bots in a controller:

   use DarvinStudio\DarvinBotDetectorBundle\Detector\BotDetector;
   
   class MyController extends AbstractController
   {
       public function index(BotDetector $detector)
       {
           if ($detector->isBot()) {
               return $this->json(['message' => 'Bot detected!'], 403);
           }
           // Normal logic for humans
       }
   }
   

Implementation Patterns

Core Workflows

1. Request-Based Detection Inject BotDetector into controllers/services to check requests:

   if ($detector->isBot()) {
       // Block, log, or redirect
   }
   

2. Event Listeners Use Symfony events (e.g., kernel.request) to globally block bots:

   // src/EventListener/BotBlocker.php
   public function onKernelRequest(GetResponseEvent $event)
   {
       if ($event->isMasterRequest() && $this->detector->isBot()) {
           $event->setResponse(new Response('Forbidden', 403));
       }
   }
   

3. Custom User-Agent Rules Extend detection logic via config or a custom detector:

   # config/packages/darvin_bot_detector.yaml
   darvin_bot_detector:
       user_agents:
           - 'Googlebot'
           - 'Bingbot'
           - 'CustomBotPattern'
   

Integration Tips

• Symfony Security Component Integrate with AccessControl or Voter for granular permissions:

  public function decide(AdvanceVote $vote)
  {
      if ($vote->getToken()->getUser() === null && $this->detector->isBot()) {
          return AccessDeniedException::create();
      }
      return AccessDenied::NO;
  }
  

• Logging Log bot attempts for analytics:

  if ($detector->isBot()) {
      $this->logger->warning('Bot detected', ['user_agent' => $request->headers->get('User-Agent')]);
  }
  

• Performance Cache detection results if checking repeatedly (e.g., in loops):

  $cache = $this->cache->get('bot_detected_' . $request->getClientIp());
  if ($cache === null) {
      $cache = $detector->isBot();
      $this->cache->set('bot_detected_' . $request->getClientIp(), $cache, 3600);
  }
  

Gotchas and Tips

Pitfalls

1. Outdated Codebase

   • Last release in 2017: Test thoroughly for compatibility with modern Symfony (5.4+/6.x).
   • May lack support for newer HTTP standards (e.g., HTTP/2, modern User-Agent formats).

2. Limited Customization

   • No built-in whitelisting (e.g., allowing specific bots like Googlebot).
   • User-Agent matching is regex-based; edge cases (e.g., spoofed headers) may slip through.

3. No Rate Limiting

   • Bundle doesn’t include brute-force protection. Combine with symfony/security or nelmio/cors for extra safety.

4. Configuration Overrides

   • Default config may not align with your needs. Always validate user_agents patterns.

Debugging

• Verify User-Agent Headers Check if headers are correctly passed:

  $userAgent = $request->headers->get('User-Agent');
  dump($userAgent); // Debug missing/empty values
  

• Test Edge Cases

  • Spoofed User-Agents (e.g., Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)).
  • Mobile bots or non-standard clients.

• Log False Positives/Negatives Use a logger to track misclassifications:

  $this->logger->debug('Bot detection result', [
      'is_bot' => $detector->isBot(),
      'user_agent' => $request->headers->get('User-Agent'),
      'ip' => $request->getClientIp(),
  ]);
  

Extension Points

1. Custom Detector Service Override the default detector:

   # config/services.yaml
   DarvinStudio\DarvinBotDetectorBundle\Detector\BotDetector:
       arguments:
           $userAgents: ['%kernel.debug% ? "DevBot" : []'] # Dynamic logic
   

2. Event-Driven Extensions Dispatch custom events when bots are detected:

   // src/Event/BotDetectedEvent.php
   class BotDetectedEvent extends Event
   {
       public function __construct(private string $userAgent) {}
       public function getUserAgent(): string { return $this->userAgent; }
   }
   

   Trigger in BotDetector or a listener.

3. Database-Backed Rules Store/load bot patterns from a database:

   $botPatterns = $this->botPatternRepository->findAll();
   $detector = new BotDetector($botPatterns);
   

Performance Quirks

• Regex Compilation Pre-compile regex patterns if performance is critical:

  $pattern = '/Googlebot/i'; // Pre-compile in a service constructor
  

• Avoid Overhead Skip detection for non-sensitive routes or trusted IPs:

  if (!$this->security->isGranted('ROLE_TRUSTED_IP') && $detector->isBot()) {
      // Block
  }