Mandrill Bridge Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require bengor-user/mandrill-bridge
   

   Ensure your Laravel project uses bengor-user/user (the parent library) as a dependency.

2. Configure Mandrill Add Mandrill credentials to your .env:

   MANDRILL_SECRET=your_mandrill_api_key
   

3. Basic Usage Inject the bridge into your service or controller:

   use BenGorUser\MandrillBridge\MandrillBridge;
   use BenGorUser\User\User;
   
   $user = new User(); // Your User model/instance
   $bridge = new MandrillBridge($user, new \Mandrill());
   $bridge->sendWelcomeEmail(); // Example method (if implemented)
   

4. Key Classes

   • MandrillBridge: Core adapter class.
   • User (from bengor-user/user): Your user model, extended for Mandrill compatibility.

Implementation Patterns

Workflow: Sending Emails via User Model

1. Extend User Model Add Mandrill-compatible methods to your User model (e.g., sendEmail()):

   use BenGorUser\MandrillBridge\MandrillBridge;
   
   class User extends Authenticatable
   {
       public function sendEmail(MandrillBridge $bridge, string $template, array $mergeVars = [])
       {
           $bridge->setTemplate($template)
                  ->setMergeVars($mergeVars)
                  ->sendTo($this->email);
       }
   }
   

2. Service Layer Integration Create a service to abstract email logic:

   class EmailService
   {
       public function __construct(private MandrillBridge $bridge) {}
   
       public function sendWelcome(User $user)
       {
           $this->bridge->setTemplate('welcome')
                        ->setMergeVars(['name' => $user->name])
                        ->sendTo($user->email);
       }
   }
   

3. Event-Driven Emails Trigger emails via Laravel events (e.g., Registered):

   use Illuminate\Auth\Events\Registered;
   use BenGorUser\MandrillBridge\MandrillBridge;
   
   Registered::listen(function ($user) {
       $bridge = app(MandrillBridge::class);
       $bridge->setTemplate('welcome')
              ->sendTo($user->email);
   });
   

4. Dynamic Templates Use user attributes to dynamically set templates:

   $bridge->setTemplate($user->isPremium() ? 'premium_welcome' : 'welcome')
          ->sendTo($user->email);
   

Gotchas and Tips

Pitfalls

1. Deprecated Package

   • Last release in 2017; verify compatibility with modern Laravel/Mandrill APIs.
   • Test thoroughly with phpunit or phpspec (as per the package’s test suite).

2. Missing Documentation

   • Rely on bengor-user/user docs for core functionality.
   • Assume undocumented methods (e.g., setTemplate()) follow Mandrill’s API conventions.

3. Hardcoded Dependencies

   • The bridge assumes bengor-user/user v0.8+. Update or fork if using a newer version.

4. No Laravel Service Provider

   • Manually bind MandrillBridge in AppServiceProvider:

     $this->app->bind(MandrillBridge::class, function ($app) {
         return new MandrillBridge(
             auth()->user(),
             new \Mandrill($app['config']['services.mandrill.secret'])
         );
     });
     

Debugging Tips

1. Enable Mandrill Debugging Add to .env:

   MANDRILL_DEBUG=true
   

   Logs will appear in storage/logs/laravel.log.

2. Validate User Data Ensure User model has email and required fields (e.g., name for merge vars):

   $this->assertNotEmpty($user->email, 'User email is required for MandrillBridge.');
   

3. Test Locally Use Mandrill’s sandbox mode (free tier) to avoid real sends:

   $mandrill = new \Mandrill('your_sandbox_key');
   

Extension Points

1. Custom Merge Vars Extend MandrillBridge to add user-specific logic:

   class CustomMandrillBridge extends MandrillBridge
   {
       public function setUserMergeVars(User $user)
       {
           $this->mergeVars = array_merge($this->mergeVars, [
               'user_id' => $user->id,
               'signup_date' => $user->created_at->format('Y-m-d'),
           ]);
       }
   }
   

2. Template Caching Cache compiled Mandrill templates to reduce API calls:

   $template = cache()->remember("mandrill_template_{$templateName}", now()->addHours(1), function () use ($bridge) {
       return $bridge->getTemplateContent($templateName);
   });
   

3. Fallback to Laravel Mail Gracefully fall back to Laravel’s Mail facade if Mandrill fails:

   try {
       $bridge->sendTo($user->email);
   } catch (\Exception $e) {
       Mail::to($user->email)->send(new WelcomeMail($user));
   }