Laravel Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require signalads-co/laravel
   php artisan vendor:publish --tag=signalads-laravel
   

2. Configure API Key: Update config/signalads.php with your apikey and sender (from Signalads Dashboard).

   return [
       'apikey' => 'your_api_key_here',
       'sender' => 'YourSenderID',
   ];
   

3. First Use Case: Send an SMS via a controller or command:

   use Signalads\Signalads\Facades\Signalads;
   
   Signalads::send([
       'to' => '1234567890',
       'message' => 'Hello from Laravel!',
   ]);
   

Where to Look First

• Facade: Signalads\Facades\Signalads (primary entry point).
• Config: config/signalads.php (API key and sender ID).
• Service Provider: SignaladsServiceProvider (for customization hooks).

Implementation Patterns

Core Workflows

1. Sending SMS:

   • Basic Usage:

     Signalads::send([
         'to' => '1234567890',
         'message' => 'Your message here',
     ]);
     

   • With Options:

     Signalads::send([
         'to' => '1234567890',
         'message' => 'Hello!',
         'sender' => 'CustomSender', // Override config
         'type' => 'transactional',  // 'promotional' or 'transactional'
     ]);
     

   • Batch Send:

     $numbers = ['1234567890', '0987654321'];
     foreach ($numbers as $number) {
         Signalads::send(['to' => $number, 'message' => 'Batch message']);
     }
     

2. Queueing Messages (for async processing):

   • Dispatch a job:

     use Signalads\Signalads\Jobs\SendSms;
     
     SendSms::dispatch([
         'to' => '1234567890',
         'message' => 'Queued message',
     ]);
     

   • Ensure QUEUE_CONNECTION is configured in .env (e.g., redis, database).

3. Handling Responses:

   • Check success/failure:

     $response = Signalads::send([...]);
     if ($response->success()) {
         // Handle success
     } else {
         Log::error('Signalads error:', ['error' => $response->getError()]);
     }
     

Integration Tips

• Validation: Validate phone numbers before sending (e.g., using Laravel's Validator).
• Logging: Log all responses for debugging:

  Log::channel('signalads')->info('SMS sent', ['response' => $response->toArray()]);
  

• Environment-Specific Config: Use Laravel's .env to override config:

  SIGNALADS_APIKEY=prod_api_key
  SIGNALADS_SENDER=ProdSender
  

  Update config/signalads.php to read from .env:

  'apikey' => env('SIGNALADS_APIKEY'),
  'sender' => env('SIGNALADS_SENDER'),
  

Gotchas and Tips

Pitfalls

1. API Key Validation:

   • The package does not auto-validate the API key on first use. Test with a small batch before production.
   • Fix: Add a middleware or service check:

     if (empty(config('signalads.apikey'))) {
         throw new \RuntimeException('Signalads API key not configured.');
     }
     

2. Phone Number Formatting:

   • Signalads expects international format (e.g., +1234567890). Strip country codes if needed:

     $cleanedNumber = preg_replace('/[^0-9]/', '', $number);
     

3. Rate Limits:

   • Signalads may throttle requests. Implement exponential backoff in retries:

     use Illuminate\Support\Facades\Http;
     
     $response = Http::retry(3, 100)->post(...);
     

4. Queue Failures:

   • Failed jobs may pile up. Monitor failed_jobs table and set up a queue worker monitor.

Debugging

• Enable Debug Mode: Set debug to true in config/signalads.php to log raw API responses:

  'debug' => env('APP_DEBUG', false),
  

• Check HTTP Client: Override the HTTP client for debugging:

  Signalads::setClient(Http::withOptions(['debug' => true]));
  

Extension Points

1. Custom Responses: Extend the SignaladsResponse class to add custom logic:

   namespace App\Services;
   
   use Signalads\Signalads\SignaladsResponse;
   
   class CustomSignaladsResponse extends SignaladsResponse {
       public function isValidNumber(): bool {
           return preg_match('/^\+[0-9]{10,15}$/', $this->data['to'] ?? '');
       }
   }
   

   Bind it in a service provider:

   $this->app->bind(
       \Signalads\Signalads\SignaladsResponse::class,
       App\Services\CustomSignaladsResponse::class
   );
   

2. Webhook Handling: Signalads supports delivery reports. Create a route to handle callbacks:

   Route::post('/signalads/webhook', function (Request $request) {
       $payload = $request->validate([
           'message_id' => 'required|string',
           'status' => 'required|string',
       ]);
       // Update your DB or trigger events
   });
   

3. Testing: Mock the facade in tests:

   Signalads::shouldReceive('send')
       ->once()
       ->andReturn(new SignaladsResponse(['success' => true]));