Clickatell Notifier Laravel Package

Getting Started

Minimal Setup for Laravel

1. Install Dependencies:

   composer require symfony/clickatell-notifier symfony/http-client
   

   (Note: Laravel’s native Http facade can replace symfony/http-client if preferred.)

2. Configure DSN in .env:

   CLICKATELL_DSN=clickatell://ACCESS_TOKEN@default?from=YOUR_SENDER_ID
   

   • Replace ACCESS_TOKEN with your Clickatell API key.
   • from is the sender ID (e.g., YourApp).

3. Create a Laravel Service Provider:

   // app/Providers/ClickatellNotifierProvider.php
   use Symfony\Component\Notifier\Clickatell\ClickatellTransport;
   use Symfony\Contracts\HttpClient\HttpClientInterface;
   use Illuminate\Support\ServiceProvider;
   
   class ClickatellNotifierProvider extends ServiceProvider
   {
       public function register()
       {
           $this->app->singleton('clickatell.transport', function ($app) {
               $dsn = env('CLICKATELL_DSN');
               $httpClient = $app->make(HttpClientInterface::class); // or use Laravel's Http
               return new ClickatellTransport($dsn, $httpClient);
           });
       }
   }
   

   Register the provider in config/app.php.

4. First Use Case: Send an SMS

   use Symfony\Component\Notifier\Message\SmsMessage;
   use Symfony\Component\Notifier\NotifierInterface;
   
   $notifier = new class implements NotifierInterface {
       public function __construct(private $transport) {}
       public function send(SmsMessage $message) {
           return $this->transport->send($message);
       }
   };
   
   $transport = app('clickatell.transport');
   $notifier = new $notifier($transport);
   
   $notifier->send(
       new SmsMessage('Hello from Laravel!', '1234567890')
   );
   

Where to Look First

• DSN Configuration: Validate CLICKATELL_DSN in .env (critical for connectivity).
• Symfony Notifier Docs: Symfony Notifier Overview for message/transport patterns.
• Clickatell API Limits: Check Clickatell’s rate limits to avoid throttling.
• Laravel HTTP Client: If using Laravel’s Http facade, wrap it in a Symfony\Contracts\HttpClient\HttpClientInterface adapter.

Implementation Patterns

Core Workflow: Sending Notifications

1. Define a Message:

   use Symfony\Component\Notifier\Message\SmsMessage;
   
   $message = new SmsMessage(
       'Your OTP is: 123456', // Body
       '1234567890',          // Recipient (string or array for bulk)
       'YOUR_SENDER_ID'       // Optional: Override DSN's 'from'
   );
   

2. Send via Transport:

   $transport = app('clickatell.transport');
   $result = $transport->send($message);
   

   • Returns a TransportResult with status (e.g., TransportResult::SUCCESS).

3. Handle Async Delivery (Optional): Use Laravel Queues to defer sending:

   use Illuminate\Support\Facades\Bus;
   
   Bus::dispatch(function () use ($message) {
       $transport->send($message);
   });
   

Integration Patterns

1. Laravel Events for Lifecycle Hooks

Extend Symfony’s TransportResult to trigger Laravel events:

// app/Providers/ClickatellNotifierProvider.php
public function boot()
{
    $this->app->afterResolving('clickatell.transport', function ($transport) {
        $transport->on('sent', function ($result) {
            event(new SmsSent($result->getMessage()));
        });
        $transport->on('failed', function ($result) {
            event(new SmsFailed($result->getMessage(), $result->getFailure()));
        });
    });
}

2. Bulk SMS with Arrays

Send to multiple recipients:

$message = new SmsMessage('Hello!', ['1234567890', '9876543210']);
$transport->send($message);

3. Custom Headers/Options

Pass Clickatell-specific options via SmsMessage:

$message = new SmsMessage('Hello', '1234567890');
$message->options()->set('priority', 'high'); // Clickatell-specific

4. Retry Logic with Laravel Queues

Use Laravel’s ShouldQueue for failed messages:

class SendSmsJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable;

    public function handle()
    {
        try {
            $transport->send($this->message);
        } catch (\Exception $e) {
            $this->release(60); // Retry after 1 minute
            throw $e;
        }
    }
}

Advanced Patterns

1. Template-Based Messages

Use Clickatell’s message templates:

$message = new SmsMessage(
    'Your {code} is valid for 5 minutes.',
    '1234567890',
    null, // No sender override
    ['code' => '123456'] // Template variables
);

2. Webhook Callbacks

Configure Clickatell to send delivery reports to a Laravel endpoint:

Route::post('/clickatell/webhook', function (Request $request) {
    // Parse Clickatell's webhook payload
    // Update DB or trigger events
});

(Note: Requires manual setup in Clickatell dashboard.)

3. Fallback Transports

Combine with other notifiers (e.g., email) for multi-channel delivery:

use Symfony\Component\Notifier\Notifier;

$notifier = new Notifier([
    app('clickatell.transport'),
    new MailTransport($mailer),
]);

$notifier->send($message); // Tries SMS first, falls back to email

Gotchas and Tips

Pitfalls

1. DSN Format Sensitivity:

   • Gotcha: clickatell://ACCESS_TOKEN@default?from=FROM is case-sensitive.
   • Fix: Use .env validation or a helper method:

     function validateClickatellDsn(string $dsn): void {
         if (!preg_match('/^clickatell:\/\/[^@]+@[^?]+(\?from=[^&]+)?$/', $dsn)) {
             throw new \InvalidArgumentException('Invalid Clickatell DSN format.');
         }
     }
     

2. Recipient Format:

   • Gotcha: Clickatell expects phone numbers as strings (not arrays) for single recipients.
   • Fix: Use SmsMessage constructor with a string:

     // Works:
     new SmsMessage('Hi', '1234567890');
     // Fails (throws exception):
     new SmsMessage('Hi', ['1234567890']); // Only works for bulk
     

3. Async Delivery Quirks:

   • Gotcha: Symfony Notifier’s async transport assumes Messenger; Laravel Queues require manual retry logic.
   • Fix: Use ShouldQueue with custom retry logic (as shown above).

4. Rate Limiting:

   • Gotcha: Clickatell throttles requests (e.g., 100 SMS/minute by default).
   • Fix: Implement exponential backoff in your transport:

     $transport->setMaxRetries(3);
     $transport->setRetryDelay(1000); // 1 second
     

5. Sender ID Restrictions:

   • Gotcha: Some countries require registered sender IDs (e.g., alphanumeric).
   • Fix: Check Clickatell’s sender ID guidelines and update your DSN’s from parameter.

Debugging Tips

1. Enable HTTP Logging:

   $httpClient = HttpClient::create([
       'headers' => ['User-Agent' => 'Laravel/Clickatell'],
       'debug' => true, // Logs requests/responses
   ]);
   

2. Inspect TransportResult:

   $result = $transport->send($message);
   if ($result->isSuccess()) {
       // Success!
   } else {
       \Log::error('SMS failed:', [