Add Postcodes.io support

.gitignore

@@ -1,3 +1,4 @@
 composer.lock
 vendor
-.idea
+.idea
+*.cache

README.md

@@ -29,6 +29,7 @@ It currently supports the following postcode lookup services.
 
 * Ideal Postcodes - https://ideal-postcodes.co.uk
 * Postcode Anywhere (PCA Predict) - https://www.pcapredict.com/
+* Postcodes.io - http://postcodes.io/
 
 Sign up at the respective website if you need to use these features.
 
@@ -38,6 +39,8 @@ You can then use the following code to get an appropriate postcode lookup servic
 $postcodeLookupService = new \DivineOmega\Postcodes\Objects\IdealPostcodes('API_KEY');
 // OR
 $postcodeLookupService = new \DivineOmega\Postcodes\Objects\PostcodeAnywhere('API_KEY');
+// OR
+$postcodeLookupService = new \DivineOmega\Postcodes\Objects\PostcodesIo();
 ```
 
 ## Usage

src/Objects/PostcodesIo.php

@@ -0,0 +1,74 @@
+<?php
+
+
+namespace DivineOmega\Postcodes\Objects;
+
+
+use DivineOmega\Postcodes\Interfaces\PostcodeServiceInterface;
+use Exception;
+use GuzzleHttp\Client;
+use GuzzleHttp\Psr7\Response;
+use InvalidArgumentException;
+
+class PostcodesIo implements PostcodeServiceInterface
+{
+    private $client;
+
+    public function __construct($apiKey = null)
+    {
+        if ($apiKey) {
+            throw new InvalidArgumentException('Postcodes.io does not require an API key.');
+        }
+
+        $this->client = new Client(['base_uri' => 'https://api.postcodes.io/', 'timeout'  => 3.0]);
+    }
+
+    public function getAddressesByPostcode($postcode)
+    {
+        $response = $this->client->request('GET', 'postcodes/'.$postcode);
+
+        $result = $this->parseResponse($response);
+
+        return $result;
+    }
+
+    private function parseResponse(Response $response)
+    {
+        if ($response->getStatusCode() != 200) {
+            throw new Exception('HTTP response code was not 200. Received HTTP reponse code: '.$response->getStatusCode().' ('.$response->getReasonPhrase().')');
+        }
+
+        $object = json_decode($response->getBody());
+
+        if (!$object) {
+            throw new Exception('Response JSON could not be decoded.');
+        }
+
+        if (!isset($object->status) || !is_numeric($object->status)) {
+            throw new Exception('Response status not found or invalid.');
+        }
+
+        if ($object->status != 200) {
+            throw new Exception('Response status was not 200. Response status: '.$object->status);
+        }
+
+        if (!isset($object->result)) {
+            throw new Exception('Response does not contain a result.');
+        }
+
+        $postcodesIoAddress = $object->result;
+
+        $addresses = [];
+
+        $address = new Address();
+        $address->townCity = $postcodesIoAddress->admin_district;
+        $address->county = $postcodesIoAddress->admin_county;
+        $address->postcode = $postcodesIoAddress->postcode;
+        $address->longitude = $postcodesIoAddress->longitude;
+        $address->latitude = $postcodesIoAddress->latitude;
+
+        $addresses[] = $address;
+
+        return $addresses;
+    }
+}

tests/Unit/PostcodesIoTest.php

@@ -0,0 +1,53 @@
+<?php
+
+use DivineOmega\Postcodes\Exceptions\InvalidPostcodeException;
+use DivineOmega\Postcodes\Objects\PostcodesIo;
+use DivineOmega\Postcodes\Utils\Generator;
+use DivineOmega\Postcodes\Utils\Tokenizer;
+use DivineOmega\Postcodes\Utils\Validator;
+use PHPUnit\Framework\TestCase;
+
+final class PostcodesIoTest extends TestCase
+{
+    public function validationProvider()
+    {
+        return [
+            [
+                'postcode' => 'ST163DP',
+                'expectedResponse' => [
+                    'townCity' => 'Stafford',
+                    'county' => 'Staffordshire',
+                    'postcode' => 'ST16 3DP',
+                    'longitude' => -2.11556,
+                    'latitude' => 52.822944,
+                ],
+            ],
+            [
+                'postcode' => 'TN30YA',
+                'expectedResponse' => [
+                    'townCity' => 'Tunbridge Wells',
+                    'county' => 'Kent',
+                    'postcode' => 'TN3 0YA',
+                    'longitude' => 0.226856,
+                    'latitude' => 51.13246,
+                ],
+            ],
+        ];
+    }
+
+    /**
+     * @dataProvider validationProvider
+     */
+    public function testLookup($postcode, $expectedResponse)
+    {
+        $postcodeLookupService = new PostcodesIo();
+        $addresses = $postcodeLookupService->getAddressesByPostcode($postcode);
+
+        $address = $addresses[0];
+
+        foreach($expectedResponse as $key => $value) {
+            $this->assertEquals($value, $address->$key);
+        }
+    }
+
+}