Conexteo Notifier Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require connected-company/conexteo-notifier
   

   Ensure your Laravel project uses Symfony's symfony/notifier (v5.4+). If not, install it first:

   composer require symfony/notifier
   

2. Configuration Add the DSN to your .env:

   CONEXTEO_DSN=conexteo://APP_ID:API_KEY@default?sender=SENDER
   

   Replace placeholders with your Conexteo credentials.

3. First Use Case Send a notification via a controller or command:

   use Symfony\Component\Notifier\NotifierInterface;
   
   public function sendNotification(NotifierInterface $notifier)
   {
       $message = new ChatMessage('Hello from Laravel!');
       $notifier->send($message->to('recipient@example.com'));
   }
   

   Register the NotifierInterface in your AppServiceProvider:

   public function register()
   {
       $this->app->singleton(NotifierInterface::class, function ($app) {
           return new Notifier([new ConexteoTransport($app['config']['services.conexteo.dsn'])]);
       });
   }
   

4. Verify Integration Check Conexteo’s developer dashboard for received messages.

Implementation Patterns

Core Workflows

1. Transport Initialization Use the ConexteoTransport class directly or via Symfony’s Notifier:

   $transport = new ConexteoTransport($dsn);
   $notifier = new Notifier([$transport]);
   

2. Message Types

   • ChatMessage: For SMS/Chat notifications.

     $message = new ChatMessage('Your OTP: 12345');
     $notifier->send($message->to('+1234567890'));
     

   • EmailMessage: If Conexteo supports email (verify API docs).

     $message = new EmailMessage('Welcome!');
     $notifier->send($message->to('user@example.com'));
     

3. Async Processing Queue notifications for background processing:

   use Illuminate\Bus\Queueable;
   use Illuminate\Contracts\Queue\ShouldQueue;
   
   class SendWelcomeNotification implements ShouldQueue
   {
       use Queueable;
   
       public function handle(NotifierInterface $notifier)
       {
           $notifier->send(new ChatMessage('Welcome!'));
       }
   }
   

4. Dynamic Sender/Recipient Fetch sender/recipient from a user model:

   $user = User::find(1);
   $message = new ChatMessage("Hello, {$user->name}!");
   $notifier->send($message->to($user->phone));
   

Integration Tips

• Laravel Notifications: Extend Laravel’s Notification class to use Symfony’s Notifier:

  use Illuminate\Notifications\Notification;
  use Symfony\Component\Notifier\NotifierInterface;
  
  class ConexteoNotification extends Notification
  {
      public function via($notifier)
      {
          return [ConexteoChannel::class];
      }
  
      public function toConexteo($notifier)
      {
          return new ChatMessage('Custom content');
      }
  }
  

  Register the channel in AppServiceProvider:

  $this->app->bind(ConexteoChannel::class, function ($app) {
      return new ConexteoChannel($app->make(NotifierInterface::class));
  });
  

• Logging Failures Wrap notifier->send() in a try-catch to log errors:

  try {
      $notifier->send($message);
  } catch (\Exception $e) {
      \Log::error('Conexteo notification failed', ['error' => $e->getMessage()]);
  }
  

Gotchas and Tips

Pitfalls

1. DSN Validation

   • Ensure the DSN format matches conexteo://APP_ID:API_KEY@default?sender=SENDER.
   • Missing default host or invalid credentials will throw TransportException.

2. Message Limits

   • Conexteo may enforce message length/character limits. Validate payloads before sending:

     if (strlen($message->getContent()) > 160) {
         throw new \InvalidArgumentException('Message exceeds 160 characters.');
     }
     

3. Rate Limiting

   • Conexteo may throttle requests. Implement exponential backoff in retries:

     $transport->setRetryStrategy(new RetryStrategy(3, 1000)); // 3 retries, 1s delay
     

4. Recipient Format

   • Phone numbers must include country codes (e.g., +1234567890). Strip non-numeric characters:

     $phone = preg_replace('/[^0-9]/', '', $user->phone);
     

Debugging

• Enable Debug Mode Set Symfony’s debug mode to log transport interactions:

  $transport->setDebug(true);
  

  Check logs for raw API responses/errors.

• Mock Testing Use a mock transport in tests:

  $mockTransport = $this->createMock(ConexteoTransport::class);
  $mockTransport->method('send')->willReturn(true);
  $notifier = new Notifier([$mockTransport]);
  

Extension Points

1. Custom Headers Extend ConexteoTransport to add headers:

   class CustomConexteoTransport extends ConexteoTransport
   {
       protected function getHeaders(): array
       {
           return array_merge(parent::getHeaders(), ['X-Custom-Header' => 'value']);
       }
   }
   

2. Template Engine Use Laravel’s Blade to render dynamic messages:

   $content = view('notifications.conexteo_template', ['user' => $user])->render();
   $message = new ChatMessage($content);
   

3. Webhook Validation If Conexteo supports webhooks, validate signatures:

   use Symfony\Component\HttpFoundation\Request;
   
   public function handleWebhook(Request $request)
   {
       $payload = $request->getContent();
       $signature = $request->headers->get('X-Conexteo-Signature');
       if (!hash_equals($signature, hash_hmac('sha256', $payload, config('services.conexteo.webhook_secret')))) {
           abort(403);
       }
   }
   

Config Quirks

• Environment Overrides Override DSN per environment (e.g., .env.testing):

  CONEXTEO_DSN=conexteo://TEST_APP_ID:TEST_KEY@default
  

• Sender Defaults Set a default sender in config/services.php:

  'conexteo' => [
      'dsn' => env('CONEXTEO_DSN'),
      'default_sender' => env('CONEXTEO_DEFAULT_SENDER', 'Support'),
  ],
  

  Then access it in ConexteoTransport:

  $sender = $this->config['default_sender'] ?? null;