Php Sdk Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require websms/php-sdk
   

   Require the autoloader in your Laravel project (handled automatically by Composer).

2. First Use Case: Sending an SMS Initialize the client with your WebSms API credentials:

   use Websms\Client;
   
   $client = new Client([
       'username' => env('WEBSMS_USERNAME'),
       'password' => env('WEBSMS_PASSWORD'),
       'sender'   => env('WEBSMS_SENDER_ID', 'YourBrand')
   ]);
   

   Store credentials in .env:

   WEBSMS_USERNAME=your_username
   WEBSMS_PASSWORD=your_password
   WEBSMS_SENDER_ID=YourBrand
   

3. Send a Basic SMS

   $response = $client->send([
       'to'      => '1234567890',
       'message' => 'Hello from Laravel!'
   ]);
   

   Check the response for success/failure:

   if ($response->isSuccess()) {
       Log::info("SMS sent: " . $response->getMessageId());
   }
   

Implementation Patterns

Common Workflows

1. Bulk SMS Sending Use a loop or collect() to send to multiple recipients:

   $recipients = ['1234567890', '0987654321'];
   foreach ($recipients as $number) {
       $client->send(['to' => $number, 'message' => 'Your message']);
   }
   

   For async processing, dispatch a job:

   SendSmsJob::dispatch($client, $number, $message);
   

2. Template-Based Messages Use WebSms templates (if supported) for dynamic content:

   $client->send([
       'to'      => '1234567890',
       'message' => 'Your code is {code}.',
       'vars'    => ['code' => '123456']
   ]);
   

3. Error Handling Wrap API calls in a try-catch:

   try {
       $response = $client->send([...]);
   } catch (\Websms\Exception\WebsmsException $e) {
       Log::error("SMS failed: " . $e->getMessage());
       // Retry logic or notify admin
   }
   

4. Laravel Service Provider Integration Bind the client to the container in AppServiceProvider:

   public function register()
   {
       $this->app->singleton('websms.client', function ($app) {
           return new Client([
               'username' => config('services.websms.username'),
               'password' => config('services.websms.password'),
               'sender'   => config('services.websms.sender')
           ]);
       });
   }
   

   Configure in config/services.php:

   'websms' => [
       'username' => env('WEBSMS_USERNAME'),
       'password' => env('WEBSMS_PASSWORD'),
       'sender'   => env('WEBSMS_SENDER_ID')
   ],
   

5. Queueing SMS Jobs Create a job (SendSmsJob):

   use Illuminate\Bus\Queueable;
   use Websms\Client;
   
   class SendSmsJob implements ShouldQueue
   {
       use Queueable;
   
       public function handle(Client $client)
       {
           $client->send([...]);
       }
   }
   

Gotchas and Tips

Pitfalls

1. Deprecated Package

   • Last release in 2019; verify API compatibility with WebSms.
   • Check for undocumented breaking changes in the WebSms API.

2. No Rate Limiting

   • The SDK lacks built-in rate limiting. Implement retries with exponential backoff:

     $attempts = 0;
     $maxAttempts = 3;
     while ($attempts < $maxAttempts) {
         try {
             $response = $client->send([...]);
             break;
         } catch (\Websms\Exception\WebsmsException $e) {
             $attempts++;
             sleep(2 ** $attempts); // Exponential backoff
         }
     }
     

3. No Async Support

   • The SDK is synchronous. Use Laravel Queues (as shown above) for async operations.

4. Limited Documentation

   • Refer to WebSms API docs for unsupported endpoints.
   • Example: Check if getBalance() or listMessages() are available.

5. Sender ID Restrictions

   • Some carriers block short sender IDs. Use alphanumeric sender IDs (e.g., 'YourBrand').

Debugging Tips

1. Enable Debug Mode

   $client = new Client([...], [
       'debug' => true // Logs raw API requests/responses
   ]);
   

2. Check HTTP Status Codes Inspect $response->getStatusCode() for non-200 responses (e.g., 401 Unauthorized).

3. Validate Credentials Test with a dummy request:

   $client->getBalance(); // Throws exception if credentials are invalid
   

Extension Points

1. Custom Responses Extend the Response class to add helper methods:

   class ExtendedResponse extends \Websms\Response
   {
       public function isDelivered()
       {
           return $this->getStatus() === 'delivered';
       }
   }
   

2. Add Retry Logic Create a decorator for the Client class:

   class RetryClientDecorator
   {
       public function send(array $params, int $retries = 3)
       {
           // Implement retry logic
       }
   }
   

3. Support for Webhooks If WebSms supports webhooks, add a setWebhookUrl() method to the client:

   $client->setWebhookUrl(config('services.websms.webhook_url'));
   

4. Mocking for Tests Use Laravel’s Mockery to stub the client:

   $mockClient = Mockery::mock(\Websms\Client::class);
   $mockClient->shouldReceive('send')->andReturn(new \Websms\Response(200, ['id' => '123']));