Semaphore Laravel Package

Getting Started

Install the package via Composer:

composer require vendor/sms-package

Publish the configuration file (if available) to customize default settings:

php artisan vendor:publish --provider="Vendor\SmsPackage\SmsPackageServiceProvider"

Register the service provider in config/app.php under providers if not auto-discovered.

First Use Case: Sending an SMS Initialize the SMS client in a controller or service:

use Vendor\SmsPackage\Facades\SmsClient;

public function sendSms()
{
    $response = SmsClient::send([
        'to' => '1234567890',
        'message' => 'Hello via SMS!',
    ]);
    return $response;
}

Check the documentation for API key setup and rate limits.

Implementation Patterns

SMS Workflow

1. Queue SMS for Reliability Use Laravel’s queue system to defer SMS delivery (avoid timeouts):

   SmsClient::queueSend($phone, $message);
   

   Configure the queue worker in .env:

   QUEUE_CONNECTION=database
   

2. Batch Processing For bulk SMS (e.g., marketing), use chunking:

   $phones = ['123...', '456...']; // Array of numbers
   foreach (array_chunk($phones, 100) as $chunk) {
       SmsClient::sendBatch($chunk, $message);
   }
   

3. Template-Based Messages Store reusable templates in the database (e.g., sms_templates table) and fetch them dynamically:

   $template = DB::table('sms_templates')->where('key', 'welcome')->first();
   SmsClient::send($phone, $template->message);
   

Account Management

Integrate account status checks into your auth flow:

use Vendor\SmsPackage\Facades\AccountChecker;

public function checkAccount()
{
    $status = AccountChecker::status();
    if ($status->isActive()) {
        // Proceed with SMS features
    } else {
        abort(503, 'SMS service unavailable');
    }
}

Logging and Reporting

Leverage the built-in log reporter for compliance/auditing:

// Fetch logs for a specific phone number
$logs = SmsClient::logs()->forPhone('1234567890')->get();

// Export logs to CSV (if supported)
$logs->export('sms_logs.csv');

Gotchas and Tips

Common Pitfalls

1. Rate Limiting The package enforces default rate limits (e.g., 1 SMS/sec). Exceeding limits may silently fail. Monitor with:

   $rateLimit = SmsClient::rateLimit();
   if ($rateLimit->remaining() < 5) {
       sleep(1); // Throttle manually
   }
   

2. Phone Number Formatting Ensure numbers are in E.164 format (e.g., +1234567890). Use a helper:

   use Vendor\SmsPackage\Support\Phone;
   $normalized = Phone::normalize('1234567890'); // Returns '+1234567890'
   

3. Logging Overhead Message logs consume storage. Prune old logs via a scheduled task:

   // app/Console/Commands/CleanSmsLogs.php
   public function handle()
   {
       SmsClient::logs()->pruneOlderThan(Carbon::now()->subDays(30));
   }
   

Extension Points

1. Custom Log Fields Extend the SmsLog model to add metadata (e.g., user_id):

   // app/Models/SmsLog.php
   protected $casts = [
       'metadata' => 'array',
   ];
   

   Attach data when sending:

   SmsClient::send($phone, $message, ['user_id' => auth()->id()]);
   

2. Webhook Integration Listen for delivery receipts via webhooks. Example listener:

   // routes/web.php
   Route::post('/sms-webhook', [SmsWebhookHandler::class, 'handle']);
   

   Implement SmsWebhookHandler to parse payloads and update logs.

3. Fallback Providers For high availability, chain multiple SMS providers:

   SmsClient::setFallbackProviders([
       'provider1' => ['key' => '...'],
       'provider2' => ['key' => '...'],
   ]);
   

Debugging

• Enable Verbose Logging Set in .env:

  SMS_PACKAGE_LOG_LEVEL=debug
  

• Simulate Failures Use the mock facade for testing:

  SmsClient::mock()->shouldFailOnSend();
  

• Check HTTP Errors Wrap calls in try-catch to inspect provider-specific errors:

  try {
      SmsClient::send($phone, $message);
  } catch (\Vendor\SmsPackage\Exceptions\SmsException $e) {
      Log::error($e->getProviderError());
  }