Rad Mailer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require devster/rad-mailer
   

   Add to config/app.php under providers:

   Devster\RadMailer\RadMailerServiceProvider::class,
   

   Publish config (optional):

   php artisan vendor:publish --provider="Devster\RadMailer\RadMailerServiceProvider"
   

2. First Use Case: Send a basic email in a controller:

   use Rad\Mailer;
   
   public function sendWelcomeEmail()
   {
       $mailer = app(Mailer::class);
       $mailer->send([
           'to' => 'user@example.com',
           'subject' => 'Welcome!',
           'template' => 'emails.welcome', // Twig template path
           'data' => ['name' => 'John']
       ]);
   }
   

3. Key Files:

   • config/rad-mailer.php (for default settings)
   • resources/views/emails/ (store Twig templates here)

Implementation Patterns

Core Workflows

1. Twig Integration:

   • Use Twig templates for emails (e.g., emails.welcome.twig).
   • Pass data dynamically:

     {# emails/welcome.twig #}
     <p>Hello {{ data.name }}, welcome!</p>
     

   • Call from Laravel:

     $mailer->send(['template' => 'emails.welcome', 'data' => ['name' => 'Alice']]);
     

2. Swiftmailer Configuration:

   • Configure via Laravel’s config/mail.php (RAD Mailer uses Swiftmailer under the hood).
   • Override defaults in config/rad-mailer.php:

     'default_from' => 'noreply@example.com',
     'twig_path' => resource_path('views'),
     

3. Batch Sending:

   • Send to multiple recipients:

     $mailer->send([
         'to' => ['user1@example.com', 'user2@example.com'],
         'subject' => 'Monthly Newsletter',
         'template' => 'emails.newsletter',
         'data' => ['month' => 'June']
     ]);
     

4. Attachments:

   • Add attachments via Swiftmailer:

     $mailer->send([
         'to' => 'user@example.com',
         'subject' => 'Your Invoice',
         'template' => 'emails.invoice',
         'attachments' => [storage_path('app/invoice.pdf')]
     ]);
     

5. Queueing Emails:

   • Use Laravel’s queue system:

     $mailer->queue([
         'to' => 'user@example.com',
         'subject' => 'Delayed Email',
         'template' => 'emails.delayed',
         'data' => ['content' => 'Hello!']
     ]);
     

6. Customizing the Mailer Instance:

   • Bind a custom instance in AppServiceProvider:

     $this->app->bind(Mailer::class, function ($app) {
         $swift = $app->make(Swift_Mailer::class);
         $twig = $app->make('view');
         return new Rad\Mailer($swift, $twig, 'custom@example.com');
     });
     

Gotchas and Tips

Pitfalls

1. Twig Template Paths:

   • Ensure templates are in resources/views/ or update twig_path in config.
   • Use dot notation for nested paths (e.g., emails.welcome resolves to resources/views/emails/welcome.twig).

2. Swiftmailer Configuration:

   • If emails fail silently, verify config/mail.php (SMTP/Gmail settings, etc.).
   • RAD Mailer relies on Laravel’s Swiftmailer setup—misconfigurations here will break RAD Mailer.

3. Data Binding:

   • Twig templates expect data to be an array. If passing an object, ensure properties are accessible (e.g., $data->name in Twig).
   • Avoid circular references in data to prevent Twig errors.

4. Queueing Issues:

   • If queued emails fail, check the queue worker logs (php artisan queue:work --verbose).
   • Ensure the queue method is used instead of send for async emails.

5. Default from Address:

   • Override the global from address per email or set it in the constructor. Unset defaults may cause emails to fail.

Debugging Tips

1. Enable Swiftmailer Logging: Add to config/mail.php:

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

   Check logs in storage/logs/laravel.log.

2. Validate Templates: Test Twig templates independently:

   $twig = $app->make('view');
   echo $twig->render('emails.welcome', ['name' => 'Test']);
   

3. Check for Exceptions: Wrap RAD Mailer calls in try-catch:

   try {
       $mailer->send([...]);
   } catch (\Exception $e) {
       \Log::error('Email failed: ' . $e->getMessage());
   }
   

Extension Points

1. Custom Twig Environment: Extend the Twig environment in AppServiceProvider:

   $twig = $app->make('view');
   $twig->getEnvironment()->addGlobal('app_name', config('app.name'));
   

2. Pre/Post-Send Hooks: Override the Rad\Mailer class to add logic:

   class CustomMailer extends Rad\Mailer {
       public function send($params) {
           // Pre-send logic
           $result = parent::send($params);
           // Post-send logic
           return $result;
       }
   }
   

3. Dynamic Templates: Use Twig’s embed or include for modular templates:

   {# emails/base.twig #}
   <html>
       <body>
           {{ include('emails/header') }}
           {{ block('content') }}
       </body>
   </html>
   

4. Testing: Mock the mailer in tests:

   $mailer = Mockery::mock(Rad\Mailer::class);
   $mailer->shouldReceive('send')->once();
   $this->app->instance(Rad\Mailer::class, $mailer);