Smsapi Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require cogitech/smsapi-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Cogitech\SMSAPIBundle\SMSAPIBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console smsapi:install
   

   Update config/packages/smsapi.yaml with your SMSAPI.pl credentials:

   smsapi:
       api_key: 'your_api_key_here'
       sender_id: 'your_sender_id'
   

3. First Use Case Send a basic SMS via a controller:

   use Cogitech\SMSAPIBundle\Service\SMSAPIClient;
   
   class MessageController extends AbstractController
   {
       public function sendSMS(SMSAPIClient $client)
       {
           $response = $client->sendSMS(
               '+48123456789',
               'Hello from Laravel!'
           );
   
           return new JsonResponse($response);
       }
   }
   

Implementation Patterns

Core Workflows

1. Sending SMS Use the SMSAPIClient service for direct API calls:

   $client->sendSMS(
       $recipient,  // String (e.g., '+48123456789')
       $message,    // String (max 160 chars)
       $senderId    // Optional (defaults to config)
   );
   

2. Bulk SMS For multiple recipients, use the sendBulkSMS method:

   $client->sendBulkSMS(
       ['+48123456789', '+48987654321'],
       'Your bulk message'
   );
   

3. Queue Integration Wrap calls in a job for async processing:

   use Cogitech\SMSAPIBundle\Job\SendSMSJob;
   
   SendSMSJob::dispatch($recipient, $message)->onQueue('sms');
   

Common Integrations

• Validation: Validate phone numbers with Symfony’s Validator:

  $constraint = new PhoneNumber($options);
  $errors = $validator->validate($phoneNumber, $constraint);
  

• Logging: Log responses for debugging:

  # config/packages/monolog.yaml
  handlers:
      smsapi:
          type: stream
          path: "%kernel.logs_dir%/smsapi.log"
          level: debug
  

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

  // src/EventListener/SMSListener.php
  public function onSMSsent(SMSSentEvent $event)
  {
      // Handle success/failure
  }
  

Gotchas and Tips

Pitfalls

1. API Key Exposure

   • Never commit config/packages/smsapi.yaml to version control.
   • Use environment variables:

     # .env
     SMSAPI_API_KEY=your_key_here
     SMSAPI_SENDER_ID=your_sender
     

     Update the config to read from .env:

     smsapi:
         api_key: '%env(SMSAPI_API_KEY)%'
     

2. Character Limits

   • SMSAPI.pl enforces a 160-character limit per message. Longer messages auto-split (costs extra).
   • Test with:

     $client->checkMessageLength($message); // Returns boolean
     

3. Rate Limits

   • SMSAPI.pl throttles requests. Implement retries with exponential backoff:

     use Symfony\Component\Retry\Retry;
     
     $retry = new Retry(3, 1000); // 3 retries, 1s delay
     $response = $retry->retry(
         fn() => $client->sendSMS($phone, $message)
     );
     

4. Sender ID Restrictions

   • Some sender IDs require approval. Test in sandbox first:

     smsapi:
         sandbox: true # Uses SMSAPI.pl's test environment
     

Debugging

• Enable Debug Mode:

  smsapi:
      debug: true # Logs raw API requests/responses
  

• Check HTTP Status Codes: Wrap calls in a try-catch to handle SMSAPIException:

  try {
      $client->sendSMS($phone, $message);
  } catch (SMSAPIException $e) {
      // Handle 4xx/5xx errors (e.g., invalid API key)
      $this->addFlash('error', $e->getMessage());
  }
  

Extension Points

1. Custom Response Handling Extend the SMSAPIClient to parse responses:

   class CustomSMSAPIClient extends SMSAPIClient
   {
       protected function parseResponse($data)
       {
           // Override to add custom fields
           return parent::parseResponse($data) + ['custom_field' => true];
       }
   }
   

   Register as a service:

   services:
       App\Service\CustomSMSAPIClient:
           decorates: 'smsapi.client'
   

2. Add New Endpoints Use the HttpClient directly for unsupported API calls:

   $httpClient = $this->container->get('http_client');
   $response = $httpClient->request('GET', 'https://api.smsapi.pl/v1/balances');
   

3. Template Management For reusable templates, create a SMSTemplate entity and a repository:

   // src/Repository/SMSTemplateRepository.php
   class SMSTemplateRepository extends ServiceEntityRepository
   {
       public function findByName(string $name): ?SMSTemplate
       {
           return $this->createQueryBuilder('t')
               ->where('t.name = :name')
               ->setParameter('name', $name)
               ->getQuery()
               ->getOneOrNullResult();
       }
   }