includes/specials/SpecialRandomInCategory.php

   1 <?php
   2 /**
   3  * Implements Special:RandomInCategory
   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 SpecialPage
  22  * @author Brian Wolff
  23  */
  24
  25 /**
  26  * Special page to direct the user to a random page
  27  *
  28  * @note The method used here is rather biased. It is assumed that
  29  * the use of this page will be people wanting to get a random page
  30  * out of a maintenance category, to fix it up. The method used by
  31  * this page should return different pages in an unpredictable fashion
  32  * which is hoped to be sufficient, even if some pages are selected
  33  * more often than others.
  34  *
  35  * A more unbiased method could be achieved by adding a cl_random field
  36  * to the categorylinks table.
  37  *
  38  * The method used here is as follows:
  39  *  * Find the smallest and largest timestamp in the category
  40  *  * Pick a random timestamp in between
  41  *  * Pick an offset between 0 and 30
  42  *  * Get the offset'ed page that is newer than the timestamp selected
  43  * The offset is meant to counter the fact the timestamps aren't usually
  44  * uniformly distributed, so if things are very non-uniform at least we
  45  * won't have the same page selected 99% of the time.
  46  *
  47  * @ingroup SpecialPage
  48  */
  49 class SpecialRandomInCategory extends FormSpecialPage {
  50         /** @var string[] */
  51         protected $extra = []; // Extra SQL statements
  52         /** @var Title|false */
  53         protected $category = false; // Title object of category
  54         /** @var int */
  55         protected $maxOffset = 30; // Max amount to fudge randomness by.
  56         /** @var int|null */
  57         private $maxTimestamp = null;
  58         /** @var int|null */
  59         private $minTimestamp = null;
  60
  61         public function __construct( $name = 'RandomInCategory' ) {
  62                 parent::__construct( $name );
  63         }
  64
  65         /**
  66          * Set which category to use.
  67          * @param Title $cat
  68          */
  69         public function setCategory( Title $cat ) {
  70                 $this->category = $cat;
  71                 $this->maxTimestamp = null;
  72                 $this->minTimestamp = null;
  73         }
  74
  75         protected function getFormFields() {
  76                 $this->addHelpLink( 'Help:RandomInCategory' );
  77
  78                 return [
  79                         'category' => [
  80                                 'type' => 'title',
  81                                 'namespace' => NS_CATEGORY,
  82                                 'relative' => true,
  83                                 'label-message' => 'randomincategory-category',
  84                                 'required' => true,
  85                         ]
  86                 ];
  87         }
  88
  89         public function requiresWrite() {
  90                 return false;
  91         }
  92
  93         public function requiresUnblock() {
  94                 return false;
  95         }
  96
  97         protected function getDisplayFormat() {
  98                 return 'ooui';
  99         }
 100
 101         protected function alterForm( HTMLForm $form ) {
 102                 $form->setSubmitTextMsg( 'randomincategory-submit' );
 103         }
 104
 105         protected function setParameter( $par ) {
 106                 // if subpage present, fake form submission
 107                 $this->onSubmit( [ 'category' => $par ] );
 108         }
 109
 110         public function onSubmit( array $data ) {
 111                 $cat = false;
 112
 113                 $categoryStr = $data['category'];
 114
 115                 if ( $categoryStr ) {
 116                         $cat = Title::newFromText( $categoryStr, NS_CATEGORY );
 117                 }
 118
 119                 if ( $cat && $cat->getNamespace() !== NS_CATEGORY ) {
 120                         // Someone searching for something like "Wikipedia:Foo"
 121                         $cat = Title::makeTitleSafe( NS_CATEGORY, $categoryStr );
 122                 }
 123
 124                 if ( $cat ) {
 125                         $this->setCategory( $cat );
 126                 }
 127
 128                 if ( !$this->category && $categoryStr ) {
 129                         $msg = $this->msg( 'randomincategory-invalidcategory',
 130                                 wfEscapeWikiText( $categoryStr ) );
 131
 132                         return Status::newFatal( $msg );
 133
 134                 } elseif ( !$this->category ) {
 135                         return false; // no data sent
 136                 }
 137
 138                 $title = $this->getRandomTitle();
 139
 140                 if ( is_null( $title ) ) {
 141                         $msg = $this->msg( 'randomincategory-nopages',
 142                                 $this->category->getText() );
 143
 144                         return Status::newFatal( $msg );
 145                 }
 146
 147                 $this->getOutput()->redirect( $title->getFullURL() );
 148         }
 149
 150         /**
 151          * Choose a random title.
 152          * @return Title|null Title object (or null if nothing to choose from)
 153          */
 154         public function getRandomTitle() {
 155                 // Convert to float, since we do math with the random number.
 156                 $rand = (float)wfRandom();
 157                 $title = null;
 158
 159                 // Given that timestamps are rather unevenly distributed, we also
 160                 // use an offset between 0 and 30 to make any biases less noticeable.
 161                 $offset = mt_rand( 0, $this->maxOffset );
 162
 163                 if ( mt_rand( 0, 1 ) ) {
 164                         $up = true;
 165                 } else {
 166                         $up = false;
 167                 }
 168
 169                 $row = $this->selectRandomPageFromDB( $rand, $offset, $up );
 170
 171                 // Try again without the timestamp offset (wrap around the end)
 172                 if ( !$row ) {
 173                         $row = $this->selectRandomPageFromDB( false, $offset, $up );
 174                 }
 175
 176                 // Maybe the category is really small and offset too high
 177                 if ( !$row ) {
 178                         $row = $this->selectRandomPageFromDB( $rand, 0, $up );
 179                 }
 180
 181                 // Just get the first entry.
 182                 if ( !$row ) {
 183                         $row = $this->selectRandomPageFromDB( false, 0, true );
 184                 }
 185
 186                 if ( $row ) {
 187                         return Title::makeTitle( $row->page_namespace, $row->page_title );
 188                 }
 189
 190                 return null;
 191         }
 192
 193         /**
 194          * @param float $rand Random number between 0 and 1
 195          * @param int $offset Extra offset to fudge randomness
 196          * @param bool $up True to get the result above the random number, false for below
 197          * @return array Query information.
 198          * @throws MWException
 199          * @note The $up parameter is supposed to counteract what would happen if there
 200          *   was a large gap in the distribution of cl_timestamp values. This way instead
 201          *   of things to the right of the gap being favoured, both sides of the gap
 202          *   are favoured.
 203          */
 204         protected function getQueryInfo( $rand, $offset, $up ) {
 205                 $op = $up ? '>=' : '<=';
 206                 $dir = $up ? 'ASC' : 'DESC';
 207                 if ( !$this->category instanceof Title ) {
 208                         throw new MWException( 'No category set' );
 209                 }
 210                 $qi = [
 211                         'tables' => [ 'categorylinks', 'page' ],
 212                         'fields' => [ 'page_title', 'page_namespace' ],
 213                         'conds' => array_merge( [
 214                                 'cl_to' => $this->category->getDBkey(),
 215                         ], $this->extra ),
 216                         'options' => [
 217                                 'ORDER BY' => 'cl_timestamp ' . $dir,
 218                                 'LIMIT' => 1,
 219                                 'OFFSET' => $offset
 220                         ],
 221                         'join_conds' => [
 222                                 'page' => [ 'INNER JOIN', 'cl_from = page_id' ]
 223                         ]
 224                 ];
 225
 226                 $dbr = wfGetDB( DB_REPLICA );
 227                 $minClTime = $this->getTimestampOffset( $rand );
 228                 if ( $minClTime ) {
 229                         $qi['conds'][] = 'cl_timestamp ' . $op . ' ' .
 230                                 $dbr->addQuotes( $dbr->timestamp( $minClTime ) );
 231                 }
 232
 233                 return $qi;
 234         }
 235
 236         /**
 237          * @param float $rand Random number between 0 and 1
 238          *
 239          * @return int|bool A random (unix) timestamp from the range of the category or false on failure
 240          */
 241         protected function getTimestampOffset( $rand ) {
 242                 if ( $rand === false ) {
 243                         return false;
 244                 }
 245                 if ( !$this->minTimestamp || !$this->maxTimestamp ) {
 246                         try {
 247                                 list( $this->minTimestamp, $this->maxTimestamp ) = $this->getMinAndMaxForCat( $this->category );
 248                         } catch ( Exception $e ) {
 249                                 // Possibly no entries in category.
 250                                 return false;
 251                         }
 252                 }
 253
 254                 $ts = ( $this->maxTimestamp - $this->minTimestamp ) * $rand + $this->minTimestamp;
 255
 256                 return intval( $ts );
 257         }
 258
 259         /**
 260          * Get the lowest and highest timestamp for a category.
 261          *
 262          * @param Title $category
 263          * @return array The lowest and highest timestamp
 264          * @throws MWException If category has no entries.
 265          */
 266         protected function getMinAndMaxForCat( Title $category ) {
 267                 $dbr = wfGetDB( DB_REPLICA );
 268                 $res = $dbr->selectRow(
 269                         'categorylinks',
 270                         [
 271                                 'low' => 'MIN( cl_timestamp )',
 272                                 'high' => 'MAX( cl_timestamp )'
 273                         ],
 274                         [
 275                                 'cl_to' => $this->category->getDBkey(),
 276                         ],
 277                         __METHOD__,
 278                         [
 279                                 'LIMIT' => 1
 280                         ]
 281                 );
 282                 if ( !$res ) {
 283                         throw new MWException( 'No entries in category' );
 284                 }
 285
 286                 return [ wfTimestamp( TS_UNIX, $res->low ), wfTimestamp( TS_UNIX, $res->high ) ];
 287         }
 288
 289         /**
 290          * @param float $rand A random number that is converted to a random timestamp
 291          * @param int $offset A small offset to make the result seem more "random"
 292          * @param bool $up Get the result above the random value
 293          * @param string $fname The name of the calling method
 294          * @return array Info for the title selected.
 295          */
 296         private function selectRandomPageFromDB( $rand, $offset, $up, $fname = __METHOD__ ) {
 297                 $dbr = wfGetDB( DB_REPLICA );
 298
 299                 $query = $this->getQueryInfo( $rand, $offset, $up );
 300                 $res = $dbr->select(
 301                         $query['tables'],
 302                         $query['fields'],
 303                         $query['conds'],
 304                         $fname,
 305                         $query['options'],
 306                         $query['join_conds']
 307                 );
 308
 309                 return $res->fetchObject();
 310         }
 311
 312         protected function getGroupName() {
 313                 return 'redirects';
 314         }
 315 }