Swift Mailer Bridge Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle:

   composer require bengor-user/swift-mailer-bridge-bundle
   

   Ensure SwiftMailerBridgeBundle is enabled in config/bundles.php:

   return [
       // ...
       BenGorUser\SwiftMailerBridgeBundle\SwiftMailerBridgeBundle::class => ['all' => true],
   ];
   

2. Configure Dependencies: Ensure FOSUserBundle (or a compatible UserBundle) and SwiftMailerBridge are installed and configured. The bundle assumes:

   • A UserBundle (e.g., FOSUserBundle) for user management.
   • SwiftMailerBridge for email templating (e.g., swiftmailer/swiftmailer-bridge).

3. First Use Case: Send a templated email to a user (e.g., password reset or welcome email):

   use BenGorUser\SwiftMailerBridgeBundle\Mailer\SwiftMailerBridgeMailer;
   
   // Inject via dependency injection (recommended)
   $mailer = $this->container->get('swiftmailer_bridge.mailer');
   $mailer->send('user/welcome_email.twig', 'user@example.com', [
       'name' => $user->getUsername(),
   ]);
   

Implementation Patterns

Core Workflows

1. Email Templating with User Context: Use Twig templates (e.g., user/welcome_email.twig) to render emails dynamically:

   {# templates/user/welcome_email.twig #}
   <p>Hello {{ name }}, welcome to our platform!</p>
   

   Pass user-specific data via the $context array in send().

2. Integration with User Events: Hook into FOSUserBundle events (e.g., user_registered) to trigger emails:

   // src/EventListener/UserListener.php
   use BenGorUser\SwiftMailerBridgeBundle\Mailer\SwiftMailerBridgeMailer;
   use FOS\UserBundle\FOSUserEvents;
   
   class UserListener
   {
       public function __construct(private SwiftMailerBridgeMailer $mailer) {}
   
       public function onUserRegistered(UserEvent $event)
       {
           $user = $event->getUser();
           $this->mailer->send('user/welcome_email.twig', $user->getEmail(), [
               'name' => $user->getUsername(),
           ]);
       }
   }
   

   Register the listener in services.yaml:

   services:
       App\EventListener\UserListener:
           tags:
               - { name: kernel.event_listener, event: fos_user.registered, method: onUserRegistered }
   

3. Reusing Email Templates: Store templates in templates/ (e.g., templates/user/) and reference them by path. Example structure:

   /templates/
       user/
           welcome_email.twig
           password_reset.twig
   

4. Testing Emails: Use SwiftMailer’s NullTransport for testing:

   // config/packages/dev/swiftmailer.yaml
   swiftmailer:
       transport: null
   

Gotchas and Tips

Pitfalls

1. Dependency Conflicts:

   • The bundle assumes FOSUserBundle or a compatible UserBundle. If using a custom user system, ensure the User entity has getEmail() and similar methods.
   • Fix: Extend SwiftMailerBridgeMailer or mock dependencies if needed.

2. Template Paths:

   • Templates must be in templates/ (not templates/bundles/). The bundle does not support bundle-specific template paths by default.
   • Fix: Override the template_locations config:

     # config/packages/swiftmailer_bridge.yaml
     swiftmailer_bridge:
         template_locations:
             - '@AppBundle/Resources/views/user/'
     

3. SwiftMailerBridge Version: The bundle is tied to swiftmailer/swiftmailer-bridge (not Symfony Mailer). Ensure compatibility:

   composer require swiftmailer/swiftmailer-bridge:^1.0
   

4. Deprecated Symfony Versions: The last release is from 2017 and targets Symfony 2.8+. For Symfony 5/6, you may need to:

   • Fork the bundle and update dependencies (e.g., replace Swift_* classes with SwiftMailer\*).
   • Use a modern alternative like symfony/mailer.

Debugging Tips

1. Check Email Content: Temporarily switch to GmailTransport to debug:

   # config/packages/dev/swiftmailer.yaml
   swiftmailer:
       transport: gmail
       username: your@gmail.com
       password: app_password
   

2. Template Errors: Enable Twig debug mode in config/packages/dev/twig.yaml:

   twig:
       debug: true
       strict_variables: true
   

3. Logging: Add a logger to SwiftMailerBridgeMailer for debugging:

   use Psr\Log\LoggerInterface;
   
   class SwiftMailerBridgeMailer
   {
       public function __construct(private LoggerInterface $logger) {}
   
       public function send(string $template, string $to, array $context)
       {
           $this->logger->debug('Sending email to', ['to' => $to, 'template' => $template]);
           // ... rest of the logic
       }
   }
   

Extension Points

1. Custom Mailer: Extend SwiftMailerBridgeMailer to add features (e.g., attachments):

   use BenGorUser\SwiftMailerBridgeBundle\Mailer\SwiftMailerBridgeMailer as BaseMailer;
   
   class CustomMailer extends BaseMailer
   {
       public function sendWithAttachment(string $template, string $to, array $context, string $attachmentPath)
       {
           $message = $this->createMessage($template, $to, $context);
           $message->attach(\Swift_Attachment::fromPath($attachmentPath));
           $this->getTransport()->send($message);
       }
   }
   

2. Dynamic Recipients: Override the send() method to support CC/BCC:

   public function send(string $template, string $to, array $context, ?string $cc = null, ?string $bcc = null)
   {
       $message = $this->createMessage($template, $to, $context);
       if ($cc) $message->setCc([$cc]);
       if ($bcc) $message->setBcc([$bcc]);
       $this->getTransport()->send($message);
   }
   

3. Event-Driven Emails: Dispatch custom events before sending emails to allow interception:

   use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
   
   class SwiftMailerBridgeMailer
   {
       public function __construct(
           private EventDispatcherInterface $dispatcher
       ) {}
   
       public function send(string $template, string $to, array $context)
       {
           $event = new PreSendEmailEvent($template, $to, $context);
           $this->dispatcher->dispatch($event);
   
           if ($event->isPropagationStopped()) {
               return;
           }
           // ... send email
       }
   }