Referentielijsten Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add the bundle via Composer in a Symfony 5.4+ project:

   composer require common-gateway/referentielijsten-bundle
   

   Enable it in config/bundles.php:

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

2. Configure the Client Define the API client in config/packages/referentielijsten.yaml:

   referentielijsten:
       client:
           endpoint: '%env(REFERENTIELIJSTEN_API_URL)%' # e.g., 'https://referentielijsten.zgw.io'
           api_key: '%env(REFERENTIELIJSTEN_API_KEY)%'
           timeout: 30
   

   Fetch environment variables from .env:

   REFERENTIELIJSTEN_API_URL=https://referentielijsten.zgw.io
   REFERENTIELIJSTEN_API_KEY=your_api_key_here
   

3. First Use Case: Fetch a Selectielijst Inject the ReferentielijstenClient service and call a list (e.g., Gemeente):

   use CommonGateway\ReferentielijstenBundle\Client\ReferentielijstenClient;
   
   class SomeController
   {
       public function __construct(private ReferentielijstenClient $client) {}
   
       public function getMunicipalities()
       {
           $gemeentes = $this->client->getSelectielijst('Gemeente');
           return $this->json($gemeentes->getItems());
       }
   }
   

Implementation Patterns

Core Workflows

1. Fetching Selectielijsten Use the client to retrieve standardized lists (e.g., Gemeente, Provincie, Postcode):

   $gemeentes = $this->client->getSelectielijst('Gemeente');
   $gemeentes->getItems(); // Array of items
   $gemeentes->getTotal(); // Total count
   

2. Filtering and Pagination Apply filters (e.g., ?filter=gemeentenaam:Amsterdam) and pagination:

   $filtered = $this->client->getSelectielijst('Gemeente', [
       'filter' => 'gemeentenaam:Amsterdam',
       'page' => 1,
       'limit' => 10,
   ]);
   

3. Caching Responses Cache responses for performance (e.g., in a controller or service):

   $cache = $this->client->getSelectielijst('Gemeente', [], 3600); // Cache for 1 hour
   

4. Integration with Forms Use the lists to populate Symfony forms dynamically:

   $builder->add('gemeente', EntityType::class, [
       'class' => Gemeente::class,
       'choices' => $this->client->getSelectielijst('Gemeente')->getItems(),
   ]);
   

5. Validation Validate user input against referentielijsten (e.g., check if a BSN exists):

   $bsnValid = $this->client->validateBsn($userInput['bsn']);
   if (!$bsnValid) {
       $this->addFlash('error', 'Ongeldig BSN');
   }
   

Advanced Patterns

1. Custom API Clients Extend the client for custom endpoints or logic:

   class CustomReferentielijstenClient extends ReferentielijstenClient
   {
       public function getCustomList(string $type, array $options = [])
       {
           return $this->get($this->buildUrl($type, $options));
       }
   }
   

2. Event Listeners Subscribe to bundle events (e.g., ReferentielijstenEvent::PRE_REQUEST):

   // config/services.yaml
   services:
       App\EventListener\ReferentielijstenListener:
           tags:
               - { name: kernel.event_listener, event: referentielijsten.pre_request, method: onPreRequest }
   

3. Doctrine Integration Sync referentielijsten data with Doctrine entities:

   $gemeentes = $this->client->getSelectielijst('Gemeente');
   foreach ($gemeentes->getItems() as $item) {
       $entityManager->persist(new GemeenteEntity($item));
   }
   $entityManager->flush();
   

Gotchas and Tips

Common Pitfalls

1. API Rate Limits

   • The API enforces rate limits (e.g., 60 requests/minute). Cache responses aggressively.
   • Monitor usage with $this->client->getRateLimitStatus().

2. Deprecated Endpoints

   • Some endpoints (e.g., /v1/) may be deprecated. Use /v2/ where possible.
   • Check the official API docs for updates.

3. Case Sensitivity

   • Selectielijst types (e.g., Gemeente) are case-sensitive. Use the exact name from the API.

4. Pagination Quirks

   • The limit parameter defaults to 100. Exceeding this may return partial results.
   • Always check $response->getTotal() vs. $response->getItems() count.

5. Caching Headers

   • The API may include Cache-Control headers. Respect these in your caching layer.

Debugging Tips

1. Enable API Logging Configure the client to log requests/responses:

   referentielijsten:
       client:
           debug: true
   

   Logs appear in var/log/dev.log.

2. Validate API Keys

   • Test your API key with:

     $this->client->getRateLimitStatus();
     

   • A 401 Unauthorized indicates an invalid key.

3. Handle Exceptions Catch ReferentielijstenException for API errors:

   try {
       $this->client->getSelectielijst('Gemeente');
   } catch (ReferentielijstenException $e) {
       $this->addFlash('error', 'API fout: ' . $e->getMessage());
   }
   

4. Network Issues

   • Use curl to test connectivity:

     curl -H "X-API-Key: $REFERENTIELIJSTEN_API_KEY" https://referentielijsten.zgw.io/v2/selectielijsten/Gemeente
     

   • Check for firewall/proxy restrictions.

Extension Points

1. Custom Response Transformers Override how responses are parsed:

   $this->client->setResponseTransformer(function (Response $response) {
       return json_decode($response->getContent(), true);
   });
   

2. Middleware Add middleware to the client (e.g., for retries):

   $client = $this->client->getHttpClient();
   $client->setDefaultOption('handler', HandlerStack::create([
       new RetryMiddleware(),
       // ...
   ]));
   

3. Event Dispatching Dispatch custom events for selectielijsten updates:

   $this->eventDispatcher->dispatch(
       new ReferentielijstenUpdatedEvent('Gemeente', $items),
       ReferentielijstenUpdatedEvent::NAME
   );
   

4. Testing Mock the client in tests:

   $mockClient = $this->createMock(ReferentielijstenClient::class);
   $mockClient->method('getSelectielijst')->willReturn(new SelectielijstResponse([...]));
   $this->container->set(ReferentielijstenClient::class, $mockClient);