Email Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alexlbr/email
   

   Add the service provider to config/app.php under providers:

   Alexlbr\Email\EmailServiceProvider::class,
   

2. Publish Config:

   php artisan vendor:publish --provider="Alexlbr\Email\EmailServiceProvider"
   

   This generates a config file at config/email.php. Update SMTP/mailer settings here.

3. First Use Case: Send a basic email via a controller or command:

   use Alexlbr\Email\Facades\Email;
   
   Email::send('user@example.com', 'Welcome!', 'emails.welcome', ['name' => 'John']);
   

   • Ensure a Blade template exists at resources/views/emails/welcome.blade.php.

Implementation Patterns

Core Workflows

1. Template-Based Emails:

   • Store reusable templates in resources/views/emails/.
   • Pass dynamic data via the 4th argument of Email::send():

     Email::send($to, $subject, 'emails.invoice', ['amount' => $total]);
     

2. Queueing Emails:

   • Use Laravel’s queue system for async sending:

     Email::queue('user@example.com', 'Reminder', 'emails.reminder', [], 'high');
     

   • Configure queue driver in .env (e.g., QUEUE_CONNECTION=database).

3. Attachments:

   • Attach files or inline images:

     Email::send($to, 'Subject', 'emails.report')
         ->attach('path/to/file.pdf')
         ->embed('path/to/image.png', 'image_id');
     

4. Custom Mailers:

   • Extend the mailer class for reusable logic:

     namespace App\Mailers;
     use Alexlbr\Email\Mailer;
     
     class NewsletterMailer extends Mailer {
         public function sendNewsletter($to, $data) {
             return $this->send($to, 'Newsletter', 'emails.newsletter', $data);
         }
     }
     

Integration Tips

• Laravel Events: Trigger emails from events:

  Event::listen('user.registered', function ($user) {
      Email::send($user->email, 'Welcome', 'emails.welcome', ['name' => $user->name]);
  });
  

• API Responses: Return email status in API responses:

  return response()->json(['status' => Email::send($to, $subject, $template, $data)->status()]);
  

• Testing: Mock the facade in PHPUnit:

  $this->app->instance('email', Mockery::mock('overload:Alexlbr\Email\Facades\Email'));
  

Gotchas and Tips

Pitfalls

1. Deprecated Package:

   • Last updated in 2015; lacks compatibility with modern Laravel (8/9/10). Use at your own risk.
   • May conflict with Laravel’s built-in Mail facade or Illuminate\Mail.

2. No Queue Middleware:

   • Unlike Laravel’s Mail facade, this package doesn’t natively support queue middleware (e.g., afterCommit). Workaround:

     Email::queue(...)->onQueue('emails')->afterCommit();
     

3. Config Overrides:

   • The published config may not align with Laravel’s mail.php. Merge settings manually:

     'driver' => config('mail.driver'), // Sync with Laravel’s config
     

4. Template Caching:

   • Blade templates aren’t auto-cached. Clear views manually if changes aren’t reflected:

     php artisan view:clear
     

Debugging Tips

• Log Emails: Add a log method to the facade for debugging:

  Email::send(...)->log(); // Check storage/logs/email.log
  

• Check SMTP Errors: Enable verbose logging in config/email.php:

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

Extension Points

1. Custom Transport: Override the transport layer by binding a new class to the email.transport service provider tag:

   $this->app->bind('email.transport', function () {
       return new CustomTransport();
   });
   

2. Event Hooks: Listen for email.sent and email.failed events (if the package emits them):

   Event::listen('email.sent', function ($event) {
       // Log or process sent emails
   });
   

3. Fallback to Laravel Mail: If the package fails, fall back to Laravel’s Mail facade:

   try {
       Email::send(...);
   } catch (\Exception $e) {
       \Mail::send(...); // Use Laravel’s Mail facade
   }