Mailing Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cnerta/mailing-bundle:dev-master
   

   Register the bundle in config/bundles.php (Symfony 4+):

   return [
       // ...
       Cnerta\MailingBundle\CnertaMailingBundle::class => ['all' => true],
   ];
   

2. Configuration (config/packages/cnerta_mailing.yaml):

   cnerta_mailing:
       default_bundle: "AppBundle"  # Replace with your bundle name
       active_log: true
       from_email:
           address: "noreply@example.com"
           name: "Your App"
   

3. First Email:

   • Create a Twig template at templates/emails/your_email.html.twig.
   • Use the service in a controller:

     use Cnerta\MailingBundle\Service\MailingService;
     
     class YourController extends AbstractController {
         public function sendEmail(MailingService $mailingService) {
             $mailingService->sendEmail(
                 'your_email',  // Template name (without extension)
                 ['to' => 'user@example.com'],
                 ['name' => 'John']  // Template variables
             );
         }
     }
     

Implementation Patterns

Common Workflows

1. Template Organization:

   • Store templates in templates/emails/ (e.g., welcome.html.twig).
   • Reference templates by filename (without .twig) in sendEmail().

2. Dynamic Recipients:

   $recipients = ['user1@example.com', 'user2@example.com'];
   $mailingService->sendEmail('newsletter', ['to' => $recipients], ['content' => $data]);
   

3. Attachments:

   $mailingService->sendEmail(
       'invoice',
       ['to' => 'client@example.com'],
       ['amount' => 100],
       ['attachments' => ['/path/to/invoice.pdf']]
   );
   

4. Async Sending (if supported):

   $mailingService->sendEmailAsync('reminder', ['to' => 'user@example.com'], []);
   

Integration Tips

• SwiftMailer Integration: Configure swiftmailer in config/packages/mailer.yaml to ensure compatibility:

  framework:
      mailer:
          dsn: '%env(MAILER_DSN)%'
  

• Event Listeners: Extend functionality by subscribing to cnerta.mailing.send events (if documented).

• Testing: Use Symfony’s Mailer component to mock emails in tests:

  $this->mailer->assertSentCount(1);
  

Gotchas and Tips

Pitfalls

1. Deprecated Symfony2:

   • The bundle targets Symfony 2.x, so features like AbstractController or Mailer may not work directly. Use SwiftMailer directly if needed:

     $this->get('mailer')->send($message);
     

2. Template Paths:

   • Templates must be in templates/emails/ under the configured default_bundle. Misplaced templates will throw errors.

3. No Laravel Port:

   • This is a Symfony bundle, not Laravel-compatible. For Laravel, consider:
     • spatie/laravel-mailables (for templates).
     • laravel-notification-channels/mail (for notifications).

4. Logging:

   • active_log: true logs emails to var/log/cnerta_mailing.log. Disable in production if sensitive data is sent.

Debugging

• Check Logs:

  tail -f var/log/cnerta_mailing.log
  

• Validate Templates: Ensure Twig templates render without errors. Test with:

  $mailingService->renderTemplate('your_email', ['name' => 'Test']);
  

Extension Points

1. Custom Services: Extend Cnerta\MailingBundle\Service\MailingService to add features (e.g., rate limiting).

2. Override Templates: Use Symfony’s template inheritance to override default emails.

3. SwiftMailer Plugins: Integrate custom SwiftMailer plugins for advanced features (e.g., HTML parsing).

Laravel Alternatives

If migrating to Laravel, consider:

• Mailables: php artisan make:mail OrderShipped
• Notifications: php artisan make:notification OrderShipped
• Packages: spatie/laravel-mailables, laravel-notification-channels/mail.