Hipaway Mandrill Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require hipaway-travel/mandrill-bundle:dev-master
   

   Enable the bundle in config/bundles.php:

   Hip\MandrillBundle\HipMandrillBundle::class => ['all' => true],
   

2. Configuration: Add Mandrill API key to config/packages/hip_mandrill.yaml:

   hip_mandrill:
       api_key: '%env(MANDRILL_API_KEY)%'
   

   Ensure MANDRILL_API_KEY is in your .env file.

3. First Use Case: Create a message class (e.g., src/Message/WelcomeEmail.php):

   namespace App\Message;
   
   use Hip\MandrillBundle\Message\MandrillMessage;
   
   class WelcomeEmail extends MandrillMessage
   {
       public function __construct()
       {
           $this->setSubject('Welcome to Our App!');
           $this->setFromEmail('noreply@example.com');
           $this->setFromName('Our App');
           $this->setTo(['user@example.com' => 'User Name']);
           $this->setHtml('<h1>Hello!</h1><p>Welcome aboard.</p>');
       }
   }
   

   Dispatch it in a controller:

   use Hip\MandrillBundle\MandrillManager;
   
   public function sendWelcomeEmail(MandrillManager $mandrill)
   {
       $message = new WelcomeEmail();
       $mandrill->send($message);
   }
   

Implementation Patterns

Core Workflows

1. Message Creation: Extend Hip\MandrillBundle\Message\MandrillMessage and override methods like:

   • setSubject(), setFromEmail(), setTo(), setHtml(), setText().
   • Use setHeaders() for custom headers (e.g., Reply-To).
   • Attach files with addAttachment().

2. Dynamic Messages: Use dependency injection to pass dynamic data:

   $message = new WelcomeEmail($user->getEmail(), $user->getName());
   

   Then inject via constructor in WelcomeEmail:

   public function __construct(string $email, string $name)
   {
       $this->setTo([$email => $name]);
       $this->setHtml($this->renderHtml($name));
   }
   

3. Templates: Use Mandrill templates by setting:

   $this->setTemplateName('welcome-template');
   $this->setTemplateContent([
       'name' => 'User Name',
       'app_name' => 'Our App',
   ]);
   

4. Async Sending: Queue messages with Symfony Messenger (if integrated):

   $message = new WelcomeEmail();
   $dispatcher->dispatch(new SendMandrillMessage($message));
   

Integration Tips

• Validation: Validate Mandrill API responses in a custom event subscriber:

  use Hip\MandrillBundle\Event\MessageSentEvent;
  
  public function onMessageSent(MessageSentEvent $event)
  {
      if (!$event->isSuccess()) {
          $this->logger->error('Mandrill error: ' . $event->getError());
      }
  }
  

• Logging: Enable debug mode in config/packages/hip_mandrill.yaml:

  hip_mandrill:
      debug: '%kernel.debug%'
  

• Testing: Mock MandrillManager in tests:

  $this->mockBuilder->getMockBuilder(MandrillManager::class)
      ->disableOriginalConstructor()
      ->getMock();
  

Gotchas and Tips

Pitfalls

1. API Key Exposure:

   • Never hardcode MANDRILL_API_KEY in config files. Always use .env.
   • Restrict the API key to specific IPs in Mandrill’s settings if possible.

2. Rate Limits:

   • Mandrill has strict rate limits. Test in staging with realistic volumes.
   • Handle 429 Too Many Requests errors gracefully:

     try {
         $mandrill->send($message);
     } catch (MandrillException $e) {
         if ($e->getCode() === 429) {
             sleep(30); // Retry after 30 seconds
             $mandrill->send($message);
         }
     }
     

3. Template Caching:

   • Mandrill templates are cached. Clear cache in Mandrill dashboard if changes don’t reflect.

4. Character Encoding:

   • Ensure setHtml() and setText() use UTF-8 encoding to avoid corruption in emails.

Debugging

• Enable Verbose Logging: Add to config/packages/monolog.yaml:

  handlers:
      hip_mandrill:
          type: stream
          path: "%kernel.logs_dir%/hip_mandrill.log"
          level: debug
  

• Check Raw API Response: Extend MandrillManager to log raw responses:

  public function send(MandrillMessage $message)
  {
      $response = $this->client->messages->send($message->toArray(), true);
      $this->logger->debug('Mandrill raw response:', ['response' => $response]);
      return $response;
  }
  

Extension Points

1. Custom Message Classes: Override Hip\MandrillBundle\Message\MandrillMessage to add domain-specific methods:

   class PasswordResetEmail extends MandrillMessage
   {
       public function setResetLink(string $link): self
       {
           $this->setHtml($this->renderHtml($link));
           return $this;
       }
   }
   

2. Event Listeners: Subscribe to hip_mandrill.message_sent event to post-process messages:

   public static function getSubscribedEvents()
   {
       return [
           'hip_mandrill.message_sent' => 'onMessageSent',
       ];
   }
   

3. Custom Transport: Replace the default Guzzle client by binding a custom MandrillClient service:

   # config/services.yaml
   Hip\MandrillBundle\MandrillManager:
       arguments:
           $client: '@custom_mandrill.client'
   

4. Batch Sending: Use Mandrill’s batch API for bulk emails:

   $batch = new Hip\MandrillBundle\Message\MandrillBatch();
   $batch->addMessage($message1);
   $batch->addMessage($message2);
   $mandrill->sendBatch($batch);