Merge php-opencloud/common

# Conflicts:
#	.travis.yml
#	composer.json
#	tests/integration/Utils.php
#	tests/unit/Fixtures/ComputeV2Api.php
#	tests/unit/Fixtures/IdentityV2Api.php
#	tests/unit/Fixtures/IdentityV3Api.php

Author: haphan

composer.json

@@ -9,13 +9,16 @@
     ],
     "autoload": {
         "psr-4": {
-            "OpenStack\\": "src/"
+            "OpenStack\\": "src/",
+            "OpenCloud\\": "src/"
         }
     },
     "autoload-dev": {
         "psr-4": {
             "OpenStack\\Test\\": "tests/unit/",
-            "OpenStack\\Integration\\": "tests/integration/"
+            "OpenStack\\Integration\\": "tests/integration/",
+            "OpenCloud\\Test\\": "tests/unit/",
+            "OpenCloud\\Integration\\": "tests/integration/"
         }
     },
     "repositories": [
@@ -25,7 +28,9 @@
         }
     ],
     "require": {
-        "php-opencloud/common": "^1.0.5"
+        "php": "~7.0",
+        "guzzlehttp/guzzle": "~6.1",
+        "justinrainbow/json-schema": "~1.3"
     },
     "require-dev": {
         "phpunit/phpunit": "~4.0",

src/Common/Api/AbstractApi.php

@@ -0,0 +1,33 @@
+<?php declare (strict_types = 1);
+
+namespace OpenCloud\Common\Api;
+
+abstract class AbstractApi implements ApiInterface
+{
+    protected $params;
+
+    protected function isRequired(array $param): array
+    {
+        return array_merge($param, ['required' => true]);
+    }
+
+    protected function notRequired(array $param): array
+    {
+        return array_merge($param, ['required' => false]);
+    }
+
+    protected function query(array $param): array
+    {
+        return array_merge($param, ['location' => AbstractParams::QUERY]);
+    }
+
+    protected function url(array $param): array
+    {
+        return array_merge($param, ['location' => AbstractParams::URL]);
+    }
+
+    public function documented(array $param): array
+    {
+        return array_merge($param, ['required' => true]);
+    }
+}

src/Common/Api/AbstractParams.php

@@ -0,0 +1,100 @@
+<?php declare (strict_types=1);
+
+namespace OpenCloud\Common\Api;
+
+abstract class AbstractParams
+{
+    // locations
+    const QUERY = 'query';
+    const HEADER = 'header';
+    const URL = 'url';
+    const JSON = 'json';
+    const RAW = 'raw';
+
+    // types
+    const STRING_TYPE = "string";
+    const BOOL_TYPE = "boolean";
+    const BOOLEAN_TYPE = self::BOOL_TYPE;
+    const OBJECT_TYPE = "object";
+    const ARRAY_TYPE = "array";
+    const NULL_TYPE = "NULL";
+    const INT_TYPE = 'integer';
+    const INTEGER_TYPE = self::INT_TYPE;
+
+    public static function isSupportedLocation(string $val): bool
+    {
+        return in_array($val, [self::QUERY, self::HEADER, self::URL, self::JSON, self::RAW]);
+    }
+
+    public function limit(): array
+    {
+        return [
+            'type'        => self::INT_TYPE,
+            'location'    => 'query',
+            'description' => <<<DESC
+This will limit the total amount of elements returned in a list up to the number specified. For example, specifying a
+limit of 10 will return 10 elements, regardless of the actual count.
+DESC
+        ];
+    }
+
+    public function marker(): array
+    {
+        return [
+            'type'        => 'string',
+            'location'    => 'query',
+            'description' => <<<DESC
+Specifying a marker will begin the list from the value specified. Elements will have a particular attribute that
+identifies them, such as a name or ID. The marker value will search for an element whose identifying attribute matches
+the marker value, and begin the list from there.
+DESC
+        ];
+    }
+
+    public function id(string $type): array
+    {
+        return [
+            'description' => sprintf("The unique ID, or identifier, for the %s", $type),
+            'type'        => self::STRING_TYPE,
+            'location'    => self::JSON,
+        ];
+    }
+
+    public function idPath(): array
+    {
+        return [
+            'type'        => self::STRING_TYPE,
+            'location'    => self::URL,
+            'description' => 'The unique ID of the resource',
+        ];
+    }
+
+    public function name(string $resource): array
+    {
+        return [
+            'description' => sprintf("The name of the %s", $resource),
+            'type'        => self::STRING_TYPE,
+            'location'    => self::JSON,
+        ];
+    }
+
+
+    public function sortDir(): array
+    {
+        return [
+            'type'        => self::STRING_TYPE,
+            'location'    => self::QUERY,
+            'description' => "Sorts by one or more sets of attribute and sort direction combinations.",
+            'enum'        => ['asc', 'desc']
+        ];
+    }
+
+    public function sortKey(): array
+    {
+        return [
+            'type'     => self::STRING_TYPE,
+            'location' => self::QUERY,
+            'description' => "Sorts by one or more sets of attribute and sort direction combinations.",
+        ];
+    }
+}

src/Common/Api/ApiInterface.php

@@ -0,0 +1,20 @@
+<?php declare (strict_types=1);
+
+namespace OpenCloud\Common\Api;
+
+/**
+ * All classes which implement this interface are a data representation of a remote OpenCloud API.
+ * They do not execute functionality, but instead return data for each API operation for other parts
+ * of the SDK to use. Usually, the data is injected into {@see OpenCloud\Common\Api\Operation} objects.
+ * The operation is then serialized into a {@see GuzzleHttp\Message\Request} and sent to the API.
+ *
+ * The reason for storing all the API-specific data is to decouple service information from client
+ * HTTP functionality. Too often it is mixed all across different layers, leading to duplication and
+ * no separation of concerns. The choice was made for storage in PHP classes, rather than YAML or JSON
+ * syntax, due to performance concerns.
+ *
+ * @package OpenCloud\Common\Api
+ */
+interface ApiInterface
+{
+}

src/Common/Api/Operation.php

@@ -0,0 +1,134 @@
+<?php declare (strict_types=1);
+
+namespace OpenCloud\Common\Api;
+
+/**
+ * This class represents an OpenCloud API operation. It encapsulates most aspects of the REST operation: its HTTP
+ * method, the URL path, its top-level JSON key, and all of its {@see Parameter} objects.
+ *
+ * An operation not only represents a remote operation, but it also provides the mechanism for executing it
+ * over HTTP. To do this, it uses a {@see ClientInterface} that allows a {@see GuzzleHttp\Message\Request}
+ * to be created from the user values provided. Once this request is assembled, it is then sent to the
+ * remote API and the response is returned to whoever first invoked the Operation class.
+ *
+ * @package OpenCloud\Common\Api
+ */
+class Operation
+{
+    /** @var string The HTTP method */
+    private $method;
+
+    /** @var string The URL path */
+    private $path;
+
+    /** @var string The top-level JSON key */
+    private $jsonKey;
+
+    /** @var []Parameter The parameters of this operation */
+    private $params;
+
+    /**
+     * @param array $definition The data definition (in array form) that will populate this
+     *                          operation. Usually this is retrieved from an {@see ApiInterface}
+     *                          object method.
+     */
+    public function __construct(array $definition)
+    {
+        $this->method = $definition['method'];
+        $this->path = $definition['path'];
+
+        if (isset($definition['jsonKey'])) {
+            $this->jsonKey = $definition['jsonKey'];
+        }
+
+        $this->params = self::toParamArray($definition['params']);
+    }
+
+    /**
+     * @return string
+     */
+    public function getPath(): string
+    {
+        return $this->path;
+    }
+
+    /**
+     * @return string
+     */
+    public function getMethod(): string
+    {
+        return $this->method;
+    }
+
+    /**
+     * Indicates whether this operation supports a parameter.
+     *
+     * @param $key The name of a parameter
+     *
+     * @return bool
+     */
+    public function hasParam(string $key): bool
+    {
+        return isset($this->params[$key]);
+    }
+
+    /**
+     * @param $name
+     *
+     * @return Parameter
+     */
+    public function getParam(string $name)
+    {
+        return isset($this->params[$name]) ? $this->params[$name] : null;
+    }
+
+    /**
+     * @return string
+     */
+    public function getJsonKey(): string
+    {
+        return $this->jsonKey ?: '';
+    }
+
+    /**
+     * A convenience method that will take a generic array of data and convert it into an array of
+     * {@see Parameter} objects.
+     *
+     * @param array $data A generic data array
+     *
+     * @return array
+     */
+    public static function toParamArray(array $data): array
+    {
+        $params = [];
+
+        foreach ($data as $name => $param) {
+            $params[$name] = new Parameter($param + ['name' => $name]);
+        }
+
+        return $params;
+    }
+
+    /**
+     * This method will validate all of the user-provided values and throw an exception if any
+     * failures are detected. This is useful for basic sanity-checking before a request is
+     * serialized and sent to the API.
+     *
+     * @param array $userValues The user-defined values
+     *
+     * @return bool       TRUE if validation passes
+     * @throws \Exception If validate fails
+     */
+    public function validate(array $userValues): bool
+    {
+        foreach ($this->params as $paramName => $param) {
+            if (array_key_exists($paramName, $userValues)) {
+                $param->validate($userValues[$paramName]);
+            } elseif ($param->isRequired()) {
+                throw new \Exception(sprintf('"%s" is a required option, but it was not provided', $paramName));
+            }
+        }
+
+        return true;
+    }
+}

src/Common/Api/OperatorInterface.php

@@ -0,0 +1,64 @@
+<?php declare (strict_types=1);
+
+namespace OpenCloud\Common\Api;
+
+use GuzzleHttp\ClientInterface;
+use GuzzleHttp\Promise\PromiseInterface;
+use OpenCloud\Common\Resource\ResourceInterface;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * An operator is any resource or service that can invoke and send REST operations. In other words, it
+ * is any class that can send requests and receive responses with a HTTP client. To do this
+ * it needs two things: a {@see ClientInterface} for handling HTTP transactions and an {@see ApiInterface}
+ * for handling how operations are created.
+ *
+ * @package OpenCloud\Common\Api
+ */
+interface OperatorInterface
+{
+    /**
+     * @param ClientInterface $client The HTTP client responsible for handling HTTP transactions
+     * @param ApiInterface    $api    The data API class that dictates how REST operations are structured
+     */
+    public function __construct(ClientInterface $client, ApiInterface $api);
+
+    /**
+     * A convenience method that assembles an operation and sends it to the remote API
+     *
+     * @param array $definition The data that dictates how the operation works
+     * @param array $userValues The user-defined values that populate the request
+     *
+     * @return \Psr\Http\Message\ResponseInterface
+     */
+    public function execute(array $definition, array $userValues = []): ResponseInterface;
+
+    /**
+     * A convenience method that assembles an operation and asynchronously sends it to the remote API
+     *
+     * @param array $definition The data that dictates how the operation works
+     * @param array $userValues The user-defined values that populate the request
+     *
+     * @return \GuzzleHttp\Promise\PromiseInterface
+     */
+    public function executeAsync(array $definition, array $userValues = []): PromiseInterface;
+
+    /**
+     * Retrieves a populated Operation according to the definition and values provided. A
+     * HTTP client is also injected into the object to allow it to communicate with the remote API.
+     *
+     * @param array $definition The data that dictates how the operation works
+     *
+     * @return Operation
+     */
+    public function getOperation(array $definition): Operation;
+
+    /**
+     * @param string $class The name of the model class.
+     * @param mixed  $data Either a {@see ResponseInterface} or data array that will populate the newly
+     *                     created model class.
+     *
+     * @return \OpenCloud\Common\Resource\ResourceInterface
+     */
+    public function model(string $class, $data = null): ResourceInterface;
+}