Mailer Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cleentfaar/mailer-bundle
   

   Add to config/bundles.php (Symfony) or config/app.php (Laravel via Symfony bridge):

   Cleentfaar\MailerBundle\CleentfaarMailerBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="Cleentfaar\MailerBundle\CleentfaarMailerBundle" --tag="config"
   

   Edit config/cleentfaar_mailer.php to define your mailers (e.g., smtp, sendgrid).

3. First Use Case Inject the mailer service into a controller/service:

   use Cleentfaar\MailerBundle\Mailer\MailerInterface;
   
   class UserController extends Controller
   {
       public function __construct(private MailerInterface $mailer) {}
   
       public function sendWelcomeEmail()
       {
           $this->mailer->send(
               new Email('welcome@example.com', 'Welcome!')
                   ->from('noreply@example.com')
                   ->text('Hello, welcome!')
           );
       }
   }
   

Implementation Patterns

Core Workflows

1. Email Composition Use the Email class to build emails programmatically:

   $email = new Email('user@example.com', 'Subject')
       ->from('app@example.com')
       ->html('<h1>Hello</h1>')
       ->attach('path/to/file.pdf');
   

2. Transport Integration Configure transports in config/cleentfaar_mailer.php:

   'transports' => [
       'smtp' => [
           'host' => env('MAIL_HOST'),
           'port' => env('MAIL_PORT'),
           // ...
       ],
       'sendgrid' => [
           'api_key' => env('SENDGRID_API_KEY'),
       ],
   ],
   

3. Dynamic Mailer Selection Use the MailerInterface to switch transports at runtime:

   $this->mailer->setTransport('sendgrid')->send($email);
   

4. Event Listeners Attach listeners for pre/post-send hooks:

   $mailer->addListener(new class implements MailerListenerInterface {
       public function onSend(Email $email, TransportInterface $transport) {
           // Log or modify email before sending
       }
   });
   

5. Testing Use the NullTransport for unit tests:

   $mailer = new Mailer(new NullTransport());
   $mailer->send($email); // No actual sending
   

Gotchas and Tips

Pitfalls

1. Transport Configuration

   • Forgetting to set default_transport in config will throw RuntimeException.
   • API keys (e.g., SendGrid) must be properly escaped in .env to avoid config parsing errors.

2. Email Validation

   • The bundle does not validate email addresses by default. Use a library like egulias/email-validator if needed.

3. Attachments

   • Large attachments may exceed SMTP limits. For SendGrid, ensure max_file_size is configured.

4. Symfony vs. Laravel

   • If using Laravel, wrap the bundle in a Symfony bridge or use Symfony\Component\HttpKernel\Kernel directly.

Debugging

• Enable debug mode in config:

  'debug' => env('APP_DEBUG', false),
  

  Logs sent emails to storage/logs/mailer.log.

• Check transport-specific errors in var/log/dev.log (Symfony) or Laravel’s storage/logs/laravel.log.

Extension Points

1. Custom Transports Implement Cleentfaar\MailerBundle\Transport\TransportInterface:

   class MyTransport implements TransportInterface {
       public function send(Email $email): void {
           // Custom logic (e.g., HTTP API calls)
       }
   }
   

   Register in config:

   'transports' => [
       'my_transport' => MyTransport::class,
   ],
   

2. Email Events Extend Cleentfaar\MailerBundle\Event\EmailEvent for custom events (e.g., EmailSent).

3. Templating Integrate with Twig or Blade by extending the Email class:

   $email->html(view('emails.welcome', ['user' => $user])->render());
   

Performance Tips

• Batch Processing: Use Mailer::flush() to send queued emails in bulk.
• Caching: Cache transport configurations if using multiple environments.