Api Postcode Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require api-postcode/api-postcode-bundle
   

   Ensure your composer.json meets the PHP version and Symfony requirements (≥7.1, Symfony 2.7–6.0).

2. Enable the Bundle: Add to config/bundles.php (Symfony 4+):

   return [
       // ...
       ApiPostcode\PostcodeBundle\ApiPostcodeBundle::class => ['all' => true],
   ];
   

3. Configure API Token: Add to .env (recommended) or config/packages/api_postcode.yaml:

   api_postcode:
       token: '%env(API_POSTCODE_TOKEN)%'
   

4. First Use Case: Fetch an address in a controller or service:

   use ApiPostcode\PostcodeBundle\Service\PostcodeService;
   
   public function fetchAddress(PostcodeService $postcodeService)
   {
       $address = $postcodeService->fetchAddress('1012JS', 1);
       return response()->json($address);
   }
   

Implementation Patterns

Core Workflows

1. Service Integration: Inject PostcodeService into controllers/services:

   public function __construct(private PostcodeService $postcodeService) {}
   

2. API Endpoint: Use Symfony’s routing for direct API access:

   # config/routes.yaml
   api_postcode:
       path: /api/postcode
       controller: ApiPostcode\PostcodeBundle\Controller\PostcodeController::getAddress
       methods: GET
   

   Call with query params: /api/postcode?postcode=1012JS&nummer=1.

3. Batch Processing: Loop through postcodes (e.g., CSV import):

   $postcodes = ['1012JS', '1013AA'];
   foreach ($postcodes as $postcode) {
       $address = $postcodeService->fetchAddress($postcode, 1);
       // Process $address
   }
   

4. Caching Responses: Cache results to reduce API calls (e.g., with Symfony Cache):

   $cache = $this->container->get('api.postcode.cache');
   $address = $cache->get($postcode, function() use ($postcode) {
       return $this->postcodeService->fetchAddress($postcode, 1);
   });
   

Integration Tips

• Validation: Validate postcode format (e.g., Dutch ####?? regex) before API calls.
• Error Handling: Wrap calls in try-catch for API rate limits or invalid responses:

  try {
      $address = $postcodeService->fetchAddress($postcode, $number);
  } catch (\ApiPostcode\Exception\ApiException $e) {
      // Log or retry
  }
  

• Environment Awareness: Use different tokens for dev/staging/prod in .env.

Gotchas and Tips

Pitfalls

1. Token Management:

   • Hardcoding tokens in config.yml violates security best practices. Always use .env.
   • Token leaks can block your API access. Rotate tokens if compromised.

2. Rate Limits:

   • The free API has strict limits. Cache aggressively or implement exponential backoff for retries.

3. Deprecated Symfony Support:

   • The bundle supports Symfony 2.7–6.0 but may lack updates for newer versions. Test thoroughly if using Symfony 6+.

4. House Number Handling:

   • The fetchAddress() method expects house number as an integer (e.g., 1 not '1'). Non-integer inputs may fail silently.

5. No Bulk Endpoint:

   • The API lacks a bulk endpoint. For large datasets, implement parallel requests with Guzzle or queue workers.

Debugging

• Enable Debug Mode: Set API_POSTCODE_DEBUG=true in .env to log raw API responses.
• Check HTTP Status Codes: The bundle may not expose HTTP errors (e.g., 429 for rate limits). Inspect the underlying GuzzleHttp client:

  $client = $this->postcodeService->getClient();
  $response = $client->send($request);
  

Extension Points

1. Custom Address Model: Extend the Address class to add fields (e.g., getFullAddress()):

   class CustomAddress extends \ApiPostcode\PostcodeBundle\Entity\Address {
       public function getFullAddress() {
           return "{$this->getStreet()} {$this->getHouseNumber()}, {$this->getZipCode()} {$this->getCity()}";
       }
   }
   

   Override the service to return your model.

2. Add Geocoding: Use the latitude/longitude to reverse-geocode via Google Maps or OpenStreetMap:

   $address = $postcodeService->fetchAddress('1012JS', 1);
   $geocoded = $this->geocodingService->reverse($address->getLatitude(), $address->getLongitude());
   

3. Mock for Testing: Replace the service with a mock in tests:

   $this->mockPostcodeService->shouldReceive('fetchAddress')
       ->once()
       ->andReturn(new Address('Dam', 'Amsterdam', 1, '1012JS', 4.4584, 52.2296));
   

4. Webhook Integration: Use the API’s webhook feature (if available) to push updates instead of polling.

Config Quirks

• Token Validation: The bundle doesn’t validate the token on startup. Test the first API call to confirm connectivity.
• Case Sensitivity: Postcode inputs are case-insensitive (1012JS = 1012js), but ensure consistency in your code.