Added /postcodes call

Author: Evert Harmeling

.travis.yml

@@ -1,7 +1,6 @@
 language: php
 
 php:
-    - 5.4
     - 5.5
     - 5.6
     - 7.0

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 2.1.0
+
+* Added `getPostcodes()` call, to get postcodes based on provided `latitude, longitude`. Note that this call is only available with a premium account.
+
 ## 2.0.0
 
 * Rewrite to support postcodeapi.nu version 2

README.md

@@ -41,6 +41,9 @@ $client = new \FH\PostcodeAPI\Client(new \GuzzleHttp\Client(), $apiKey);
 // call endpoints
 $response = $client->getAddresses('5041EB', 21);
 $response = $client->getAddress('0855200000061001');
+
+// Note that this call is only available with a premium account
+$response = $client->getPostcodes('51.566405', '5.077171');
 ```
 
 [![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/freshheads/fhpostcodeapiclient/trend.png)](https://bitdeli.com/free "Bitdeli Badge")

composer.json

@@ -19,6 +19,9 @@
         "php": ">=5.4.0",
         "guzzlehttp/guzzle": "^6.0"
     },
+    "require-dev": {
+        "phpunit/phpunit": "^4.3.5"
+    },
     "autoload": {
         "psr-0": { "FH\\PostcodeAPI": "lib/" }
     },

lib/FH/PostcodeAPI/Client.php

@@ -16,15 +16,35 @@
  */
 class Client
 {
-    const BASE_URI = 'https://postcode-api.apiwise.nl';
+    const POSTCODES_SORT_DISTANCE = 'distance';
+
+    /**
+     * @var string
+     */
+    private $uriScheme  = 'https://';
+
+    /**
+     * @var null|string
+     */
+    private $domain     = 'postcode-api.apiwise.nl';
+
+    /**
+     * @var string
+     */
+    private $version    = 'v2';
 
     /**
      * @var HTTPClient
      */
     private $httpClient;
 
-    public function __construct(ClientInterface $httpClient)
+
+    public function __construct(ClientInterface $httpClient, $domain = null)
     {
+        if (null !== $domain) {
+            $this->domain = $domain;
+        }
+
         $this->httpClient = $httpClient;
     }
 
@@ -33,11 +53,11 @@ public function __construct(ClientInterface $httpClient)
      * @param string|null $number
      * @param int $from
      *
-     * @return \StdClass
+     * @return \stdClass
      */
     public function getAddresses($postcode = null, $number = null, $from = 0)
     {
-        return $this->get('/v2/addresses/', [
+        return $this->get('/addresses/', [
             'postcode' => $postcode,
             'number' => $number,
             'from' => $from
@@ -47,26 +67,44 @@ public function getAddresses($postcode = null, $number = null, $from = 0)
     /**
      * @param string $id
      *
-     * @return \StdClass
+     * @return \stdClass
      */
     public function getAddress($id)
     {
-        return $this->get("/v2/addresses/{$id}");
+        return $this->get(sprintf('/addresses/%s', $id));
+    }
+
+    /**
+     * @param string $latitude
+     * @param string $longitude
+     * @param string $sort
+     *
+     * @return \stdClass
+     */
+    public function getPostcodesByCoordinates($latitude, $longitude, $sort = self::POSTCODES_SORT_DISTANCE)
+    {
+        return $this->get('/postcodes/', [
+            'coords' => [
+                'latitude' => $latitude,
+                'longitude' => $longitude
+            ],
+            'sort' => $sort
+        ]);
     }
 
     /**
      * @param string $path
      * @param array $queryParams
      *
-     * @return \StdClass
+     * @return \stdClass
      *
      * @throws RequestException
      */
     private function get($path, array $queryParams = array())
     {
-        $url = self::BASE_URI . $path;
-
-        $request = $this->createHttpRequest('GET', $url, $queryParams);
+        $request = $this->createHttpRequest('GET', sprintf('%s%s/%s%s', $this->uriScheme, $this->domain, $this->version, $path),
+            $queryParams
+        );
 
         $response = $this->httpClient->send($request);
 
@@ -76,7 +114,7 @@ private function get($path, array $queryParams = array())
     /**
      * @param ResponseInterface $response
      *
-     * @return \StdClass
+     * @return \stdClass
      *
      * @throws CouldNotParseResponseException
      */
@@ -85,7 +123,7 @@ private function parseResponse(ResponseInterface $response)
         $out = json_decode((string) $response->getBody());
 
         if (json_last_error() !== JSON_ERROR_NONE) {
-            throw new CouldNotParseResponseException('Could not parse repsonse', $response);
+            throw new CouldNotParseResponseException('Could not parse response', $response);
         }
 
         return $out;

tests/FH/PostcodeAPI/ClientTest.php

@@ -43,12 +43,12 @@ public function testRequestExceptionIsThrownWhenUsingAnInvalidApiKey()
         try {
             $client->getAddresses();
 
-            $this->fail('Should not get to this point as an exception should have been thrown because the api client was supplied with an invalid API key');
+            static::fail('Should not get to this point as an exception should have been thrown because the api client was supplied with an invalid API key');
         } catch (RequestException $exception) {
             if ($exception->getResponse() instanceof Response) {
-                $this->assertTrue($exception->getResponse()->getStatusCode() === 401);
+                static::assertTrue($exception->getResponse()->getStatusCode() === 401);
             } else {
-                $this->fail($exception->getMessage());
+                static::fail($exception->getMessage());
             }
         }
     }
@@ -65,7 +65,7 @@ public function testListResourceReturnsAllAddressesWhenNoParamsAreSupplied()
 
         $addresses = $response->_embedded->addresses;
 
-        $this->assertTrue(count($addresses) > 0, 'Expecting that there are always addresses available');
+        static::assertGreaterThan(0, count($addresses), 'Expecting that there are always addresses available');
 
         $this->applyAddressFieldAreSetAndOfTheCorrectTypeAssertions($addresses[0]);
     }
@@ -82,7 +82,7 @@ public function testListResourceReturnsExpectedAddressWhenPostcodeAndNumberAreSu
 
         $addresses = $response->_embedded->addresses;
 
-        $this->assertTrue(count($addresses) > 0, 'Expecting that there are always addresses available when no filters are applied');
+        static::assertGreaterThan(0, count($addresses), 'Expecting that there are always addresses available when no filters are applied');
 
         $firstAddress = $addresses[0];
 
@@ -99,7 +99,6 @@ public function testExpectedAddressInformationIsReturnedFromDetailResource()
         $address = $client->getAddress(self::FRESHHEADS_ADDRESS_ID);
 
         $this->applyAddressFieldAreSetAndOfTheCorrectTypeAssertions($address);
-
         $this->applyIsFreshheadsAddressAssertions($address);
     }
 
@@ -122,64 +121,68 @@ public function testClientThrowsExceptionWhenInvalidInputIsSupplied()
      */
     private function loadMockResponse($name)
     {
-        return file_get_contents(__DIR__ . "/../../Mock/{$name}");
+        return file_get_contents(sprintf('%s/../../Mock/%s', __DIR__, $name));
     }
 
     /**
-     * @param \StdClass $address
+     * @param \stdClass $address
      */
-    private function applyIsFreshheadsAddressAssertions(\StdClass $address)
+    private function applyIsFreshheadsAddressAssertions(\stdClass $address)
     {
-        $this->assertSame(strtoupper($address->postcode), self::FRESHHEADS_POSTCODE, 'Incoming postcode did not match the expected postcode');
-        $this->assertSame((string)$address->number, (string)self::FRESHHEADS_NUMBER, 'Incoming number did not match the expected number');
-        $this->assertSame($address->city->label, self::FRESHHEADS_CITY, 'Incoming city did not match the expected city');
+        static::assertSame(strtoupper($address->postcode), self::FRESHHEADS_POSTCODE, 'Incoming postcode did not match the expected postcode');
+        static::assertSame((string)$address->number, (string)self::FRESHHEADS_NUMBER, 'Incoming number did not match the expected number');
+        static::assertSame($address->city->label, self::FRESHHEADS_CITY, 'Incoming city did not match the expected city');
 
         // use number_format number rounding to allow for minor changes between expected and actual value
-        $this->assertSame(
-            number_format($address->geo->center->wgs84->coordinates[0], 5),
+        $wgs84 = $address->geo->center->wgs84;
+
+        static::assertSame(
+            number_format($wgs84->coordinates[0], 5),
             number_format(self::FRESHHEADS_LONGITUDE, 5),
             'Incoming longitude did not match the expected value'
         );
-        $this->assertSame(
-            number_format($address->geo->center->wgs84->coordinates[1], 5),
+        static::assertSame(
+            number_format($wgs84->coordinates[1], 5),
             number_format(self::FRESHHEADS_LATITUDE, 5),
             'Incoming latitude did not match the expected value'
         );
     }
 
     /**
-     * @param \StdClass $response
+     * @param \stdClass $response
      */
-    private function applyAssertsToMakeSureAddressesArrayIsAvailableInResponse(\StdClass $response)
+    private function applyAssertsToMakeSureAddressesArrayIsAvailableInResponse(\stdClass $response)
     {
-        $this->assertTrue(isset($response->_embedded->addresses));
-        $this->assertTrue(is_array($response->_embedded->addresses));
+        static::assertTrue(isset($response->_embedded->addresses));
+        static::assertTrue(is_array($response->_embedded->addresses));
     }
 
     /**
      * @param \stdClass $address
      */
-    private function applyAddressFieldAreSetAndOfTheCorrectTypeAssertions(\StdClass $address)
+    private function applyAddressFieldAreSetAndOfTheCorrectTypeAssertions(\stdClass $address)
     {
         // only test the availability of the most import fields and their values
 
-        $this->assertTrue(isset($address->street), 'Incoming address did not have a street field');
-        $this->assertTrue(is_string($address->street), 'Incoming address did not have a street value of type string');
+        static::assertTrue(isset($address->street), 'Incoming address did not have a street field');
+        static::assertTrue(is_string($address->street), 'Incoming address did not have a street value of type string');
+
+        static::assertTrue(isset($address->city->label), 'Incoming address did not have a city.label field');
+        static::assertTrue(is_string($address->city->label), 'Incoming address did not have a city.label value of type string');
 
-        $this->assertTrue(isset($address->city->label), 'Incoming address did not have a city.label field');
-        $this->assertTrue(is_string($address->city->label), 'Incoming address did not have a city.label value of type string');
+        static::assertTrue(isset($address->postcode), 'Incoming address did not have a postcode field');
+        static::assertTrue(preg_match(self::POSTCODE_PATTERN, $address->postcode) === 1, 'Incoming address did not have a postcode value that matches the pattern: ' . self::POSTCODE_PATTERN);
 
-        $this->assertTrue(isset($address->postcode), 'Incoming address did not have a postcode field');
-        $this->assertTrue(preg_match(self::POSTCODE_PATTERN, $address->postcode) === 1, 'Incoming address did not have a postcode value that matches the pattern: ' . self::POSTCODE_PATTERN);
+        static::assertTrue(isset($address->number), 'Incoming address did not have a number field');
+        static::assertTrue(is_string($address->number) || is_numeric($address->number), 'Incoming address did not have a number field with type string');
 
-        $this->assertTrue(isset($address->number), 'Incoming address did not have a number field');
-        $this->assertTrue(is_string($address->number) || is_numeric($address->number), 'Incoming address did not have a number field with type string');
+        $wgs84 = $address->geo->center->wgs84;
 
-        $this->assertTrue(isset($address->geo->center->wgs84->coordinates[0]), 'Incoming address did not have a longitude field');
-        $this->assertTrue(is_float($address->geo->center->wgs84->coordinates[0]), 'Incoming address did not have a longitude value of type float');
+        static::assertTrue(isset($wgs84->coordinates[0]), 'Incoming address did not have a longitude field');
+        static::assertTrue(is_float($address->geo->center->wgs84->coordinates[0]), 'Incoming address did not have a longitude value of type float');
 
-        $this->assertTrue(isset($address->geo->center->wgs84->coordinates[1]), 'Incoming address did not have a latitude field');
-        $this->assertTrue(is_float($address->geo->center->wgs84->coordinates[1]), 'Incoming address did not have a latitude value of type float');
+        static::assertTrue(isset($wgs84->coordinates[1]), 'Incoming address did not have a latitude field');
+        static::assertTrue(is_float($address->geo->center->wgs84->coordinates[1]), 'Incoming address did not have a latitude value of type float');
     }
 
     /**