Smsservice Bundle Laravel Package

Getting Started

Minimal Steps to First SMS Send

1. Install the Bundle

   composer require amorebietakoudala/smsservice-bundle
   

2. Configure .env Add these to your .env file (Laravel-compatible):

   SMS_USERNAME=your_dinasms_username
   SMS_PASSWORD=your_dinasms_password
   SMS_ACCOUNT=your_account_id
   SMS_TEST=false  # Set to `true` for testing (no real sends)
   SMS_PROVIDER=dinasms  # Options: dinasms, acumbamail, smspubli
   

3. Verify Installation

   • For Symfony: Visit /smsBundle/ to check remaining credits.
   • For Laravel: Create a route to call the bundle’s service directly (see Implementation Patterns).

4. First SMS Send (Symfony Route) Use the bundle’s built-in route (Symfony only):

   /smsBundle/send?phone=3412345678&message=Hello
   

   Laravel Workaround: Create a controller to call the service:

   use Amorebietakoudala\SMSServiceBundle\Service\SMSService;
   
   public function sendSMS(SMSService $smsService) {
       $result = $smsService->send('3412345678', 'Hello');
       return response()->json($result);
   }
   

Implementation Patterns

Core Workflows

1. Sending SMS via Service Container

Symfony/Laravel (with Bridge):

// In a controller or command
public function __invoke(SMSService $smsService) {
    $response = $smsService->send(
        '34600123456',  // Recipient phone (format: countrycode+number)
        'Your OTP is 12345'
    );
    return $response->getStatusCode() === 200;
}

Laravel (Manual Binding): Bind the Symfony service to Laravel’s container in AppServiceProvider:

$this->app->bind(\Amorebietakoudala\SMSServiceBundle\Service\SMSService::class,
    function ($app) {
        return new \Amorebietakoudala\SMSServiceBundle\Service\SMSService(
            $app['config']['sms.username'],
            $app['config']['sms.password'],
            $app['config']['sms.provider']
        );
    }
);

2. Provider-Specific Configuration

Override default provider settings in config/packages/amorebietakoudala_sms.yaml (Symfony) or config/sms.php (Laravel):

# Symfony config
amorebietakoudala_sms:
    providers:
        dinasms:
            username: '%env(SMS_USERNAME)%'
            password: '%env(SMS_PASSWORD)%'
            endpoint: 'https://api.dinasms.com/send'

Laravel Equivalent:

// config/sms.php
return [
    'providers' => [
        'dinasms' => [
            'username' => env('SMS_USERNAME'),
            'password' => env('SMS_PASSWORD'),
            'endpoint' => 'https://api.dinasms.com/send',
        ],
    ],
];

3. Testing Mode

• Set SMS_TEST=true in .env to bypass real API calls.
• Laravel Testing: Mock the SMSService in PHPUnit:

  $mock = Mockery::mock(SMSService::class);
  $mock->shouldReceive('send')
       ->once()
       ->andReturn(new Response(200, [], '{"status":"success"}'));
  
  $this->app->instance(SMSService::class, $mock);
  

4. Bulk SMS (Limited Support)

The bundle doesn’t natively support bulk sends. Workaround:

• Loop in Laravel and batch calls:

  foreach ($phones as $phone) {
      $smsService->send($phone, $message);
      sleep(1); // Rate limiting
  }
  

• For high volume, use a queue job (see Gotchas).

5. Error Handling

Wrap API calls to handle failures:

try {
    $response = $smsService->send($phone, $message);
    if ($response->getStatusCode() !== 200) {
        Log::error('SMS failed', ['error' => $response->getContent()]);
        throw new \RuntimeException('SMS delivery failed');
    }
} catch (\Exception $e) {
    // Retry logic or fallback
}

Integration Tips

Laravel-Specific Patterns

1. Queue SMS Jobs Create a job to send SMS asynchronously:

   php artisan make:job SendSmsJob
   

   // app/Jobs/SendSmsJob.php
   public function handle(SMSService $smsService) {
       $smsService->send($this->phone, $this->message);
   }
   

   Dispatch in a controller:

   SendSmsJob::dispatch('34600123456', 'Your message')->onQueue('sms');
   

2. Event-Driven SMS Trigger SMS on Laravel events (e.g., OrderShipped):

   // Listen to event
   event(new OrderShipped($order));
   

   // In event listener
   SendSmsJob::dispatch($order->customerPhone, 'Order shipped!');
   

3. API Resource Wrapper Create a Laravel API resource to standardize SMS responses:

   namespace App\Http\Resources;
   use Illuminate\Http\Resources\Json\JsonResource;
   
   class SmsResponse extends JsonResource {
       public function toArray($request) {
           return [
               'status' => $this->status,
               'message' => $this->message,
               'provider' => $this->provider,
           ];
       }
   }
   

Symfony-Laravel Bridge

If using the Symfony Bridge:

• Load the Bundle: Add to config/bundles.php:

  return [
      // ...
      Amorebietakoudala\SMSServiceBundle\SMSServiceBundle::class => ['all' => true],
  ];
  

• Access Services: Autowire SMSService in controllers:

  use Amorebietakoudala\SMSServiceBundle\Service\SMSService;
  
  public function __construct(private SMSService $smsService) {}
  

Multi-Provider Strategy

To switch providers dynamically:

1. Extend the Bundle: Create a custom provider class.
2. Configure in Laravel:

   // config/sms.php
   'default_provider' => env('SMS_PROVIDER', 'dinasms'),
   'providers' => [
       'dinasms' => [...],
       'acumbamail' => [...],
   ],
   

3. Factory Pattern:

   class SmsFactory {
       public static function create(string $provider) {
           return match ($provider) {
               'dinasms' => new DinSmsService(...),
               'acumbamail' => new AcumbaMailService(...),
               default => throw new \InvalidArgumentException('Provider not supported'),
           };
       }
   }
   

Gotchas and Tips

Pitfalls

1. Symfony Dependency Hell

   • Issue: The bundle requires Symfony components (e.g., HttpClient, DependencyInjection).
   • Fix: Use the Symfony Bridge or manually reimplement services in Laravel.
   • Workaround: Check for Laravel-native alternatives like spatie/laravel-sms.

2. Provider-Specific Quirks

   • dinaSMS: Requires exact phone format (e.g., 34600123456 for Spain).
   • Acumbamail: Date formats changed in v1.1.4 (now YYYY-MM-DD HH:MM).
   • Smspubli: Limited documentation; test thoroughly.

3. No Native Queue Support

   • Issue: The bundle doesn’t integrate with Laravel Queues.
   • Fix: Wrap calls in a SendSmsJob (see Implementation Patterns).

4. Testing Mode Limitations

   • Issue: SMS_TEST=true only prevents API calls but doesn’t mock responses.
   • Fix: Combine with Laravel’s MockHttp:

     $this->mock(Http::class, function ($mock) {
         $mock->shouldReceive('post')
              ->once()
              ->andReturn(Http::response('{"status":"success"}', 200));