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          * @suppress PhanTypeMismatchDimFetch
 103          */
 104         private function buildProfileApiParam() {
 105                 $configs = $this->getSearchProfileParams();
 106                 $searchEngine = MediaWikiServices::getInstance()->newSearchEngine();
 107                 $params = [];
 108                 foreach ( $configs as $paramName => $paramConfig ) {
 109                         $profiles = $searchEngine->getProfiles( $paramConfig['profile-type'],
 110                                 $this->getContext()->getUser() );
 111                         if ( !$profiles ) {
 112                                 continue;
 113                         }
 114
 115                         $types = [];
 116                         $helpMessages = [];
 117                         $defaultProfile = null;
 118                         foreach ( $profiles as $profile ) {
 119                                 $types[] = $profile['name'];
 120                                 if ( isset( $profile['desc-message'] ) ) {
 121                                         $helpMessages[$profile['name']] = $profile['desc-message'];
 122                                 }
 123
 124                                 if ( !empty( $profile['default'] ) ) {
 125                                         $defaultProfile = $profile['name'];
 126                                 }
 127                         }
 128
 129                         $params[$paramName] = [
 130                                 ApiBase::PARAM_TYPE => $types,
 131                                 ApiBase::PARAM_HELP_MSG => $paramConfig['help-message'],
 132                                 ApiBase::PARAM_HELP_MSG_PER_VALUE => $helpMessages,
 133                                 ApiBase::PARAM_DFLT => $defaultProfile,
 134                         ];
 135                 }
 136
 137                 return $params;
 138         }
 139
 140         /**
 141          * Build the search engine to use.
 142          * If $params is provided then the following searchEngine options
 143          * will be set:
 144          *  - backend: which search backend to use
 145          *  - limit: mandatory
 146          *  - offset: optional
 147          *  - namespace: mandatory
 148          *  - search engine profiles defined by SearchApi::getSearchProfileParams()
 149          * @param string[]|null $params API request params (must be sanitized by
 150          * ApiBase::extractRequestParams() before)
 151          * @return SearchEngine the search engine
 152          */
 153         public function buildSearchEngine( array $params = null ) {
 154                 if ( $params != null ) {
 155                         $type = $params['backend'] ?? null;
 156                         if ( $type === self::$BACKEND_NULL_PARAM ) {
 157                                 $type = null;
 158                         }
 159                         $searchEngine = MediaWikiServices::getInstance()->getSearchEngineFactory()->create( $type );
 160                         $limit = $params['limit'];
 161                         $searchEngine->setNamespaces( $params['namespace'] );
 162                         $offset = $params['offset'] ?? null;
 163                         $searchEngine->setLimitOffset( $limit, $offset );
 164
 165                         // Initialize requested search profiles.
 166                         $configs = $this->getSearchProfileParams();
 167                         foreach ( $configs as $paramName => $paramConfig ) {
 168                                 if ( isset( $params[$paramName] ) ) {
 169                                         $searchEngine->setFeatureData(
 170                                                 $paramConfig['profile-type'],
 171                                                 $params[$paramName]
 172                                         );
 173                                 }
 174                         }
 175                 } else {
 176                         $searchEngine = MediaWikiServices::getInstance()->newSearchEngine();
 177                 }
 178                 return $searchEngine;
 179         }
 180
 181         /**
 182          * @return array[] array of arrays mapping from parameter name to a two value map
 183          *  containing 'help-message' and 'profile-type' keys.
 184          */
 185         abstract public function getSearchProfileParams();
 186
 187         /**
 188          * @return IContextSource
 189          */
 190         abstract public function getContext();
 191 }