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