MediaWiki REL1_34
ApiQuerySearch.php
Go to the documentation of this file.
1<?php
29 use SearchApi;
30
33
34 public function __construct( ApiQuery $query, $moduleName ) {
35 parent::__construct( $query, $moduleName, 'sr' );
36 }
37
38 public function execute() {
39 $this->run();
40 }
41
42 public function executeGenerator( $resultPageSet ) {
43 $this->run( $resultPageSet );
44 }
45
50 private function run( $resultPageSet = null ) {
51 $params = $this->extractRequestParams();
52
53 // Extract parameters
54 $query = $params['search'];
55 $what = $params['what'];
56 $interwiki = $params['interwiki'];
57 $searchInfo = array_flip( $params['info'] );
58 $prop = array_flip( $params['prop'] );
59
60 // Create search engine instance and set options
61 $search = $this->buildSearchEngine( $params );
62 if ( isset( $params['sort'] ) ) {
63 $search->setSort( $params['sort'] );
64 }
65 $search->setFeatureData( 'rewrite', (bool)$params['enablerewrites'] );
66 $search->setFeatureData( 'interwiki', (bool)$interwiki );
67
68 $nquery = $search->replacePrefixes( $query );
69 if ( $nquery !== $query ) {
70 $query = $nquery;
71 wfDeprecated( 'SearchEngine::replacePrefixes() (overridden by ' .
72 get_class( $search ) . ')', '1.32' );
73 }
74 // Perform the actual search
75 if ( $what == 'text' ) {
76 $matches = $search->searchText( $query );
77 } elseif ( $what == 'title' ) {
78 $matches = $search->searchTitle( $query );
79 } elseif ( $what == 'nearmatch' ) {
80 // near matches must receive the user input as provided, otherwise
81 // the near matches within namespaces are lost.
82 $matches = $search->getNearMatcher( $this->getConfig() )
83 ->getNearMatchResultSet( $params['search'] );
84 } else {
85 // We default to title searches; this is a terrible legacy
86 // of the way we initially set up the MySQL fulltext-based
87 // search engine with separate title and text fields.
88 // In the future, the default should be for a combined index.
89 $what = 'title';
90 $matches = $search->searchTitle( $query );
91
92 // Not all search engines support a separate title search,
93 // for instance the Lucene-based engine we use on Wikipedia.
94 // In this case, fall back to full-text search (which will
95 // include titles in it!)
96 if ( is_null( $matches ) ) {
97 $what = 'text';
98 $matches = $search->searchText( $query );
99 }
100 }
101
102 if ( $matches instanceof Status ) {
103 $status = $matches;
104 $matches = $status->getValue();
105 } else {
106 $status = null;
107 }
108
109 if ( $status ) {
110 if ( $status->isOK() ) {
111 $this->getMain()->getErrorFormatter()->addMessagesFromStatus(
112 $this->getModuleName(),
113 $status
114 );
115 } else {
116 $this->dieStatus( $status );
117 }
118 } elseif ( is_null( $matches ) ) {
119 $this->dieWithError( [ 'apierror-searchdisabled', $what ], "search-{$what}-disabled" );
120 }
121
122 if ( $resultPageSet === null ) {
123 $apiResult = $this->getResult();
124 // Add search meta data to result
125 if ( isset( $searchInfo['totalhits'] ) ) {
126 $totalhits = $matches->getTotalHits();
127 if ( $totalhits !== null ) {
128 $apiResult->addValue( [ 'query', 'searchinfo' ],
129 'totalhits', $totalhits );
130 }
131 }
132 if ( isset( $searchInfo['suggestion'] ) && $matches->hasSuggestion() ) {
133 $apiResult->addValue( [ 'query', 'searchinfo' ],
134 'suggestion', $matches->getSuggestionQuery() );
135 $apiResult->addValue( [ 'query', 'searchinfo' ],
136 'suggestionsnippet', $matches->getSuggestionSnippet() );
137 }
138 if ( isset( $searchInfo['rewrittenquery'] ) && $matches->hasRewrittenQuery() ) {
139 $apiResult->addValue( [ 'query', 'searchinfo' ],
140 'rewrittenquery', $matches->getQueryAfterRewrite() );
141 $apiResult->addValue( [ 'query', 'searchinfo' ],
142 'rewrittenquerysnippet', $matches->getQueryAfterRewriteSnippet() );
143 }
144 }
145
146 $titles = [];
147 $count = 0;
148
149 if ( $matches->hasMoreResults() ) {
150 $this->setContinueEnumParameter( 'offset', $params['offset'] + $params['limit'] );
151 }
152
153 foreach ( $matches as $result ) {
154 $count++;
155 // Silently skip broken and missing titles
156 if ( $result->isBrokenTitle() || $result->isMissingRevision() ) {
157 continue;
158 }
159
160 if ( $resultPageSet === null ) {
161 $vals = $this->getSearchResultData( $result, $prop );
162 if ( $vals ) {
163 // Add item to results and see whether it fits
164 $fit = $apiResult->addValue( [ 'query', $this->getModuleName() ], null, $vals );
165 if ( !$fit ) {
166 $this->setContinueEnumParameter( 'offset', $params['offset'] + $count - 1 );
167 break;
168 }
169 }
170 } else {
171 $titles[] = $result->getTitle();
172 }
173 }
174
175 // Here we assume interwiki results do not count with
176 // regular search results. We may want to reconsider this
177 // if we ever return a lot of interwiki results or want pagination
178 // for them.
179 // Interwiki results inside main result set
180 $canAddInterwiki = (bool)$params['enablerewrites'] && ( $resultPageSet === null );
181 if ( $canAddInterwiki ) {
182 $this->addInterwikiResults( $matches, $apiResult, $prop, 'additional',
183 ISearchResultSet::INLINE_RESULTS );
184 }
185
186 // Interwiki results outside main result set
187 if ( $interwiki && $resultPageSet === null ) {
188 $this->addInterwikiResults( $matches, $apiResult, $prop, 'interwiki',
189 ISearchResultSet::SECONDARY_RESULTS );
190 }
191
192 if ( $resultPageSet === null ) {
193 $apiResult->addIndexedTagName( [
194 'query', $this->getModuleName()
195 ], 'p' );
196 } else {
197 $resultPageSet->setRedirectMergePolicy( function ( $current, $new ) {
198 if ( !isset( $current['index'] ) || $new['index'] < $current['index'] ) {
199 $current['index'] = $new['index'];
200 }
201 return $current;
202 } );
203 $resultPageSet->populateFromTitles( $titles );
204 $offset = $params['offset'] + 1;
205 foreach ( $titles as $index => $title ) {
206 $resultPageSet->setGeneratorData( $title, [ 'index' => $index + $offset ] );
207 }
208 }
209 }
210
217 private function getSearchResultData( SearchResult $result, $prop ) {
218 // Silently skip broken and missing titles
219 if ( $result->isBrokenTitle() || $result->isMissingRevision() ) {
220 return null;
221 }
222
223 $vals = [];
224
225 $title = $result->getTitle();
227 $vals['pageid'] = $title->getArticleID();
228
229 if ( isset( $prop['size'] ) ) {
230 $vals['size'] = $result->getByteSize();
231 }
232 if ( isset( $prop['wordcount'] ) ) {
233 $vals['wordcount'] = $result->getWordCount();
234 }
235 if ( isset( $prop['snippet'] ) ) {
236 $vals['snippet'] = $result->getTextSnippet();
237 }
238 if ( isset( $prop['timestamp'] ) ) {
239 $vals['timestamp'] = wfTimestamp( TS_ISO_8601, $result->getTimestamp() );
240 }
241 if ( isset( $prop['titlesnippet'] ) ) {
242 $vals['titlesnippet'] = $result->getTitleSnippet();
243 }
244 if ( isset( $prop['categorysnippet'] ) ) {
245 $vals['categorysnippet'] = $result->getCategorySnippet();
246 }
247 if ( !is_null( $result->getRedirectTitle() ) ) {
248 if ( isset( $prop['redirecttitle'] ) ) {
249 $vals['redirecttitle'] = $result->getRedirectTitle()->getPrefixedText();
250 }
251 if ( isset( $prop['redirectsnippet'] ) ) {
252 $vals['redirectsnippet'] = $result->getRedirectSnippet();
253 }
254 }
255 if ( !is_null( $result->getSectionTitle() ) ) {
256 if ( isset( $prop['sectiontitle'] ) ) {
257 $vals['sectiontitle'] = $result->getSectionTitle()->getFragment();
258 }
259 if ( isset( $prop['sectionsnippet'] ) ) {
260 $vals['sectionsnippet'] = $result->getSectionSnippet();
261 }
262 }
263 if ( isset( $prop['isfilematch'] ) ) {
264 $vals['isfilematch'] = $result->isFileMatch();
265 }
266
267 if ( isset( $prop['extensiondata'] ) ) {
268 $extra = $result->getExtensionData();
269 // Add augmented data to the result. The data would be organized as a map:
270 // augmentorName => data
271 if ( $extra ) {
272 $vals['extensiondata'] = ApiResult::addMetadataToResultVars( $extra );
273 }
274 }
275
276 return $vals;
277 }
278
288 private function addInterwikiResults(
289 ISearchResultSet $matches, ApiResult $apiResult, $prop,
290 $section, $type
291 ) {
292 $totalhits = null;
293 if ( $matches->hasInterwikiResults( $type ) ) {
294 foreach ( $matches->getInterwikiResults( $type ) as $interwikiMatches ) {
295 // Include number of results if requested
296 $totalhits += $interwikiMatches->getTotalHits();
297
298 foreach ( $interwikiMatches as $result ) {
299 $title = $result->getTitle();
300 $vals = $this->getSearchResultData( $result, $prop );
301
302 $vals['namespace'] = $result->getInterwikiNamespaceText();
303 $vals['title'] = $title->getText();
304 $vals['url'] = $title->getFullURL();
305
306 // Add item to results and see whether it fits
307 $fit = $apiResult->addValue( [
308 'query',
309 $section . $this->getModuleName(),
310 $result->getInterwikiPrefix()
311 ], null, $vals );
312
313 if ( !$fit ) {
314 // We hit the limit. We can't really provide any meaningful
315 // pagination info so just bail out
316 break;
317 }
318 }
319 }
320 if ( $totalhits !== null ) {
321 $apiResult->addValue( [ 'query', $section . 'searchinfo' ], 'totalhits', $totalhits );
322 $apiResult->addIndexedTagName( [
323 'query', $section . $this->getModuleName()
324 ], 'p' );
325 }
326 }
327 return $totalhits;
328 }
329
330 public function getCacheMode( $params ) {
331 return 'public';
332 }
333
334 public function getAllowedParams() {
335 if ( $this->allowedParams !== null ) {
337 }
338
339 $this->allowedParams = $this->buildCommonApiParams() + [
340 'what' => [
342 'title',
343 'text',
344 'nearmatch',
345 ]
346 ],
347 'info' => [
348 ApiBase::PARAM_DFLT => 'totalhits|suggestion|rewrittenquery',
350 'totalhits',
351 'suggestion',
352 'rewrittenquery',
353 ],
355 ],
356 'prop' => [
357 ApiBase::PARAM_DFLT => 'size|wordcount|timestamp|snippet',
359 'size',
360 'wordcount',
361 'timestamp',
362 'snippet',
363 'titlesnippet',
364 'redirecttitle',
365 'redirectsnippet',
366 'sectiontitle',
367 'sectionsnippet',
368 'isfilematch',
369 'categorysnippet',
370 'score', // deprecated
371 'hasrelated', // deprecated
372 'extensiondata',
373 ],
377 'score' => true,
378 'hasrelated' => true
379 ],
380 ],
381 'interwiki' => false,
382 'enablerewrites' => false,
383 ];
384
385 // If we have more than one engine the list of available sorts is
386 // difficult to represent. For now don't expose it.
387 $services = MediaWiki\MediaWikiServices::getInstance();
388 $alternatives = $services
389 ->getSearchEngineConfig()
390 ->getSearchTypes();
391 if ( count( $alternatives ) == 1 ) {
392 $this->allowedParams['sort'] = [
393 ApiBase::PARAM_DFLT => 'relevance',
394 ApiBase::PARAM_TYPE => $services
395 ->newSearchEngine()
396 ->getValidSorts(),
397 ];
398 }
399
401 }
402
403 public function getSearchProfileParams() {
404 return [
405 'qiprofile' => [
406 'profile-type' => SearchEngine::FT_QUERY_INDEP_PROFILE_TYPE,
407 'help-message' => 'apihelp-query+search-param-qiprofile',
408 ],
409 ];
410 }
411
412 protected function getExamplesMessages() {
413 return [
414 'action=query&list=search&srsearch=meaning'
415 => 'apihelp-query+search-example-simple',
416 'action=query&list=search&srwhat=text&srsearch=meaning'
417 => 'apihelp-query+search-example-text',
418 'action=query&generator=search&gsrsearch=meaning&prop=info'
419 => 'apihelp-query+search-example-generator',
420 ];
421 }
422
423 public function getHelpUrls() {
424 return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Search';
425 }
426}
wfTimestamp( $outputtype=TS_UNIX, $ts=0)
Get a timestamp string in one of various formats.
wfDeprecated( $function, $version=false, $component=false, $callerOffset=2)
Throws a warning that $function is deprecated.
buildSearchEngine(array $params=null)
Build the search engine to use.
buildCommonApiParams( $isScrollable=true)
The set of api parameters that are shared between api calls that call the SearchEngine.
Definition SearchApi.php:47
dieWithError( $msg, $code=null, $data=null, $httpCode=null)
Abort execution with an error.
Definition ApiBase.php:2014
const PARAM_DEPRECATED_VALUES
(array) When PARAM_TYPE is an array, this indicates which of the values are deprecated.
Definition ApiBase.php:209
getMain()
Get the main module.
Definition ApiBase.php:536
const PARAM_TYPE
(string|string[]) Either an array of allowed value strings, or a string type as described below.
Definition ApiBase.php:94
const PARAM_DFLT
(null|boolean|integer|string) Default value of the parameter.
Definition ApiBase.php:55
const PARAM_HELP_MSG_PER_VALUE
((string|array|Message)[]) When PARAM_TYPE is an array, this is an array mapping those values to $msg...
Definition ApiBase.php:164
getResult()
Get the result object.
Definition ApiBase.php:640
extractRequestParams( $options=[])
Using getAllowedParams(), this function makes an array of the values provided by the user,...
Definition ApiBase.php:761
getModuleName()
Get the name of the module being executed by this instance.
Definition ApiBase.php:520
dieStatus(StatusValue $status)
Throw an ApiUsageException based on the Status object.
Definition ApiBase.php:2086
const PARAM_ISMULTI
(boolean) Accept multiple pipe-separated values for this parameter (e.g.
Definition ApiBase.php:58
static addTitleInfo(&$arr, $title, $prefix='')
Add information (title and namespace) about a Title object to a result array.
setContinueEnumParameter( $paramName, $paramValue)
Overridden to set the generator param if in generator mode.
Query module to perform full text search within wiki titles and content.
run( $resultPageSet=null)
execute()
Evaluates the parameters, performs the requested query, and sets up the result.
getHelpUrls()
Return links to more detailed help pages about the module.
getExamplesMessages()
Returns usage examples for this module.
__construct(ApiQuery $query, $moduleName)
getSearchResultData(SearchResult $result, $prop)
Assemble search result data.
getCacheMode( $params)
Get the cache mode for the data generated by this module.
getAllowedParams()
Returns an array of allowed parameters (parameter name) => (default value) or (parameter name) => (ar...
addInterwikiResults(ISearchResultSet $matches, ApiResult $apiResult, $prop, $section, $type)
Add interwiki results as a section in query results.
executeGenerator( $resultPageSet)
Execute this module as a generator.
array $allowedParams
list of api allowed params
This is the main query class.
Definition ApiQuery.php:37
This class represents the result of the API operations.
Definition ApiResult.php:35
static addMetadataToResultVars( $vars, $forceHash=true)
Add the correct metadata to an array of vars we want to export through the API.
addIndexedTagName( $path, $tag)
Set the tag name for numeric-keyed values in XML format.
addValue( $path, $name, $value, $flags=0)
Add value to the output data at the given path.
NOTE: this class is being refactored into an abstract base class.
Generic operation result class Has warning/error list, boolean status and arbitrary value.
Definition Status.php:40
trait SearchApi
Traits for API components that use a SearchEngine.
Definition SearchApi.php:29
A set of SearchEngine results.
return true
Definition router.php:94