Mandrill Bridge Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require bengor-user/mandrill-bridge-bundle
   

   Ensure MandrillBridgeBundle is enabled in config/bundles.php:

   return [
       // ...
       BenGorUser\MandrillBridgeBundle\MandrillBridgeBundle::class => ['all' => true],
   ];
   

2. Configure Mandrill API Key Add your Mandrill API key to config/packages/mandrill_bridge.yaml (or create it):

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

3. First Use Case: Sending a Welcome Email Trigger the email in your user registration workflow (e.g., after UserBundle's onRegistrationSuccess event):

   use BenGorUser\MandrillBridgeBundle\Event\SendEmailEvent;
   
   // In your registration listener/service
   $event = new SendEmailEvent(
       $user, // User entity
       'welcome_email', // Template name (must exist in Mandrill)
       ['name' => $user->getFullName()] // Template variables
   );
   $this->dispatcher->dispatch($event);
   

Implementation Patterns

Core Workflows

1. Event-Driven Email Dispatch

   • Use SendEmailEvent for all Mandrill-triggered emails (e.g., password resets, notifications).
   • Example: Extend UserBundle's UserEvents to dispatch emails post-actions:

     // src/EventListener/UserListener.php
     public function onRegistrationSuccess(UserEvents::onRegistrationSuccess, User $user) {
         $event = new SendEmailEvent($user, 'welcome_email', ['name' => $user->getName()]);
         $this->dispatcher->dispatch($event);
     }
     

2. Template Management

   • Store Mandrill template names as constants (e.g., MandrillTemplates::WELCOME).
   • Validate templates exist in Mandrill via API call (see "Gotchas").

3. Dynamic Recipients

   • Pass recipient emails directly or resolve from user entities:

     $event = new SendEmailEvent($user, 'template_name', [], $user->getEmail());
     

4. Async Processing (Optional)

   • Use Symfony Messenger to queue emails for background processing:

     # config/packages/messenger.yaml
     framework:
         messenger:
             transports:
                 mandrill: '%env(MANDRILL_MESSENGER_TRANSPORT_DSN)%'
     

Integration Tips

• UserBundle Compatibility

  • Ensure BenGorUser\UserBundle is installed (composer require bengor-user/user-bundle).
  • Override UserBundle's event listeners to inject SendEmailEvent where needed.

• Custom Templates

  • Extend the bundle’s MandrillClient to support custom template logic:

    // src/Service/MandrillClient.php
    public function sendCustomTemplate(User $user, string $template, array $vars) {
        $this->sendTemplate($template, $vars, $user->getEmail());
    }
    

• Testing

  • Mock the MandrillClient in PHPUnit:

    $this->client = $this->createMock(MandrillClient::class);
    $this->client->expects($this->once())
        ->method('sendTemplate')
        ->with('welcome_email', ['name' => 'John'], 'john@example.com');
    

Gotchas and Tips

Pitfalls

1. Deprecated Dependencies

   • The bundle relies on UserBundle (last updated 2017). Verify compatibility with your User entity structure.
   • Fix: Override services or extend entities if fields differ (e.g., getFullName()).

2. Mandrill Template Validation

   • The bundle does not validate templates exist in Mandrill. Add a check:

     // src/Service/MandrillClient.php
     public function templateExists(string $name): bool {
         $templates = $this->client->templates->list();
         return in_array($name, wp_list_pluck($templates, 'name'));
     }
     

3. API Rate Limits

   • Mandrill has strict rate limits. Cache API responses or use a queue.

4. Environment Variables

   • The bundle expects MANDRILL_API_KEY in .env. Add a fallback in config/packages/mandrill_bridge.yaml:

     mandrill_bridge:
         api_key: '%env(MANDRILL_API_KEY)%{default:null}'
     

Debugging

• Enable API Logging Add to config/packages/mandrill_bridge.yaml:

  mandrill_bridge:
      debug: '%kernel.debug%'
  

  Logs will appear in var/log/dev.log.

• Common Errors

  Error	Cause	Solution
  Invalid API key	Wrong MANDRILL_API_KEY	Verify .env and Mandrill dashboard.
  Template not found	Template name mismatch	Check Mandrill’s "Templates" tab.
  Recipient invalid	Malformed email	Validate emails before dispatching.

Extension Points

1. Custom Email Events Extend SendEmailEvent for domain-specific data:

   class CustomEmailEvent extends SendEmailEvent {
       public function __construct(
           User $user,
           string $template,
           array $vars,
           ?string $recipient = null,
           array $customData = []
       ) {
           parent::__construct($user, $template, $vars, $recipient);
           $this->customData = $customData;
       }
   }
   

2. Override Mandrill Client Replace the default MandrillClient service:

   # config/services.yaml
   services:
       BenGorUser\MandrillBridgeBundle\Service\MandrillClient:
           class: App\Service\CustomMandrillClient
           arguments: ['@mandrill.client']
   

3. Add Global Email Headers Inject headers via a compiler pass:

   // src/DependencyInjection/Compiler/MandrillHeadersPass.php
   public function process(ContainerBuilder $container) {
       $definition = $container->findDefinition('mandrill_bridge.client');
       $definition->addMethodCall('setDefaultHeaders', [['X-My-Header' => 'value']]);
   }