Mailer Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require 2lenet/mailer-bundle
   

   Ensure your project meets the requirements: PHP ≥ 7.1 and Symfony 4.

2. Enable the Bundle: Add to config/bundles.php:

   return [
       // ...
       TwoLE\MailerBundle\MailerBundle::class => ['all' => true],
   ];
   

3. First Use Case: Inject MailerManager into a controller/service and send a basic email:

   use TwoLE\MailerBundle\Mailer\MailerManager;
   
   public function sendTestEmail(MailerManager $mailerManager)
   {
       $recipients = [
           'recipient@example.com' => ['nom' => 'John Doe'],
       ];
   
       $mail = $mailerManager->create('TEST', $recipients);
       $mailerManager->send($mail);
   }
   

4. Check Configuration: Verify config/packages/two_le_mailer.yaml exists (or create it). Defaults are minimal; extend as needed.

Implementation Patterns

Core Workflow

1. Mail Creation: Use MailerManager::create() with a template name (e.g., 'TEST') and an array of recipients with metadata (e.g., ['nom' => 'Name']). Templates should be defined in templates/mail/ (e.g., TEST.html.twig).

2. Sending Emails:

   $mail = $mailerManager->create('TEMPLATE_NAME', $recipients);
   $mailerManager->send($mail); // Synchronous send
   

   For async, use a message queue (e.g., Symfony Messenger) or wrap in a job.

3. Dynamic Recipients: Loop through collections to generate emails dynamically:

   foreach ($users as $user) {
       $mail = $mailerManager->create('WELCOME', [$user->email => ['nom' => $user->name]]);
       $mailerManager->send($mail);
   }
   

4. Template Inheritance: Extend base templates (e.g., base.html.twig) for consistent layouts. Example:

   {# templates/mail/TEST.html.twig #}
   {% extends 'mail/base.html.twig' %}
   {% block body %}
       Hello {{ recipient.nom }}, welcome!
   {% endblock %}
   

Integration Tips

• Symfony Mailer: Configure two_le_mailer.yaml to use Symfony’s MailerInterface:

  two_le_mailer:
      mailer: 'symfony.mailer.mailer'
  

• Swiftmailer Legacy: If using Swiftmailer, ensure it’s installed and configured in config/packages/swiftmailer.yaml.
• EasyAdminPlus: For admin UI, install 2lenet/easyadmin-plus-bundle and configure menu.yaml to expose mail templates/recipients.

Gotchas and Tips

Pitfalls

1. Template Paths: Templates must reside in templates/mail/ or a custom path defined in config. Example error:

   Template "TEST.html.twig" not found in namespace "mail".
   

   Fix: Verify the path in two_le_mailer.yaml:

   two_le_mailer:
       templates_dir: '%kernel.project_dir%/templates/custom_mail/'
   

2. Recipient Format: The destinataires array must use email as the key and an associative array as the value:

   // ❌ Wrong
   $recipients = ['John Doe' => 'john@example.com'];
   
   // ✅ Correct
   $recipients = ['john@example.com' => ['nom' => 'John Doe']];
   

3. Async Sending: The bundle does not natively support async. Use Symfony Messenger or a queue system:

   $this->messageBus->dispatch(new SendMailMessage($mail));
   

4. EasyAdminPlus Dependency: The admin UI features (editing templates/recipients) require easyadmin-plus-bundle. Without it, these routes will 404.

Debugging

• Log Emails: Enable Symfony’s mailer logger in config/packages/dev/monolog.yaml:

  handlers:
      mailer:
          type: stream
          path: '%kernel.logs_dir%/%kernel.environment%.mailer.log'
          level: debug
          channels: ['mailer']
  

• Check Config: Dump the resolved config to verify settings:

  use Symfony\Component\DependencyInjection\ParameterBag\ParameterBagInterface;
  
  public function __construct(ParameterBagInterface $params) {
      dump($params->get('two_le_mailer'));
  }
  

Extension Points

1. Custom Mailer: Implement TwoLE\MailerBundle\Mailer\MailerInterface for custom transport (e.g., SES, SendGrid):

   class CustomMailer implements MailerInterface {
       public function send(Mail $mail) { /* ... */ }
   }
   

   Register as a service and set in config:

   two_le_mailer:
       mailer: 'app.custom_mailer'
   

2. Template Overrides: Override default templates by placing files in templates/TwoLEMailerBundle/mail/.

3. Recipient Validation: Extend TwoLE\MailerBundle\Validator\RecipientValidator to add custom validation logic (e.g., domain checks).

4. Events: Listen for mailer.send events to intercept/modify emails:

   $eventDispatcher->addListener(MailerEvents::SEND, function (MailerEvent $event) {
       $event->getMail()->setSubject('[MODIFIED] ' . $event->getMail()->getSubject());
   });