1<?php
2
3namespace Elastica\Aggregation;
4
5use Elastica\Script\AbstractScript;
6use Elastica\Script\ScriptFields;
7
8/**
9 * Class TopHits.
10 *
11 * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-top-hits-aggregation.html
12 */
13class TopHits extends AbstractAggregation
14{
15    public function toArray(): array
16    {
17        $array = parent::toArray();
18
19        // if there are no params, it's ok, but ES will throw exception if json
20        // will be like {"top_hits":[]} instead of {"top_hits":{}}
21        if (empty($array['top_hits'])) {
22            $array['top_hits'] = new \stdClass();
23        }
24
25        return $array;
26    }
27
28    /**
29     * The maximum number of top matching hits to return per bucket. By default the top three matching hits are returned.
30     *
31     * @return $this
32     */
33    public function setSize(int $size): self
34    {
35        return $this->setParam('size', $size);
36    }
37
38    /**
39     * The offset from the first result you want to fetch.
40     *
41     * @return $this
42     */
43    public function setFrom(int $from): self
44    {
45        return $this->setParam('from', $from);
46    }
47
48    /**
49     * How the top matching hits should be sorted. By default the hits are sorted by the score of the main query.
50     *
51     * @return $this
52     */
53    public function setSort(array $sortArgs): self
54    {
55        return $this->setParam('sort', $sortArgs);
56    }
57
58    /**
59     * Allows to control how the _source field is returned with every hit.
60     *
61     * @param array|bool|string $params Fields to be returned or false to disable source
62     *
63     * @return $this
64     */
65    public function setSource($params): self
66    {
67        return $this->setParam('_source', $params);
68    }
69
70    /**
71     * Returns a version for each search hit.
72     *
73     * @return $this
74     */
75    public function setVersion(bool $version): self
76    {
77        return $this->setParam('version', $version);
78    }
79
80    /**
81     * Enables explanation for each hit on how its score was computed.
82     *
83     * @return $this
84     */
85    public function setExplain(bool $explain): self
86    {
87        return $this->setParam('explain', $explain);
88    }
89
90    /**
91     * Set script fields.
92     *
93     * @param array|ScriptFields $scriptFields
94     *
95     * @return $this
96     */
97    public function setScriptFields($scriptFields): self
98    {
99        if (\is_array($scriptFields)) {
100            $scriptFields = new ScriptFields($scriptFields);
101        }
102
103        return $this->setParam('script_fields', $scriptFields);
104    }
105
106    /**
107     * Adds a Script to the aggregation.
108     *
109     * @return $this
110     */
111    public function addScriptField(string $name, AbstractScript $script): self
112    {
113        if (!isset($this->_params['script_fields'])) {
114            $this->_params['script_fields'] = new ScriptFields();
115        }
116
117        $this->_params['script_fields']->addScript($name, $script);
118
119        return $this;
120    }
121
122    /**
123     * Sets highlight arguments for the results.
124     *
125     * @return $this
126     */
127    public function setHighlight(array $highlightArgs): self
128    {
129        return $this->setParam('highlight', $highlightArgs);
130    }
131
132    /**
133     * Allows to return the field data representation of a field for each hit.
134     *
135     * @return $this
136     */
137    public function setFieldDataFields(array $fields): self
138    {
139        return $this->setParam('docvalue_fields', $fields);
140    }
141}
142