Merge pull request #20 from contentful/feat/interfaces

Add more interfaces

Author: dborsatto

composer.json

@@ -5,6 +5,7 @@
     "require": {
         "php": "^7.0",
         "ext-json": "*",
+        "ext-mbstring": "*",
         "guzzlehttp/guzzle": "^6.3",
         "guzzlehttp/psr7": "^1.4",
         "psr/http-message": "^1.0",

src/Api/BaseClient.php

@@ -13,21 +13,20 @@
 
 use Contentful\Core\Log\NullLogger;
 use GuzzleHttp\Client as HttpClient;
-use GuzzleHttp\Exception\ClientException;
 use Jean85\PrettyVersions;
-use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
 use Psr\Log\LoggerInterface;
 use function GuzzleHttp\json_decode as guzzle_json_decode;
 
 /**
  * Abstract client for common code for the different clients.
  */
-abstract class BaseClient
+abstract class BaseClient implements ClientInterface
 {
     /**
-     * @var HttpClient
+     * @var Requester
      */
-    private $httpClient;
+    private $requester;
 
     /**
      * @var LoggerInterface
@@ -69,14 +68,18 @@ public function __construct(
         HttpClient $httpClient = \null
     ) {
         $this->logger = $logger ?: new NullLogger();
-        $this->httpClient = $httpClient ?: new HttpClient();
+        $this->requester = new Requester(
+            $httpClient ?: new HttpClient(),
+            $this->getApi(),
+            $this->getExceptionNamespace()
+        );
 
         if ('/' === \mb_substr($host, -1)) {
             $host = \mb_substr($host, 0, -1);
         }
         $this->host = $host;
 
-        $this->userAgentGenerator = new UserAgentGenerator($this->getSdkName(), $this->getVersion());
+        $this->userAgentGenerator = new UserAgentGenerator($this->getSdkName(), self::getVersion());
         $this->requestBuilder = new RequestBuilder(
             $accessToken,
             $host,
@@ -86,184 +89,77 @@ public function __construct(
     }
 
     /**
-     * @return string
-     */
-    private function getVersion(): string
-    {
-        try {
-            $version = PrettyVersions::getVersion($this->getPackageName());
-            $shortVersion = $version->getShortVersion();
-
-            // Removes the ".x-dev" part which is inserted during development
-            if ('.x-dev' === \mb_substr($shortVersion, -6)) {
-                $shortVersion = \mb_substr($shortVersion, 0, -6).'-dev';
-            }
-
-            return $shortVersion;
-        } catch (\OutOfBoundsException $exception) {
-            return '0.0.0-alpha';
-        }
-    }
-
-    /**
-     * 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
-     *
-     * @return $this
-     */
-    public function setApplication(string $name, string $version = '')
-    {
-        $this->userAgentGenerator->setApplication($name, $version);
-
-        return $this;
-    }
-
-    /**
-     * Set the integration name and version.
-     * The values are used as part of the X-Contentful-User-Agent header.
+     * Make a call to the API and returns the parsed JSON.
      *
-     * @param string $name
-     * @param string $version
-     *
-     * @return $this
-     */
-    public function setIntegration(string $name, string $version = '')
-    {
-        $this->userAgentGenerator->setIntegration($name, $version);
-
-        return $this;
-    }
-
-    /**
      * @param string $method  The HTTP method
-     * @param string $path    The URI path
+     * @param string $uri     The URI path
      * @param array  $options An array of optional parameters. The following keys are accepted:
      *                        * query   An array of query parameters that will be appended to the URI
      *                        * headers An array of headers that will be added to the request
      *                        * body    The request body
-     *                        * baseUri A string that can be used to override the default client base URI
+     *                        * host    A string that can be used to override the default client base URI
      *
      * @throws \Exception
      *
-     * @return array|null
+     * @return array
      */
-    protected function request(string $method, string $path, array $options = [])
+    protected function callApi(string $method, string $uri, array $options = []): array
     {
-        $request = $this->requestBuilder->build($method, $path, $options);
+        $request = $this->requestBuilder->build($method, $uri, $options);
 
-        $message = $this->callApi($request);
+        $message = $this->requester->sendRequest($request);
         $this->messages[] = $message;
 
-        $logMessage = \sprintf(
-            '%s %s (%.3Fs)',
-            $request->getMethod(),
-            (string) $request->getUri(),
-            $message->getDuration()
-        );
-
-        // This is a "simple" log, for general purpose
-        $this->logger->log(
-            $message->getLogLevel(),
-            $logMessage
-        );
-        // This is a debug log, with all message details
-        $this->logger->debug($logMessage, $message->jsonSerialize());
+        $this->logMessage($message);
 
         $exception = $message->getException();
         if (\null !== $exception) {
             throw $exception;
         }
 
-        $response = $message->getResponse();
-        $body = $response
-            ? (string) $response->getBody()
-            : \null;
-
-        return $body
-            ? guzzle_json_decode($body, \true)
-            : [];
+        return $this->parseResponse($message->getResponse());
     }
 
     /**
-     * Performs a query to the API, and returns a message object
-     * which contains all information needed for processing and logging.
+     * Write information about a message object into the logger.
      *
-     * @param RequestInterface $request
-     *
-     * @return Message
+     * @param Message $message
      */
-    private function callApi(RequestInterface $request): Message
+    private function logMessage(Message $message)
     {
-        $startTime = \microtime(\true);
-
-        $exception = \null;
-        try {
-            $response = $this->httpClient->send($request);
-        } catch (ClientException $exception) {
-            $response = $exception->hasResponse()
-                ? $exception->getResponse()
-                : \null;
-
-            $exception = $this->createCustomException($exception);
-        }
-
-        $duration = \microtime(\true) - $startTime;
-
-        return new Message(
-            $this->getApi(),
-            $duration,
-            $request,
-            $response,
-            $exception
+        $logMessage = \sprintf(
+            '%s %s (%.3Fs)',
+            $message->getRequest()->getMethod(),
+            (string) $message->getRequest()->getUri(),
+            $message->getDuration()
         );
-    }
-
-    /**
-     * Attempts to create a custom exception.
-     * It will return a default exception if no suitable class is found.
-     *
-     * @param ClientException $exception
-     *
-     * @return Exception
-     */
-    private function createCustomException(ClientException $exception): Exception
-    {
-        $errorId = '';
-        $response = $exception->getResponse();
-        if ($response) {
-            $data = guzzle_json_decode((string) $response->getBody(), \true);
-            $errorId = (string) $data['sys']['id'];
-        }
 
-        $exceptionClass = $this->getExceptionClass($errorId);
+        // This is a "simple" log, for general purpose
+        $this->logger->log(
+            $message->getLogLevel(),
+            $logMessage
+        );
 
-        return new $exceptionClass($exception);
+        // This is a debug log, with all message details, useful for debugging
+        $this->logger->debug($logMessage, $message->jsonSerialize());
     }
 
     /**
-     * Returns the FQCN of an exception class to be used for the given API error.
+     * Parse the body of a JSON response.
      *
-     * @param string $apiError
+     * @param ResponseInterface|null $response
      *
-     * @return string
+     * @return array
      */
-    private function getExceptionClass(string $apiError): string
+    private function parseResponse(ResponseInterface $response = \null): array
     {
-        $namespace = $this->getExceptionNamespace();
-        if ($namespace) {
-            $class = $namespace.'\\'.$apiError.'Exception';
-
-            if (\class_exists($class)) {
-                return $class;
-            }
-        }
-
-        $class = '\\Contentful\\Core\\Exception\\'.$apiError.'Exception';
+        $body = $response
+            ? (string) $response->getBody()
+            : \null;
 
-        return \class_exists($class) ? $class : Exception::class;
+        return $body
+            ? guzzle_json_decode($body, \true)
+            : [];
     }
 
     /**
@@ -306,30 +202,64 @@ public function getHost(): string
     }
 
     /**
-     * Returns a string representation of the API currently in use.
-     *
+     * {@inheritdoc}
+     */
+    public function setApplication(string $name, string $version = '')
+    {
+        $this->userAgentGenerator->setApplication($name, $version);
+
+        return $this;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function setIntegration(string $name, string $version = '')
+    {
+        $this->userAgentGenerator->setIntegration($name, $version);
+
+        return $this;
+    }
+
+    /**
      * @return string
      */
-    abstract public function getApi(): string;
+    public static function getVersion(): string
+    {
+        try {
+            $shortVersion = PrettyVersions::getVersion(static::getPackageName())
+                ->getShortVersion()
+            ;
+
+            // Removes the ".x-dev" part which is inserted during development
+            if ('.x-dev' === \mb_substr($shortVersion, -6)) {
+                $shortVersion = \mb_substr($shortVersion, 0, -6).'-dev';
+            }
+
+            return $shortVersion;
+        } catch (\OutOfBoundsException $exception) {
+            return '0.0.0-alpha';
+        }
+    }
 
     /**
      * Returns the packagist name of the current package.
      *
      * @return string
      */
-    abstract protected function getPackageName(): string;
+    abstract protected static function getPackageName(): string;
 
     /**
      * The name of the library to be used in the User-Agent header.
      *
      * @return string
      */
-    abstract protected function getSdkName(): string;
+    abstract protected static function getSdkName(): string;
 
     /**
      * Returns the Content-Type (MIME-Type) to be used when communication with the API.
      *
      * @return string
      */
-    abstract protected function getApiContentType(): string;
+    abstract protected static function getApiContentType(): string;
 }

src/Api/BaseQuery.php

@@ -205,19 +205,13 @@ public function setLimit(int $limit = \null)
      * Note that when ordering Entries by fields you must set the content_type URI query parameter to the ID of
      * the Content Type you want to filter by. Can be called multiple times to order by multiple values.
      *
-     * @param string|null $field
-     * @param bool        $reverse
+     * @param string $field
+     * @param bool   $reverse
      *
      * @return $this
      */
-    public function orderBy(string $field = \null, bool $reverse = \false)
+    public function orderBy(string $field, bool $reverse = \false)
     {
-        if (\null === $field) {
-            $this->orderConditions = [];
-
-            return $this;
-        }
-
         if ($reverse) {
             $field = '-'.$field;
         }