Mailbundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require atm/mailbundle
   

   Add to config/app.php under providers:

   Atm\MailBundle\MailBundle::class,
   

   Publish the config:

   php artisan vendor:publish --provider="Atm\MailBundle\MailBundle" --tag=config
   

2. First Use Case Send a basic email via a service container:

   $mailer = $this->container->get('atm_mail.mailer');
   $mailer->send([
       'to' => '[email protected]',
       'subject' => 'Welcome!',
       'body' => 'Hello, welcome to our platform!',
       'template' => 'emails.welcome' // Optional: Blade template path
   ]);
   

3. Key Config Check config/atm_mail.php for:

   • Default sender settings (from, reply_to).
   • Template paths (Blade/PHP).
   • Queue/mailer configurations.

Implementation Patterns

Core Workflows

1. Template-Based Emails Store reusable templates in resources/views/emails/ (Blade or PHP).

   $mailer->send([
       'template' => 'emails.invoice',
       'data' => ['amount' => 100, 'user' => $user]
   ]);
   

2. Attachments & Embeds

   $mailer->send([
       'attachments' => ['/path/to/file.pdf'],
       'embeds' => ['/path/to/image.png' => 'cid:image1']
   ]);
   

3. Queueing Emails Configure atm_mail.php to use queue:mail driver:

   'mailer' => [
       'driver' => 'queue',
       'queue' => 'mail'
   ],
   

   Dispatch jobs via:

   $mailer->queue($emailData);
   

4. Event-Based Sending Listen for events (e.g., user.registered) and trigger emails:

   Event::listen('user.registered', function ($user) {
       $mailer = app('atm_mail.mailer');
       $mailer->send(['to' => $user->email, 'template' => 'emails.welcome']);
   });
   

5. Custom Mailers Extend the base mailer for domain-specific logic:

   use Atm\MailBundle\Mailer\MailerInterface;
   
   class CustomMailer implements MailerInterface {
       public function send(array $data) {
           // Custom logic (e.g., logging, analytics)
           $defaultMailer->send($data);
       }
   }
   

   Bind in AppServiceProvider:

   $this->app->bind(MailerInterface::class, CustomMailer::class);
   

Integration Tips

• Laravel Notifications: Use the bundle alongside Laravel’s notifications for consistency:

  $user->notify(new WelcomeEmail($mailer));
  

• Testing: Mock the mailer in tests:

  $this->app->instance('atm_mail.mailer', Mockery::mock('Atm\MailBundle\Mailer\MailerInterface'));
  

• Logging: Enable debug logs in atm_mail.php:

  'debug' => env('MAIL_DEBUG', false),
  

Gotchas and Tips

Pitfalls

1. Template Paths

   • Ensure Blade templates extend a layout (e.g., resources/views/layouts/email.blade.php).
   • PHP templates must return a string or use ob_start()/ob_get_clean().

2. Queue Stuck Jobs

   • Monitor failed_jobs table if emails aren’t sending.
   • Retry failed jobs:

     php artisan queue:retry all
     

3. Attachment Permissions

   • Verify web server has read access to attached files.

4. Circular Dependencies

   • Avoid injecting the mailer into event listeners that trigger emails (risk of infinite loops).

Debugging

• Enable Debug Mode:

  'debug' => true, // in atm_mail.php
  

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

• Check Raw Output:

  $mailer->send(['debug' => true, ...]);
  

  Returns the raw email string for inspection.

Extension Points

1. Custom Transport Override the transport layer by binding Atm\MailBundle\Transport\TransportInterface:

   $this->app->bind(TransportInterface::class, CustomTransport::class);
   

2. Pre/Post-Send Hooks Use the atm.mail.sending and atm.mail.sent events:

   Event::listen('atm.mail.sending', function ($event) {
       // Modify $event->data before sending
   });
   

3. Dynamic Templates Fetch templates dynamically (e.g., from a database):

   $template = Template::find($id)->content;
   $mailer->send(['body' => $template, 'data' => $vars]);
   

Config Quirks

• Default Sender: Override globally in atm_mail.php or per-email:

  $mailer->send(['from' => '[email protected]', ...]);
  

• Rate Limiting: Configure in atm_mail.php:

  'rate_limiting' => [
      'enabled' => true,
      'max_emails' => 100,
      'period' => 'hour',
  ],