Refactored Management API tests and various improvements (#25)

Highlights:

* Block installation of the latest vimeo/psalm.

vimeo/psalm#1016

* Introducing new API and HTTP clients for testing.

* Updated Management API tests to use the new test API- and HTTP clients.

* Explode entity CRUD operation trait and interface to smaller components
per operation.

* Added missing organization property to Company entity.

* Added more details about the actual behavior of the Company membership API.

* Introducing new base class and interface for developer- and company
entity.

* Refactored basic and Management API tests.

* Bump minimum version of php-http/client-common to >=1.8.1.

1.8.0 contains a regression bug:
php-http/client-common#112

* Add new required patch to php-http/client-common.

php-http/client-common#113

* Disable process timeout to prevent failing test runs caused by
PHPUnit executed via a Composer command.

* Removed useless PHP nightly builds from testing matrix.

* Added test to getDeveloperByApp.

* Introducing new base exception interface for our client.

* Introducing API client specific RuntimeException class.

* Throw more meaningful exceptions when an entity property has an
incorrect value.

* Be more type-strict by replacing array arguments on data object's
setters with type strict variable-length arguments.

* Fix implementation of getProperties(). (BC breaking change.)

Author: mxr576

.travis.yml

@@ -9,12 +9,9 @@ addons:
 php:
   - 7.1
   - 7.2
-  - nightly
 
 matrix:
   fast_finish: true
-  allow_failures:
-    - php: nightly
 
 cache:
   directories:
@@ -27,6 +24,9 @@ notifications:
 env:
   global:
     - COMPOSER_OPTIONS="--no-suggest --no-interaction"
+    # To prevent failing test runs caused by
+    # "The process "phpunit" exceeded the timeout of 300 seconds.
+    - COMPOSER_PROCESS_TIMEOUT=0
   matrix:
     - DEPENDENCIES="--prefer-lowest"
     - DEPENDENCIES=""

README.md

@@ -134,6 +134,7 @@ Testing of new changes does not require Apigee Edge connection. By default, unit
 tests with a real Apigee Edge instance you have to specify the following environment variables (without brackets):
 
 ```shell
+APIGEE_EDGE_PHP_CLIENT_API_CLIENT=\Apigee\Edge\Tests\Test\FileSystemMockClient
 APIGEE_EDGE_PHP_CLIENT_HTTP_CLIENT=\Http\Adapter\Guzzle6\Client
 APIGEE_EDGE_PHP_CLIENT_BASIC_AUTH_USER=[[email protected]]
 APIGEE_EDGE_PHP_CLIENT_BASIC_AUTH_PASSWORD=[PASSWORD]

composer.json

@@ -19,7 +19,7 @@
         "fightbulc/moment": "^1.26",
         "league/period": "^3.4",
         "php-http/cache-plugin": "^1.4",
-        "php-http/client-common": "^1.6",
+        "php-http/client-common": "^1.8.1",
         "php-http/client-implementation": "^1.0",
         "php-http/discovery": "^1.0",
         "php-http/httplug": "^1.0",
@@ -46,13 +46,14 @@
         "phpmetrics/phpmetrics": "^2.3",
         "phpunit/phpunit": "^6.4.0",
         "sebastian/comparator": "^2.1",
+        "symfony/cache": "~3.4|~4.0",
         "vimeo/psalm": "^2.0.0"
     },
     "conflict": {
         "guzzlehttp/guzzle": "<6.1.0",
         "guzzlehttp/psr7": "<1.4.1",
         "phpdocumentor/type-resolver": "<0.2.1",
-        "php-http/client-common": ">1.7"
+        "vimeo/psalm": ">2.0.13"
     },
     "autoload": {
         "psr-4": {
@@ -86,7 +87,7 @@
         },
         "patches": {
             "php-http/client-common": {
-                "Only add path prefix if the path does not contain it already #103": "https://patch-diff.githubusercontent.com/raw/php-http/client-common/pull/103.diff"
+                "Path prefix must be present #113": "https://github.com/php-http/client-common/pull/113.diff"
             }
         }
     }

phpunit.xml.dist

@@ -24,7 +24,7 @@
          printerClass="LimeDeck\Testing\Printer"
          verbose="true">
     <testsuites>
-        <testsuite name="All Apigee Edge PHP SDK Tests">
+        <testsuite name="All Apigee Edge PHP API Client Tests">
             <directory>tests/</directory>
         </testsuite>
     </testsuites>

src/Api/Management/Controller/AppControllerInterface.php

@@ -31,12 +31,24 @@
 interface AppControllerInterface extends PaginatedEntityControllerInterface, EntityControllerInterface
 {
     /**
-     * String that should be sent to the API to change the status of a credential to approved.
+     * Type of a developer app.
+     */
+    public const APP_TYPE_DEVELOPER = 'developer';
+
+    /**
+     * Type of a company app.
+     */
+    public const APP_TYPE_COMPANY = 'company';
+
+    /**
+     * String that should be sent to the API to change the status of a
+     * credential to approved.
      */
     public const STATUS_APPROVE = 'approve';
 
     /**
-     * String that should be sent to the API to change the status of a credential to revoked.
+     * String that should be sent to the API to change the status of a
+     * credential to revoked.
      */
     public const STATUS_REVOKE = 'revoke';
 

src/Api/Management/Controller/CompanyMembersControllerInterface.php

@@ -38,8 +38,11 @@ public function getMembers(): CompanyMembership;
     /**
      * Set (add/update/remove) members of a company.
      *
-     * You have to pass the complete list of developers otherwise you remove previously added developers from
-     * a company.
+     * Warning! If you pass en empty membership object you remove all developers
+     * from the company.
+     *
+     * The return array only contains the changes, it does not contain all
+     * members. Use getMembers() to retrieve it.
      *
      * @param \Apigee\Edge\Api\Management\Structure\CompanyMembership $members
      *   Array of developers with their optional roles in the company.

src/Api/Management/Controller/DeveloperController.php

@@ -99,11 +99,7 @@ public function getEntities(
     }
 
     /**
-     * Returns the API endpoint that the controller communicates with.
-     *
-     * In case of an entity that belongs to an organisation it should return organization/[orgName]/[endpoint].
-     *
-     * @return UriInterface
+     * @inheritdoc
      */
     protected function getBaseEndpointUri(): UriInterface
     {

src/Api/Management/Entity/ApiProduct.php

@@ -95,7 +95,7 @@ public function getProxies(): array
     /**
      * @inheritdoc
      */
-    public function setProxies(array $proxies): void
+    public function setProxies(string ...$proxies): void
     {
         $this->proxies = $proxies;
     }
@@ -175,7 +175,7 @@ public function getApiResources(): array
     /**
      * @inheritdoc
      */
-    public function setApiResources(array $apiResources): void
+    public function setApiResources(string ...$apiResources): void
     {
         $this->apiResources = $apiResources;
     }

src/Api/Management/Entity/ApiProductInterface.php

@@ -58,9 +58,9 @@ interface ApiProductInterface extends
     public function getProxies(): array;
 
     /**
-     * @param string[] $proxy
+     * @param string ...$proxy
      */
-    public function setProxies(array $proxy): void;
+    public function setProxies(string ...$proxy): void;
 
     /**
      * @return string|null
@@ -108,7 +108,7 @@ public function setApprovalType(string $approvalType): void;
     public function getApiResources(): array;
 
     /**
-     * @param string[] $apiResources
+     * @param string ...$apiResources
      */
-    public function setApiResources(array $apiResources): void;
+    public function setApiResources(string ...$apiResources): void;
 }

src/Api/Management/Entity/App.php

@@ -186,31 +186,32 @@ public function getCredentials(): array
     }
 
     /**
-     * Set credentials from an Edge API response.
+     * Set credentials from an Apigee Edge API response.
      *
      * Credentials, included in app, can not be changed by modifying them on the entity level.
      *
-     * @param \Apigee\Edge\Api\Management\Entity\AppCredentialInterface[] $credentials
+     * @param \Apigee\Edge\Api\Management\Entity\AppCredentialInterface ...$credentials
      *
      * @internal
      */
-    public function setCredentials(array $credentials): void
+    public function setCredentials(AppCredentialInterface ...$credentials): void
     {
         $this->credentials = $credentials;
     }
 
     /**
      * Set OAuth scopes from an Edge API response.
      *
-     * Scopes of an app should not be changed on the entity level. You should modify them by using the app credential
+     * Scopes of an app should not be changed on the entity level.
+     * You should modify them by using the app credential
      * controllers.
      *
-     * @param string[] $scopes
+     * @param string ...$scopes
      *
      * @internal
      */
-    public function setScopes(array $scopes): void
+    public function setScopes(string ...$scopes): void
     {
-        $this->privateSetScopes($scopes);
+        $this->privateSetScopes(...$scopes);
     }
 }

src/Api/Management/Entity/AppCredential.php

@@ -23,6 +23,7 @@
 use Apigee\Edge\Entity\Property\ScopesPropertyAwareTrait;
 use Apigee\Edge\Entity\Property\StatusPropertyAwareTrait;
 use Apigee\Edge\Structure\AttributesProperty;
+use Apigee\Edge\Structure\CredentialProductInterface;
 
 /**
  * Class AppCredential.
@@ -92,11 +93,11 @@ public function getApiProducts(): array
      *
      * Included API products in an app credential can not be changed by modifying this property's value.
      *
-     * @param \Apigee\Edge\Structure\CredentialProductInterface[] $apiProducts
+     * @param \Apigee\Edge\Structure\CredentialProductInterface ...$apiProducts
      *
      * @internal
      */
-    public function setApiProducts(array $apiProducts): void
+    public function setApiProducts(CredentialProductInterface ...$apiProducts): void
     {
         $this->apiProducts = $apiProducts;
     }

src/Api/Management/Entity/AppOwner.php

@@ -0,0 +1,36 @@
+<?php
+
+/*
+ * Copyright 2018 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace Apigee\Edge\Api\Management\Entity;
+
+use Apigee\Edge\Entity\CommonEntityPropertiesAwareTrait;
+use Apigee\Edge\Entity\Entity;
+use Apigee\Edge\Entity\Property\AppsPropertyAwareTrait;
+use Apigee\Edge\Entity\Property\AttributesPropertyAwareTrait;
+use Apigee\Edge\Entity\Property\StatusPropertyAwareTrait;
+
+/**
+ * Base class for developer- and company entities.
+ */
+abstract class AppOwner extends Entity implements AppOwnerInterface
+{
+    use AttributesPropertyAwareTrait;
+    use AppsPropertyAwareTrait;
+    use CommonEntityPropertiesAwareTrait;
+    use StatusPropertyAwareTrait;
+}

src/Api/Management/Entity/AppOwnerInterface.php

@@ -0,0 +1,39 @@
+<?php
+
+/*
+ * Copyright 2018 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace Apigee\Edge\Api\Management\Entity;
+
+use Apigee\Edge\Entity\CommonEntityPropertiesInterface;
+use Apigee\Edge\Entity\EntityInterface;
+use Apigee\Edge\Entity\Property\AppsPropertyInterface;
+use Apigee\Edge\Entity\Property\AttributesPropertyInterface;
+use Apigee\Edge\Entity\Property\StatusPropertyInterface;
+
+/**
+ * Interface AppOwnerInterface.
+ */
+interface AppOwnerInterface extends EntityInterface,
+    AttributesPropertyInterface,
+    AppsPropertyInterface,
+    CommonEntityPropertiesInterface,
+    StatusPropertyInterface
+{
+    public const STATUS_ACTIVE = 'active';
+
+    public const STATUS_INACTIVE = 'inactive';
+}

src/Api/Management/Entity/Company.php

@@ -18,26 +18,28 @@
 
 namespace Apigee\Edge\Api\Management\Entity;
 
-use Apigee\Edge\Entity\CommonEntityPropertiesAwareTrait;
-use Apigee\Edge\Entity\Entity;
-use Apigee\Edge\Entity\Property\AppsPropertyAwareTrait;
-use Apigee\Edge\Entity\Property\AttributesPropertyAwareTrait;
 use Apigee\Edge\Entity\Property\DisplayNamePropertyAwareTrait;
 use Apigee\Edge\Entity\Property\NamePropertyAwareTrait;
-use Apigee\Edge\Entity\Property\StatusPropertyAwareTrait;
 use Apigee\Edge\Structure\AttributesProperty;
 
 /**
  * Describes a Company entity.
  */
-class Company extends Entity implements CompanyInterface
+class Company extends AppOwner implements CompanyInterface
 {
-    use AttributesPropertyAwareTrait;
-    use AppsPropertyAwareTrait;
-    use CommonEntityPropertiesAwareTrait;
     use DisplayNamePropertyAwareTrait;
     use NamePropertyAwareTrait;
-    use StatusPropertyAwareTrait;
+
+    /**
+     * It is organization and not organizationName in the API response.
+     *
+     * This is the reason why it does not implement
+     * OrganizationNamePropertyInterface. We also id not created a name
+     * converter just to hide this small inconsistency.
+     *
+     * @var string|null
+     */
+    protected $organization;
 
     /**
      * Company constructor.
@@ -49,4 +51,20 @@ public function __construct(array $values = [])
         $this->attributes = new AttributesProperty();
         parent::__construct($values);
     }
+
+    /**
+     * @inheritdoc
+     */
+    public function setOrganization(string $organization): void
+    {
+        $this->organization = $organization;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getOrganization(): ?string
+    {
+        return $this->organization;
+    }
 }