feat(interfaces): Add ApplicationInterface and IntegrationInterface

Author: dborsatto

CHANGELOG.md

@@ -6,7 +6,9 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## [Unreleased](https://github.com/contentful/contentful-core.php/compare/2.1.1...HEAD)
 
 <!-- PENDING-CHANGES -->
-> No meaningful changes since last release.
+### Added
+
+* Interface `ApplicationInterface` and `IntegrationInterface` have been added, as well as `ClientInterface::useApplication(ApplicationInterface $application)` and `ClientInterface::useIntegration(IntegrationInterface $integration)`. The `BaseClient` class already provides an implementation of these methods.
 <!-- /PENDING-CHANGES -->
 
 ## [2.1.1](https://github.com/contentful/contentful-core.php/tree/2.1.1) (2018-11-08)

src/Api/ApplicationInterface.php

@@ -0,0 +1,49 @@
+<?php
+
+/**
+ * This file is part of the contentful/contentful-core package.
+ *
+ * @copyright 2015-2018 Contentful GmbH
+ * @license   MIT
+ */
+
+declare(strict_types=1);
+
+namespace Contentful\Core\Api;
+
+interface ApplicationInterface
+{
+    /**
+     * Returns the name of the current application.
+     * This value must be the one that is sent as part of
+     * the "X-Contentful-User-Agent" header to the API.
+     *
+     * @return string
+     */
+    public function getApplicationName(): string;
+
+    /**
+     * Returns whether the current application is distributed as a Composer package.
+     *
+     * @return bool
+     */
+    public function isPackagedApplication(): bool;
+
+    /**
+     * Returns the package name of the current application.
+     * If the application is not distributed as a package, this method
+     * must return an empty string.
+     *
+     * @return string
+     */
+    public function getApplicationPackageName(): string;
+
+    /**
+     * Returns the version of the current application.
+     * This must return an actual version if the application is not distributed
+     * as a Composer package.
+     *
+     * @return string
+     */
+    public function getApplicationVersion(): string;
+}

src/Api/BaseClient.php

@@ -201,6 +201,21 @@ public function getHost(): string
         return $this->host;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function useApplication(ApplicationInterface $application)
+    {
+        $version = $application->isPackagedApplication()
+            ? self::getVersionForPackage($application->getApplicationPackageName())
+            : $application->getApplicationVersion();
+
+        $this->userAgentGenerator->setApplication(
+            $application->getApplicationName(),
+            $version
+        );
+    }
+
     /**
      * {@inheritdoc}
      */
@@ -211,6 +226,17 @@ public function setApplication(string $name, string $version = '')
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function useIntegration(IntegrationInterface $integration)
+    {
+        $this->userAgentGenerator->setIntegration(
+            $integration->getIntegrationName(),
+            self::getVersionForPackage($integration->getIntegrationPackageName())
+        );
+    }
+
     /**
      * {@inheritdoc}
      */
@@ -225,6 +251,16 @@ public function setIntegration(string $name, string $version = '')
      * @return string
      */
     public static function getVersion(): string
+    {
+        return self::getVersionForPackage(static::getPackageName());
+    }
+
+    /**
+     * @param string $package
+     *
+     * @return string
+     */
+    protected static function getVersionForPackage(string $package): string
     {
         try {
             $shortVersion = PrettyVersions::getVersion(static::getPackageName())

src/Api/ClientInterface.php

@@ -32,21 +32,41 @@ interface ClientInterface
      */
     public function request(string $method, string $uri, array $options = []): ResourceInterface;
 
+    /**
+     * Sets the current application.
+     * The values are used as part of the X-Contentful-User-Agent header.
+     *
+     * @param ApplicationInterface $application
+     */
+    public function useApplication(ApplicationInterface $application);
+
     /**
      * Set the application name and version.
      * The values are used as part of the X-Contentful-User-Agent header.
      *
      * @param string $name
      * @param string $version
+     *
+     * @deprecated 2.2.0 Use useApplication instead
      */
     public function setApplication(string $name, string $version = '');
 
+    /**
+     * Sets the current integration.
+     * The values are used as part of the X-Contentful-User-Agent header.
+     *
+     * @param IntegrationInterface $integration
+     */
+    public function useIntegration(IntegrationInterface $integration);
+
     /**
      * Set the integration name and version.
      * The values are used as part of the X-Contentful-User-Agent header.
      *
      * @param string $name
      * @param string $version
+     *
+     * @deprecated 2.2.0 Use useIntegration instead
      */
     public function setIntegration(string $name, string $version = '');
 

src/Api/IntegrationInterface.php

@@ -0,0 +1,32 @@
+<?php
+
+/**
+ * This file is part of the contentful/contentful-core package.
+ *
+ * @copyright 2015-2018 Contentful GmbH
+ * @license   MIT
+ */
+
+declare(strict_types=1);
+
+namespace Contentful\Core\Api;
+
+interface IntegrationInterface
+{
+    /**
+     * Returns the name of the current integration.
+     * This value must be the one that is sent as part of
+     * the "X-Contentful-User-Agent" header to the API.
+     *
+     * @return string
+     */
+    public function getIntegrationName(): string;
+
+    /**
+     * Returns the package name of the current integration.
+     * This value must be the one defined in the "composer.json" file.
+     *
+     * @return string
+     */
+    public function getIntegrationPackageName(): string;
+}

tests/Implementation/Application.php

@@ -0,0 +1,63 @@
+<?php
+
+/**
+ * This file is part of the contentful/contentful-core package.
+ *
+ * @copyright 2015-2018 Contentful GmbH
+ * @license   MIT
+ */
+
+declare(strict_types=1);
+
+namespace Contentful\Tests\Core\Implementation;
+
+use Contentful\Core\Api\ApplicationInterface;
+
+class Application implements ApplicationInterface
+{
+    /**
+     * @var bool
+     */
+    private $isPackagedApplication;
+
+    public function __construct(bool $isPackagedApplication)
+    {
+        $this->isPackagedApplication = $isPackagedApplication;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getApplicationName(): string
+    {
+        return 'the-example-app';
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function isPackagedApplication(): bool
+    {
+        return $this->isPackagedApplication;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getApplicationPackageName(): string
+    {
+        return $this->isPackagedApplication
+            ? 'contentful/the-example-app'
+            : '';
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getApplicationVersion(): string
+    {
+        return $this->isPackagedApplication
+            ? ''
+            : '1.0.0';
+    }
+}

tests/Implementation/Integration.php

@@ -0,0 +1,33 @@
+<?php
+
+/**
+ * This file is part of the contentful/contentful-core package.
+ *
+ * @copyright 2015-2018 Contentful GmbH
+ * @license   MIT
+ */
+
+declare(strict_types=1);
+
+namespace Contentful\Tests\Core\Implementation;
+
+use Contentful\Core\Api\IntegrationInterface;
+
+class Integration implements IntegrationInterface
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function getIntegrationName(): string
+    {
+        return 'contentful.symfony';
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getIntegrationPackageName(): string
+    {
+        return 'contentful/contentful-bundle';
+    }
+}

tests/Unit/Api/BaseClientTest.php

@@ -11,9 +11,11 @@
 
 namespace Contentful\Tests\Core\Unit\Api;
 
+use Contentful\Tests\Core\Implementation\Application;
 use Contentful\Tests\Core\Implementation\Client;
 use Contentful\Tests\Core\Implementation\ClientCustomException;
 use Contentful\Tests\Core\Implementation\Exception\BadRequestException;
+use Contentful\Tests\Core\Implementation\Integration;
 use Contentful\Tests\Core\Implementation\InvalidPackageNameClient;
 use Contentful\Tests\TestCase;
 use GuzzleHttp\Client as HttpClient;
@@ -177,10 +179,53 @@ public function testInvalidPackageNameVersion()
 
         $request = $client->getMessages()[0]->getRequest();
         // When the current package name is invalid,
-        //the version will automatically be set to 0.0.0-alpha
+        // the version will automatically be set to 0.0.0-alpha
         $this->assertRegExp(
             '/sdk invalid\/0.0.0-alpha; platform PHP\/[0-9\.]*; os (Windows|Linux|macOS);$/',
             $request->getHeaderLine('X-Contentful-User-Agent')
         );
     }
+
+    public function testCustomApplication()
+    {
+        $httpClient = $this->createHttpClient(function (): ResponseInterface {
+            return new Response(201);
+        });
+        $client = new Client('irrelevant', 'https://cdn.contentful.com', \null, $httpClient);
+
+        $client->useApplication(new Application(\false));
+        $client->callApi('GET', '/');
+
+        $request = $client->getMessages()[0]->getRequest();
+        $this->assertRegExp(
+            '/^app the-example-app\/1.0.0; sdk contentful-core.php\/[0-9\.]*(-(dev|beta|alpha|RC))?; platform PHP\/[0-9\.]*; os (Windows|Linux|macOS);$/',
+            $request->getHeaderLine('X-Contentful-User-Agent')
+        );
+
+        $client->useApplication(new Application(\true));
+        $client->callApi('GET', '/');
+
+        $request = $client->getMessages()[0]->getRequest();
+        $this->assertRegExp(
+            '/^app the-example-app\/[0-9\.]*(-(dev|beta|alpha|RC))?; sdk contentful-core.php\/[0-9\.]*(-(dev|beta|alpha|RC))?; platform PHP\/[0-9\.]*; os (Windows|Linux|macOS);$/',
+            $request->getHeaderLine('X-Contentful-User-Agent')
+        );
+    }
+
+    public function testCustomIntegration()
+    {
+        $httpClient = $this->createHttpClient(function (): ResponseInterface {
+            return new Response(201);
+        });
+        $client = new Client('irrelevant', 'https://cdn.contentful.com', \null, $httpClient);
+
+        $client->useIntegration(new Integration());
+        $client->callApi('GET', '/');
+
+        $request = $client->getMessages()[0]->getRequest();
+        $this->assertRegExp(
+            '/^integration contentful.symfony\/[0-9\.]*(-(dev|beta|alpha|RC))?; sdk contentful-core.php\/[0-9\.]*(-(dev|beta|alpha|RC))?; platform PHP\/[0-9\.]*; os (Windows|Linux|macOS);$/',
+            $request->getHeaderLine('X-Contentful-User-Agent')
+        );
+    }
 }