Octopush Notifier Laravel Package

Getting Started

Minimal Setup in Laravel

1. Install Dependencies (via Composer):

   composer require symfony/http-client symfony/notifier
   

   Note: Laravel doesn’t natively support Symfony Notifier, so this is a manual integration.

2. Configure DSN in .env:

   OCTOPUSH_DSN=octopush://USERLOGIN:APIKEY@default?from=SENDER&type=FR
   

   • Replace USERLOGIN, APIKEY, SENDER (e.g., YourApp), and type (XXX/FR/WWW).

3. First Use Case: Send an SMS Create a service to bridge Symfony Notifier with Laravel:

   // app/Services/OctopushNotifier.php
   use Symfony\Component\Notifier\Notifier;
   use Symfony\Component\Notifier\Transport\OctopushTransport;
   
   class OctopushNotifier
   {
       public function send(string $to, string $message): void
       {
           $dsn = $_ENV['OCTOPUSH_DSN'];
           $transport = new OctopushTransport($dsn);
           $notifier = new Notifier([$transport]);
   
           $notifier->send(
               new \Symfony\Component\Notifier\Message\SmsMessage($message, $to)
           );
       }
   }
   

4. Register the Service (Laravel Service Provider):

   // app/Providers/AppServiceProvider.php
   public function register()
   {
       $this->app->singleton(OctopushNotifier::class, function ($app) {
           return new OctopushNotifier();
       });
   }
   

5. Trigger the SMS (e.g., in a controller or job):

   use App\Services\OctopushNotifier;
   
   public function sendWelcomeSms()
   {
       $notifier = app(OctopushNotifier::class);
       $notifier->send('+33612345678', 'Welcome to our app!');
   }
   

Implementation Patterns

Workflow: Sending Notifications

1. For One-Off SMS: Use the OctopushNotifier service directly in controllers or jobs.

   $notifier->send('+33612345678', 'Your OTP is 12345');
   

2. For Queued Notifications: Wrap the call in a Laravel job:

   // app/Jobs/SendOctopushSms.php
   use App\Services\OctopushNotifier;
   
   class SendOctopushSms implements ShouldQueue
   {
       use Dispatchable, InteractsWithQueue, Queueable;
   
       public function handle(OctopushNotifier $notifier)
       {
           $notifier->send($this->phone, $this->message);
       }
   }
   

   Dispatch the job:

   SendOctopushSms::dispatch('+33612345678', 'Hello!');
   

3. For Multi-Channel Notifications: Extend Symfony’s Notifier to support email/SMS/push in one call (advanced):

   $notifier = new Notifier([
       new OctopushTransport($_ENV['OCTOPUSH_DSN']),
       new MailTransport(new SymfonyMailer()),
   ]);
   
   $notifier->send(
       new MultipartMessage(
           new SmsMessage('SMS part', '+33612345678'),
           new EmailMessage('Email part', 'user@example.com')
       )
   );
   

Integration Tips

• Laravel Events: Trigger Octopush notifications on Laravel events:

  // In an event listener
  event(new UserRegistered($user));
  SendOctopushSms::dispatch($user->phone, 'Account created!');
  

• Dynamic DSN: Override the DSN per environment or use a config file:

  $transport = new OctopushTransport(config('services.octopush.dsn'));
  

• Retry Logic: Use Laravel’s retry helper for transient failures:

  retry(5, function () use ($notifier) {
      $notifier->send($phone, $message);
  }, 100);
  

• Logging: Log failures for debugging:

  try {
      $notifier->send($phone, $message);
  } catch (\Exception $e) {
      \Log::error("Octopush failed: " . $e->getMessage());
  }
  

Gotchas and Tips

Pitfalls

1. Symfony Dependency Overhead:

   • Avoid pulling in symfony/notifier if only SMS is needed. Use Laravel’s Http facade instead:

     Http::withOptions(['auth' => [env('OCTOPUSH_KEY'), '']])
         ->post('https://api.octopush.com/sms', [
             'to' => $phone,
             'message' => $message,
             'from' => env('OCTOPUSH_FROM'),
             'type' => env('OCTOPUSH_TYPE', 'FR'),
         ]);
     

2. DSN Configuration:

   • The type parameter in the DSN (XXX/FR/WWW) must match Octopush’s SMS types. Invalid types will fail silently or return errors.
   • Example DSN:

     OCTOPUSH_DSN=octopush://login:key@default?from=MyApp&type=FR
     

3. Character Limits:

   • Octopush enforces SMS length limits (e.g., 160 chars for FR). Longer messages auto-split but may incur extra costs.
   • Validate message length before sending:

     if (mb_strlen($message, 'UTF-8') > 160) {
         throw new \InvalidArgumentException('Message too long for Octopush.');
     }
     

4. Rate Limiting:

   • Octopush has API rate limits. Implement exponential backoff for retries:

     use Symfony\Component\Notifier\Exception\TransportException;
     
     try {
         $notifier->send($phone, $message);
     } catch (TransportException $e) {
         if (str_contains($e->getMessage(), 'rate limit')) {
             sleep(10); // Wait before retry
             retry();
         }
     }
     

5. Testing:

   • Mock the OctopushTransport in PHPUnit:

     $transport = $this->createMock(OctopushTransport::class);
     $transport->expects($this->once())
         ->method('send')
         ->with($this->isInstanceOf(SmsMessage::class));
     $notifier = new Notifier([$transport]);
     

Debugging Tips

• Enable Symfony Debug Mode: Set SYMFONY_DEBUG=1 in your environment to get detailed errors from the Notifier component.

• Check Octopush API Responses: Use Http::withOptions(['debug' => true]) to inspect raw API responses.

• Common Errors:

  • Invalid DSN: Verify USERLOGIN and APIKEY in the DSN.
  • Unknown sender: Ensure the from parameter in the DSN is approved by Octopush.
  • Quota exceeded: Check your Octopush account balance or upgrade your plan.

Extension Points

1. Custom Transport Options: Extend OctopushTransport to add Octopush-specific options:

   class CustomOctopushTransport extends OctopushTransport
   {
       public function __construct(string $dsn, array $options = [])
       {
           parent::__construct($dsn, $options + ['custom_option' => true]);
       }
   }
   

2. Webhook Validation: If using Octopush’s webhooks, validate signatures in Laravel middleware:

   public function handle($request, Closure $next)
   {
       $signature = $request->header('X-Octopush-Signature');
       if (!hash_equals($this->generateSignature($request->getContent()), $signature)) {
           abort(403);
       }
       return $next($request);
   }
   

3. Fallback Providers: Implement a fallback to another SMS provider (e.g., Twilio) if Octopush fails:

   try {
       $notifier->send($phone, $message);
   } catch (\Exception $e) {
       $fallbackNotifier->send($phone, $message); // e.g., Twilio
   }
   

4. Dynamic Sender: Override the from parameter dynamically:

   $transport = new OctopushTransport(
       'octopush://login:key@default?type=FR