tfarla / php-postcodeapinu
PHP client for https://www.postcodeapi.nu
This package's canonical repository appears to be gone and the package has been frozen as a result.
Requires
- php: ^7
- guzzlehttp/psr7: ^1.4
- php-http/message: ^1.6
Requires (Dev)
- dephpend/dephpend: ^0.5.0
- doctrine/instantiator: ^1.0.2
- johnkary/phpunit-speedtrap: ^2.0
- php-coveralls/php-coveralls: ^2.0
- php-http/mock-client: ^1.1
- phpmd/phpmd: ^2.6
- phpstan/phpstan: ^0.9.2
- phpunit/phpunit: ^6
This package is auto-updated.
Last update: 2020-10-16 13:14:53 UTC
README
This package provides a client for the https://www.postcodeapi.nu/ service to consume in your PHP application. Enjoying this library? Please consider supporting me by buying me a cup of coffee @
Getting started
To install the library you will need composer and you should use php version >= 7.0
composer require tfarla/php-postcodeapinu
This library uses an HTTP abstraction layer called httpplug which allows you to use your favorite HTTP client with this library. Don't want to use guzzle? That's okay. Have a look at the other available adapters. This library won't force you to. Httpplug does require some configuration in order to work so please read the instructions on http://docs.php-http.org/en/latest/httplug/users.html.
Execute the following command to install the php-http/curl-client
composer require php-http/curl-client
<?php use TFarla\PostcodeApiNu\Client; $curl = new Http\Client\Curl\Client(); $token = 'superSecretToken'; $client = new Client($curl, $token);
But I recommend using the guzzle adapter since it offers more fine grained control. Execute the following command to install the php-http/guzzle6-adapter adapter
composer require php-http/guzzle6-adapter
<?php use TFarla\PostcodeApiNu\Client; use Http\Adapter\Guzzle6\Client as GuzzleAdapter; $config = ['timeout' => 2]; $adapter = GuzzleAdapter::createWithConfig($config); $token = 'superSecretToken'; $client = new Client($adapter, $token);
Usage
Now that you've installed the http adapter and the php-postcodeapinu library. You are ready to consume their API through the client.
Get an address
<?php use TFarla\PostcodeApiNu\Client; $client = new Client($adapter, $token); $addresses = $client->getAddress('0268200000075156'); $address = null; if ($addresses->isEmpty() === false) { $address = $addresses[0]; }
Get addresses
<?php use TFarla\PostcodeApiNu\Client; use TFarla\PostcodeApiNu\Address; $client = new Client($adapter, $token); $addresses = $client->getAddresses(); /** @var Address $address */ foreach ($addresses as $address) { // Do something with the address $address->getPostcode(); }
Search for an address
<?php use TFarla\PostcodeApiNu\Client; use TFarla\PostcodeApiNu\Address; $client = new Client($adapter, $token); $postcode = '1234AJ'; $houseNumber = '138E10'; $addresses = $client->getAddresses($postcode, $houseNumber); /** @var Address $address */ foreach ($addresses as $address) { // Do something with the address $address->getPostcode(); }
Get a single postcode
<?php use TFarla\PostcodeApiNu\Client; $client = new Client($adapter, $token); $postcodes = $client->getPostcode('1234AJ'); if ($postcodes->isEmpty() === false) { $postcode = $postcodes[0]; }
Get all postcodes
<?php use TFarla\PostcodeApiNu\Client; use TFarla\PostcodeApiNu\Postcode; $client = new Client($adapter, $token); $area = null; $from = null; // the area and from parameters are optional and only present for demonstration in this example $postcodes = $client->getPostcodes($area, $from); /** @var Postcode $postcode */ foreach ($postcodes as $postcode) { $postcode->getCity(); }
The address and postcode class
Both the address and postcode class are immutable data structures.
Exception handling
This packages uses a exceptions to communicate that something has gone wrong. The exception hierarchy is described bellow:
\TFarla\PostcodeApiNu\
├── Exception.php
├──── BadRequestException.php
├──── NotFoundException.php
├──── RateLimitReachedException.php
└──── UnauthorisedException.php
The exceptions all have the getResponse
method which allows the developer to retrieve the original response.
Other then that they are normal exceptions.
Rate limit
The API uses rate limiting and communicates our remaining requests along with the limit. Since we need to consider the rate limit. It's present on every response from the client.
<?php use TFarla\PostcodeApiNu\Client; $client = new Client($adapter, $token); $postcodes = $client->getPostcode('1234AJ'); if ($postcodes->isEmpty() === false) { $postcode = $postcodes[0]; } $rateLimit = $postcodes->getRateLimit(); $rateLimit->getRemaining(); $rateLimit->getLimit();
Class diagram
Address methods
+ getPostcode(): string
+ getPurpose(): string
+ getSurface(): string
+ getMunicipality(): LabeledValue
+ getCity(): LabeledValue
+ getProvince(): LabeledValue
+ getLetter(): string
+ getCenterPoint(): Point
+ getExteriorPoints(): Point[]
+ getHouseNumber(): int
+ getHouseNumberAddition(): string
+ getYear(): int
+ getType(): string
+ getStreet(): string
Postcode methods
+ getPostcode(): string
+ getCity(): LabeledValue
+ getMuniciple(): LabeledValue
+ getProvince(): LabeledValue
+ getPoint(): Point
+ getStreets(): string[]
Development
Thanks for reading this far into the readme and considering development of this library! In order to guarantee a certain amount of professionalism and stability this library has been developed using the test driven development paradigm. Even though the tests have been carefully crafted. It would be naive to think that the amount of lines covered in them is a good metric for quality and stability. We don't want to make you worry about bugs in this library. Therefor we also use a tool called phpstan for static analysis in hopes to prevent bugs related to typing. To also make this package maintainable we use a mess detector called phpmd.
Running tests
composer run tests
Running static analysis
composer run phpstan
Running mess detector
composer run phpmd
Security vulnerability
If you discover any security vulnerability please report them as an issue on this repository