Merge pull request #117 from einorler/suggest

Suggest

docs/Suggest/index.md

 # 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
\ No newline at end of file
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters.html
\ No newline at end of file

src/Suggest/CompletionSuggest.php

@@ -14,6 +14,9 @@ namespace ONGR\ElasticsearchDSL\Suggest;
 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

+<?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 @@ namespace ONGR\ElasticsearchDSL\Suggest;
 use ONGR\ElasticsearchDSL\BuilderInterface;
 use ONGR\ElasticsearchDSL\ParametersTrait;
 
+/**
+ * @deprecated TermSuggestClass is deprecated, use Suggest instead
+ */
 class TermSuggest implements BuilderInterface
 {
     use ParametersTrait;

tests/Suggest/SuggestTest.php

+<?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\Tests\Suggest;
+
+use ONGR\ElasticsearchDSL\Suggest\Suggest;
+
+class SuggestTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * Tests getType method.
+     */
+    public function testSuggestGetType()
+    {
+        $suggest = new Suggest('foo', 'term', 'acme', 'bar');
+        $this->assertEquals('term', $suggest->getType());
+    }
+
+    /**
+     * Data provider for testToArray()
+     *
+     * @return array[]
+     */
+    public function getTestToArrayData()
+    {
+        return [
+            [
+                'suggest' => new Suggest(
+                    'foo',
+                    'term',
+                    'bar',
+                    'acme',
+                    ['size' => 5]
+                ),
+                'expected' => [
+                    'foo' => [
+                        'text' => 'bar',
+                        'term' => [
+                            'field' => 'acme',
+                            'size' => 5
+                        ]
+                    ]
+                ]
+            ],
+            [
+                'suggest' => new Suggest(
+                    'foo',
+                    'phrase',
+                    'bar',
+                    'acme',
+                    ['max_errors' => 0.5]
+                ),
+                'expected' => [
+                    'foo' => [
+                        'text' => 'bar',
+                        'phrase' => [
+                            'field' => 'acme',
+                            'max_errors' => 0.5,
+                        ],
+                    ]
+                ]
+            ],
+            [
+                'suggest' => new Suggest(
+                    'foo',
+                    'completion',
+                    'bar',
+                    'acme',
+                    ['fuzziness' => 2]
+                ),
+                'expected' => [
+                    'foo' => [
+                        'text' => 'bar',
+                        'completion' => [
+                            'field' => 'acme',
+                            'fuzziness' => 2
+                        ]
+                    ]
+                ]
+            ],
+            [
+                'suggest' => new Suggest(
+                    'foo',
+                    'completion',
+                    'bar',
+                    'acme',
+                    ['context' => ['color' => 'red'], 'size' => 3]
+                ),
+                'expected' => [
+                    'foo' => [
+                        'text' => 'bar',
+                        'completion' => [
+                            'field' => 'acme',
+                            'size' => 3,
+                            'context' => [
+                                'color' => 'red'
+                            ]
+                        ]
+                    ]
+                ]
+            ]
+        ];
+    }
+
+    /**
+     * @param Suggest $suggest
+     * @param array $expected
+     *
+     * @dataProvider getTestToArrayData()
+     */
+    public function testToArray(Suggest $suggest, array $expected)
+    {
+        $this->assertEquals($expected, $suggest->toArray());
+    }
+}

tests/Suggest/TermSuggestTest.php

@@ -13,7 +13,7 @@ namespace ONGR\ElasticsearchDSL\Tests\Suggest;
 
 use ONGR\ElasticsearchDSL\Suggest\TermSuggest;
 
-class SuggestTest extends \PHPUnit_Framework_TestCase
+class TermSuggestTest extends \PHPUnit_Framework_TestCase
 {
     /**
      * Tests getType method.