devmobgroup / postcodes
Abstraction layer for fetching Dutch postcode data.
Requires
- php: >=7.1
- ext-json: *
- adbario/php-dot-notation: ^2.1
- guzzlehttp/guzzle: ~6.0
- psr/http-message: ^1.0
Requires (Dev)
- phpunit/phpunit: ^7.3
Suggests
- devmobgroup/postcodes-api-postcode: Provider for Api-postcode.nl
- devmobgroup/postcodes-postcode-api-nu: Provider for PostcodeAPI.nu
This package is auto-updated.
Last update: 2022-01-09 23:01:35 UTC
README
This package provides some basic functionality that can be implemented for specific postcode APIs. This package alone does not provide immediate access to postcode data.
Install
-
Install the base package:
composer require devmobgroup/postcodes
-
Choose a postcode provider or create your own. You can find all of our own provider implementations in this repository.
-
PostcodeAPI.nu (recommended) postcodeapi.nu
composer require devmobgroup/postcodes-postcode-api-nu
-
API Postcode api-postcode.nl
composer require devmobgroup/postcodes-api-postcode
Read more about using and configuring these providers.
-
Usage
All providers implement the ProviderInterface
which has a lookup method:
$provider->lookup(string $postcode, string $number);
This method returns an array of Address
instances. This array should never be empty, because instead the NoSuchCombinationException
exception indicates no
results were found.
$address = $addresses[0]; $address->getPostcode(); // '3011 ED' $address->getHouseNumber(); // '50' $address->getStreet(); // 'Schiedamsedijk' $address->getCity(); // 'Rotterdam' $address->getProvince(); // 'Zuid-Holland' $address->getLatitude(); // '51.9147442' $address->getLongitude(); // '4.4766394'
There's also a getRaw()
method which usually contains an array of the raw data retrieved from the provider:
$address->getRaw(); // ['city' => 'Rotterdam', 'year' => 1990, ...]
Additionally, the lookup()
method throws exceptions that should be caught.
use DevMob\Postcodes\Exceptions\NoSuchCombinationException; use DevMob\Postcodes\Exceptions\PostcodesException; try { $provider->lookup('3011ED', '50'); } catch (NoSuchCombinationException $e) { // Combination of postcode and house number not found } catch (PostcodesException $e) { // Catch-all interface for other exceptions. // It's best to always catch these exceptions, because // providers may implement their own exceptions that // are not documented in the ProviderInterface. }
Extending
Read more about creating your own provider.
License
The MIT License (MIT). Please see License File for more information.