includes/api/SearchApi.php

   1 <?php
   2
   3 use MediaWiki\MediaWikiServices;
   4
   5 /**
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along
  17  * with this program; if not, write to the Free Software Foundation, Inc.,
  18  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  19  * http://www.gnu.org/copyleft/gpl.html
  20  *
  21  * @file
  22  * @since 1.28
  23  */
  24
  25 /**
  26  * Traits for API components that use a SearchEngine.
  27  * @ingroup API
  28  */
  29 trait SearchApi {
  30
  31         /**
  32          * When $wgSearchType is null, $wgSearchAlternatives[0] is null. Null isn't
  33          * a valid option for an array for PARAM_TYPE, so we'll use a fake name
  34          * that can't possibly be a class name and describes what the null behavior
  35          * does
  36          */
  37         private static $BACKEND_NULL_PARAM = 'database-backed';
  38
  39         /**
  40          * The set of api parameters that are shared between api calls that
  41          * call the SearchEngine. Primarily this defines parameters that
  42          * are utilized by self::buildSearchEngine().
  43          *
  44          * @param bool $isScrollable True if the api offers scrolling
  45          * @return array
  46          */
  47         public function buildCommonApiParams( $isScrollable = true ) {
  48                 $params = [
  49                         'search' => [
  50                                 ApiBase::PARAM_TYPE => 'string',
  51                                 ApiBase::PARAM_REQUIRED => true,
  52                         ],
  53                         'namespace' => [
  54                                 ApiBase::PARAM_DFLT => NS_MAIN,
  55                                 ApiBase::PARAM_TYPE => 'namespace',
  56                                 ApiBase::PARAM_ISMULTI => true,
  57                         ],
  58                         'limit' => [
  59                                 ApiBase::PARAM_DFLT => 10,
  60                                 ApiBase::PARAM_TYPE => 'limit',
  61                                 ApiBase::PARAM_MIN => 1,
  62                                 ApiBase::PARAM_MAX => ApiBase::LIMIT_BIG1,
  63                                 ApiBase::PARAM_MAX2 => ApiBase::LIMIT_BIG2,
  64                         ],
  65                 ];
  66                 if ( $isScrollable ) {
  67                         $params['offset'] = [
  68                                 ApiBase::PARAM_DFLT => 0,
  69                                 ApiBase::PARAM_TYPE => 'integer',
  70                                 ApiBase::PARAM_HELP_MSG => 'api-help-param-continue',
  71                         ];
  72                 }
  73
  74                 $searchConfig = MediaWikiServices::getInstance()->getSearchEngineConfig();
  75                 $alternatives = $searchConfig->getSearchTypes();
  76                 if ( count( $alternatives ) > 1 ) {
  77                         if ( $alternatives[0] === null ) {
  78                                 $alternatives[0] = self::$BACKEND_NULL_PARAM;
  79                         }
  80                         $params['backend'] = [
  81                                 ApiBase::PARAM_DFLT => $searchConfig->getSearchType(),
  82                                 ApiBase::PARAM_TYPE => $alternatives,
  83                         ];
  84                         // @todo: support profile selection when multiple
  85                         // backends are available. The solution could be to
  86                         // merge all possible profiles and let ApiBase
  87                         // subclasses do the check. Making ApiHelp and ApiSandbox
  88                         // comprehensive might be more difficult.
  89                 } else {
  90                         $params += $this->buildProfileApiParam();
  91                 }
  92
  93                 return $params;
  94         }
  95
  96         /**
  97          * Build the profile api param definitions. Makes bold assumption only one search
  98          * engine is available, ensure that is true before calling.
  99          *
 100          * @return array array containing available additional api param definitions.
 101          *  Empty if profiles are not supported by the searchEngine implementation.
 102          */
 103         private function buildProfileApiParam() {
 104                 $configs = $this->getSearchProfileParams();
 105                 $searchEngine = MediaWikiServices::getInstance()->newSearchEngine();
 106                 $params = [];
 107                 foreach ( $configs as $paramName => $paramConfig ) {
 108                         $profiles = $searchEngine->getProfiles( $paramConfig['profile-type'],
 109                                 $this->getContext()->getUser() );
 110                         if ( !$profiles ) {
 111                                 continue;
 112                         }
 113
 114                         $types = [];
 115                         $helpMessages = [];
 116                         $defaultProfile = null;
 117                         foreach ( $profiles as $profile ) {
 118                                 $types[] = $profile['name'];
 119                                 if ( isset( $profile['desc-message'] ) ) {
 120                                         $helpMessages[$profile['name']] = $profile['desc-message'];
 121                                 }
 122                                 if ( !empty( $profile['default'] ) ) {
 123                                         $defaultProfile = $profile['name'];
 124                                 }
 125                         }
 126
 127                         $params[$paramName] = [
 128                                 ApiBase::PARAM_TYPE => $types,
 129                                 ApiBase::PARAM_HELP_MSG => $paramConfig['help-message'],
 130                                 ApiBase::PARAM_HELP_MSG_PER_VALUE => $helpMessages,
 131                                 ApiBase::PARAM_DFLT => $defaultProfile,
 132                         ];
 133                 }
 134
 135                 return $params;
 136         }
 137
 138         /**
 139          * Build the search engine to use.
 140          * If $params is provided then the following searchEngine options
 141          * will be set:
 142          *  - backend: which search backend to use
 143          *  - limit: mandatory
 144          *  - offset: optional
 145          *  - namespace: mandatory
 146          *  - search engine profiles defined by SearchApi::getSearchProfileParams()
 147          * @param string[]|null $params API request params (must be sanitized by
 148          * ApiBase::extractRequestParams() before)
 149          * @return SearchEngine the search engine
 150          */
 151         public function buildSearchEngine( array $params = null ) {
 152                 if ( $params != null ) {
 153                         $type = $params['backend'] ?? null;
 154                         if ( $type === self::$BACKEND_NULL_PARAM ) {
 155                                 $type = null;
 156                         }
 157                         $searchEngine = MediaWikiServices::getInstance()->getSearchEngineFactory()->create( $type );
 158                         $limit = $params['limit'];
 159                         $searchEngine->setNamespaces( $params['namespace'] );
 160                         $offset = $params['offset'] ?? null;
 161                         $searchEngine->setLimitOffset( $limit, $offset );
 162
 163                         // Initialize requested search profiles.
 164                         $configs = $this->getSearchProfileParams();
 165                         foreach ( $configs as $paramName => $paramConfig ) {
 166                                 if ( isset( $params[$paramName] ) ) {
 167                                         $searchEngine->setFeatureData(
 168                                                 $paramConfig['profile-type'],
 169                                                 $params[$paramName]
 170                                         );
 171                                 }
 172                         }
 173                 } else {
 174                         $searchEngine = MediaWikiServices::getInstance()->newSearchEngine();
 175                 }
 176                 return $searchEngine;
 177         }
 178
 179         /**
 180          * @return array[] array of arrays mapping from parameter name to a two value map
 181          *  containing 'help-message' and 'profile-type' keys.
 182          */
 183         abstract public function getSearchProfileParams();
 184
 185         /**
 186          * @return IContextSource
 187          */
 188         abstract public function getContext();
 189 }