Email Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require druidvav/email-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Druidvav\EmailBundle\DruidvavEmailBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console druidvav:email:install
   

   Edit config/packages/druidvav_email.yaml to match your SMTP/mailer settings.

3. First Email Use the EmailService in a controller or service:

   use Druidvav\EmailBundle\Service\EmailService;
   
   class UserController extends AbstractController
   {
       public function sendWelcomeEmail(EmailService $emailService)
       {
           $emailService->send(
               'user@example.com',
               'Welcome!',
               'This is a test email.'
           );
       }
   }
   

4. Templates Place templates in templates/emails/ (e.g., welcome.html.twig). Use the render() method for templated emails:

   $emailService->send(
       'user@example.com',
       'Welcome!',
       $emailService->render('emails/welcome.html.twig', ['name' => 'John'])
   );
   

Implementation Patterns

Core Workflows

1. Basic Email Sending

   $emailService->send(
       'recipient@example.com',
       'Subject',
       'Plaintext or HTML content'
   );
   

2. Attachments

   $emailService->send(
       'recipient@example.com',
       'Subject',
       'Content',
       ['/path/to/file.pdf']
   );
   

3. Templated Emails

   • Store templates in templates/emails/ (e.g., invoice.html.twig).
   • Pass data dynamically:

     $emailService->send(
         'user@example.com',
         'Your Invoice',
         $emailService->render('emails/invoice.html.twig', ['total' => 99.99])
     );
     

4. Async Sending (Queue Integration) Configure druidvav_email.yaml to use Symfony’s Messenger component:

   druidvav_email:
       async: true
   

   Then dispatch emails as messages:

   $emailService->dispatch(
       'recipient@example.com',
       'Subject',
       'Content'
   );
   

5. Customizing Defaults Override defaults in config/packages/druidvav_email.yaml:

   druidvav_email:
       from_email: 'noreply@example.com'
       from_name: 'My App'
       charset: 'UTF-8'
   

Integration Tips

1. Dependency Injection Inject EmailService into services/controllers for reusable logic:

   public function __construct(private EmailService $emailService) {}
   

2. Event-Driven Emails Trigger emails from Symfony events (e.g., KernelEvents::TERMINATE):

   $eventDispatcher->addListener(KernelEvents::TERMINATE, function () use ($emailService) {
       $emailService->send('admin@example.com', 'System Alert', 'Server restarted.');
   });
   

3. Testing Use the EmailService in tests with a mock mailer:

   $emailService = $this->createMock(EmailService::class);
   $emailService->expects($this->once())->method('send');
   

4. Local Development Use Symfony’s null transport for testing:

   framework:
       mailer:
           dsn: 'null://default'
   

Gotchas and Tips

Pitfalls

1. Template Paths

   • Ensure templates are in templates/emails/ (case-sensitive on some systems).
   • Use absolute paths in render() (e.g., 'emails/welcome.html.twig').

2. Async Mode Quirks

   • If async: true, emails may not send immediately (depends on Messenger transport).
   • Verify the messenger.transport.async DSN is configured in framework.yaml.

3. Attachment Limits

   • Large attachments may fail silently. Monitor Symfony’s mailer logs (var/log/dev.log).

4. Configuration Overrides

   • Bundle config is merged with Symfony’s framework.mailer. Explicitly set from_email to avoid conflicts.

Debugging

1. Logs Enable Symfony’s mailer logging:

   monolog:
       handlers:
           main:
               level: debug
               channels: ['!event']
   

2. Common Errors

   • "Template not found": Verify the template exists and the path is correct.
   • "Connection refused": Check SMTP credentials in druidvav_email.yaml.
   • HTML emails rendering as plaintext: Ensure the Content-Type header is set to text/html in your template.

Extension Points

1. Custom Mailer Extend the EmailService to add logic:

   class CustomEmailService extends EmailService
   {
       public function sendWithTracking($to, $subject, $content)
       {
           $this->trackEmail($to); // Custom logic
           parent::send($to, $subject, $content);
       }
   }
   

2. Dynamic Templates Use Twig’s include to modularize templates:

   {# templates/emails/base.html.twig #}
   <html>
       <body>
           {{ include('emails/header.html.twig') }}
           {{ content }}
       </body>
   </html>
   

3. Environment-Specific Config Use Symfony’s parameter bags to switch configs:

   # config/packages/dev/druidvav_email.yaml
   druidvav_email:
       from_email: 'dev@example.com'