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