diff --git a/CHANGELOG.md b/CHANGELOG.md index ba3dc38946..0d0d2aceba 100755 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ All notable changes to this project will be documented in this file based on the * Changed all factory methods to make use of [late static bindings](http://docs.php.net/manual/en/language.oop5.late-static-bindings.php) by using `static` instead of `self` keyword. This is to increase extendability for classes with factory methods. ### Backward Compatibility Breaks +* The `\Elastica\Query::$_suggest` property has been renamed to `$hasSuggest` and is now private, it should not be used from extending classes [#1679](https://github.com/ruflin/Elastica/pull/1679) * Removed `\Elastica\Query\GeohashCell` query, use `\Elastica\Query\GeoBoundingBox` instead [#1672](https://github.com/ruflin/Elastica/pull/1672). * Dropped support for PHP 7.0 * \Elastica\AbstractUpdateAction::getOptions( $fields ) no longer supports the $underscore parameter, option names must match what elasticsearch expects. diff --git a/lib/Elastica/Query.php b/lib/Elastica/Query.php index a6b8bbcf15..9d5586fbdb 100644 --- a/lib/Elastica/Query.php +++ b/lib/Elastica/Query.php @@ -23,16 +23,14 @@ class Query extends Param { /** - * Suggest query or not. - * - * @var int Suggest + * If the current query has a suggest in it. */ - protected $_suggest = 0; + private $hasSuggest = false; /** * Creates a query object. * - * @param array|\Elastica\Query\AbstractQuery $query OPTIONAL Query object (default = null) + * @param array|AbstractQuery $query Query object (default = null) */ public function __construct($query = null) { @@ -55,30 +53,23 @@ public function __construct($query = null) * @param mixed $query * * @throws InvalidException For an invalid argument - * - * @return self */ - public static function create($query) + public static function create($query): self { switch (true) { - case $query instanceof self: - return $query; - case $query instanceof AbstractQuery: - return new static($query); case empty($query): return new static(new MatchAll()); - case \is_array($query): - return new static($query); - case \is_string($query): - return new static(new QueryString($query)); + case $query instanceof self: + return $query; case $query instanceof AbstractSuggest: return new static(new Suggest($query)); - + case $query instanceof AbstractQuery: case $query instanceof Suggest: - return new static($query); - case $query instanceof Collapse: + case \is_array($query): return new static($query); + case \is_string($query): + return new static(new QueryString($query)); } throw new InvalidException('Unexpected argument to create a query for.'); @@ -88,10 +79,8 @@ public static function create($query) * Sets query as raw array. Will overwrite all already set arguments. * * @param array $query Query array - * - * @return $this */ - public function setRawQuery(array $query) + public function setRawQuery(array $query): self { $this->_params = $query; @@ -101,11 +90,9 @@ public function setRawQuery(array $query) /** * Sets the query. * - * @param \Elastica\Query\AbstractQuery $query Query object - * - * @return $this + * @param AbstractQuery $query Query object */ - public function setQuery(AbstractQuery $query) + public function setQuery(AbstractQuery $query): self { return $this->setParam('query', $query); } @@ -113,7 +100,7 @@ public function setQuery(AbstractQuery $query) /** * Gets the query object. * - * @return array|\Elastica\Query\AbstractQuery + * @return array|AbstractQuery **/ public function getQuery() { @@ -123,11 +110,9 @@ public function getQuery() /** * Sets the start from which the search results should be returned. * - * @param int $from - * - * @return $this + * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-from-size */ - public function setFrom($from) + public function setFrom(int $from): self { return $this->setParam('from', $from); } @@ -138,11 +123,9 @@ public function setFrom($from) * * @param array $sortArgs Sorting arguments * - * @return $this - * * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-sort.html */ - public function setSort(array $sortArgs) + public function setSort(array $sortArgs): self { return $this->setParam('sort', $sortArgs); } @@ -152,11 +135,9 @@ public function setSort(array $sortArgs) * * @param mixed $sort Sort parameter * - * @return $this - * * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-sort.html */ - public function addSort($sort) + public function addSort($sort): self { return $this->addParam('sort', $sort); } @@ -164,15 +145,11 @@ public function addSort($sort) /** * Keep track of the scores when sorting results. * - * @param bool $trackScores - * - * @return $this - * * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-sort.html#_track_scores */ - public function setTrackScores($trackScores = true): self + public function setTrackScores(bool $trackScores = true): self { - return $this->setParam('track_scores', (bool) $trackScores); + return $this->setParam('track_scores', $trackScores); } /** @@ -180,11 +157,9 @@ public function setTrackScores($trackScores = true): self * * @param array $highlightArgs Set all highlight arguments * - * @return $this - * * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-highlighting.html */ - public function setHighlight(array $highlightArgs) + public function setHighlight(array $highlightArgs): self { return $this->setParam('highlight', $highlightArgs); } @@ -194,11 +169,9 @@ public function setHighlight(array $highlightArgs) * * @param mixed $highlight Add highlight argument * - * @return $this - * * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-highlighting.html */ - public function addHighlight($highlight) + public function addHighlight($highlight): self { return $this->addParam('highlight', $highlight); } @@ -206,11 +179,11 @@ public function addHighlight($highlight) /** * Sets maximum number of results for this query. * - * @param int $size OPTIONAL Maximal number of results for query (default = 10) + * @param int $size Maximal number of results for query (default = 10) * - * @return $this + * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-from-size */ - public function setSize($size = 10) + public function setSize(int $size = 10): self { return $this->setParam('size', $size); } @@ -218,13 +191,11 @@ public function setSize($size = 10) /** * Enables explain on the query. * - * @param bool $explain OPTIONAL Enabled or disable explain (default = true) + * @param bool $explain Enabled or disable explain (default = true) * - * @return $this - * - * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-explain.html + * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-explain */ - public function setExplain($explain = true) + public function setExplain($explain = true): self { return $this->setParam('explain', $explain); } @@ -232,13 +203,11 @@ public function setExplain($explain = true) /** * Enables version on the query. * - * @param bool $version OPTIONAL Enabled or disable version (default = true) - * - * @return $this + * @param bool $version Enabled or disable version (default = true) * - * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-version.html + * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-version */ - public function setVersion($version = true) + public function setVersion($version = true): self { return $this->setParam('version', $version); } @@ -250,25 +219,21 @@ public function setVersion($version = true) * * @param array $fields Fields to be returned * - * @return $this - * - * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-fields.html + * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-stored-fields */ - public function setStoredFields(array $fields) + public function setStoredFields(array $fields): self { return $this->setParam('stored_fields', $fields); } /** - * Sets the fields not stored to be returned by the search. + * Set the doc value representation of a fields to return for each hit. * * @param array $fieldDataFields Fields not stored to be returned * - * @return $this - * - * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-fielddata-fields.html + * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-docvalue-fields */ - public function setFieldDataFields(array $fieldDataFields) + public function setFieldDataFields(array $fieldDataFields): self { return $this->setParam('docvalue_fields', $fieldDataFields); } @@ -278,11 +243,9 @@ public function setFieldDataFields(array $fieldDataFields) * * @param array|\Elastica\Script\ScriptFields $scriptFields Script fields * - * @return $this - * - * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-script-fields.html + * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-script-fields */ - public function setScriptFields($scriptFields) + public function setScriptFields($scriptFields): self { if (\is_array($scriptFields)) { $scriptFields = new ScriptFields($scriptFields); @@ -296,10 +259,8 @@ public function setScriptFields($scriptFields) * * @param string $name * @param \Elastica\Script\AbstractScript $script Script object - * - * @return $this */ - public function addScriptField($name, AbstractScript $script) + public function addScriptField($name, AbstractScript $script): self { if (isset($this->_params['script_fields'])) { $this->_params['script_fields']->addScript($name, $script); @@ -314,10 +275,8 @@ public function addScriptField($name, AbstractScript $script) * Adds an Aggregation to the query. * * @param AbstractAggregation $agg - * - * @return $this */ - public function addAggregation(AbstractAggregation $agg) + public function addAggregation(AbstractAggregation $agg): self { $this->_params['aggs'][] = $agg; @@ -326,12 +285,10 @@ public function addAggregation(AbstractAggregation $agg) /** * Converts all query params to an array. - * - * @return array Query array */ - public function toArray() + public function toArray(): array { - if (!isset($this->_params['query']) && (0 == $this->_suggest)) { + if (!$this->hasSuggest && !isset($this->_params['query'])) { $this->setQuery(new MatchAll()); } @@ -353,31 +310,26 @@ public function toArray() * * @param float $minScore Minimum score to filter documents by * - * @throws \Elastica\Exception\InvalidException + * @throws InvalidException * - * @return $this + * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-min-score */ - public function setMinScore($minScore) + public function setMinScore(float $minScore): self { - if (!\is_numeric($minScore)) { - throw new InvalidException('has to be numeric param'); - } - return $this->setParam('min_score', $minScore); } /** * Add a suggest term. * - * @param \Elastica\Suggest $suggest suggestion object + * @param Suggest $suggest suggestion object * - * @return $this + * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters.html */ - public function setSuggest(Suggest $suggest) + public function setSuggest(Suggest $suggest): self { $this->setParam('suggest', $suggest); - - $this->_suggest = 1; + $this->hasSuggest = true; return $this; } @@ -387,9 +339,9 @@ public function setSuggest(Suggest $suggest) * * @param mixed $rescore suggestion object * - * @return $this + * @see: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-rescore */ - public function setRescore($rescore) + public function setRescore($rescore): self { if (\is_array($rescore)) { $buffer = []; @@ -409,33 +361,31 @@ public function setRescore($rescore) * * @param array|bool $params Fields to be returned or false to disable source * - * @return $this - * - * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-source-filtering.html + * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-source-filtering */ - public function setSource($params) + public function setSource($params): self { return $this->setParam('_source', $params); } /** - * Sets post_filter argument for the query. The filter is applied after the query has executed. - * - * @param array|\Elastica\Query\AbstractQuery $filter + * Sets a post_filter to the current query. * - * @return $this + * @param array|AbstractQuery $filter * - * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-post-filter.html + * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-post-filter */ - public function setPostFilter(AbstractQuery $filter) + public function setPostFilter(AbstractQuery $filter): self { return $this->setParam('post_filter', $filter); } /** + * Allows to collapse search results based on field values. + * * @param Collapse $collapse * - * @return $this + * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-collapse */ public function setCollapse(Collapse $collapse): self { @@ -445,13 +395,11 @@ public function setCollapse(Collapse $collapse): self /** * Adds a track_total_hits argument. * - * @param bool|int $trackTotalHits OPTIONAL Track total hits parameter (default = true) - * - * @return $this + * @param bool|int $trackTotalHits Track total hits parameter (default = true) * * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-track-total-hits */ - public function setTrackTotalHits($trackTotalHits = true) + public function setTrackTotalHits($trackTotalHits = true): self { return $this->setParam('track_total_hits', $trackTotalHits); }