From 67559d5f49b1db30cd4dab93056e9fd406a259bc Mon Sep 17 00:00:00 2001 From: Mantas Date: Fri, 1 Jul 2016 10:37:05 +0300 Subject: [PATCH 1/5] deprecated existing suggest classes --- src/Suggest/CompletionSuggest.php | 3 +++ src/Suggest/TermSuggest.php | 3 +++ 2 files changed, 6 insertions(+) diff --git a/src/Suggest/CompletionSuggest.php b/src/Suggest/CompletionSuggest.php index 5219d7b8..fa5e2ba7 100644 --- a/src/Suggest/CompletionSuggest.php +++ b/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; diff --git a/src/Suggest/TermSuggest.php b/src/Suggest/TermSuggest.php index d2afa0c2..7083d3ee 100644 --- a/src/Suggest/TermSuggest.php +++ b/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; From f8bc9a1636baed6617e6271260cf7e12e5ba6a92 Mon Sep 17 00:00:00 2001 From: Mantas Date: Fri, 1 Jul 2016 10:37:17 +0300 Subject: [PATCH 2/5] added general Suggest class --- src/Suggest/Suggest.php | 171 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 src/Suggest/Suggest.php diff --git a/src/Suggest/Suggest.php b/src/Suggest/Suggest.php new file mode 100644 index 00000000..bd2e55f3 --- /dev/null +++ b/src/Suggest/Suggest.php @@ -0,0 +1,171 @@ + + * + * 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; + + const TERM = 'term'; + const COMPLETION = 'completion'; + const PHRASE = 'phrase'; + const CONTEXT = 'completion'; + + /** + * @var string + */ + private $name; + + /** + * @var string + */ + private $type; + + /** + * @var string + */ + private $field; + + /** + * @var string + */ + private $text; + + /** + * TermSuggest constructor. + * @param string $name + * @param string $field + * @param string $type + * @param string $text + * @param array $parameters + */ + public function __construct($name, $field, $type, $text, $parameters = []) + { + $this->setName($name); + $this->validateType($type); + $this->setField($field); + $this->setType($type); + $this->setText($text); + $this->setParameters($parameters); + } + + /** + * 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; + } + + /** + * @param string $name + */ + public function setName($name) + { + $this->name = $name; + } + + /** + * Returns suggest name + * + * @return string + */ + public function getName() + { + return $this->name; + } + + /** + * Checks if the type is valid + * + * @param string $type + * + * @return bool + * + * @throws InvalidArgumentException + */ + private function validateType($type) + { + if (in_array($type, [ + self::COMPLETION, + self::CONTEXT, + self::PHRASE, + self::TERM + ])) { + return true; + } + throw new InvalidArgumentException( + 'You must provide a valid type to the Suggest()' + ); + } + + /** + * {@inheritdoc} + */ + public function toArray() + { + $output = [ + $this->getName() => [ + 'text' => $this->getText(), + $this->getType() => $this->processArray(['field' => $this->getField()]), + ] + ]; + + return $output; + } +} From 12c56e0b077c44551c27322753f6ec979e091502 Mon Sep 17 00:00:00 2001 From: Mantas Date: Fri, 1 Jul 2016 10:37:32 +0300 Subject: [PATCH 3/5] added Tests --- tests/Suggest/SuggestTest.php | 131 ++++++++++++++++++++++++++++++ tests/Suggest/TermSuggestTest.php | 2 +- 2 files changed, 132 insertions(+), 1 deletion(-) create mode 100644 tests/Suggest/SuggestTest.php diff --git a/tests/Suggest/SuggestTest.php b/tests/Suggest/SuggestTest.php new file mode 100644 index 00000000..7e0e102f --- /dev/null +++ b/tests/Suggest/SuggestTest.php @@ -0,0 +1,131 @@ + + * + * 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', 'bar', Suggest::TERM, 'acme'); + $this->assertEquals('term', $suggest->getType()); + } + + /** + * Data provider for testToArray() + * + * @return array[] + */ + public function getTestToArrayData() + { + return [ + [ + 'suggest' => new Suggest( + 'foo', + 'acme', + Suggest::PHRASE, + 'bar', + ['max_errors' => 0.5] + ), + 'expected' => [ + 'foo' => [ + 'text' => 'bar', + 'phrase' => [ + 'field' => 'acme', + 'max_errors' => 0.5, + ], + ] + ] + ], + [ + 'suggest' => new Suggest( + 'foo', + 'acme', + Suggest::CONTEXT, + 'bar', + ['context' => ['color' => 'red'], 'size' => 3] + ), + 'expected' => [ + 'foo' => [ + 'text' => 'bar', + 'completion' => [ + 'field' => 'acme', + 'size' => 3, + 'context' => [ + 'color' => 'red' + ] + ] + ] + ] + ], + [ + 'suggest' => new Suggest( + 'foo', + 'acme', + Suggest::TERM, + 'bar', + ['size' => 5] + ), + 'expected' => [ + 'foo' => [ + 'text' => 'bar', + 'term' => [ + 'field' => 'acme', + 'size' => 5 + ] + ] + ] + ], + [ + 'suggest' => new Suggest( + 'foo', + 'acme', + Suggest::COMPLETION, + 'bar' + ), + 'expected' => [ + 'foo' => [ + 'text' => 'bar', + 'completion' => [ + 'field' => 'acme' + ] + ] + ] + ] + ]; + } + + /** + * @param Suggest $suggest + * @param array $expected + * + * @dataProvider getTestToArrayData() + */ + public function testToArray(Suggest $suggest, array $expected) + { + $this->assertEquals($expected, $suggest->toArray()); + } + + /** + * Tests exception that is thrown when wrong type is provided + * + * @expectedException \InvalidArgumentException + */ + public function testValidateTypeException() + { + new Suggest('foo', 'bar', 'wrong-type', 'acme'); + } +} diff --git a/tests/Suggest/TermSuggestTest.php b/tests/Suggest/TermSuggestTest.php index d20c0bdc..e3685e72 100644 --- a/tests/Suggest/TermSuggestTest.php +++ b/tests/Suggest/TermSuggestTest.php @@ -13,7 +13,7 @@ use ONGR\ElasticsearchDSL\Suggest\TermSuggest; -class SuggestTest extends \PHPUnit_Framework_TestCase +class TermSuggestTest extends \PHPUnit_Framework_TestCase { /** * Tests getType method. From 028934c3bcf3b92203fbd7d1e4044a1005ede215 Mon Sep 17 00:00:00 2001 From: Mantas Date: Tue, 12 Jul 2016 14:22:10 +0300 Subject: [PATCH 4/5] removed constants and changed the order of params --- src/Suggest/Suggest.php | 76 +++++++++++------------------------ tests/Suggest/SuggestTest.php | 60 ++++++++++++--------------- 2 files changed, 49 insertions(+), 87 deletions(-) diff --git a/src/Suggest/Suggest.php b/src/Suggest/Suggest.php index bd2e55f3..f7951308 100644 --- a/src/Suggest/Suggest.php +++ b/src/Suggest/Suggest.php @@ -19,11 +19,6 @@ class Suggest implements BuilderInterface { use ParametersTrait; - const TERM = 'term'; - const COMPLETION = 'completion'; - const PHRASE = 'phrase'; - const CONTEXT = 'completion'; - /** * @var string */ @@ -37,31 +32,48 @@ class Suggest implements BuilderInterface /** * @var string */ - private $field; + private $text; /** * @var string */ - private $text; + private $field; /** * TermSuggest constructor. * @param string $name - * @param string $field * @param string $type * @param string $text + * @param string $field * @param array $parameters */ - public function __construct($name, $field, $type, $text, $parameters = []) + public function __construct($name, $type, $text, $field, $parameters = []) { $this->setName($name); - $this->validateType($type); - $this->setField($field); $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. * @@ -112,48 +124,6 @@ public function setField($field) $this->field = $field; } - /** - * @param string $name - */ - public function setName($name) - { - $this->name = $name; - } - - /** - * Returns suggest name - * - * @return string - */ - public function getName() - { - return $this->name; - } - - /** - * Checks if the type is valid - * - * @param string $type - * - * @return bool - * - * @throws InvalidArgumentException - */ - private function validateType($type) - { - if (in_array($type, [ - self::COMPLETION, - self::CONTEXT, - self::PHRASE, - self::TERM - ])) { - return true; - } - throw new InvalidArgumentException( - 'You must provide a valid type to the Suggest()' - ); - } - /** * {@inheritdoc} */ diff --git a/tests/Suggest/SuggestTest.php b/tests/Suggest/SuggestTest.php index 7e0e102f..e7482239 100644 --- a/tests/Suggest/SuggestTest.php +++ b/tests/Suggest/SuggestTest.php @@ -20,7 +20,7 @@ class SuggestTest extends \PHPUnit_Framework_TestCase */ public function testSuggestGetType() { - $suggest = new Suggest('foo', 'bar', Suggest::TERM, 'acme'); + $suggest = new Suggest('foo', 'term', 'acme', 'bar'); $this->assertEquals('term', $suggest->getType()); } @@ -35,56 +35,53 @@ public function getTestToArrayData() [ 'suggest' => new Suggest( 'foo', - 'acme', - Suggest::PHRASE, + 'term', 'bar', - ['max_errors' => 0.5] + 'acme', + ['size' => 5] ), 'expected' => [ 'foo' => [ 'text' => 'bar', - 'phrase' => [ + 'term' => [ 'field' => 'acme', - 'max_errors' => 0.5, - ], + 'size' => 5 + ] ] ] ], [ 'suggest' => new Suggest( 'foo', - 'acme', - Suggest::CONTEXT, + 'phrase', 'bar', - ['context' => ['color' => 'red'], 'size' => 3] + 'acme', + ['max_errors' => 0.5] ), 'expected' => [ 'foo' => [ 'text' => 'bar', - 'completion' => [ + 'phrase' => [ 'field' => 'acme', - 'size' => 3, - 'context' => [ - 'color' => 'red' - ] - ] + 'max_errors' => 0.5, + ], ] ] ], [ 'suggest' => new Suggest( 'foo', - 'acme', - Suggest::TERM, + 'completion', 'bar', - ['size' => 5] + 'acme', + ['fuzziness' => 2] ), 'expected' => [ 'foo' => [ 'text' => 'bar', - 'term' => [ + 'completion' => [ 'field' => 'acme', - 'size' => 5 + 'fuzziness' => 2 ] ] ] @@ -92,15 +89,20 @@ public function getTestToArrayData() [ 'suggest' => new Suggest( 'foo', + 'completion', + 'bar', 'acme', - Suggest::COMPLETION, - 'bar' + ['context' => ['color' => 'red'], 'size' => 3] ), 'expected' => [ 'foo' => [ 'text' => 'bar', 'completion' => [ - 'field' => 'acme' + 'field' => 'acme', + 'size' => 3, + 'context' => [ + 'color' => 'red' + ] ] ] ] @@ -118,14 +120,4 @@ public function testToArray(Suggest $suggest, array $expected) { $this->assertEquals($expected, $suggest->toArray()); } - - /** - * Tests exception that is thrown when wrong type is provided - * - * @expectedException \InvalidArgumentException - */ - public function testValidateTypeException() - { - new Suggest('foo', 'bar', 'wrong-type', 'acme'); - } } From d6ceeb238e78c8020368ec2307f7c02fc4b67592 Mon Sep 17 00:00:00 2001 From: Mantas Date: Tue, 12 Jul 2016 14:25:17 +0300 Subject: [PATCH 5/5] updated the documentation --- docs/Suggest/index.md | 162 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 154 insertions(+), 8 deletions(-) diff --git a/docs/Suggest/index.md b/docs/Suggest/index.md index 273c784a..d496d97b 100644 --- a/docs/Suggest/index.md +++ b/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' => '', + 'post_tag' => '' + ] + ] +); + +$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": "", + "post_tag": "" + } + } + } +} + +``` + +### 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