Imasys Message Sender Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer in your Laravel project:

   composer require comsolit/imasys-message-sender-bundle
   

   Register the bundle in config/app.php under ExtraBundles (Symfony) or manually in config/app.php under providers (Laravel 5.x/6.x/7.x/8.x).

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="Comsolit\ImasysMessageSenderBundle\ComsolitImasysMessageSenderBundle" --tag=config
   

   Update config/imasys_message_sender.php with your IMASYS API credentials and endpoint.

3. First Use Case Inject the ImasysMessageSender service into a controller or service:

   use Comsolit\ImasysMessageSenderBundle\Service\ImasysMessageSender;
   
   class MessageController extends Controller
   {
       public function __construct(private ImasysMessageSender $sender) {}
   
       public function sendTestMessage()
       {
           $message = [
               'recipient' => '1234567890', // Phone number
               'message' => 'Hello from Laravel!',
               'sender' => 'YourApp'
           ];
   
           $response = $this->sender->sendMessage($message);
           return response()->json($response);
       }
   }
   

Implementation Patterns

Core Workflows

1. Sending Messages Use the sendMessage() method for basic SMS delivery:

   $this->sender->sendMessage([
       'recipient' => '1234567890',
       'message' => 'Your OTP is 12345',
       'sender' => 'BankApp',
       'type' => 'OTP' // Optional: Customize message type
   ]);
   

2. Batch Processing For bulk sends, leverage Laravel’s queues:

   $this->sender->sendMessage($message)->onQueue('sms');
   

   Configure the queue in config/imasys_message_sender.php:

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

3. Response Handling Parse responses with helper methods:

   $response = $this->sender->sendMessage($message);
   if ($this->sender->isSuccess($response)) {
       $messageId = $this->sender->getMessageId($response);
   }
   

Integration Tips

• Logging: Enable debug logging in config to track API calls:

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

• Fallbacks: Implement a fallback sender (e.g., Twilio) if IMASYS fails:

  try {
      $this->sender->sendMessage($message);
  } catch (ImasysException $e) {
      $fallbackSender->send($message);
  }
  

• Validation: Validate phone numbers before sending:

  use Comsolit\ImasysMessageSenderBundle\Validator\PhoneValidator;
  
  if (!PhoneValidator::validate($phoneNumber)) {
      throw new \InvalidArgumentException('Invalid phone number');
  }
  

Gotchas and Tips

Common Pitfalls

1. Deprecation Risk

   • The package is unmaintained. Test thoroughly and consider forking or replacing with alternatives (e.g., laravel-notification-channels/imasys if available).
   • Monitor for breaking changes in the underlying imasys-php library.

2. Configuration Quirks

   • API Credentials: Ensure client_id and client_secret are correctly set in config. IMASYS may require OAuth tokens or API keys.
   • Endpoint URLs: Verify the api_url in config matches IMASYS’s current endpoint (e.g., https://api.imasys.com/v2/sms).

3. Error Handling

   • IMASYS may return non-standard error formats. Extend the ImasysException class to handle custom errors:

     catch (ImasysException $e) {
         if ($e->getCode() === 401) {
             // Handle unauthorized (e.g., retry with refreshed token)
         }
     }
     

4. Rate Limiting

   • IMASYS may throttle requests. Implement exponential backoff in your retry logic:

     use Symfony\Component\Process\Exception\TimeoutException;
     
     try {
         $this->sender->sendMessage($message);
     } catch (TimeoutException $e) {
         sleep(2 ** $attempt); // Exponential backoff
         retry();
     }
     

Extension Points

1. Custom Message Templates Override the MessageBuilder service to add dynamic templates:

   $this->app->bind(MessageBuilder::class, function ($app) {
       return new CustomMessageBuilder($app->make('imasys.client'));
   });
   

2. Webhook Listeners Extend the bundle to listen for IMASYS delivery reports:

   $this->sender->onDeliveryReport(function ($report) {
       // Log or process delivery status
   });
   

3. Testing Mock the ImasysClient in PHPUnit:

   $mockClient = $this->createMock(ImasysClient::class);
   $mockClient->method('send')->willReturn(['status' => 'success']);
   
   $this->app->instance(ImasysClient::class, $mockClient);
   

Debugging Tips

• Enable Verbose Logging: Set 'debug' => true in config and check Laravel logs for raw API responses.
• API Inspection: Use tools like Postman to verify IMASYS API endpoints independently.
• Dependency Conflicts: Ensure comsolit/imasys-php is compatible with your PHP version (e.g., PHP 7.4+).