Twilio Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require blackford/twilio-bundle
   

2. Environment Setup Add Twilio credentials to .env.local:

   TWILIO_USER=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   TWILIO_PASSWORD=your_auth_token_or_password
   

3. Configuration Create config/packages/twilio.yml with:

   blackford_twilio:
       username: '%env(TWILIO_USER)%'
       password: '%env(TWILIO_PASSWORD)%'
   

4. First Use Case Inject the TwilioClient service into a controller/service and use it like the official SDK:

   use Blackford\TwilioBundle\Client\TwilioClient;
   
   class MyController extends AbstractController
   {
       public function sendSms(TwilioClient $twilio): Response
       {
           $message = $twilio->messages->create(
               '+1234567890', // To
               '+0987654321', // From
               'Hello from Symfony!'
           );
   
           return new Response('SMS sent: ' . $message->sid);
       }
   }
   

Implementation Patterns

Common Workflows

1. Sending SMS

   $twilio->messages->create($to, $from, $body, [
       'statusCallback' => $this->generateUrl('callback_route'),
   ]);
   

2. Making Calls

   $call = $twilio->calls->create(
       $from,
       $to,
       $this->generateUrl('call_status_route')
   );
   

3. Handling Webhooks Use Symfony’s Request and EventDispatcher to validate and process Twilio webhooks:

   use Blackford\TwilioBundle\Event\TwilioWebhookEvent;
   
   public function onTwilioWebhook(TwilioWebhookEvent $event)
   {
       if ($event->isValid()) {
           $data = $event->getData();
           // Process SMS/call status updates
       }
   }
   

4. Service Integration Bind the TwilioClient to a dedicated service for reusability:

   # config/services.yaml
   services:
       App\Service\TwilioService:
           arguments:
               $twilio: '@blackford_twilio.client'
   

Best Practices

• Environment Variables: Always use .env.local for credentials (never hardcode).
• Dependency Injection: Prefer injecting TwilioClient over instantiating it manually.
• Error Handling: Wrap Twilio operations in try-catch blocks to handle Twilio\Rest\ApiException:

  try {
      $twilio->messages->create(...);
  } catch (ApiException $e) {
      $this->addFlash('error', $e->getMessage());
  }
  

Gotchas and Tips

Pitfalls

1. Deprecated SDK Version The bundle wraps Twilio SDK v6, but the last release was in 2016. Verify compatibility with the latest SDK if using newer Twilio features.

2. Configuration Overrides The bundle does not support dynamic configuration via config/packages/twilio.yaml overrides in Symfony 5.4+. Use environment variables or parameters.yaml instead:

   # config/packages/parameters.yaml
   parameters:
       twilio.username: '%env(TWILIO_USER)%'
       twilio.password: '%env(TWILIO_PASSWORD)%'
   

3. Webhook Validation Twilio webhooks require strict validation. Use the bundle’s TwilioWebhookEvent or manually validate signatures:

   $event->isValid($request->getContent(), $request->headers->get('X-Twilio-Signature'));
   

4. Rate Limiting Twilio enforces rate limits. Cache TwilioClient instances to avoid reconnection overhead:

   # config/services.yaml
   services:
       blackford_twilio.client:
           public: true
           synthetic: true
   

Debugging Tips

• Enable Twilio Debugging: Set TWILIO_DEBUG=true in .env.local to log requests/responses.
• Check Headers: Use dd($request->headers->all()) to inspect webhook payloads.
• SDK Logs: Enable Twilio SDK logging via monolog:

  $twilio->setLogger(new MonologLogger($this->container->get('logger')));
  

Extension Points

1. Custom Services Extend the bundle by creating a decorator for TwilioClient:

   class CustomTwilioClient extends TwilioClient
   {
       public function sendTransactionalSms($to, $templateId, $data)
       {
           return $this->messages->create($to, $this->getFromNumber(), $this->renderTemplate($templateId, $data));
       }
   }
   

2. Event Subscribers Listen to Twilio events globally:

   class TwilioSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               TwilioEvents::WEBHOOK => 'onWebhook',
           ];
       }
   }
   

3. Messenger Integration Dispatch Twilio operations as async messages:

   $this->messageBus->dispatch(new SendSmsMessage($to, $body));