Smtp Notifications Channel Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aiqedge/smtp-notifications-channel
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       AIQEdge\SMTPNotificationsChannel\SMTPNotificationsChannelServiceProvider::class,
   ],
   

2. Publish Config (Optional)

   php artisan vendor:publish --provider="AIQEdge\SMTPNotificationsChannel\SMTPNotificationsChannelServiceProvider"
   

   Config file: config/smtp-notifications-channel.php.

3. First Use Case Create a notification class extending AIQEdge\SMTPNotificationsChannel\Messages\SMTPMessage:

   use AIQEdge\SMTPNotificationsChannel\Messages\SMTPMessage;
   use Illuminate\Notifications\Notification;
   
   class OrderShipped extends Notification
   {
       public function via($notifiable)
       {
           return ['smtp'];
       }
   
       public function toSMTP($notifiable)
       {
           return (new SMTPMessage)
               ->subject('Your Order Has Shipped!')
               ->greeting('Hi ' . $notifiable->name)
               ->line('Your order #12345 is now on its way!')
               ->action('Track Order', url('/track/12345'))
               ->line('Thank you for shopping with us!');
       }
   }
   

4. Send the Notification

   $user->notify(new OrderShipped());
   

Implementation Patterns

Core Workflow

1. Channel Configuration Configure SMTP settings in config/smtp-notifications-channel.php:

   'host' => env('SMTP_HOST'),
   'port' => env('SMTP_PORT'),
   'username' => env('SMTP_USERNAME'),
   'password' => env('SMTP_PASSWORD'),
   'encryption' => env('SMTP_ENCRYPTION'),
   'from' => [
       'address' => env('SMTP_FROM_ADDRESS'),
       'name' => env('SMTP_FROM_NAME'),
   ],
   

2. Customizing Messages Extend SMTPMessage to override defaults:

   public function toSMTP($notifiable)
   {
       return (new SMTPMessage)
           ->markdown('emails.order-shipped') // Use a custom markdown template
           ->with(['order' => $notifiable->order]);
   }
   

3. Dynamic Recipients Use notifiable data to dynamically set recipients:

   public function via($notifiable)
   {
       return $notifiable->prefers_smtp ? ['smtp'] : [];
   }
   

4. Queueing Notifications Queue notifications for async delivery:

   $user->notify((new OrderShipped())->delay(now()->addMinutes(5)));
   

5. Testing Use Laravel’s built-in notification testing:

   $notification = new OrderShipped();
   $this->assertCount(1, $notification->toSMTP($user)->lines);
   

Integration Tips

• Laravel Mail vs SMTP Channel Use this channel for transactional emails (e.g., order confirmations, password resets) where you need SMTP-specific features (e.g., custom headers, attachments via AIQEDGE-SMTP API). Use Laravel’s built-in Mail for marketing emails or when you need queues, retries, or events.

• Attachments Attach files via the attach() method:

  ->attach(storage_path('app/public/receipt.pdf'), [
      'as' => 'receipt.pdf',
      'mime' => 'application/pdf',
  ]);
  

• Custom Headers Add headers via the withHeaders() method:

  ->withHeaders(['X-Priority' => 'High', 'Reply-To' => 'support@example.com']);
  

• Fallback Channels Combine with other channels for fallback:

  public function via($notifiable)
  {
      return ['smtp', 'database']; // Fallback to database if SMTP fails
  }
  

• Logging Enable debug logging in config:

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

Gotchas and Tips

Pitfalls

1. Missing Config If notifications fail silently, check:

   • config/smtp-notifications-channel.php exists and is properly configured.
   • Environment variables (e.g., SMTP_HOST) are set in .env.

2. Authentication Issues

   • Ensure username and password are correct in config.
   • Test SMTP credentials separately (e.g., via telnet or swaks).

3. No Error Feedback The package lacks built-in error logging. Wrap notifications in a try-catch:

   try {
       $user->notify(new OrderShipped());
   } catch (\Exception $e) {
       \Log::error("SMTP Notification Failed: " . $e->getMessage());
   }
   

4. Template Paths Markdown templates must be in resources/views/emails/. If using custom paths, specify them explicitly:

   ->markdown('vendor.custom/emails.order-shipped')
   

5. Rate Limiting AIQEDGE-SMTP may throttle requests. Implement exponential backoff in your notification logic:

   $this->afterCommit(function () use ($notifiable) {
       if ($notifiable->failedSmtpAttempts >= 3) {
           $this->release(60); // Retry after 1 minute
       }
   });
   

Debugging

1. Enable Debug Mode Set 'debug' => true in config to log raw SMTP interactions to storage/logs/laravel.log.

2. Check Raw Message Dump the raw message before sending:

   $message = (new SMTPMessage)->subject('Test')->line('Hello');
   \Log::debug($message->getHeaders()->getAllHeaders());
   

3. Test with a Dummy SMTP Server Use a local SMTP server like MailHog for testing:

   'host' => 'localhost',
   'port' => 1025,
   

Extension Points

1. Custom SMTP Client Override the default Guzzle client by binding a new AIQEdge\SMTPNotificationsChannel\SMTPManager in a service provider:

   $this->app->bind(\AIQEdge\SMTPNotificationsChannel\SMTPManager::class, function () {
       return new CustomSMTPManager();
   });
   

2. Event Hooks Listen for SMTP events (e.g., SMTPNotificationSent):

   \Event::listen(\AIQEdge\SMTPNotificationsChannel\Events\SMTPNotificationSent::class, function ($event) {
       \Log::info("Sent to {$event->notifiable->email}");
   });
   

3. Custom Message Classes Extend SMTPMessage to add domain-specific methods:

   class InvoiceSMTPMessage extends SMTPMessage
   {
       public function addInvoiceDetails($invoice)
       {
           $this->line("Invoice #: {$invoice->number}");
           $this->line("Amount: {$invoice->amount}");
           return $this;
       }
   }
   

4. Queue Connection Use a custom queue connection for SMTP notifications:

   'queue' => 'smtp', // Define in config/queue.php
   

Pro Tips

• Dynamic "From" Address Override the from address per notification:

  ->from('noreply@clientdomain.com', 'Client Name')
  

• Localization Localize subject/body dynamically:

  ->subject(__('emails.order.shipped.subject'))
  ->line(__('emails.order.shipped.greeting', ['name' => $notifiable->name]))
  

• Bulk Notifications Use Laravel’s Notification::send() for bulk sends:

  Notification::send($users, new OrderShipped());
  

• Monitor Deliveries Track delivery status via AIQEDGE-SMTP API (if supported) and log outcomes:

  $this->afterCommit(function () use ($notifiable) {
      \Log::info("SMTP Notification queued for {$notifiable->email}");
  });