Merge pull request #39 from murnieza/query_params

Missing parameters for request

docs/HowTo/CustomParameters.md

+# How to set custom parameters to your search
+
+Elasticsearch supports number of custom parameters which can be added to your query. Detailed explanation of each parameter can be found at [official documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#_parameters_5)
+
+## Setting `timeout` parameter
+
+This option allows user to specify timeout for query execution in ["Time units"](https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#time-units).
+
+Following code
+
+```php
+$search = new Search();
+$search->setTimeout('5s');
+```
+
+would generate the query like this:
+```json
+{
+  "timeout": "5s"
+}
+```
+
+## Setting `from` and `size` parameters
+
+These parameters are usually used for pagination.
+
+Following code
+
+```php
+$search = new Search();
+$search->setSize(25);
+$search->setFrom(50);
+```
+
+would generate the query like this:
+```json
+{
+  "size": 25,
+  "from": 50
+}
+```
+
+## Setting `terminate_after` parameter
+
+This parameter can limit how many documents can be fetched from shard before query execution is terminated.
+
+Following code
+
+```php
+$search = new Search();
+$search->setTerminateAfter(1000);
+```
+
+would generate the query like this:
+```json
+{
+  "terminate_after": 1000
+}
+```
+
+## Setting `search_type` and `request_cache` parameters
+
+These parameters are different from previous ones because they have to be passed not in query's body but as query string parameters.
+
+Following code
+
+```php
+$search = new Search();
+$search->setSearchType('dfs_query_then_fetch');
+$search->setRequestCache(true);
+```
+
+would generate query string with `?search_type=dfs_query_then_fetch&request_cache=true`.
\ No newline at end of file

docs/index.md

@@ -11,6 +11,7 @@ Everything starts from the `Search` object. We recommend first to take a look at
 
 ### How to
 - [How to Search](HowTo/HowToSearch.md)
+- [How to set custom parameters to Search](HowTo/CustomParameters.md)
 - more coming soon..
 
 [1]: https://github.com/elastic/elasticsearch-php

src/Search.php

@@ -43,6 +43,16 @@ class Search
      */
     private $from;
 
+    /**
+     * @var string
+     */
+    private $timeout;
+
+    /**
+     * @var int
+     */
+    private $terminateAfter;
+
     /**
      * @var string|null
      */
@@ -68,6 +78,11 @@ class Search
      */
     private $searchType;
 
+    /**
+     * @var string
+     */
+    private $requestCache;
+
     /**
      * @var bool
      */
@@ -400,6 +415,34 @@ class Search
         return $this;
     }
 
+    /**
+     * Sets timeout for query execution.
+     *
+     * @param $timeout
+     *
+     * @return $this
+     */
+    public function setTimeout($timeout)
+    {
+        $this->timeout = $timeout;
+
+        return $this;
+    }
+
+    /**
+     * Sets maximum number of documents per shard.
+     *
+     * @param $terminateAfter
+     *
+     * @return $this
+     */
+    public function setTerminateAfter($terminateAfter)
+    {
+        $this->terminateAfter = $terminateAfter;
+
+        return $this;
+    }
+
     /**
      * Returns results offset value.
      *
@@ -602,6 +645,31 @@ class Search
         return $this->searchType;
     }
 
+
+    /**
+     * Set request cache.
+     *
+     * @param string $requestCache
+     *
+     * @return $this
+     */
+    public function setRequestCache($requestCache)
+    {
+        $this->requestCache = $requestCache;
+
+        return $this;
+    }
+
+    /**
+     * Returns request cache.
+     *
+     * @return string
+     */
+    public function getRequestCache()
+    {
+        return $this->requestCache;
+    }
+
     /**
      * Setter for preference.
      *
@@ -653,6 +721,7 @@ class Search
             [
                 'scroll' => $this->getScroll(),
                 'search_type' => $this->getSearchType(),
+                'request_cache' => $this->getRequestCache(),
                 'preference' => $this->getPreference(),
             ]
         );
@@ -674,6 +743,8 @@ class Search
             'stats' => 'stats',
             'minScore' => 'min_score',
             'source' => '_source',
+            'timeout' => 'timeout',
+            'terminateAfter' => 'terminate_after',
         ];
 
         foreach ($params as $field => $param) {

tests/SearchTest.php

@@ -25,4 +25,162 @@ class SearchTest extends \PHPUnit_Framework_TestCase
     {
         $this->assertInstanceOf('ONGR\ElasticsearchDSL\Search', new Search());
     }
+
+    /**
+     * Data provider for test testSettingParams()
+     *
+     * @return array
+     */
+    public function getTestSettingParamsData()
+    {
+        $cases = [];
+
+        $search = new Search();
+        $search->setSize(3);
+        $cases['Only size is set'] = [
+            $search,
+            [
+                'size' => 3,
+            ],
+        ];
+
+        $search = new Search();
+        $search->setFrom(4);
+        $cases['Only from is set'] = [
+            $search,
+            [
+                'from' => 4,
+            ],
+        ];
+
+        $search = new Search();
+        $search->setTimeout('2s');
+        $cases['Only timeout is set'] = [
+            $search,
+            [
+                'timeout' => '2s',
+            ],
+        ];
+
+        $search = new Search();
+        $search->setTerminateAfter(100);
+        $cases['Only terminate_after is set'] = [
+            $search,
+            [
+                'terminate_after' => 100,
+            ],
+        ];
+
+        $search = new Search();
+        $search->setSize(3);
+        $search->setFrom(4);
+        $search->setTimeout('2s');
+        $search->setTerminateAfter(100);
+        $cases['Multiple parameters are set'] = [
+            $search,
+            [
+                'size' => 3,
+                'from' => 4,
+                'timeout' => '2s',
+                'terminate_after' => 100,
+            ],
+        ];
+
+        return $cases;
+    }
+
+    /**
+     * This test checks if parameters are correctly set into Search object.
+     *
+     * @dataProvider getTestSettingParamsData()
+     *
+     * @param Search    $search
+     * @param array     $expected
+     */
+    public function testSettingParams($search, $expected)
+    {
+        $this->assertEquals(
+            $expected,
+            $search->toArray()
+        );
+    }
+
+    /**
+     * Data provider for test testSettingQueryParams()
+     *
+     * @return array
+     */
+    public function getTestSettingQueryParamsData()
+    {
+        $cases = [];
+
+        $search = new Search();
+        $search->setSearchType('dfs_query_then_fetch');
+        $cases['Only search_type is set'] = [
+            $search,
+            [
+                'search_type' => 'dfs_query_then_fetch',
+            ],
+        ];
+
+        $search = new Search();
+        $search->setRequestCache(true);
+        $cases['Only request_cache is set'] = [
+            $search,
+            [
+                'request_cache' => true,
+            ],
+        ];
+
+        $search = new Search();
+        $search->setScroll('1m');
+        $cases['Only scroll is set'] = [
+            $search,
+            [
+                'scroll' => '1m',
+            ],
+        ];
+
+        $search = new Search();
+        $search->setPreference('_local');
+        $cases['Only preference is set'] = [
+            $search,
+            [
+                'preference' => '_local',
+            ],
+        ];
+
+        $search = new Search();
+        $search->setSearchType('dfs_query_then_fetch');
+        $search->setRequestCache(true);
+        $search->setScroll('1m');
+        $search->setPreference('_local');
+        $cases['Multiple parameters are set'] = [
+            $search,
+            [
+                'search_type' => 'dfs_query_then_fetch',
+                'request_cache' => true,
+                'scroll' => '1m',
+                'preference' => '_local',
+            ],
+        ];
+
+        return $cases;
+    }
+
+    /**
+     * Test if query params are constructed correctly.
+     *
+     * @dataProvider getTestSettingQueryParamsData()
+     *
+     * @param Search    $search
+     * @param array     $expected
+     */
+    public function testSettingQueryParams($search, $expected)
+    {
+        $this->assertEquals(
+            $expected,
+            $search->getQueryParams()
+        );
+    }
 }