Zgw Vrijbrp Request Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the Bundle Run via Composer:

   composer require common-gateway/zgw-vrijbrp-request-bundle:dev-main
   

   Or via Docker:

   docker-compose exec php composer require common-gateway/zgw-vrijbrp-request-bundle:dev-main
   

2. Install Schemas Execute the console command to register the bundle’s schemas:

   php bin/console commongateway:install common-gateway/zgw-vrijbrp-request-bundle
   

3. Verify Installation

   • Navigate to the Common Gateway Admin UI → Plugins tab.
   • Search for ZgwVrijBRPRequestBundle and ensure it appears in the list.
   • Install the plugin via the UI or manually via:

     php bin/console commongateway:plugin:install zgw-vrijbrp-request-bundle
     

4. First Use Case: Sending a Request Use the bundle’s service to send a request to the VrijBRP API (e.g., fetching address data):

   use CommonGateway\ZgwVrijBRPRequestBundle\Service\VrijBRPRequestService;
   
   class MyController extends AbstractController
   {
       public function __construct(
           private VrijBRPRequestService $vrijBRPRequestService
       ) {}
   
       public function fetchAddress(Request $request): Response
       {
           $response = $this->vrijBRPRequestService->fetchAddress(
               $request->query->get('addressId')
           );
           return $this->json($response);
       }
   }
   

   • Route it in config/routes.yaml:

     my_address_route:
         path: /api/address/{addressId}
         controller: App\Controller\MyController::fetchAddress
     

Implementation Patterns

Core Workflows

1. Plugin-Based Request Handling

   • The bundle abstracts API interactions with VrijBRP (e.g., address, person, or organization data) into reusable services.
   • Pattern: Use dependency injection to inject VrijBRPRequestService into controllers or command handlers.

     $this->vrijBRPRequestService->fetchPerson($personId);
     $this->vrijBRPRequestService->searchAddresses($criteria);
     

2. Schema-Driven Configuration

   • The bundle installs OpenAPI schemas for VrijBRP endpoints. Leverage these in:
     • Symfony API Platform: Extend existing resources or create new ones.
     • Swagger UI: Auto-generate docs by enabling NelmioApiDocBundle.
     • Validation: Use the schemas for request/response validation (e.g., with Symfony’s Validator).

3. Event-Driven Extensions

   • Subscribe to bundle events (e.g., zgw.vrijbrp.request.success) to intercept or modify responses:

     // src/EventListener/VrijBRPResponseListener.php
     public static function getSubscribedEvents(): array
     {
         return [
             KernelEvents::RESPONSE => ['onVrijBRPResponse', 100],
         ];
     }
     
     public function onVrijBRPResponse(ResponseEvent $event): void
     {
         $response = $event->getResponse();
         if ($response->headers->contains('X-VrijBRP-Request')) {
             // Transform or log the response
         }
     }
     

4. Command-Line Automation

   • Use console commands for bulk operations (e.g., syncing data):

     php bin/console zgw:vrijbrp:sync --endpoint=addresses --limit=100
     

   • Extend the bundle’s commands by creating custom commands that inject VrijBRPRequestService.

Integration Tips

1. Caching Responses Cache API responses to reduce calls to VrijBRP:

   use Symfony\Contracts\Cache\CacheInterface;
   
   $cache = $this->container->get('cache.app');
   $cachedResponse = $cache->get("vrijbrp_address_{$addressId}", function() use ($addressId) {
       return $this->vrijBRPRequestService->fetchAddress($addressId);
   });
   

2. Error Handling

   • Wrap service calls in try-catch blocks to handle ZgwVrijBRPException:

     try {
         $data = $this->vrijBRPRequestService->fetchOrganization($orgId);
     } catch (ZgwVrijBRPException $e) {
         $this->addFlash('error', $e->getMessage());
         return $this->redirectToRoute('home');
     }
     

3. Testing

   • Mock VrijBRPRequestService in tests:

     $mockService = $this->createMock(VrijBRPRequestService::class);
     $mockService->method('fetchAddress')
         ->willReturn(['id' => 123, 'street' => 'Test Street']);
     
     $controller = new MyController($mockService);
     

   • Use HttpClient for integration tests to verify API responses.

4. Custom Endpoints

   • Extend the bundle by creating a custom service that extends VrijBRPRequestService:

     class CustomVrijBRPService extends VrijBRPRequestService
     {
         public function fetchCustomData($endpoint, array $params): array
         {
             return $this->request('GET', $endpoint, $params);
         }
     }
     

   • Register the service in services.yaml:

     services:
         App\Service\CustomVrijBRPService:
             arguments:
                 $client: '@http_client'
             tags: ['zgw.vrijbrp.service']
     

Gotchas and Tips

Pitfalls

1. Schema Mismatches

   • If the VrijBRP API schema changes, the bundle’s installed schemas may become outdated.
   • Fix: Re-run commongateway:install or manually update schemas via the Admin UI.

2. Authentication Issues

   • The bundle assumes valid API credentials are configured in config/packages/zgw_vrijbrp.yaml.
   • Debug: Check var/log/dev.log for ZgwVrijBRPException with auth-related messages.
   • Tip: Use environment variables for credentials:

     zgw_vrijbrp:
         client_id: '%env(VIJBRP_CLIENT_ID)%'
         client_secret: '%env(VIJBRP_CLIENT_SECRET)%'
     

3. Rate Limiting

   • VrijBRP may throttle requests. Implement exponential backoff in custom services:

     use Symfony\Component\HttpClient\RetryableHttpException;
     
     try {
         $response = $this->client->request('GET', $url);
     } catch (RetryableHttpException $e) {
         sleep(2 ** $attempt); // Exponential backoff
         retry();
     }
     

4. Plugin Discovery Failures

   • If the plugin doesn’t appear in the Admin UI, ensure:
     • The bundle is installed via Composer (not manually copied).
     • The composer.json includes the correct extra/commongateway metadata:

       "extra": {
           "commongateway": {
               "name": "zgw-vrijbrp-request-bundle",
               "title": "VrijBRP Request Plugin",
               "description": "Extends Common Gateway with VrijBRP API requests."
           }
       }
       

Debugging Tips

1. Enable Verbose Logging Add to config/packages/dev/zgw_vrijbrp.yaml:

   zgw_vrijbrp:
       debug: true
   

   Logs will include request/response payloads in var/log/dev.log.

2. HTTP Client Debugging Configure the HttpClient to log requests:

   # config/packages/http_client.yaml
   framework:
       http_client:
           plugins:
               - Symfony\Bundle\HttpClientBundle\HttpClient\EventListener\ProfilerListener
   

   View requests in the Profiler (/_profiler).

3. Common Exceptions

   • ZgwVrijBRPInvalidResponseException: The API returned an unexpected format.
     • Action: Validate the response structure or update the bundle’s schema parser.
   • ZgwVrijBRPAuthenticationException: Invalid credentials or token.
     • Action: Regenerate credentials in the VrijBRP portal and update zgw_vrijbrp.yaml.

Extension Points

1. Custom Request Handlers Override the default request logic by implementing ZgwVrijBRPRequestHandlerInterface:

   class CustomRequestHandler implements ZgwVrijBRPRequestHandlerInterface
   {
       public function handle(Request $request): Response
       {
           // Custom logic (e.g., add headers, transform payload)
           return $this->client->send($request);