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          * @param int $type
 156          * @return SearchResultSet[]
 157          */
 158         function getInterwikiResults( $type = self::SECONDARY_RESULTS ) {
 159                 return null;
 160         }
 161
 162         /**
 163          * Check if there are results on other wikis
 164          *
 165          * @param int $type
 166          * @return bool
 167          */
 168         function hasInterwikiResults( $type = self::SECONDARY_RESULTS ) {
 169                 return false;
 170         }
 171
 172         /**
 173          * Fetches next search result, or false.
 174          * STUB
 175          * FIXME: refactor as iterator, so we could use nicer interfaces.
 176          * @deprecated since 1.32; Use self::extractResults()
 177          * @return SearchResult|false
 178          */
 179         function next() {
 180                 return false;
 181         }
 182
 183         /**
 184          * Rewind result set back to beginning
 185          * @deprecated since 1.32; Use self::extractResults()
 186          */
 187         function rewind() {
 188         }
 189
 190         /**
 191          * Frees the result set, if applicable.
 192          */
 193         function free() {
 194                 // ...
 195         }
 196
 197         /**
 198          * Did the search contain search syntax?  If so, Special:Search won't offer
 199          * the user a link to a create a page named by the search string because the
 200          * name would contain the search syntax.
 201          * @return bool
 202          */
 203         public function searchContainedSyntax() {
 204                 return $this->containedSyntax;
 205         }
 206
 207         /**
 208          * Extract all the results in the result set as array.
 209          * @return SearchResult[]
 210          */
 211         public function extractResults() {
 212                 if ( is_null( $this->results ) ) {
 213                         $this->results = [];
 214                         if ( $this->numRows() == 0 ) {
 215                                 // Don't bother if we've got empty result
 216                                 return $this->results;
 217                         }
 218                         $this->rewind();
 219                         while ( ( $result = $this->next() ) != false ) {
 220                                 $this->results[] = $result;
 221                         }
 222                         $this->rewind();
 223                 }
 224                 return $this->results;
 225         }
 226
 227         /**
 228          * Extract all the titles in the result set.
 229          * @return Title[]
 230          */
 231         public function extractTitles() {
 232                 if ( is_null( $this->titles ) ) {
 233                         if ( $this->numRows() == 0 ) {
 234                                 // Don't bother if we've got empty result
 235                                 $this->titles = [];
 236                         } else {
 237                                 $this->titles = array_map(
 238                                         function ( SearchResult $result ) {
 239                                                 return $result->getTitle();
 240                                         },
 241                                         $this->extractResults() );
 242                         }
 243                 }
 244                 return $this->titles;
 245         }
 246
 247         /**
 248          * Sets augmented data for result set.
 249          * @param string $name Extra data item name
 250          * @param array[] $data Extra data as PAGEID => data
 251          */
 252         public function setAugmentedData( $name, $data ) {
 253                 foreach ( $data as $id => $resultData ) {
 254                         $this->extraData[$id][$name] = $resultData;
 255                 }
 256         }
 257
 258         /**
 259          * Returns extra data for specific result and store it in SearchResult object.
 260          * @param SearchResult $result
 261          * @return array|null List of data as name => value or null if none present.
 262          */
 263         public function augmentResult( SearchResult $result ) {
 264                 $id = $result->getTitle()->getArticleID();
 265                 if ( !$id || !isset( $this->extraData[$id] ) ) {
 266                         return null;
 267                 }
 268                 $result->setExtensionData( $this->extraData[$id] );
 269                 return $this->extraData[$id];
 270         }
 271
 272         /**
 273          * @return int|null The offset the current page starts at. Typically
 274          *  this should be null to allow the UI to decide on its own, but in
 275          *  special cases like interleaved AB tests specifying explicitly is
 276          *  necessary.
 277          */
 278         public function getOffset() {
 279                 return null;
 280         }
 281 }