3 use MediaWiki\MediaWikiServices
;
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.
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.
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
26 * Traits for API components that use a SearchEngine.
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
37 private static $BACKEND_NULL_PARAM = 'database-backed';
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().
44 * @param bool $isScrollable True if the api offers scrolling
47 public function buildCommonApiParams( $isScrollable = true ) {
50 ApiBase
::PARAM_TYPE
=> 'string',
51 ApiBase
::PARAM_REQUIRED
=> true,
54 ApiBase
::PARAM_DFLT
=> NS_MAIN
,
55 ApiBase
::PARAM_TYPE
=> 'namespace',
56 ApiBase
::PARAM_ISMULTI
=> true,
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
,
66 if ( $isScrollable ) {
68 ApiBase
::PARAM_DFLT
=> 0,
69 ApiBase
::PARAM_TYPE
=> 'integer',
70 ApiBase
::PARAM_HELP_MSG
=> 'api-help-param-continue',
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;
80 $params['backend'] = [
81 ApiBase
::PARAM_DFLT
=> $searchConfig->getSearchType(),
82 ApiBase
::PARAM_TYPE
=> $alternatives,
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.
90 $params +
= $this->buildProfileApiParam();
97 * Build the profile api param definitions. Makes bold assumption only one search
98 * engine is available, ensure that is true before calling.
100 * @return array array containing available additional api param definitions.
101 * Empty if profiles are not supported by the searchEngine implementation.
103 private function buildProfileApiParam() {
104 $configs = $this->getSearchProfileParams();
105 $searchEngine = MediaWikiServices
::getInstance()->newSearchEngine();
107 foreach ( $configs as $paramName => $paramConfig ) {
108 $profiles = $searchEngine->getProfiles( $paramConfig['profile-type'],
109 $this->getContext()->getUser() );
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'];
122 if ( !empty( $profile['default'] ) ) {
123 $defaultProfile = $profile['name'];
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,
139 * Build the search engine to use.
140 * If $params is provided then the following searchEngine options
142 * - backend: which search backend to use
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
151 public function buildSearchEngine( array $params = null ) {
152 if ( $params != null ) {
153 $type = $params['backend'] ??
null;
154 if ( $type === self
::$BACKEND_NULL_PARAM ) {
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 );
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'],
174 $searchEngine = MediaWikiServices
::getInstance()->newSearchEngine();
176 return $searchEngine;
180 * @return array[] array of arrays mapping from parameter name to a two value map
181 * containing 'help-message' and 'profile-type' keys.
183 abstract public function getSearchProfileParams();
186 * @return IContextSource
188 abstract public function getContext();