1	<?php
2
3	use MediaWiki\Title\Title;
4
5	/**
6	* A set of SearchEngine results.
7	*
8	* Must not be implemented directly by extensions, extend BaseSearchResultSet instead.
9	*
10	* @stable to type
11	* @see BaseSearchResultSet
12	* @ingroup Search
13	*/
14	interface ISearchResultSet extends \Countable, \IteratorAggregate {
15	/**
16	* Identifier for interwiki results that are displayed only together with existing main wiki
17	* results.
18	*/
19	public const SECONDARY_RESULTS = 0;
20
21	/**
22	* Identifier for interwiki results that can be displayed even if no existing main wiki results
23	* exist.
24	*/
25	public const INLINE_RESULTS = 1;
26
27	/**
28	* @return int
29	*/
30	public function numRows();
31
32	/**
33	* Some search modes return a total hit count for the query
34	* in the entire article database. This may include pages
35	* in namespaces that would not be matched on the given
36	* settings.
37	*
38	* Return null if no total hits number is supported.
39	*
40	* @return int|null
41	*/
42	public function getTotalHits();
43
44	/**
45	* If {@link #getTotalHits()} is supported determine whether this number is approximate or not.
46	* Some engine might perform optimizations that might lead to inaccurate total hits.
47	* If this happens such engine should return true.
48	*
49	* @return bool
50	* @since 1.44
51	*/
52	public function isApproximateTotalHits(): bool;
53
54	/**
55	* Some search modes will run an alternative query that it thinks gives
56	* a better result than the provided search. Returns true if this has
57	* occurred.
58	*
59	* NOTE: In practice this has only been applied when the original query
60	* returned no results. UI messages, such as `search-rewritten`, have
61	* this assumption baked in.
62	*
63	* @return bool
64	*/
65	public function hasRewrittenQuery();
66
67	/**
68	* @return string|null The search the query was internally rewritten to,
69	*  or null when the result of the original query was returned.
70	*/
71	public function getQueryAfterRewrite();
72
73	/**
74	* @return HtmlArmor|string|null Same as self::getQueryAfterRewrite(), but
75	*  with changes to the string highlighted in HTML and wrapped in
76	*  HtmlArmor.  If highlighting is not available the rewritten query will
77	*  be returned. When the self::hasRewrittenQuery returns false (i.e. the
78	*  results have not been rewritten) null will be returned.
79	*/
80	public function getQueryAfterRewriteSnippet();
81
82	/**
83	* Some search modes return a suggested alternate term if there are
84	* no exact hits. Returns true if there is one on this set.
85	*
86	* @return bool
87	*/
88	public function hasSuggestion();
89
90	/**
91	* @return string|null Suggested query, null if none
92	*/
93	public function getSuggestionQuery();
94
95	/**
96	* @return HtmlArmor|string Same as self::getSuggestionQuery(), but with
97	*  changes to the string highlighted in HTML and wrapped in HtmlArmor. If
98	*  highlighting is not available the suggested query will be returned. When
99	*  self::hasSuggestion returns false (i.e no suggested query) the empty
100	*  string will be returned.
101	*/
102	public function getSuggestionSnippet();
103
104	/**
105	* Return a result set of hits on other (multiple) wikis associated with this one
106	*
107	* @param int $type
108	* @return ISearchResultSet[]
109	*/
110	public function getInterwikiResults( $type = self::SECONDARY_RESULTS );
111
112	/**
113	* Check if there are results on other wikis
114	*
115	* @param int $type
116	* @return bool
117	*/
118	public function hasInterwikiResults( $type = self::SECONDARY_RESULTS );
119
120	/**
121	* Did the search contain search syntax?  If so, Special:Search won't offer
122	* the user a link to a create a page named by the search string because the
123	* name would contain the search syntax.
124	* @return bool
125	*/
126	public function searchContainedSyntax();
127
128	/**
129	* @return bool True when there are more pages of search results available.
130	*/
131	public function hasMoreResults();
132
133	/**
134	* @param int $limit Shrink result set to $limit and flag
135	*  if more results are available.
136	*/
137	public function shrink( $limit );
138
139	/**
140	* Extract all the results in the result set as array.
141	* @return SearchResult[]
142	*/
143	public function extractResults();
144
145	/**
146	* Extract all the titles in the result set.
147	* @return Title[]
148	*/
149	public function extractTitles();
150
151	/**
152	* Sets augmented data for result set.
153	* @param string $name Extra data item name
154	* @param array[] $data Extra data as PAGEID => data
155	*/
156	public function setAugmentedData( $name, $data );
157
158	/**
159	* Returns extra data for specific result and store it in SearchResult object.
160	*/
161	public function augmentResult( SearchResult $result );
162
163	/**
164	* @return int|null The offset the current page starts at. Typically
165	*  this should be null to allow the UI to decide on its own, but in
166	*  special cases like interleaved AB tests specifying explicitly is
167	*  necessary.
168	*/
169	public function getOffset();
170	}