SpecialRandomInCategory.php

Go to the documentation of this file.

<?php
namespace MediaWiki\Specials;
 
use BadMethodCallException;
use MediaWiki\Deferred\LinksUpdate\CategoryLinksTable;
use MediaWiki\HTMLForm\HTMLForm;
use MediaWiki\SpecialPage\FormSpecialPage;
use MediaWiki\Status\Status;
use MediaWiki\Title\Title;
use stdClass;
use Wikimedia\Rdbms\IConnectionProvider;
use Wikimedia\Rdbms\SelectQueryBuilder;
use Wikimedia\Timestamp\TimestampFormat as TS;
 
class SpecialRandomInCategory extends FormSpecialPage {
    protected $extra = [];
    protected $category = false;
    protected $maxOffset = 30;
    private $maxTimestamp = null;
    private $minTimestamp = null;
 
    public function __construct(
        private readonly IConnectionProvider $dbProvider,
    ) {
        parent::__construct( 'RandomInCategory' );
    }
 
    public function setCategory( Title $cat ) {
        $this->category = $cat;
        $this->maxTimestamp = null;
        $this->minTimestamp = null;
    }
 
    protected function getFormFields() {
        $this->addHelpLink( 'Help:RandomInCategory' );
 
        return [
            'category' => [
                'type' => 'title',
                'namespace' => NS_CATEGORY,
                'relative' => true,
                'label-message' => 'randomincategory-category',
                'required' => true,
            ]
        ];
    }
 
    public function requiresPost() {
        return false;
    }
 
    protected function getDisplayFormat() {
        return 'ooui';
    }
 
    protected function alterForm( HTMLForm $form ) {
        $form->setSubmitTextMsg( 'randomincategory-submit' );
    }
 
    protected function getSubpageField() {
        return 'category';
    }
 
    public function onSubmit( array $data ) {
        $cat = false;
 
        $categoryStr = $data['category'];
 
        if ( $categoryStr ) {
            $cat = Title::newFromText( $categoryStr, NS_CATEGORY );
        }
 
        if ( $cat && $cat->getNamespace() !== NS_CATEGORY ) {
            // Someone searching for something like "Wikipedia:Foo"
            $cat = Title::makeTitleSafe( NS_CATEGORY, $categoryStr );
        }
 
        if ( $cat ) {
            $this->setCategory( $cat );
        }
 
        if ( !$this->category && $categoryStr ) {
            $msg = $this->msg( 'randomincategory-invalidcategory',
                wfEscapeWikiText( $categoryStr ) );
 
            return Status::newFatal( $msg );
 
        } elseif ( !$this->category ) {
            return false; // no data sent
        }
 
        $title = $this->getRandomTitle();
 
        if ( $title === null ) {
            $msg = $this->msg( 'randomincategory-nopages',
                $this->category->getText() );
 
            return Status::newFatal( $msg );
        }
 
        $query = $this->getRequest()->getQueryValues();
        unset( $query['title'] );
        $this->getOutput()->redirect( $title->getFullURL( $query ) );
    }
 
    public function getRandomTitle() {
        // Convert to float, since we do math with the random number.
        $rand = (float)wfRandom();
 
        // Given that timestamps are rather unevenly distributed, we also
        // use an offset between 0 and 30 to make any biases less noticeable.
        $offset = mt_rand( 0, $this->maxOffset );
 
        if ( mt_rand( 0, 1 ) ) {
            $up = true;
        } else {
            $up = false;
        }
 
        $row = $this->selectRandomPageFromDB( $rand, $offset, $up, __METHOD__ );
 
        // Try again without the timestamp offset (wrap around the end)
        if ( !$row ) {
            $row = $this->selectRandomPageFromDB( false, $offset, $up, __METHOD__ );
        }
 
        // Maybe the category is really small and offset too high
        if ( !$row ) {
            $row = $this->selectRandomPageFromDB( $rand, 0, $up, __METHOD__ );
        }
 
        // Just get the first entry.
        if ( !$row ) {
            $row = $this->selectRandomPageFromDB( false, 0, true, __METHOD__ );
        }
 
        if ( $row ) {
            return Title::makeTitle( $row->page_namespace, $row->page_title );
        }
 
        return null;
    }
 
    protected function getQueryBuilder( $rand, $offset, $up ) {
        if ( !$this->category instanceof Title ) {
            throw new BadMethodCallException( 'No category set' );
        }
        $dbr = $this->dbProvider->getReplicaDatabase( CategoryLinksTable::VIRTUAL_DOMAIN );
        $queryBuilder = $dbr->newSelectQueryBuilder()
            ->select( [ 'page_title', 'page_namespace' ] )
            ->from( 'categorylinks' )
            ->join( 'linktarget', null, 'cl_target_id = lt_id' )
            ->join( 'page', null, 'cl_from = page_id' )
            ->where( [ 'lt_title' => $this->category->getDBkey(), 'lt_namespace' => NS_CATEGORY ] )
            ->andWhere( $this->extra )
            ->orderBy( 'cl_timestamp', $up ? SelectQueryBuilder::SORT_ASC : SelectQueryBuilder::SORT_DESC )
            ->limit( 1 )
            ->offset( $offset );
 
        $minClTime = $this->getTimestampOffset( $rand );
        if ( $minClTime ) {
            $op = $up ? '>=' : '<=';
            $queryBuilder->andWhere(
                $dbr->expr( 'cl_timestamp', $op, $dbr->timestamp( $minClTime ) )
            );
        }
 
        return $queryBuilder;
    }
 
    protected function getTimestampOffset( $rand ) {
        if ( $rand === false ) {
            return false;
        }
        if ( !$this->minTimestamp || !$this->maxTimestamp ) {
            $minAndMax = $this->getMinAndMaxForCat();
            if ( $minAndMax === null ) {
                // No entries in this category.
                return false;
            }
            [ $this->minTimestamp, $this->maxTimestamp ] = $minAndMax;
        }
 
        $ts = ( $this->maxTimestamp - $this->minTimestamp ) * $rand + $this->minTimestamp;
 
        return intval( $ts );
    }
 
    protected function getMinAndMaxForCat() {
        $dbr = $this->dbProvider->getReplicaDatabase( CategoryLinksTable::VIRTUAL_DOMAIN );
        $res = $dbr->newSelectQueryBuilder()
            ->select( [ 'low' => 'MIN( cl_timestamp )', 'high' => 'MAX( cl_timestamp )' ] )
            ->from( 'categorylinks' )
            ->join( 'linktarget', null, 'cl_target_id = lt_id' )
            ->where( [ 'lt_title' => $this->category->getDBkey(), 'lt_namespace' => NS_CATEGORY ] )
            ->caller( __METHOD__ )
            ->fetchRow();
 
        if ( !$res ) {
            return null;
        }
 
        return [ (int)wfTimestamp( TS::UNIX, $res->low ), (int)wfTimestamp( TS::UNIX, $res->high ) ];
    }
 
    private function selectRandomPageFromDB( $rand, $offset, $up, $fname ) {
        return $this->getQueryBuilder( $rand, $offset, $up )->caller( $fname )->fetchRow();
    }
 
    protected function getGroupName() {
        return 'redirects';
    }
}
 
class_alias( SpecialRandomInCategory::class, 'SpecialRandomInCategory' );