Mailerbundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle to your composer.json:

   composer require cekurte/mailerbundle
   

   Enable the bundle in config/bundles.php:

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

2. Configuration Publish the default config:

   php artisan vendor:publish --tag=mailer-config
   

   Update config/mailer.php with your Mail2Easy API credentials (client ID, client secret, and environment).

3. First Use Case Send a test email via a Symfony Controller:

   use Cekurte\MailerBundle\Mailer\MailerService;
   
   class TestController extends Controller
   {
       public function sendTestEmail(MailerService $mailer)
       {
           $mailer->send([
               'to' => 'recipient@example.com',
               'subject' => 'Test Email',
               'body' => 'Hello from Mail2Easy!',
           ]);
           return response()->json(['status' => 'Email sent']);
       }
   }
   

Implementation Patterns

Core Workflows

1. Email Sending Use the MailerService to send emails with structured data:

   $mailer->send([
       'to' => ['user1@example.com', 'user2@example.com'],
       'cc' => 'cc@example.com',
       'bcc' => 'bcc@example.com',
       'subject' => 'Your Subject',
       'body' => 'Email content',
       'html_body' => '<strong>HTML content</strong>', // Optional
       'attachments' => ['/path/to/file.pdf'], // Optional
   ]);
   

2. Templates Integrate with Mail2Easy templates by referencing them in the body or html_body fields:

   $mailer->send([
       'to' => 'user@example.com',
       'subject' => 'Welcome!',
       'body' => '{{template_id}}', // Replace with Mail2Easy template ID
   ]);
   

3. Async Processing Queue emails for background processing (if supported by the bundle):

   $mailer->queue([
       'to' => 'user@example.com',
       'subject' => 'Async Email',
       'body' => 'This will be sent later.',
   ]);
   

4. Event Listeners Subscribe to email events (e.g., mailer.send or mailer.failed) via Symfony’s event dispatcher:

   // In a service or controller
   $dispatcher->addListener('mailer.send', function ($event) {
       // Log or process sent emails
   });
   

Integration Tips

• Laravel-Specific: Use dependency injection to inject MailerService into controllers/services.
• Validation: Validate recipient lists and attachments before sending.
• Logging: Enable Monolog to track email failures:

  'logging' => [
      'enabled' => true,
      'channel' => 'mailer',
  ],
  

• Testing: Mock MailerService in PHPUnit:

  $this->mock(MailerService::class)->shouldReceive('send')->once();
  

Gotchas and Tips

Pitfalls

1. API Rate Limits Mail2Easy may throttle requests. Implement retries with exponential backoff:

   $mailer->setRetryPolicy(new RetryPolicy(3, 1000)); // 3 retries, 1s delay
   

2. Template IDs Hardcoding template IDs in code violates DRY. Store them in config or a database:

   config(['mailer.templates.welcome' => 'template_123']);
   

3. Attachment Size Limits Mail2Easy may reject large attachments. Validate files before upload:

   if ($file->getSize() > 5 * 1024 * 1024) { // 5MB
       throw new \RuntimeException('Attachment too large');
   }
   

4. Locale/Encoding Issues Ensure body and subject use UTF-8 encoding. For non-Latin scripts, test thoroughly.

5. Symfony vs. Laravel Conflicts The bundle is Symfony-focused. In Laravel, resolve conflicts by:

   • Overriding the MailerService binding in AppServiceProvider:

     $this->app->bind(MailerService::class, function ($app) {
         return new MailerService($app['config']['mailer']);
     });
     

Debugging

• Enable Debug Mode Set 'debug' => true in config/mailer.php to log raw API responses.

• Check API Credentials Verify client_id and client_secret in the config. Use the Mail2Easy dashboard to regenerate credentials if needed.

• Validate API Endpoints Ensure the environment (e.g., sandbox or production) matches your Mail2Easy setup.

Extension Points

1. Custom Mailer Classes Extend MailerService to add domain-specific logic:

   class CustomMailer extends MailerService
   {
       public function sendWelcomeEmail($user)
       {
           $this->send([
               'to' => $user->email,
               'subject' => 'Welcome, ' . $user->name,
               'body' => config('mailer.templates.welcome'),
           ]);
       }
   }
   

2. Event-Driven Extensions Dispatch custom events for pre/post-send actions:

   // In MailerService
   $dispatcher->dispatch(new EmailSentEvent($emailData));
   

3. Queue Integration If the bundle lacks queue support, wrap MailerService in a queueable job:

   class SendEmailJob implements ShouldQueue
   {
       use Dispatchable, InteractsWithQueue, Queueable;
   
       public function handle(MailerService $mailer)
       {
           $mailer->send($this->emailData);
       }
   }
   

4. Fallback to Local Mailer Implement a fallback to Laravel’s default mailer if Mail2Easy fails:

   try {
       $mailer->send($data);
   } catch (\Exception $e) {
       Mail::raw($data['body'], function ($message) use ($data) {
           $message->to($data['to'])->subject($data['subject']);
       });
   }