Support automatic forward-paging of entity collections

.editorconfig

@@ -0,0 +1,13 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+max_line_length = 120
+tab_width = 4
+
+[{*.ctp,*.engine,*.hphp,*.inc,*.install,*.module,*.php,*.php4,*.php5,*.phtml,*.profile,*.test,*.theme}]
+max_line_length = 80

.gitignore

@@ -3,3 +3,5 @@ vendor/
 build/
 
 .idea/
+
+.phpunit.result.cache

composer.json

@@ -18,7 +18,8 @@
         "guzzlehttp/psr7": "^1.6",
         "php-http/client-implementation": "^1.0",
         "psr/http-client": "^1.0",
-        "psr/http-message": "^1.0"
+        "psr/http-message": "^1.0",
+        "symfony/serializer": "^5.2"
     },
     "require-dev": {
         "php-http/mock-client": "^1.3",

src/Entity/Collection/CollectionRelLinkTrait.php

@@ -0,0 +1,64 @@
+<?php
+
+namespace Hussainweb\DrupalApi\Entity\Collection;
+
+use GuzzleHttp\Psr7\Uri;
+
+/**
+ * Trait for relationship links in collections.
+ *
+ * @see \Hussainweb\DrupalApi\Entity\Collection\EntityCollectionInterface
+ */
+trait CollectionRelLinkTrait
+{
+
+  /**
+   * @var \stdClass
+   */
+    protected $rawData;
+
+    public function getSelfLink()
+    {
+        return $this->getRelLink('self');
+    }
+
+    public function getFirstLink()
+    {
+        return $this->getRelLink('first');
+    }
+
+    public function getPreviousLink()
+    {
+        return $this->getRelLink('prev');
+    }
+
+    public function getLastLink()
+    {
+        return $this->getRelLink('last');
+    }
+
+    public function getNextLink()
+    {
+        return $this->getRelLink('next');
+    }
+
+    /**
+     * Get the related link.
+     *
+     * @param string $link_name
+     *   The name of the related link to retrieve.
+     *
+     * @return bool|\Psr\Http\Message\UriInterface
+     *   The related URL or FALSE if not present.
+     */
+    protected function getRelLink(string $link_name)
+    {
+        if (!isset($this->rawData->$link_name)) {
+            return false;
+        }
+
+        $uri = new Uri($this->rawData->$link_name);
+        $uri = $uri->withPath($uri->getPath() . '.json');
+        return $uri;
+    }
+}

src/Entity/Collection/EntityCollection.php

@@ -2,11 +2,14 @@
 
 namespace Hussainweb\DrupalApi\Entity\Collection;
 
-use GuzzleHttp\Psr7\Uri;
+use Psr\Http\Client\ClientInterface;
 use Psr\Http\Message\ResponseInterface;
+use Symfony\Component\Serializer\Encoder\JsonDecode;
+use Symfony\Component\Serializer\Encoder\JsonEncoder;
 
-abstract class EntityCollection implements \Iterator, \Countable
+abstract class EntityCollection implements EntityCollectionInterface, \Countable
 {
+    use CollectionRelLinkTrait;
 
     private $iteratorPosition = 0;
 
@@ -31,52 +34,22 @@ final public function __construct($data)
      */
     public static function fromResponse(ResponseInterface $response)
     {
-        return new static(json_decode((string) $response->getBody()));
-    }
-
-    public function getSelfLink()
-    {
-        return $this->getRelLink('self');
-    }
-
-    public function getFirstLink()
-    {
-        return $this->getRelLink('first');
-    }
-
-    public function getPreviousLink()
-    {
-        return $this->getRelLink('prev');
-    }
-
-    public function getNextLink()
-    {
-        return $this->getRelLink('next');
-    }
-
-    public function getLastLink()
-    {
-        return $this->getRelLink('last');
+        return new static((new JsonDecode())->decode((string) $response->getBody(), JsonEncoder::FORMAT));
     }
 
     /**
-     * Get the related link.
+     * Construct a paging entity collection from this collection.
      *
-     * @param string $link_name
-     *   The name of the related link to retrieve.
+     * @param \Psr\Http\Client\ClientInterface $client
+     *   The HTTP client used to fetch subsequent pages.
      *
-     * @return bool|\Psr\Http\Message\UriInterface
-     *   The related URL or FALSE if not present.
+     * @see \Hussainweb\DrupalApi\Client::getEntity
+     *
+     * @return \Hussainweb\DrupalApi\Entity\Collection\PagingEntityCollection
      */
-    protected function getRelLink($link_name)
+    public function toPagingEntityCollection(ClientInterface $client): PagingEntityCollection
     {
-        if (!isset($this->rawData->$link_name)) {
-            return false;
-        }
-
-        $uri = new Uri($this->rawData->$link_name);
-        $uri = $uri->withPath($uri->getPath() . '.json');
-        return $uri;
+        return new PagingEntityCollection($this->rawData, $client, $this->getListItemClass());
     }
 
     /**
@@ -115,7 +88,7 @@ public function key()
     /**
      * {@inheritdoc}
      */
-    public function valid()
+    public function valid(): bool
     {
         return isset($this->rawData->list[$this->iteratorPosition]);
     }

src/Entity/Collection/EntityCollectionInterface.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace Hussainweb\DrupalApi\Entity\Collection;
+
+/**
+ * Interface representing a collection of entities loaded from drupal.org.
+ */
+interface EntityCollectionInterface extends \Iterator
+{
+
+    /**
+     * @return bool|\GuzzleHttp\Psr7\Uri
+     */
+    public function getSelfLink();
+
+    /**
+     * @return bool|\GuzzleHttp\Psr7\Uri
+     */
+    public function getFirstLink();
+
+    /**
+     * @return bool|\GuzzleHttp\Psr7\Uri
+     */
+    public function getPreviousLink();
+
+    /**
+     * @return bool|\GuzzleHttp\Psr7\Uri
+     */
+    public function getNextLink();
+
+    /**
+     * @return bool|\GuzzleHttp\Psr7\Uri
+     */
+    public function getLastLink();
+
+    /**
+     * {@inheritdoc}
+     */
+    public function current();
+
+    /**
+     * {@inheritdoc}
+     */
+    public function next();
+
+    /**
+     * {@inheritdoc}
+     */
+    public function key();
+
+    /**
+     * {@inheritdoc}
+     */
+    public function valid(): bool;
+
+    /**
+     * {@inheritdoc}
+     *
+     * If a collection does not support rewinding, implement this method with an
+     * empty body.
+     */
+    public function rewind();
+}

src/Entity/Collection/PagingEntityCollection.php

@@ -0,0 +1,125 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hussainweb\DrupalApi\Entity\Collection;
+
+use Hussainweb\DrupalApi\Request\Request;
+use Psr\Http\Client\ClientInterface;
+use Psr\Http\Message\ResponseInterface;
+use Symfony\Component\Serializer\Encoder\JsonDecode;
+use Symfony\Component\Serializer\Encoder\JsonEncoder;
+
+/**
+ * A collection of entities loaded from drupal.org that supports automatic
+ * forward-paging.
+ */
+class PagingEntityCollection implements EntityCollectionInterface
+{
+    use CollectionRelLinkTrait;
+
+    private $iteratorPosition = 0;
+
+    /**
+     * @var \stdClass
+     */
+    protected $rawData;
+
+    /**
+     * @var \Psr\Http\Client\ClientInterface
+     */
+    private $client;
+
+    /**
+     * @var string
+     */
+    private $listItemClass;
+
+    /**
+     * PagingEntityCollection constructor.
+     *
+     * @param \stdClass $data
+     *   The data with the first page response.
+     * @param \Psr\Http\Client\ClientInterface $client
+     *   The HTTP client used to fetch subsequent pages.
+     * @param string $listItemClass
+     *   The list item class FQCN to deserialize entities into.
+     */
+    final public function __construct(
+        \stdClass $data,
+        ClientInterface $client,
+        string $listItemClass
+    ) {
+        $this->rawData = $data;
+        $this->client = $client;
+        $this->listItemClass = $listItemClass;
+    }
+
+    /**
+     * Construct the object from a HTTP Response.
+     *
+     * @param \Psr\Http\Message\ResponseInterface $response
+     *   Response object to parse.
+     * @param \Psr\Http\Client\ClientInterface $client
+     *   The HTTP client used to fetch subsequent pages.
+     * @param string $listItemClass
+     *   The list item class FQCN to deserialize entities into.
+     *
+     * @return static
+     *   The EntityCollection object for the response.
+     */
+    public static function fromResponse(
+        ResponseInterface $response,
+        ClientInterface $client,
+        string $listItemClass
+    ): self {
+        return new static(
+            (new JsonDecode())->decode(
+                (string) $response->getBody(),
+                JsonEncoder::FORMAT
+            ),
+            $client,
+            $listItemClass
+        );
+    }
+
+    public function current()
+    {
+        return new $this->listItemClass(
+            $this->rawData->list[$this->iteratorPosition]
+        );
+    }
+
+    public function next()
+    {
+        ++$this->iteratorPosition;
+    }
+
+    public function key()
+    {
+        return $this->iteratorPosition;
+    }
+
+    public function valid(): bool
+    {
+        $valid = isset($this->rawData->list[$this->iteratorPosition]);
+        if (!$valid && $this->getNextLink()) {
+            $request = new Request((string) $this->getNextLink());
+            $response = $this->client->sendRequest($request);
+            $this->rawData = (new JsonDecode())->decode(
+                (string) $response->getBody(),
+                JsonEncoder::FORMAT
+            );
+            $this->iteratorPosition = 0;
+            $valid = true;
+        }
+
+        return $valid;
+    }
+
+    public function rewind()
+    {
+        // We do not allow rewinding as that could force us to go back and reload a
+        // previously loaded page.
+    }
+}