Mailer Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require brouzie/mailer-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Brouzie\MailerBundle\BrouzieMailerBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php artisan vendor:publish --tag=brouzie-mailer-config
   

   Update config/brouzie_mailer.php with your Brouzie API credentials:

   return [
       'api_key' => env('BROUZIE_API_KEY'),
       'default_from' => 'noreply@example.com',
   ];
   

3. First Use Case Send a test email via a Symfony service:

   use Brouzie\MailerBundle\Mailer\BrouzieMailer;
   
   class EmailService {
       public function __construct(private BrouzieMailer $mailer) {}
   
       public function sendWelcomeEmail(string $email): void {
           $this->mailer->send(new Email(
               to: $email,
               subject: 'Welcome!',
               html: '<h1>Hello!</h1>'
           ));
       }
   }
   

Implementation Patterns

Core Workflows

1. Email Composition Use the Email class (or DTO) for structured emails:

   $email = new Email(
       to: ['user@example.com', 'admin@example.com'],
       cc: ['manager@example.com'],
       bcc: ['archive@example.com'],
       subject: 'Your Order Confirmation',
       html: '<p>Order #12345 confirmed.</p>',
       text: 'Order #12345 confirmed.', // Fallback
       attachments: [
           new Attachment('invoice.pdf', file_get_contents('invoice.pdf'))
       ]
   );
   

2. Templates & Dynamic Content Store templates in resources/views/emails/ and pass data:

   $this->mailer->send(new Email(
       to: 'user@example.com',
       subject: 'Your Report',
       html: $this->renderView('emails.report', ['data' => $reportData])
   ));
   

3. Async Sending Use the queue option for background processing:

   $this->mailer->send($email, ['queue' => true]);
   

4. Event Listeners Hook into BrouzieMailerEvents for pre/post-send logic:

   // config/services.php
   Brouzie\MailerBundle\Event\BrouzieMailerEvents::MAILER_SENDING => [
       \App\Listeners\LogEmail::class,
   ],
   

Integration Tips

• Laravel-Specific: Wrap the bundle in a Laravel service provider for tighter integration:

  public function register() {
      $this->app->bind(BrouzieMailer::class, function ($app) {
          return new BrouzieMailer(
              $app['config']['brouzie_mailer.api_key'],
              $app['config']['brouzie_mailer.default_from']
          );
      });
  }
  

• Testing: Use the BrouzieMailer mock in PHPUnit:

  $this->mailer->shouldReceive('send')->once();
  

Gotchas and Tips

Pitfalls

1. API Rate Limits Brouzie may throttle requests. Implement exponential backoff in listeners:

   try {
       $this->mailer->send($email);
   } catch (RateLimitException $e) {
       sleep($e->getRetryAfter());
       retry();
   }
   

2. Attachment Size Limits Brouzie enforces a 20MB attachment limit. Validate files before sending:

   if ($attachment->getSize() > 20_000_000) {
       throw new \RuntimeException('Attachment too large');
   }
   

3. Missing to Address The bundle does not validate recipients. Add a validator:

   if (empty($email->getTo())) {
       throw new \InvalidArgumentException('Recipient email required');
   }
   

Debugging

• Enable Logging Set debug: true in config to log raw API responses:

  'debug' => env('APP_DEBUG'),
  

• API Response Inspection Override the BrouzieMailer client to dump responses:

  $client = new \GuzzleHttp\Client([
      'handler' => \GuzzleHttp\HandlerStack::create([
          new \GuzzleHttp\Middleware::tap(function ($request, $next) {
              $response = $next($request);
              error_log($response->getBody());
          })
      ])
  ]);
  

Extension Points

1. Custom Transport Extend BrouzieTransport to add features (e.g., retry logic):

   class CustomBrouzieTransport extends BrouzieTransport {
       public function send(Email $email, array $options) {
           // Add retry logic here
           parent::send($email, $options);
       }
   }
   

2. Event-Driven Extensions Dispatch custom events for analytics:

   $dispatcher->dispatch(new BrouzieMailerEvent($email, $response));
   

3. Template Engine Integrate with Laravel’s Blade:

   $this->mailer->setTemplateEngine(new BladeEngine($this->viewFactory));