Shwanix Mailer Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require mahrdanial/shwanix-mailer
   

2. Configure the mailer:

   • Publish the config file:

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

   • Update config/mail.php to set MAIL_MAILER=shwanix.
   • Configure config/shwanix-mail.php with your Shwanix API endpoint, API key, and optional settings (timeouts, SSL verification).

3. First use case: Send a test email using Laravel’s built-in Mail facade:

   use Illuminate\Support\Facades\Mail;
   use App\Mail\TestMail;
   
   Mail::to('user@example.com')->send(new TestMail());
   

   The email will be sent via Shwanix’s HTTP API instead of SMTP.

Implementation Patterns

Standard Laravel Mail Workflows

• Mailables: Use existing App\Mail\* classes without modification.

  Mail::to('recipient@example.com')->send(new WelcomeEmail($user));
  

• Queued Emails: Works seamlessly with Laravel queues.

  Mail::to('user@example.com')->queue(new OrderConfirmation($order));
  

• Markdown Emails: Supports Blade templates and Markdown mailables.

  Mail::markdown('emails.welcome')->to('user@example.com')->send();
  

API-Specific Patterns

• Custom Headers: Pass additional headers via the withSwiftMessage method:

  Mail::to('user@example.com')->withSwiftMessage(function ($message) {
      $message->getHeaders()->addTextHeader('X-Custom-Header', 'value');
  })->send(new TestMail());
  

• Attachments: Use Laravel’s built-in attachment methods:

  Mail::to('user@example.com')->attach($pathToFile)->send(new TestMail());
  

• Async Processing: Leverage Laravel’s queue workers for background processing:

  php artisan queue:work
  

Integration with Shwanix API

• API Key Rotation: Update config/shwanix-mail.php dynamically (e.g., via environment variables or a config service).
• Endpoint Switching: Use environment-based config (e.g., staging.shwanix-api.com vs. api.shwanix.com).
• Error Handling: Catch GuzzleException for API failures:

  try {
      Mail::to('user@example.com')->send(new TestMail());
  } catch (\GuzzleHttp\Exception\RequestException $e) {
      Log::error('Shwanix API error: ' . $e->getMessage());
      // Fallback to another mailer (e.g., SMTP)
  }
  

Gotchas and Tips

Pitfalls

1. Laravel Version Mismatch:

   • Laravel 7.x requires PHP 8.0+ (via 7.30.x). Installing on older Laravel 7 versions will fail.
   • Laravel 11+ requires PHP 8.2+ (framework constraint).
   • Fix: Update Laravel or PHP version to meet requirements.

2. SwiftMailer vs. Symfony Mailer:

   • Laravel 7–8 use SwiftShwanixTransport (SwiftMailer).
   • Laravel 9+ use ApiTransport (Symfony Mailer).
   • Tip: If migrating between versions, test email rendering (e.g., HTML/Markdown) for compatibility.

3. API Rate Limits:

   • Shwanix may throttle requests. Monitor config/shwanix-mail.php for timeout/retries.
   • Tip: Implement exponential backoff in custom logic:

     $client->setDefaultOption('timeout', 30);
     $client->setDefaultOption('connect_timeout', 5);
     

4. Missing Config:

   • Forgetting to publish config/shwanix-mail.php will throw Configuration not found errors.
   • Fix: Run php artisan vendor:publish --tag=shwanix-mailer-config and update .env:

     SHWANIX_API_KEY=your_key_here
     SHWANIX_API_URL=https://api.shwanix.com/send
     

Debugging

• Enable Guzzle Logging: Add to config/shwanix-mail.php:

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

  Logs will appear in Laravel’s log channel.

• Test with MAIL_MAILER=log: Temporarily switch to the log mailer to verify email content before sending:

  MAIL_MAILER=log
  

Extension Points

1. Custom Transport: Extend ShwanixTransport for additional API features:

   namespace App\Mail\Transports;
   
   use Mahrdanial\ShwanixMailer\Transports\ShwanixTransport;
   
   class CustomShwanixTransport extends ShwanixTransport {
       public function sendSwiftMessage(Swift_Message $message) {
           // Add custom logic (e.g., pre-process attachments)
           return parent::sendSwiftMessage($message);
       }
   }
   

   Register in AppServiceProvider:

   Mail::extend('custom_shwanix', function () {
       return new CustomShwanixTransport();
   });
   

2. Fallback to SMTP: Implement a fallback mailer in AppServiceProvider:

   Mail::extend('shwanix_fallback', function () {
       $shwanix = new \Mahrdanial\ShwanixMailer\Transports\ShwanixTransport();
       return function ($message) use ($shwanix) {
           try {
               $shwanix->sendSwiftMessage($message);
           } catch (\Exception $e) {
               // Fallback to SMTP
               $smtp = new \Illuminate\Mail\Transport\SendmailTransport();
               $smtp->send($message);
           }
       };
   });
   

3. Environment-Specific Config: Use Laravel’s config() helper to dynamically load settings:

   $apiKey = config('services.shwanix.key', env('SHWANIX_API_KEY'));
   

Performance Tips

• Batch Processing: For bulk emails, use Laravel’s Mail::batch():

  Mail::batch([])->to('user@example.com')->send(new Newsletter());
  

• Queue Priorities: Assign priorities to time-sensitive emails:

  Mail::to('user@example.com')->later(now()->addMinutes(5), new Reminder())->onQueue('high');