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

tfarla / php-postcodeapinu

Maintainers

Details