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