Brk Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Install via Composer

   composer require common-gateway/brk-bundle
   

   Ensure your composer.json includes Symfony 5+ and PHP 7.4+.

2. Enable the Bundle Add to config/bundles.php:

   return [
       // ...
       CommonGateway\BrkBundle\BrkBundle::class => ['all' => true],
   ];
   

3. Configure API Credentials Publish the default config:

   php bin/console brk:install
   

   Update config/packages/brk.yaml with your Kadaster API credentials (e.g., client_id, client_secret).

4. First API Call Use the service in a controller:

   use CommonGateway\BrkBundle\Service\BrkApiService;
   
   class BrkController extends AbstractController {
       public function __construct(private BrkApiService $brkApi) {}
   
       public function searchParcel(string $brkNumber): Response {
           $data = $this->brkApi->getParcelData($brkNumber);
           return $this->json($data);
       }
   }
   

5. Test Locally Use the built-in CLI command to verify connectivity:

   php bin/console brk:test-connection
   

Implementation Patterns

Core Workflows

1. Fetching Parcel Data

Leverage the BrkApiService for structured queries:

// Get basic parcel info
$parcel = $this->brkApi->getParcel($brkNumber);

// Get historical transactions
$transactions = $this->brkApi->getParcelTransactions($brkNumber, new DateTime('2020-01-01'));

2. Batch Processing

Use the BrkBatchService for bulk operations (e.g., syncing multiple parcels):

$batchService = $this->container->get(BrkBatchService::class);
$batchService->processBrkNumbers(['BRK123', 'BRK456'], function ($data) {
    // Handle each parcel response
});

3. Event-Driven Updates

Subscribe to BRK events (e.g., BrkParcelUpdatedEvent) via Symfony’s event dispatcher:

// In a service constructor
public function __construct(private EventDispatcherInterface $dispatcher) {
    $this->dispatcher->addListener(
        BrkParcelUpdatedEvent::class,
        [$this, 'handleParcelUpdate']
    );
}

public function handleParcelUpdate(BrkParcelUpdatedEvent $event) {
    // Log or process updated data
}

4. Caching Strategies

Enable caching for frequent queries via BrkCacheService:

# config/packages/brk.yaml
brk:
    cache_enabled: true
    cache_ttl: 3600  # 1 hour

Integration Tips

• Symfony Forms: Use the BrkType form type for BRK number validation:

  use CommonGateway\BrkBundle\Form\Type\BrkType;
  
  $builder->add('brkNumber', BrkType::class);
  

• API Rate Limiting: Configure retry logic in BrkApiService for throttled requests:

  $this->brkApi->setRetryPolicy(new ExponentialBackoffRetryPolicy());
  

• Doctrine Entities: Map BRK responses to Doctrine entities using BrkHydrator:

  $hydrator = new BrkHydrator();
  $parcelEntity = $hydrator->hydrate($brkResponse, new Parcel());
  

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • The Kadaster API enforces strict rate limits (e.g., 100 requests/minute).
   • Fix: Implement exponential backoff in BrkApiService or use the built-in BrkRateLimiter.

2. Deprecated Endpoints

   • Some Kadaster endpoints may change without notice.
   • Fix: Monitor the brk.log file for 404 or 410 errors and update the bundle’s BrkClient configuration.

3. Sensitive Data Exposure

   • Hardcoding API credentials in brk.yaml risks leaks.
   • Fix: Use Symfony’s parameter_bag or environment variables:

     brk:
         client_id: "%env(BRK_CLIENT_ID)%"
     

4. Time Zone Mismatches

   • Kadaster APIs return timestamps in UTC, but your app may use a local time zone.
   • Fix: Normalize dates in BrkDateConverter:

     $localDate = $this->brkDateConverter->toLocalTime($utcTimestamp);
     

Debugging

• Enable Verbose Logging Set debug: true in brk.yaml to log raw API responses:

  brk:
      debug: true
  

  Logs appear in var/log/brk.log.

• Mock the API for Testing Use the BrkMockClient in tests:

  $this->container->set(BrkClientInterface::class, new BrkMockClient());
  

Extension Points

1. Custom Hydrators Extend BrkHydrator to map BRK responses to your domain models:

   class CustomBrkHydrator extends BrkHydrator {
       protected function hydrateParcel(array $data): Parcel {
           $parcel = parent::hydrateParcel($data);
           $parcel->setCustomField($data['custom_field']);
           return $parcel;
       }
   }
   

2. Event Listeners Add listeners for BrkEvent types (e.g., BrkParcelFetchedEvent) to intercept or modify data:

   $dispatcher->addListener(BrkParcelFetchedEvent::class, function ($event) {
       $event->setData($this->transformData($event->getData()));
   });
   

3. Custom API Clients Replace BrkClient with a custom implementation (e.g., for GraphQL):

   $this->container->set(BrkClientInterface::class, new CustomBrkGraphqlClient());
   

Configuration Quirks

• Caching Invalidation Clear the BRK cache manually when data changes:

  php bin/console cache:clear BRK_CACHE
  

• Environment-Specific Configs Use %kernel.environment% to load different API endpoints per environment:

  brk:
      api_url: "%brk.api_url_%"
  

  Define in .env:

  BRK_API_URL="https://api.kadaster.nl/prod"  # prod
  BRK_API_URL="https://api.kadaster.nl/test" # test