Search numbers available to purchase

This commit deprecates `Numbers::search` in favour of
`Numbers::searchOwned` to make it clear when you're searching your own
numbers or those which are available.

When searching available numbers, there is a whitelist of supported
query parameters, via
https://developer.nexmo.com/api/developer/numbers#search-available-numbers

* pattern
* search_pattern
* features
* size
* index

Resolves #54

Author: mheap

src/Numbers/Client.php

@@ -82,7 +82,49 @@ public function get($number = null)
         return $items[0];
     }
 
+    /**
+     * @param null|string $number
+     * @return array []Number
+     * @deprecated Use `searchOwned` instead
+     */
     public function search($number = null)
+    {
+        return $this->searchOwned($number);
+    }
+
+    public function searchAvailable($country, $options = [])
+    {
+        $query = [
+            'country' => $country
+        ];
+
+        // These are all optional parameters
+        $possibleParameters = [
+            'pattern',
+            'search_pattern',
+            'features',
+            'size',
+            'index'
+        ];
+
+        foreach ($possibleParameters as $param) {
+            if (isset($options[$param])) {
+                $query[$param] = $options[$param];
+            }
+        }
+
+        $request = new Request(
+            \Nexmo\Client::BASE_REST . '/number/search?' . http_build_query($query),
+            'GET',
+            'php://temp'
+        );
+
+        $response = $this->client->send($request);
+
+        return $this->handleNumberSearchResult($response, null);
+    }
+
+    public function searchOwned($number = null)
     {
         $queryString = '';
         if ($number !== null) {
@@ -102,7 +144,11 @@ public function search($number = null)
         );
 
         $response = $this->client->send($request);
+        return $this->handleNumberSearchResult($response, $number);
+    }
 
+    private function handleNumberSearchResult($response, $number)
+    {
         if($response->getStatusCode() != '200'){
             throw $this->getException($response);
         }

test/Numbers/ClientTest.php

@@ -178,6 +178,58 @@ public function testListNumbers()
         $this->assertSame('14155550101', $numbers[1]->getId());
     }
 
+    public function testSearchAvailablePassesThroughWhitelistedOptions()
+    {
+
+        $allowedOptions = [
+            'pattern' => 'one',
+            'search_pattern' => '2',
+            'features' => 'SMS,VOICE',
+            'size' => '100',
+            'index' => '19'
+        ];
+        $invalidOptions = ['foo' => 'bananas'];
+
+        $options = array_merge($allowedOptions, $invalidOptions);
+
+        $this->nexmoClient->send(Argument::that(function(RequestInterface $request) use ($allowedOptions, $invalidOptions){
+            $this->assertEquals('/number/search', $request->getUri()->getPath());
+            $this->assertEquals('rest.nexmo.com', $request->getUri()->getHost());
+            $this->assertEquals('GET', $request->getMethod());
+
+            // Things that are whitelisted should be shown
+            foreach ($allowedOptions as $name => $value) {
+                $this->assertRequestQueryContains($name, $value, $request);
+            }
+
+            // Anything else should be dropped
+            foreach ($invalidOptions as $name => $value) {
+                $this->assertRequestQueryNotContains($name, $value, $request);
+            }
+            return true;
+        }))->willReturn($this->getResponse('available-numbers'));
+
+        $this->numberClient->searchAvailable('US', $options);
+    }
+
+    public function testSearchAvailableReturnsNumberList()
+    {
+        $this->nexmoClient->send(Argument::that(function(RequestInterface $request){
+            $this->assertEquals('/number/search', $request->getUri()->getPath());
+            $this->assertEquals('rest.nexmo.com', $request->getUri()->getHost());
+            $this->assertEquals('GET', $request->getMethod());
+            return true;
+        }))->willReturn($this->getResponse('available-numbers'));
+
+        $numbers = $this->numberClient->searchAvailable('US');
+
+        $this->assertInternalType('array', $numbers);
+        $this->assertInstanceOf('Nexmo\Numbers\Number', $numbers[0]);
+        $this->assertInstanceOf('Nexmo\Numbers\Number', $numbers[1]);
+
+        $this->assertSame('14155550100', $numbers[0]->getId());
+        $this->assertSame('14155550101', $numbers[1]->getId());
+    }
 
     public function testPurchaseNumberWithNumberObject()
     {

test/Numbers/responses/available-numbers.json

@@ -0,0 +1,24 @@
+{
+  "count": 94441,
+  "numbers": [
+    {
+      "country": "US",
+      "msisdn": "14155550100",
+      "cost": "0.67",
+      "type": "mobile-lvn",
+      "features": [
+        "VOICE",
+        "SMS"
+      ]
+    },
+    {
+      "country": "US",
+      "msisdn": "14155550101",
+      "cost": "0.67",
+      "type": "mobile-lvn",
+      "features": [
+        "VOICE"
+      ]
+    }
+  ]
+}

test/Psr7AssertionTrait.php

@@ -42,6 +42,14 @@ public static function assertRequestUrl($host, $path, $method, RequestInterface
         self::assertEquals($method, $request->getMethod());
     }
 
+    public static function assertRequestQueryNotContains($key, $value, RequestInterface $request)
+    {
+        $query = $request->getUri()->getQuery();
+        $params = [];
+        parse_str($query, $params);
+        self::assertArrayNotHasKey($key, $params, 'query string has key when it should not: ' . $key);
+    }
+
     public static function assertRequestQueryContains($key, $value, RequestInterface $request)
     {
         $query = $request->getUri()->getQuery();