MediaWiki  master
ApiQueryRandom.php
Go to the documentation of this file.
1 <?php
2 
30  public function __construct( ApiQuery $query, $moduleName ) {
31  parent::__construct( $query, $moduleName, 'rn' );
32  }
33 
34  public function execute() {
35  $this->run();
36  }
37 
38  public function executeGenerator( $resultPageSet ) {
39  $this->run( $resultPageSet );
40  }
41 
51  protected function runQuery( $resultPageSet, $limit, $start, $startId, $end ) {
52  $params = $this->extractRequestParams();
53 
54  $this->resetQueryParams();
55  $this->addTables( 'page' );
56  $this->addFields( [ 'page_id', 'page_random' ] );
57  if ( is_null( $resultPageSet ) ) {
58  $this->addFields( [ 'page_title', 'page_namespace' ] );
59  } else {
60  $this->addFields( $resultPageSet->getPageTableFields() );
61  }
62  $this->addWhereFld( 'page_namespace', $params['namespace'] );
63  if ( $params['redirect'] || $params['filterredir'] === 'redirects' ) {
64  $this->addWhereFld( 'page_is_redirect', 1 );
65  } elseif ( $params['filterredir'] === 'nonredirects' ) {
66  $this->addWhereFld( 'page_is_redirect', 0 );
67  } elseif ( is_null( $resultPageSet ) ) {
68  $this->addFields( [ 'page_is_redirect' ] );
69  }
70  $this->addOption( 'LIMIT', $limit + 1 );
71 
72  if ( $start !== null ) {
73  $start = $this->getDB()->addQuotes( $start );
74  if ( $startId > 0 ) {
75  $startId = (int)$startId; // safety
76  $this->addWhere( "page_random = $start AND page_id >= $startId OR page_random > $start" );
77  } else {
78  $this->addWhere( "page_random >= $start" );
79  }
80  }
81  if ( $end !== null ) {
82  $this->addWhere( 'page_random < ' . $this->getDB()->addQuotes( $end ) );
83  }
84  $this->addOption( 'ORDER BY', [ 'page_random', 'page_id' ] );
85 
86  $result = $this->getResult();
87  $path = [ 'query', $this->getModuleName() ];
88 
89  $res = $this->select( __METHOD__ );
90  $count = 0;
91  foreach ( $res as $row ) {
92  if ( $count++ >= $limit ) {
93  return [ 0, "{$row->page_random}|{$row->page_id}" ];
94  }
95  if ( is_null( $resultPageSet ) ) {
96  $title = Title::makeTitle( $row->page_namespace, $row->page_title );
97  $page = [
98  'id' => (int)$row->page_id,
99  ];
101  if ( isset( $row->page_is_redirect ) ) {
102  $page['redirect'] = (bool)$row->page_is_redirect;
103  }
104  $fit = $result->addValue( $path, null, $page );
105  if ( !$fit ) {
106  return [ 0, "{$row->page_random}|{$row->page_id}" ];
107  }
108  } else {
109  $resultPageSet->processDbRow( $row );
110  }
111  }
112 
113  return [ $limit - $count, null ];
114  }
115 
119  public function run( $resultPageSet = null ) {
120  $params = $this->extractRequestParams();
121 
122  // Since 'filterredir" will always be set in $params, we have to dig
123  // into the WebRequest to see if it was actually passed.
124  $request = $this->getMain()->getRequest();
125  if ( $request->getCheck( $this->encodeParamName( 'filterredir' ) ) ) {
126  $this->requireMaxOneParameter( $params, 'filterredir', 'redirect' );
127  }
128 
129  if ( isset( $params['continue'] ) ) {
130  $cont = explode( '|', $params['continue'] );
131  $this->dieContinueUsageIf( count( $cont ) != 4 );
132  $rand = $cont[0];
133  $start = $cont[1];
134  $startId = (int)$cont[2];
135  $end = $cont[3] ? $rand : null;
136  $this->dieContinueUsageIf( !preg_match( '/^0\.\d+$/', $rand ) );
137  $this->dieContinueUsageIf( !preg_match( '/^0\.\d+$/', $start ) );
138  $this->dieContinueUsageIf( $cont[2] !== (string)$startId );
139  $this->dieContinueUsageIf( $cont[3] !== '0' && $cont[3] !== '1' );
140  } else {
141  $rand = wfRandom();
142  $start = $rand;
143  $startId = 0;
144  $end = null;
145  }
146 
147  // Set the non-continue if this is being used as a generator
148  // (as a list it doesn't matter because lists never non-continue)
149  if ( $resultPageSet !== null ) {
150  $endFlag = $end === null ? 0 : 1;
151  $this->getContinuationManager()->addGeneratorNonContinueParam(
152  $this, 'continue', "$rand|$start|$startId|$endFlag"
153  );
154  }
155 
156  list( $left, $continue ) =
157  $this->runQuery( $resultPageSet, $params['limit'], $start, $startId, $end );
158  if ( $end === null && $continue === null ) {
159  // Wrap around. We do this even if $left === 0 for continuation
160  // (saving a DB query in this rare case probably isn't worth the
161  // added code complexity it would require).
162  $end = $rand;
163  list( $left, $continue ) = $this->runQuery( $resultPageSet, $left, null, null, $end );
164  }
165 
166  if ( $continue !== null ) {
167  $endFlag = $end === null ? 0 : 1;
168  $this->setContinueEnumParameter( 'continue', "$rand|$continue|$endFlag" );
169  }
170 
171  if ( is_null( $resultPageSet ) ) {
172  $this->getResult()->addIndexedTagName( [ 'query', $this->getModuleName() ], 'page' );
173  }
174  }
175 
176  public function getCacheMode( $params ) {
177  return 'public';
178  }
179 
180  public function getAllowedParams() {
181  return [
182  'namespace' => [
183  ApiBase::PARAM_TYPE => 'namespace',
185  ],
186  'filterredir' => [
187  ApiBase::PARAM_TYPE => [ 'all', 'redirects', 'nonredirects' ],
188  ApiBase::PARAM_DFLT => 'nonredirects', // for BC
189  ],
190  'redirect' => [
192  ApiBase::PARAM_DFLT => false,
193  ],
194  'limit' => [
195  ApiBase::PARAM_TYPE => 'limit',
196  ApiBase::PARAM_DFLT => 1,
197  ApiBase::PARAM_MIN => 1,
200  ],
201  'continue' => [
202  ApiBase::PARAM_HELP_MSG => 'api-help-param-continue'
203  ],
204  ];
205  }
206 
207  protected function getExamplesMessages() {
208  return [
209  'action=query&list=random&rnnamespace=0&rnlimit=2'
210  => 'apihelp-query+random-example-simple',
211  'action=query&generator=random&grnnamespace=0&grnlimit=2&prop=info'
212  => 'apihelp-query+random-example-generator',
213  ];
214  }
215 
216  public function getHelpUrls() {
217  return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Random';
218  }
219 }
getCacheMode( $params)
select( $method, $extraQuery=[], array &$hookData=null)
Execute a SELECT query based on the values in the internal arrays.
const PARAM_TYPE
(string|string[]) Either an array of allowed value strings, or a string type as described below...
Definition: ApiBase.php:94
getDB()
Get the Query database connection (read-only)
const LIMIT_BIG2
Fast query, apihighlimits limit.
Definition: ApiBase.php:261
static addTitleInfo(&$arr, $title, $prefix='')
Add information (title and namespace) about a Title object to a result array.
getResult()
Get the result object.
Definition: ApiBase.php:640
const PARAM_DFLT
(null|boolean|integer|string) Default value of the parameter.
Definition: ApiBase.php:55
getMain()
Get the main module.
Definition: ApiBase.php:536
const LIMIT_BIG1
Fast query, standard limit.
Definition: ApiBase.php:259
const PARAM_MAX
(integer) Max value allowed for the parameter, for PARAM_TYPE &#39;integer&#39; and &#39;limit&#39;.
Definition: ApiBase.php:97
executeGenerator( $resultPageSet)
extractRequestParams( $options=[])
Using getAllowedParams(), this function makes an array of the values provided by the user...
Definition: ApiBase.php:761
setContinueEnumParameter( $paramName, $paramValue)
Overridden to set the generator param if in generator mode.
Query module to get list of random pages.
run( $resultPageSet=null)
addTables( $tables, $alias=null)
Add a set of tables to the internal array.
dieContinueUsageIf( $condition)
Die with the &#39;badcontinue&#39; error.
Definition: ApiBase.php:2199
getContinuationManager()
Get the continuation manager.
Definition: ApiBase.php:680
getModuleName()
Get the name of the module being executed by this instance.
Definition: ApiBase.php:520
addFields( $value)
Add a set of fields to select to the internal array.
const PARAM_MAX2
(integer) Max value allowed for the parameter for users with the apihighlimits right, for PARAM_TYPE &#39;limit&#39;.
Definition: ApiBase.php:103
This is the main query class.
Definition: ApiQuery.php:37
runQuery( $resultPageSet, $limit, $start, $startId, $end)
Actually perform the query and add pages to the result.
const PARAM_HELP_MSG
(string|array|Message) Specify an alternative i18n documentation message for this parameter...
Definition: ApiBase.php:131
static makeTitle( $ns, $title, $fragment='', $interwiki='')
Create a new Title from a namespace index and a DB key.
Definition: Title.php:586
wfRandom()
Get a random decimal value in the domain of [0, 1), in a way not likely to give duplicate values for ...
addWhere( $value)
Add a set of WHERE clauses to the internal array.
const PARAM_ISMULTI
(boolean) Accept multiple pipe-separated values for this parameter (e.g.
Definition: ApiBase.php:58
addWhereFld( $field, $value)
Equivalent to addWhere( [ $field => $value ] )
__construct(ApiQuery $query, $moduleName)
addOption( $name, $value=null)
Add an option such as LIMIT or USE INDEX.
const PARAM_DEPRECATED
(boolean) Is the parameter deprecated (will show a warning)?
Definition: ApiBase.php:112
const PARAM_MIN
(integer) Lowest value allowed for the parameter, for PARAM_TYPE &#39;integer&#39; and &#39;limit&#39;.
Definition: ApiBase.php:106
requireMaxOneParameter( $params,... $required)
Die if more than one of a certain set of parameters is set and not false.
Definition: ApiBase.php:928
return true
Definition: router.php:92
resetQueryParams()
Blank the internal arrays with query parameters.