Sms Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Run:

   composer require amirjon/sms-bundle
   

   (Note: Fix typo in sms-bunle → sms-bundle in your docs.)

2. Register Bundle Add to config/bundles.php:

   Amir\SmsBundle\SmsBundle::class => ['all' => true],
   

3. Configure .env Add Eskiz credentials (replace placeholders):

   ESKIZ_EMAIL=your@email.com
   ESKIZ_PASSWORD=your_secure_password
   ESKIZ_FROM=your_sender_number  # e.g., "998123456789"
   

4. First Use Case Inject SmsSender into a class (e.g., a controller or service) and send an SMS:

   use Amir\SmsBundle\Services\SmsSender;
   
   class MyController {
       public function __construct(private SmsSender $sender) {}
   
       public function sendWelcomeSms() {
           $this->sender->sendMessage('998123456789', 'Welcome to our platform!');
       }
   }
   

Implementation Patterns

Dependency Injection

• Preferred Approach: Use constructor injection for SmsSender in services/controllers.

  public function __construct(private SmsSender $sender) {}
  

• Service Binding: Register custom bindings if extending functionality:

  $this->app->bind(SmsSender::class, function ($app) {
      return new CustomSmsSender($app->make(SmsSender::class));
  });
  

Workflows

1. Basic SMS Sending

   $this->sender->sendMessage('+1234567890', 'Your OTP is 123456');
   

   (Note: Validate phone numbers with Str::startsWith($number, '+') or similar.)

2. Bulk SMS Loop through recipients (no built-in bulk method; implement manually):

   foreach ($recipients as $phone) {
       $this->sender->sendMessage($phone, $message);
   }
   

3. Async Processing Use Laravel Queues to offload SMS sending:

   SendSmsJob::dispatch($phone, $message);
   

   (Requires custom job class; package lacks built-in queue support.)

Integration Tips

• Validation: Validate phone numbers before sending:

  use Illuminate\Support\Facades\Validator;
  
  $validator = Validator::make(['phone' => $phone], [
      'phone' => 'required|string|starts_with:+,998|digits_between:9,15'
  ]);
  

• Logging: Wrap calls in try-catch to log failures:

  try {
      $this->sender->sendMessage($phone, $message);
  } catch (\Exception $e) {
      \Log::error("SMS failed for $phone: " . $e->getMessage());
  }
  

• Configuration: Override defaults via config/sms.php (create file if missing):

  return [
      'default_from' => '998901234567',
      'timeout' => 30, // seconds
  ];
  

Gotchas and Tips

Pitfalls

1. Typo in Package Name

   • The composer.json lists amirjon/sms-bundle, but the README shows sms-bunle. Double-check installation.

2. No Error Handling

   • The sendMessage() method lacks explicit error handling. Wrap calls in try-catch blocks.

3. Phone Number Format

   • Eskiz may require specific formats (e.g., +998912345678). Test with your provider’s format.

4. No Rate Limiting

   • Eskiz may throttle requests. Implement retries with exponential backoff:

     use Illuminate\Support\Facades\Http;
     
     Http::timeout(30)->retry(3, 100);
     

5. Dependency Conflicts

   • The package requires Symfony 6.2. Ensure your Laravel version (9.x/10.x) is compatible.

Debugging

• Check Eskiz Credentials Verify .env values and test manually via Eskiz’s API docs.
• Enable Debugging Temporarily log raw HTTP requests:

  \Log::debug('SMS Request:', [
      'url' => $this->sender->getEndpoint(),
      'data' => $this->sender->getPayload($phone, $message),
  ]);
  

• Symfony HTTP Client If issues arise, inspect the underlying client:

  $this->sender->getHttpClient()->withOptions(['debug' => true]);
  

Extension Points

1. Custom Providers Extend Amir\SmsBundle\Services\SmsSender to support other APIs (e.g., Clickatell):

   class CustomSmsSender extends SmsSender {
       public function sendMessage(string $phone, string $message): bool {
           // Implement alternative logic
       }
   }
   

2. Middleware Add middleware to validate SMS content or log messages:

   $this->app->bind(SmsSender::class, function ($app) {
       $sender = new SmsSender($app);
       return new Middleware\SmsLogger($sender);
   });
   

3. Events Dispatch events before/after sending (requires custom implementation):

   event(new SmsSent($phone, $message));
   

Configuration Quirks

• Default Sender The ESKIZ_FROM in .env sets the default sender ID. Override per-message if needed:

  $this->sender->sendMessage($phone, $message, ['from' => '998901234567']);
  

• Timeouts Adjust Symfony HTTP client timeouts in config/sms.php:

  'http_client' => [
      'timeout' => 60, // seconds
      'connect_timeout' => 10,
  ],
  

Pro Tips

• Unit Testing Mock SmsSender in tests:

  $mock = Mockery::mock(SmsSender::class);
  $mock->shouldReceive('sendMessage')->once();
  

• Environment-Specific Configs Use Laravel’s config('sms.timeout') for dynamic values.
• Monitor Usage Track SMS costs by logging sent messages to a database table:

  \DB::table('sms_logs')->insert([
      'phone' => $phone,
      'message' => $message,
      'sent_at' => now(),
  ]);