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