includes/pager/RangeChronologicalPager.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  */
  20
  21 namespace MediaWiki\Pager;
  22
  23 use MediaWiki\Utils\MWTimestamp;
  24 use Wikimedia\Timestamp\TimestampException;
  25
  26 /**
  27  * Pager for filtering by a range of dates.
  28  *
  29  * @stable to extend
  30  * @ingroup Pager
  31  */
  32 abstract class RangeChronologicalPager extends ReverseChronologicalPager {
  33
  34         /**
  35          * @var string[]
  36          * @deprecated since 1.40, use $startOffset and $endOffset instead.
  37          */
  38         protected $rangeConds;
  39
  40         /** @var string */
  41         protected $startOffset;
  42
  43         /**
  44          * Set and return a date range condition using timestamps provided by the user.
  45          * We want the revisions between the two timestamps.
  46          * Also supports only having a start or end timestamp.
  47          * Assumes that the start timestamp comes before the end timestamp.
  48          *
  49          * @stable to override
  50          *
  51          * @param string $startTime Timestamp of the beginning of the date range (or empty)
  52          * @param string $endTime Timestamp of the end of the date range (or empty)
  53          * @return array|null Database conditions to satisfy the specified date range
  54          *     or null if dates are invalid
  55          */
  56         public function getDateRangeCond( $startTime, $endTime ) {
  57                 // Construct the conds array for compatibility with callers and derived classes
  58                 $this->rangeConds = [];
  59
  60                 try {
  61                         if ( $startTime !== '' ) {
  62                                 $startTimestamp = MWTimestamp::getInstance( $startTime );
  63                                 $this->startOffset = $this->mDb->timestamp( $startTimestamp->getTimestamp() );
  64                                 $this->rangeConds[] = $this->mDb->buildComparison( '>=',
  65                                         [ $this->getTimestampField() => $this->startOffset ] );
  66                         }
  67
  68                         if ( $endTime !== '' ) {
  69                                 $endTimestamp = MWTimestamp::getInstance( $endTime );
  70                                 // Turned to use '<' for consistency with the parent class,
  71                                 // add one second for compatibility with existing use cases
  72                                 $endTimestamp->timestamp = $endTimestamp->timestamp->modify( '+1 second' );
  73                                 $this->endOffset = $this->mDb->timestamp( $endTimestamp->getTimestamp() );
  74                                 $this->rangeConds[] = $this->mDb->buildComparison( '<',
  75                                         [ $this->getTimestampField() => $this->endOffset ] );
  76
  77                                 // populate existing variables for compatibility with parent
  78                                 $this->mYear = (int)$endTimestamp->format( 'Y' );
  79                                 $this->mMonth = (int)$endTimestamp->format( 'm' );
  80                                 $this->mDay = (int)$endTimestamp->format( 'd' );
  81                         }
  82                 } catch ( TimestampException $ex ) {
  83                         return null;
  84                 }
  85
  86                 return $this->rangeConds;
  87         }
  88
  89         /**
  90          * Return the range of date offsets, in the format of [ endOffset, startOffset ].
  91          * Extensions can use this to get the range if they are not in the context of subclasses.
  92          *
  93          * @since 1.40
  94          * @return string[]
  95          */
  96         public function getRangeOffsets() {
  97                 return [ $this->endOffset, $this->startOffset ];
  98         }
  99
 100         /**
 101          * @inheritDoc
 102          */
 103         protected function buildQueryInfo( $offset, $limit, $order ) {
 104                 [ $tables, $fields, $conds, $fname, $options, $join_conds ] = parent::buildQueryInfo(
 105                         $offset,
 106                         $limit,
 107                         $order
 108                 );
 109                 // End of the range has been added by ReverseChronologicalPager
 110                 if ( $this->startOffset ) {
 111                         $conds[] = $this->mDb->expr( $this->getTimestampField(), '>=', $this->startOffset );
 112                 } elseif ( $this->rangeConds ) {
 113                         // Keep compatibility with some derived classes, T325034
 114                         $conds = array_merge( $conds, $this->rangeConds );
 115                 }
 116
 117                 return [ $tables, $fields, $conds, $fname, $options, $join_conds ];
 118         }
 119 }
 120
 121 /** @deprecated class alias since 1.41 */
 122 class_alias( RangeChronologicalPager::class, 'RangeChronologicalPager' );