Mailer Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cleentfaar/mailer
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Cleentfaar\Mailer\MailerServiceProvider" --tag="mailer-config"
   

2. First Use Case: Sending a Basic Email

   use Cleentfaar\Mailer\Facades\Mailer;
   
   Mailer::send('emails.welcome', [], function ($message) {
       $message->to('[email protected]')
               ->subject('Welcome!');
   });
   

3. Where to Look First

   • Documentation: Check the GitHub README for basic usage.
   • Config File: config/mailer.php (if published) for customization.
   • Blade Templates: Store email templates in resources/views/emails/.

Implementation Patterns

Common Workflows

1. Dynamic Email Templates Use Blade templates with dynamic data:

   Mailer::send('emails.invoice', ['amount' => 99.99, 'user' => $user], function ($message) {
       $message->to($user->email)
               ->subject('Invoice #'.$invoiceId);
   });
   

2. Reusable Email Classes Extend Cleentfaar\Mailer\Mailer for reusable logic:

   class UserMailer extends Mailer {
       public function sendWelcome(User $user) {
           $this->send('emails.welcome', ['user' => $user], function ($message) use ($user) {
               $message->to($user->email)
                       ->subject('Welcome, '.$user->name);
           });
       }
   }
   

3. Attachments & Inline Images

   $message->attach('path/to/file.pdf')
           ->attachData($pdfContent, 'invoice.pdf', ['mime' => 'application/pdf'])
           ->embed('path/to/image.png', 'image_id');
   

4. Queueing Emails Use Laravel's queue system:

   Mailer::queue('emails.notification', [], function ($message) {
       $message->to('[email protected]');
   });
   

5. Customizing the Mailer Instance Bind a custom mailer in AppServiceProvider:

   $this->app->bind('mailer', function () {
       return new CustomMailer();
   });
   

Integration Tips

1. Leverage Laravel's Existing Mail Config The package integrates seamlessly with Laravel's config/mail.php (e.g., SMTP, Mailgun, SES).

2. Use Events for Post-Send Logic Listen to Cleentfaar\Mailer\Events\MessageSent:

   Event::listen('Cleentfaar\Mailer\Events\MessageSent', function ($event) {
       Log::info('Email sent to: '.$event->message->to->address);
   });
   

3. Testing Emails Use Laravel's Mail::fake() alongside the package:

   Mail::fake();
   Mailer::send('emails.test');
   Mail::assertSent(\Cleentfaar\Mailer\Message::class);
   

4. Localization Support Pass a locale to templates:

   Mailer::send('emails.welcome', [], function ($message) {
       $message->locale('nl');
   });
   

Gotchas and Tips

Pitfalls

1. Template Paths Ensure Blade templates are in resources/views/emails/ or specify a custom path in the config:

   'view_path' => resource_path('views/custom_emails'),
   

2. Queueing Without a Queue Driver If MAIL_DRIVER is not set to queue, queued emails will send immediately (bypassing the queue).

3. Missing Facade Alias If using the facade, ensure the alias is registered in config/app.php:

   'aliases' => [
       'Mailer' => Cleentfaar\Mailer\Facades\Mailer::class,
   ],
   

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

5. Caching Templates The package does not cache templates by default. For high-volume emails, consider caching compiled views:

   Mailer::setViewFactory(function () {
       return new \Illuminate\View\Factory(app('view'), app('events'));
   });
   

Debugging

1. Log Sent Emails Enable logging in config/mailer.php:

   'log_sent_messages' => true,
   

   Check storage/logs/laravel.log for sent email details.

2. Inspect Raw Messages Use a debug listener:

   Event::listen('Cleentfaar\Mailer\Events\MessageSent', function ($event) {
       \Log::debug('Raw Message:', $event->message->getSwiftMessage()->toString());
   });
   

3. Check for Silent Failures Wrap sends in try-catch:

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

Extension Points

1. Custom Mailer Drivers Extend Cleentfaar\Mailer\Mailer and bind it in AppServiceProvider:

   class SlackMailer extends Mailer {
       public function send($view, $data, Closure $callback) {
           // Custom logic (e.g., send to Slack)
       }
   }
   

2. Modify Message Before Sending Use the beforeSend event:

   Event::listen('Cleentfaar\Mailer\Events\BeforeSend', function ($event) {
       $event->message->cc('[email protected]');
   });
   

3. Add Custom Headers

   $message->addHeader('X-Priority', 'High');
   $message->addHeader('Reply-To', '[email protected]');
   

4. Override Default Swiftmailer Transport Configure in config/mail.php:

   'transport' => 'smtp',
   'smtp' => [
       'host' => env('MAIL_HOST'),
       'port' => env('MAIL_PORT'),
       // Custom transport options
   ],
   

5. Dynamic Recipients Use closures for dynamic to, cc, or bcc:

   $message->to(function ($message) {
       return $message->to('[email protected]');
   });