Fix user agent string to confirm to the client library spec

See https://github.com/Nexmo/client-library-specification/blob/master/SPECIFICATION.md#reporting

Instead of having multiple parts delimited with slashes, each
name/version pair must be it's own entry, separated with a space.

This commit also allows the user to specify an app/name version to help
us identify their traffic if required

Author: mheap

src/Client.php

@@ -38,7 +38,7 @@
  */
 class Client
 {
-    const VERSION = '1.0.0-beta1';
+    const VERSION = '1.0.0';
 
     const BASE_API  = 'https://api.nexmo.com';
     const BASE_REST = 'https://rest.nexmo.com';
@@ -85,6 +85,11 @@ public function __construct(CredentialsInterface $credentials, $options = array(
 
         $this->options = $options;
 
+        // If they've provided an app name, validate it
+        if (isset($options['app'])) {
+            $this->validateAppOptions($options['app']);
+        }
+
         $this->setFactory(new MapFactory([
             'message' => 'Nexmo\Message\Client',
             'verify'  => 'Nexmo\Verify\Client',
@@ -319,17 +324,45 @@ public function send(\Psr\Http\Message\RequestInterface $request)
             }
         }
 
-        //set the user-agent
-        $request = $request->withHeader('user-agent', implode('/', [
-            'nexmo-php',
-            self::VERSION,
-            'PHP-' . implode('.', [PHP_MAJOR_VERSION, PHP_MINOR_VERSION])
-        ]));
+        // The user agent must be in the following format:
+        // LIBRARY-NAME/LIBRARY-VERSION LANGUAGE-NAME/LANGUAGE-VERSION [APP-NAME/APP-VERSION]
+        // See https://github.com/Nexmo/client-library-specification/blob/master/SPECIFICATION.md#reporting
+        $userAgent = [];
+
+        // Library name
+        $userAgent[] = 'nexmo-php/'.self::VERSION;
+
+        // Language name
+        $userAgent[] = 'php/'.PHP_MAJOR_VERSION.'.'.PHP_MINOR_VERSION;
+
+        // If we have an app set, add that to the UA
+        if (isset($this->options['app'])) {
+            $app = $this->options['app'];
+            $userAgent[] = $app['name'].'/'.$app['version'];
+        }
+
+        // Set the header. Build by joining all the parts we have with a space
+        $request = $request->withHeader('user-agent', implode(" ", $userAgent));
 
         $response = $this->client->sendRequest($request);
         return $response;
     }
 
+    protected function validateAppOptions($app) {
+        $disallowedCharacters = ['/', ' ', "\t", "\n"];
+        foreach (['name', 'version'] as $key) {
+            if (!isset($app[$key])) {
+                throw new \InvalidArgumentException('app.'.$key.' has not been set');
+            }
+
+            foreach ($disallowedCharacters as $char) {
+                if (strpos($app[$key], $char) !== false) {
+                    throw new \InvalidArgumentException('app.'.$key.' cannot contain the '.$char.' character');
+                }
+            }
+        }
+    }
+
     public function serialize(EntityInterface $entity)
     {
         if($entity instanceof Verification){

test/ClientTest.php

@@ -52,6 +52,43 @@ public function setUp()
         $this->container    = new Client\Credentials\Container($this->key_credentials, $this->basic_credentials, $this->signature_credentials);
     }
 
+    /**
+     * @dataProvider validateAppNameThrowsProvider
+     */
+    public function testValidateAppNameThrows($name, $version, $field, $invalidCharacter)
+    {
+        try {
+            new Client($this->basic_credentials, [
+                'app' => [
+                    'name' => $name,
+                    'version' => $version
+                ]
+            ], $this->http);
+
+            $this->fail('invalid app details provided, but no exception was thrown');
+        } catch (\InvalidArgumentException $e) {
+            $this->assertEquals('app.'.$field.' cannot contain the '.$invalidCharacter.' character', $e->getMessage());
+        }
+
+    }
+
+    public function validateAppNameThrowsProvider()
+    {
+        $r = [];
+
+        $r['/ name'] = ['foo/bar', '1.0', 'name', '/'];
+        $r['space name'] = ['foo bar', '1.0', 'name', ' '];
+        $r['tab name'] = ["foo\tbar", '1.0', 'name', "\t"];
+        $r['newline name'] = ["foo\nbar", '1.0', 'name', "\n"];
+
+        $r['/ version'] = ['foobar', '1/0', 'version', '/'];
+        $r['space version'] = ['foobar', '1 0', 'version', ' '];
+        $r['tab version'] = ["foobar", "1\t0", 'version', "\t"];
+        $r['newline version'] = ["foobar", "1\n0", 'version', "\n"];
+
+        return $r;
+    }
+
     public function testBasicCredentialsQuery()
     {
         $client = new Client($this->basic_credentials, [], $this->http);
@@ -299,10 +336,10 @@ public function testNamespaceFactory()
         $this->assertSame($api, $client->sms());
     }
 
-    public function testUserAgentString()
+    public function testUserAgentStringAppNotProvided()
     {
         $version = Client::VERSION;
-        $php = 'PHP-' . implode('.', [
+        $php = 'php/' . implode('.', [
             PHP_MAJOR_VERSION,
             PHP_MINOR_VERSION
         ]);
@@ -320,15 +357,49 @@ public function testUserAgentString()
 
         //useragent should match the expected format
         $agent = $this->http->getRequests()[0]->getHeaderLine('user-agent');
-        $expected = implode('/', [
-            'nexmo-php',
-            $version,
+        $expected = implode(' ', [
+            'nexmo-php/'.$version,
             $php
         ]);
 
         $this->assertEquals($expected, $agent);
     }
 
+    public function testUserAgentStringAppProvided()
+    {
+        $version = Client::VERSION;
+        $php = 'php/' . implode('.', [
+            PHP_MAJOR_VERSION,
+            PHP_MINOR_VERSION
+        ]);
+
+        //get a mock response to test
+        $response = new Response();
+        $response->getBody()->write('test response');
+        $this->http->addResponse($response);
+
+        $client = new Client(new Basic('key', 'secret'), [
+            'app' => [
+                'name' => 'TestApp',
+                'version' => '9.4.5'
+            ]
+        ], $this->http);
+        $request = $this->getRequest();
+
+        //api client should simply pass back the http response
+        $client->send($request);
+
+        //useragent should match the expected format
+        $agent = $this->http->getRequests()[0]->getHeaderLine('user-agent');
+        $expected = implode(' ', [
+            'nexmo-php/'.$version,
+            $php,
+            'TestApp/9.4.5'
+        ]);
+
+        $this->assertEquals($expected, $agent);
+    }
+
     public function testSerializationProxiesVerify()
     {
         $verify = $this->prophesize('Nexmo\Verify\Client');