Kickbox Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require andi/kickbox-bundle
   

   Add the bundle to config/bundles.php (Symfony 4+) or app/AppKernel.php (Symfony 2/3):

   Andi\KickBoxBundle\AndiKickBoxBundle::class => ['all' => true],
   

2. Configuration: Add your Kickbox API key(s) to config/packages/andi_kick_box.yaml:

   andi_kick_box:
       api_keys:
           default:
               key: "%env(KICKBOX_API_KEY)%"
       default_api_name: default
   

3. First Use Case: Verify an email in a controller:

   use Andi\KickBoxBundle\Client\KickboxClient;
   
   public function verifyEmail(Request $request, KickboxClient $kickbox)
   {
       $email = $request->get('email');
       $response = $kickbox->verify($email);
   
       return new JsonResponse($response->getResult());
   }
   

Implementation Patterns

Common Workflows

1. Email Validation Middleware:

   // app/Http/Middleware/ValidateEmail.php
   public function handle($request, Closure $next)
   {
       if ($request->is('register') && !$request->hasValidatedEmail()) {
           $kickbox = app(KickboxClient::class);
           $response = $kickbox->verify($request->email);
   
           if (!$response->isSuccess() || $response->getResult() === 'undeliverable') {
               throw new \Exception('Invalid email address');
           }
       }
       return $next($request);
   }
   

2. Batch Processing:

   public function bulkVerify(array $emails)
   {
       $results = [];
       foreach ($emails as $email) {
           $results[$email] = app(KickboxClient::class)->verify($email)->getResult();
       }
       return $results;
   }
   

3. Service Integration:

   • User Registration:

     public function register(UserRequest $request)
     {
         $response = app(KickboxClient::class)->verify($request->email);
         if ($response->getResult() === 'deliverable') {
             $user = User::create($request->validated());
             return response()->json(['success' => true]);
         }
         return response()->json(['error' => 'Email invalid'], 400);
     }
     

   • Mailing List Cleanup:

     public function cleanMailingList()
     {
         $emails = MailingList::all()->pluck('email');
         $invalid = collect($emails)->filter(function($email) {
             return app(KickboxClient::class)->verify($email)->getResult() !== 'deliverable';
         });
         MailingList::whereIn('email', $invalid)->delete();
     }
     

4. Caching Responses:

   public function verifyWithCache($email, $ttl = 86400)
   {
       $cacheKey = "kickbox_{$email}";
       if (cache()->has($cacheKey)) {
           return cache()->get($cacheKey);
       }
       $response = app(KickboxClient::class)->verify($email);
       cache()->put($cacheKey, $response, $ttl);
       return $response;
   }
   

Gotchas and Tips

Pitfalls

1. API Key Management:

   • Hardcoding API keys in config/ violates security best practices. Use environment variables (%env(KICKBOX_API_KEY)%) or Laravel's .env.
   • Rotate API keys periodically and update the config accordingly.

2. Rate Limiting:

   • Kickbox has strict rate limits. Exceeding limits (e.g., >100 requests/minute) will return 429 Too Many Requests.
   • Solution: Implement exponential backoff or queue delayed requests:

     use Illuminate\Support\Facades\Queue;
     
     Queue::later(now()->addSeconds(10), function() use ($email) {
         app(KickboxClient::class)->verify($email);
     });
     

3. Deprecated Bundle:

   • The package is archived (last release: 2015) and lacks Symfony 5+ support. Expect compatibility issues with modern Laravel/Symfony.
   • Workaround: Fork the repo and update dependencies (e.g., guzzlehttp/guzzle:^7.0).

4. Response Handling:

   • The isSuccess() method checks HTTP status, but business logic (e.g., deliverable vs. risky) requires manual checks:

     if ($response->getResult() === 'undeliverable') {
         // Block registration
     } elseif ($response->getResult() === 'risky') {
         // Flag for review
     }
     

5. Timeouts:

   • Default timeout is 6 seconds (6000ms). Slow responses (e.g., large lists) may fail.
   • Tip: Increase timeout for bulk operations:

     $response = $kickbox->verify($email, 10000); // 10-second timeout
     

Debugging Tips

1. Enable Guzzle Debugging: Add to config/services.php:

   'guzzle' => [
       'debug' => env('APP_DEBUG', false),
   ],
   

   Check logs for raw API responses during failures.

2. Mocking for Tests: Use Laravel’s MockHttp to simulate API responses:

   $this->mock(KickboxClient::class)->shouldReceive('verify')
       ->once()
       ->andReturn((object) ['result' => 'deliverable']);
   

3. Common Errors:

   • KickBoxApiException: HTTP errors (e.g., 401 Unauthorized, 404 Not Found).
     • Fix: Verify API key and endpoint in config/andi_kick_box.yaml.
   • ConnectionException: Network issues.
     • Fix: Check proxy settings or firewall rules.

Extension Points

1. Custom Response Handling: Extend the Response class to add domain-specific logic:

   namespace App\Services;
   
   use Andi\KickBoxBundle\Response\KickboxResponse;
   
   class EnhancedKickboxResponse extends KickboxResponse
   {
       public function isValidForNewsletter()
       {
           return $this->getResult() === 'deliverable' && !$this->isDisposable();
       }
   }
   

   Bind it in AppServiceProvider:

   $this->app->bind(KickboxResponse::class, function ($app) {
       return new EnhancedKickboxResponse($app->make('kickbox_client')->verify('test@example.com'));
   });
   

2. Queue Failed Requests: Retry failed verifications using Laravel Queues:

   public function verifyWithRetry($email, int $retries = 3)
   {
       try {
           return app(KickboxClient::class)->verify($email);
       } catch (\Exception $e) {
           if ($retries > 0) {
               Queue::push(new VerifyEmailJob($email, $retries - 1));
           }
           throw $e;
       }
   }
   

3. Webhook Integration: Use Kickbox’s webhooks to sync real-time updates:

   Route::post('/kickbox-webhook', function (Request $request) {
       $payload = $request->json()->all();
       // Update local records based on $payload['result']
   });