includes/api/SearchApi.php

   1 <?php
   2 use MediaWiki\MediaWikiServices;
   3
   4 /**
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @since 1.28
  22  */
  23
  24 /**
  25  * Traits for API components that use a SearchEngine.
  26  * @ingroup API
  27  */
  28 trait SearchApi {
  29         /**
  30          * Build the profile api param definitions.
  31          *
  32          * @param string $profileType type of profile to customize
  33          * @param string $helpMsg i18n message
  34          * @param string|null $backendType SearchEngine backend type or null for default engine
  35          * @return array|null the api param definition or null if profiles are
  36          * not supported by the searchEngine implementation.
  37          */
  38         public function buildProfileApiParam( $profileType, $helpMsg, $backendType = null ) {
  39                 $searchEngine = null;
  40                 if ( $backendType !== null ) {
  41                         $searchEngine = MediaWikiServices::getInstance()
  42                                 ->getSearchEngineFactory()->create( $backendType );
  43                 } else {
  44                         $searchEngine = MediaWikiServices::getInstance()->newSearchEngine();
  45                 }
  46
  47                 $profiles = $searchEngine->getProfiles( $profileType );
  48                 if ( $profiles ) {
  49                         $types = [];
  50                         $helpMessages = [];
  51                         $defaultProfile = null;
  52                         foreach ( $profiles as $profile ) {
  53                                 $types[] = $profile['name'];
  54                                 if ( isset ( $profile['desc-message'] ) ) {
  55                                         $helpMessages[$profile['name']] = $profile['desc-message'];
  56                                 }
  57                                 if ( !empty( $profile['default'] ) ) {
  58                                         $defaultProfile = $profile['name'];
  59                                 }
  60                         }
  61                         return [
  62                                 ApiBase::PARAM_TYPE => $types,
  63                                 ApiBase::PARAM_HELP_MSG => $helpMsg,
  64                                 ApiBase::PARAM_HELP_MSG_PER_VALUE => $helpMessages,
  65                                 ApiBase::PARAM_DFLT => $defaultProfile,
  66                         ];
  67                 }
  68                 return null;
  69         }
  70
  71         /**
  72          * Build the search engine to use.
  73          * If $params is provided then the following searchEngine options
  74          * will be set:
  75          *  - limit: mandatory
  76          *  - offset: optional, if set limit will be incremented by
  77          *    one ( to support the continue parameter )
  78          *  - namespace: mandatory
  79          *  - search engine profiles defined by SearchApi::getSearchProfileParams()
  80          * @param string[]|null API request params (must be sanitized by
  81          * ApiBase::extractRequestParams() before)
  82          * @return SearchEngine the search engine
  83          */
  84         public function buildSearchEngine( array $params = null ) {
  85                 if ( $params != null ) {
  86                         $type = isset( $params['backend'] ) ? $params['backend'] : null;
  87                         $searchEngine = MediaWikiServices::getInstance()->getSearchEngineFactory()->create( $type );
  88                         $limit = $params['limit'];
  89                         $searchEngine->setNamespaces( $params['namespace'] );
  90                         $offset = null;
  91                         if ( isset( $params['offset'] ) ) {
  92                                 // If the API supports offset then it probably
  93                                 // wants to fetch limit+1 so it can check if
  94                                 // more results are available to properly set
  95                                 // the continue param
  96                                 $offset = $params['offset'];
  97                                 $limit += 1;
  98                         }
  99                         $searchEngine->setLimitOffset( $limit, $offset );
 100                         foreach ( $this->getSearchProfileParams() as $type => $param ) {
 101                                 if ( isset( $params[$param] ) ) {
 102                                         $searchEngine->setFeatureData( $type, $params[$param] );
 103                                 }
 104                         }
 105                 } else {
 106                         $searchEngine = MediaWikiServices::getInstance()->newSearchEngine();
 107                 }
 108                 return $searchEngine;
 109         }
 110
 111         /**
 112          * @return string[] the list of supported search profile types. Key is
 113          * the profile type and its associated value is the request param.
 114          */
 115         abstract public function getSearchProfileParams();
 116 }