Mailer Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require brouzie/mailer
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Brouzie\Mailer\MailerServiceProvider"
   

2. Basic Configuration Ensure your .env has valid mail settings (SMTP/mailgun/etc.) and update config/mailer.php if the package requires customization.

3. First Use Case: Sending a Simple Email

   use Brouzie\Mailer\Facades\Mailer;
   
   Mailer::send('emails.welcome', ['name' => 'John'], function ($message) {
       $message->to('user@example.com')
               ->subject('Welcome!');
   });
   

   • Where to look first: Check config/mailer.php for default settings and resources/views/emails/ for template examples.

Implementation Patterns

Core Workflows

1. Template-Based Emails

   • Store Blade templates in resources/views/emails/ (e.g., welcome.blade.php).
   • Pass data dynamically:

     Mailer::send('emails.invoice', ['user' => $user, 'total' => $total], $callback);
     

2. Queueing Emails

   • Use Laravel’s queue system for async sending:

     Mailer::queue('emails.notification', ['data' => $data], $callback);
     

   • Configure queue driver in config/mail.php.

3. Attachments & Inline Assets

   • Attach files or embed images:

     $message->attach('path/to/file.pdf');
     $message->embed('path/to/image.png', 'cid:unique-id');
     

4. Customizing the Mailer Instance

   • Override defaults per request:

     Mailer::setFrom('custom@example.com');
     Mailer::setQueue('mailgun');
     

Integration Tips

• Laravel Events: Trigger emails from events:

  event(new UserRegistered($user)); // Dispatcher calls Mailer in listener.
  

• API Responses: Send emails post-API calls:

  return response()->json(['success' => true])->withMailer('emails.api_success');
  

• Testing: Use Mail::fake() with the package’s facade:

  Mailer::shouldReceive('send')->once();
  

Gotchas and Tips

Pitfalls

1. Template Paths

   • Ensure Blade templates are in resources/views/emails/ or specify a custom path in config.
   • Fix: Verify view.paths in config/mailer.php includes resources/views/emails.

2. Queue Configuration

   • If emails don’t send, check:
     • Queue driver is set in config/mail.php.
     • Queue worker is running (php artisan queue:work).
   • Debug: Tail logs with php artisan queue:failed-table and php artisan queue:work --once.

3. Facade vs. Service Container

   • Avoid new Brouzie\Mailer\Mailer(); use the facade (Mailer::) or resolve via container:

     $mailer = app(Brouzie\Mailer\Mailer::class);
     

4. Missing Dependencies

   • The package may rely on Laravel’s Mail facade. Ensure laravel/framework is installed.

Debugging Tips

• Log Emails: Enable Laravel’s mail logging in .env:

  MAIL_LOG=true
  

• Inspect Raw Emails: Use Mail::raw() for debugging:

  Mailer::raw('Test body', function ($message) { ... });
  

• Check Config Overrides: Run php artisan config:clear if changes to config/mailer.php aren’t applied.

Extension Points

1. Custom Mailables

   • Extend the package’s Mailable class:

     use Brouzie\Mailer\Mailable;
     
     class CustomMailable extends Mailable {
         public function build() {
             return $this->view('custom.template');
         }
     }
     

   • Register in MailerServiceProvider.

2. Hooks

   • Override beforeSend/afterSend in config:

     'events' => [
         'beforeSend' => \App\Listeners\LogEmail::class,
     ],
     

3. Dynamic Recipients

   • Use closures for dynamic to/cc/bcc:

     $message->to(function ($message) {
         return $message->user()->pluck('email');
     });