Gsm Box Laravel Package

Getting Started

First Steps

1. Installation

   composer require bestnetwork/gsm-box
   

   Register the service provider in config/app.php under providers:

   BestNetwork\GSMBox\GSMBoxServiceProvider::class,
   

2. Publish Config

   php artisan vendor:publish --provider="BestNetwork\GSMBox\GSMBoxServiceProvider" --tag="config"
   

   This generates config/gsm-box.php. Review/modify default settings (e.g., default box type, timeout, retry logic).

3. Basic Usage Inject the GSMBox facade or service into a controller/service:

   use BestNetwork\GSMBox\Facades\GSMBox;
   
   public function sendSMS()
   {
       $response = GSMBox::sendSMS(
           phone: '+1234567890',
           message: 'Hello from GSMBox!'
       );
       return $response->success() ? 'Sent!' : 'Failed.';
   }
   

4. Quick Test Use the gsm-box:test Artisan command to verify connectivity:

   php artisan gsm-box:test
   

Implementation Patterns

Core Workflows

1. SMS Sending

   // Basic send
   GSMBox::sendSMS('+1234567890', 'Test message');
   
   // With options (e.g., priority, scheduling)
   GSMBox::sendSMS('+1234567890', 'Urgent!', [
       'priority' => 'high',
       'schedule' => now()->addMinutes(5),
   ]);
   

2. Box Management

   • List Connected Boxes:

     $boxes = GSMBox::boxes(); // Returns collection of active GSMBox instances
     

   • Select a Specific Box:

     GSMBox::on('box_identifier')->sendSMS(...);
     

3. Event Handling Subscribe to SMS events (e.g., SMSSent, SMSSentFailed) in EventServiceProvider:

   protected $listen = [
       \BestNetwork\GSMBox\Events\SMSSent::class => [
           \App\Listeners\LogSMSSent::class,
       ],
   ];
   

4. Queue Integration Configure config/gsm-box.php to use queues for async processing:

   'queue' => [
       'enabled' => true,
       'connection' => 'database',
   ],
   

   Dispatch jobs manually:

   GSMBox::dispatchSMS('+1234567890', 'Queued message');
   

5. Logging & Monitoring

   • Enable debug logs in config:

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

   • Use GSMBox::logs() to retrieve recent activity.

Integration Tips

• Laravel Notifications: Extend BestNetwork\GSMBox\Notifications\SMSMessage to customize notifications:

  use BestNetwork\GSMBox\Notifications\SMSMessage;
  
  SMSMessage::to($recipient)->content('Custom content');
  

• API Wrappers: Use the GSMBoxHttpClient trait to integrate with external GSM APIs if extending functionality.
• Testing: Mock the GSMBox facade in tests:

  $this->mock(GSMBox::class)->shouldReceive('sendSMS')->andReturn(new \BestNetwork\GSMBox\Responses\SuccessResponse());
  

Gotchas and Tips

Common Pitfalls

1. Connection Issues

   • Symptom: SMS fails silently or times out.
   • Fix: Verify config/gsm-box.php settings (e.g., timeout, retry_attempts). Check if the GSM box is online:

     php artisan gsm-box:status
     

   • Debug: Enable debug: true and check logs for HTTP errors.

2. Character Limits

   • GSM boxes often enforce 70-character limits per segment. Long messages auto-split, but test edge cases:

     GSMBox::sendSMS('+1234567890', str_repeat('a', 200)); // May split into 3 segments
     

3. Rate Limiting

   • Some boxes throttle requests. Configure throttle in config:

     'throttle' => [
         'max_attempts' => 10,
         'per_minute' => 60,
     ],
     

4. Facade vs. Service Container

   • Avoid: Directly instantiating GSMBox classes (e.g., new \BestNetwork\GSMBox\GSMBox). Use dependency injection or the facade.

5. Queue Stuck Jobs

   • If using queues, monitor failed_jobs table. Retry manually:

     php artisan queue:retry all
     

Debugging Tips

• Artisan Commands:
  • php artisan gsm-box:list: List all configured boxes.
  • php artisan gsm-box:clear-cache: Clear cached box configurations.
• Log Levels: Configure log_level in config (debug, info, error) to filter logs.
• Environment Variables: Override settings via .env:

  GSMBOX_DEFAULT_BOX=box_identifier
  GSMBOX_TIMEOUT=30
  

Extension Points

1. Custom Box Types Extend BestNetwork\GSMBox\Contracts\Box to support new hardware:

   class CustomBox implements Box {
       public function send($message) { ... }
       public function status() { ... }
   }
   

   Register in config:

   'boxes' => [
       'custom' => \App\Boxes\CustomBox::class,
   ],
   

2. Response Handlers Override default responses by binding a custom handler:

   GSMBox::extend(function ($app) {
       $app->bind(\BestNetwork\GSMBox\Contracts\Response::class, \App\Responses\CustomResponse::class);
   });
   

3. Middleware Add middleware to config/gsm-box.php to validate/transform messages:

   'middleware' => [
       \App\Middleware\ValidateRecipient::class,
   ],