Merge "Support ApiPageSet in ApiWatch"
[lhc/web/wiklou.git] / includes / api / ApiPageSet.php
1 <?php
2 /**
3 *
4 *
5 * Created on Sep 24, 2006
6 *
7 * Copyright © 2006, 2013 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
8 *
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
13 *
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License along
20 * with this program; if not, write to the Free Software Foundation, Inc.,
21 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
22 * http://www.gnu.org/copyleft/gpl.html
23 *
24 * @file
25 */
26
27 /**
28 * This class contains a list of pages that the client has requested.
29 * Initially, when the client passes in titles=, pageids=, or revisions=
30 * parameter, an instance of the ApiPageSet class will normalize titles,
31 * determine if the pages/revisions exist, and prefetch any additional page
32 * data requested.
33 *
34 * When a generator is used, the result of the generator will become the input
35 * for the second instance of this class, and all subsequent actions will use
36 * the second instance for all their work.
37 *
38 * @ingroup API
39 * @since 1.21 derives from ApiBase instead of ApiQueryBase
40 */
41 class ApiPageSet extends ApiBase {
42
43 /**
44 * Constructor flag: The new instance of ApiPageSet will ignore the 'generator=' parameter
45 * @since 1.21
46 */
47 const DISABLE_GENERATORS = 1;
48
49 private $mDbSource;
50 private $mParams;
51 private $mResolveRedirects;
52 private $mConvertTitles;
53 private $mAllowGenerator;
54
55 private $mAllPages = array(); // [ns][dbkey] => page_id or negative when missing
56 private $mTitles = array();
57 private $mGoodTitles = array();
58 private $mMissingTitles = array();
59 private $mInvalidTitles = array();
60 private $mMissingPageIDs = array();
61 private $mRedirectTitles = array();
62 private $mSpecialTitles = array();
63 private $mNormalizedTitles = array();
64 private $mInterwikiTitles = array();
65 private $mPendingRedirectIDs = array();
66 private $mConvertedTitles = array();
67 private $mGoodRevIDs = array();
68 private $mMissingRevIDs = array();
69 private $mFakePageId = -1;
70 private $mCacheMode = 'public';
71 private $mRequestedPageFields = array();
72 /**
73 * @var int
74 */
75 private $mDefaultNamespace = NS_MAIN;
76
77 /**
78 * Add all items from $values into the result
79 * @param array $result output
80 * @param array $values values to add
81 * @param string $flag the name of the boolean flag to mark this element
82 * @param string $name if given, name of the value
83 */
84 private static function addValues( array &$result, $values, $flag = null, $name = null ) {
85 foreach ( $values as $val ) {
86 if ( $val instanceof Title ) {
87 $v = array();
88 ApiQueryBase::addTitleInfo( $v, $val );
89 } elseif ( $name !== null ) {
90 $v = array( $name => $val );
91 } else {
92 $v = $val;
93 }
94 if ( $flag !== null ) {
95 $v[$flag] = '';
96 }
97 $result[] = $v;
98 }
99 }
100
101 /**
102 * Constructor
103 * @param $dbSource ApiBase Module implementing getDB().
104 * Allows PageSet to reuse existing db connection from the shared state like ApiQuery.
105 * @param int $flags Zero or more flags like DISABLE_GENERATORS
106 * @param int $defaultNamespace the namespace to use if none is specified by a prefix.
107 * @since 1.21 accepts $flags instead of two boolean values
108 */
109 public function __construct( ApiBase $dbSource, $flags = 0, $defaultNamespace = NS_MAIN ) {
110 parent::__construct( $dbSource->getMain(), $dbSource->getModuleName() );
111 $this->mDbSource = $dbSource;
112 $this->mAllowGenerator = ( $flags & ApiPageSet::DISABLE_GENERATORS ) == 0;
113 $this->mDefaultNamespace = $defaultNamespace;
114
115 $this->profileIn();
116 $this->mParams = $this->extractRequestParams();
117 $this->mResolveRedirects = $this->mParams['redirects'];
118 $this->mConvertTitles = $this->mParams['converttitles'];
119 $this->profileOut();
120 }
121
122 /**
123 * In case execute() is not called, call this method to mark all relevant parameters as used
124 * This prevents unused parameters from being reported as warnings
125 */
126 public function executeDryRun() {
127 $this->executeInternal( true );
128 }
129
130 /**
131 * Populate the PageSet from the request parameters.
132 */
133 public function execute() {
134 $this->executeInternal( false );
135 }
136
137 /**
138 * Populate the PageSet from the request parameters.
139 * @param bool $isDryRun If true, instantiates generator, but only to mark
140 * relevant parameters as used
141 */
142 private function executeInternal( $isDryRun ) {
143 $this->profileIn();
144
145 $generatorName = $this->mAllowGenerator ? $this->mParams['generator'] : null;
146 if ( isset( $generatorName ) ) {
147 $dbSource = $this->mDbSource;
148 $isQuery = $dbSource instanceof ApiQuery;
149 if ( !$isQuery ) {
150 // If the parent container of this pageset is not ApiQuery, we must create it to run generator
151 $dbSource = $this->getMain()->getModuleManager()->getModule( 'query' );
152 // Enable profiling for query module because it will be used for db sql profiling
153 $dbSource->profileIn();
154 }
155 $generator = $dbSource->getModuleManager()->getModule( $generatorName, null, true );
156 if ( $generator === null ) {
157 $this->dieUsage( 'Unknown generator=' . $generatorName, 'badgenerator' );
158 }
159 if ( !$generator instanceof ApiQueryGeneratorBase ) {
160 $this->dieUsage( "Module $generatorName cannot be used as a generator", 'badgenerator' );
161 }
162 // Create a temporary pageset to store generator's output,
163 // add any additional fields generator may need, and execute pageset to populate titles/pageids
164 $tmpPageSet = new ApiPageSet( $dbSource, ApiPageSet::DISABLE_GENERATORS );
165 $generator->setGeneratorMode( $tmpPageSet );
166 $this->mCacheMode = $generator->getCacheMode( $generator->extractRequestParams() );
167
168 if ( !$isDryRun ) {
169 $generator->requestExtraData( $tmpPageSet );
170 }
171 $tmpPageSet->executeInternal( $isDryRun );
172
173 // populate this pageset with the generator output
174 $this->profileOut();
175 $generator->profileIn();
176
177 if ( !$isDryRun ) {
178 $generator->executeGenerator( $this );
179 wfRunHooks( 'APIQueryGeneratorAfterExecute', array( &$generator, &$this ) );
180 } else {
181 // Prevent warnings from being reported on these parameters
182 $main = $this->getMain();
183 foreach ( $generator->extractRequestParams() as $paramName => $param ) {
184 $main->getVal( $generator->encodeParamName( $paramName ) );
185 }
186 }
187 $generator->profileOut();
188 $this->profileIn();
189
190 if ( !$isDryRun ) {
191 $this->resolvePendingRedirects();
192 }
193
194 if ( !$isQuery ) {
195 // If this pageset is not part of the query, we called profileIn() above
196 $dbSource->profileOut();
197 }
198 } else {
199 // Only one of the titles/pageids/revids is allowed at the same time
200 $dataSource = null;
201 if ( isset( $this->mParams['titles'] ) ) {
202 $dataSource = 'titles';
203 }
204 if ( isset( $this->mParams['pageids'] ) ) {
205 if ( isset( $dataSource ) ) {
206 $this->dieUsage( "Cannot use 'pageids' at the same time as '$dataSource'", 'multisource' );
207 }
208 $dataSource = 'pageids';
209 }
210 if ( isset( $this->mParams['revids'] ) ) {
211 if ( isset( $dataSource ) ) {
212 $this->dieUsage( "Cannot use 'revids' at the same time as '$dataSource'", 'multisource' );
213 }
214 $dataSource = 'revids';
215 }
216
217 if ( !$isDryRun ) {
218 // Populate page information with the original user input
219 switch ( $dataSource ) {
220 case 'titles':
221 $this->initFromTitles( $this->mParams['titles'] );
222 break;
223 case 'pageids':
224 $this->initFromPageIds( $this->mParams['pageids'] );
225 break;
226 case 'revids':
227 if ( $this->mResolveRedirects ) {
228 $this->setWarning( 'Redirect resolution cannot be used ' .
229 'together with the revids= parameter. Any redirects ' .
230 'the revids= point to have not been resolved.' );
231 }
232 $this->mResolveRedirects = false;
233 $this->initFromRevIDs( $this->mParams['revids'] );
234 break;
235 default:
236 // Do nothing - some queries do not need any of the data sources.
237 break;
238 }
239 }
240 }
241 $this->profileOut();
242 }
243
244 /**
245 * Check whether this PageSet is resolving redirects
246 * @return bool
247 */
248 public function isResolvingRedirects() {
249 return $this->mResolveRedirects;
250 }
251
252 /**
253 * Return the parameter name that is the source of data for this PageSet
254 *
255 * If multiple source parameters are specified (e.g. titles and pageids),
256 * one will be named arbitrarily.
257 *
258 * @return string|null
259 */
260 public function getDataSource() {
261 if ( $this->mAllowGenerator && isset( $this->mParams['generator'] ) ) {
262 return 'generator';
263 }
264 if ( isset( $this->mParams['titles'] ) ) {
265 return 'titles';
266 }
267 if ( isset( $this->mParams['pageids'] ) ) {
268 return 'pageids';
269 }
270 if ( isset( $this->mParams['revids'] ) ) {
271 return 'revids';
272 }
273
274 return null;
275 }
276
277 /**
278 * Request an additional field from the page table.
279 * Must be called before execute()
280 * @param string $fieldName Field name
281 */
282 public function requestField( $fieldName ) {
283 $this->mRequestedPageFields[$fieldName] = null;
284 }
285
286 /**
287 * Get the value of a custom field previously requested through
288 * requestField()
289 * @param string $fieldName Field name
290 * @return mixed Field value
291 */
292 public function getCustomField( $fieldName ) {
293 return $this->mRequestedPageFields[$fieldName];
294 }
295
296 /**
297 * Get the fields that have to be queried from the page table:
298 * the ones requested through requestField() and a few basic ones
299 * we always need
300 * @return array of field names
301 */
302 public function getPageTableFields() {
303 // Ensure we get minimum required fields
304 // DON'T change this order
305 $pageFlds = array(
306 'page_namespace' => null,
307 'page_title' => null,
308 'page_id' => null,
309 );
310
311 if ( $this->mResolveRedirects ) {
312 $pageFlds['page_is_redirect'] = null;
313 }
314
315 // only store non-default fields
316 $this->mRequestedPageFields = array_diff_key( $this->mRequestedPageFields, $pageFlds );
317
318 $pageFlds = array_merge( $pageFlds, $this->mRequestedPageFields );
319
320 return array_keys( $pageFlds );
321 }
322
323 /**
324 * Returns an array [ns][dbkey] => page_id for all requested titles.
325 * page_id is a unique negative number in case title was not found.
326 * Invalid titles will also have negative page IDs and will be in namespace 0
327 * @return array
328 */
329 public function getAllTitlesByNamespace() {
330 return $this->mAllPages;
331 }
332
333 /**
334 * All Title objects provided.
335 * @return Title[]
336 */
337 public function getTitles() {
338 return $this->mTitles;
339 }
340
341 /**
342 * Returns the number of unique pages (not revisions) in the set.
343 * @return int
344 */
345 public function getTitleCount() {
346 return count( $this->mTitles );
347 }
348
349 /**
350 * Title objects that were found in the database.
351 * @return Title[] Array page_id (int) => Title (obj)
352 */
353 public function getGoodTitles() {
354 return $this->mGoodTitles;
355 }
356
357 /**
358 * Returns the number of found unique pages (not revisions) in the set.
359 * @return int
360 */
361 public function getGoodTitleCount() {
362 return count( $this->mGoodTitles );
363 }
364
365 /**
366 * Title objects that were NOT found in the database.
367 * The array's index will be negative for each item
368 * @return Title[]
369 */
370 public function getMissingTitles() {
371 return $this->mMissingTitles;
372 }
373
374 /**
375 * Titles that were deemed invalid by Title::newFromText()
376 * The array's index will be unique and negative for each item
377 * @return string[] Array of strings (not Title objects)
378 */
379 public function getInvalidTitles() {
380 return $this->mInvalidTitles;
381 }
382
383 /**
384 * Page IDs that were not found in the database
385 * @return array of page IDs
386 */
387 public function getMissingPageIDs() {
388 return $this->mMissingPageIDs;
389 }
390
391 /**
392 * Get a list of redirect resolutions - maps a title to its redirect
393 * target, as an array of output-ready arrays
394 * @return array
395 */
396 public function getRedirectTitles() {
397 return $this->mRedirectTitles;
398 }
399
400 /**
401 * Get a list of redirect resolutions - maps a title to its redirect
402 * target.
403 * @param $result ApiResult
404 * @return array of prefixed_title (string) => Title object
405 * @since 1.21
406 */
407 public function getRedirectTitlesAsResult( $result = null ) {
408 $values = array();
409 foreach ( $this->getRedirectTitles() as $titleStrFrom => $titleTo ) {
410 $r = array(
411 'from' => strval( $titleStrFrom ),
412 'to' => $titleTo->getPrefixedText(),
413 );
414 if ( $titleTo->hasFragment() ) {
415 $r['tofragment'] = $titleTo->getFragment();
416 }
417 $values[] = $r;
418 }
419 if ( !empty( $values ) && $result ) {
420 $result->setIndexedTagName( $values, 'r' );
421 }
422
423 return $values;
424 }
425
426 /**
427 * Get a list of title normalizations - maps a title to its normalized
428 * version.
429 * @return array raw_prefixed_title (string) => prefixed_title (string)
430 */
431 public function getNormalizedTitles() {
432 return $this->mNormalizedTitles;
433 }
434
435 /**
436 * Get a list of title normalizations - maps a title to its normalized
437 * version in the form of result array.
438 * @param $result ApiResult
439 * @return array of raw_prefixed_title (string) => prefixed_title (string)
440 * @since 1.21
441 */
442 public function getNormalizedTitlesAsResult( $result = null ) {
443 $values = array();
444 foreach ( $this->getNormalizedTitles() as $rawTitleStr => $titleStr ) {
445 $values[] = array(
446 'from' => $rawTitleStr,
447 'to' => $titleStr
448 );
449 }
450 if ( !empty( $values ) && $result ) {
451 $result->setIndexedTagName( $values, 'n' );
452 }
453
454 return $values;
455 }
456
457 /**
458 * Get a list of title conversions - maps a title to its converted
459 * version.
460 * @return array raw_prefixed_title (string) => prefixed_title (string)
461 */
462 public function getConvertedTitles() {
463 return $this->mConvertedTitles;
464 }
465
466 /**
467 * Get a list of title conversions - maps a title to its converted
468 * version as a result array.
469 * @param $result ApiResult
470 * @return array of (from, to) strings
471 * @since 1.21
472 */
473 public function getConvertedTitlesAsResult( $result = null ) {
474 $values = array();
475 foreach ( $this->getConvertedTitles() as $rawTitleStr => $titleStr ) {
476 $values[] = array(
477 'from' => $rawTitleStr,
478 'to' => $titleStr
479 );
480 }
481 if ( !empty( $values ) && $result ) {
482 $result->setIndexedTagName( $values, 'c' );
483 }
484
485 return $values;
486 }
487
488 /**
489 * Get a list of interwiki titles - maps a title to its interwiki
490 * prefix.
491 * @return array raw_prefixed_title (string) => interwiki_prefix (string)
492 */
493 public function getInterwikiTitles() {
494 return $this->mInterwikiTitles;
495 }
496
497 /**
498 * Get a list of interwiki titles - maps a title to its interwiki
499 * prefix as result.
500 * @param $result ApiResult
501 * @param $iwUrl boolean
502 * @return array raw_prefixed_title (string) => interwiki_prefix (string)
503 * @since 1.21
504 */
505 public function getInterwikiTitlesAsResult( $result = null, $iwUrl = false ) {
506 $values = array();
507 foreach ( $this->getInterwikiTitles() as $rawTitleStr => $interwikiStr ) {
508 $item = array(
509 'title' => $rawTitleStr,
510 'iw' => $interwikiStr,
511 );
512 if ( $iwUrl ) {
513 $title = Title::newFromText( $rawTitleStr );
514 $item['url'] = $title->getFullURL( '', false, PROTO_CURRENT );
515 }
516 $values[] = $item;
517 }
518 if ( !empty( $values ) && $result ) {
519 $result->setIndexedTagName( $values, 'i' );
520 }
521
522 return $values;
523 }
524
525 /**
526 * Get an array of invalid/special/missing titles.
527 *
528 * @param $invalidChecks List of types of invalid titles to include.
529 * Recognized values are:
530 * - invalidTitles: Titles from $this->getInvalidTitles()
531 * - special: Titles from $this->getSpecialTitles()
532 * - missingIds: ids from $this->getMissingPageIDs()
533 * - missingRevIds: ids from $this->getMissingRevisionIDs()
534 * - missingTitles: Titles from $this->getMissingTitles()
535 * - interwikiTitles: Titles from $this->getInterwikiTitlesAsResult()
536 * @return array Array suitable for inclusion in the response
537 * @since 1.23
538 */
539 public function getInvalidTitlesAndRevisions( $invalidChecks = array( 'invalidTitles', 'special', 'missingIds', 'missingRevIds', 'missingTitles', 'interwikiTitles' ) ) {
540 $result = array();
541 if ( in_array( "invalidTitles", $invalidChecks ) ) {
542 self::addValues( $result, $this->getInvalidTitles(), 'invalid', 'title' );
543 }
544 if ( in_array( "special", $invalidChecks ) ) {
545 self::addValues( $result, $this->getSpecialTitles(), 'special', 'title' );
546 }
547 if ( in_array( "missingIds", $invalidChecks ) ) {
548 self::addValues( $result, $this->getMissingPageIDs(), 'missing', 'pageid' );
549 }
550 if ( in_array( "missingRevIds", $invalidChecks ) ) {
551 self::addValues( $result, $this->getMissingRevisionIDs(), 'missing', 'revid' );
552 }
553 if ( in_array( "missingTitles", $invalidChecks ) ) {
554 self::addValues( $result, $this->getMissingTitles(), 'missing' );
555 }
556 if ( in_array( "interwikiTitles", $invalidChecks ) ) {
557 self::addValues( $result, $this->getInterwikiTitlesAsResult() );
558 }
559 return $result;
560 }
561
562 /**
563 * Get the list of revision IDs (requested with the revids= parameter)
564 * @return array revID (int) => pageID (int)
565 */
566 public function getRevisionIDs() {
567 return $this->mGoodRevIDs;
568 }
569
570 /**
571 * Revision IDs that were not found in the database
572 * @return array of revision IDs
573 */
574 public function getMissingRevisionIDs() {
575 return $this->mMissingRevIDs;
576 }
577
578 /**
579 * Revision IDs that were not found in the database as result array.
580 * @param $result ApiResult
581 * @return array of revision IDs
582 * @since 1.21
583 */
584 public function getMissingRevisionIDsAsResult( $result = null ) {
585 $values = array();
586 foreach ( $this->getMissingRevisionIDs() as $revid ) {
587 $values[$revid] = array(
588 'revid' => $revid
589 );
590 }
591 if ( !empty( $values ) && $result ) {
592 $result->setIndexedTagName( $values, 'rev' );
593 }
594
595 return $values;
596 }
597
598 /**
599 * Get the list of titles with negative namespace
600 * @return array Title
601 */
602 public function getSpecialTitles() {
603 return $this->mSpecialTitles;
604 }
605
606 /**
607 * Returns the number of revisions (requested with revids= parameter).
608 * @return int Number of revisions.
609 */
610 public function getRevisionCount() {
611 return count( $this->getRevisionIDs() );
612 }
613
614 /**
615 * Populate this PageSet from a list of Titles
616 * @param array $titles of Title objects
617 */
618 public function populateFromTitles( $titles ) {
619 $this->profileIn();
620 $this->initFromTitles( $titles );
621 $this->profileOut();
622 }
623
624 /**
625 * Populate this PageSet from a list of page IDs
626 * @param array $pageIDs of page IDs
627 */
628 public function populateFromPageIDs( $pageIDs ) {
629 $this->profileIn();
630 $this->initFromPageIds( $pageIDs );
631 $this->profileOut();
632 }
633
634 /**
635 * Populate this PageSet from a rowset returned from the database
636 * @param $db DatabaseBase object
637 * @param $queryResult ResultWrapper Query result object
638 */
639 public function populateFromQueryResult( $db, $queryResult ) {
640 $this->profileIn();
641 $this->initFromQueryResult( $queryResult );
642 $this->profileOut();
643 }
644
645 /**
646 * Populate this PageSet from a list of revision IDs
647 * @param array $revIDs of revision IDs
648 */
649 public function populateFromRevisionIDs( $revIDs ) {
650 $this->profileIn();
651 $this->initFromRevIDs( $revIDs );
652 $this->profileOut();
653 }
654
655 /**
656 * Extract all requested fields from the row received from the database
657 * @param stdClass $row Result row
658 */
659 public function processDbRow( $row ) {
660 // Store Title object in various data structures
661 $title = Title::newFromRow( $row );
662
663 $pageId = intval( $row->page_id );
664 $this->mAllPages[$row->page_namespace][$row->page_title] = $pageId;
665 $this->mTitles[] = $title;
666
667 if ( $this->mResolveRedirects && $row->page_is_redirect == '1' ) {
668 $this->mPendingRedirectIDs[$pageId] = $title;
669 } else {
670 $this->mGoodTitles[$pageId] = $title;
671 }
672
673 foreach ( $this->mRequestedPageFields as $fieldName => &$fieldValues ) {
674 $fieldValues[$pageId] = $row->$fieldName;
675 }
676 }
677
678 /**
679 * Do not use, does nothing, will be removed
680 * @deprecated since 1.21
681 */
682 public function finishPageSetGeneration() {
683 wfDeprecated( __METHOD__, '1.21' );
684 }
685
686 /**
687 * This method populates internal variables with page information
688 * based on the given array of title strings.
689 *
690 * Steps:
691 * #1 For each title, get data from `page` table
692 * #2 If page was not found in the DB, store it as missing
693 *
694 * Additionally, when resolving redirects:
695 * #3 If no more redirects left, stop.
696 * #4 For each redirect, get its target from the `redirect` table.
697 * #5 Substitute the original LinkBatch object with the new list
698 * #6 Repeat from step #1
699 *
700 * @param array $titles of Title objects or strings
701 */
702 private function initFromTitles( $titles ) {
703 // Get validated and normalized title objects
704 $linkBatch = $this->processTitlesArray( $titles );
705 if ( $linkBatch->isEmpty() ) {
706 return;
707 }
708
709 $db = $this->getDB();
710 $set = $linkBatch->constructSet( 'page', $db );
711
712 // Get pageIDs data from the `page` table
713 $this->profileDBIn();
714 $res = $db->select( 'page', $this->getPageTableFields(), $set,
715 __METHOD__ );
716 $this->profileDBOut();
717
718 // Hack: get the ns:titles stored in array(ns => array(titles)) format
719 $this->initFromQueryResult( $res, $linkBatch->data, true ); // process Titles
720
721 // Resolve any found redirects
722 $this->resolvePendingRedirects();
723 }
724
725 /**
726 * Does the same as initFromTitles(), but is based on page IDs instead
727 * @param array $pageids of page IDs
728 */
729 private function initFromPageIds( $pageids ) {
730 if ( !$pageids ) {
731 return;
732 }
733
734 $pageids = array_map( 'intval', $pageids ); // paranoia
735 $remaining = array_flip( $pageids );
736
737 $pageids = self::getPositiveIntegers( $pageids );
738
739 $res = null;
740 if ( !empty( $pageids ) ) {
741 $set = array(
742 'page_id' => $pageids
743 );
744 $db = $this->getDB();
745
746 // Get pageIDs data from the `page` table
747 $this->profileDBIn();
748 $res = $db->select( 'page', $this->getPageTableFields(), $set,
749 __METHOD__ );
750 $this->profileDBOut();
751 }
752
753 $this->initFromQueryResult( $res, $remaining, false ); // process PageIDs
754
755 // Resolve any found redirects
756 $this->resolvePendingRedirects();
757 }
758
759 /**
760 * Iterate through the result of the query on 'page' table,
761 * and for each row create and store title object and save any extra fields requested.
762 * @param $res ResultWrapper DB Query result
763 * @param array $remaining of either pageID or ns/title elements (optional).
764 * If given, any missing items will go to $mMissingPageIDs and $mMissingTitles
765 * @param bool $processTitles Must be provided together with $remaining.
766 * If true, treat $remaining as an array of [ns][title]
767 * If false, treat it as an array of [pageIDs]
768 */
769 private function initFromQueryResult( $res, &$remaining = null, $processTitles = null ) {
770 if ( !is_null( $remaining ) && is_null( $processTitles ) ) {
771 ApiBase::dieDebug( __METHOD__, 'Missing $processTitles parameter when $remaining is provided' );
772 }
773
774 $usernames = array();
775 if ( $res ) {
776 foreach ( $res as $row ) {
777 $pageId = intval( $row->page_id );
778
779 // Remove found page from the list of remaining items
780 if ( isset( $remaining ) ) {
781 if ( $processTitles ) {
782 unset( $remaining[$row->page_namespace][$row->page_title] );
783 } else {
784 unset( $remaining[$pageId] );
785 }
786 }
787
788 // Store any extra fields requested by modules
789 $this->processDbRow( $row );
790
791 // Need gender information
792 if ( MWNamespace::hasGenderDistinction( $row->page_namespace ) ) {
793 $usernames[] = $row->page_title;
794 }
795 }
796 }
797
798 if ( isset( $remaining ) ) {
799 // Any items left in the $remaining list are added as missing
800 if ( $processTitles ) {
801 // The remaining titles in $remaining are non-existent pages
802 foreach ( $remaining as $ns => $dbkeys ) {
803 foreach ( array_keys( $dbkeys ) as $dbkey ) {
804 $title = Title::makeTitle( $ns, $dbkey );
805 $this->mAllPages[$ns][$dbkey] = $this->mFakePageId;
806 $this->mMissingTitles[$this->mFakePageId] = $title;
807 $this->mFakePageId--;
808 $this->mTitles[] = $title;
809
810 // need gender information
811 if ( MWNamespace::hasGenderDistinction( $ns ) ) {
812 $usernames[] = $dbkey;
813 }
814 }
815 }
816 } else {
817 // The remaining pageids do not exist
818 if ( !$this->mMissingPageIDs ) {
819 $this->mMissingPageIDs = array_keys( $remaining );
820 } else {
821 $this->mMissingPageIDs = array_merge( $this->mMissingPageIDs, array_keys( $remaining ) );
822 }
823 }
824 }
825
826 // Get gender information
827 $genderCache = GenderCache::singleton();
828 $genderCache->doQuery( $usernames, __METHOD__ );
829 }
830
831 /**
832 * Does the same as initFromTitles(), but is based on revision IDs
833 * instead
834 * @param array $revids of revision IDs
835 */
836 private function initFromRevIDs( $revids ) {
837 if ( !$revids ) {
838 return;
839 }
840
841 $revids = array_map( 'intval', $revids ); // paranoia
842 $db = $this->getDB();
843 $pageids = array();
844 $remaining = array_flip( $revids );
845
846 $revids = self::getPositiveIntegers( $revids );
847
848 if ( !empty( $revids ) ) {
849 $tables = array( 'revision', 'page' );
850 $fields = array( 'rev_id', 'rev_page' );
851 $where = array( 'rev_id' => $revids, 'rev_page = page_id' );
852
853 // Get pageIDs data from the `page` table
854 $this->profileDBIn();
855 $res = $db->select( $tables, $fields, $where, __METHOD__ );
856 foreach ( $res as $row ) {
857 $revid = intval( $row->rev_id );
858 $pageid = intval( $row->rev_page );
859 $this->mGoodRevIDs[$revid] = $pageid;
860 $pageids[$pageid] = '';
861 unset( $remaining[$revid] );
862 }
863 $this->profileDBOut();
864 }
865
866 $this->mMissingRevIDs = array_keys( $remaining );
867
868 // Populate all the page information
869 $this->initFromPageIds( array_keys( $pageids ) );
870 }
871
872 /**
873 * Resolve any redirects in the result if redirect resolution was
874 * requested. This function is called repeatedly until all redirects
875 * have been resolved.
876 */
877 private function resolvePendingRedirects() {
878 if ( $this->mResolveRedirects ) {
879 $db = $this->getDB();
880 $pageFlds = $this->getPageTableFields();
881
882 // Repeat until all redirects have been resolved
883 // The infinite loop is prevented by keeping all known pages in $this->mAllPages
884 while ( $this->mPendingRedirectIDs ) {
885 // Resolve redirects by querying the pagelinks table, and repeat the process
886 // Create a new linkBatch object for the next pass
887 $linkBatch = $this->getRedirectTargets();
888
889 if ( $linkBatch->isEmpty() ) {
890 break;
891 }
892
893 $set = $linkBatch->constructSet( 'page', $db );
894 if ( $set === false ) {
895 break;
896 }
897
898 // Get pageIDs data from the `page` table
899 $this->profileDBIn();
900 $res = $db->select( 'page', $pageFlds, $set, __METHOD__ );
901 $this->profileDBOut();
902
903 // Hack: get the ns:titles stored in array(ns => array(titles)) format
904 $this->initFromQueryResult( $res, $linkBatch->data, true );
905 }
906 }
907 }
908
909 /**
910 * Get the targets of the pending redirects from the database
911 *
912 * Also creates entries in the redirect table for redirects that don't
913 * have one.
914 * @return LinkBatch
915 */
916 private function getRedirectTargets() {
917 $lb = new LinkBatch();
918 $db = $this->getDB();
919
920 $this->profileDBIn();
921 $res = $db->select(
922 'redirect',
923 array(
924 'rd_from',
925 'rd_namespace',
926 'rd_fragment',
927 'rd_interwiki',
928 'rd_title'
929 ), array( 'rd_from' => array_keys( $this->mPendingRedirectIDs ) ),
930 __METHOD__
931 );
932 $this->profileDBOut();
933 foreach ( $res as $row ) {
934 $rdfrom = intval( $row->rd_from );
935 $from = $this->mPendingRedirectIDs[$rdfrom]->getPrefixedText();
936 $to = Title::makeTitle(
937 $row->rd_namespace,
938 $row->rd_title,
939 $row->rd_fragment,
940 $row->rd_interwiki
941 );
942 unset( $this->mPendingRedirectIDs[$rdfrom] );
943 if ( !$to->isExternal() && !isset( $this->mAllPages[$row->rd_namespace][$row->rd_title] ) ) {
944 $lb->add( $row->rd_namespace, $row->rd_title );
945 }
946 $this->mRedirectTitles[$from] = $to;
947 }
948
949 if ( $this->mPendingRedirectIDs ) {
950 // We found pages that aren't in the redirect table
951 // Add them
952 foreach ( $this->mPendingRedirectIDs as $id => $title ) {
953 $page = WikiPage::factory( $title );
954 $rt = $page->insertRedirect();
955 if ( !$rt ) {
956 // What the hell. Let's just ignore this
957 continue;
958 }
959 $lb->addObj( $rt );
960 $this->mRedirectTitles[$title->getPrefixedText()] = $rt;
961 unset( $this->mPendingRedirectIDs[$id] );
962 }
963 }
964
965 return $lb;
966 }
967
968 /**
969 * Get the cache mode for the data generated by this module.
970 * All PageSet users should take into account whether this returns a more-restrictive
971 * cache mode than the using module itself. For possible return values and other
972 * details about cache modes, see ApiMain::setCacheMode()
973 *
974 * Public caching will only be allowed if *all* the modules that supply
975 * data for a given request return a cache mode of public.
976 *
977 * @param $params
978 * @return string
979 * @since 1.21
980 */
981 public function getCacheMode( $params = null ) {
982 return $this->mCacheMode;
983 }
984
985 /**
986 * Given an array of title strings, convert them into Title objects.
987 * Alternatively, an array of Title objects may be given.
988 * This method validates access rights for the title,
989 * and appends normalization values to the output.
990 *
991 * @param array $titles of Title objects or strings
992 * @return LinkBatch
993 */
994 private function processTitlesArray( $titles ) {
995 $usernames = array();
996 $linkBatch = new LinkBatch();
997
998 foreach ( $titles as $title ) {
999 if ( is_string( $title ) ) {
1000 $titleObj = Title::newFromText( $title, $this->mDefaultNamespace );
1001 } else {
1002 $titleObj = $title;
1003 }
1004 if ( !$titleObj ) {
1005 // Handle invalid titles gracefully
1006 $this->mAllPages[0][$title] = $this->mFakePageId;
1007 $this->mInvalidTitles[$this->mFakePageId] = $title;
1008 $this->mFakePageId--;
1009 continue; // There's nothing else we can do
1010 }
1011 $unconvertedTitle = $titleObj->getPrefixedText();
1012 $titleWasConverted = false;
1013 if ( $titleObj->isExternal() ) {
1014 // This title is an interwiki link.
1015 $this->mInterwikiTitles[$unconvertedTitle] = $titleObj->getInterwiki();
1016 } else {
1017 // Variants checking
1018 global $wgContLang;
1019 if ( $this->mConvertTitles &&
1020 count( $wgContLang->getVariants() ) > 1 &&
1021 !$titleObj->exists()
1022 ) {
1023 // Language::findVariantLink will modify titleText and titleObj into
1024 // the canonical variant if possible
1025 $titleText = is_string( $title ) ? $title : $titleObj->getPrefixedText();
1026 $wgContLang->findVariantLink( $titleText, $titleObj );
1027 $titleWasConverted = $unconvertedTitle !== $titleObj->getPrefixedText();
1028 }
1029
1030 if ( $titleObj->getNamespace() < 0 ) {
1031 // Handle Special and Media pages
1032 $titleObj = $titleObj->fixSpecialName();
1033 $this->mSpecialTitles[$this->mFakePageId] = $titleObj;
1034 $this->mFakePageId--;
1035 } else {
1036 // Regular page
1037 $linkBatch->addObj( $titleObj );
1038 }
1039 }
1040
1041 // Make sure we remember the original title that was
1042 // given to us. This way the caller can correlate new
1043 // titles with the originally requested when e.g. the
1044 // namespace is localized or the capitalization is
1045 // different
1046 if ( $titleWasConverted ) {
1047 $this->mConvertedTitles[$unconvertedTitle] = $titleObj->getPrefixedText();
1048 // In this case the page can't be Special.
1049 if ( is_string( $title ) && $title !== $unconvertedTitle ) {
1050 $this->mNormalizedTitles[$title] = $unconvertedTitle;
1051 }
1052 } elseif ( is_string( $title ) && $title !== $titleObj->getPrefixedText() ) {
1053 $this->mNormalizedTitles[$title] = $titleObj->getPrefixedText();
1054 }
1055
1056 // Need gender information
1057 if ( MWNamespace::hasGenderDistinction( $titleObj->getNamespace() ) ) {
1058 $usernames[] = $titleObj->getText();
1059 }
1060 }
1061 // Get gender information
1062 $genderCache = GenderCache::singleton();
1063 $genderCache->doQuery( $usernames, __METHOD__ );
1064
1065 return $linkBatch;
1066 }
1067
1068 /**
1069 * Get the database connection (read-only)
1070 * @return DatabaseBase
1071 */
1072 protected function getDB() {
1073 return $this->mDbSource->getDB();
1074 }
1075
1076 /**
1077 * Returns the input array of integers with all values < 0 removed
1078 *
1079 * @param $array array
1080 * @return array
1081 */
1082 private static function getPositiveIntegers( $array ) {
1083 // bug 25734 API: possible issue with revids validation
1084 // It seems with a load of revision rows, MySQL gets upset
1085 // Remove any < 0 integers, as they can't be valid
1086 foreach ( $array as $i => $int ) {
1087 if ( $int < 0 ) {
1088 unset( $array[$i] );
1089 }
1090 }
1091
1092 return $array;
1093 }
1094
1095 public function getAllowedParams( $flags = 0 ) {
1096 $result = array(
1097 'titles' => array(
1098 ApiBase::PARAM_ISMULTI => true
1099 ),
1100 'pageids' => array(
1101 ApiBase::PARAM_TYPE => 'integer',
1102 ApiBase::PARAM_ISMULTI => true
1103 ),
1104 'revids' => array(
1105 ApiBase::PARAM_TYPE => 'integer',
1106 ApiBase::PARAM_ISMULTI => true
1107 ),
1108 'redirects' => false,
1109 'converttitles' => false,
1110 );
1111 if ( $this->mAllowGenerator ) {
1112 if ( $flags & ApiBase::GET_VALUES_FOR_HELP ) {
1113 $result['generator'] = array(
1114 ApiBase::PARAM_TYPE => $this->getGenerators()
1115 );
1116 } else {
1117 $result['generator'] = null;
1118 }
1119 }
1120
1121 return $result;
1122 }
1123
1124 private static $generators = null;
1125
1126 /**
1127 * Get an array of all available generators
1128 * @return array
1129 */
1130 private function getGenerators() {
1131 if ( self::$generators === null ) {
1132 $query = $this->mDbSource;
1133 if ( !( $query instanceof ApiQuery ) ) {
1134 // If the parent container of this pageset is not ApiQuery,
1135 // we must create it to get module manager
1136 $query = $this->getMain()->getModuleManager()->getModule( 'query' );
1137 }
1138 $gens = array();
1139 $mgr = $query->getModuleManager();
1140 foreach ( $mgr->getNamesWithClasses() as $name => $class ) {
1141 if ( is_subclass_of( $class, 'ApiQueryGeneratorBase' ) ) {
1142 $gens[] = $name;
1143 }
1144 }
1145 sort( $gens );
1146 self::$generators = $gens;
1147 }
1148
1149 return self::$generators;
1150 }
1151
1152 public function getParamDescription() {
1153 return array(
1154 'titles' => 'A list of titles to work on',
1155 'pageids' => 'A list of page IDs to work on',
1156 'revids' => 'A list of revision IDs to work on',
1157 'generator' => array(
1158 'Get the list of pages to work on by executing the specified query module.',
1159 'NOTE: generator parameter names must be prefixed with a \'g\', see examples'
1160 ),
1161 'redirects' => 'Automatically resolve redirects',
1162 'converttitles' => array(
1163 'Convert titles to other variants if necessary. Only works if ' .
1164 'the wiki\'s content language supports variant conversion.',
1165 'Languages that support variant conversion include ' .
1166 implode( ', ', LanguageConverter::$languagesWithVariants )
1167 ),
1168 );
1169 }
1170
1171 public function getPossibleErrors() {
1172 return array_merge( parent::getPossibleErrors(), array(
1173 array(
1174 'code' => 'multisource',
1175 'info' => "Cannot use 'pageids' at the same time as 'dataSource'"
1176 ),
1177 array(
1178 'code' => 'multisource',
1179 'info' => "Cannot use 'revids' at the same time as 'dataSource'"
1180 ),
1181 array(
1182 'code' => 'badgenerator',
1183 'info' => 'Module $generatorName cannot be used as a generator'
1184 ),
1185 ) );
1186 }
1187 }