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