3 * Copyright © 2006 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
24 * A query module to enumerate pages that belong to a category.
28 class ApiQueryCategoryMembers
extends ApiQueryGeneratorBase
{
30 public function __construct( ApiQuery
$query, $moduleName ) {
31 parent
::__construct( $query, $moduleName, 'cm' );
34 public function execute() {
38 public function getCacheMode( $params ) {
42 public function executeGenerator( $resultPageSet ) {
43 $this->run( $resultPageSet );
47 * @param string $hexSortkey
50 private function validateHexSortkey( $hexSortkey ) {
51 // A hex sortkey has an unbound number of 2 letter pairs
52 return (bool)preg_match( '/^(?:[a-fA-F0-9]{2})*$/D', $hexSortkey );
56 * @param ApiPageSet $resultPageSet
59 private function run( $resultPageSet = null ) {
60 $params = $this->extractRequestParams();
62 $categoryTitle = $this->getTitleOrPageId( $params )->getTitle();
63 if ( $categoryTitle->getNamespace() != NS_CATEGORY
) {
64 $this->dieWithError( 'apierror-invalidcategory' );
67 $prop = array_flip( $params['prop'] );
68 $fld_ids = isset( $prop['ids'] );
69 $fld_title = isset( $prop['title'] );
70 $fld_sortkey = isset( $prop['sortkey'] );
71 $fld_sortkeyprefix = isset( $prop['sortkeyprefix'] );
72 $fld_timestamp = isset( $prop['timestamp'] );
73 $fld_type = isset( $prop['type'] );
75 if ( is_null( $resultPageSet ) ) {
76 $this->addFields( [ 'cl_from', 'cl_sortkey', 'cl_type', 'page_namespace', 'page_title' ] );
77 $this->addFieldsIf( 'page_id', $fld_ids );
78 $this->addFieldsIf( 'cl_sortkey_prefix', $fld_sortkeyprefix );
80 $this->addFields( $resultPageSet->getPageTableFields() ); // will include page_ id, ns, title
81 $this->addFields( [ 'cl_from', 'cl_sortkey', 'cl_type' ] );
84 $this->addFieldsIf( 'cl_timestamp', $fld_timestamp ||
$params['sort'] == 'timestamp' );
86 $this->addTables( [ 'page', 'categorylinks' ] ); // must be in this order for 'USE INDEX'
88 $this->addWhereFld( 'cl_to', $categoryTitle->getDBkey() );
89 $queryTypes = $params['type'];
92 // Scanning large datasets for rare categories sucks, and I already told
93 // how to have efficient subcategory access :-) ~~~~ (oh well, domas)
95 if ( $this->getConfig()->get( 'MiserMode' ) ) {
96 $miser_ns = $params['namespace'] ?
: [];
98 $this->addWhereFld( 'page_namespace', $params['namespace'] );
101 $dir = in_array( $params['dir'], [ 'asc', 'ascending', 'newer' ] ) ?
'newer' : 'older';
103 if ( $params['sort'] == 'timestamp' ) {
104 $this->addTimestampWhereRange( 'cl_timestamp',
108 // Include in ORDER BY for uniqueness
109 $this->addWhereRange( 'cl_from', $dir, null, null );
111 if ( !is_null( $params['continue'] ) ) {
112 $cont = explode( '|', $params['continue'] );
113 $this->dieContinueUsageIf( count( $cont ) != 2 );
114 $op = ( $dir === 'newer' ?
'>' : '<' );
115 $db = $this->getDB();
116 $continueTimestamp = $db->addQuotes( $db->timestamp( $cont[0] ) );
117 $continueFrom = (int)$cont[1];
118 $this->dieContinueUsageIf( $continueFrom != $cont[1] );
119 $this->addWhere( "cl_timestamp $op $continueTimestamp OR " .
120 "(cl_timestamp = $continueTimestamp AND " .
121 "cl_from $op= $continueFrom)"
125 $this->addOption( 'USE INDEX', 'cl_timestamp' );
127 if ( $params['continue'] ) {
128 $cont = explode( '|', $params['continue'], 3 );
129 $this->dieContinueUsageIf( count( $cont ) != 3 );
131 // Remove the types to skip from $queryTypes
132 $contTypeIndex = array_search( $cont[0], $queryTypes );
133 $queryTypes = array_slice( $queryTypes, $contTypeIndex );
135 // Add a WHERE clause for sortkey and from
136 $this->dieContinueUsageIf( !$this->validateHexSortkey( $cont[1] ) );
137 $escSortkey = $this->getDB()->addQuotes( hex2bin( $cont[1] ) );
138 $from = intval( $cont[2] );
139 $op = $dir == 'newer' ?
'>' : '<';
140 // $contWhere is used further down
141 $contWhere = "cl_sortkey $op $escSortkey OR " .
142 "(cl_sortkey = $escSortkey AND " .
143 "cl_from $op= $from)";
144 // The below produces ORDER BY cl_sortkey, cl_from, possibly with DESC added to each of them
145 $this->addWhereRange( 'cl_sortkey', $dir, null, null );
146 $this->addWhereRange( 'cl_from', $dir, null, null );
148 if ( $params['startsortkeyprefix'] !== null ) {
149 $startsortkey = Collation
::singleton()->getSortKey( $params['startsortkeyprefix'] );
150 } elseif ( $params['starthexsortkey'] !== null ) {
151 if ( !$this->validateHexSortkey( $params['starthexsortkey'] ) ) {
152 $encParamName = $this->encodeParamName( 'starthexsortkey' );
153 $this->dieWithError( [ 'apierror-badparameter', $encParamName ], "badvalue_$encParamName" );
155 $startsortkey = hex2bin( $params['starthexsortkey'] );
157 $startsortkey = $params['startsortkey'];
159 if ( $params['endsortkeyprefix'] !== null ) {
160 $endsortkey = Collation
::singleton()->getSortKey( $params['endsortkeyprefix'] );
161 } elseif ( $params['endhexsortkey'] !== null ) {
162 if ( !$this->validateHexSortkey( $params['endhexsortkey'] ) ) {
163 $encParamName = $this->encodeParamName( 'endhexsortkey' );
164 $this->dieWithError( [ 'apierror-badparameter', $encParamName ], "badvalue_$encParamName" );
166 $endsortkey = hex2bin( $params['endhexsortkey'] );
168 $endsortkey = $params['endsortkey'];
171 // The below produces ORDER BY cl_sortkey, cl_from, possibly with DESC added to each of them
172 $this->addWhereRange( 'cl_sortkey',
176 $this->addWhereRange( 'cl_from', $dir, null, null );
178 $this->addOption( 'USE INDEX', 'cl_sortkey' );
181 $this->addWhere( 'cl_from=page_id' );
183 $limit = $params['limit'];
184 $this->addOption( 'LIMIT', $limit +
1 );
186 if ( $params['sort'] == 'sortkey' ) {
187 // Run a separate SELECT query for each value of cl_type.
188 // This is needed because cl_type is an enum, and MySQL has
189 // inconsistencies between ORDER BY cl_type and
190 // WHERE cl_type >= 'foo' making proper paging impossible
194 foreach ( $queryTypes as $type ) {
195 $extraConds = [ 'cl_type' => $type ];
196 if ( $first && $contWhere ) {
197 // Continuation condition. Only added to the
198 // first query, otherwise we'll skip things
199 $extraConds[] = $contWhere;
201 $res = $this->select( __METHOD__
, [ 'where' => $extraConds ] );
202 $rows = array_merge( $rows, iterator_to_array( $res ) );
203 if ( count( $rows ) >= $limit +
1 ) {
209 // Sorting by timestamp
210 // No need to worry about per-type queries because we
211 // aren't sorting or filtering by type anyway
212 $res = $this->select( __METHOD__
);
213 $rows = iterator_to_array( $res );
216 $result = $this->getResult();
218 foreach ( $rows as $row ) {
219 if ( ++
$count > $limit ) {
220 // We've reached the one extra which shows that there are
221 // additional pages to be had. Stop here...
222 // @todo Security issue - if the user has no right to view next
223 // title, it will still be shown
224 if ( $params['sort'] == 'timestamp' ) {
225 $this->setContinueEnumParameter( 'continue', "$row->cl_timestamp|$row->cl_from" );
227 $sortkey = bin2hex( $row->cl_sortkey
);
228 $this->setContinueEnumParameter( 'continue',
229 "{$row->cl_type}|$sortkey|{$row->cl_from}"
235 // Since domas won't tell anyone what he told long ago, apply
236 // cmnamespace here. This means the query may return 0 actual
237 // results, but on the other hand it could save returning 5000
238 // useless results to the client. ~~~~
239 if ( count( $miser_ns ) && !in_array( $row->page_namespace
, $miser_ns ) ) {
243 if ( is_null( $resultPageSet ) ) {
245 ApiResult
::META_TYPE
=> 'assoc',
248 $vals['pageid'] = intval( $row->page_id
);
251 $title = Title
::makeTitle( $row->page_namespace
, $row->page_title
);
252 ApiQueryBase
::addTitleInfo( $vals, $title );
254 if ( $fld_sortkey ) {
255 $vals['sortkey'] = bin2hex( $row->cl_sortkey
);
257 if ( $fld_sortkeyprefix ) {
258 $vals['sortkeyprefix'] = $row->cl_sortkey_prefix
;
261 $vals['type'] = $row->cl_type
;
263 if ( $fld_timestamp ) {
264 $vals['timestamp'] = wfTimestamp( TS_ISO_8601
, $row->cl_timestamp
);
266 $fit = $result->addValue( [ 'query', $this->getModuleName() ],
269 if ( $params['sort'] == 'timestamp' ) {
270 $this->setContinueEnumParameter( 'continue', "$row->cl_timestamp|$row->cl_from" );
272 $sortkey = bin2hex( $row->cl_sortkey
);
273 $this->setContinueEnumParameter( 'continue',
274 "{$row->cl_type}|$sortkey|{$row->cl_from}"
280 $resultPageSet->processDbRow( $row );
284 if ( is_null( $resultPageSet ) ) {
285 $result->addIndexedTagName(
286 [ 'query', $this->getModuleName() ], 'cm' );
290 public function getAllowedParams() {
293 ApiBase
::PARAM_TYPE
=> 'string',
296 ApiBase
::PARAM_TYPE
=> 'integer'
299 ApiBase
::PARAM_DFLT
=> 'ids|title',
300 ApiBase
::PARAM_ISMULTI
=> true,
301 ApiBase
::PARAM_TYPE
=> [
309 ApiBase
::PARAM_HELP_MSG_PER_VALUE
=> [],
312 ApiBase
::PARAM_ISMULTI
=> true,
313 ApiBase
::PARAM_TYPE
=> 'namespace',
316 ApiBase
::PARAM_ISMULTI
=> true,
317 ApiBase
::PARAM_DFLT
=> 'page|subcat|file',
318 ApiBase
::PARAM_TYPE
=> [
325 ApiBase
::PARAM_HELP_MSG
=> 'api-help-param-continue',
328 ApiBase
::PARAM_TYPE
=> 'limit',
329 ApiBase
::PARAM_DFLT
=> 10,
330 ApiBase
::PARAM_MIN
=> 1,
331 ApiBase
::PARAM_MAX
=> ApiBase
::LIMIT_BIG1
,
332 ApiBase
::PARAM_MAX2
=> ApiBase
::LIMIT_BIG2
335 ApiBase
::PARAM_DFLT
=> 'sortkey',
336 ApiBase
::PARAM_TYPE
=> [
342 ApiBase
::PARAM_DFLT
=> 'ascending',
343 ApiBase
::PARAM_TYPE
=> [
346 // Normalising with other modules
354 ApiBase
::PARAM_TYPE
=> 'timestamp'
357 ApiBase
::PARAM_TYPE
=> 'timestamp'
359 'starthexsortkey' => null,
360 'endhexsortkey' => null,
361 'startsortkeyprefix' => null,
362 'endsortkeyprefix' => null,
364 ApiBase
::PARAM_DEPRECATED
=> true,
367 ApiBase
::PARAM_DEPRECATED
=> true,
371 if ( $this->getConfig()->get( 'MiserMode' ) ) {
372 $ret['namespace'][ApiBase
::PARAM_HELP_MSG_APPEND
] = [
373 'api-help-param-limited-in-miser-mode',
380 protected function getExamplesMessages() {
382 'action=query&list=categorymembers&cmtitle=Category:Physics'
383 => 'apihelp-query+categorymembers-example-simple',
384 'action=query&generator=categorymembers&gcmtitle=Category:Physics&prop=info'
385 => 'apihelp-query+categorymembers-example-generator',
389 public function getHelpUrls() {
390 return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Categorymembers';