Laminas Mail Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laminas/laminas-mail
   

   (Note: Due to abandonment, consider alternatives like symfony/mailer for new projects.)

2. Basic Email Composition:

   use Laminas\Mail\Message;
   use Laminas\Mail\Transport\Sendmail;
   
   $message = new Message();
   $message->setBody('Hello, World!')
           ->setFrom('sender@example.com')
           ->addTo('recipient@example.com')
           ->setSubject('Test Email');
   
   $transport = new Sendmail();
   $transport->send($message);
   

3. SMTP Transport (Recommended for Production):

   use Laminas\Mail\Transport\Smtp;
   
   $transport = new Smtp([
       'host'     => 'smtp.example.com',
       'port'     => 587,
       'username' => 'user@example.com',
       'password' => 'password',
       'ssl'      => 'tls',
   ]);
   $transport->send($message);
   

First Use Case

Send a multipart email (HTML + Plaintext fallback):

$message = new Message();
$message->setBody('Plaintext fallback')
        ->setEncoding('UTF-8')
        ->getBody()
        ->setType('text/plain; charset=UTF-8');

$htmlBody = new \Laminas\Mime\Part('HTML content');
$htmlBody->setType('text/html; charset=UTF-8');

$body = new \Laminas\Mime\Message();
$body->setParts([$message->getBody(), $htmlBody]);
$message->setBody($body);

Implementation Patterns

Core Workflows

1. Message Composition:

   • Use Laminas\Mail\Message for headers (From, To, Subject).
   • Attachments via Laminas\Mime\Part:

     $attachment = new \Laminas\Mime\Part(file_get_contents('file.pdf'));
     $attachment->disposition = \Laminas\Mime\Mime::DISPOSITION_ATTACHMENT;
     $attachment->filename = 'file.pdf';
     $body->addPart($attachment);
     

2. Transport Abstraction:

   • Sendmail: Simple, local delivery (dev/testing).
   • SMTP: Production-ready with auth (TLS/SSL).
   • Custom Transport: Implement TransportInterface for APIs (e.g., AWS SES):

     class SesTransport implements TransportInterface {
         public function send(Message $message) { /* AWS SDK logic */ }
     }
     

3. Bulk Emails:

   $message = new Message();
   $message->setFrom('sender@example.com')
           ->setSubject('Newsletter');
   
   $transport = new Smtp([...]);
   foreach ($recipients as $email) {
       $clone = clone $message;
       $clone->addTo($email);
       $transport->send($clone);
   }
   

Integration Tips

• Laravel Service Provider:

  $this->app->singleton('mail.transport', function ($app) {
      return new Smtp([
          'host' => config('mail.host'),
          'port' => config('mail.port'),
          // ...
      ]);
  });
  

• Queueable Emails: Use Laravel’s queue system to defer sending:

  Mail::queue($message);
  

  (Note: Requires custom queue driver integration.)

• Templates: Combine with laminas/laminas-view for dynamic content:

  $view = new \Laminas\View\PhpRenderer();
  $html = $view->render('email-template', ['user' => $user]);
  $message->setBody($html)->setType('text/html');
  

Gotchas and Tips

Pitfalls

1. Deprecation Warning:

   • The package is abandoned. Prefer symfony/mailer for new projects.
   • Key differences:
     • Symfony Mailer uses SwiftMailer under the hood (more features).
     • Laminas Mail lacks modern auth plugins (e.g., OAuth2).

2. SMTP Timeouts:

   • Default timeout is 10 seconds. Increase for unreliable connections:

     $transport = new Smtp([...]);
     $transport->setTimeout(30); // 30 seconds
     

3. Header Injection:

   • Sanitize user input in To/Subject fields to prevent header injection:

     $subject = filter_var($userInput, FILTER_SANITIZE_STRING);
     $message->setSubject($subject);
     

4. Multipart Boundary Issues:

   • Ensure boundary is unique per message:

     $body = new \Laminas\Mime\Message();
     $body->setBoundary(md5(uniqid()));
     

5. Sendmail Quirks:

   • On Windows, use -f flag explicitly:

     $transport = new Sendmail(['from' => 'sender@example.com']);
     

Debugging

• Enable Verbose SMTP:

  $transport = new Smtp([...]);
  $transport->setDebug(true); // Logs to stderr
  

• Check Raw Email: Use File transport to inspect output:

  $transport = new \Laminas\Mail\Transport\File('path/to/emails');
  $transport->send($message); // Saves to file
  

Extension Points

1. Custom Transports: Implement TransportInterface for APIs (e.g., SendGrid):

   class SendGridTransport implements TransportInterface {
       public function send(Message $message) {
           $client = new \SendGrid\Client(config('services.sendgrid.key'));
           $client->send($message->toString());
       }
   }
   

2. Event Listeners: Extend Laminas\Mail\Message to add pre-send logic:

   $message->getEventManager()->attach('send', function ($event) {
       $event->getMessage()->addHeader('X-Custom', 'Value');
   });
   

3. Override Defaults: Configure transports globally via config/autoload/mail.global.php:

   return [
       'transports' => [
           'smtp' => [
               'host' => 'smtp.example.com',
               'port' => 587,
           ],
       ],
   ];
   

Performance Tips

• Reuse Transports: Instantiate transports once (e.g., in a service container) to avoid reconnection overhead.
• Batch Emails: For bulk sends, use a loop with cloned messages (avoid recreating transports):

  $transport = new Smtp([...]);
  foreach ($emails as $email) {
      $msg = clone $baseMessage;
      $msg->addTo($email);
      $transport->send($msg);
  }
  

Laravel-Specific

• Mail Facade Integration: Create a facade to bridge Laminas Mail with Laravel’s Mail facade:

  // app/Facades/Mail.php
  namespace App\Facades;
  
  use Illuminate\Support\Facades\Facade;
  
  class Mail extends Facade {
      protected static function getFacadeAccessor() {
          return 'laminas.mail';
      }
  }
  

• Queue Integration: Implement a queue driver for laminas/mail:

  // app/Providers/QueueServiceProvider
  $this->app->extend('queue.worker', function ($worker) {
      $worker->pushOn('mail', function ($job, $data) {
          $transport = app('mail.transport');
          $transport->send($job->mail);
      });
      return $worker;
  });