Mail Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require zetacomponents/mail
   

   Add to composer.json under require if not auto-loaded.

2. Basic Configuration: Locate the zetacomponents/mail config file (auto-published to config/mail.php if using Laravel’s package auto-discovery). Configure default SMTP/transport settings:

   'transport' => [
       'type' => 'smtp',
       'host' => env('MAIL_HOST'),
       'port' => env('MAIL_PORT'),
       'auth' => true,
       'username' => env('MAIL_USERNAME'),
       'password' => env('MAIL_PASSWORD'),
   ],
   

3. First Use Case: Send a plain-text email:

   use Zeta\Mail\Message;
   
   $message = new Message();
   $message->setFrom('sender@example.com')
           ->addTo('recipient@example.com')
           ->setSubject('Hello from ZetaMail')
           ->setBody('This is a test email.');
   
   $mailer = new \Zeta\Mail\Mailer();
   $mailer->send($message);
   

   Key Files:

   • config/mail.php (config)
   • vendor/zetacomponents/mail/src/ (source code for reference)

Implementation Patterns

Core Workflows

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

   $message = new Message();
   $message->setFrom('no-reply@app.com')
           ->addTo('user@example.com')
           ->addCc('manager@example.com')
           ->setSubject('Your Order Confirmation')
           ->setBody('Order #12345 confirmed.')
           ->addAttachment('/path/to/file.pdf', 'invoice.pdf');
   

2. HTML Emails: Use setBody() with HTML content or leverage templates:

   $message->setBody(file_get_contents('resources/views/emails/welcome.blade.php'));
   

3. Templates with Laravel Views: Extend Laravel’s Blade integration by passing data to the Message body:

   $viewData = ['name' => 'John'];
   $message->setBody(view('emails.welcome', $viewData)->render());
   

4. Queueing Emails: Wrap the mailer in a job for async processing:

   use Zeta\Mail\Jobs\SendMailJob;
   
   SendMailJob::dispatch($message)->onQueue('emails');
   

5. Transport Switching: Dynamically switch transports (e.g., SMTP → Mailgun) via config or runtime:

   $mailer->setTransport('mailgun');
   

Integration Tips

• Laravel Service Provider: Bind the mailer to Laravel’s IoC container for dependency injection:

  $this->app->singleton(\Zeta\Mail\Mailer::class, function ($app) {
      return new \Zeta\Mail\Mailer($app['config']['mail']);
  });
  

• Event Listeners: Hook into Zeta\Mail\Events\MessageSent to log or analyze sent emails:

  event(new \Zeta\Mail\Events\MessageSent($message));
  

• Testing: Use a null transport for unit tests:

  $mailer->setTransport('null');
  

Gotchas and Tips

Pitfalls

1. Deprecated Methods: Avoid Zeta\Mail\Message::send() (deprecated in favor of Mailer::send()).

2. Attachment Handling: Ensure attachments are readable by the PHP process (check file permissions).

3. HTML Encoding: Manually encode HTML entities if sending raw HTML to avoid XSS warnings:

   $message->setBody(htmlspecialchars($htmlContent, ENT_QUOTES, 'UTF-8'));
   

4. Config Overrides: Runtime transport changes may not persist across requests (reconfigure per request if needed).

5. No Laravel-Specific Features: Lacks built-in queue workers, notifications, or mailables (use Laravel’s Mailable for advanced features).

Debugging

• Enable Logging: Configure the Zeta\Mail\Logger to debug issues:

  $mailer->setLogger(new \Zeta\Mail\Logger\FileLogger('/path/to/debug.log'));
  

• Check Transport Errors: Wrap Mailer::send() in a try-catch to catch transport-specific exceptions:

  try {
      $mailer->send($message);
  } catch (\Zeta\Mail\Exception\TransportException $e) {
      Log::error('Mail failed: ' . $e->getMessage());
  }
  

Extension Points

1. Custom Transports: Implement Zeta\Mail\Transport\TransportInterface for new protocols (e.g., SES, SendGrid):

   class CustomTransport implements TransportInterface {
       public function send(Message $message) { ... }
   }
   

2. Message Events: Extend Zeta\Mail\Events\MessageSent to trigger custom logic:

   class CustomEvent extends MessageSent {
       public function handle() {
           // Custom logic (e.g., analytics)
       }
   }
   

3. Attachment Filters: Override Zeta\Mail\Message::addAttachment() to validate or transform attachments:

   $message->addAttachment($path, $name, [
       'filter' => function ($content) {
           return str_replace('old', 'new', $content);
       }
   ]);
   

4. Laravel Mail Facade: Create a facade for seamless Laravel integration:

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

   Bind in a service provider:

   $this->app->bind('zetamail.mailer', function ($app) {
       return new \Zeta\Mail\Mailer($app['config']['mail']);
   });
   

   Usage:

   \Mail::send($message);