SearchApi.php

Go to the documentation of this file.

<?php
 
namespace MediaWiki\Api;
 
use LogicException;
use MediaWiki\Context\IContextSource;
use SearchEngine;
use SearchEngineConfig;
use SearchEngineFactory;
use Wikimedia\ParamValidator\ParamValidator;
use Wikimedia\ParamValidator\TypeDef\IntegerDef;
 
trait SearchApi {
 
    private SearchEngineConfig $searchEngineConfig;
    private SearchEngineFactory $searchEngineFactory;
 
    private function checkDependenciesSet() {
        // Since this is a trait, we can't have a constructor where the services
        // that we need are injected. Instead, the api modules that use this trait
        // are responsible for setting them (since api modules *can* have services
        // injected). Double check that the api module did indeed set them
        // @phan-suppress-next-line PhanRedundantCondition Phan trusts the type hints too much
        if ( !isset( $this->searchEngineConfig ) || !isset( $this->searchEngineFactory ) ) {
            throw new LogicException(
                'SearchApi requires both a SearchEngineConfig and SearchEngineFactory to be set'
            );
        }
    }
 
    private static $BACKEND_NULL_PARAM = 'database-backed';
 
    public function buildCommonApiParams( $isScrollable = true ) {
        $this->checkDependenciesSet();
 
        $params = [
            'search' => [
                ParamValidator::PARAM_TYPE => 'string',
                ParamValidator::PARAM_REQUIRED => true,
            ],
            'namespace' => [
                ParamValidator::PARAM_DEFAULT => NS_MAIN,
                ParamValidator::PARAM_TYPE => 'namespace',
                ParamValidator::PARAM_ISMULTI => true,
            ],
            'limit' => [
                ParamValidator::PARAM_DEFAULT => 10,
                ParamValidator::PARAM_TYPE => 'limit',
                IntegerDef::PARAM_MIN => 1,
                IntegerDef::PARAM_MAX => ApiBase::LIMIT_BIG1,
                IntegerDef::PARAM_MAX2 => ApiBase::LIMIT_BIG2,
            ],
        ];
        if ( $isScrollable ) {
            $params['offset'] = [
                ParamValidator::PARAM_DEFAULT => 0,
                IntegerDef::PARAM_MIN => 0,
                ParamValidator::PARAM_TYPE => 'integer',
                ApiBase::PARAM_HELP_MSG => 'api-help-param-continue',
            ];
        }
 
        $alternatives = $this->searchEngineConfig->getSearchTypes();
        if ( count( $alternatives ) > 1 ) {
            $alternatives[0] ??= self::$BACKEND_NULL_PARAM;
            $params['backend'] = [
                ParamValidator::PARAM_DEFAULT => $this->searchEngineConfig->getSearchType(),
                ParamValidator::PARAM_TYPE => $alternatives,
            ];
            // @todo: support profile selection when multiple
            // backends are available. The solution could be to
            // merge all possible profiles and let ApiBase
            // subclasses do the check. Making ApiHelp and ApiSandbox
            // comprehensive might be more difficult.
        } else {
            $params += $this->buildProfileApiParam();
        }
 
        return $params;
    }
 
    private function buildProfileApiParam() {
        $this->checkDependenciesSet();
 
        $configs = $this->getSearchProfileParams();
        $searchEngine = $this->searchEngineFactory->create();
        $params = [];
        foreach ( $configs as $paramName => $paramConfig ) {
            $profiles = $searchEngine->getProfiles(
                $paramConfig['profile-type'],
                $this->getContext()->getUser()
            );
            if ( !$profiles ) {
                continue;
            }
 
            $types = [];
            $helpMessages = [];
            $defaultProfile = null;
            foreach ( $profiles as $profile ) {
                $types[] = $profile['name'];
                if ( isset( $profile['desc-message'] ) ) {
                    $helpMessages[$profile['name']] = $profile['desc-message'];
                }
 
                if ( !empty( $profile['default'] ) ) {
                    $defaultProfile = $profile['name'];
                }
            }
 
            $params[$paramName] = [
                ParamValidator::PARAM_TYPE => $types,
                ApiBase::PARAM_HELP_MSG => $paramConfig['help-message'],
                ApiBase::PARAM_HELP_MSG_PER_VALUE => $helpMessages,
                ParamValidator::PARAM_DEFAULT => $defaultProfile,
            ];
        }
 
        return $params;
    }
 
    public function buildSearchEngine( ?array $params = null ) {
        $this->checkDependenciesSet();
 
        if ( $params == null ) {
            return $this->searchEngineFactory->create();
        }
 
        $type = $params['backend'] ?? null;
        if ( $type === self::$BACKEND_NULL_PARAM ) {
            $type = null;
        }
        $searchEngine = $this->searchEngineFactory->create( $type );
        $searchEngine->setNamespaces( $params['namespace'] );
        $searchEngine->setLimitOffset( $params['limit'], $params['offset'] ?? 0 );
 
        // Initialize requested search profiles.
        $configs = $this->getSearchProfileParams();
        foreach ( $configs as $paramName => $paramConfig ) {
            if ( isset( $params[$paramName] ) ) {
                $searchEngine->setFeatureData(
                    $paramConfig['profile-type'],
                    $params[$paramName]
                );
            }
        }
        return $searchEngine;
    }
 
    abstract public function getSearchProfileParams();
 
    abstract public function getContext();
}
 
class_alias( SearchApi::class, 'SearchApi' );