Africastalking Laravel Package

Getting Started

1. Install the package via Composer:

   composer require <vendor>/laravel-africastalking
   

   v2.0.3 now requires africastalking/africastalking ^3.0. Confirm your PHP version meets the SDK’s constraint (usually PHP 7.4+/8.x).

2. Publish configuration (if the package provides it):

   php artisan vendor:publish --tag=africastalking-config
   

   Add credentials to .env:

   AFRICASTALKING_USERNAME=sandbox
   AFRICASTALKING_API_KEY=your_key
   AFRICASTALKING_SENDER_ID=your_sender_id
   

3. Where to look first:

   • config/africastalking.php – credentials, sender ID, sandbox toggle.
   • The package service provider / facade – to see available bindings (AfricasTalking, Sms, etc.).
   • The SDK’s AfricasTalking class from africastalking/africastalking v3.0, since the wrapper delegates to it.

4. First use case – send an SMS:

   use AfricasTalking\SDK\AfricasTalking; // or the package facade
   
   $sms = AfricasTalking::sms();
   $sms->send([
       'to'      => '+254700000000',
       'message' => 'Hello from Laravel',
       'from'    => config('africastalking.sender_id'),
   ]);
   

   Or, if the package exposes a facade:

   use Vendor\AfricasTalking\Facades\Sms;
   
   Sms::send('+254700000000', 'Hello from Laravel');
   

   Start in sandbox mode (AFRICASTALKING_USERNAME=sandbox) to avoid real charges while validating the integration.

Implementation Patterns

• Single and bulk SMS
  Use the package’s SMS API for one-off messages, and loop or batch recipients for bulk sends. Keep recipient lists in a queued job to avoid request timeouts.

• Laravel notifications
  If the package provides a notification channel, use it for transactional messages:

  public function via($notifiable)
  {
      return ['africastalking'];
  }
  
  public function toAfricasTalking($notifiable)
  {
      return (new SmsMessage)
          ->to($notifiable->phone)
          ->content('Your code is 1234');
  }
  

  Queue notifications (ShouldQueue) for reliability.

• Queued jobs for outbound messages
  Wrap sends in jobs with retries and backoff. This is especially important for bulk SMS, airtime disbursements, and voice callbacks.

• USSD and inbound SMS handling
  Expose routes/controllers for Africa’s Talking callbacks. Validate payloads, respond within the USSD session timeout, and log raw requests for debugging.

• Airtime, payments, and voice
  Use the SDK methods exposed by the package (airtime, payments, voice). Keep amounts and currency codes in config, not hardcoded.

• Dependency injection
  Prefer injecting the package’s service classes over using facades directly in domain code. This makes it easier to swap or fake in tests.

• Testing
  Mock the SDK or the package’s client in unit tests. For integration tests, use sandbox credentials and avoid hitting production endpoints.

• Configuration caching
  If you cache config in production, ensure all Africa’s Talking credentials are environment-driven and run php artisan config:cache after deployment.

Gotchas and Tips

• v2.0.3 is a dependency bump, not a feature release
  The only change is support for africastalking/africastalking v3.0. Check the SDK’s v3.0 changelog for method signature or namespace changes. If your code type-hints or extends SDK classes directly, verify compatibility.

• Sandbox vs production
  username=sandbox routes to the sandbox environment. Production credentials require an approved sender ID and may incur costs. Never accidentally deploy sandbox credentials to production.

• Phone number format
  Use E.164 format (+254...). Validate and normalize numbers before sending to avoid silent failures or wasted credits.

• Sender ID approval
  Sender IDs must be registered and approved by Africa’s Talking. Unapproved IDs can cause delivery failures or fallback to a shared shortcode.

• Error handling and retries
  The SDK can throw exceptions or return error payloads depending on the call. Catch both, log the raw response, and avoid retrying non-idempotent operations (e.g., payments) without safeguards.

• Rate limits and throughput
  Bulk sends may be throttled. Use queues, chunk recipient lists, and monitor for 429 or provider-specific throttling responses.

• Webhook/callback security
  Africa’s Talking callbacks are HTTP requests. Validate source IPs or shared secrets where possible, and never trust callback payloads blindly.

• Config caching quirks
  If credentials are read via env() directly outside config files, config:cache will break them. Always reference config('africastalking.*').

• Logging and debugging
  Log request payloads and response bodies (excluding API keys) during development. In production, log correlation IDs and error codes, not full phone numbers or message content.

• Extension points
  If the package binds the SDK client in the container, you can swap it with a decorated or mocked client in tests. Check the service provider for binding names before assuming a facade is the only entry point.