SearchEngine.php

Go to the documentation of this file.

<?php
use MediaWiki\MediaWikiServices;

abstract class SearchEngine {
    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 = [];

    const COMPLETION_PROFILE_TYPE = 'completionSearchProfile';

    const FT_QUERY_INDEP_PROFILE_TYPE = 'fulltextQueryIndepProfile';

    const CHARS_ALL = 1;

    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 new SearchNearMatcher( $config,
            MediaWikiServices::getInstance()->getContentLanguage() );
    }

    protected static function defaultNearMatcher() {
        $services = MediaWikiServices::getInstance();
        $config = $services->getMainConfig();
        return $services->newSearchEngine()->getNearMatcher( $config );
    }

    public function legalSearchChars( $type = self::CHARS_ALL ) {
        return "A-Za-z_'.0-9\\x80-\\xFF\\-";
    }

    function setLimitOffset( $limit, $offset = 0 ) {
        $this->limit = intval( $limit );
        $this->offset = intval( $offset );
    }

    function setNamespaces( $namespaces ) {
        if ( $namespaces ) {
            // Filter namespaces to only keep valid ones
            $validNs = MediaWikiServices::getInstance()->getSearchEngineConfig()->searchableNamespaces();
            $namespaces = array_filter( $namespaces, function ( $ns ) use( $validNs ) {
                return $ns < 0 || isset( $validNs[$ns] );
            } );
        } else {
            $namespaces = [];
        }
        $this->namespaces = $namespaces;
    }

    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;
    }

    function replacePrefixes( $query ) {
        return $query;
    }

    public static function parseNamespacePrefixes(
        $query,
        $withAllKeyword = true,
        $withPrefixSearchExtractNamespaceHook = false
    ) {
        $parsed = $query;
        if ( strpos( $query, ':' ) === false ) { // 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 ( strncmp( $query, $kw, strlen( $kw ) ) == 0 ) {
                    $extractedNamespace = null;
                    $parsed = substr( $query, strlen( $kw ) );
                    $allQuery = true;
                    break;
                }
            }
        }

        if ( !$allQuery && strpos( $query, ':' ) !== false ) {
            $prefix = str_replace( ' ', '_', substr( $query, 0, strpos( $query, ':' ) ) );
            $index = MediaWikiServices::getInstance()->getContentLanguage()->getNsIndex( $prefix );
            if ( $index !== false ) {
                $extractedNamespace = [ $index ];
                $parsed = substr( $query, strlen( $prefix ) + 1 );
            } elseif ( $withPrefixSearchExtractNamespaceHook ) {
                $hookNamespaces = [ NS_MAIN ];
                $hookQuery = $query;
                Hooks::run( 'PrefixSearchExtractNamespace', [ &$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 ];
    }

    function update( $id, $title, $text ) {
        // no-op
    }

    function updateTitle( $id, $title ) {
        // no-op
    }

    function delete( $id, $title ) {
        // no-op
    }

    public function getTextFromContent( Title $t, Content $c = null ) {
        return $c ? $c->getTextForSearchIndex() : '';
    }

    public function textAlreadyUpdatedForIndex() {
        return false;
    }

    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
             !Hooks::run( 'PrefixSearchBackend',
                [ $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 ) {
            $fallbackSearches = MediaWikiServices::getInstance()->getContentLanguage()->
                autoConvertToAllVariants( $search );
            $fallbackSearches = array_diff( array_unique( $fallbackSearches ), [ $search ] );

            foreach ( $fallbackSearches as $fbs ) {
                $this->setLimitOffset( $fallbackLimit );
                $fallbackSearchResult = $this->completionSearch( $fbs );
                $results->appendAll( $fallbackSearchResult );
                $fallbackLimit -= $fallbackSearchResult->getSize();
                if ( $fallbackLimit <= 0 ) {
                    break;
                }
            }
        }
        return $this->processCompletionResults( $search, $results );
    }

    public function extractTitles( SearchSuggestionSet $completionResults ) {
        return $completionResults->map( 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
        $lb = new LinkBatch( $suggestions->map( function ( SearchSuggestion $sugg ) {
            return $sugg->getSuggestedTitle();
        } ) );
        $lb->setCaller( __METHOD__ );
        $lb->execute();

        $diff = $suggestions->filter( function ( SearchSuggestion $sugg ) {
            return $sugg->getSuggestedTitle()->isKnown();
        } );
        if ( $diff > 0 ) {
            MediaWikiServices::getInstance()->getStatsdDataFactory()
                ->updateCount( 'search.completion.missing', $diff );
        }

        $results = $suggestions->map( function ( SearchSuggestion $sugg ) {
            return $sugg->getSuggestedTitle()->getPrefixedText();
        } );

        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
            $rescorer = new SearchExactMatchRescorer();
            $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 );
                $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 = ContentHandler::getContentModels();
        $fields = [];
        $seenHandlers = new SplObjectStorage();
        foreach ( $models as $model ) {
            try {
                $handler = ContentHandler::getForModelID( $model );
            }
            catch ( MWUnknownContentModelException $e ) {
                // 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
        Hooks::run( 'SearchIndexFields', [ &$fields, $this ] );
        return $fields;
    }

    public function augmentSearchResults( ISearchResultSet $resultSet ) {
        $setAugmentors = [];
        $rowAugmentors = [];
        Hooks::run( "SearchResultsAugment", [ &$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 );
            }
        }
    }
}