Sdk Laravel Package

Getting Started

Minimal Setup in Laravel

1. Install the Package Add the SDK via Composer in your Laravel project:

   composer require esendex/sdk:^3.0
   

   Laravel’s autoloader will handle the rest—no manual require needed.

2. Configure Credentials Store Esendex credentials in .env:

   ESENDEX_ACCOUNT_REF=EX000000
   ESENDEX_USERNAME=user@example.com
   ESENDEX_PASSWORD=your_password
   

3. First Use Case: Send an SMS Create a helper class (e.g., app/Services/EsendexService.php):

   use Esendex\Authentication\LoginAuthentication;
   use Esendex\DispatchService;
   use Esendex\Model\DispatchMessage;
   
   class EsendexService {
       public function sendSms(string $to, string $message): array {
           $auth = new LoginAuthentication(
               config('esendex.account_ref'),
               config('esendex.username'),
               config('esendex.password')
           );
           $service = new DispatchService($auth);
           $dispatch = new DispatchMessage(
               config('esendex.default_sender'), // e.g., "YourApp"
               $to,
               $message,
               \Esendex\Model\Message::SmsType
           );
           $result = $service->send($dispatch);
           return [
               'message_id' => $result->id(),
               'uri' => $result->uri(),
           ];
       }
   }
   

   Register the service in config/services.php:

   'esendex' => [
       'account_ref' => env('ESENDEX_ACCOUNT_REF'),
       'username' => env('ESENDEX_USERNAME'),
       'password' => env('ESENDEX_PASSWORD'),
       'default_sender' => env('ESENDEX_DEFAULT_SENDER', 'YourApp'),
   ],
   

4. Trigger from a Controller

   use App\Services\EsendexService;
   
   class NotificationController extends Controller {
       public function sendWelcomeSms(Request $request) {
           $esendex = app(EsendexService::class);
           $response = $esendex->sendSms(
               $request->phone,
               "Welcome to our app! Use code: {$request->code}"
           );
           return response()->json($response);
       }
   }
   

Implementation Patterns

1. Service Layer Abstraction

• Pattern: Encapsulate Esendex logic in a dedicated service class (e.g., EsendexService) to:
  • Centralize authentication and error handling.
  • Reuse across controllers/queues/jobs.
  • Mock easily for testing.
• Example:

  class EsendexService {
      protected $auth;
      protected $dispatchService;
      protected $inboxService;
  
      public function __construct() {
          $this->auth = new LoginAuthentication(
              config('esendex.account_ref'),
              config('esendex.username'),
              config('esendex.password')
          );
          $this->dispatchService = new DispatchService($this->auth);
          $this->inboxService = new InboxService($this->auth);
      }
  
      // ... methods for sendSms(), fetchInbox(), etc.
  }
  

2. Queue-Based SMS Dispatch

• Pattern: Offload SMS sending to Laravel queues to avoid timeouts and improve UX.
• Implementation:

  // Queue the job
  SendSmsJob::dispatch($phone, $message);
  
  // Job class
  class SendSmsJob implements ShouldQueue {
      use Dispatchable, InteractsWithQueue, Queueable;
  
      public function handle() {
          $esendex = app(EsendexService::class);
          $esendex->sendSms($this->phone, $this->message);
      }
  }
  

3. Inbox Monitoring

• Pattern: Poll the inbox periodically (e.g., via Laravel Scheduler) to track replies.
• Example:

  // app/Console/Commands/FetchInboxMessages.php
  class FetchInboxMessages extends Command {
      public function handle() {
          $esendex = app(EsendexService::class);
          $messages = $esendex->fetchInbox();
          foreach ($messages as $msg) {
              // Process replies (e.g., update DB, trigger webhooks)
              Reply::create([
                  'phone' => $msg->originator(),
                  'message' => $msg->summary(),
              ]);
          }
      }
  }
  

  Schedule in app/Console/Kernel.php:

  protected function schedule(Schedule $schedule) {
      $schedule->command('fetch:inbox')->everyFiveMinutes();
  }
  

4. Webhook Integration

• Pattern: Use Esendex webhooks (via their API) to receive real-time status updates.
• Laravel Setup:

  // routes/web.php
  Route::post('/esendex/webhook', [EsendexWebhookController::class]);
  
  // app/Http/Controllers/EsendexWebhookController.php
  class EsendexWebhookController extends Controller {
      public function handleWebhook(Request $request) {
          $payload = $request->json()->all();
          // Validate signature (if using Esendex's webhook auth)
          // Update DB or trigger events based on $payload['status']
      }
  }
  

5. Fallbacks and Retries

• Pattern: Implement retries for failed SMS sends using Laravel’s retryAfter().
• Example:

  class SendSmsJob extends Job {
      public function handle() {
          try {
              $esendex = app(EsendexService::class);
              $result = $esendex->sendSms($this->phone, $this->message);
          } catch (\Esendex\Exception\EsendexException $e) {
              if ($e->getCode() === 400 && $this->attempts() < 3) {
                  $this->release(60); // Retry after 60 seconds
              }
              throw $e;
          }
      }
  }
  

Gotchas and Tips

1. Authentication Pitfalls

• Gotcha: Hardcoding credentials in the service class violates the Principle of Least Privilege. Fix: Always use Laravel’s config() or .env for credentials.
• Tip: For production, use Laravel’s environment-based configuration or vaults for sensitive data.

2. PHP Version Mismatch

• Gotcha: The package requires PHP 8.3+, but the README lists PHP 7.3+ (v3.0.0). Always check the latest release for requirements. Fix: Update your composer.json to pin the version:

  "esendex/sdk": "^3.0"
  

3. Rate Limiting and Throttling

• Gotcha: Esendex’s API has rate limits. Exceeding limits may cause 429 Too Many Requests errors. Fix:
  • Implement exponential backoff in retries.
  • Use Laravel’s throttle middleware for API routes calling Esendex.
  • Cache frequent inbox checks (e.g., Cache::remember()).

4. Message ID Handling

• Gotcha: Message IDs returned by send() are not guaranteed to be unique across accounts or time. Use them only for temporary tracking. Tip: Store a local UUID in your DB alongside the Esendex message_id for reliable reference.

5. Testing Challenges

• Gotcha: The SDK lacks built-in mocking support, making unit tests harder. Tip: Use Laravel’s Mockery to stub the DispatchService:

  $mockService = Mockery::mock(\Esendex\DispatchService::class);
  $mockService->shouldReceive('send')
      ->once()
      ->andReturn(new \Esendex\Model\DispatchResult('test-id', 'http://example.com'));
  $this->app->instance(\Esendex\DispatchService::class, $mockService);
  

• Integration Testing: Use the check-access Phing task (from README) to validate credentials in CI:

  vendor/bin/phing check-access
  

6. Unicode/Character Limits

• Gotcha: SMS messages are limited to 160 characters (70 for Unicode). Longer messages auto-convert to multi-part, but:
  • **