Merge pull request #117 from einorler/suggest

Suggest

docs/Suggest/index.md

@@ -1,12 +1,27 @@
 # Suggest
 
-Objective suggest builder represents [Elasticsearch Term suggest][1].
+Objective suggest builder in ONGR ElasticsearchDSL represents [Elasticsearch suggesters][1].
+The `Suggest` class is universal for all the suggesters that are currently implemented in
+Elasticsearch.
 
-To form a suggest you have to create `Search` object. See below an example of suggest usage.
+The `Suggest` object takes up to 5 parameters during the initiation:
+
+|   Parameter  |                              Description                                   |
+|:------------:|:--------------------------------------------------------------------------:|
+|    `name`    | The name of the Suggest                                                    |
+|    `field`   | The ES field to execute the suggest                                        |
+|    `type`    | The type of the suggest (eg. phrase)                                       |
+|    `text`    | The text that will be passed to suggest                                    |
+| `parameters` | Array of additional parameters that may be unique to every type of suggest |
+
+To form a suggest you have to create `Search` object. See examples below for more information
+on suggest usage:
+
+### Simple example
 
 ```php
 $search = new Search();
-$suggest = new Suggest('my_suggest', 'searchText', ['field' => 'title', 'size' => 5]);
+$suggest = new Suggest('my_suggest', 'term', 'searchText', 'title', ['size' => 5]);
 $search->addSuggest($suggest);
 $queryArray = $search->toArray();
 ```
@@ -25,13 +40,15 @@ That will generate following JSON:
 }
 ```
 
+### Example of multiple suggests
+
 You're able to create more than one suggest:
 
 ```php
 $search = new Search();
-$suggest1 = new Suggest('my_suggest1', 'the amsterdma meetpu', ['field' => 'body', 'size' => 5]);
+$suggest1 = new Suggest('my_suggest1', 'term', 'the amsterdma meetpu', 'body', ['size' => 5]);
 $search->addSuggest($suggest1);
-$suggest2 = new Suggest('my_suggest2', 'the rottredam meetpu', ['field' => 'title', 'size' => 5]);
+$suggest2 = new Suggest('my_suggest2', 'term', 'the rottredam meetpu', 'title', ['size' => 5]);
 $search->addSuggest($suggest2);
 $queryArray = $search->toArray();
 ```
@@ -57,8 +74,137 @@ That will generate following JSON:
 }
 ```
 
-If parameters `field` or `size` are not provided they will have default values, `field = _all` and `size = 3`
+### Example of phrase suggest
+
+Also, provide different types of suggests, for example, this is a phrase suggest:
+
+```php
+$search = new Search();
+$suggest = new Suggest(
+    'my-suggest',
+    'phrase',
+    'Xor the Got-Jewel',
+    'bigram',
+    [
+        'analyzer' => 'body',
+        'size' => 1,
+        'real_word_error_likelihood' => 0.95,
+        'max_errors' => 0.5,
+        'gram_size' => 2,
+        'direct_generator' => [
+            [
+                'field' => 'body',
+                'suggest_mode' => 'always',
+                'min_word_length' => 1
+            ]
+        ],
+        'highlight'=> [
+            'pre_tag' => '<em>',
+            'post_tag' => '</em>'
+        ]
+    ]
+);
+
+$search->addSuggest($suggest);
+$queryArray = $search->toArray();
+
+```
+
+That will generate following JSON:
+
+```yaml
+"suggest" : {
+  "my-suggest"
+    "text" : "Xor the Got-Jewel",
+    "phrase" : {
+      "analyzer" : "body",
+      "field" : "bigram",
+      "size" : 1,
+      "real_word_error_likelihood" : 0.95,
+      "max_errors" : 0.5,
+      "gram_size" : 2,
+      "direct_generator" : [ {
+        "field" : "body",
+        "suggest_mode" : "always",
+        "min_word_length" : 1
+      } ],
+      "highlight": {
+        "pre_tag": "<em>",
+        "post_tag": "</em>"
+      }
+    }
+  }
+}
+
+```
+
+### Example of completion suggest:
+
+```php
+
+$search = new Search();
+$suggest = new Suggest('song-suggest', 'completion', 'n', 'suggest');
+
+$search->addSuggest($suggest);
+$queryArray = $search->toArray();
+
+```
+
+That will generate following JSON:
+
+```yaml
+
+"suggest" : {
+  "song-suggest" : {
+    "text" : "n",
+    "completion" : {
+      "field" : "suggest"
+    }
+  }
+}
+
+```
+
+### Example of context suggest:
+
+```php
+
+$search = new Search();
+$suggest = new Suggest(
+    'context-suggestion',
+    'completion',
+    'm',
+    'suggest_field',
+    [
+        'context' => ['color' => 'red'],
+        'size' => 10
+    ]
+);
+
+$search->addSuggest($suggest);
+$queryArray = $search->toArray();
+
+```
+
+That will generate following JSON:
+
+```yaml
+
+"suggest" : {
+  "context-suggestion" : {
+    "text" : "m",
+    "completion" : {
+      "field" : "suggest_field",
+      "size": 10,
+      "context": {
+        "color": "red"
+      }
+    }
+  }
+}
+
+```
 
-Find available parameters in [Elasticsearch Term suggest documentation][1]
+Find out more about suggesters in the official [Elasticsearch suggest documentation][1]
 
-[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters-term.html
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters.html

src/Suggest/CompletionSuggest.php

@@ -14,6 +14,9 @@
 use ONGR\ElasticsearchDSL\BuilderInterface;
 use ONGR\ElasticsearchDSL\ParametersTrait;
 
+/**
+ * @deprecated CompletionSuggest is deprecated, use Suggest instead
+ */
 class CompletionSuggest implements BuilderInterface
 {
     use ParametersTrait;

src/Suggest/Suggest.php

@@ -0,0 +1,141 @@
+<?php
+
+/*
+ * This file is part of the ONGR package.
+ *
+ * (c) NFQ Technologies UAB <info@nfq.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace ONGR\ElasticsearchDSL\Suggest;
+
+use ONGR\ElasticsearchDSL\BuilderInterface;
+use ONGR\ElasticsearchDSL\ParametersTrait;
+use Symfony\Component\Serializer\Exception\InvalidArgumentException;
+
+class Suggest implements BuilderInterface
+{
+    use ParametersTrait;
+
+    /**
+     * @var string
+     */
+    private $name;
+
+    /**
+     * @var string
+     */
+    private $type;
+
+    /**
+     * @var string
+     */
+    private $text;
+
+    /**
+     * @var string
+     */
+    private $field;
+
+    /**
+     * TermSuggest constructor.
+     * @param string $name
+     * @param string $type
+     * @param string $text
+     * @param string $field
+     * @param array $parameters
+     */
+    public function __construct($name, $type, $text, $field, $parameters = [])
+    {
+        $this->setName($name);
+        $this->setType($type);
+        $this->setText($text);
+        $this->setField($field);
+        $this->setParameters($parameters);
+    }
+
+    /**
+     * @param string $name
+     */
+    public function setName($name)
+    {
+        $this->name = $name;
+    }
+
+    /**
+     * Returns suggest name
+     *
+     * @return string
+     */
+    public function getName()
+    {
+        return $this->name;
+    }
+
+    /**
+     * Returns element type.
+     *
+     * @return string
+     */
+    public function getType()
+    {
+        return $this->type;
+    }
+
+    /**
+     * @param string $type
+     */
+    public function setType($type)
+    {
+        $this->type = $type;
+    }
+
+    /**
+     * @return string
+     */
+    public function getText()
+    {
+        return $this->text;
+    }
+
+    /**
+     * @param string $text
+     */
+    public function setText($text)
+    {
+        $this->text = $text;
+    }
+
+    /**
+     * @return string
+     */
+    public function getField()
+    {
+        return $this->field;
+    }
+
+    /**
+     * @param string $field
+     */
+    public function setField($field)
+    {
+        $this->field = $field;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function toArray()
+    {
+        $output = [
+            $this->getName() => [
+                'text' => $this->getText(),
+                $this->getType() => $this->processArray(['field' => $this->getField()]),
+            ]
+        ];
+
+        return $output;
+    }
+}

src/Suggest/TermSuggest.php

@@ -14,6 +14,9 @@
 use ONGR\ElasticsearchDSL\BuilderInterface;
 use ONGR\ElasticsearchDSL\ParametersTrait;
 
+/**
+ * @deprecated TermSuggestClass is deprecated, use Suggest instead
+ */
 class TermSuggest implements BuilderInterface
 {
     use ParametersTrait;