Email Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Laravel project via Composer:

   composer require black/email-bundle
   

   Register the bundle in config/app.php under providers:

   Black\EmailBundle\BlackEmailBundle::class,
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="Black\EmailBundle\BlackEmailBundle" --tag="config"
   

   Edit config/black_email.php to define your email transport (e.g., SMTP, Mailgun, SendGrid).

3. First Use Case Inject the Black\Email\EmailManager service into a controller or service:

   use Black\Email\EmailManager;
   
   public function sendWelcomeEmail(EmailManager $emailManager) {
       $email = $emailManager->createEmail()
           ->setTo('user@example.com')
           ->setSubject('Welcome!')
           ->setBody('Hello, welcome!');
       $emailManager->send($email);
   }
   

Implementation Patterns

Core Workflow

1. Email Creation Use the EmailManager to create emails with fluent methods:

   $email = $emailManager->createEmail()
       ->setFrom('noreply@example.com')
       ->setTo(['user1@example.com', 'user2@example.com'])
       ->setCc('cc@example.com')
       ->setBcc('bcc@example.com')
       ->setSubject('Your Order Confirmation')
       ->setBody($this->renderView('emails.order_confirmation', ['order' => $order]));
   

2. Attachments Attach files dynamically:

   $email->attachFromPath(storage_path('app/order.pdf'), 'order.pdf', 'application/pdf');
   $email->attachFromString('Base64-encoded-content', 'inline.png', 'image/png');
   

3. Templates Use Laravel’s Blade for templating:

   $email->setBody($this->renderView('emails.template', ['data' => $data]));
   

4. Queueing Emails Dispatch emails as jobs for async processing:

   use Black\Email\Jobs\SendEmail;
   
   SendEmail::dispatch($email)->onQueue('emails');
   

Integration Tips

• Laravel Mailables: Extend Black\Email\Email to create reusable email classes:

  class WelcomeEmail extends Email {
      public function __construct($user) {
          $this->setTo($user->email)
               ->setSubject('Welcome, ' . $user->name);
      }
  }
  

• Event Listeners: Trigger actions post-send:

  $emailManager->send($email, function () {
      // Post-send logic (e.g., analytics, logging)
  });
  

• Testing: Use the EmailManager mock in PHPUnit:

  $emailManager = $this->createMock(EmailManager::class);
  $emailManager->expects($this->once())->method('send');
  $this->app->instance(EmailManager::class, $emailManager);
  

Gotchas and Tips

Pitfalls

1. Version Instability Avoid @stable; pin to a specific version (e.g., 1.0.0) to prevent breaking changes. Check the releases for updates.

2. Missing Dependencies Ensure black/email (the underlying component) is installed:

   composer require black/email
   

3. Queue Configuration If using queues, ensure the emails queue exists in .env:

   QUEUE_CONNECTION=database
   QUEUE_DEFAULT=emails
   

4. Attachment Limits Large attachments may hit PHP’s post_max_size or upload_max_filesize. Adjust in php.ini or use cloud storage (e.g., S3) for binaries.

Debugging

• Log Emails: Enable logging in config/black_email.php:

  'logging' => true,
  

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

• Validate Recipients: Use setTo() with an array to avoid typos:

  $email->setTo(['valid@example.com']); // Fails silently on invalid addresses
  

Extension Points

1. Custom Transports Extend Black\Email\Transport\TransportInterface to add new providers (e.g., AWS SES):

   class AWSTransport implements TransportInterface {
       public function send(Email $email) { /* ... */ }
   }
   

   Register in config/black_email.php:

   'transports' => [
       'aws' => Black\Email\Transport\AWSTransport::class,
   ],
   

2. Email Events Listen for email.sent or email.failed events:

   Event::listen('email.sent', function ($email) {
       // Track sent emails in a database
   });
   

3. Fallback Transports Configure a fallback transport in config/black_email.php:

   'fallback_transport' => 'smtp',
   

   Ensures emails are sent even if the primary transport fails.

Pro Tips

• Environment-Specific Configs: Use Laravel’s config caching to switch transports per environment:

  // config/black_email.php
  'transport' => env('MAIL_TRANSPORT', 'smtp'),
  

• Rate Limiting: Implement rate limiting in a middleware to prevent abuse:

  $emailManager->send($email, function () use ($user) {
      $user->increment('emails_sent');
  });
  

• Local Testing: Use the log transport for testing:

  'transport' => 'log', // Logs emails to storage/logs/black_email.log