MediaWiki  master
ApiQueryCategories.php
Go to the documentation of this file.
1 <?php
29 
30  public function __construct( ApiQuery $query, $moduleName ) {
31  parent::__construct( $query, $moduleName, 'cl' );
32  }
33 
34  public function execute() {
35  $this->run();
36  }
37 
38  public function getCacheMode( $params ) {
39  return 'public';
40  }
41 
42  public function executeGenerator( $resultPageSet ) {
43  $this->run( $resultPageSet );
44  }
45 
49  private function run( $resultPageSet = null ) {
50  if ( $this->getPageSet()->getGoodTitleCount() == 0 ) {
51  return; // nothing to do
52  }
53 
54  $params = $this->extractRequestParams();
55  $prop = array_flip( (array)$params['prop'] );
56  $show = array_flip( (array)$params['show'] );
57 
58  $this->addFields( [
59  'cl_from',
60  'cl_to'
61  ] );
62 
63  $this->addFieldsIf( [ 'cl_sortkey', 'cl_sortkey_prefix' ], isset( $prop['sortkey'] ) );
64  $this->addFieldsIf( 'cl_timestamp', isset( $prop['timestamp'] ) );
65 
66  $this->addTables( 'categorylinks' );
67  $this->addWhereFld( 'cl_from', array_keys( $this->getPageSet()->getGoodTitles() ) );
68  if ( $params['categories'] ) {
69  $cats = [];
70  foreach ( $params['categories'] as $cat ) {
71  $title = Title::newFromText( $cat );
72  if ( !$title || $title->getNamespace() != NS_CATEGORY ) {
73  $this->addWarning( [ 'apiwarn-invalidcategory', wfEscapeWikiText( $cat ) ] );
74  } else {
75  $cats[] = $title->getDBkey();
76  }
77  }
78  if ( !$cats ) {
79  // No titles so no results
80  return;
81  }
82  $this->addWhereFld( 'cl_to', $cats );
83  }
84 
85  if ( !is_null( $params['continue'] ) ) {
86  $cont = explode( '|', $params['continue'] );
87  $this->dieContinueUsageIf( count( $cont ) != 2 );
88  $op = $params['dir'] == 'descending' ? '<' : '>';
89  $clfrom = (int)$cont[0];
90  $clto = $this->getDB()->addQuotes( $cont[1] );
91  $this->addWhere(
92  "cl_from $op $clfrom OR " .
93  "(cl_from = $clfrom AND " .
94  "cl_to $op= $clto)"
95  );
96  }
97 
98  if ( isset( $show['hidden'] ) && isset( $show['!hidden'] ) ) {
99  $this->dieWithError( 'apierror-show' );
100  }
101  if ( isset( $show['hidden'] ) || isset( $show['!hidden'] ) || isset( $prop['hidden'] ) ) {
102  $this->addOption( 'STRAIGHT_JOIN' );
103  $this->addTables( [ 'page', 'page_props' ] );
104  $this->addFieldsIf( 'pp_propname', isset( $prop['hidden'] ) );
105  $this->addJoinConds( [
106  'page' => [ 'LEFT JOIN', [
107  'page_namespace' => NS_CATEGORY,
108  'page_title = cl_to' ] ],
109  'page_props' => [ 'LEFT JOIN', [
110  'pp_page=page_id',
111  'pp_propname' => 'hiddencat' ] ]
112  ] );
113  if ( isset( $show['hidden'] ) ) {
114  $this->addWhere( [ 'pp_propname IS NOT NULL' ] );
115  } elseif ( isset( $show['!hidden'] ) ) {
116  $this->addWhere( [ 'pp_propname IS NULL' ] );
117  }
118  }
119 
120  $sort = ( $params['dir'] == 'descending' ? ' DESC' : '' );
121  // Don't order by cl_from if it's constant in the WHERE clause
122  if ( count( $this->getPageSet()->getGoodTitles() ) == 1 ) {
123  $this->addOption( 'ORDER BY', 'cl_to' . $sort );
124  } else {
125  $this->addOption( 'ORDER BY', [
126  'cl_from' . $sort,
127  'cl_to' . $sort
128  ] );
129  }
130  $this->addOption( 'LIMIT', $params['limit'] + 1 );
131 
132  $res = $this->select( __METHOD__ );
133 
134  $count = 0;
135  if ( is_null( $resultPageSet ) ) {
136  foreach ( $res as $row ) {
137  if ( ++$count > $params['limit'] ) {
138  // We've reached the one extra which shows that
139  // there are additional pages to be had. Stop here...
140  $this->setContinueEnumParameter( 'continue', $row->cl_from . '|' . $row->cl_to );
141  break;
142  }
143 
144  $title = Title::makeTitle( NS_CATEGORY, $row->cl_to );
145  $vals = [];
147  if ( isset( $prop['sortkey'] ) ) {
148  $vals['sortkey'] = bin2hex( $row->cl_sortkey );
149  $vals['sortkeyprefix'] = $row->cl_sortkey_prefix;
150  }
151  if ( isset( $prop['timestamp'] ) ) {
152  $vals['timestamp'] = wfTimestamp( TS_ISO_8601, $row->cl_timestamp );
153  }
154  if ( isset( $prop['hidden'] ) ) {
155  $vals['hidden'] = !is_null( $row->pp_propname );
156  }
157 
158  $fit = $this->addPageSubItem( $row->cl_from, $vals );
159  if ( !$fit ) {
160  $this->setContinueEnumParameter( 'continue', $row->cl_from . '|' . $row->cl_to );
161  break;
162  }
163  }
164  } else {
165  $titles = [];
166  foreach ( $res as $row ) {
167  if ( ++$count > $params['limit'] ) {
168  // We've reached the one extra which shows that
169  // there are additional pages to be had. Stop here...
170  $this->setContinueEnumParameter( 'continue', $row->cl_from . '|' . $row->cl_to );
171  break;
172  }
173 
174  $titles[] = Title::makeTitle( NS_CATEGORY, $row->cl_to );
175  }
176  $resultPageSet->populateFromTitles( $titles );
177  }
178  }
179 
180  public function getAllowedParams() {
181  return [
182  'prop' => [
183  ApiBase::PARAM_ISMULTI => true,
185  'sortkey',
186  'timestamp',
187  'hidden',
188  ],
190  ],
191  'show' => [
192  ApiBase::PARAM_ISMULTI => true,
194  'hidden',
195  '!hidden',
196  ]
197  ],
198  'limit' => [
199  ApiBase::PARAM_DFLT => 10,
200  ApiBase::PARAM_TYPE => 'limit',
201  ApiBase::PARAM_MIN => 1,
204  ],
205  'continue' => [
206  ApiBase::PARAM_HELP_MSG => 'api-help-param-continue',
207  ],
208  'categories' => [
209  ApiBase::PARAM_ISMULTI => true,
210  ],
211  'dir' => [
212  ApiBase::PARAM_DFLT => 'ascending',
214  'ascending',
215  'descending'
216  ]
217  ],
218  ];
219  }
220 
221  protected function getExamplesMessages() {
222  return [
223  'action=query&prop=categories&titles=Albert%20Einstein'
224  => 'apihelp-query+categories-example-simple',
225  'action=query&generator=categories&titles=Albert%20Einstein&prop=info'
226  => 'apihelp-query+categories-example-generator',
227  ];
228  }
229 
230  public function getHelpUrls() {
231  return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Categories';
232  }
233 }
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
wfEscapeWikiText( $text)
Escapes the given text so that it may be output using addWikiText() without any linking, formatting, etc.
static addTitleInfo(&$arr, $title, $prefix='')
Add information (title and namespace) about a Title object to a result array.
A query module to enumerate categories the set of pages belong to.
addJoinConds( $join_conds)
Add a set of JOIN conditions to the internal array.
const PARAM_DFLT
(null|boolean|integer|string) Default value of the parameter.
Definition: ApiBase.php:55
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
$sort
dieWithError( $msg, $code=null, $data=null, $httpCode=null)
Abort execution with an error.
Definition: ApiBase.php:2005
extractRequestParams( $options=[])
Using getAllowedParams(), this function makes an array of the values provided by the user...
Definition: ApiBase.php:761
const PARAM_HELP_MSG_PER_VALUE
((string|array|Message)[]) When PARAM_TYPE is an array, this is an array mapping those values to $msg...
Definition: ApiBase.php:164
setContinueEnumParameter( $paramName, $paramValue)
Overridden to set the generator param if in generator mode.
run( $resultPageSet=null)
addPageSubItem( $pageId, $item, $elemname=null)
Same as addPageSubItems(), but one element of $data at a time.
wfTimestamp( $outputtype=TS_UNIX, $ts=0)
Get a timestamp string in one of various formats.
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
const NS_CATEGORY
Definition: Defines.php:74
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
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
addWhere( $value)
Add a set of WHERE clauses to the internal array.
addWarning( $msg, $code=null, $data=null)
Add a warning for this module.
Definition: ApiBase.php:1924
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 ] )
addFieldsIf( $value, $condition)
Same as addFields(), but add the fields only if a condition is met.
executeGenerator( $resultPageSet)
addOption( $name, $value=null)
Add an option such as LIMIT or USE INDEX.
const PARAM_MIN
(integer) Lowest value allowed for the parameter, for PARAM_TYPE &#39;integer&#39; and &#39;limit&#39;.
Definition: ApiBase.php:106
getPageSet()
Get the PageSet object to work on.
__construct(ApiQuery $query, $moduleName)
static newFromText( $text, $defaultNamespace=NS_MAIN)
Create a new Title from text, such as what one would find in a link.
Definition: Title.php:319