Implementation of pagination for Apigee X Teams-3x

src/Api/ApigeeX/Controller/AppGroupController.php

@@ -22,7 +22,6 @@
 use Apigee\Edge\Api\ApigeeX\Serializer\AppGroupSerializer;
 use Apigee\Edge\Api\Management\Controller\AttributesAwareEntityControllerTrait;
 use Apigee\Edge\ClientInterface;
-use Apigee\Edge\Controller\EntityController;
 use Apigee\Edge\Controller\EntityCreateOperationControllerTrait;
 use Apigee\Edge\Controller\EntityCrudOperationsControllerTrait;
 use Apigee\Edge\Controller\EntityListingControllerTrait;
@@ -34,11 +33,13 @@
 /**
  * Class AppGroupController.
  */
-class AppGroupController extends EntityController implements AppGroupControllerInterface
+class AppGroupController extends PaginatedEntityController implements AppGroupControllerInterface
 {
     use AttributesAwareEntityControllerTrait;
     use EntityCrudOperationsControllerTrait;
     use EntityListingControllerTrait;
+    use PaginatedEntityListingControllerTrait;
+    use PaginationHelperTrait;
     use StatusAwareEntityControllerTrait;
     use EntityCreateOperationControllerTrait;
 
@@ -56,25 +57,6 @@ public function __construct(string $organization, ClientInterface $client, ?Enti
         parent::__construct($organization, $client, $entitySerializer);
     }
 
-    /**
-     * {@inheritdoc}
-     */
-    public function getEntities(): array
-    {
-        $uri = $this->getBaseEndpointUri();
-        $response = $this->client->get($uri);
-        $responseArray = $this->responseToArray($response);
-        // Ignore entity type key from response.
-        $responseArray = reset($responseArray);
-
-        // Appgroup can be empty.
-        if (empty($responseArray)) {
-            return [];
-        }
-
-        return $this->responseArrayToArrayOfEntities($responseArray);
-    }
-
     /**
      * {@inheritdoc}
      */

src/Api/ApigeeX/Controller/AppGroupControllerInterface.php

@@ -25,11 +25,14 @@
 
 /**
  * Interface AppGroupControllerInterface.
+ *
+ * @see https://cloud.google.com/apigee/docs/reference/apis/apigee/rest/v1/organizations.appgroups
  */
 interface AppGroupControllerInterface extends
     AttributesAwareEntityControllerInterface,
     EntityControllerInterface,
     EntityCrudOperationsControllerInterface,
+    PaginatedEntityListingControllerInterface,
     StatusAwareEntityControllerInterface
 {
 }

src/Api/ApigeeX/Controller/PaginatedEntityController.php

@@ -0,0 +1,65 @@
+<?php
+
+/*
+ * Copyright 2023 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\ApigeeX\Controller;
+
+use Apigee\Edge\Api\Management\Controller\OrganizationController;
+use Apigee\Edge\Api\Management\Controller\OrganizationControllerInterface;
+use Apigee\Edge\ClientInterface;
+use Apigee\Edge\Controller\EntityController;
+use Apigee\Edge\Controller\OrganizationControllerAwareTrait;
+use Apigee\Edge\Serializer\EntitySerializerInterface;
+
+/**
+ * Class PaginatedEntityController.
+ *
+ * @see \Apigee\Edge\Api\ApigeeX\Controller\PaginatedEntityControllerInterface
+ */
+abstract class PaginatedEntityController extends EntityController implements PaginatedEntityControllerInterface
+{
+    use OrganizationControllerAwareTrait;
+
+    /** @var \Apigee\Edge\Api\Management\Controller\OrganizationControllerInterface */
+    protected $organizationController;
+
+    /**
+     * PaginatedEntityController constructor.
+     *
+     * @param string $organization
+     * @param \Apigee\Edge\ClientInterface $client
+     * @param \Apigee\Edge\Serializer\EntitySerializerInterface|null $entitySerializer
+     * @param OrganizationControllerInterface|null $organizationController
+     */
+    public function __construct(
+        string $organization,
+        ClientInterface $client,
+        ?EntitySerializerInterface $entitySerializer = null,
+        OrganizationControllerInterface $organizationController = null
+    ) {
+        parent::__construct($organization, $client, $entitySerializer);
+        $this->organizationController = $organizationController ?: new OrganizationController($client);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function getOrganizationController(): OrganizationControllerInterface
+    {
+        return $this->organizationController;
+    }
+}

src/Api/ApigeeX/Controller/PaginatedEntityControllerInterface.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * Copyright 2023 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\ApigeeX\Controller;
+
+use Apigee\Edge\Api\ApigeeX\Structure\PagerInterface;
+
+/**
+ * Interface PaginatedEntityControllerInterface.
+ *
+ * For those controllers that contains as least one method that communicates
+ * with an endpoint which supports pagination.
+ */
+interface PaginatedEntityControllerInterface
+{
+    /**
+     * Creates a pager.
+     *
+     * @param int $limit
+     *   Number of items to return. Default is 0 which means load as much as
+     *   supported. (Different endpoints have different limits, ex.:
+     *   100 for AppGroup apps.)
+     * @param string|null $pageToken
+     *   First item in the list, if it is not set then Apigee Edge decides the
+     *   first item.
+     *
+     * @return \Apigee\Edge\Api\ApigeeX\Structure\PagerInterface
+     *   The pager object.
+     */
+    public function createPager(int $limit = 0, ?string $pageToken = null): PagerInterface;
+}

src/Api/ApigeeX/Controller/PaginatedEntityListingControllerInterface.php

@@ -0,0 +1,50 @@
+<?php
+
+/*
+ * Copyright 2023 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\ApigeeX\Controller;
+
+use Apigee\Edge\Api\ApigeeX\Structure\PagerInterface;
+
+/**
+ * Interface PaginatedEntityListingControllerInterface.
+ *
+ * For those entities that can be listed as objects and pagination is supported
+ * on their endpoint.
+ */
+interface PaginatedEntityListingControllerInterface extends PaginatedEntityControllerInterface
+{
+    /**
+     * Returns list of entities fro Apigee Edge. The returned number of entities
+     * can be limited, if you do not provide a limit then all entities are
+     * returned.
+     *
+     * On pagination enabled endpoints Apigee X only
+     * returns certain number of entities in one API call so we have to collect
+     * all entities by sending multiple API calls to Apigee X synchronously.
+     * If you do not actually need _all_ entities of a type then always set
+     * a limit to reduce memory usage and increase speed.
+     *
+     * @param \Apigee\Edge\Api\ApigeeX\Structure\PagerInterface|null $pager
+     *   Pager.
+     * @param string $key_provider
+     *   Getter method on the entity that should provide a unique array key.
+     *
+     * @return \Apigee\Edge\Entity\EntityInterface[]
+     */
+    public function getEntities(PagerInterface $pager = null, string $key_provider = 'id'): array;
+}

src/Api/ApigeeX/Controller/PaginatedEntityListingControllerTrait.php

@@ -0,0 +1,44 @@
+<?php
+
+/*
+ * Copyright 2023 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\ApigeeX\Controller;
+
+use Apigee\Edge\Api\ApigeeX\Structure\PagerInterface;
+
+/**
+ * Trait PaginatedEntityListingControllerTrait.
+ *
+ * @see \Apigee\Edge\Api\ApigeeX\Controller\PaginatedEntityListingControllerInterface
+ */
+trait PaginatedEntityListingControllerTrait
+{
+    /**
+     * {@inheritdoc}
+     *
+     * @return \Apigee\Edge\Entity\EntityInterface[]
+     */
+    public function getEntities(PagerInterface $pager = null, string $key_provider = 'id'): array
+    {
+        return $this->listEntities($pager, [], $key_provider);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    abstract protected function listEntities(PagerInterface $pager = null, array $query_params = [], string $key_provider = 'id'): array;
+}