Kvk Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require common-gateway/kvk-bundle
   

   Register the bundle in config/app.php under providers:

   CommonGateway\KVKBundle\KVKBundle::class,
   

2. Publish Configuration Publish the default config (if available) to customize endpoints or API keys:

   php artisan vendor:publish --provider="CommonGateway\KVKBundle\KVKBundle" --tag="config"
   

   (Note: Verify if the package includes a config/kvk.php file in its source.)

3. First Use Case: Fetch a Company Inject the KVKClient service into a controller or service:

   use CommonGateway\KVKBundle\Client\KVKClient;
   
   public function showCompany(KVKClient $kvkClient, string $companyNumber) {
       $company = $kvkClient->getCompany($companyNumber);
       return response()->json($company);
   }
   

   (Assumes the bundle provides a getCompany() method; adjust based on actual API.)

4. Check the README for Mock Behavior Since this is a mock bundle, verify if it simulates real KVK (Dutch Chamber of Commerce) API responses. Test locally before relying on it in production.

Implementation Patterns

Workflows

1. API Integration Layer Use the bundle as a thin wrapper for KVK API calls, abstracting HTTP logic:

   // Example: Service layer for company validation
   public function validateCompany(KVKClient $kvkClient, string $number) {
       try {
           $response = $kvkClient->validate($number);
           return $response->isValid();
       } catch (KVKException $e) {
           Log::error("KVK Validation Failed: " . $e->getMessage());
           return false;
       }
   }
   

2. Event-Driven Updates Leverage Laravel events to trigger KVK checks after model creation/updates:

   // In a model observer or event listener
   public function saved(Company $company) {
       event(new CompanyRegistered($company));
   }
   
   // Listener
   public function handle(CompanyRegistered $event) {
       $kvkClient->getCompany($event->company->number);
   }
   

3. Caching Responses Cache KVK responses to reduce API calls (e.g., using Laravel Cache):

   public function getCompany(KVKClient $kvkClient, string $number) {
       return Cache::remember("kvk_{$number}", now()->addHours(1), function() use ($kvkClient, $number) {
           return $kvkClient->getCompany($number);
       });
   }
   

4. Form Request Validation Validate KVK numbers in Laravel form requests:

   public function rules() {
       return [
           'kvk_number' => [
               'required',
               'string',
               Rule::exists('kvk_companies', 'number')->where(function ($query) {
                   $query->where('active', true);
               }),
           ],
       ];
   }
   

Integration Tips

• Mock vs. Real API: If the bundle is purely a mock, replace it with a real client (e.g., guzzlehttp/guzzle) in production.
• Error Handling: Wrap KVK calls in try-catch blocks to handle API failures gracefully.
• Testing: Use the mock bundle in unit tests to avoid hitting the real KVK API:

  $this->app->bind(KVKClient::class, function ($app) {
      return new MockKVKClient(); // Hypothetical mock class
  });
  

Gotchas and Tips

Pitfalls

1. Mock Limitations

   • The bundle’s TODO in the README suggests incomplete search functionality. Avoid relying on it for critical workflows until fixed.
   • Mock responses may not match the real KVK API schema. Validate against actual API docs.

2. Configuration Assumptions

   • The package may assume default KVK endpoints (e.g., https://api.kvk.nl). Override these in config/kvk.php if needed:

     'endpoints' => [
         'base' => env('KVK_API_BASE_URL', 'https://mock.kvk.nl'),
     ],
     

3. Rate Limiting

   • If the mock doesn’t enforce rate limits, the real KVK API might throttle requests. Implement retries with exponential backoff:

     use Symfony\Component\HttpClient\RetryableHttpClient;
     
     $client = new RetryableHttpClient($baseClient, [
         'max_retries' => 3,
         'delay' => 100,
         'multiplier' => 2,
     ]);
     

4. Data Duplication Note The README mentions search functionality runs on "data duplication add action." If this is critical, implement a separate cron job or queue job to trigger searches periodically:

   php artisan schedule:run
   

   (Add to app/Console/Kernel.php.)

Debugging

• Enable Debugging: Check if the bundle supports debug mode via config:

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

• Log Raw Responses: Log KVK responses to compare with mock data:

  Log::debug('KVK Response', ['data' => $kvkClient->getCompany($number)]);
  

• Check for Exceptions: The bundle may throw custom exceptions (e.g., KVKException). Catch these to provide user-friendly errors.

Extension Points

1. Custom Responses Extend the mock behavior by overriding the bundle’s service provider:

   public function register() {
       $this->app->singleton(KVKClient::class, function ($app) {
           $client = new CustomKVKClient($app['http.client']);
           $client->setMockData([/* custom mock data */]);
           return $client;
       });
   }
   

2. Add New Endpoints If the bundle lacks an endpoint, create a decorator:

   class ExtendedKVKClient extends KVKClient {
       public function getCompanyHistory(string $number) {
           return $this->request('GET', "/companies/{$number}/history");
       }
   }
   

   Bind it in AppServiceProvider.

3. Testing Utilities Add helper methods to generate test data:

   // In a TestCase trait
   protected function mockKVKResponse(array $data) {
       $this->app->instance(KVKClient::class, Mockery::mock(KVKClient::class)->shouldReceive('getCompany')->andReturn($data)->getMock());
   }