MediaWiki master
ApiQueryCategoryMembers.php
Go to the documentation of this file.
1<?php
23namespace MediaWiki\Api;
24
25use Collation;
31
38
39 private Collation $collation;
40 private int $migrationStage;
41
42 public function __construct(
43 ApiQuery $query,
44 string $moduleName,
45 CollationFactory $collationFactory
46 ) {
47 parent::__construct( $query, $moduleName, 'cm' );
48 $this->collation = $collationFactory->getCategoryCollation();
49 $this->migrationStage = $query->getConfig()->get(
51 );
52 }
53
54 public function execute() {
55 $this->run();
56 }
57
58 public function getCacheMode( $params ) {
59 return 'public';
60 }
61
62 public function executeGenerator( $resultPageSet ) {
63 $this->run( $resultPageSet );
64 }
65
70 private function validateHexSortkey( $hexSortkey ) {
71 // A hex sortkey has an unbound number of 2 letter pairs
72 return (bool)preg_match( '/^(?:[a-fA-F0-9]{2})*$/D', $hexSortkey );
73 }
74
79 private function run( $resultPageSet = null ) {
80 $params = $this->extractRequestParams();
81
82 $categoryTitle = $this->getTitleOrPageId( $params )->getTitle();
83 if ( $categoryTitle->getNamespace() !== NS_CATEGORY ) {
84 $this->dieWithError( 'apierror-invalidcategory' );
85 }
86
87 $prop = array_fill_keys( $params['prop'], true );
88 $fld_ids = isset( $prop['ids'] );
89 $fld_title = isset( $prop['title'] );
90 $fld_sortkey = isset( $prop['sortkey'] );
91 $fld_sortkeyprefix = isset( $prop['sortkeyprefix'] );
92 $fld_timestamp = isset( $prop['timestamp'] );
93 $fld_type = isset( $prop['type'] );
94
95 if ( $resultPageSet === null ) {
96 $this->addFields( [ 'cl_from', 'cl_sortkey', 'cl_type', 'page_namespace', 'page_title' ] );
97 $this->addFieldsIf( 'page_id', $fld_ids );
98 $this->addFieldsIf( 'cl_sortkey_prefix', $fld_sortkeyprefix );
99 } else {
100 $this->addFields( $resultPageSet->getPageTableFields() ); // will include page_ id, ns, title
101 $this->addFields( [ 'cl_from', 'cl_sortkey', 'cl_type' ] );
102 }
103
104 $this->addFieldsIf( 'cl_timestamp', $fld_timestamp || $params['sort'] == 'timestamp' );
105
106 $this->addTables( [ 'page', 'categorylinks' ] ); // must be in this order for 'USE INDEX'
107 if ( $this->migrationStage & SCHEMA_COMPAT_READ_OLD ) {
108 $this->addWhereFld( 'cl_to', $categoryTitle->getDBkey() );
109 } else {
110 $this->addTables( 'linktarget' );
111 $this->addJoinConds( [ 'linktarget' => [ 'JOIN', 'cl_target_id = lt_id ' ] ] );
112 $this->addWhere( [
113 'lt_namespace' => NS_CATEGORY,
114 'lt_title' => $categoryTitle->getDBkey(),
115 ] );
116 }
117
118 $queryTypes = $params['type'];
119 $contWhere = false;
120
121 // Scanning large datasets for rare categories sucks, and I already told
122 // how to have efficient subcategory access :-) ~~~~ (oh well, domas)
123 $miser_ns = [];
124 if ( $this->getConfig()->get( MainConfigNames::MiserMode ) ) {
125 $miser_ns = $params['namespace'] ?: [];
126 } else {
127 $this->addWhereFld( 'page_namespace', $params['namespace'] );
128 }
129
130 $dir = in_array( $params['dir'], [ 'asc', 'ascending', 'newer' ] ) ? 'newer' : 'older';
131
132 if ( $params['sort'] == 'timestamp' ) {
133 $this->addTimestampWhereRange( 'cl_timestamp',
134 $dir,
135 $params['start'],
136 $params['end'] );
137 // Include in ORDER BY for uniqueness
138 $this->addWhereRange( 'cl_from', $dir, null, null );
139
140 if ( $params['continue'] !== null ) {
141 $cont = $this->parseContinueParamOrDie( $params['continue'], [ 'timestamp', 'int' ] );
142 $op = ( $dir === 'newer' ? '>=' : '<=' );
143 $db = $this->getDB();
144 $this->addWhere( $db->buildComparison( $op, [
145 'cl_timestamp' => $db->timestamp( $cont[0] ),
146 'cl_from' => $cont[1],
147 ] ) );
148 }
149
150 $this->addOption( 'USE INDEX', [ 'categorylinks' => 'cl_timestamp' ] );
151 } else {
152 if ( $params['continue'] ) {
153 $cont = $this->parseContinueParamOrDie( $params['continue'], [ 'string', 'string', 'int' ] );
154
155 // Remove the types to skip from $queryTypes
156 $contTypeIndex = array_search( $cont[0], $queryTypes );
157 $queryTypes = array_slice( $queryTypes, $contTypeIndex );
158
159 // Add a WHERE clause for sortkey and from
160 $this->dieContinueUsageIf( !$this->validateHexSortkey( $cont[1] ) );
161 $op = $dir == 'newer' ? '>=' : '<=';
162 // $contWhere is used further down
163 $contWhere = $this->getDB()->buildComparison( $op, [
164 'cl_sortkey' => hex2bin( $cont[1] ),
165 'cl_from' => $cont[2],
166 ] );
167 // The below produces ORDER BY cl_sortkey, cl_from, possibly with DESC added to each of them
168 $this->addWhereRange( 'cl_sortkey', $dir, null, null );
169 $this->addWhereRange( 'cl_from', $dir, null, null );
170 } else {
171 if ( $params['startsortkeyprefix'] !== null ) {
172 $startsortkey = $this->collation->getSortKey( $params['startsortkeyprefix'] );
173 } elseif ( $params['starthexsortkey'] !== null ) {
174 if ( !$this->validateHexSortkey( $params['starthexsortkey'] ) ) {
175 $encParamName = $this->encodeParamName( 'starthexsortkey' );
176 $this->dieWithError( [ 'apierror-badparameter', $encParamName ], "badvalue_$encParamName" );
177 }
178 $startsortkey = hex2bin( $params['starthexsortkey'] );
179 } else {
180 $startsortkey = $params['startsortkey'];
181 }
182 if ( $params['endsortkeyprefix'] !== null ) {
183 $endsortkey = $this->collation->getSortKey( $params['endsortkeyprefix'] );
184 } elseif ( $params['endhexsortkey'] !== null ) {
185 if ( !$this->validateHexSortkey( $params['endhexsortkey'] ) ) {
186 $encParamName = $this->encodeParamName( 'endhexsortkey' );
187 $this->dieWithError( [ 'apierror-badparameter', $encParamName ], "badvalue_$encParamName" );
188 }
189 $endsortkey = hex2bin( $params['endhexsortkey'] );
190 } else {
191 $endsortkey = $params['endsortkey'];
192 }
193
194 // The below produces ORDER BY cl_sortkey, cl_from, possibly with DESC added to each of them
195 $this->addWhereRange( 'cl_sortkey',
196 $dir,
197 $startsortkey,
198 $endsortkey );
199 $this->addWhereRange( 'cl_from', $dir, null, null );
200 }
201 $this->addOption( 'USE INDEX', [ 'categorylinks' => 'cl_sortkey' ] );
202 }
203
204 $this->addWhere( 'cl_from=page_id' );
205
206 $limit = $params['limit'];
207 $this->addOption( 'LIMIT', $limit + 1 );
208
209 if ( $params['sort'] == 'sortkey' ) {
210 // Run a separate SELECT query for each value of cl_type.
211 // This is needed because cl_type is an enum, and MySQL has
212 // inconsistencies between ORDER BY cl_type and
213 // WHERE cl_type >= 'foo' making proper paging impossible
214 // and unindexed.
215 $rows = [];
216 $first = true;
217 foreach ( $queryTypes as $type ) {
218 $extraConds = [ 'cl_type' => $type ];
219 if ( $first && $contWhere ) {
220 // Continuation condition. Only added to the
221 // first query, otherwise we'll skip things
222 $extraConds[] = $contWhere;
223 }
224 $res = $this->select( __METHOD__, [ 'where' => $extraConds ] );
225 if ( $type === 'page' && $resultPageSet === null ) {
226 $this->executeGenderCacheFromResultWrapper( $res, __METHOD__ );
227 }
228 $rows = array_merge( $rows, iterator_to_array( $res ) );
229 if ( count( $rows ) >= $limit + 1 ) {
230 break;
231 }
232 $first = false;
233 }
234 } else {
235 // Sorting by timestamp
236 // No need to worry about per-type queries because we
237 // aren't sorting or filtering by type anyway
238 $res = $this->select( __METHOD__ );
239 if ( $resultPageSet === null ) {
240 $this->executeGenderCacheFromResultWrapper( $res, __METHOD__ );
241 }
242 $rows = iterator_to_array( $res );
243 }
244
245 $result = $this->getResult();
246 $count = 0;
247 foreach ( $rows as $row ) {
248 if ( ++$count > $limit ) {
249 // We've reached the one extra which shows that there are
250 // additional pages to be had. Stop here...
251 // @todo Security issue - if the user has no right to view next
252 // title, it will still be shown
253 if ( $params['sort'] == 'timestamp' ) {
255 'continue',
256 $this->getDB()->timestamp( $row->cl_timestamp ) . "|$row->cl_from"
257 );
258 } else {
259 $sortkey = bin2hex( $row->cl_sortkey );
260 $this->setContinueEnumParameter( 'continue',
261 "{$row->cl_type}|$sortkey|{$row->cl_from}"
262 );
263 }
264 break;
265 }
266
267 // Since domas won't tell anyone what he told long ago, apply
268 // cmnamespace here. This means the query may return 0 actual
269 // results, but on the other hand it could save returning 5000
270 // useless results to the client. ~~~~
271 if ( count( $miser_ns ) && !in_array( $row->page_namespace, $miser_ns ) ) {
272 continue;
273 }
274
275 if ( $resultPageSet === null ) {
276 $vals = [
277 ApiResult::META_TYPE => 'assoc',
278 ];
279 if ( $fld_ids ) {
280 $vals['pageid'] = (int)$row->page_id;
281 }
282 if ( $fld_title ) {
283 $title = Title::makeTitle( $row->page_namespace, $row->page_title );
284 ApiQueryBase::addTitleInfo( $vals, $title );
285 }
286 if ( $fld_sortkey ) {
287 $vals['sortkey'] = bin2hex( $row->cl_sortkey );
288 }
289 if ( $fld_sortkeyprefix ) {
290 $vals['sortkeyprefix'] = $row->cl_sortkey_prefix;
291 }
292 if ( $fld_type ) {
293 $vals['type'] = $row->cl_type;
294 }
295 if ( $fld_timestamp ) {
296 $vals['timestamp'] = wfTimestamp( TS_ISO_8601, $row->cl_timestamp );
297 }
298 $fit = $result->addValue( [ 'query', $this->getModuleName() ],
299 null, $vals );
300 if ( !$fit ) {
301 if ( $params['sort'] == 'timestamp' ) {
303 'continue',
304 $this->getDB()->timestamp( $row->cl_timestamp ) . "|$row->cl_from"
305 );
306 } else {
307 $sortkey = bin2hex( $row->cl_sortkey );
308 $this->setContinueEnumParameter( 'continue',
309 "{$row->cl_type}|$sortkey|{$row->cl_from}"
310 );
311 }
312 break;
313 }
314 } else {
315 $resultPageSet->processDbRow( $row );
316 }
317 }
318
319 if ( $resultPageSet === null ) {
320 $result->addIndexedTagName(
321 [ 'query', $this->getModuleName() ], 'cm' );
322 }
323 }
324
325 public function getAllowedParams() {
326 $ret = [
327 'title' => [
328 ParamValidator::PARAM_TYPE => 'string',
329 ],
330 'pageid' => [
331 ParamValidator::PARAM_TYPE => 'integer'
332 ],
333 'prop' => [
334 ParamValidator::PARAM_DEFAULT => 'ids|title',
335 ParamValidator::PARAM_ISMULTI => true,
336 ParamValidator::PARAM_TYPE => [
337 'ids',
338 'title',
339 'sortkey',
340 'sortkeyprefix',
341 'type',
342 'timestamp',
343 ],
345 ],
346 'namespace' => [
347 ParamValidator::PARAM_ISMULTI => true,
348 ParamValidator::PARAM_TYPE => 'namespace',
349 ],
350 'type' => [
351 ParamValidator::PARAM_ISMULTI => true,
352 ParamValidator::PARAM_DEFAULT => 'page|subcat|file',
353 ParamValidator::PARAM_TYPE => [
354 'page',
355 'subcat',
356 'file'
357 ]
358 ],
359 'continue' => [
360 ApiBase::PARAM_HELP_MSG => 'api-help-param-continue',
361 ],
362 'limit' => [
363 ParamValidator::PARAM_TYPE => 'limit',
364 ParamValidator::PARAM_DEFAULT => 10,
365 IntegerDef::PARAM_MIN => 1,
366 IntegerDef::PARAM_MAX => ApiBase::LIMIT_BIG1,
367 IntegerDef::PARAM_MAX2 => ApiBase::LIMIT_BIG2
368 ],
369 'sort' => [
370 ParamValidator::PARAM_DEFAULT => 'sortkey',
371 ParamValidator::PARAM_TYPE => [
372 'sortkey',
373 'timestamp'
374 ]
375 ],
376 'dir' => [
377 ParamValidator::PARAM_DEFAULT => 'ascending',
378 ParamValidator::PARAM_TYPE => [
379 'asc',
380 'desc',
381 // Normalising with other modules
382 'ascending',
383 'descending',
384 'newer',
385 'older',
386 ]
387 ],
388 'start' => [
389 ParamValidator::PARAM_TYPE => 'timestamp'
390 ],
391 'end' => [
392 ParamValidator::PARAM_TYPE => 'timestamp'
393 ],
394 'starthexsortkey' => null,
395 'endhexsortkey' => null,
396 'startsortkeyprefix' => null,
397 'endsortkeyprefix' => null,
398 'startsortkey' => [
399 ParamValidator::PARAM_DEPRECATED => true,
400 ],
401 'endsortkey' => [
402 ParamValidator::PARAM_DEPRECATED => true,
403 ],
404 ];
405
406 if ( $this->getConfig()->get( MainConfigNames::MiserMode ) ) {
407 $ret['namespace'][ApiBase::PARAM_HELP_MSG_APPEND] = [
408 'api-help-param-limited-in-miser-mode',
409 ];
410 }
411
412 return $ret;
413 }
414
415 protected function getExamplesMessages() {
416 return [
417 'action=query&list=categorymembers&cmtitle=Category:Physics'
418 => 'apihelp-query+categorymembers-example-simple',
419 'action=query&generator=categorymembers&gcmtitle=Category:Physics&prop=info'
420 => 'apihelp-query+categorymembers-example-generator',
421 ];
422 }
423
424 public function getHelpUrls() {
425 return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Categorymembers';
426 }
427}
428
430class_alias( ApiQueryCategoryMembers::class, 'ApiQueryCategoryMembers' );
const SCHEMA_COMPAT_READ_OLD
Definition Defines.php:304
const NS_CATEGORY
Definition Defines.php:79
wfTimestamp( $outputtype=TS_UNIX, $ts=0)
Get a timestamp string in one of various formats.
dieWithError( $msg, $code=null, $data=null, $httpCode=0)
Abort execution with an error.
Definition ApiBase.php:1526
getModuleName()
Get the name of the module being executed by this instance.
Definition ApiBase.php:557
dieContinueUsageIf( $condition)
Die with the 'badcontinue' error.
Definition ApiBase.php:1750
parseContinueParamOrDie(string $continue, array $types)
Parse the 'continue' parameter in the usual format and validate the types of each part,...
Definition ApiBase.php:1711
getResult()
Get the result object.
Definition ApiBase.php:696
const PARAM_HELP_MSG_PER_VALUE
((string|array|Message)[]) When PARAM_TYPE is an array, or 'string' with PARAM_ISMULTI,...
Definition ApiBase.php:221
const PARAM_HELP_MSG_APPEND
((string|array|Message)[]) Specify additional i18n messages to append to the normal message for this ...
Definition ApiBase.php:189
const PARAM_HELP_MSG
(string|array|Message) Specify an alternative i18n documentation message for this parameter.
Definition ApiBase.php:181
const LIMIT_BIG2
Fast query, apihighlimits limit.
Definition ApiBase.php:248
extractRequestParams( $options=[])
Using getAllowedParams(), this function makes an array of the values provided by the user,...
Definition ApiBase.php:837
getTitleOrPageId( $params, $load=false)
Attempts to load a WikiPage object from a title or pageid parameter, if possible.
Definition ApiBase.php:1162
const LIMIT_BIG1
Fast query, standard limit.
Definition ApiBase.php:246
addOption( $name, $value=null)
Add an option such as LIMIT or USE INDEX.
addFieldsIf( $value, $condition)
Same as addFields(), but add the fields only if a condition is met.
static addTitleInfo(&$arr, $title, $prefix='')
Add information (title and namespace) about a Title object to a result array.
addTables( $tables, $alias=null)
Add a set of tables to the internal array.
addJoinConds( $join_conds)
Add a set of JOIN conditions to the internal array.
getDB()
Get the Query database connection (read-only)
select( $method, $extraQuery=[], ?array &$hookData=null)
Execute a SELECT query based on the values in the internal arrays.
addWhere( $value)
Add a set of WHERE clauses to the internal array.
executeGenderCacheFromResultWrapper(IResultWrapper $res, $fname=__METHOD__, $fieldPrefix='page')
Preprocess the result set to fill the GenderCache with the necessary information before using self::a...
addTimestampWhereRange( $field, $dir, $start, $end, $sort=true)
Add a WHERE clause corresponding to a range, similar to addWhereRange, but converts $start and $end t...
addWhereFld( $field, $value)
Equivalent to addWhere( [ $field => $value ] )
addFields( $value)
Add a set of fields to select to the internal array.
addWhereRange( $field, $dir, $start, $end, $sort=true)
Add a WHERE clause corresponding to a range, and an ORDER BY clause to sort in the right direction.
A query module to enumerate pages that belong to a category.
getAllowedParams()
Returns an array of allowed parameters (parameter name) => (default value) or (parameter name) => (ar...
executeGenerator( $resultPageSet)
Execute this module as a generator.
getHelpUrls()
Return links to more detailed help pages about the module.
execute()
Evaluates the parameters, performs the requested query, and sets up the result.
getExamplesMessages()
Returns usage examples for this module.
__construct(ApiQuery $query, string $moduleName, CollationFactory $collationFactory)
getCacheMode( $params)
Get the cache mode for the data generated by this module.
setContinueEnumParameter( $paramName, $paramValue)
Overridden to set the generator param if in generator mode.
encodeParamName( $paramName)
Overrides ApiBase to prepend 'g' to every generator parameter.
This is the main query class.
Definition ApiQuery.php:50
const META_TYPE
Key for the 'type' metadata item.
Common factory to construct collation classes.
A class containing constants representing the names of configuration variables.
const CategoryLinksSchemaMigrationStage
Name constant for the CategoryLinksSchemaMigrationStage setting, for use with Config::get()
const MiserMode
Name constant for the MiserMode setting, for use with Config::get()
Represents a title within MediaWiki.
Definition Title.php:78
Service for formatting and validating API parameters.
Type definition for integer types.
array $params
The job parameters.