Smsru Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require zelenin/smsru
   

   Register the service provider in config/app.php (if not auto-discovered):

   'providers' => [
       // ...
       Zelenin\SmsRu\SmsRuServiceProvider::class,
   ],
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Zelenin\SmsRu\SmsRuServiceProvider" --tag="config"
   

   Update config/smsru.php with your SMS.ru API credentials:

   'api_id' => env('SMSRU_API_ID'),
   'api_password' => env('SMSRU_API_PASSWORD'),
   

3. First Use Case: Sending an SMS Inject the SmsRu facade or service into a controller/console:

   use Zelenin\SmsRu\Facades\SmsRu;
   
   public function sendSms()
   {
       $response = SmsRu::send([
           'to' => '79123456789',
           'text' => 'Test message from Laravel',
       ]);
   
       return $response->success ? 'SMS sent!' : 'Failed: ' . $response->error;
   }
   

Implementation Patterns

Core Workflows

1. Sending SMS

   • Basic Usage:

     SmsRu::send(['to' => '79123456789', 'text' => 'Hello']);
     

   • With Options:

     SmsRu::send([
         'to'   => '79123456789',
         'text' => 'Hello',
         'from' => 'YourBrand', // Sender ID
         'translit' => true,    // Transliterate Cyrillic
     ]);
     

2. Checking Balance

   $balance = SmsRu::balance();
   

3. Retrieving Send Status

   $status = SmsRu::status(['id' => 123456789]);
   

4. Batch Processing Use a loop for bulk sends (with rate-limiting awareness):

   $phones = ['79123456789', '79123456790'];
   foreach ($phones as $phone) {
       SmsRu::send(['to' => $phone, 'text' => 'Batch message']);
       sleep(1); // Avoid hitting API limits
   }
   

Integration Tips

• Laravel Queues: Dispatch SMS jobs to a queue for async processing:

  use Zelenin\SmsRu\Jobs\SendSms;
  
  SendSms::dispatch(['to' => '79123456789', 'text' => 'Async message']);
  

• Events: Trigger events post-send (extend the package or use Laravel events):

  event(new SmsSent($response));
  

• Logging: Log responses for debugging:

  \Log::info('SMS Response', $response->toArray());
  

Gotchas and Tips

Pitfalls

1. Deprecated Package

   • Last release in 2018; verify API compatibility with SMS.ru’s current docs.
   • Mitigation: Fork the repo or use a maintained alternative like php-smsru.

2. Rate Limiting

   • SMS.ru enforces 1 SMS/sec for free plans. Ignoring this causes 429 Too Many Requests.
   • Fix: Implement exponential backoff or use queues.

3. Phone Format

   • Must include country code (e.g., 79123456789, not 9123456789).
   • Validation: Add a rule in Laravel:

     'phone' => 'required|regex:/^7\d{10}$/'
     

4. Character Limits

   • SMS.ru truncates messages > 70 chars (GSM-7) or 160 chars (Unicode).
   • Tip: Use mb_strlen() for accurate counting:

     if (mb_strlen($text, 'UTF-8') > 160) {
         throw new \InvalidArgumentException('Message too long');
     }
     

5. Error Handling

   • Responses may return non-standard errors. Parse carefully:

     if (!$response->success) {
         throw new \RuntimeException($response->error ?? 'Unknown error');
     }
     

Debugging

• Enable Debug Mode:

  SmsRu::setDebug(true); // Logs raw API responses
  

• Test with Sandbox: Use SMS.ru’s sandbox API for testing:

  SmsRu::setSandbox(true);
  

Extension Points

1. Custom Responses Extend the Zelenin\SmsRu\Response class to add fields:

   class ExtendedResponse extends \Zelenin\SmsRu\Response {
       public function getCost() { return $this->data['cost'] ?? 0; }
   }
   

2. API Wrapper Replace the underlying Guzzle client for custom logic:

   $client = new \GuzzleHttp\Client(['base_uri' => 'https://sms.ru/']);
   SmsRu::setClient($client);
   

3. Laravel Notifications Integrate with Laravel’s notifications:

   use Zelenin\SmsRu\Notifications\SendSmsNotification;
   
   Notification::route('sms', '79123456789')
               ->notify(new SendSmsNotification('Hello'));