Yii2 Swiftmailer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require yiisoft/yii2-swiftmailer
   

   Add to your config/web.php (or console.php for CLI emails):

   'components' => [
       'mailer' => [
           'class' => 'yii\swiftmailer\Mailer',
           'useFileTransport' => false, // Set to true for debugging
           'transport' => [
               'class' => 'Swift_SmtpTransport',
               'host' => 'smtp.example.com',
               'username' => 'user@example.com',
               'password' => 'password',
               'port' => '587',
               'encryption' => 'tls',
           ],
       ],
   ],
   

2. First Use Case: Send a simple email in a controller:

   Yii::$app->mailer->compose()
       ->setTo('recipient@example.com')
       ->setSubject('Hello!')
       ->setTextBody('This is a test email.')
       ->send();
   

3. Where to Look First:

   • SwiftMailer Documentation
   • Yii2-Swiftmailer README (if available)
   • vendor/yiisoft/yii2-swiftmailer/src/Mailer.php for core logic.

Implementation Patterns

Common Workflows

1. Dynamic Email Templates: Use compose() with views for reusable templates:

   Yii::$app->mailer->compose('emails/welcome', ['user' => $user])
       ->setFrom(['noreply@example.com' => 'Example'])
       ->setTo($user->email)
       ->setSubject('Welcome!')
       ->send();
   

2. Attachments:

   $message = Yii::$app->mailer->compose()
       ->setFrom(['from@example.com' => 'From'])
       ->setTo('to@example.com')
       ->setSubject('With Attachment')
       ->attach(Yii::getAlias('@webroot/files/report.pdf'));
   $message->send();
   

3. HTML + Plaintext Emails:

   Yii::$app->mailer->compose()
       ->setFrom(['from@example.com' => 'From'])
       ->setTo('to@example.com')
       ->setSubject('HTML Email')
       ->setHtmlBody('<b>HTML Content</b>')
       ->setTextBody('Plaintext fallback')
       ->send();
   

4. Queueing Emails (with yii2-queue):

   Yii::$app->mailer->compose()
       ->setTo('recipient@example.com')
       ->setSubject('Queued Email')
       ->setTextBody('This will be sent later.')
       ->queue(); // Uses Yii's queue system
   

5. Customizing Headers:

   $message = Yii::$app->mailer->compose();
   $message->getHeaders()->addTextHeader('X-Custom-Header', 'value');
   $message->send();
   

Integration Tips

• Validation: Use Yii's validators (e.g., EmailValidator) to validate email addresses before sending.
• Logging: Enable useFileTransport in development to log emails to runtime/mail.
• Environment Config: Store SMTP credentials in .env and load them via Yii::$app->params.
• Rate Limiting: Implement middleware to throttle email sending (e.g., for bulk operations).

Gotchas and Tips

Pitfalls

1. SMTP Connection Issues:

   • Symptom: Emails silently fail or time out.
   • Fix: Verify host, port, encryption (e.g., tls/ssl), and credentials. Test with useFileTransport first.
   • Debugging: Check SwiftMailer's logger or enable Yii's debug mode:

     'components' => [
         'mailer' => [
             'class' => 'yii\swiftmailer\Mailer',
             'transport' => [
                 'logging' => true, // Enable SwiftMailer logging
             ],
         ],
     ],
     

2. HTML Emails Rendering Incorrectly:

   • Cause: Missing CSS or inline styles.
   • Fix: Use tools like MJML or Foundation for Emails for responsive templates.

3. Queue Not Working:

   • Cause: Missing queue component or misconfigured queue() method.
   • Fix: Ensure yii2-queue is installed and configured. Use send() instead of queue() for immediate delivery.

4. Character Encoding Issues:

   • Fix: Explicitly set encoding:

     Yii::$app->mailer->compose()
         ->setCharSet('UTF-8')
         ->setSubject('Subject with UTF-8: café')
         ->send();
     

5. Memory Limits:

   • Cause: Large attachments or complex templates exceed PHP's memory_limit.
   • Fix: Increase memory_limit in php.ini or optimize attachments (e.g., compress files).

Tips

1. Reusable Components: Create a MailService class to encapsulate common logic:

   class MailService {
       public function sendWelcomeEmail($user) {
           Yii::$app->mailer->compose(['html' => 'emails/welcome.html', 'text' => 'emails/welcome.txt'], ['user' => $user])
               ->setFrom(['noreply@example.com' => 'Example'])
               ->setTo($user->email)
               ->setSubject('Welcome!')
               ->send();
       }
   }
   

2. Testing:

   • Use useFileTransport to test emails without sending:

     'mailer' => [
         'useFileTransport' => true,
     ],
     

   • Check logged emails in runtime/mail.

3. Performance:

   • Batch emails for bulk sends (e.g., newsletters) to avoid rate limits.
   • Use Swift_EventDispatcher to optimize transport (e.g., connection pooling).

4. Security:

   • Avoid hardcoding credentials; use .env or secure vaults.
   • Sanitize email content to prevent header injection:

     $message->setSubject(Yii::$app->security->encode(Yii::$app->request->post('subject')));
     

5. Extending SwiftMailer:

   • Override Mailer class to add custom methods:

     class CustomMailer extends \yii\swiftmailer\Mailer {
         public function sendTransactional($view, $model) {
             // Custom logic
         }
     }
     

   • Register your class in config/web.php:

     'mailer' => ['class' => 'app\mail\CustomMailer'],
     

6. Debugging:

   • Enable SwiftMailer's debug mode:

     'transport' => [
         'debug' => true,
     ],
     

   • Check Yii's logs for SwiftMailer errors (e.g., Swift_TransportException).