Sdk Sierra Iot M2M Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer (note: this is a legacy package with outdated dependencies):

   composer require dodev34/sdk-sierra-iot-m2m-bundle:dev-master
   

   Update composer.json to match the provided psr-4 autoloading and dependencies.

2. Configuration Create config/packages/m12u_sdk_sierra_iot_m2m.yaml (or add to parameters.yml):

   m12u.sdk.sierra.iot_m2m:
       uri_oauth_token: "https://eu.airvantage.net/api/oauth/token"
       username: "%env(AIRVANTAGE_USERNAME)%"
       password: "%env(AIRVANTAGE_PASSWORD)%"
       base_uri: "https://eu.airvantage.net"
       client_id: "%env(AIRVANTAGE_CLIENT_ID)%"
       client_secret: "%env(AIRVANTAGE_CLIENT_SECRET)%"
       grant_type: "password"
   

   Use environment variables for sensitive data (e.g., .env).

3. First Use Case: Fetching OAuth Token Inject the service into a controller or command:

   use M12U\Bundle\Sdk\Sierra\IotM2MBundle\Service\AirvantageService;
   
   class MyController extends AbstractController {
       public function __construct(private AirvantageService $airvantage) {}
   
       public function index() {
           $token = $this->airvantage->getOAuthToken();
           // Use $token for API requests
       }
   }
   

Implementation Patterns

Core Workflows

1. Authentication Flow

   • Use AirvantageService to handle OAuth2 token retrieval:

     $token = $this->airvantage->getOAuthToken();
     $this->airvantage->setToken($token); // Cache for subsequent requests
     

   • For long-lived tokens, store the token in the session or database after the first fetch.

2. API Requests

   • Wrap Guzzle HTTP client calls in service methods (e.g., getSimCards(), getDeviceData()).
   • Example:

     $simCards = $this->airvantage->fetchResource('/simcards', [
         'limit' => 10,
         'offset' => 0
     ]);
     

3. Event-Driven Remote Analysis

   • Poll for device events (e.g., usage alerts) via cron jobs:

     $events = $this->airvantage->getEventsSince(\Carbon\Carbon::now()->subHours(1));
     foreach ($events as $event) {
         $this->handleEvent($event);
     }
     

4. Bulk Operations

   • Use batch endpoints (e.g., /simcards/bulk) for cost optimization:

     $this->airvantage->bulkUpdateSimCards([
         ['iccid' => '123', 'status' => 'active'],
         ['iccid' => '456', 'status' => 'suspended']
     ]);
     

Integration Tips

• Laravel Service Provider Extend the bundle’s M12USdkSierraIotM2MBundle to bind additional services:

  public function register() {
      $this->container->singleton('airvantage.analyzer', function ($c) {
          return new DeviceUsageAnalyzer($c->get('m12u.sdk.sierra.iot_m2m.service'));
      });
  }
  

• Queue Jobs Offload long-running operations (e.g., SIM card provisioning) to Laravel queues:

  dispatch(new ProvisionSimCardJob($iccid, $planId));
  

• API Rate Limiting Implement a decorator pattern to handle rate limits:

  class RateLimitedAirvantageService {
      public function fetchResource($endpoint, $params) {
          $retries = 0;
          while ($retries < 3) {
              try {
                  return $this->decorated->fetchResource($endpoint, $params);
              } catch (RateLimitExceededException $e) {
                  sleep(10);
                  $retries++;
              }
          }
          throw new \RuntimeException("API rate limit exceeded");
      }
  }
  

Gotchas and Tips

Pitfalls

1. Deprecated Dependencies

   • The package requires PHP 5.3+ and Symfony 2.8+, which is highly outdated. Use a compatibility layer (e.g., nikic/php-parser) or fork the package for modern PHP.
   • Workaround: Override the GuzzleHttp\Client binding to use GuzzleHttp\Client v7+:

     $this->container->bind('m12u.sdk.sierra.iot_m2m.http_client', function () {
         return new \GuzzleHttp\Client();
     });
     

2. Token Expiry

   • OAuth tokens expire quickly (e.g., 1 hour). Implement a token refresh strategy:

     try {
         $response = $this->airvantage->getOAuthToken();
     } catch (TokenExpiredException $e) {
         $this->airvantage->refreshToken();
         $response = $this->airvantage->getOAuthToken();
     }
     

3. Error Handling

   • The bundle lacks structured error handling. Extend the service to throw custom exceptions:

     class AirvantageException extends \RuntimeException {}
     class InvalidSimCardException extends AirvantageException {}
     
     // In your service:
     if (!$simCard) {
         throw new InvalidSimCardException("SIM card not found");
     }
     

4. Configuration Overrides

   • Hardcoded values in the bundle (e.g., /api/oauth/token) may not match your Airvantage instance. Override them in config/packages/m12u_sdk_sierra_iot_m2m.yaml:

     m12u.sdk.sierra.iot_m2m:
         uri_oauth_token: "%env(AIRVANTAGE_OAUTH_URI)%"
     

Debugging Tips

1. Enable Guzzle Middleware Add logging to HTTP requests:

   $this->container->bind('m12u.sdk.sierra.iot_m2m.http_client', function () {
       return new \GuzzleHttp\Client([
           'middleware' => [
               new \GuzzleHttp\Middleware::tap(function ($request) {
                   \Log::debug('Request:', [
                       'url' => (string) $request->getUri(),
                       'method' => $request->getMethod(),
                       'headers' => $request->getHeaders(),
                   ]);
               }),
           ],
       ]);
   });
   

2. Validate API Responses Use Laravel’s Validator to parse Airvantage’s JSON responses:

   $response = $this->airvantage->fetchResource('/devices');
   $data = json_decode($response, true);
   Validator::make($data, [
       'devices.*.iccid' => 'required|string',
       'devices.*.status' => 'in:active,inactive,suspended',
   ]);
   

3. Test with Mocks Mock the AirvantageService in tests:

   $mock = Mockery::mock('M12U\Bundle\Sdk\Sierra\IotM2MBundle\Service\AirvantageService');
   $mock->shouldReceive('getSimCards')->andReturn([$simCardMock]);
   $this->app->instance('m12u.sdk.sierra.iot_m2m.service', $mock);
   

Extension Points

1. Custom Endpoints Extend the service to support non-standard Airvantage endpoints:

   class ExtendedAirvantageService extends \M12U\Bundle\Sdk\Sierra\IotM2MBundle\Service\AirvantageService {
       public function getCustomReport($reportId) {
           return $this->request('GET', "/reports/custom/{$reportId}");
       }
   }
   

2. Webhook Listener Add a Symfony EventDispatcher listener for Airvantage webhooks:

   $dispatcher->addListener('airvantage.webhook.received', function ($event) {
       $payload = $event->getPayload();
       // Process webhook (e.g., SIM usage alerts)
   });
   

3. Local Caching Cache API responses with Laravel’s cache:

   $cacheKey = "airvantage_simcards_{$limit}_{$offset}";
   return Cache::remember($cacheKey, now()->addMinutes(5), function () use ($limit, $offset) {
       return $this->airvantage->fetchResource('/simcards', compact('limit', 'offset'));
   });