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.
102 * @suppress PhanTypeMismatchDimFetch
104 private function buildProfileApiParam() {
105 $configs = $this->getSearchProfileParams();
106 $searchEngine = MediaWikiServices
::getInstance()->newSearchEngine();
108 foreach ( $configs as $paramName => $paramConfig ) {
109 $profiles = $searchEngine->getProfiles( $paramConfig['profile-type'],
110 $this->getContext()->getUser() );
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'];
124 if ( !empty( $profile['default'] ) ) {
125 $defaultProfile = $profile['name'];
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,
141 * Build the search engine to use.
142 * If $params is provided then the following searchEngine options
144 * - backend: which search backend to use
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
153 public function buildSearchEngine( array $params = null ) {
154 if ( $params != null ) {
155 $type = $params['backend'] ??
null;
156 if ( $type === self
::$BACKEND_NULL_PARAM ) {
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 );
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'],
176 $searchEngine = MediaWikiServices
::getInstance()->newSearchEngine();
178 return $searchEngine;
182 * @return array[] array of arrays mapping from parameter name to a two value map
183 * containing 'help-message' and 'profile-type' keys.
185 abstract public function getSearchProfileParams();
188 * @return IContextSource
190 abstract public function getContext();