SearchEngine.php

Go to the documentation of this file.

<?php
use MediaWiki\Config\Config;
use MediaWiki\Exception\MWUnknownContentModelException;
use MediaWiki\HookContainer\HookContainer;
use MediaWiki\HookContainer\HookRunner;
use MediaWiki\MediaWikiServices;
use MediaWiki\Search\TitleMatcher;
use MediaWiki\Status\Status;
use MediaWiki\Title\Title;
use MediaWiki\User\User;
 
abstract class SearchEngine {
    public const DEFAULT_SORT = 'relevance';
 
    public $prefix = '';
 
    public $namespaces = [ NS_MAIN ];
 
    protected $limit = 10;
 
    protected $offset = 0;
 
    protected $searchTerms = [];
 
    protected $showSuggestion = true;
    private $sort = self::DEFAULT_SORT;
 
    protected $features = [];
 
    private $hookContainer;
 
    private $hookRunner;
 
    public const COMPLETION_PROFILE_TYPE = 'completionSearchProfile';
 
    public const FT_QUERY_INDEP_PROFILE_TYPE = 'fulltextQueryIndepProfile';
 
    public const FT_QUERY_DEP_PROFILE_TYPE = 'fulltextQueryDepProfile';
 
    protected const CHARS_ALL = 1;
 
    protected const CHARS_NO_SYNTAX = 2;
 
    public function searchText( $term ) {
        return $this->maybePaginate( function () use ( $term ) {
            return $this->doSearchText( $term );
        } );
    }
 
    protected function doSearchText( $term ) {
        return null;
    }
 
    public function searchArchiveTitle( $term ) {
        return $this->doSearchArchiveTitle( $term );
    }
 
    protected function doSearchArchiveTitle( $term ) {
        return Status::newGood( [] );
    }
 
    public function searchTitle( $term ) {
        return $this->maybePaginate( function () use ( $term ) {
            return $this->doSearchTitle( $term );
        } );
    }
 
    protected function doSearchTitle( $term ) {
        return null;
    }
 
    private function maybePaginate( Closure $fn ) {
        if ( $this instanceof PaginatingSearchEngine ) {
            return $fn();
        }
        $this->limit++;
        try {
            $resultSetOrStatus = $fn();
        } finally {
            $this->limit--;
        }
 
        $resultSet = null;
        if ( $resultSetOrStatus instanceof ISearchResultSet ) {
            $resultSet = $resultSetOrStatus;
        } elseif ( $resultSetOrStatus instanceof Status &&
            $resultSetOrStatus->getValue() instanceof ISearchResultSet
        ) {
            $resultSet = $resultSetOrStatus->getValue();
        }
        if ( $resultSet ) {
            $resultSet->shrink( $this->limit );
        }
 
        return $resultSetOrStatus;
    }
 
    public function supports( $feature ) {
        switch ( $feature ) {
            case 'search-update':
                return true;
            case 'title-suffix-filter':
            default:
                return false;
        }
    }
 
    public function setFeatureData( $feature, $data ) {
        $this->features[$feature] = $data;
    }
 
    public function getFeatureData( $feature ) {
        return $this->features[$feature] ?? null;
    }
 
    public function normalizeText( $string ) {
        // Some languages such as Chinese require word segmentation
        return MediaWikiServices::getInstance()->getContentLanguage()->segmentByWord( $string );
    }
 
    public function getNearMatcher( Config $config ) {
        return MediaWikiServices::getInstance()->getTitleMatcher();
    }
 
    protected static function defaultNearMatcher() {
        wfDeprecated( __METHOD__, '1.40' );
        return MediaWikiServices::getInstance()->getTitleMatcher();
    }
 
    public function legalSearchChars( $type = self::CHARS_ALL ) {
        return "A-Za-z_'.0-9\\x80-\\xFF\\-";
    }
 
    public function setLimitOffset( $limit, $offset = 0 ) {
        $this->limit = intval( $limit );
        $this->offset = intval( $offset );
    }
 
    public function setNamespaces( $namespaces ) {
        if ( $namespaces ) {
            // Filter namespaces to only keep valid ones
            $validNs = MediaWikiServices::getInstance()->getSearchEngineConfig()->searchableNamespaces();
            $namespaces = array_filter( $namespaces,
                static fn ( $id ) => $id < 0 || isset( $validNs[$id] )
            );
        } else {
            $namespaces = [];
        }
        $this->namespaces = $namespaces;
    }
 
    public function setShowSuggestion( $showSuggestion ) {
        $this->showSuggestion = $showSuggestion;
    }
 
    public function getValidSorts() {
        return [ self::DEFAULT_SORT ];
    }
 
    public function setSort( $sort ) {
        if ( !in_array( $sort, $this->getValidSorts() ) ) {
            throw new InvalidArgumentException( "Invalid sort: $sort. " .
                "Must be one of: " . implode( ', ', $this->getValidSorts() ) );
        }
        $this->sort = $sort;
    }
 
    public function getSort() {
        return $this->sort;
    }
 
    public static function parseNamespacePrefixes(
        $query,
        $withAllKeyword = true,
        $withPrefixSearchExtractNamespaceHook = false
    ) {
        $parsed = $query;
        if ( !str_contains( $query, ':' ) ) { // nothing to do
            return false;
        }
        $extractedNamespace = null;
 
        $allQuery = false;
        if ( $withAllKeyword ) {
            $allkeywords = [];
 
            $allkeywords[] = wfMessage( 'searchall' )->inContentLanguage()->text() . ":";
            // force all: so that we have a common syntax for all the wikis
            if ( !in_array( 'all:', $allkeywords ) ) {
                $allkeywords[] = 'all:';
            }
 
            foreach ( $allkeywords as $kw ) {
                if ( str_starts_with( $query, $kw ) ) {
                    $parsed = substr( $query, strlen( $kw ) );
                    $allQuery = true;
                    break;
                }
            }
        }
 
        if ( !$allQuery && str_contains( $query, ':' ) ) {
            $prefix = str_replace( ' ', '_', substr( $query, 0, strpos( $query, ':' ) ) );
            $services = MediaWikiServices::getInstance();
            $index = $services->getContentLanguage()->getNsIndex( $prefix );
            if ( $index !== false ) {
                $extractedNamespace = [ $index ];
                $parsed = substr( $query, strlen( $prefix ) + 1 );
            } elseif ( $withPrefixSearchExtractNamespaceHook ) {
                $hookNamespaces = [ NS_MAIN ];
                $hookQuery = $query;
                ( new HookRunner( $services->getHookContainer() ) )
                    ->onPrefixSearchExtractNamespace( $hookNamespaces, $hookQuery );
                if ( $hookQuery !== $query ) {
                    $parsed = $hookQuery;
                    $extractedNamespace = $hookNamespaces;
                } else {
                    return false;
                }
            } else {
                return false;
            }
        }
 
        return [ $parsed, $extractedNamespace ];
    }
 
    public static function userHighlightPrefs() {
        $contextlines = SearchHighlighter::DEFAULT_CONTEXT_LINES;
        $contextchars = SearchHighlighter::DEFAULT_CONTEXT_CHARS;
        return [ $contextlines, $contextchars ];
    }
 
    public function update( $id, $title, $text ) {
        // no-op
    }
 
    public function updateTitle( $id, $title ) {
        // no-op
    }
 
    public function delete( $id, $title ) {
        // no-op
    }
 
    protected function normalizeNamespaces( $search ) {
        $queryAndNs = self::parseNamespacePrefixes( $search, false, true );
        if ( $queryAndNs !== false ) {
            $this->setNamespaces( $queryAndNs[1] );
            return $queryAndNs[0];
        }
        return $search;
    }
 
    protected function completionSearchBackendOverfetch( $search ) {
        $this->limit++;
        try {
            return $this->completionSearchBackend( $search );
        } finally {
            $this->limit--;
        }
    }
 
    protected function completionSearchBackend( $search ) {
        $results = [];
 
        $search = trim( $search );
 
        if ( !in_array( NS_SPECIAL, $this->namespaces ) && // We do not run hook on Special: search
            !$this->getHookRunner()->onPrefixSearchBackend(
                $this->namespaces, $search, $this->limit, $results, $this->offset )
        ) {
            // False means hook worked.
            // FIXME: Yes, the API is weird. That's why it is going to be deprecated.
 
            return SearchSuggestionSet::fromStrings( $results );
        } else {
            // Hook did not do the job, use default simple search
            $results = $this->simplePrefixSearch( $search );
            return SearchSuggestionSet::fromTitles( $results );
        }
    }
 
    public function completionSearch( $search ) {
        if ( trim( $search ) === '' ) {
            return SearchSuggestionSet::emptySuggestionSet(); // Return empty result
        }
        $search = $this->normalizeNamespaces( $search );
        $suggestions = $this->completionSearchBackendOverfetch( $search );
        return $this->processCompletionResults( $search, $suggestions );
    }
 
    public function completionSearchWithVariants( $search ) {
        if ( trim( $search ) === '' ) {
            return SearchSuggestionSet::emptySuggestionSet(); // Return empty result
        }
        $search = $this->normalizeNamespaces( $search );
 
        $results = $this->completionSearchBackendOverfetch( $search );
        $fallbackLimit = 1 + $this->limit - $results->getSize();
        if ( $fallbackLimit > 0 ) {
            $services = MediaWikiServices::getInstance();
            $fallbackSearches = $services->getLanguageConverterFactory()
                ->getLanguageConverter( $services->getContentLanguage() )
                ->autoConvertToAllVariants( $search );
            $fallbackSearches = array_diff( array_unique( $fallbackSearches ), [ $search ] );
 
            $origLimit = $this->limit;
            $origOffset = $this->offset;
            foreach ( $fallbackSearches as $fbs ) {
                try {
                    $this->setLimitOffset( $fallbackLimit );
                    $fallbackSearchResult = $this->completionSearch( $fbs );
                    $results->appendAll( $fallbackSearchResult );
                    $fallbackLimit -= $fallbackSearchResult->getSize();
                } finally {
                    $this->setLimitOffset( $origLimit, $origOffset );
                }
                if ( $fallbackLimit <= 0 ) {
                    break;
                }
            }
        }
        return $this->processCompletionResults( $search, $results );
    }
 
    public function extractTitles( SearchSuggestionSet $completionResults ) {
        return $completionResults->map( static function ( SearchSuggestion $sugg ) {
            return $sugg->getSuggestedTitle();
        } );
    }
 
    protected function processCompletionResults( $search, SearchSuggestionSet $suggestions ) {
        // We over-fetched to determine pagination. Shrink back down if we have extra results
        // and mark if pagination is possible
        $suggestions->shrink( $this->limit );
 
        $search = trim( $search );
        // preload the titles with LinkBatch
        $suggestedTitles = $suggestions->map( static function ( SearchSuggestion $sugg ) {
            return $sugg->getSuggestedTitle();
        } );
        $linkBatchFactory = MediaWikiServices::getInstance()->getLinkBatchFactory();
        $linkBatchFactory->newLinkBatch( $suggestedTitles )
            ->setCaller( __METHOD__ )
            ->execute();
 
        $diff = $suggestions->filter( static function ( SearchSuggestion $sugg ) {
            return $sugg->getSuggestedTitle()->isKnown();
        } );
        if ( $diff > 0 ) {
            $statsFactory = MediaWikiServices::getInstance()->getStatsFactory();
            $statsFactory->getCounter( 'search_completion_missing_total' )
                ->incrementBy( $diff );
        }
 
        // SearchExactMatchRescorer should probably be refactored to work directly on top of a SearchSuggestionSet
        // instead of converting it to array and trying to infer if it has re-scored anything by inspected the head
        // of the returned array.
        $results = $suggestions->map( static function ( SearchSuggestion $sugg ) {
            return $sugg->getSuggestedTitle()->getPrefixedText();
        } );
 
        $rescorer = new SearchExactMatchRescorer();
        if ( $this->offset === 0 ) {
            // Rescore results with an exact title match
            // NOTE: in some cases like cross-namespace redirects
            // (frequently used as shortcuts e.g. WP:WP on huwiki) some
            // backends like Cirrus will return no results. We should still
            // try an exact title match to workaround this limitation
            $rescoredResults = $rescorer->rescore( $search, $this->namespaces, $results, $this->limit );
        } else {
            // No need to rescore if offset is not 0
            // The exact match must have been returned at position 0
            // if it existed.
            $rescoredResults = $results;
        }
 
        if ( count( $rescoredResults ) > 0 ) {
            $found = array_search( $rescoredResults[0], $results );
            if ( $found === false ) {
                // If the first result is not in the previous array it
                // means that we found a new exact match
                $exactMatch = SearchSuggestion::fromTitle( 0, Title::newFromText( $rescoredResults[0] ) );
                $suggestions->prepend( $exactMatch );
                if ( $rescorer->getReplacedRedirect() !== null ) {
                    // the exact match rescorer replaced one of the suggestion found by the search engine
                    // let's remove it from our suggestions set to avoid showing duplicates
                    $suggestions->remove( SearchSuggestion::fromTitle( 0,
                        Title::newFromText( $rescorer->getReplacedRedirect() ) ) );
                }
                $suggestions->shrink( $this->limit );
            } else {
                // if the first result is not the same we need to rescore
                if ( $found > 0 ) {
                    $suggestions->rescore( $found );
                }
            }
        }
 
        return $suggestions;
    }
 
    public function defaultPrefixSearch( $search ) {
        if ( trim( $search ) === '' ) {
            return [];
        }
 
        $search = $this->normalizeNamespaces( $search );
        return $this->simplePrefixSearch( $search );
    }
 
    protected function simplePrefixSearch( $search ) {
        // Use default database prefix search
        $backend = new TitlePrefixSearch;
        return $backend->defaultSearchBackend( $this->namespaces, $search, $this->limit, $this->offset );
    }
 
    public function getProfiles( $profileType, ?User $user = null ) {
        return null;
    }
 
    public function makeSearchFieldMapping( $name, $type ) {
        return new NullIndexField();
    }
 
    public function getSearchIndexFields() {
        $models = MediaWikiServices::getInstance()->getContentHandlerFactory()->getContentModels();
        $fields = [];
        $seenHandlers = new SplObjectStorage();
        foreach ( $models as $model ) {
            try {
                $handler = MediaWikiServices::getInstance()
                    ->getContentHandlerFactory()
                    ->getContentHandler( $model );
            } catch ( MWUnknownContentModelException ) {
                // If we can find no handler, ignore it
                continue;
            }
            // Several models can have the same handler, so avoid processing it repeatedly
            if ( $seenHandlers->contains( $handler ) ) {
                // We already did this one
                continue;
            }
            $seenHandlers->attach( $handler );
            $handlerFields = $handler->getFieldsForSearchIndex( $this );
            foreach ( $handlerFields as $fieldName => $fieldData ) {
                if ( empty( $fields[$fieldName] ) ) {
                    $fields[$fieldName] = $fieldData;
                } else {
                    // TODO: do we allow some clashes with the same type or reject all of them?
                    $mergeDef = $fields[$fieldName]->merge( $fieldData );
                    if ( !$mergeDef ) {
                        throw new InvalidArgumentException( "Duplicate field $fieldName for model $model" );
                    }
                    $fields[$fieldName] = $mergeDef;
                }
            }
        }
        // Hook to allow extensions to produce search mapping fields
        $this->getHookRunner()->onSearchIndexFields( $fields, $this );
        return $fields;
    }
 
    public function augmentSearchResults( ISearchResultSet $resultSet ) {
        $setAugmentors = [];
        $rowAugmentors = [];
        $this->getHookRunner()->onSearchResultsAugment( $setAugmentors, $rowAugmentors );
        if ( !$setAugmentors && !$rowAugmentors ) {
            // We're done here
            return;
        }
 
        // Convert row augmentors to set augmentor
        foreach ( $rowAugmentors as $name => $row ) {
            if ( isset( $setAugmentors[$name] ) ) {
                throw new InvalidArgumentException( "Both row and set augmentors are defined for $name" );
            }
            $setAugmentors[$name] = new PerRowAugmentor( $row );
        }
 
        foreach ( $setAugmentors as $name => $augmentor ) {
            $data = $augmentor->augmentAll( $resultSet );
            if ( $data ) {
                $resultSet->setAugmentedData( $name, $data );
            }
        }
    }
 
    public function setHookContainer( HookContainer $hookContainer ) {
        $this->hookContainer = $hookContainer;
        $this->hookRunner = new HookRunner( $hookContainer );
    }
 
    protected function getHookContainer(): HookContainer {
        if ( !$this->hookContainer ) {
            // This shouldn't be hit in core, but it is needed for CirrusSearch
            // which commonly creates a CirrusSearch object without cirrus being
            // configured in $wgSearchType/$wgSearchTypeAlternatives.
            $this->hookContainer = MediaWikiServices::getInstance()->getHookContainer();
        }
        return $this->hookContainer;
    }
 
    protected function getHookRunner(): HookRunner {
        if ( !$this->hookRunner ) {
            $this->hookRunner = new HookRunner( $this->getHookContainer() );
        }
        return $this->hookRunner;
    }
 
}