Improve paginated response

.gitignore

@@ -9,8 +9,5 @@
 ### PHPUnit
 /.phpunit.result.cache
 
-### Documentation
-/docs
-
 ### Local test
-/test*.php
+/test*.php

CHANGELOG.md

@@ -6,6 +6,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased v2.x]
 
+### Added
+
+- Documentation on paginated responses
+- Throw custom exception is client is missing
+
+### Changed
+
+- Rework paginated responses
+
+### Deprecated
+
+- `\MacFJA\RediSearch\Redis\Response\AggregateResponseItem::getValue` (use `\MacFJA\RediSearch\Redis\Response\AggregateResponseItem::getFieldValue` instead)
+
 ## [2.1.2]
 
 ### Fixed

docs/BuildQuery.md

@@ -0,0 +1,27 @@
+# Building a Query
+
+To help create RediSearch, the library offer a builder.
+
+It all start with the class `\MacFJA\RediSearch\Query\Builder`. From there you can add groups and query elements.
+
+---
+
+For example, for search all people named `John`, and preferably with the last name `Doe` that work as an accountant in the 10 km around Washington DC, and the resume contain text `cake` the request will be:
+```php
+use MacFJA\RediSearch\Query\Builder;
+use MacFJA\RediSearch\Query\Builder\GeoFacet;
+use MacFJA\RediSearch\Query\Builder\TextFacet;
+use MacFJA\RediSearch\Query\Builder\Optional;
+use MacFJA\RediSearch\Redis\Command\SearchCommand\GeoFilterOption;
+
+$queryBuilder = new Builder();
+$query = $queryBuilder
+    ->addTextFacet('firstname', 'John') // people named `John`
+    ->addElement(new Optional(new TextFacet(['lastname'], 'Doe'))) // preferably with the last name `Doe`
+    ->addTextFacet('job', 'accountant') // work as an accountant
+    ->addGeoFacet('address', -77.0365427, 38.8950368, 10, GeoFilterOption::UNIT_KILOMETERS) // in the 10 km around Washington DC
+    ->addString('cake') // the resume contain text `cake`
+    ->render();
+
+// @firstname:John ~@lastname:Doe @job:accountant @address:[-77.0365427 38.8950368 10 km] cake
+```

docs/UsingResult.md

@@ -0,0 +1,70 @@
+# Using result
+
+As you can set an offset and limit on `FT.SEARCH` and `FT.AGGREGATE`, they are paginated commands.
+The result of those commands is a page, that can contain one or more document.
+
+---
+
+So in this library, the result of `\MacFJA\RediSearch\Redis\Command\Search` and `\MacFJA\RediSearch\Redis\Command\Aggregate` is also a paginated object:
+either a `\MacFJA\RediSearch\Redis\Response\PaginatedResponse` (for Search and Aggregate) or a `\MacFJA\RediSearch\Redis\Response\CursorResponse` (for Aggregate)
+
+The 2 classes are representing a page.
+
+Both `\MacFJA\RediSearch\Redis\Response\PaginatedResponse` and `\MacFJA\RediSearch\Redis\Response\CursorResponse` can be read inside a `foreach` loop or with any iterator function.
+(As they implement the [`\Iterator` interface](https://www.php.net/manual/en/class.iterator.php))
+What you are iterating over, are the pages (not the documents inside the page).
+
+```php
+// If your RediSearch search have 15 results in total, but you set the pagination to 10 per page:
+/** @var PaginatedResponse $results */
+
+/** @var array<SearchResponseItem> $items */
+$items = $results->current();
+// $items is a list of 10 SearchResponseItem
+
+$results->next(); // To be able to class `->next()`, you need to call `->setClient()` first !
+
+/** @var array<SearchResponseItem> $items */
+$items = $results->current();
+// $items is a list of 5 SearchResponseItem
+```
+
+## Get all items on all pages
+
+```php
+/** @var \MacFJA\RediSearch\Redis\Client $client */
+/** @var \MacFJA\RediSearch\Redis\Command\Search $search */
+
+/** @var \MacFJA\RediSearch\Redis\Response\PaginatedResponse $results */
+$results = $client->execute($search);
+$results->setClient($client);
+
+$items = [];
+foreach ($results as $pageIndex => $pageContent) {
+    $items = array_merge($items, $pageContent);
+}
+/** @var \MacFJA\RediSearch\Redis\Response\SearchResponseItem $item */
+foreach ($items as $item) {
+    doSomething($item);
+}
+```
+Be careful, this will load all items in the memory.
+This will also call Redis multiple time if there are several pages.
+
+---
+
+If you need to avoid loading all items in the memory, you can use [`ResponseItemIterator`](https://github.com/MacFJA/php-redisearch-integration/blob/main/src/Iterator/ResponseItemIterator.php) from the sister project [macfja/redisearch-integration](https://github.com/MacFJA/php-redisearch-integration).
+This class it a custom iterator that will load in memory only one page at the time.
+
+```php
+/** @var \MacFJA\RediSearch\Redis\Client $client */
+/** @var \MacFJA\RediSearch\Redis\Command\Search $search */
+
+$results = $client->execute($search);
+$allItems = new \MacFJA\RediSearch\Integration\Iterator\ResponseItemIterator($results, $client);
+/** @var \MacFJA\RediSearch\Redis\Response\SearchResponseItem $item */
+foreach ($allItems as $item) {
+    // Only one page exist in the memory
+    doSomething($item);
+}
+```

src/Exception/MissingClientException.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright MacFJA
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+namespace MacFJA\RediSearch\Exception;
+
+use RuntimeException;
+use Throwable;
+
+class MissingClientException extends RuntimeException
+{
+    public function __construct(Throwable $previous = null)
+    {
+        parent::__construct('The Redis client is missing. You need to manually set it.', 0, $previous);
+    }
+}

src/Redis/Client/AmpRedisClient.php

@@ -34,6 +34,9 @@ class AmpRedisClient extends AbstractClient
     /** @var Redis */
     private $redis;
 
+    /**
+     * @codeCoverageIgnore
+     */
     private function __construct(Redis $redis)
     {
         if (!static::supports($redis)) {
@@ -83,6 +86,9 @@ public function pipeline(Command ...$commands): array
         }, $commands);
     }
 
+    /**
+     * @codeCoverageIgnore
+     */
     protected function doPipeline(Command ...$commands): array
     {
         return [];

src/Redis/Client/CheprasovRedisClient.php

@@ -33,6 +33,9 @@ class CheprasovRedisClient extends AbstractClient
     /** @var AbstractRedisClient */
     private $redis;
 
+    /**
+     * @codeCoverageIgnore
+     */
     private function __construct(AbstractRedisClient $redis)
     {
         if (!static::supports($redis)) {

src/Redis/Client/CredisClient.php

@@ -32,6 +32,9 @@ class CredisClient extends AbstractClient
     /** @var Credis_Client */
     private $redis;
 
+    /**
+     * @codeCoverageIgnore
+     */
     private function __construct(Credis_Client $redis)
     {
         if (!self::supports($redis)) {

src/Redis/Client/PredisClient.php

@@ -34,6 +34,9 @@ class PredisClient extends AbstractClient
     /** @var ClientInterface */
     private $redis;
 
+    /**
+     * @codeCoverageIgnore
+     */
     private function __construct(ClientInterface $redis)
     {
         if (!static::supports($redis)) {

src/Redis/Client/RedisentClient.php

@@ -31,6 +31,9 @@ class RedisentClient extends AbstractClient
     /** @var Redis */
     private $redis;
 
+    /**
+     * @codeCoverageIgnore
+     */
     private function __construct(Redis $redis)
     {
         if (!static::supports($redis)) {

src/Redis/Client/Rediska/RediskaRediSearchCommand.php

@@ -26,6 +26,9 @@
 use Rediska_Command_Abstract;
 use Rediska_Connection_Exec;
 
+/**
+ * @codeCoverageIgnore
+ */
 class RediskaRediSearchCommand extends Rediska_Command_Abstract
 {
     public function create(): Rediska_Connection_Exec

src/Redis/Client/RediskaClient.php

@@ -36,6 +36,9 @@ class RediskaClient extends AbstractClient
     /** @var Rediska */
     private $redis;
 
+    /**
+     * @codeCoverageIgnore
+     */
     private function __construct(Rediska $redis)
     {
         if (!static::supports($redis)) {

src/Redis/Client/TinyRedisClient.php

@@ -30,6 +30,9 @@ class TinyRedisClient extends AbstractClient
     /** @var \TinyRedisClient */
     private $redis;
 
+    /**
+     * @codeCoverageIgnore
+     */
     public function __construct(\TinyRedisClient $redis)
     {
         if (!self::supports($redis)) {

src/Redis/Response/AggregateResponseItem.php

@@ -24,7 +24,7 @@
 /**
  * @codeCoverageIgnore Simple value object
  */
-class AggregateResponseItem
+class AggregateResponseItem implements ResponseItem
 {
     /** @var array<string,null|array<mixed>|float|int|string> */
     private $fields = [];
@@ -49,8 +49,24 @@ public function getFields(): array
      * @param null|array<mixed>|float|int|string $default
      *
      * @return null|array<mixed>|float|int|string
+     *
+     * @deprecated Use ::getFieldValue instead
+     * @codeCoverageIgnore
+     * @psalm-suppress
+     * @SuppressWarnings
      */
     public function getValue(string $fieldName, $default = null)
+    {
+        trigger_error(sprintf(
+            'Method %s is deprecated from version 2.2.0, use %s::getFieldValue instead',
+            __METHOD__,
+            __CLASS__
+        ), E_USER_DEPRECATED);
+        // @phpstan-ignore-next-line
+        return $this->getFieldValue($fieldName, $default);
+    }
+
+    public function getFieldValue(string $fieldName, $default = null)
     {
         return $this->fields[$fieldName] ?? $default;
     }

src/Redis/Response/ArrayResponseTrait.php

@@ -86,9 +86,12 @@ private static function getNextValue(array $notKeyedArray, string $key)
      */
     private static function getKeys(array $notKeyedArray): array
     {
-        $keys = array_filter(array_values($notKeyedArray), static function (int $key): bool {
+        if (count($notKeyedArray) % 2 > 0) {
+            array_pop($notKeyedArray);
+        }
+        $keys = array_values(array_filter(array_values($notKeyedArray), static function (int $key): bool {
             return 0 === $key % 2;
-        }, ARRAY_FILTER_USE_KEY);
+        }, ARRAY_FILTER_USE_KEY));
 
         return array_map(static function ($key): string {
             return (string) $key;

src/Redis/Response/ClientAware.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright MacFJA
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+namespace MacFJA\RediSearch\Redis\Response;
+
+use MacFJA\RediSearch\Redis\Client;
+
+interface ClientAware
+{
+    public function setClient(Client $client): ClientAware;
+
+    public function getClient(): ?Client;
+}

src/Redis/Response/ClientAwareTrait.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright MacFJA
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+namespace MacFJA\RediSearch\Redis\Response;
+
+use MacFJA\RediSearch\Redis\Client;
+
+trait ClientAwareTrait
+{
+    /** @var null|Client */
+    private $client;
+
+    public function getClient(): ?Client
+    {
+        return $this->client;
+    }
+
+    public function setClient(Client $client): ClientAware
+    {
+        $this->client = $client;
+
+        return $this;
+    }
+}