includes/search/SearchResultSet.php

   1 <?php
   2 /**
   3  * Search result sets
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup Search
  22  */
  23
  24 /**
  25  * @ingroup Search
  26  */
  27 class SearchResultSet {
  28
  29         /**
  30          * Types of interwiki results
  31          */
  32         /**
  33          * Results that are displayed only together with existing main wiki results
  34          * @var int
  35          */
  36         const SECONDARY_RESULTS = 0;
  37         /**
  38          * Results that can displayed even if no existing main wiki results exist
  39          * @var int
  40          */
  41         const INLINE_RESULTS = 1;
  42
  43         protected $containedSyntax = false;
  44
  45         /**
  46          * Cache of titles.
  47          * Lists titles of the result set, in the same order as results.
  48          * @var Title[]
  49          */
  50         private $titles;
  51
  52         /**
  53          * Cache of results - serialization of the result iterator
  54          * as an array.
  55          * @var SearchResult[]
  56          */
  57         private $results;
  58
  59         /**
  60          * Set of result's extra data, indexed per result id
  61          * and then per data item name.
  62          * The structure is:
  63          * PAGE_ID => [ augmentor name => data, ... ]
  64          * @var array[]
  65          */
  66         protected $extraData = [];
  67
  68         public function __construct( $containedSyntax = false ) {
  69                 $this->containedSyntax = $containedSyntax;
  70         }
  71
  72         /**
  73          * Fetch an array of regular expression fragments for matching
  74          * the search terms as parsed by this engine in a text extract.
  75          * STUB
  76          *
  77          * @return array
  78          */
  79         function termMatches() {
  80                 return [];
  81         }
  82
  83         function numRows() {
  84                 return 0;
  85         }
  86
  87         /**
  88          * Some search modes return a total hit count for the query
  89          * in the entire article database. This may include pages
  90          * in namespaces that would not be matched on the given
  91          * settings.
  92          *
  93          * Return null if no total hits number is supported.
  94          *
  95          * @return int
  96          */
  97         function getTotalHits() {
  98                 return null;
  99         }
 100
 101         /**
 102          * Some search modes will run an alternative query that it thinks gives
 103          * a better result than the provided search. Returns true if this has
 104          * occured.
 105          *
 106          * @return bool
 107          */
 108         function hasRewrittenQuery() {
 109                 return false;
 110         }
 111
 112         /**
 113          * @return string|null The search the query was internally rewritten to,
 114          *  or null when the result of the original query was returned.
 115          */
 116         function getQueryAfterRewrite() {
 117                 return null;
 118         }
 119
 120         /**
 121          * @return string|null Same as self::getQueryAfterRewrite(), but in HTML
 122          *  and with changes highlighted. Null when the query was not rewritten.
 123          */
 124         function getQueryAfterRewriteSnippet() {
 125                 return null;
 126         }
 127
 128         /**
 129          * Some search modes return a suggested alternate term if there are
 130          * no exact hits. Returns true if there is one on this set.
 131          *
 132          * @return bool
 133          */
 134         function hasSuggestion() {
 135                 return false;
 136         }
 137
 138         /**
 139          * @return string|null Suggested query, null if none
 140          */
 141         function getSuggestionQuery() {
 142                 return null;
 143         }
 144
 145         /**
 146          * @return string HTML highlighted suggested query, '' if none
 147          */
 148         function getSuggestionSnippet() {
 149                 return '';
 150         }
 151
 152         /**
 153          * Return a result set of hits on other (multiple) wikis associated with this one
 154          *
 155          * @return SearchResultSet[]
 156          */
 157         function getInterwikiResults( $type = self::SECONDARY_RESULTS ) {
 158                 return null;
 159         }
 160
 161         /**
 162          * Check if there are results on other wikis
 163          *
 164          * @return bool
 165          */
 166         function hasInterwikiResults( $type = self::SECONDARY_RESULTS ) {
 167                 return false;
 168         }
 169
 170         /**
 171          * Fetches next search result, or false.
 172          * STUB
 173          * FIXME: refactor as iterator, so we could use nicer interfaces.
 174          * @return SearchResult|false
 175          */
 176         function next() {
 177                 return false;
 178         }
 179
 180         /**
 181          * Rewind result set back to beginning
 182          */
 183         function rewind() {
 184         }
 185
 186         /**
 187          * Frees the result set, if applicable.
 188          */
 189         function free() {
 190                 // ...
 191         }
 192
 193         /**
 194          * Did the search contain search syntax?  If so, Special:Search won't offer
 195          * the user a link to a create a page named by the search string because the
 196          * name would contain the search syntax.
 197          * @return bool
 198          */
 199         public function searchContainedSyntax() {
 200                 return $this->containedSyntax;
 201         }
 202
 203         /**
 204          * Extract all the results in the result set as array.
 205          * @return SearchResult[]
 206          */
 207         public function extractResults() {
 208                 if ( is_null( $this->results ) ) {
 209                         $this->results = [];
 210                         if ( $this->numRows() == 0 ) {
 211                                 // Don't bother if we've got empty result
 212                                 return $this->results;
 213                         }
 214                         $this->rewind();
 215                         while ( ( $result = $this->next() ) != false ) {
 216                                 $this->results[] = $result;
 217                         }
 218                         $this->rewind();
 219                 }
 220                 return $this->results;
 221         }
 222
 223         /**
 224          * Extract all the titles in the result set.
 225          * @return Title[]
 226          */
 227         public function extractTitles() {
 228                 if ( is_null( $this->titles ) ) {
 229                         if ( $this->numRows() == 0 ) {
 230                                 // Don't bother if we've got empty result
 231                                 $this->titles = [];
 232                         } else {
 233                                 $this->titles = array_map(
 234                                         function ( SearchResult $result ) {
 235                                                 return $result->getTitle();
 236                                         },
 237                                         $this->extractResults() );
 238                         }
 239                 }
 240                 return $this->titles;
 241         }
 242
 243         /**
 244          * Sets augmented data for result set.
 245          * @param string $name Extra data item name
 246          * @param array[] $data Extra data as PAGEID => data
 247          */
 248         public function setAugmentedData( $name, $data ) {
 249                 foreach ( $data as $id => $resultData ) {
 250                         $this->extraData[$id][$name] = $resultData;
 251                 }
 252         }
 253
 254         /**
 255          * Returns extra data for specific result and store it in SearchResult object.
 256          * @param SearchResult $result
 257          * @return array|null List of data as name => value or null if none present.
 258          */
 259         public function augmentResult( SearchResult $result ) {
 260                 $id = $result->getTitle()->getArticleID();
 261                 if ( !$id || !isset( $this->extraData[$id] ) ) {
 262                         return null;
 263                 }
 264                 $result->setExtensionData( $this->extraData[$id] );
 265                 return $this->extraData[$id];
 266         }
 267 }