Swift Mailer Bridge Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require bengor-user/swift-mailer-bridge
   

   Ensure your project uses BenGorUser/User (v0.8) and SwiftMailer (v5.x or v6.x).

2. Basic Setup:

   • Register the bridge’s service provider in config/app.php:

     'providers' => [
         // ...
         BenGorUser\SwiftMailerBridge\SwiftMailerBridgeServiceProvider::class,
     ],
     

   • Publish the config (if available) or configure manually in config/mail.php:

     'bridge' => [
         'user_class' => BenGorUser\User\User::class,
     ],
     

3. First Use Case: Send a password reset email using SwiftMailer with a BenGorUser:

   use BenGorUser\SwiftMailerBridge\UserMessage;
   use Swift_Mailer;
   
   $mailer = new Swift_Mailer(/* your transport */);
   $user = $this->userRepository->find(1); // BenGorUser instance
   
   $message = (new UserMessage())
       ->setUser($user)
       ->setSubject('Reset Password')
       ->setBodyFromView('emails.reset_password', ['user' => $user]);
   
   $mailer->send($message);
   

4. Laravel Integration: Use the bridge in a Mailable class:

   use Illuminate\Bus\Queueable;
   use Illuminate\Mail\Mailable;
   use BenGorUser\SwiftMailerBridge\UserMessage;
   
   class ResetPasswordMailable extends Mailable
   {
       use Queueable;
   
       public function build()
       {
           $user = auth()->user();
           $message = (new UserMessage())
               ->setUser($user)
               ->setSubject('Reset Password')
               ->setBodyFromView('emails.reset_password');
   
           return $this->markdown('emails.reset_password')
               ->with(['user' => $user])
               ->to($user->getEmail());
       }
   }
   

Implementation Patterns

Usage Patterns

1. Event-Driven Emails: Attach the bridge to Laravel events (e.g., Registered, PasswordReset) to automate emails:

   // In EventServiceProvider
   protected $listen = [
       \Illuminate\Auth\Events\Registered::class => [
           \App\Listeners\SendWelcomeEmail::class,
       ],
   ];
   

   // Listener
   public function handle(Registered $event)
   {
       $mailer = app(Swift_Mailer::class);
       $message = (new UserMessage())
           ->setUser($event->user)
           ->setSubject('Welcome!')
           ->setBodyFromView('emails.welcome');
   
       $mailer->send($message);
   }
   

2. Dynamic Email Templates: Use Blade templates with user data:

   // In a Mailable
   $message = (new UserMessage())
       ->setUser($user)
       ->setBodyFromView('emails.notification', [
           'user' => $user,
           'activity' => $activity,
       ]);
   

   <!-- resources/views/emails/notification.blade.php -->
   <p>Hello {{ $user->getName() }},</p>
   <p>You have new activity: {{ $activity->description }}</p>
   

3. Multi-Recipient Emails: Send emails to multiple users with shared context:

   $message = (new UserMessage())
       ->setSubject('Team Update')
       ->setBodyFromView('emails.team_update');
   
   foreach ($teamMembers as $user) {
       $message->setUser($user);
       $mailer->send($message);
   }
   

4. Queueing Emails: Dispatch emails as jobs for async processing:

   use Illuminate\Support\Facades\Bus;
   
   Bus::dispatch(new SendEmailJob($user, 'welcome'));
   

   // SendEmailJob.php
   public function handle()
   {
       $mailer = app(Swift_Mailer::class);
       $message = (new UserMessage())
           ->setUser($this->user)
           ->setSubject($this->subject)
           ->setBodyFromView('emails.' . $this->subject);
   
       $mailer->send($message);
   }
   

Workflows

1. Password Reset Flow:

   • Trigger on PasswordReset event.
   • Use the bridge to send a reset link via SwiftMailer:

     $message = (new UserMessage())
         ->setUser($user)
         ->setSubject('Reset Password')
         ->setBodyFromView('emails.reset', [
             'token' => $token,
             'expires' => now()->addHours(1),
         ]);
     

2. User Verification:

   • Send a verification email after registration:

     $message = (new UserMessage())
         ->setUser($user)
         ->setSubject('Verify Your Email')
         ->setBodyFromView('emails.verify', [
             'verificationUrl' => route('verification.verify', ['token' => $token]),
         ]);
     

3. Transactional Emails:

   • Order confirmations, shipping updates, etc.:

     $message = (new UserMessage())
         ->setUser($user)
         ->setSubject('Order #{{ $order->id }} Confirmed')
         ->setBodyFromView('emails.order_confirmation', [
             'order' => $order,
         ]);
     

Integration Tips

1. Leverage Laravel’s Mail Facade: Combine the bridge with Laravel’s Mail facade for consistency:

   use Illuminate\Support\Facades\Mail;
   use BenGorUser\SwiftMailerBridge\UserMessage;
   
   $message = (new UserMessage())
       ->setUser($user)
       ->setSubject('Hello!');
   
   Mail::send($message);
   

2. Customize SwiftMailer Transport: Configure SwiftMailer in config/mail.php:

   'swift' => [
       'transport' => 'smtp',
       'host' => env('MAIL_HOST', 'smtp.example.com'),
       'port' => env('MAIL_PORT', 587),
       'username' => env('MAIL_USERNAME'),
       'password' => env('MAIL_PASSWORD'),
       'encryption' => env('MAIL_ENCRYPTION', 'tls'),
   ],
   

3. Extend UserMessage: Add custom methods to UserMessage for project-specific needs:

   class CustomUserMessage extends UserMessage
   {
       public function addOrderDetails($order)
       {
           $this->body .= "\nOrder #{$order->id}: {$order->total}";
           return $this;
       }
   }
   

4. Testing: Use Laravel’s MailFake for unit tests:

   public function test_welcome_email()
   {
       Mail::fake();
       $user = factory(BenGorUser\User\User::class)->create();
   
       $message = (new UserMessage())
           ->setUser($user)
           ->setSubject('Welcome');
   
       Mail::send($message);
   
       Mail::assertSent(UserMessage::class, function ($mail) use ($user) {
           return $mail->getSubject() === 'Welcome' &&
                  $mail->getTo()[0] === $user->getEmail();
       });
   }
   

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch:

   • The package requires PHP 5.5, but Laravel 10+ needs PHP 8.1+.
   • Fix: Fork the package and update dependencies (SwiftMailer v6+, PHP 8.1+).

2. SwiftMailer Version Conflicts:

   • The package may assume SwiftMailer v5.x, but Laravel uses v6.x.
   • Fix: Test compatibility or update the bridge’s composer.json:

     "require": {
         "swiftmailer/swiftmailer": "^6.0"
     }
     

3. Tight Coupling to BenGorUser:

   • The bridge expects a BenGorUser\User instance. If using Laravel’s App\User, you’ll need to:
     • Option 1: Extend BenGorUser\User to match your model.
     • Option 2: Create an adapter interface:

       interface UserContract {
           public function getEmail();
           public function getName();
           // Add other required methods.
       }
       

       Then wrap your Laravel user:

       class LaravelUserAdapter implements UserContract {
           protected $user;
       
           public function __construct($user) {
               $this->user = $user;
           }
       
           public function getEmail() {
               return $this->user->email;
           }
       
           // Implement other methods.
       }
       

4. Missing Laravel-Specific Features:

   • The bridge lacks native support for Laravel’s queueing, failures, or **markdown