Naamgebruik Vrijbrp Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer Add the bundle to your Laravel project (via Symfony Flex or manually):

   composer require common-gateway/naamgebruik-vrijbrp-bundle
   

   Note: Since this is a Symfony bundle, you’ll need to bridge it with Laravel via Symfony’s Laravel Bridge or use it in a Symfony-based Laravel app (e.g., with Laravel Symfony).

2. Register the Bundle In config/app.php (Symfony) or via a custom Kernel.php (if using Laravel Symfony integration), add:

   new CommonGateway\NaamgebruikVrijBRPBundle\NaamgebruikVrijBRPBundle(),
   

3. Configure the Bundle Publish the default config:

   php artisan vendor:publish --tag="naamgebruik-vrijbrp:config"
   

   Update config/naamgebruik_vrijbrp.php with your VrijBRP API credentials (e.g., client ID, secret, and endpoint).

4. First Use Case: Fetching Name Usage Data Inject the service into a controller or command:

   use CommonGateway\NaamgebruikVrijBRPBundle\Service\NaamgebruikService;
   
   class NameUsageController extends Controller {
       public function __construct(private NaamgebruikService $naamgebruikService) {}
   
       public function checkNameUsage(string $firstName, string $lastName) {
           $response = $this->naamgebruikService->checkNameUsage($firstName, $lastName);
           return response()->json($response);
       }
   }
   

   Call the endpoint with:

   GET /api/naamgebruik?firstName=Jan&lastName=Klaassen
   

Implementation Patterns

Core Workflows

1. API Integration

   • The bundle abstracts VrijBRP’s Naamgebruik API (name usage checks). Use the NaamgebruikService to:
     • Validate if a name combination exists in the Dutch BRP (Basic Registration Personal Data).
     • Fetch metadata (e.g., gender distribution, popularity).
   • Example workflow:

     // Check if "Maria Jansen" exists in BRP
     $exists = $this->naamgebruikService->isNameUsed('Maria', 'Jansen');
     
     // Get statistics for "Anna"
     $stats = $this->naamgebruikService->getNameStatistics('Anna');
     

2. Event-Driven Extensions

   • Extend the bundle’s events (e.g., NaamgebruikEvent) to trigger actions post-check:

     // In a service provider
     $dispatcher->addListener(NaamgebruikEvent::NAME_CHECKED, function (NaamgebruikEvent $event) {
         if ($event->isUsed()) {
             Log::warning("Name {$event->getFirstName()} {$event->getLastName()} is already in use.");
         }
     });
     

3. Caching Responses

   • Cache API responses to reduce calls to VrijBRP. Use Laravel’s cache or Symfony’s cache component:

     $cacheKey = "naamgebruik_{$firstName}_{$lastName}";
     return Cache::remember($cacheKey, now()->addHours(1), function () use ($firstName, $lastName) {
         return $this->naamgebruikService->checkNameUsage($firstName, $lastName);
     });
     

4. Form Validation

   • Integrate with Laravel’s validation:

     use CommonGateway\NaamgebruikVrijBRPBundle\Rules\NameUsage;
     
     $request->validate([
         'first_name' => ['required', new NameUsage],
         'last_name'  => ['required', new NameUsage],
     ]);
     

Integration Tips

• Symfony-Laravel Bridge: If using Laravel, wrap the bundle’s services in Laravel’s container:

  // In AppServiceProvider::boot()
  $this->app->bind(NaamgebruikService::class, function ($app) {
      return new NaamgebruikService(
          $app->make('config')->get('naamgebruik_vrijbrp.api_client')
      );
  });
  

• Testing: Mock the NaamgebruikService in tests:

  $mock = Mockery::mock(NaamgebruikService::class);
  $mock->shouldReceive('isNameUsed')->andReturn(false);
  $this->app->instance(NaamgebruikService::class, $mock);
  

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • VrijBRP may throttle requests. Implement exponential backoff:

     try {
         $response = $this->naamgebruikService->checkNameUsage($name);
     } catch (RateLimitExceededException $e) {
         sleep($e->getRetryAfter());
         retry();
     }
     

2. Case Sensitivity

   • Dutch names in BRP are case-insensitive. Normalize inputs:

     $normalizedName = mb_strtolower($name, 'UTF-8');
     

3. Bundle Dependencies

   • Requires CommonGateway/CoreBundle. Ensure it’s installed:

     composer require common-gateway/core-bundle
     

4. Configuration Overrides

   • Avoid hardcoding API endpoints. Use the config file:

     // Wrong: Hardcoded URL
     $client->setBaseUri('https://api.vrijbrp.nl');
     
     // Right: Config-driven
     $client->setBaseUri(config('naamgebruik_vrijbrp.api_endpoint'));
     

Debugging

• Enable API Logging Add to config/naamgebruik_vrijbrp.php:

  'debug' => env('NAAMGEBRUIK_DEBUG', false),
  

  Logs will appear in storage/logs/laravel.log.

• Common Errors

  Error	Solution
  ClientException: Invalid credentials	Verify client_id and client_secret in config.
  ConnectionException	Check api_endpoint and network connectivity.
  InvalidArgumentException	Ensure firstName and lastName are non-empty strings.

Extension Points

1. Custom Name Rules Extend the NameUsage rule to add business logic:

   class CustomNameUsage extends NameUsage {
       public function passes($attribute, $value) {
           $isUsed = parent::passes($attribute, $value);
           return $isUsed && $this->isPreferredName($value);
       }
   }
   

2. Alternative Data Sources Override the service to support multiple BRP-like APIs:

   class MultiBRPApiService extends NaamgebruikService {
       public function checkNameUsage(string $firstName, string $lastName, string $source = 'vrijbrp') {
           if ($source === 'custom') {
               return $this->customApi->check($firstName, $lastName);
           }
           return parent::checkNameUsage($firstName, $lastName);
       }
   }
   

3. Webhook Listeners Subscribe to NaamgebruikEvent::NAME_ADDED to sync with external systems:

   $dispatcher->addListener(NaamgebruikEvent::NAME_ADDED, function (NaamgebruikEvent $event) {
       Http::post('https://external-system.com/webhook', [
           'name' => "{$event->getFirstName()} {$event->getLastName()}"
       ]);
   });