Nexmo Client Laravel Package

Getting Started

Minimal Setup

1. Installation: Add the package via Composer:

   composer require connect-corp/nexmo-client
   

2. Configuration: Store your Nexmo API key and secret in .env:

   NEXMO_API_KEY=your_api_key_here
   NEXMO_API_SECRET=your_api_secret_here
   

3. Service Provider: Register the client in config/app.php under providers:

   ConnectCorp\NexmoClient\NexmoServiceProvider::class,
   

4. Facade: Publish the config (optional) and use the facade in your code:

   use ConnectCorp\NexmoClient\Facades\Nexmo;
   

First Use Case: Sending an SMS

$response = Nexmo::message()->send('1234567890', '15551232020', 'Hello from Laravel!');

Implementation Patterns

Core Workflows

1. Message Sending:

   • Use Nexmo::message()->send() for text messages.
   • For advanced use cases (e.g., Unicode, callbacks), chain methods:

     $response = Nexmo::message()
         ->to('15551232020')
         ->from('1234567890')
         ->text('Hello!')
         ->send();
     

2. Account Management:

   • Fetch balance: Nexmo::account()->balance().
   • Check number status: Nexmo::number()->status('1234567890').

3. Error Handling:

   • Wrap calls in try-catch blocks to handle Nexmo\Exception:

     try {
         $response = Nexmo::message()->send(...);
     } catch (Nexmo\Exception $e) {
         Log::error('Nexmo error: ' . $e->getMessage());
         return response()->json(['error' => 'Failed to send SMS'], 500);
     }
     

Integration Tips

1. Laravel Queues:

   • Dispatch SMS jobs to a queue for async processing:

     dispatch(new SendSmsJob($to, $from, $message));
     

   • Implement SendSmsJob with Nexmo::message()->send().

2. Logging:

   • Log responses/errors for debugging:

     Log::debug('Nexmo response:', ['response' => $response]);
     

3. Testing:

   • Use Nexmo::fake() in PHPUnit to mock responses:

     public function test_sms_sending()
     {
         Nexmo::fake()->shouldReceive('send')->once()->andReturn(['status' => '0']);
         $this->assertTrue(true); // Test logic here
     }
     

Gotchas and Tips

Pitfalls

1. Deprecated Methods:

   • The package is outdated (last release 2015). Use invoke() instead of deprecated methods like send() where applicable.
   • Example: Prefer $nexmo->message->invoke($from, $to, 'text', $text) over $nexmo->message->send().

2. Rate Limits:

   • Nexmo enforces rate limits. Implement exponential backoff for retries:

     use Symfony\Component\Process\Exception\TimeoutException;
     try {
         $response = $nexmo->message->invoke(...);
     } catch (TimeoutException $e) {
         sleep(2); // Exponential backoff logic here
         retry();
     }
     

3. Number Formatting:

   • Ensure phone numbers are in E.164 format (e.g., +15551232020). Use a helper:

     function formatPhoneNumber($number) {
         return preg_replace('/[^0-9]/', '', $number);
     }
     

Debugging

1. Enable Debug Mode:

   • Set NEXMO_DEBUG=true in .env to log raw API responses.

2. Common Errors:

   • 401 Unauthorized: Verify apiKey and apiSecret.
   • 400 Bad Request: Check phone number format or message length (max 1600 chars for Unicode).

Extension Points

1. Custom Responses:

   • Extend the client to handle additional Nexmo APIs (e.g., Voice, Verify):

     class CustomNexmoClient extends \Nexmo\Client {
         public function verify($number, $code) {
             return $this->request('POST', '/verify/json', [
                 'api_key' => $this->apiKey,
                 'api_secret' => $this->apiSecret,
                 'number' => $number,
                 'code' => $code,
             ]);
         }
     }
     

2. Middleware:

   • Add middleware to log or modify requests/responses:

     $nexmo->getClient()->getHandler()->push(new \GuzzleHttp\HandlerStack(), 'logging');
     

3. Configuration:

   • Override default settings in config/nexmo.php:

     'timeout' => 30, // Default: 10 seconds
     'base_uri' => env('NEXMO_BASE_URI', 'https://api.nexmo.com'),