Conexteo Notifier Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require com-company/conexteo-notifier
   

   Add the DSN to your .env:

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

2. First Use Case: Sending a Notification Inject the Notifier service and use the conexteo transport:

   use Symfony\Component\Notifier\NotifierInterface;
   use Symfony\Component\Notifier\Message\SmsMessage;
   
   class MyService
   {
       public function __construct(private NotifierInterface $notifier) {}
   
       public function sendWelcomeSms(string $phone): void
       {
           $message = new SmsMessage('Welcome! Your account is ready.');
           $this->notifier->send($message->to($phone));
       }
   }
   

3. Where to Look First

   • Configuration: Check config/packages/conexteo_notifier.yaml (if provided) for default settings.
   • DSN Format: Validate CONEXTEO_DSN in .env matches the required structure.
   • Symfony Notifier Docs: Refer to Symfony’s Notifier docs for message types (e.g., SmsMessage, Email).

Implementation Patterns

Core Workflows

1. Sending SMS Notifications

   $this->notifier->send(
       new SmsMessage('Your OTP: 123456')
           ->to('+1234567890')
           ->priority(NotifierInterface::PRIORITY_HIGH)
   );
   

2. Handling Failures Use Symfony’s Failure events to log or retry failed sends:

   $this->notifier->send(
       new SmsMessage('Hello'),
       ['failure' => function (Failure $failure) {
           // Log or retry logic
       }]
   );
   

3. Dynamic Sender/Recipient Override the sender or recipient per message:

   $message = new SmsMessage('Hello')
       ->to($phone)
       ->sender('CustomSender'); // Overrides DSN's `sender`
   

Integration Tips

• Event Dispatching: Pair with Symfony’s EventDispatcher to trigger actions post-send (e.g., analytics).
• Rate Limiting: Use Symfony’s RateLimiter to throttle messages if needed.
• Testing: Mock the Transport interface for unit tests:

  $transport = $this->createMock(TransportInterface::class);
  $notifier = new Notifier([$transport]);
  

Gotchas and Tips

Pitfalls

1. DSN Validation

   • Issue: Invalid CONEXTEO_DSN (e.g., missing APP_ID or API_KEY) throws cryptic errors.
   • Fix: Validate the DSN early in a service constructor or use a ParameterBag check:

     if (!preg_match('/^conexteo:\/\/[^:]+:[^@]+@/', $dsn)) {
         throw new \InvalidArgumentException('Invalid Conexteo DSN');
     }
     

2. Sender Defaults

   • Issue: The sender in the DSN is optional but required by Conexteo’s API.
   • Fix: Ensure ?sender=SENDER is included in the DSN or handle missing sender in the transport.

3. Async Delays

   • Issue: Conexteo’s API may delay delivery, causing race conditions in time-sensitive flows.
   • Fix: Use Symfony’s AsyncTransport to queue messages:

     $this->notifier->send($message, ['transport' => new AsyncTransport($conexteoTransport)]);
     

Debugging

• Logs: Enable Symfony’s monolog to log transport interactions:

  # config/packages/monolog.yaml
  handlers:
      main:
          type: stream
          path: "%kernel.logs_dir%/%kernel.environment%.log"
          level: debug
  

• Payload Inspection: Dump the raw payload sent to Conexteo:

  $message->getHeaders()->add('X-DEBUG-PAYLOAD', json_encode($message->getContent()));
  

Extension Points

1. Custom Transports Extend TransportInterface to add features like:

   • Template Rendering: Replace placeholders in messages dynamically.
   • Webhook Validation: Verify Conexteo’s delivery receipts via webhooks.

2. Middleware Use Symfony’s TransportMiddleware to modify messages:

   $transport = new ConexteoTransport($dsn);
   $transport->addMiddleware(new AddSignatureMiddleware('your-secret'));
   

3. Configuration Overrides Override default settings in config/packages/conexteo_notifier.yaml:

   conexteo_notifier:
       default_sender: 'OverrideSender'
       timeout: 30 # seconds