Added test coverage and docs for cursor functionality (#596)

docs/plugins.md

@@ -471,6 +471,11 @@ $client = new Solarium\Client($config);
 $query = $client->createSelect();
 $query->setFields(array('id'));
 
+// cursor functionality can be used for efficient deep paging (since Solr 4.7)
+$query->setCursormark('*');
+// cursor functionality requires a sort containing a uniqueKey field as tie breaker on top of your desired sorts for the query
+$query->addSort('id', $query::SORT_ASC);
+
 // get a plugin instance and apply settings
 $prefetch = $client->getPlugin('prefetchiterator');
 $prefetch->setPrefetch(2); //fetch 2 rows per query (for real world use this can be way higher)

docs/queries/select-query/building-a-select-query/building-a-select-query.md

@@ -19,6 +19,7 @@ The options below can be set as query option values, but also by using the set/g
 | querydefaultfield    | string           | null                          | With a null value the default of your Solr config will be used. If you want to override this supply a field name as the value.                                             |
 | responsewriter       | string           | json                          | You can set this to 'phps' for improved response parsing performance, at the cost of a (possible) security risk. Only use 'phps' for trusted Solr instances.               |
 | tag                  | array of strings | null                          | You can supply one or multiple tags for the main query string, to allow for exclusion of the main query in facets                                                          |
+| cursormark           | string           | null                          | Set to '\*' and make sure sort contains a uniqueKey field to enable cursor functionality when passing the query to the PrefetchIterator plugin. Available since Solr 4.7.  |
 | splitonwhitespace    | bool             | null                          | Specifies whether the query parser splits the query text on whitespace before it's sent to be analyzed. Available for 'lucene' and 'edismax' query parsers since Solr 6.5. |
 ||
 

examples/7.6-plugin-prefetchiterator.php

@@ -15,6 +15,11 @@ $prefetch = $client->getPlugin('prefetchiterator');
 $prefetch->setPrefetch(2); //fetch 2 rows per query (for real world use this can be way higher)
 $prefetch->setQuery($query);
 
+// cursor functionality can be used for efficient deep paging (since Solr 4.7)
+$query->setCursormark('*');
+// cursor functionality requires a sort containing a uniqueKey field as tie breaker on top of your desired sorts for the query
+$query->addSort('id', $query::SORT_ASC);
+
 // display the total number of documents found by solr
 echo 'NumFound: ' . count($prefetch);
 

src/QueryType/Select/Query/Query.php

@@ -732,7 +732,9 @@ class Query extends AbstractQuery implements ComponentAwareQueryInterface
     /**
      * Set the cursor mark to fetch.
      *
-     * Cursor functionality requires a sort containing a uniqueKey field tie breaker
+     * Cursor functionality requires a sort containing a uniqueKey field as tie breaker on top of your desired
+     * sorts for the query.
+     * Cursor functionality was introduced in Solr 4.7.
      *
      * @param string $cursormark
      *

src/QueryType/Select/Result/Result.php

@@ -154,7 +154,7 @@ class Result extends BaseResult implements \IteratorAggregate, \Countable
      * get Solr nextcursormark.
      *
      * Returns the next cursor mark for deep paging
-     * Will only be available if 'cursormark' was set for your query
+     * Will only be available if 'cursormark' was set for your query against Solr 4.7+
      *
      * @return string
      */

tests/QueryType/Select/Query/AbstractQueryTest.php

@@ -689,6 +689,19 @@ abstract class AbstractQueryTest extends TestCase
         $this->assertSame(['t3', 't4'], $this->query->getTags());
     }
 
+    public function testSetCursormark()
+    {
+        $this->query->setCursormark('*');
+        $this->assertSame('*', $this->query->getCursormark());
+    }
+
+    public function testClearCursormark()
+    {
+        $this->query->setCursormark('*');
+        $this->query->clearCursormark();
+        $this->assertNull($this->query->getCursormark());
+    }
+
     public function testSetAndGetSplitOnWhitespace()
     {
         $this->query->setSplitOnWhitespace(false);