Mail Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require disjfa/mail-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Disjfa\MailBundle\DisjfaMailBundle::class => ['all' => true],
   ];
   

2. Configure Routes: Add to config/routes/disjfa_mail.yaml:

   disjfa_mail:
       resource: '@DisjfaMailBundle/Controller/'
       type: annotation
       prefix: '/admin'
   

3. First Use Case: Create a custom mail class extending MailInterface in src/Mail/:

   namespace App\Mail;
   
   use Disjfa\MailBundle\Mail\MailInterface;
   use Twig\Environment;
   
   class WelcomeMail implements MailInterface
   {
       public function getName() { return 'Welcome Email'; }
       public function getSubject() { return 'Welcome to our platform!'; }
       public function getContent(Environment $twig) {
           return $twig->render('emails/welcome.html.twig', ['name' => 'User']);
       }
   }
   

4. Send the Email: Inject the MailService and call:

   $mailService->send(new WelcomeMail(), ['user@example.com']);
   

Implementation Patterns

Core Workflows

1. Template-Based Emails:

   • Use Twig for dynamic content. Escape Twig delimiters ({{ → {{ '{{' }}).
   • Example template (templates/emails/welcome.html.twig):

     <p>Hello {{ name }}!</p>
     

2. Dynamic Variables:

   • Pass variables via send() method’s second argument:

     $mailService->send(new WelcomeMail(), ['name' => 'John']);
     

   • Access them in templates via {{ variable }}.

3. Translation Support:

   • Inject Translator into your MailInterface implementation:

     public function getSubject(TranslatorInterface $translator) {
         return $translator->trans('welcome.subject');
     }
     

4. Reusable Mail Classes:

   • Store mail classes in src/Mail/ and reuse across controllers/services.

Integration Tips

• Symfony Mailer: Configure DisjfaMailBundle to use Symfony’s Mailer component via config/packages/disjfa_mail.yaml:

  disjfa_mail:
      mailer: symfony_mailer
  

• Queue Emails: Use Symfony Messenger to queue emails:

  disjfa_mail:
      mailer: messenger_mailer
  

• Testing: Mock MailService in tests:

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

Gotchas and Tips

Pitfalls

1. Twig Delimiter Escaping:

   • Forgetting to escape {{ and }} in templates will break variable parsing.
   • Fix: Use {{ '{{' }} variable {{ '}}' }} instead of {{ variable }}.

2. Circular Dependencies:

   • Avoid injecting MailService into MailInterface implementations (circular dependency).
   • Fix: Pass data via constructor or send() arguments.

3. Missing Routes:

   • Forgetting to configure disjfa_mail.yaml routes will break admin access to mail settings.
   • Fix: Always include the route config.

4. No Default Transport:

   • The bundle requires manual transport configuration (e.g., SMTP, Symfony Mailer).
   • Fix: Configure in config/packages/mailer.yaml or use Symfony’s framework/mailer.

Debugging

• Check Sent Emails: Use Symfony’s MailerDebugListener to log emails:

  framework:
      mailer:
          dsn: '%env(MAILER_DSN)%'
          delivery_mode: 'debug'  # Logs emails to `var/log/dev.log`
  

• Validate Mail Classes: Ensure all MailInterface methods are implemented. Use PHPStan:

  vendor/bin/phpstan analyse src/Mail
  

Extension Points

1. Custom Transports: Extend Disjfa\MailBundle\Transport\TransportInterface to add support for non-Symfony transports (e.g., AWS SES).

2. Event Listeners: Listen to mail.send events to log or modify emails:

   // config/services.yaml
   services:
       App\EventListener\MailListener:
           tags:
               - { name: kernel.event_listener, event: mail.send, method: onMailSend }
   

3. Dynamic Templates: Override Disjfa\MailBundle\Mail\MailInterface to support dynamic template selection:

   public function getTemplatePath(): string { return 'emails/' . $this->getName() . '.html.twig'; }
   

4. Attachments: Extend the bundle to support attachments by modifying MailInterface:

   public function getAttachments(): array { return []; }