Cirici Beacon Control Client Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Symfony project via Composer:

   composer require ciricihq/cirici-beacon-control-client-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       CiriciHQ\BeaconControlClientBundle\CiriciBeaconControlClientBundle::class => ['all' => true],
   ];
   

2. Configuration Define API credentials in config/packages/cirici_beacon_control_client.yaml:

   cirici_beacon_control_client:
       api_key: '%env(BEACON_CONTROL_API_KEY)%'
       base_uri: '%env(BEACON_CONTROL_BASE_URI)%'
   

3. First Use Case Fetch a beacon’s status in a controller:

   use CiriciHQ\BeaconControlClientBundle\Service\BeaconControlClient;
   
   class BeaconController extends AbstractController
   {
       public function showStatus(BeaconControlClient $client, string $beaconId): JsonResponse
       {
           $status = $client->getBeaconStatus($beaconId);
           return $this->json($status);
       }
   }
   

Implementation Patterns

Workflows

1. CRUD Operations Use the client for standard API interactions:

   // Create
   $client->createBeacon($beaconData);
   
   // Read
   $client->getBeaconStatus($beaconId);
   
   // Update
   $client->updateBeacon($beaconId, $updatedData);
   
   // Delete
   $client->deleteBeacon($beaconId);
   

2. Event-Driven Integrations Subscribe to beacon events (e.g., battery low) via webhooks:

   # config/packages/cirici_beacon_control_client.yaml
   cirici_beacon_control_client:
       webhook:
           endpoint: '/api/beacon/webhook'
           events: ['battery_low', 'status_change']
   

   Handle events in a Symfony event listener:

   use CiriciHQ\BeaconControlClientBundle\Event\BeaconEvent;
   
   public function onBeaconEvent(BeaconEvent $event): void
   {
       $this->logger->info('Beacon event:', ['data' => $event->getData()]);
   }
   

3. Batch Processing Fetch multiple beacons efficiently:

   $beacons = $client->getBeacons(['limit' => 100, 'offset' => 0]);
   

Integration Tips

• Dependency Injection: Prefer injecting BeaconControlClient over instantiating it manually.
• Error Handling: Wrap API calls in try-catch blocks to handle BeaconControlException:

  try {
      $client->getBeaconStatus($beaconId);
  } catch (BeaconControlException $e) {
      $this->addFlash('error', $e->getMessage());
  }
  

• Logging: Enable debug logging for API requests:

  cirici_beacon_control_client:
      debug: true
  

Gotchas and Tips

Pitfalls

1. API Rate Limits The bundle does not auto-retry on rate limits. Implement exponential backoff in your service layer:

   use Symfony\Component\HttpClient\RetryableHttpInterface;
   
   $client->withOptions([
       RetryableHttpInterface::RETRY_ON_STATUS_CODES => [429],
       RetryableHttpInterface::MAX_RETRIES => 3,
   ]);
   

2. Webhook Verification Always verify webhook payloads to prevent spoofing:

   public function handleWebhook(Request $request): Response
   {
       $payload = json_decode($request->getContent(), true);
       $signature = $request->headers->get('X-Signature');
   
       if (!$this->validateWebhookSignature($payload, $signature)) {
           throw $this->createAccessDeniedException();
       }
       // Process payload
   }
   

3. Deprecated Endpoints Monitor the BeaconControl API docs for breaking changes. Override the client if needed:

   $client = new CustomBeaconControlClient(
       $apiKey,
       $baseUri,
       ['custom_endpoint' => 'v2/beacons']
   );
   

Debugging

• Enable Verbose Logging:

  cirici_beacon_control_client:
      debug: true
      logging:
          level: debug
  

• Inspect HTTP Requests: Use Symfony’s profiler (_profiler) to view raw API calls.

Extension Points

1. Custom Responses Extend the BeaconControlClient to transform responses:

   class CustomBeaconControlClient extends BeaconControlClient
   {
       protected function transformBeaconStatus(array $data): array
       {
           return array_merge($data, ['formatted_at' => (new \DateTime())->format('Y-m-d H:i:s')]);
       }
   }
   

2. Middleware Add request/response middleware:

   $client->setMiddleware(function (callable $next) {
       return function ($request) use ($next) {
           $request = $request->withHeader('X-Custom-Header', 'value');
           return $next($request);
       };
   });
   

3. Testing Mock the client in PHPUnit:

   $mockClient = $this->createMock(BeaconControlClient::class);
   $mockClient->method('getBeaconStatus')->willReturn(['status' => 'active']);
   
   $this->container->set(BeaconControlClient::class, $mockClient);