Akismet Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add the package via Composer:

   composer require benji07/akismet-bundle
   

   Enable the bundle in config/bundles.php:

   Benji07\AkismetBundle\Benji07AkismetBundle::class => ['all' => true],
   

2. Configure Akismet Add your Akismet API key and blog URL in config/packages/benji_akismet.yaml:

   benji_akismet:
       key: 'your_akismet_api_key'
       blog: 'https://your-site.com'
   

3. First Use Case: Spam Detection Inject the Akismet service into a controller or service:

   use Benji07\AkismetBundle\Akismet\Akismet;
   
   public function __construct(private Akismet $akismet) {}
   
   public function checkComment(Comment $comment)
   {
       $data = [
           'user_ip' => $comment->getUserIp(),
           'user_agent' => $comment->getUserAgent(),
           'referrer' => $comment->getReferrer(),
           'comment_type' => 'comment',
           'comment_author' => $comment->getUsername(),
           'comment_author_email' => $comment->getEmail(),
           'comment_content' => $comment->getContent(),
       ];
   
       return $this->akismet->isSpam($data);
   }
   

Implementation Patterns

Common Workflows

1. Spam Detection in Forms Use the isSpam() method to validate user-submitted content (e.g., comments, contact forms):

   public function store(Request $request)
   {
       $data = $this->mapFormData($request);
       if ($this->akismet->isSpam($data)) {
           return back()->with('error', 'Spam detected!');
       }
       // Save to DB
   }
   

2. Feedback Loop for False Positives/Negatives Submit spam/ham feedback to improve Akismet’s model:

   // After manual review
   if ($comment->isSpam) {
       $this->akismet->submitSpam($data);
   } else {
       $this->akismet->submitHam($data);
   }
   

3. Event-Driven Integration Trigger Akismet checks via Symfony events (e.g., kernel.request):

   // src/EventListener/AkismetListener.php
   public function onKernelRequest(GetResponseEvent $event)
   {
       if ($event->isMainRequest() && $event->getRequest()->isMethod('POST')) {
           $data = $this->extractFormData($event->getRequest());
           if ($this->akismet->isSpam($data)) {
               $event->setResponse(new Response('Spam blocked', 403));
           }
       }
   }
   

4. Caching Responses Cache Akismet results to reduce API calls (e.g., using Symfony’s cache system):

   $cacheKey = 'akismet_' . md5($comment->getContent());
   $isSpam = $this->cache->get($cacheKey);
   if ($isSpam === null) {
       $isSpam = $this->akismet->isSpam($data);
       $this->cache->set($cacheKey, $isSpam, '1 hour');
   }
   

Gotchas and Tips

Pitfalls

1. API Key Validation

   • The bundle does not validate the API key on configuration load. Test the connection early:

     try {
         $this->akismet->verifyKey();
     } catch (\Exception $e) {
         throw new \RuntimeException('Invalid Akismet API key');
     }
     

2. Rate Limits

   • Akismet enforces rate limits. Cache responses aggressively or implement exponential backoff for retries.

3. Missing Fields

   • isSpam() requires all fields (e.g., user_ip, comment_content). Omit optional fields (e.g., referrer) but avoid passing null:

     $data = array_filter([
         'user_ip' => $comment->getUserIp(),
         'comment_content' => $comment->getContent(),
         // 'referrer' => null, // Skip instead of passing null
     ]);
     

4. Symfony 4+ Deprecations

   • The bundle targets Symfony 2/3. For Symfony 4+, ensure autowiring is configured in config/services.yaml:

     services:
         Benji07\AkismetBundle\Akismet\Akismet: ~
     

Debugging Tips

1. Enable Verbose Logging Configure Monolog to log Akismet requests/responses:

   # config/packages/monolog.yaml
   handlers:
       akismet:
           type: stream
           path: "%kernel.logs_dir%/akismet.log"
           level: debug
           channels: ["akismet"]
   

   Then enable the channel in the bundle’s service.

2. Test Locally Use Akismet’s sandbox API for testing:

   benji_akismet:
       key: 'your_sandbox_key'
       blog: 'http://example.com'
   

Extension Points

1. Custom Data Mappers Create a decorator to transform data before sending to Akismet:

   // src/Service/AkismetDataMapper.php
   class AkismetDataMapper implements DataMapperInterface
   {
       public function map($entity): array
       {
           $data = [
               'user_ip' => $entity->getIp(),
               'comment_content' => $entity->getContent(),
           ];
           // Add custom logic (e.g., sanitize content)
           return $data;
       }
   }
   

2. Override HTTP Client Replace the default Guzzle client for custom headers/proxies:

   benji_akismet:
       client:
           options:
               headers:
                   'X-Custom-Header': 'value'
               proxy: 'http://proxy.example.com'
   

3. Add Custom Fields Extend the bundle’s configuration to support additional Akismet fields (e.g., user_role):

   // src/DependencyInjection/Benji07AkismetExtension.php
   public function load(array $configs, ContainerBuilder $container)
   {
       $container->setParameter('akismet.custom_fields', ['user_role']);
   }