MediaWiki master
ApiQueryCategories.php
Go to the documentation of this file.
1<?php
26
33
38 public function __construct( ApiQuery $query, $moduleName ) {
39 parent::__construct( $query, $moduleName, 'cl' );
40 }
41
42 public function execute() {
43 $this->run();
44 }
45
46 public function getCacheMode( $params ) {
47 return 'public';
48 }
49
50 public function executeGenerator( $resultPageSet ) {
51 $this->run( $resultPageSet );
52 }
53
57 private function run( $resultPageSet = null ) {
58 $pages = $this->getPageSet()->getGoodPages();
59 if ( $pages === [] ) {
60 return; // nothing to do
61 }
62
64 $prop = array_fill_keys( (array)$params['prop'], true );
65 $show = array_fill_keys( (array)$params['show'], true );
66
67 $this->addFields( [
68 'cl_from',
69 'cl_to'
70 ] );
71
72 $this->addFieldsIf( [ 'cl_sortkey', 'cl_sortkey_prefix' ], isset( $prop['sortkey'] ) );
73 $this->addFieldsIf( 'cl_timestamp', isset( $prop['timestamp'] ) );
74
75 $this->addTables( 'categorylinks' );
76 $this->addWhereFld( 'cl_from', array_keys( $pages ) );
77 if ( $params['categories'] ) {
78 $cats = [];
79 foreach ( $params['categories'] as $cat ) {
80 $title = Title::newFromText( $cat );
81 if ( !$title || $title->getNamespace() !== NS_CATEGORY ) {
82 $this->addWarning( [ 'apiwarn-invalidcategory', wfEscapeWikiText( $cat ) ] );
83 } else {
84 $cats[] = $title->getDBkey();
85 }
86 }
87 if ( !$cats ) {
88 // No titles so no results
89 return;
90 }
91 $this->addWhereFld( 'cl_to', $cats );
92 }
93
94 if ( $params['continue'] !== null ) {
95 $db = $this->getDB();
96 $cont = $this->parseContinueParamOrDie( $params['continue'], [ 'int', 'string' ] );
97 $op = $params['dir'] == 'descending' ? '<=' : '>=';
98 $this->addWhere( $db->buildComparison( $op, [
99 'cl_from' => $cont[0],
100 'cl_to' => $cont[1],
101 ] ) );
102 }
103
104 if ( isset( $show['hidden'] ) && isset( $show['!hidden'] ) ) {
105 $this->dieWithError( 'apierror-show' );
106 }
107 if ( isset( $show['hidden'] ) || isset( $show['!hidden'] ) || isset( $prop['hidden'] ) ) {
108 $this->addOption( 'STRAIGHT_JOIN' );
109 $this->addTables( [ 'page', 'page_props' ] );
110 $this->addFieldsIf( 'pp_propname', isset( $prop['hidden'] ) );
111 $this->addJoinConds( [
112 'page' => [ 'LEFT JOIN', [
113 'page_namespace' => NS_CATEGORY,
114 'page_title = cl_to' ] ],
115 'page_props' => [ 'LEFT JOIN', [
116 'pp_page=page_id',
117 'pp_propname' => 'hiddencat' ] ]
118 ] );
119 if ( isset( $show['hidden'] ) ) {
120 $this->addWhere( [ 'pp_propname IS NOT NULL' ] );
121 } elseif ( isset( $show['!hidden'] ) ) {
122 $this->addWhere( [ 'pp_propname' => null ] );
123 }
124 }
125
126 $sort = ( $params['dir'] == 'descending' ? ' DESC' : '' );
127 // Don't order by cl_from if it's constant in the WHERE clause
128 if ( count( $pages ) === 1 ) {
129 $this->addOption( 'ORDER BY', 'cl_to' . $sort );
130 } else {
131 $this->addOption( 'ORDER BY', [
132 'cl_from' . $sort,
133 'cl_to' . $sort
134 ] );
135 }
136 $this->addOption( 'LIMIT', $params['limit'] + 1 );
137
138 $res = $this->select( __METHOD__ );
139
140 $count = 0;
141 if ( $resultPageSet === null ) {
142 foreach ( $res as $row ) {
143 if ( ++$count > $params['limit'] ) {
144 // We've reached the one extra which shows that
145 // there are additional pages to be had. Stop here...
146 $this->setContinueEnumParameter( 'continue', $row->cl_from . '|' . $row->cl_to );
147 break;
148 }
149
150 $title = Title::makeTitle( NS_CATEGORY, $row->cl_to );
151 $vals = [];
152 ApiQueryBase::addTitleInfo( $vals, $title );
153 if ( isset( $prop['sortkey'] ) ) {
154 $vals['sortkey'] = bin2hex( $row->cl_sortkey );
155 $vals['sortkeyprefix'] = $row->cl_sortkey_prefix;
156 }
157 if ( isset( $prop['timestamp'] ) ) {
158 $vals['timestamp'] = wfTimestamp( TS_ISO_8601, $row->cl_timestamp );
159 }
160 if ( isset( $prop['hidden'] ) ) {
161 $vals['hidden'] = $row->pp_propname !== null;
162 }
163
164 $fit = $this->addPageSubItem( $row->cl_from, $vals );
165 if ( !$fit ) {
166 $this->setContinueEnumParameter( 'continue', $row->cl_from . '|' . $row->cl_to );
167 break;
168 }
169 }
170 } else {
171 $titles = [];
172 foreach ( $res as $row ) {
173 if ( ++$count > $params['limit'] ) {
174 // We've reached the one extra which shows that
175 // there are additional pages to be had. Stop here...
176 $this->setContinueEnumParameter( 'continue', $row->cl_from . '|' . $row->cl_to );
177 break;
178 }
179
180 $titles[] = Title::makeTitle( NS_CATEGORY, $row->cl_to );
181 }
182 $resultPageSet->populateFromTitles( $titles );
183 }
184 }
185
186 public function getAllowedParams() {
187 return [
188 'prop' => [
189 ParamValidator::PARAM_ISMULTI => true,
190 ParamValidator::PARAM_TYPE => [
191 'sortkey',
192 'timestamp',
193 'hidden',
194 ],
196 ],
197 'show' => [
198 ParamValidator::PARAM_ISMULTI => true,
199 ParamValidator::PARAM_TYPE => [
200 'hidden',
201 '!hidden',
202 ]
203 ],
204 'limit' => [
205 ParamValidator::PARAM_DEFAULT => 10,
206 ParamValidator::PARAM_TYPE => 'limit',
207 IntegerDef::PARAM_MIN => 1,
208 IntegerDef::PARAM_MAX => ApiBase::LIMIT_BIG1,
209 IntegerDef::PARAM_MAX2 => ApiBase::LIMIT_BIG2
210 ],
211 'continue' => [
212 ApiBase::PARAM_HELP_MSG => 'api-help-param-continue',
213 ],
214 'categories' => [
215 ParamValidator::PARAM_ISMULTI => true,
216 ],
217 'dir' => [
218 ParamValidator::PARAM_DEFAULT => 'ascending',
219 ParamValidator::PARAM_TYPE => [
220 'ascending',
221 'descending'
222 ]
223 ],
224 ];
225 }
226
227 protected function getExamplesMessages() {
228 return [
229 'action=query&prop=categories&titles=Albert%20Einstein'
230 => 'apihelp-query+categories-example-simple',
231 'action=query&generator=categories&titles=Albert%20Einstein&prop=info'
232 => 'apihelp-query+categories-example-generator',
233 ];
234 }
235
236 public function getHelpUrls() {
237 return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Categories';
238 }
239}
const NS_CATEGORY
Definition Defines.php:79
wfEscapeWikiText( $input)
Escapes the given text so that it may be output using addWikiText() without any linking,...
wfTimestamp( $outputtype=TS_UNIX, $ts=0)
Get a timestamp string in one of various formats.
array $params
The job parameters.
run()
Run the job.
dieWithError( $msg, $code=null, $data=null, $httpCode=0)
Abort execution with an error.
Definition ApiBase.php:1540
parseContinueParamOrDie(string $continue, array $types)
Parse the 'continue' parameter in the usual format and validate the types of each part,...
Definition ApiBase.php:1731
const PARAM_HELP_MSG_PER_VALUE
((string|array|Message)[]) When PARAM_TYPE is an array, or 'string' with PARAM_ISMULTI,...
Definition ApiBase.php:212
const LIMIT_BIG1
Fast query, standard limit.
Definition ApiBase.php:237
extractRequestParams( $options=[])
Using getAllowedParams(), this function makes an array of the values provided by the user,...
Definition ApiBase.php:821
const PARAM_HELP_MSG
(string|array|Message) Specify an alternative i18n documentation message for this parameter.
Definition ApiBase.php:172
addWarning( $msg, $code=null, $data=null)
Add a warning for this module.
Definition ApiBase.php:1458
const LIMIT_BIG2
Fast query, apihighlimits limit.
Definition ApiBase.php:239
static addTitleInfo(&$arr, $title, $prefix='')
Add information (title and namespace) about a Title object to a result array.
addFields( $value)
Add a set of fields to select to the internal array.
addPageSubItem( $pageId, $item, $elemname=null)
Same as addPageSubItems(), but one element of $data at a time.
addOption( $name, $value=null)
Add an option such as LIMIT or USE INDEX.
addTables( $tables, $alias=null)
Add a set of tables 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.
addFieldsIf( $value, $condition)
Same as addFields(), but add the fields only if a condition is met.
addJoinConds( $join_conds)
Add a set of JOIN conditions to the internal array.
addWhereFld( $field, $value)
Equivalent to addWhere( [ $field => $value ] )
addWhere( $value)
Add a set of WHERE clauses to the internal array.
A query module to enumerate categories the set of pages belong to.
executeGenerator( $resultPageSet)
Execute this module as a generator.
__construct(ApiQuery $query, $moduleName)
getHelpUrls()
Return links to more detailed help pages about the module.
getExamplesMessages()
Returns usage examples for this module.
getAllowedParams()
Returns an array of allowed parameters (parameter name) => (default value) or (parameter name) => (ar...
execute()
Evaluates the parameters, performs the requested query, and sets up the result.
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.
getPageSet()
Get the PageSet object to work on.
This is the main query class.
Definition ApiQuery.php:43
Represents a title within MediaWiki.
Definition Title.php:79
Service for formatting and validating API parameters.
Type definition for integer types.