MediaWiki  master
ApiQueryBacklinksprop.php
Go to the documentation of this file.
1 <?php
34 
35  // Data for the various modules implemented by this class
36  private static $settings = [
37  'redirects' => [
38  'code' => 'rd',
39  'prefix' => 'rd',
40  'linktable' => 'redirect',
41  'props' => [
42  'fragment',
43  ],
44  'showredirects' => false,
45  'show' => [
46  'fragment',
47  '!fragment',
48  ],
49  ],
50  'linkshere' => [
51  'code' => 'lh',
52  'prefix' => 'pl',
53  'linktable' => 'pagelinks',
54  'indexes' => [ 'pl_namespace', 'pl_backlinks_namespace' ],
55  'from_namespace' => true,
56  'showredirects' => true,
57  ],
58  'transcludedin' => [
59  'code' => 'ti',
60  'prefix' => 'tl',
61  'linktable' => 'templatelinks',
62  'indexes' => [ 'tl_namespace', 'tl_backlinks_namespace' ],
63  'from_namespace' => true,
64  'showredirects' => true,
65  ],
66  'fileusage' => [
67  'code' => 'fu',
68  'prefix' => 'il',
69  'linktable' => 'imagelinks',
70  'indexes' => [ 'il_to', 'il_backlinks_namespace' ],
71  'from_namespace' => true,
72  'to_namespace' => NS_FILE,
73  'exampletitle' => 'File:Example.jpg',
74  'showredirects' => true,
75  ],
76  ];
77 
78  public function __construct( ApiQuery $query, $moduleName ) {
79  parent::__construct( $query, $moduleName, self::$settings[$moduleName]['code'] );
80  }
81 
82  public function execute() {
83  $this->run();
84  }
85 
86  public function executeGenerator( $resultPageSet ) {
87  $this->run( $resultPageSet );
88  }
89 
93  private function run( ApiPageSet $resultPageSet = null ) {
94  $settings = self::$settings[$this->getModuleName()];
95 
96  $db = $this->getDB();
97  $params = $this->extractRequestParams();
98  $prop = array_flip( $params['prop'] );
99  $emptyString = $db->addQuotes( '' );
100 
101  $pageSet = $this->getPageSet();
102  $titles = $pageSet->getGoodAndMissingTitles();
103  $map = $pageSet->getGoodAndMissingTitlesByNamespace();
104 
105  // Add in special pages, they can theoretically have backlinks too.
106  // (although currently they only do for prop=redirects)
107  foreach ( $pageSet->getSpecialTitles() as $id => $title ) {
108  $titles[] = $title;
109  $map[$title->getNamespace()][$title->getDBkey()] = $id;
110  }
111 
112  // Determine our fields to query on
113  $p = $settings['prefix'];
114  $hasNS = !isset( $settings['to_namespace'] );
115  if ( $hasNS ) {
116  $bl_namespace = "{$p}_namespace";
117  $bl_title = "{$p}_title";
118  } else {
119  $bl_namespace = $settings['to_namespace'];
120  $bl_title = "{$p}_to";
121 
122  $titles = array_filter( $titles, function ( $t ) use ( $bl_namespace ) {
123  return $t->getNamespace() === $bl_namespace;
124  } );
125  $map = array_intersect_key( $map, [ $bl_namespace => true ] );
126  }
127  $bl_from = "{$p}_from";
128 
129  if ( !$titles ) {
130  return; // nothing to do
131  }
132  if ( $params['namespace'] !== null && count( $params['namespace'] ) === 0 ) {
133  return; // nothing to do
134  }
135 
136  // Figure out what we're sorting by, and add associated WHERE clauses.
137  // MySQL's query planner screws up if we include a field in ORDER BY
138  // when it's constant in WHERE, so we have to test that for each field.
139  $sortby = [];
140  if ( $hasNS && count( $map ) > 1 ) {
141  $sortby[$bl_namespace] = 'ns';
142  }
143  $theTitle = null;
144  foreach ( $map as $nsTitles ) {
145  reset( $nsTitles );
146  $key = key( $nsTitles );
147  if ( $theTitle === null ) {
148  $theTitle = $key;
149  }
150  if ( count( $nsTitles ) > 1 || $key !== $theTitle ) {
151  $sortby[$bl_title] = 'title';
152  break;
153  }
154  }
155  $miser_ns = null;
156  if ( $params['namespace'] !== null ) {
157  if ( empty( $settings['from_namespace'] ) ) {
158  if ( $this->getConfig()->get( 'MiserMode' ) ) {
159  $miser_ns = $params['namespace'];
160  } else {
161  $this->addWhereFld( 'page_namespace', $params['namespace'] );
162  }
163  } else {
164  $this->addWhereFld( "{$p}_from_namespace", $params['namespace'] );
165  if ( !empty( $settings['from_namespace'] )
166  && $params['namespace'] !== null && count( $params['namespace'] ) > 1
167  ) {
168  $sortby["{$p}_from_namespace"] = 'int';
169  }
170  }
171  }
172  $sortby[$bl_from] = 'int';
173 
174  // Now use the $sortby to figure out the continuation
175  if ( !is_null( $params['continue'] ) ) {
176  $cont = explode( '|', $params['continue'] );
177  $this->dieContinueUsageIf( count( $cont ) != count( $sortby ) );
178  $where = '';
179  $i = count( $sortby ) - 1;
180  foreach ( array_reverse( $sortby, true ) as $field => $type ) {
181  $v = $cont[$i];
182  switch ( $type ) {
183  case 'ns':
184  case 'int':
185  $v = (int)$v;
186  $this->dieContinueUsageIf( $v != $cont[$i] );
187  break;
188  default:
189  $v = $db->addQuotes( $v );
190  break;
191  }
192 
193  if ( $where === '' ) {
194  $where = "$field >= $v";
195  } else {
196  $where = "$field > $v OR ($field = $v AND ($where))";
197  }
198 
199  $i--;
200  }
201  $this->addWhere( $where );
202  }
203 
204  // Populate the rest of the query
205  $this->addTables( [ $settings['linktable'], 'page' ] );
206  $this->addWhere( "$bl_from = page_id" );
207 
208  if ( $this->getModuleName() === 'redirects' ) {
209  $this->addWhere( "rd_interwiki = $emptyString OR rd_interwiki IS NULL" );
210  }
211 
212  $this->addFields( array_keys( $sortby ) );
213  $this->addFields( [ 'bl_namespace' => $bl_namespace, 'bl_title' => $bl_title ] );
214  if ( is_null( $resultPageSet ) ) {
215  $fld_pageid = isset( $prop['pageid'] );
216  $fld_title = isset( $prop['title'] );
217  $fld_redirect = isset( $prop['redirect'] );
218 
219  $this->addFieldsIf( 'page_id', $fld_pageid );
220  $this->addFieldsIf( [ 'page_title', 'page_namespace' ], $fld_title );
221  $this->addFieldsIf( 'page_is_redirect', $fld_redirect );
222 
223  // prop=redirects
224  $fld_fragment = isset( $prop['fragment'] );
225  $this->addFieldsIf( 'rd_fragment', $fld_fragment );
226  } else {
227  $this->addFields( $resultPageSet->getPageTableFields() );
228  }
229 
230  $this->addFieldsIf( 'page_namespace', $miser_ns !== null );
231 
232  if ( $hasNS ) {
233  // Can't use LinkBatch because it throws away Special titles.
234  // And we already have the needed data structure anyway.
235  $this->addWhere( $db->makeWhereFrom2d( $map, $bl_namespace, $bl_title ) );
236  } else {
237  $where = [];
238  foreach ( $titles as $t ) {
239  if ( $t->getNamespace() == $bl_namespace ) {
240  $where[] = "$bl_title = " . $db->addQuotes( $t->getDBkey() );
241  }
242  }
243  $this->addWhere( $db->makeList( $where, LIST_OR ) );
244  }
245 
246  if ( $params['show'] !== null ) {
247  // prop=redirects only
248  $show = array_flip( $params['show'] );
249  if ( isset( $show['fragment'] ) && isset( $show['!fragment'] ) ||
250  isset( $show['redirect'] ) && isset( $show['!redirect'] )
251  ) {
252  $this->dieWithError( 'apierror-show' );
253  }
254  $this->addWhereIf( "rd_fragment != $emptyString", isset( $show['fragment'] ) );
255  $this->addWhereIf(
256  "rd_fragment = $emptyString OR rd_fragment IS NULL",
257  isset( $show['!fragment'] )
258  );
259  $this->addWhereIf( [ 'page_is_redirect' => 1 ], isset( $show['redirect'] ) );
260  $this->addWhereIf( [ 'page_is_redirect' => 0 ], isset( $show['!redirect'] ) );
261  }
262 
263  // Override any ORDER BY from above with what we calculated earlier.
264  $this->addOption( 'ORDER BY', array_keys( $sortby ) );
265 
266  // MySQL's optimizer chokes if we have too many values in "$bl_title IN
267  // (...)" and chooses the wrong index, so specify the correct index to
268  // use for the query. See T139056 for details.
269  if ( !empty( $settings['indexes'] ) ) {
270  list( $idxNoFromNS, $idxWithFromNS ) = $settings['indexes'];
271  if ( $params['namespace'] !== null && !empty( $settings['from_namespace'] ) ) {
272  $this->addOption( 'USE INDEX', [ $settings['linktable'] => $idxWithFromNS ] );
273  } else {
274  $this->addOption( 'USE INDEX', [ $settings['linktable'] => $idxNoFromNS ] );
275  }
276  }
277 
278  // MySQL (or at least 5.5.5-10.0.23-MariaDB) chooses a really bad query
279  // plan if it thinks there will be more matching rows in the linktable
280  // than are in page. Use STRAIGHT_JOIN here to force it to use the
281  // intended, fast plan. See T145079 for details.
282  $this->addOption( 'STRAIGHT_JOIN' );
283 
284  $this->addOption( 'LIMIT', $params['limit'] + 1 );
285 
286  $res = $this->select( __METHOD__ );
287 
288  if ( is_null( $resultPageSet ) ) {
289  $count = 0;
290  foreach ( $res as $row ) {
291  if ( ++$count > $params['limit'] ) {
292  // We've reached the one extra which shows that
293  // there are additional pages to be had. Stop here...
294  $this->setContinue( $row, $sortby );
295  break;
296  }
297 
298  if ( $miser_ns !== null && !in_array( $row->page_namespace, $miser_ns ) ) {
299  // Miser mode namespace check
300  continue;
301  }
302 
303  // Get the ID of the current page
304  $id = $map[$row->bl_namespace][$row->bl_title];
305 
306  $vals = [];
307  if ( $fld_pageid ) {
308  $vals['pageid'] = (int)$row->page_id;
309  }
310  if ( $fld_title ) {
312  Title::makeTitle( $row->page_namespace, $row->page_title )
313  );
314  }
315  if ( $fld_fragment && $row->rd_fragment !== null && $row->rd_fragment !== '' ) {
316  $vals['fragment'] = $row->rd_fragment;
317  }
318  if ( $fld_redirect ) {
319  $vals['redirect'] = (bool)$row->page_is_redirect;
320  }
321  $fit = $this->addPageSubItem( $id, $vals );
322  if ( !$fit ) {
323  $this->setContinue( $row, $sortby );
324  break;
325  }
326  }
327  } else {
328  $titles = [];
329  $count = 0;
330  foreach ( $res as $row ) {
331  if ( ++$count > $params['limit'] ) {
332  // We've reached the one extra which shows that
333  // there are additional pages to be had. Stop here...
334  $this->setContinue( $row, $sortby );
335  break;
336  }
337  $titles[] = Title::makeTitle( $row->page_namespace, $row->page_title );
338  }
339  $resultPageSet->populateFromTitles( $titles );
340  }
341  }
342 
343  private function setContinue( $row, $sortby ) {
344  $cont = [];
345  foreach ( $sortby as $field => $v ) {
346  $cont[] = $row->$field;
347  }
348  $this->setContinueEnumParameter( 'continue', implode( '|', $cont ) );
349  }
350 
351  public function getCacheMode( $params ) {
352  return 'public';
353  }
354 
355  public function getAllowedParams() {
356  $settings = self::$settings[$this->getModuleName()];
357 
358  $ret = [
359  'prop' => [
361  'pageid',
362  'title',
363  ],
364  ApiBase::PARAM_ISMULTI => true,
365  ApiBase::PARAM_DFLT => 'pageid|title',
367  ],
368  'namespace' => [
369  ApiBase::PARAM_ISMULTI => true,
370  ApiBase::PARAM_TYPE => 'namespace',
371  ],
372  'show' => null, // Will be filled/removed below
373  'limit' => [
374  ApiBase::PARAM_DFLT => 10,
375  ApiBase::PARAM_TYPE => 'limit',
376  ApiBase::PARAM_MIN => 1,
379  ],
380  'continue' => [
381  ApiBase::PARAM_HELP_MSG => 'api-help-param-continue',
382  ],
383  ];
384 
385  if ( empty( $settings['from_namespace'] ) && $this->getConfig()->get( 'MiserMode' ) ) {
386  $ret['namespace'][ApiBase::PARAM_HELP_MSG_APPEND] = [
387  'api-help-param-limited-in-miser-mode',
388  ];
389  }
390 
391  if ( !empty( $settings['showredirects'] ) ) {
392  $ret['prop'][ApiBase::PARAM_TYPE][] = 'redirect';
393  $ret['prop'][ApiBase::PARAM_DFLT] .= '|redirect';
394  }
395  if ( isset( $settings['props'] ) ) {
396  $ret['prop'][ApiBase::PARAM_TYPE] = array_merge(
397  $ret['prop'][ApiBase::PARAM_TYPE], $settings['props']
398  );
399  }
400 
401  $show = [];
402  if ( !empty( $settings['showredirects'] ) ) {
403  $show[] = 'redirect';
404  $show[] = '!redirect';
405  }
406  if ( isset( $settings['show'] ) ) {
407  $show = array_merge( $show, $settings['show'] );
408  }
409  if ( $show ) {
410  $ret['show'] = [
411  ApiBase::PARAM_TYPE => $show,
412  ApiBase::PARAM_ISMULTI => true,
413  ];
414  } else {
415  unset( $ret['show'] );
416  }
417 
418  return $ret;
419  }
420 
421  protected function getExamplesMessages() {
422  $settings = self::$settings[$this->getModuleName()];
423  $name = $this->getModuleName();
424  $path = $this->getModulePath();
425  $title = $settings['exampletitle'] ?? 'Main Page';
426  $etitle = rawurlencode( $title );
427 
428  return [
429  "action=query&prop={$name}&titles={$etitle}"
430  => "apihelp-$path-example-simple",
431  "action=query&generator={$name}&titles={$etitle}&prop=info"
432  => "apihelp-$path-example-generator",
433  ];
434  }
435 
436  public function getHelpUrls() {
437  $name = ucfirst( $this->getModuleName() );
438  return "https://www.mediawiki.org/wiki/Special:MyLanguage/API:{$name}";
439  }
440 }
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:88
getDB()
Get the Query database connection (read-only)
const LIMIT_BIG2
Fast query, apihighlimits limit.
Definition: ApiBase.php:255
deferred txt A few of the database updates required by various functions here can be deferred until after the result page is displayed to the user For updating the view updating the linked to tables after a etc PHP does not yet have any way to tell the server to actually return and disconnect while still running these but it might have such a feature in the future We handle these by creating a deferred update object and putting those objects on a global list
Definition: deferred.txt:11
static addTitleInfo(&$arr, $title, $prefix='')
Add information (title and namespace) about a Title object to a result array.
null for the local wiki Added should default to null in handler for backwards compatibility add a value to it if you want to add a cookie that have to vary cache options can modify $query
Definition: hooks.txt:1585
This class contains a list of pages that the client has requested.
Definition: ApiPageSet.php:40
null means default in associative array with keys and values unescaped Should be merged with default with a value of false meaning to suppress the attribute in associative array with keys and values unescaped noclasses & $ret
Definition: hooks.txt:1982
Apache License January AND DISTRIBUTION Definitions License shall mean the terms and conditions for use
run(ApiPageSet $resultPageSet=null)
static __construct(ApiQuery $query, $moduleName)
const PARAM_DFLT
(null|boolean|integer|string) Default value of the parameter.
Definition: ApiBase.php:49
const LIMIT_BIG1
Fast query, standard limit.
Definition: ApiBase.php:253
const PARAM_MAX
(integer) Max value allowed for the parameter, for PARAM_TYPE &#39;integer&#39; and &#39;limit&#39;.
Definition: ApiBase.php:91
dieWithError( $msg, $code=null, $data=null, $httpCode=null)
Abort execution with an error.
Definition: ApiBase.php:1991
extractRequestParams( $options=[])
Using getAllowedParams(), this function makes an array of the values provided by the user...
Definition: ApiBase.php:744
either a unescaped string or a HtmlArmor object after in associative array form externallinks including delete and has completed for all link tables whether this was an auto creation use $formDescriptor instead default is conds Array Extra conditions for the No matching items in log is displayed if loglist is empty msgKey Array If you want a nice box with a set this to the key of the message First element is the message key
Definition: hooks.txt:2151
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:158
setContinueEnumParameter( $paramName, $paramValue)
Overridden to set the generator param if in generator mode.
executeGenerator( $resultPageSet)
addPageSubItem( $pageId, $item, $elemname=null)
Same as addPageSubItems(), but one element of $data at a time.
const PARAM_HELP_MSG_APPEND
((string|array|Message)[]) Specify additional i18n messages to append to the normal message for this ...
Definition: ApiBase.php:132
addTables( $tables, $alias=null)
Add a set of tables to the internal array.
addWhereIf( $value, $condition)
Same as addWhere(), but add the WHERE clauses only if a condition is met.
$res
Definition: database.txt:21
dieContinueUsageIf( $condition)
Die with the &#39;badcontinue&#39; error.
Definition: ApiBase.php:2206
getModulePath()
Get the path to this module.
Definition: ApiBase.php:577
$params
this hook is for auditing only or null if authentication failed before getting that far or null if we can t even determine that When $user is not null
Definition: hooks.txt:780
namespace and then decline to actually register it file or subcat img or subcat $title
Definition: hooks.txt:925
getModuleName()
Get the name of the module being executed by this instance.
Definition: ApiBase.php:513
addFields( $value)
Add a set of fields to select to the internal array.
const NS_FILE
Definition: Defines.php:70
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:97
This is the main query class.
Definition: ApiQuery.php:36
This document is intended to provide useful advice for parties seeking to redistribute MediaWiki to end users It s targeted particularly at maintainers for Linux since it s been observed that distribution packages of MediaWiki often break We ve consistently had to recommend that users seeking support use official tarballs instead of their distribution s and this often solves whatever problem the user is having It would be nice if this could such as
Definition: distributors.txt:9
const PARAM_HELP_MSG
(string|array|Message) Specify an alternative i18n documentation message for this parameter...
Definition: ApiBase.php:125
const LIST_OR
Definition: Defines.php:46
static makeTitle( $ns, $title, $fragment='', $interwiki='')
Create a new Title from a namespace index and a DB key.
Definition: Title.php:589
injection txt This is an overview of how MediaWiki makes use of dependency injection The design described here grew from the discussion of RFC T384 The term dependency this means that anything an object needs to operate should be injected from the the object itself should only know narrow no concrete implementation of the logic it relies on The requirement to inject everything typically results in an architecture that based on two main types of and essentially stateless service objects that use other service objects to operate on the value objects As of the beginning MediaWiki is only starting to use the DI approach Much of the code still relies on global state or direct resulting in a highly cyclical dependency which acts as the top level factory for services in MediaWiki which can be used to gain access to default instances of various services MediaWikiServices however also allows new services to be defined and default services to be redefined Services are defined or redefined by providing a callback the instantiator that will return a new instance of the service When it will create an instance of MediaWikiServices and populate it with the services defined in the files listed by thereby bootstrapping the DI framework Per $wgServiceWiringFiles lists includes ServiceWiring php
Definition: injection.txt:35
linkcache txt The LinkCache class maintains a list of article titles and the information about whether or not the article exists in the database This is used to mark up links when displaying a page If the same link appears more than once on any page then it only has to be looked up once In most cases link lookups are done in batches with the LinkBatch class or the equivalent in so the link cache is mostly useful for short snippets of parsed and for links in the navigation areas of the skin The link cache was formerly used to track links used in a document for the purposes of updating the link tables This application is now deprecated To create a you can use the following $titles
Definition: linkcache.txt:17
addWhere( $value)
Add a set of WHERE clauses to the internal array.
const PARAM_ISMULTI
(boolean) Accept multiple pipe-separated values for this parameter (e.g.
Definition: ApiBase.php:52
addWhereFld( $field, $value)
Equivalent to addWhere(array($field => $value))
addFieldsIf( $value, $condition)
Same as addFields(), but add the fields only if a condition is met.
Allows to change the fields on the form that will be generated $name
Definition: hooks.txt:271
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:100
getPageSet()
Get the PageSet object to work on.
This implements prop=redirects, prop=linkshere, prop=catmembers, prop=transcludedin, and prop=fileusage.