IndexPager.php

Go to the documentation of this file.

<?php
use MediaWiki\HookContainer\ProtectedHookAccessorTrait;
use MediaWiki\Linker\LinkRenderer;
use MediaWiki\MediaWikiServices;
use MediaWiki\Navigation\PrevNextNavigationRenderer;
use Wikimedia\Rdbms\IDatabase;
use Wikimedia\Rdbms\IResultWrapper;
 
abstract class IndexPager extends ContextSource implements Pager {
    use ProtectedHookAccessorTrait;
 
    public const DIR_ASCENDING = false;
    public const DIR_DESCENDING = true;
 
    public const QUERY_ASCENDING = true;
    public const QUERY_DESCENDING = false;
 
    public $mRequest;
    public $mLimitsShown = [ 20, 50, 100, 250, 500 ];
    public $mDefaultLimit = 50;
    public $mOffset;
    public $mLimit;
    public $mQueryDone = false;
    public $mDb;
    public $mPastTheEndRow;
 
    protected $mIndexField;
    protected $mExtraSortFields;
    protected $mOrderType;
    public $mDefaultDirection;
    public $mIsBackwards;
 
    public $mIsFirst;
    public $mIsLast;
 
    protected $mLastShown;
    protected $mFirstShown;
    protected $mPastTheEndIndex;
    protected $mDefaultQuery;
    protected $mNavigationBar;
 
    protected $mIncludeOffset = false;
 
    public $mResult;
 
    private $linkRenderer;
 
    public function __construct( IContextSource $context = null, LinkRenderer $linkRenderer = null ) {
        if ( $context ) {
            $this->setContext( $context );
        }
 
        $this->mRequest = $this->getRequest();
 
        # NB: the offset is quoted, not validated. It is treated as an
        # arbitrary string to support the widest variety of index types. Be
        # careful outputting it into HTML!
        $this->mOffset = $this->mRequest->getText( 'offset' );
 
        # Use consistent behavior for the limit options
        $this->mDefaultLimit = $this->getUser()->getIntOption( 'rclimit' );
        if ( !$this->mLimit ) {
            // Don't override if a subclass calls $this->setLimit() in its constructor.
            list( $this->mLimit, /* $offset */ ) = $this->mRequest
                ->getLimitOffsetForUser( $this->getUser() );
        }
 
        $this->mIsBackwards = ( $this->mRequest->getVal( 'dir' ) == 'prev' );
        # Let the subclass set the DB here; otherwise use a replica DB for the current wiki
        $this->mDb = $this->mDb ?: wfGetDB( DB_REPLICA );
 
        $index = $this->getIndexField(); // column to sort on
        $extraSort = $this->getExtraSortFields(); // extra columns to sort on for query planning
        $order = $this->mRequest->getVal( 'order' );
 
        if ( is_array( $index ) && isset( $index[$order] ) ) {
            $this->mOrderType = $order;
            $this->mIndexField = $index[$order];
            $this->mExtraSortFields = isset( $extraSort[$order] )
                ? (array)$extraSort[$order]
                : [];
        } elseif ( is_array( $index ) ) {
            # First element is the default
            $this->mIndexField = reset( $index );
            $this->mOrderType = key( $index );
            $this->mExtraSortFields = isset( $extraSort[$this->mOrderType] )
                ? (array)$extraSort[$this->mOrderType]
                : [];
        } else {
            # $index is not an array
            $this->mOrderType = null;
            $this->mIndexField = $index;
            $isSortAssociative = array_values( $extraSort ) !== $extraSort;
            if ( $isSortAssociative ) {
                $this->mExtraSortFields = isset( $extraSort[$index] )
                    ? (array)$extraSort[$index]
                    : [];
            } else {
                $this->mExtraSortFields = (array)$extraSort;
            }
        }
 
        if ( !isset( $this->mDefaultDirection ) ) {
            $dir = $this->getDefaultDirections();
            $this->mDefaultDirection = is_array( $dir )
                ? $dir[$this->mOrderType]
                : $dir;
        }
        $this->linkRenderer = $linkRenderer;
    }
 
    public function getDatabase() {
        return $this->mDb;
    }
 
    public function doQuery() {
        $defaultOrder = ( $this->mDefaultDirection === self::DIR_ASCENDING )
            ? self::QUERY_ASCENDING
            : self::QUERY_DESCENDING;
        $order = $this->mIsBackwards ? self::oppositeOrder( $defaultOrder ) : $defaultOrder;
 
        # Plus an extra row so that we can tell the "next" link should be shown
        $queryLimit = $this->mLimit + 1;
 
        if ( $this->mOffset == '' ) {
            $isFirst = true;
        } else {
            // If there's an offset, we may or may not be at the first entry.
            // The only way to tell is to run the query in the opposite
            // direction see if we get a row.
            $oldIncludeOffset = $this->mIncludeOffset;
            $this->mIncludeOffset = !$this->mIncludeOffset;
            $oppositeOrder = self::oppositeOrder( $order );
            $isFirst = !$this->reallyDoQuery( $this->mOffset, 1, $oppositeOrder )->numRows();
            $this->mIncludeOffset = $oldIncludeOffset;
        }
 
        $this->mResult = $this->reallyDoQuery(
            $this->mOffset,
            $queryLimit,
            $order
        );
 
        $this->extractResultInfo( $isFirst, $queryLimit, $this->mResult );
        $this->mQueryDone = true;
 
        $this->preprocessResults( $this->mResult );
        $this->mResult->rewind(); // Paranoia
    }
 
    final protected static function oppositeOrder( $order ) {
        return ( $order === self::QUERY_ASCENDING )
            ? self::QUERY_DESCENDING
            : self::QUERY_ASCENDING;
    }
 
    public function getResult() {
        return $this->mResult;
    }
 
    public function setOffset( $offset ) {
        $this->mOffset = $offset;
    }
 
    public function setLimit( $limit ) {
        $limit = (int)$limit;
        // WebRequest::getLimitOffsetForUser() puts a cap of 5000, so do same here.
        if ( $limit > 5000 ) {
            $limit = 5000;
        }
        if ( $limit > 0 ) {
            $this->mLimit = $limit;
        }
    }
 
    public function getLimit() {
        return $this->mLimit;
    }
 
    public function setIncludeOffset( $include ) {
        $this->mIncludeOffset = $include;
    }
 
    protected function extractResultInfo( $isFirst, $limit, IResultWrapper $res ) {
        $numRows = $res->numRows();
 
        $firstIndex = [];
        $lastIndex = [];
        $this->mPastTheEndIndex = [];
        $this->mPastTheEndRow = null;
 
        if ( $numRows ) {
            $indexColumns = array_map( function ( $v ) {
                // Remove any table prefix from index field
                $parts = explode( '.', $v );
                return end( $parts );
            }, (array)$this->mIndexField );
 
            $row = $res->fetchRow();
            foreach ( $indexColumns as $indexColumn ) {
                $firstIndex[] = $row[$indexColumn];
            }
 
            # Discard the extra result row if there is one
            if ( $numRows > $this->mLimit && $numRows > 1 ) {
                $res->seek( $numRows - 1 );
                $this->mPastTheEndRow = $res->fetchObject();
                foreach ( $indexColumns as $indexColumn ) {
                    $this->mPastTheEndIndex[] = $this->mPastTheEndRow->$indexColumn;
                }
                $res->seek( $numRows - 2 );
                $row = $res->fetchRow();
                foreach ( $indexColumns as $indexColumn ) {
                    $lastIndex[] = $row[$indexColumn];
                }
            } else {
                $this->mPastTheEndRow = null;
                $res->seek( $numRows - 1 );
                $row = $res->fetchRow();
                foreach ( $indexColumns as $indexColumn ) {
                    $lastIndex[] = $row[$indexColumn];
                }
            }
        }
 
        if ( $this->mIsBackwards ) {
            $this->mIsFirst = ( $numRows < $limit );
            $this->mIsLast = $isFirst;
            $this->mLastShown = $firstIndex;
            $this->mFirstShown = $lastIndex;
        } else {
            $this->mIsFirst = $isFirst;
            $this->mIsLast = ( $numRows < $limit );
            $this->mLastShown = $lastIndex;
            $this->mFirstShown = $firstIndex;
        }
    }
 
    protected function getSqlComment() {
        return static::class;
    }
 
    public function reallyDoQuery( $offset, $limit, $order ) {
        list( $tables, $fields, $conds, $fname, $options, $join_conds ) =
            $this->buildQueryInfo( $offset, $limit, $order );
 
        return $this->mDb->select( $tables, $fields, $conds, $fname, $options, $join_conds );
    }
 
    protected function buildQueryInfo( $offset, $limit, $order ) {
        $fname = __METHOD__ . ' (' . $this->getSqlComment() . ')';
        $info = $this->getQueryInfo();
        $tables = $info['tables'];
        $fields = $info['fields'];
        $conds = $info['conds'] ?? [];
        $options = $info['options'] ?? [];
        $join_conds = $info['join_conds'] ?? [];
        $indexColumns = (array)$this->mIndexField;
        $sortColumns = array_merge( $indexColumns, $this->mExtraSortFields );
 
        if ( $order === self::QUERY_ASCENDING ) {
            $options['ORDER BY'] = $sortColumns;
            $operator = $this->mIncludeOffset ? '>=' : '>';
        } else {
            $orderBy = [];
            foreach ( $sortColumns as $col ) {
                $orderBy[] = $col . ' DESC';
            }
            $options['ORDER BY'] = $orderBy;
            $operator = $this->mIncludeOffset ? '<=' : '<';
        }
        if ( $offset ) {
            $offsets = explode( '|', $offset, /* Limit to max of indices */ count( $indexColumns ) );
 
            $conds[] = $this->buildOffsetConds(
                $offsets,
                $indexColumns,
                $operator
            );
        }
        $options['LIMIT'] = intval( $limit );
        return [ $tables, $fields, $conds, $fname, $options, $join_conds ];
    }
 
    private function buildOffsetConds( $offsets, $columns, $operator ) {
        $innerConds = [];
        // $offsets and $columns are the same length
        for ( $i = 1; $i <= count( $offsets ); $i++ ) {
            $innerConds[] = $this->buildOffsetInnerConds(
                array_slice( $offsets, 0, $i ),
                array_slice( $columns, 0, $i ),
                $operator
            );
        }
        return $this->mDb->makeList( $innerConds, IDatabase::LIST_OR );
    }
 
    private function buildOffsetInnerConds( $offsets, $columns, $operator ) {
        $conds = [];
        while ( count( $offsets ) > 1 ) {
            $conds[] = $columns[0] . '=' . $this->mDb->addQuotes( $offsets[0] );
            array_shift( $columns );
            array_shift( $offsets );
        }
        $conds[] = $columns[0] . $operator . $this->mDb->addQuotes( $offsets[0] );
        return $this->mDb->makeList( $conds, IDatabase::LIST_AND );
    }
 
    protected function preprocessResults( $result ) {
    }
 
    public function getBody() {
        if ( !$this->mQueryDone ) {
            $this->doQuery();
        }
 
        if ( $this->mResult->numRows() ) {
            # Do any special query batches before display
            $this->doBatchLookups();
        }
 
        # Don't use any extra rows returned by the query
        $numRows = min( $this->mResult->numRows(), $this->mLimit );
 
        $s = $this->getStartBody();
        if ( $numRows ) {
            if ( $this->mIsBackwards ) {
                for ( $i = $numRows - 1; $i >= 0; $i-- ) {
                    $this->mResult->seek( $i );
                    $row = $this->mResult->fetchObject();
                    $s .= $this->formatRow( $row );
                }
            } else {
                $this->mResult->seek( 0 );
                for ( $i = 0; $i < $numRows; $i++ ) {
                    $row = $this->mResult->fetchObject();
                    $s .= $this->formatRow( $row );
                }
            }
        } else {
            $s .= $this->getEmptyBody();
        }
        $s .= $this->getEndBody();
        return $s;
    }
 
    protected function makeLink( $text, array $query = null, $type = null ) {
        if ( $query === null ) {
            return $text;
        }
 
        $attrs = [];
        if ( in_array( $type, [ 'prev', 'next' ] ) ) {
            $attrs['rel'] = $type;
        }
 
        if ( in_array( $type, [ 'asc', 'desc' ] ) ) {
            $attrs['title'] = $this->msg( $type == 'asc' ? 'sort-ascending' : 'sort-descending' )->text();
        }
 
        if ( $type ) {
            $attrs['class'] = "mw-{$type}link";
        }
 
        return $this->getLinkRenderer()->makeKnownLink(
            $this->getTitle(),
            new HtmlArmor( $text ),
            $attrs,
            $query + $this->getDefaultQuery()
        );
    }
 
    protected function doBatchLookups() {
    }
 
    protected function getStartBody() {
        return '';
    }
 
    protected function getEndBody() {
        return '';
    }
 
    protected function getEmptyBody() {
        return '';
    }
 
    public function getDefaultQuery() {
        if ( !isset( $this->mDefaultQuery ) ) {
            $this->mDefaultQuery = $this->getRequest()->getQueryValues();
            unset( $this->mDefaultQuery['title'] );
            unset( $this->mDefaultQuery['dir'] );
            unset( $this->mDefaultQuery['offset'] );
            unset( $this->mDefaultQuery['limit'] );
            unset( $this->mDefaultQuery['order'] );
            unset( $this->mDefaultQuery['month'] );
            unset( $this->mDefaultQuery['year'] );
        }
        return $this->mDefaultQuery;
    }
 
    public function getNumRows() {
        if ( !$this->mQueryDone ) {
            $this->doQuery();
        }
        return $this->mResult->numRows();
    }
 
    public function getPagingQueries() {
        if ( !$this->mQueryDone ) {
            $this->doQuery();
        }
 
        # Don't announce the limit everywhere if it's the default
        $urlLimit = $this->mLimit == $this->mDefaultLimit ? null : $this->mLimit;
 
        if ( $this->mIsFirst ) {
            $prev = false;
            $first = false;
        } else {
            $prev = [
                'dir' => 'prev',
                'offset' => implode( '|', (array)$this->mFirstShown ),
                'limit' => $urlLimit
            ];
            $first = [ 'limit' => $urlLimit ];
        }
        if ( $this->mIsLast ) {
            $next = false;
            $last = false;
        } else {
            $next = [ 'offset' => implode( '|', (array)$this->mLastShown ), 'limit' => $urlLimit ];
            $last = [ 'dir' => 'prev', 'limit' => $urlLimit ];
        }
 
        return [
            'prev' => $prev,
            'next' => $next,
            'first' => $first,
            'last' => $last
        ];
    }
 
    protected function isNavigationBarShown() {
        if ( !$this->mQueryDone ) {
            $this->doQuery();
        }
        // Hide navigation by default if there is nothing to page
        return !( $this->mIsFirst && $this->mIsLast );
    }
 
    protected function getPagingLinks( $linkTexts, $disabledTexts = [] ) {
        $queries = $this->getPagingQueries();
        $links = [];
 
        foreach ( $queries as $type => $query ) {
            if ( $query !== false ) {
                $links[$type] = $this->makeLink(
                    $linkTexts[$type],
                    $query,
                    $type
                );
            } elseif ( isset( $disabledTexts[$type] ) ) {
                $links[$type] = $disabledTexts[$type];
            } else {
                $links[$type] = $linkTexts[$type];
            }
        }
 
        return $links;
    }
 
    protected function getLimitLinks() {
        $links = [];
        if ( $this->mIsBackwards ) {
            $offset = implode( '|', (array)$this->mPastTheEndIndex );
        } else {
            $offset = $this->mOffset;
        }
        foreach ( $this->mLimitsShown as $limit ) {
            $links[] = $this->makeLink(
                $this->getLanguage()->formatNum( $limit ),
                [ 'offset' => $offset, 'limit' => $limit ],
                'num'
            );
        }
        return $links;
    }
 
    abstract public function formatRow( $row );
 
    abstract public function getQueryInfo();
 
    abstract public function getIndexField();
 
    protected function getExtraSortFields() {
        return [];
    }
 
    protected function getDefaultDirections() {
        return self::DIR_ASCENDING;
    }
 
    protected function buildPrevNextNavigation(
        Title $title,
        $offset,
        $limit,
        array $query = [],
        $atend = false
    ) {
        $prevNext = new PrevNextNavigationRenderer( $this );
 
        return $prevNext->buildPrevNextNavigation( $title, $offset, $limit, $query, $atend );
    }
 
    protected function getLinkRenderer() {
        if ( $this->linkRenderer === null ) {
             $this->linkRenderer = MediaWikiServices::getInstance()->getLinkRenderer();
        }
        return $this->linkRenderer;
    }
}