MediaWiki  master
ApiQuerySearch.php
Go to the documentation of this file.
1 <?php
29  use SearchApi;
30 
32  private $allowedParams;
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',
184  }
185 
186  // Interwiki results outside main result set
187  if ( $interwiki && $resultPageSet === null ) {
188  $this->addInterwikiResults( $matches, $apiResult, $prop, 'interwiki',
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 ) {
336  return $this->allowedParams;
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  ],
354  ApiBase::PARAM_ISMULTI => true,
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  ],
374  ApiBase::PARAM_ISMULTI => true,
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.
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 
400  return $this->allowedParams;
401  }
402 
403  public function getSearchProfileParams() {
404  return [
405  'qiprofile' => [
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 }
const PARAM_TYPE
(string|string[]) Either an array of allowed value strings, or a string type as described below...
Definition: ApiBase.php:94
getInterwikiResults( $type=self::SECONDARY_RESULTS)
Return a result set of hits on other (multiple) wikis associated with this one.
static addTitleInfo(&$arr, $title, $prefix='')
Add information (title and namespace) about a Title object to a result array.
getResult()
Get the result object.
Definition: ApiBase.php:640
dieStatus(StatusValue $status)
Throw an ApiUsageException based on the Status object.
Definition: ApiBase.php:2078
const INLINE_RESULTS
Identifier for interwiki results that can be displayed even if no existing main wiki results exist...
const PARAM_DFLT
(null|boolean|integer|string) Default value of the parameter.
Definition: ApiBase.php:55
getMain()
Get the main module.
Definition: ApiBase.php:536
trait SearchApi
Traits for API components that use a SearchEngine.
Definition: SearchApi.php:29
buildCommonApiParams( $isScrollable=true)
The set of api parameters that are shared between api calls that call the SearchEngine.
Definition: SearchApi.php:47
getCacheMode( $params)
dieWithError( $msg, $code=null, $data=null, $httpCode=null)
Abort execution with an error.
Definition: ApiBase.php:2006
extractRequestParams( $options=[])
Using getAllowedParams(), this function makes an array of the values provided by the user...
Definition: ApiBase.php:761
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
setContinueEnumParameter( $paramName, $paramValue)
Overridden to set the generator param if in generator mode.
addValue( $path, $name, $value, $flags=0)
Add value to the output data at the given path.
Definition: ApiResult.php:405
static getInstance()
Returns the global default instance of the top level service locator.
wfTimestamp( $outputtype=TS_UNIX, $ts=0)
Get a timestamp string in one of various formats.
hasInterwikiResults( $type=self::SECONDARY_RESULTS)
Check if there are results on other wikis.
__construct(ApiQuery $query, $moduleName)
static addMetadataToResultVars( $vars, $forceHash=true)
Add the correct metadata to an array of vars we want to export through the API.
Definition: ApiResult.php:1150
getModuleName()
Get the name of the module being executed by this instance.
Definition: ApiBase.php:520
This class represents the result of the API operations.
Definition: ApiResult.php:35
This is the main query class.
Definition: ApiQuery.php:37
const FT_QUERY_INDEP_PROFILE_TYPE
Profile type for query independent ranking features.
buildSearchEngine(array $params=null)
Build the search engine to use.
Definition: SearchApi.php:153
const SECONDARY_RESULTS
Identifier for interwiki results that are displayed only together with existing main wiki results...
wfDeprecated( $function, $version=false, $component=false, $callerOffset=2)
Throws a warning that $function is deprecated.
addIndexedTagName( $path, $tag)
Set the tag name for numeric-keyed values in XML format.
Definition: ApiResult.php:629
const PARAM_DEPRECATED_VALUES
(array) When PARAM_TYPE is an array, this indicates which of the values are deprecated.
Definition: ApiBase.php:209
const PARAM_ISMULTI
(boolean) Accept multiple pipe-separated values for this parameter (e.g.
Definition: ApiBase.php:58
run( $resultPageSet=null)
array $allowedParams
list of api allowed params
addInterwikiResults(ISearchResultSet $matches, ApiResult $apiResult, $prop, $section, $type)
Add interwiki results as a section in query results.
getSearchResultData(SearchResult $result, $prop)
Assemble search result data.
executeGenerator( $resultPageSet)
return true
Definition: router.php:92
Query module to perform full text search within wiki titles and content.
$matches