Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require chaboksms/laravel
   

   Publish the config file:

   php artisan vendor:publish --provider="Chaboksms\Laravel\ChaboksmsServiceProvider" --tag="config"
   

2. Configuration:

   • Edit .env with your Chaboksms credentials:

     CHABOKSMS_API_KEY=your_api_key_here
     CHABOKSMS_API_SECRET=your_api_secret_here
     

   • Verify the config/chaboksms.php file matches your setup (e.g., sandbox vs. production).

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

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

Implementation Patterns

Core Workflows

1. Sending SMS:

   • Basic Usage:

     Chaboksms::send([
         'to' => '09123456789',
         'message' => 'Your OTP is 12345',
         'type' => 'transactional', // Optional: 'promotional' or 'transactional'
     ]);
     

   • Bulk SMS:

     Chaboksms::sendBulk([
         'to' => ['09123456789', '09987654321'],
         'message' => 'Bulk message for all recipients',
     ]);
     

2. Handling Responses:

   • Use callbacks for async responses:

     Chaboksms::send([
         'to' => '09123456789',
         'message' => 'Callback test',
     ], function ($response) {
         // Handle success/failure
         if ($response->success) {
             Log::info('SMS sent:', ['id' => $response->id]);
         }
     });
     

3. OTP Management:

   • Generate and send OTPs with built-in helpers:

     $otp = Chaboksms::generateOtp(6); // 6-digit OTP
     Chaboksms::sendOtp('09123456789', $otp, 'Your verification code');
     

4. Queue Integration:

   • Dispatch SMS jobs to queues for background processing:

     use Chaboksms\Laravel\Jobs\SendSmsJob;
     
     SendSmsJob::dispatch([
         'to' => '09123456789',
         'message' => 'Queued message',
     ]);
     

Integration Tips

1. Validation:

   • Validate phone numbers before sending:

     use Chaboksms\Laravel\Rules\ValidIranianPhone;
     
     $request->validate([
         'phone' => ['required', new ValidIranianPhone],
     ]);
     

2. Logging:

   • Enable logging in config/chaboksms.php to track SMS activity:

     'log' => [
         'enabled' => true,
         'channel' => 'single',
     ],
     

3. Testing:

   • Use the sandbox environment for development:

     CHABOKSMS_ENVIRONMENT=sandbox
     

   • Mock responses in tests:

     Chaboksms::shouldReceive('send')->andReturn(['success' => true]);
     

4. Webhooks:

   • Set up webhook endpoints to handle delivery reports:

     Route::post('/chaboksms/webhook', [SmsWebhookController::class, 'handle']);
     

Gotchas and Tips

Pitfalls

1. Phone Number Format:

   • Ensure phone numbers are in the correct format (e.g., 09123456789 for Iran). Invalid formats will fail silently or return errors.

2. Rate Limits:

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

     try {
         Chaboksms::send($request);
     } catch (\Chaboksms\Laravel\Exceptions\RateLimitExceeded $e) {
         sleep(2); // Retry after delay
         Chaboksms::send($request);
     }
     

3. Async Delays:

   • Async responses may take time. Avoid relying on immediate callbacks for critical logic (e.g., OTP validation).

4. Configuration Overrides:

   • Avoid hardcoding API keys in code. Always use .env or Laravel's config system.

Debugging

1. Enable Debug Mode:

   • Set debug to true in config/chaboksms.php to log raw API responses:

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

2. Common Errors:

   • Invalid API Key: Verify .env and config file.
   • Invalid Phone Number: Check phone number format (e.g., 09123456789).
   • Balance Insufficient: Monitor your Chaboksms balance via their dashboard.

3. Testing Locally:

   • Use the sandbox environment to avoid real charges:

     CHABOKSMS_ENVIRONMENT=sandbox
     

Extension Points

1. Custom Requests:

   • Extend the package by creating a custom request class:

     namespace App\Services;
     
     use Chaboksms\Laravel\Requests\SendSmsRequest;
     
     class CustomSendSmsRequest extends SendSmsRequest {
         public function rules() {
             return array_merge(parent::rules(), [
                 'custom_field' => 'sometimes|string',
             ]);
         }
     }
     

   • Bind it in AppServiceProvider:

     Chaboksms::extend('custom', function () {
         return new CustomSendSmsRequest();
     });
     

2. Middleware:

   • Add middleware to validate or modify requests:

     Chaboksms::extend(function ($request) {
         $request->merge(['custom_header' => 'value']);
         return $request;
     });
     

3. Events:

   • Listen for SMS events (e.g., SmsSent):

     Chaboksms::on('SmsSent', function ($sms) {
         // Trigger analytics or notifications
     });
     

4. Fallback Providers:

   • Implement a fallback to another SMS provider if Chaboksms fails:

     try {
         Chaboksms::send($request);
     } catch (\Exception $e) {
         FallbackSms::send($request); // Custom fallback logic
     }