Nexmo Bundle Laravel Package

Getting Started

1. Update Package Name: Replace BotjaegerNexmoBundle with BotjaegerVonageBundle in composer.json and run:

   composer require botjaeger/vonage-bundle
   

2. Verify SDK Integration: The bundle now uses the official Vonage PHP SDK. Check the migration guide for SDK-specific changes (e.g., Nexmo_Client → Vonage_Client).
3. First Use Case: Replace nexmo service calls in your code with the new SDK methods. Example:

   // Old (deprecated)
   $client = $this->get('nexmo.client');
   $client->message->send(...);
   
   // New
   $client = $this->get('vonage.client');
   $client->sms()->send(...);
   

Implementation Patterns

1. Service Binding:
   • The bundle auto-configures the vonage.client service (using Vonage_Client). Override via config/packages/botjaeger_vonage.yaml:

     services:
         vonage.client:
             arguments:
                 $key: '%env(VONAGE_KEY)%'
                 $secret: '%env(VONAGE_SECRET)%'
                 $applicationId: '%env(VONAGE_APP_ID)%'
     

2. SDK Method Mapping:
   • Map old Nexmo methods to Vonage SDK equivalents (e.g., message->send() → sms()->send()). Use the SDK docs as a reference.
3. Event Handling:
   • Vonage SDK emits events (e.g., Vonage\Client\Events\MessageSent). Subscribe via Laravel’s event system:

     // In a service provider
     $this->app->make('vonage.client')->on('Vonage\Client\Events\MessageSent', function ($event) {
         // Handle event
     });
     

4. Testing:
   • Use the Vonage SDK’s mock client for unit tests:

     $mock = Mockery::mock('overload:Vonage\Client\VonageClient');
     $mock->shouldReceive('sms()->send')->andReturn(new Vonage\SMS\Message());
     

Gotchas and Tips

1. Breaking Changes:
   • Namespace Changes: Replace Nexmo_* with Vonage_* in all code (e.g., Nexmo_Client → Vonage_Client).
   • Method Signatures: Some SDK methods have renamed parameters (e.g., from → sender). Check the SDK changelog.
   • Deprecated Features: Features like Nexmo_Message::setType() may no longer exist. Use Vonage’s SMS or WhatsApp classes directly.
2. Configuration Quirks:
   • The bundle no longer supports NEXMO_* env vars. Use VONAGE_* (e.g., VONAGE_KEY, VONAGE_SECRET).
   • For ApplicationId, add to .env:

     VONAGE_APP_ID=your_app_id
     

3. Extension Points:
   • Custom SDK Setup: Extend the Vonage_Client via a decorator or middleware:

     $client->extend(function ($client) {
         $client->setDefaultSender('YourBrand');
     });
     

   • Webhook Handling: Use Laravel’s Http\Middleware\HandleIncomingModelEvents to process Vonage webhooks (e.g., inbound-sms).
4. Debugging:
   • Enable SDK logging:

     $client = new Vonage\Client\VonageClient($key, $secret, [
         'logLevel' => \Monolog\Logger::DEBUG,
     ]);
     

   • Check for Vonage\Client\Exception\SDKException and handle gracefully.
5. Migration Pitfalls:
   • Twilio Compatibility: If you used Twilio-like features (e.g., Nexmo_Client::call()), note that Vonage’s Voice API requires separate setup. See Vonage Voice SDK.
   • Rate Limits: Vonage’s SDK enforces stricter rate limits. Monitor usage via the Vonage Dashboard.