Merge pull request #192 from Nexmo/v2-alpha

SDK v2 Release

Author: dragonmantank

.gitignore

@@ -2,3 +2,4 @@
 composer.lock
 vendor
 logs
+.php_cs.cache

.travis.yml

@@ -1,7 +1,5 @@
 language: php
 php:
-  - '5.6'
-  - '7.0'
   - '7.1'
   - '7.2'
   - '7.3'

README.md

@@ -5,7 +5,7 @@ Client Library for PHP
 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE.txt)
 [![codecov](https://codecov.io/gh/Nexmo/nexmo-php/branch/master/graph/badge.svg)](https://codecov.io/gh/Nexmo/nexmo-php)
 
-*This library requires a minimum PHP version of 5.6*
+*This library requires a minimum PHP version of 7.1*
 
 This is the PHP client library for use Nexmo's API. To use this, you'll need a Nexmo account. Sign up [for free at 
 nexmo.com][signup].
@@ -655,6 +655,43 @@ $response = $client->account()->updateConfig([
 print_r($response->data);
 ```
 
+### Get Information About a Number
+
+The [Number Insights API](https://developer.nexmo.com/api/number-insight) allows a user to check that a number is valid and to find out more about how to use it.
+
+#### Basic and Standard Usage
+
+You can use either the `basic()` or `standard()` methods (an `advanced()` method is available, but it is recommended to use the async option to get advanced info), like this:
+
+```php
+
+try {
+  $insights = $client->insights()->basic(PHONE_NUMBER);
+
+  echo $insights['national_format_number'];
+} catch (Exception $e) {
+  // for the Nexmo-specific exceptions, try the `getEntity()` method for more diagnostic information
+}
+```
+
+The data is returned in the `$insights` variable in the example above.
+
+#### Advanced Usage
+
+To get advanced insights, use the async feature and supply a URL for the webhook to be sent to:
+
+```php
+try {
+  $client->insights()->advancedAsync(PHONE_NUMBER, 'http://example.com/webhooks/number-insights');
+} catch (Exception $e) {
+  // for the Nexmo-specific exceptions, try the `getEntity()` method for more diagnostic information
+}
+```
+
+Check out the [documentation](https://developer.nexmo.com/number-insight/code-snippets/number-insight-advanced-async-callback) for what to expect in the incoming webhook containing the data you requested.
+
+
+
 ## Troubleshooting
 
 
@@ -679,7 +716,7 @@ curl.cainfo = "/etc/pki/tls/cacert.pem"
 curl.cainfo = "C:\php\extras\ssl\cacert.pem"
 ```
 
-### Pass custom Guzzle client
+### Pass custom HTTP client
 
 We allow use of any HTTPlug adapter, so you can create a client with alternative configuration if you need it, for example to take account of a local proxy, or deal with something else specific to your setup.
 
@@ -690,6 +727,15 @@ $adapter_client = new Http\Adapter\Guzzle6\Client(new GuzzleHttp\Client(['timeou
 $nexmo_client = new Nexmo\Client(new Nexmo\Client\Credentials\Basic($api_key, $api_secret), [], $adapter_client);
 ```
 
+### Accessing Response Data
+
+When things go wrong, you'll receive an `Exception`. The Nexmo exception classes `Nexmo\Client\Exception\Request` and `Nexmo\Client\Exception\Server` support an additional `getEntity()` method which you can use in addition to `getCode()` and `getMessage()` to find out more about what went wrong. The entity returned will typically be an object related to the operation, or the response object from the API call.
+
+### Composer installation fails due to Guzzle Adapter
+
+If you have a conflicting package installation that cannot co-exist with our recommended `php-http/guzzle6-adapter` package, then you may install the package `nexmo/client-core` along with any package that satisfies the `php-http/client-implementation` requirement.
+
+See the [Packagist page for client-implementation](https://packagist.org/providers/php-http/client-implementation) for options.
 
 Contributing
 ------------

composer.json

@@ -1,5 +1,5 @@
 {
-  "name": "nexmo/client",
+  "name": "nexmo/client-core",
   "description": "PHP Client for using Nexmo's API.",
   "license": "MIT",
   "type": "library",
@@ -9,23 +9,39 @@
       "email": "tim@nexmo.com",
       "role": "Developer",
       "homepage": "http://twitter.com/tjlytle"
+    },
+    {
+      "name": "Michael Heap",
+      "email": "michael.heap@vonage.com",
+      "role": "Developer"
+    },
+    {
+      "name": "Lorna Mitchell",
+      "email": "lorna.mitchell@vonage.com",
+      "role": "Developer"
+    },
+    {
+      "name": "Chris Tankersley",
+      "email": "chris.tankersley@vonage.com",
+      "role": "Developer"
     }
   ],
   "support": {
     "email": "devrel@nexmo.com"
   },
   "require": {
-    "php": ">=5.6",
+    "php": ">=7.1",
     "php-http/client-implementation": "^1.0",
     "zendframework/zend-diactoros": "^1.8.4 || ^2.0",
-    "php-http/guzzle6-adapter": "^1.0",
-    "lcobucci/jwt": "^3.2"
+    "lcobucci/jwt": "^3.2",
+    "ocramius/package-versions": "^1.4"
   },
   "require-dev": {
-    "phpunit/phpunit": "^5.7",
+    "phpunit/phpunit": "^7.4",
     "php-http/mock-client": "^0.3.0",
-    "estahn/phpunit-json-assertions": "^1.0.0",
-    "squizlabs/php_codesniffer": "^3.1"
+    "estahn/phpunit-json-assertions": "^3.0.0",
+    "squizlabs/php_codesniffer": "^3.1",
+    "php-http/guzzle6-adapter": "^1.0"
   },
   "autoload": {
     "psr-4": {
@@ -37,5 +53,8 @@
       "Nexmo\\": "test/",
       "NexmoTest\\": "test/"
     }
+  },
+  "replace": {
+    "nexmo/client": "^2.0"
   }
 }

src/Account/Balance.php

@@ -7,7 +7,19 @@
 use Nexmo\Entity\JsonSerializableInterface;
 use Nexmo\Entity\JsonUnserializableInterface;
 
-class Balance implements JsonSerializableInterface, JsonUnserializableInterface, ArrayAccess {
+/**
+ * @todo Have the JSON unserialize/serialize keys match with $this->data keys
+ */
+class Balance implements JsonSerializableInterface, JsonUnserializableInterface, ArrayAccess
+{
+    /**
+     * @var array
+     */
+    public $data;
+
+    /**
+     * @todo Have these take null values, since we offer an unserialize option to populate
+     */
     public function __construct($balance, $autoReload)
     {
         $this->data['balance'] = $balance;
@@ -32,7 +44,7 @@ public function jsonUnserialize(array $json)
         ];
     }
 
-    function jsonSerialize()
+    public function jsonSerialize()
     {
         return $this->data;
     }
@@ -56,4 +68,4 @@ public function offsetUnset($offset)
     {
         throw new Exception('Balance is read only');
     }
-}
+}

src/Account/Client.php

@@ -10,7 +10,9 @@
 use Zend\Diactoros\Request;
 use Nexmo\Client\Exception;
 
-
+/**
+ * @todo Unify the exception handling to avoid duplicated code and logic (ie: getPrefixPricing())
+ */
 class Client implements ClientAwareInterface
 {
     use ClientAwareTrait;
@@ -36,7 +38,7 @@ public function getPrefixPricing($prefix)
         if ($codeCategory != 2) {
             if ($codeCategory == 4) {
                 throw new Exception\Request($body['error-code-label']);
-            }else if ($codeCategory == 5) {
+            } elseif ($codeCategory == 5) {
                 throw new Exception\Server($body['error-code-label']);
             }
         }
@@ -72,6 +74,9 @@ public function getVoicePrice($country)
         return $voicePrice;
     }
 
+    /**
+     * @todo This should return an empty result instead of throwing an Exception on no results
+     */
     protected function makePricingRequest($country, $pricingType)
     {
         $queryString = http_build_query([
@@ -94,9 +99,11 @@ protected function makePricingRequest($country, $pricingType)
         return json_decode($rawBody, true);
     }
 
+    /**
+     * @todo This needs further investigated to see if '' can even be returned from this endpoint
+     */
     public function getBalance()
     {
-
         $request = new Request(
             $this->getClient()->getRestUrl() . '/account/get-balance',
             'GET',
@@ -123,23 +130,22 @@ public function topUp($trx)
         ];
 
         $request = new Request(
-            $this->getClient()->getRestUrl() . '/account/top-up'
-            ,'POST'
-            , 'php://temp'
-            , ['content-type' => 'application/x-www-form-urlencoded']
+            $this->getClient()->getRestUrl() . '/account/top-up',
+            'POST',
+            'php://temp',
+            ['content-type' => 'application/x-www-form-urlencoded']
         );
 
         $request->getBody()->write(http_build_query($body));
         $response = $this->client->send($request);
 
-        if($response->getStatusCode() != '200'){
+        if ($response->getStatusCode() != '200') {
             throw $this->getException($response);
         }
     }
 
     public function getConfig()
     {
-
         $request = new Request(
             $this->getClient()->getRestUrl() . '/account/settings',
             'POST',
@@ -169,11 +175,11 @@ public function updateConfig($options)
     {
         // supported options are SMS Callback and DR Callback
         $params = [];
-        if(isset($options['sms_callback_url'])) {
+        if (isset($options['sms_callback_url'])) {
             $params['moCallBackUrl'] = $options['sms_callback_url'];
         }
 
-        if(isset($options['dr_callback_url'])) {
+        if (isset($options['dr_callback_url'])) {
             $params['drCallBackUrl'] = $options['dr_callback_url'];
         }
 
@@ -187,7 +193,7 @@ public function updateConfig($options)
         $request->getBody()->write(http_build_query($params));
         $response = $this->client->send($request);
 
-        if($response->getStatusCode() != '200'){
+        if ($response->getStatusCode() != '200') {
             throw $this->getException($response);
         }
 
@@ -211,13 +217,13 @@ public function updateConfig($options)
 
     public function listSecrets($apiKey)
     {
-        $body = $this->get( $this->getClient()->getApiUrl() . '/accounts/'.$apiKey.'/secrets');
+        $body = $this->get($this->getClient()->getApiUrl() . '/accounts/'.$apiKey.'/secrets');
         return SecretCollection::fromApi($body);
     }
 
     public function getSecret($apiKey, $secretId)
     {
-        $body = $this->get( $this->getClient()->getApiUrl() . '/accounts/'.$apiKey.'/secrets/'. $secretId);
+        $body = $this->get($this->getClient()->getApiUrl() . '/accounts/'.$apiKey.'/secrets/'. $secretId);
         return Secret::fromApi($body);
     }
 
@@ -228,10 +234,10 @@ public function createSecret($apiKey, $newSecret)
         ];
 
         $request = new Request(
-            $this->getClient()->getApiUrl() . '/accounts/'.$apiKey.'/secrets'
-            ,'POST'
-            , 'php://temp'
-            , ['content-type' => 'application/json']
+            $this->getClient()->getApiUrl() . '/accounts/'.$apiKey.'/secrets',
+            'POST',
+            'php://temp',
+            ['content-type' => 'application/json']
         );
 
         $request->getBody()->write(json_encode($body));
@@ -247,10 +253,10 @@ public function createSecret($apiKey, $newSecret)
     public function deleteSecret($apiKey, $secretId)
     {
         $request = new Request(
-            $this->getClient()->getApiUrl() . '/accounts/'.$apiKey.'/secrets/'. $secretId
-            ,'DELETE'
-            , 'php://temp'
-            , ['content-type' => 'application/json']
+            $this->getClient()->getApiUrl() . '/accounts/'.$apiKey.'/secrets/'. $secretId,
+            'DELETE',
+            'php://temp',
+            ['content-type' => 'application/json']
         );
 
         $response = $this->client->send($request);
@@ -263,12 +269,13 @@ public function deleteSecret($apiKey, $secretId)
         // This returns a 204, so no response body
     }
 
-    protected function get($url) {
-       $request = new Request(
-           $url
-           ,'GET'
-           , 'php://temp'
-           , ['content-type' => 'application/json']
+    protected function get($url)
+    {
+        $request = new Request(
+            $url,
+            'GET',
+            'php://temp',
+            ['content-type' => 'application/json']
         );
 
         $response = $this->client->send($request);
@@ -281,20 +288,35 @@ protected function get($url) {
         return $body;
     }
 
+    /**
+     * Generates an appropriate Exception message and object based on HTTP response
+     * This has a bit of logic to it since different error messages have a different
+     * reponse format.
+     *
+     * @return Exception
+     */
     protected function getException(ResponseInterface $response, $application = null)
     {
         $body = json_decode($response->getBody()->getContents(), true);
         $status = $response->getStatusCode();
 
-        if($status >= 400 AND $status < 500) {
-            $e = new Exception\Request($body['error_title'], $status);
-        } elseif($status >= 500 AND $status < 600) {
-            $e = new Exception\Server($body['error_title'], $status);
-        } else {
-            $e = new Exception\Exception('Unexpected HTTP Status Code');
+        $errorMessage = "Unexpected HTTP Status Code";
+        if (array_key_exists('error_title', $body)) {
+            $errorMessage = $body['error_title'];
+        } elseif (array_key_exists('error-code-label', $body)) {
+            $errorMessage = $body['error-code-label'];
         }
 
+        $e = new Exception\Exception($errorMessage);
+        if ($status >= 400 && $status < 500) {
+            $e = new Exception\Request($errorMessage, $status);
+        } elseif ($status >= 500 && $status < 600) {
+            $e = new Exception\Server($errorMessage, $status);
+        }
+
+        $response->getBody()->rewind();
+        $e->setEntity($response);
+
         return $e;
     }
-
 }