5 * Created on Sep 24, 2006
7 * Copyright © 2006, 2013 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
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.
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.
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
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
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.
39 * @since 1.21 derives from ApiBase instead of ApiQueryBase
41 class ApiPageSet
extends ApiBase
{
43 * Constructor flag: The new instance of ApiPageSet will ignore the 'generator=' parameter
46 const DISABLE_GENERATORS
= 1;
50 private $mResolveRedirects;
51 private $mConvertTitles;
52 private $mAllowGenerator;
54 private $mAllPages = array(); // [ns][dbkey] => page_id or negative when missing
55 private $mTitles = array();
56 private $mGoodAndMissingPages = array(); // [ns][dbkey] => page_id or negative when missing
57 private $mGoodPages = array(); // [ns][dbkey] => page_id
58 private $mGoodTitles = array();
59 private $mMissingPages = array(); // [ns][dbkey] => fake page_id
60 private $mMissingTitles = array();
61 /** @var array [fake_page_id] => array( 'title' => $title, 'invalidreason' => $reason ) */
62 private $mInvalidTitles = array();
63 private $mMissingPageIDs = array();
64 private $mRedirectTitles = array();
65 private $mSpecialTitles = array();
66 private $mNormalizedTitles = array();
67 private $mInterwikiTitles = array();
69 private $mPendingRedirectIDs = array();
70 private $mResolvedRedirectTitles = array();
71 private $mConvertedTitles = array();
72 private $mGoodRevIDs = array();
73 private $mLiveRevIDs = array();
74 private $mDeletedRevIDs = array();
75 private $mMissingRevIDs = array();
76 private $mGeneratorData = array(); // [ns][dbkey] => data array
77 private $mFakePageId = -1;
78 private $mCacheMode = 'public';
79 private $mRequestedPageFields = array();
81 private $mDefaultNamespace = NS_MAIN
;
84 * Add all items from $values into the result
85 * @param array $result Output
86 * @param array $values Values to add
87 * @param string $flag The name of the boolean flag to mark this element
88 * @param string $name If given, name of the value
90 private static function addValues( array &$result, $values, $flag = null, $name = null ) {
91 foreach ( $values as $val ) {
92 if ( $val instanceof Title
) {
94 ApiQueryBase
::addTitleInfo( $v, $val );
95 } elseif ( $name !== null ) {
96 $v = array( $name => $val );
100 if ( $flag !== null ) {
108 * @param ApiBase $dbSource Module implementing getDB().
109 * Allows PageSet to reuse existing db connection from the shared state like ApiQuery.
110 * @param int $flags Zero or more flags like DISABLE_GENERATORS
111 * @param int $defaultNamespace The namespace to use if none is specified by a prefix.
112 * @since 1.21 accepts $flags instead of two boolean values
114 public function __construct( ApiBase
$dbSource, $flags = 0, $defaultNamespace = NS_MAIN
) {
115 parent
::__construct( $dbSource->getMain(), $dbSource->getModuleName() );
116 $this->mDbSource
= $dbSource;
117 $this->mAllowGenerator
= ( $flags & ApiPageSet
::DISABLE_GENERATORS
) == 0;
118 $this->mDefaultNamespace
= $defaultNamespace;
120 $this->mParams
= $this->extractRequestParams();
121 $this->mResolveRedirects
= $this->mParams
['redirects'];
122 $this->mConvertTitles
= $this->mParams
['converttitles'];
126 * In case execute() is not called, call this method to mark all relevant parameters as used
127 * This prevents unused parameters from being reported as warnings
129 public function executeDryRun() {
130 $this->executeInternal( true );
134 * Populate the PageSet from the request parameters.
136 public function execute() {
137 $this->executeInternal( false );
141 * Populate the PageSet from the request parameters.
142 * @param bool $isDryRun If true, instantiates generator, but only to mark
143 * relevant parameters as used
145 private function executeInternal( $isDryRun ) {
146 $generatorName = $this->mAllowGenerator ?
$this->mParams
['generator'] : null;
147 if ( isset( $generatorName ) ) {
148 $dbSource = $this->mDbSource
;
149 if ( !$dbSource instanceof ApiQuery
) {
150 // If the parent container of this pageset is not ApiQuery, we must create it to run generator
151 $dbSource = $this->getMain()->getModuleManager()->getModule( 'query' );
153 $generator = $dbSource->getModuleManager()->getModule( $generatorName, null, true );
154 if ( $generator === null ) {
155 $this->dieUsage( 'Unknown generator=' . $generatorName, 'badgenerator' );
157 if ( !$generator instanceof ApiQueryGeneratorBase
) {
158 $this->dieUsage( "Module $generatorName cannot be used as a generator", 'badgenerator' );
160 // Create a temporary pageset to store generator's output,
161 // add any additional fields generator may need, and execute pageset to populate titles/pageids
162 $tmpPageSet = new ApiPageSet( $dbSource, ApiPageSet
::DISABLE_GENERATORS
);
163 $generator->setGeneratorMode( $tmpPageSet );
164 $this->mCacheMode
= $generator->getCacheMode( $generator->extractRequestParams() );
167 $generator->requestExtraData( $tmpPageSet );
169 $tmpPageSet->executeInternal( $isDryRun );
171 // populate this pageset with the generator output
173 $generator->executeGenerator( $this );
174 Hooks
::run( 'APIQueryGeneratorAfterExecute', array( &$generator, &$this ) );
176 // Prevent warnings from being reported on these parameters
177 $main = $this->getMain();
178 foreach ( $generator->extractRequestParams() as $paramName => $param ) {
179 $main->getVal( $generator->encodeParamName( $paramName ) );
184 $this->resolvePendingRedirects();
187 // Only one of the titles/pageids/revids is allowed at the same time
189 if ( isset( $this->mParams
['titles'] ) ) {
190 $dataSource = 'titles';
192 if ( isset( $this->mParams
['pageids'] ) ) {
193 if ( isset( $dataSource ) ) {
194 $this->dieUsage( "Cannot use 'pageids' at the same time as '$dataSource'", 'multisource' );
196 $dataSource = 'pageids';
198 if ( isset( $this->mParams
['revids'] ) ) {
199 if ( isset( $dataSource ) ) {
200 $this->dieUsage( "Cannot use 'revids' at the same time as '$dataSource'", 'multisource' );
202 $dataSource = 'revids';
206 // Populate page information with the original user input
207 switch ( $dataSource ) {
209 $this->initFromTitles( $this->mParams
['titles'] );
212 $this->initFromPageIds( $this->mParams
['pageids'] );
215 if ( $this->mResolveRedirects
) {
216 $this->setWarning( 'Redirect resolution cannot be used ' .
217 'together with the revids= parameter. Any redirects ' .
218 'the revids= point to have not been resolved.' );
220 $this->mResolveRedirects
= false;
221 $this->initFromRevIDs( $this->mParams
['revids'] );
224 // Do nothing - some queries do not need any of the data sources.
232 * Check whether this PageSet is resolving redirects
235 public function isResolvingRedirects() {
236 return $this->mResolveRedirects
;
240 * Return the parameter name that is the source of data for this PageSet
242 * If multiple source parameters are specified (e.g. titles and pageids),
243 * one will be named arbitrarily.
245 * @return string|null
247 public function getDataSource() {
248 if ( $this->mAllowGenerator
&& isset( $this->mParams
['generator'] ) ) {
251 if ( isset( $this->mParams
['titles'] ) ) {
254 if ( isset( $this->mParams
['pageids'] ) ) {
257 if ( isset( $this->mParams
['revids'] ) ) {
265 * Request an additional field from the page table.
266 * Must be called before execute()
267 * @param string $fieldName Field name
269 public function requestField( $fieldName ) {
270 $this->mRequestedPageFields
[$fieldName] = null;
274 * Get the value of a custom field previously requested through
276 * @param string $fieldName Field name
277 * @return mixed Field value
279 public function getCustomField( $fieldName ) {
280 return $this->mRequestedPageFields
[$fieldName];
284 * Get the fields that have to be queried from the page table:
285 * the ones requested through requestField() and a few basic ones
287 * @return array Array of field names
289 public function getPageTableFields() {
290 // Ensure we get minimum required fields
291 // DON'T change this order
293 'page_namespace' => null,
294 'page_title' => null,
298 if ( $this->mResolveRedirects
) {
299 $pageFlds['page_is_redirect'] = null;
302 if ( $this->getConfig()->get( 'ContentHandlerUseDB' ) ) {
303 $pageFlds['page_content_model'] = null;
306 // only store non-default fields
307 $this->mRequestedPageFields
= array_diff_key( $this->mRequestedPageFields
, $pageFlds );
309 $pageFlds = array_merge( $pageFlds, $this->mRequestedPageFields
);
311 return array_keys( $pageFlds );
315 * Returns an array [ns][dbkey] => page_id for all requested titles.
316 * page_id is a unique negative number in case title was not found.
317 * Invalid titles will also have negative page IDs and will be in namespace 0
320 public function getAllTitlesByNamespace() {
321 return $this->mAllPages
;
325 * All Title objects provided.
328 public function getTitles() {
329 return $this->mTitles
;
333 * Returns the number of unique pages (not revisions) in the set.
336 public function getTitleCount() {
337 return count( $this->mTitles
);
341 * Returns an array [ns][dbkey] => page_id for all good titles.
344 public function getGoodTitlesByNamespace() {
345 return $this->mGoodPages
;
349 * Title objects that were found in the database.
350 * @return Title[] Array page_id (int) => Title (obj)
352 public function getGoodTitles() {
353 return $this->mGoodTitles
;
357 * Returns the number of found unique pages (not revisions) in the set.
360 public function getGoodTitleCount() {
361 return count( $this->mGoodTitles
);
365 * Returns an array [ns][dbkey] => fake_page_id for all missing titles.
366 * fake_page_id is a unique negative number.
369 public function getMissingTitlesByNamespace() {
370 return $this->mMissingPages
;
374 * Title objects that were NOT found in the database.
375 * The array's index will be negative for each item
378 public function getMissingTitles() {
379 return $this->mMissingTitles
;
383 * Returns an array [ns][dbkey] => page_id for all good and missing titles.
386 public function getGoodAndMissingTitlesByNamespace() {
387 return $this->mGoodAndMissingPages
;
391 * Title objects for good and missing titles.
394 public function getGoodAndMissingTitles() {
395 return $this->mGoodTitles +
$this->mMissingTitles
;
399 * Titles that were deemed invalid by Title::newFromText()
400 * The array's index will be unique and negative for each item
401 * @deprecated since 1.26, use self::getInvalidTitlesAndReasons()
402 * @return string[] Array of strings (not Title objects)
404 public function getInvalidTitles() {
405 wfDeprecated( __METHOD__
, '1.26' );
406 return array_map( function ( $t ) {
408 }, $this->mInvalidTitles
);
412 * Titles that were deemed invalid by Title::newFromText()
413 * The array's index will be unique and negative for each item
414 * @return array[] Array of arrays with 'title' and 'invalidreason' properties
416 public function getInvalidTitlesAndReasons() {
417 return $this->mInvalidTitles
;
421 * Page IDs that were not found in the database
422 * @return array Array of page IDs
424 public function getMissingPageIDs() {
425 return $this->mMissingPageIDs
;
429 * Get a list of redirect resolutions - maps a title to its redirect
430 * target, as an array of output-ready arrays
433 public function getRedirectTitles() {
434 return $this->mRedirectTitles
;
438 * Get a list of redirect resolutions - maps a title to its redirect
439 * target. Includes generator data for redirect source when available.
440 * @param ApiResult $result
441 * @return array Array of prefixed_title (string) => Title object
444 public function getRedirectTitlesAsResult( $result = null ) {
446 foreach ( $this->getRedirectTitles() as $titleStrFrom => $titleTo ) {
448 'from' => strval( $titleStrFrom ),
449 'to' => $titleTo->getPrefixedText(),
451 if ( $titleTo->hasFragment() ) {
452 $r['tofragment'] = $titleTo->getFragment();
454 if ( $titleTo->isExternal() ) {
455 $r['tointerwiki'] = $titleTo->getInterwiki();
457 if ( isset( $this->mResolvedRedirectTitles
[$titleStrFrom] ) ) {
458 $titleFrom = $this->mResolvedRedirectTitles
[$titleStrFrom];
459 $ns = $titleFrom->getNamespace();
460 $dbkey = $titleFrom->getDBkey();
461 if ( isset( $this->mGeneratorData
[$ns][$dbkey] ) ) {
462 $r = array_merge( $this->mGeneratorData
[$ns][$dbkey], $r );
468 if ( !empty( $values ) && $result ) {
469 ApiResult
::setIndexedTagName( $values, 'r' );
476 * Get a list of title normalizations - maps a title to its normalized
478 * @return array Array of raw_prefixed_title (string) => prefixed_title (string)
480 public function getNormalizedTitles() {
481 return $this->mNormalizedTitles
;
485 * Get a list of title normalizations - maps a title to its normalized
486 * version in the form of result array.
487 * @param ApiResult $result
488 * @return array Array of raw_prefixed_title (string) => prefixed_title (string)
491 public function getNormalizedTitlesAsResult( $result = null ) {
493 foreach ( $this->getNormalizedTitles() as $rawTitleStr => $titleStr ) {
495 'from' => $rawTitleStr,
499 if ( !empty( $values ) && $result ) {
500 ApiResult
::setIndexedTagName( $values, 'n' );
507 * Get a list of title conversions - maps a title to its converted
509 * @return array Array of raw_prefixed_title (string) => prefixed_title (string)
511 public function getConvertedTitles() {
512 return $this->mConvertedTitles
;
516 * Get a list of title conversions - maps a title to its converted
517 * version as a result array.
518 * @param ApiResult $result
519 * @return array Array of (from, to) strings
522 public function getConvertedTitlesAsResult( $result = null ) {
524 foreach ( $this->getConvertedTitles() as $rawTitleStr => $titleStr ) {
526 'from' => $rawTitleStr,
530 if ( !empty( $values ) && $result ) {
531 ApiResult
::setIndexedTagName( $values, 'c' );
538 * Get a list of interwiki titles - maps a title to its interwiki
540 * @return array Array of raw_prefixed_title (string) => interwiki_prefix (string)
542 public function getInterwikiTitles() {
543 return $this->mInterwikiTitles
;
547 * Get a list of interwiki titles - maps a title to its interwiki
549 * @param ApiResult $result
551 * @return array Array of raw_prefixed_title (string) => interwiki_prefix (string)
554 public function getInterwikiTitlesAsResult( $result = null, $iwUrl = false ) {
556 foreach ( $this->getInterwikiTitles() as $rawTitleStr => $interwikiStr ) {
558 'title' => $rawTitleStr,
559 'iw' => $interwikiStr,
562 $title = Title
::newFromText( $rawTitleStr );
563 $item['url'] = $title->getFullURL( '', false, PROTO_CURRENT
);
567 if ( !empty( $values ) && $result ) {
568 ApiResult
::setIndexedTagName( $values, 'i' );
575 * Get an array of invalid/special/missing titles.
577 * @param array $invalidChecks List of types of invalid titles to include.
578 * Recognized values are:
579 * - invalidTitles: Titles and reasons from $this->getInvalidTitlesAndReasons()
580 * - special: Titles from $this->getSpecialTitles()
581 * - missingIds: ids from $this->getMissingPageIDs()
582 * - missingRevIds: ids from $this->getMissingRevisionIDs()
583 * - missingTitles: Titles from $this->getMissingTitles()
584 * - interwikiTitles: Titles from $this->getInterwikiTitlesAsResult()
585 * @return array Array suitable for inclusion in the response
588 public function getInvalidTitlesAndRevisions( $invalidChecks = array( 'invalidTitles',
589 'special', 'missingIds', 'missingRevIds', 'missingTitles', 'interwikiTitles' )
592 if ( in_array( "invalidTitles", $invalidChecks ) ) {
593 self
::addValues( $result, $this->getInvalidTitlesAndReasons(), 'invalid' );
595 if ( in_array( "special", $invalidChecks ) ) {
596 self
::addValues( $result, $this->getSpecialTitles(), 'special', 'title' );
598 if ( in_array( "missingIds", $invalidChecks ) ) {
599 self
::addValues( $result, $this->getMissingPageIDs(), 'missing', 'pageid' );
601 if ( in_array( "missingRevIds", $invalidChecks ) ) {
602 self
::addValues( $result, $this->getMissingRevisionIDs(), 'missing', 'revid' );
604 if ( in_array( "missingTitles", $invalidChecks ) ) {
605 self
::addValues( $result, $this->getMissingTitles(), 'missing' );
607 if ( in_array( "interwikiTitles", $invalidChecks ) ) {
608 self
::addValues( $result, $this->getInterwikiTitlesAsResult() );
615 * Get the list of valid revision IDs (requested with the revids= parameter)
616 * @return array Array of revID (int) => pageID (int)
618 public function getRevisionIDs() {
619 return $this->mGoodRevIDs
;
623 * Get the list of non-deleted revision IDs (requested with the revids= parameter)
624 * @return array Array of revID (int) => pageID (int)
626 public function getLiveRevisionIDs() {
627 return $this->mLiveRevIDs
;
631 * Get the list of revision IDs that were associated with deleted titles.
632 * @return array Array of revID (int) => pageID (int)
634 public function getDeletedRevisionIDs() {
635 return $this->mDeletedRevIDs
;
639 * Revision IDs that were not found in the database
640 * @return array Array of revision IDs
642 public function getMissingRevisionIDs() {
643 return $this->mMissingRevIDs
;
647 * Revision IDs that were not found in the database as result array.
648 * @param ApiResult $result
649 * @return array Array of revision IDs
652 public function getMissingRevisionIDsAsResult( $result = null ) {
654 foreach ( $this->getMissingRevisionIDs() as $revid ) {
655 $values[$revid] = array(
659 if ( !empty( $values ) && $result ) {
660 ApiResult
::setIndexedTagName( $values, 'rev' );
667 * Get the list of titles with negative namespace
670 public function getSpecialTitles() {
671 return $this->mSpecialTitles
;
675 * Returns the number of revisions (requested with revids= parameter).
676 * @return int Number of revisions.
678 public function getRevisionCount() {
679 return count( $this->getRevisionIDs() );
683 * Populate this PageSet from a list of Titles
684 * @param array $titles Array of Title objects
686 public function populateFromTitles( $titles ) {
687 $this->initFromTitles( $titles );
691 * Populate this PageSet from a list of page IDs
692 * @param array $pageIDs Array of page IDs
694 public function populateFromPageIDs( $pageIDs ) {
695 $this->initFromPageIds( $pageIDs );
699 * Populate this PageSet from a rowset returned from the database
701 * Note that the query result must include the columns returned by
702 * $this->getPageTableFields().
704 * @param IDatabase $db
705 * @param ResultWrapper $queryResult Query result object
707 public function populateFromQueryResult( $db, $queryResult ) {
708 $this->initFromQueryResult( $queryResult );
712 * Populate this PageSet from a list of revision IDs
713 * @param array $revIDs Array of revision IDs
715 public function populateFromRevisionIDs( $revIDs ) {
716 $this->initFromRevIDs( $revIDs );
720 * Extract all requested fields from the row received from the database
721 * @param stdClass $row Result row
723 public function processDbRow( $row ) {
724 // Store Title object in various data structures
725 $title = Title
::newFromRow( $row );
727 $pageId = intval( $row->page_id
);
728 $this->mAllPages
[$row->page_namespace
][$row->page_title
] = $pageId;
729 $this->mTitles
[] = $title;
731 if ( $this->mResolveRedirects
&& $row->page_is_redirect
== '1' ) {
732 $this->mPendingRedirectIDs
[$pageId] = $title;
734 $this->mGoodPages
[$row->page_namespace
][$row->page_title
] = $pageId;
735 $this->mGoodAndMissingPages
[$row->page_namespace
][$row->page_title
] = $pageId;
736 $this->mGoodTitles
[$pageId] = $title;
739 foreach ( $this->mRequestedPageFields
as $fieldName => &$fieldValues ) {
740 $fieldValues[$pageId] = $row->$fieldName;
745 * Do not use, does nothing, will be removed
746 * @deprecated since 1.21
748 public function finishPageSetGeneration() {
749 wfDeprecated( __METHOD__
, '1.21' );
753 * This method populates internal variables with page information
754 * based on the given array of title strings.
757 * #1 For each title, get data from `page` table
758 * #2 If page was not found in the DB, store it as missing
760 * Additionally, when resolving redirects:
761 * #3 If no more redirects left, stop.
762 * #4 For each redirect, get its target from the `redirect` table.
763 * #5 Substitute the original LinkBatch object with the new list
764 * #6 Repeat from step #1
766 * @param array $titles Array of Title objects or strings
768 private function initFromTitles( $titles ) {
769 // Get validated and normalized title objects
770 $linkBatch = $this->processTitlesArray( $titles );
771 if ( $linkBatch->isEmpty() ) {
775 $db = $this->getDB();
776 $set = $linkBatch->constructSet( 'page', $db );
778 // Get pageIDs data from the `page` table
779 $res = $db->select( 'page', $this->getPageTableFields(), $set,
782 // Hack: get the ns:titles stored in array(ns => array(titles)) format
783 $this->initFromQueryResult( $res, $linkBatch->data
, true ); // process Titles
785 // Resolve any found redirects
786 $this->resolvePendingRedirects();
790 * Does the same as initFromTitles(), but is based on page IDs instead
791 * @param array $pageids Array of page IDs
793 private function initFromPageIds( $pageids ) {
798 $pageids = array_map( 'intval', $pageids ); // paranoia
799 $remaining = array_flip( $pageids );
801 $pageids = self
::getPositiveIntegers( $pageids );
804 if ( !empty( $pageids ) ) {
806 'page_id' => $pageids
808 $db = $this->getDB();
810 // Get pageIDs data from the `page` table
811 $res = $db->select( 'page', $this->getPageTableFields(), $set,
815 $this->initFromQueryResult( $res, $remaining, false ); // process PageIDs
817 // Resolve any found redirects
818 $this->resolvePendingRedirects();
822 * Iterate through the result of the query on 'page' table,
823 * and for each row create and store title object and save any extra fields requested.
824 * @param ResultWrapper $res DB Query result
825 * @param array $remaining Array of either pageID or ns/title elements (optional).
826 * If given, any missing items will go to $mMissingPageIDs and $mMissingTitles
827 * @param bool $processTitles Must be provided together with $remaining.
828 * If true, treat $remaining as an array of [ns][title]
829 * If false, treat it as an array of [pageIDs]
831 private function initFromQueryResult( $res, &$remaining = null, $processTitles = null ) {
832 if ( !is_null( $remaining ) && is_null( $processTitles ) ) {
833 ApiBase
::dieDebug( __METHOD__
, 'Missing $processTitles parameter when $remaining is provided' );
836 $usernames = array();
838 foreach ( $res as $row ) {
839 $pageId = intval( $row->page_id
);
841 // Remove found page from the list of remaining items
842 if ( isset( $remaining ) ) {
843 if ( $processTitles ) {
844 unset( $remaining[$row->page_namespace
][$row->page_title
] );
846 unset( $remaining[$pageId] );
850 // Store any extra fields requested by modules
851 $this->processDbRow( $row );
853 // Need gender information
854 if ( MWNamespace
::hasGenderDistinction( $row->page_namespace
) ) {
855 $usernames[] = $row->page_title
;
860 if ( isset( $remaining ) ) {
861 // Any items left in the $remaining list are added as missing
862 if ( $processTitles ) {
863 // The remaining titles in $remaining are non-existent pages
864 foreach ( $remaining as $ns => $dbkeys ) {
865 foreach ( array_keys( $dbkeys ) as $dbkey ) {
866 $title = Title
::makeTitle( $ns, $dbkey );
867 $this->mAllPages
[$ns][$dbkey] = $this->mFakePageId
;
868 $this->mMissingPages
[$ns][$dbkey] = $this->mFakePageId
;
869 $this->mGoodAndMissingPages
[$ns][$dbkey] = $this->mFakePageId
;
870 $this->mMissingTitles
[$this->mFakePageId
] = $title;
871 $this->mFakePageId
--;
872 $this->mTitles
[] = $title;
874 // need gender information
875 if ( MWNamespace
::hasGenderDistinction( $ns ) ) {
876 $usernames[] = $dbkey;
881 // The remaining pageids do not exist
882 if ( !$this->mMissingPageIDs
) {
883 $this->mMissingPageIDs
= array_keys( $remaining );
885 $this->mMissingPageIDs
= array_merge( $this->mMissingPageIDs
, array_keys( $remaining ) );
890 // Get gender information
891 $genderCache = GenderCache
::singleton();
892 $genderCache->doQuery( $usernames, __METHOD__
);
896 * Does the same as initFromTitles(), but is based on revision IDs
898 * @param array $revids Array of revision IDs
900 private function initFromRevIDs( $revids ) {
905 $revids = array_map( 'intval', $revids ); // paranoia
906 $db = $this->getDB();
908 $remaining = array_flip( $revids );
910 $revids = self
::getPositiveIntegers( $revids );
912 if ( !empty( $revids ) ) {
913 $tables = array( 'revision', 'page' );
914 $fields = array( 'rev_id', 'rev_page' );
915 $where = array( 'rev_id' => $revids, 'rev_page = page_id' );
917 // Get pageIDs data from the `page` table
918 $res = $db->select( $tables, $fields, $where, __METHOD__
);
919 foreach ( $res as $row ) {
920 $revid = intval( $row->rev_id
);
921 $pageid = intval( $row->rev_page
);
922 $this->mGoodRevIDs
[$revid] = $pageid;
923 $this->mLiveRevIDs
[$revid] = $pageid;
924 $pageids[$pageid] = '';
925 unset( $remaining[$revid] );
929 $this->mMissingRevIDs
= array_keys( $remaining );
931 // Populate all the page information
932 $this->initFromPageIds( array_keys( $pageids ) );
934 // If the user can see deleted revisions, pull out the corresponding
935 // titles from the archive table and include them too. We ignore
936 // ar_page_id because deleted revisions are tied by title, not page_id.
937 if ( !empty( $this->mMissingRevIDs
) && $this->getUser()->isAllowed( 'deletedhistory' ) ) {
938 $remaining = array_flip( $this->mMissingRevIDs
);
939 $tables = array( 'archive' );
940 $fields = array( 'ar_rev_id', 'ar_namespace', 'ar_title' );
941 $where = array( 'ar_rev_id' => $this->mMissingRevIDs
);
943 $res = $db->select( $tables, $fields, $where, __METHOD__
);
945 foreach ( $res as $row ) {
946 $revid = intval( $row->ar_rev_id
);
947 $titles[$revid] = Title
::makeTitle( $row->ar_namespace
, $row->ar_title
);
948 unset( $remaining[$revid] );
951 $this->initFromTitles( $titles );
953 foreach ( $titles as $revid => $title ) {
954 $ns = $title->getNamespace();
955 $dbkey = $title->getDBkey();
957 // Handle converted titles
958 if ( !isset( $this->mAllPages
[$ns][$dbkey] ) &&
959 isset( $this->mConvertedTitles
[$title->getPrefixedText()] )
961 $title = Title
::newFromText( $this->mConvertedTitles
[$title->getPrefixedText()] );
962 $ns = $title->getNamespace();
963 $dbkey = $title->getDBkey();
966 if ( isset( $this->mAllPages
[$ns][$dbkey] ) ) {
967 $this->mGoodRevIDs
[$revid] = $this->mAllPages
[$ns][$dbkey];
968 $this->mDeletedRevIDs
[$revid] = $this->mAllPages
[$ns][$dbkey];
970 $remaining[$revid] = true;
974 $this->mMissingRevIDs
= array_keys( $remaining );
979 * Resolve any redirects in the result if redirect resolution was
980 * requested. This function is called repeatedly until all redirects
981 * have been resolved.
983 private function resolvePendingRedirects() {
984 if ( $this->mResolveRedirects
) {
985 $db = $this->getDB();
986 $pageFlds = $this->getPageTableFields();
988 // Repeat until all redirects have been resolved
989 // The infinite loop is prevented by keeping all known pages in $this->mAllPages
990 while ( $this->mPendingRedirectIDs
) {
991 // Resolve redirects by querying the pagelinks table, and repeat the process
992 // Create a new linkBatch object for the next pass
993 $linkBatch = $this->getRedirectTargets();
995 if ( $linkBatch->isEmpty() ) {
999 $set = $linkBatch->constructSet( 'page', $db );
1000 if ( $set === false ) {
1004 // Get pageIDs data from the `page` table
1005 $res = $db->select( 'page', $pageFlds, $set, __METHOD__
);
1007 // Hack: get the ns:titles stored in array(ns => array(titles)) format
1008 $this->initFromQueryResult( $res, $linkBatch->data
, true );
1014 * Get the targets of the pending redirects from the database
1016 * Also creates entries in the redirect table for redirects that don't
1020 private function getRedirectTargets() {
1021 $lb = new LinkBatch();
1022 $db = $this->getDB();
1032 ), array( 'rd_from' => array_keys( $this->mPendingRedirectIDs
) ),
1035 foreach ( $res as $row ) {
1036 $rdfrom = intval( $row->rd_from
);
1037 $from = $this->mPendingRedirectIDs
[$rdfrom]->getPrefixedText();
1038 $to = Title
::makeTitle(
1044 $this->mResolvedRedirectTitles
[$from] = $this->mPendingRedirectIDs
[$rdfrom];
1045 unset( $this->mPendingRedirectIDs
[$rdfrom] );
1046 if ( $to->isExternal() ) {
1047 $this->mInterwikiTitles
[$to->getPrefixedText()] = $to->getInterwiki();
1048 } elseif ( !isset( $this->mAllPages
[$row->rd_namespace
][$row->rd_title
] ) ) {
1049 $lb->add( $row->rd_namespace
, $row->rd_title
);
1051 $this->mRedirectTitles
[$from] = $to;
1054 if ( $this->mPendingRedirectIDs
) {
1055 // We found pages that aren't in the redirect table
1057 foreach ( $this->mPendingRedirectIDs
as $id => $title ) {
1058 $page = WikiPage
::factory( $title );
1059 $rt = $page->insertRedirect();
1061 // What the hell. Let's just ignore this
1065 $from = $title->getPrefixedText();
1066 $this->mResolvedRedirectTitles
[$from] = $title;
1067 $this->mRedirectTitles
[$from] = $rt;
1068 unset( $this->mPendingRedirectIDs
[$id] );
1076 * Get the cache mode for the data generated by this module.
1077 * All PageSet users should take into account whether this returns a more-restrictive
1078 * cache mode than the using module itself. For possible return values and other
1079 * details about cache modes, see ApiMain::setCacheMode()
1081 * Public caching will only be allowed if *all* the modules that supply
1082 * data for a given request return a cache mode of public.
1084 * @param array|null $params
1088 public function getCacheMode( $params = null ) {
1089 return $this->mCacheMode
;
1093 * Given an array of title strings, convert them into Title objects.
1094 * Alternatively, an array of Title objects may be given.
1095 * This method validates access rights for the title,
1096 * and appends normalization values to the output.
1098 * @param array $titles Array of Title objects or strings
1101 private function processTitlesArray( $titles ) {
1102 $usernames = array();
1103 $linkBatch = new LinkBatch();
1105 foreach ( $titles as $title ) {
1106 if ( is_string( $title ) ) {
1108 $titleObj = Title
::newFromTextThrow( $title, $this->mDefaultNamespace
);
1109 } catch ( MalformedTitleException
$ex ) {
1110 // Handle invalid titles gracefully
1111 $this->mAllPages
[0][$title] = $this->mFakePageId
;
1112 $this->mInvalidTitles
[$this->mFakePageId
] = array(
1114 'invalidreason' => $ex->getMessage(),
1116 $this->mFakePageId
--;
1117 continue; // There's nothing else we can do
1122 $unconvertedTitle = $titleObj->getPrefixedText();
1123 $titleWasConverted = false;
1124 if ( $titleObj->isExternal() ) {
1125 // This title is an interwiki link.
1126 $this->mInterwikiTitles
[$unconvertedTitle] = $titleObj->getInterwiki();
1128 // Variants checking
1130 if ( $this->mConvertTitles
&&
1131 count( $wgContLang->getVariants() ) > 1 &&
1132 !$titleObj->exists()
1134 // Language::findVariantLink will modify titleText and titleObj into
1135 // the canonical variant if possible
1136 $titleText = is_string( $title ) ?
$title : $titleObj->getPrefixedText();
1137 $wgContLang->findVariantLink( $titleText, $titleObj );
1138 $titleWasConverted = $unconvertedTitle !== $titleObj->getPrefixedText();
1141 if ( $titleObj->getNamespace() < 0 ) {
1142 // Handle Special and Media pages
1143 $titleObj = $titleObj->fixSpecialName();
1144 $this->mSpecialTitles
[$this->mFakePageId
] = $titleObj;
1145 $this->mFakePageId
--;
1148 $linkBatch->addObj( $titleObj );
1152 // Make sure we remember the original title that was
1153 // given to us. This way the caller can correlate new
1154 // titles with the originally requested when e.g. the
1155 // namespace is localized or the capitalization is
1157 if ( $titleWasConverted ) {
1158 $this->mConvertedTitles
[$unconvertedTitle] = $titleObj->getPrefixedText();
1159 // In this case the page can't be Special.
1160 if ( is_string( $title ) && $title !== $unconvertedTitle ) {
1161 $this->mNormalizedTitles
[$title] = $unconvertedTitle;
1163 } elseif ( is_string( $title ) && $title !== $titleObj->getPrefixedText() ) {
1164 $this->mNormalizedTitles
[$title] = $titleObj->getPrefixedText();
1167 // Need gender information
1168 if ( MWNamespace
::hasGenderDistinction( $titleObj->getNamespace() ) ) {
1169 $usernames[] = $titleObj->getText();
1172 // Get gender information
1173 $genderCache = GenderCache
::singleton();
1174 $genderCache->doQuery( $usernames, __METHOD__
);
1180 * Set data for a title.
1182 * This data may be extracted into an ApiResult using
1183 * self::populateGeneratorData. This should generally be limited to
1184 * data that is likely to be particularly useful to end users rather than
1185 * just being a dump of everything returned in non-generator mode.
1187 * Redirects here will *not* be followed, even if 'redirects' was
1188 * specified, since in the case of multiple redirects we can't know which
1189 * source's data to use on the target.
1191 * @param Title $title
1192 * @param array $data
1194 public function setGeneratorData( Title
$title, array $data ) {
1195 $ns = $title->getNamespace();
1196 $dbkey = $title->getDBkey();
1197 $this->mGeneratorData
[$ns][$dbkey] = $data;
1201 * Populate the generator data for all titles in the result
1203 * The page data may be inserted into an ApiResult object or into an
1204 * associative array. The $path parameter specifies the path within the
1205 * ApiResult or array to find the "pages" node.
1207 * The "pages" node itself must be an associative array mapping the page ID
1208 * or fake page ID values returned by this pageset (see
1209 * self::getAllTitlesByNamespace() and self::getSpecialTitles()) to
1210 * associative arrays of page data. Each of those subarrays will have the
1211 * data from self::setGeneratorData() merged in.
1213 * Data that was set by self::setGeneratorData() for pages not in the
1214 * "pages" node will be ignored.
1216 * @param ApiResult|array &$result
1217 * @param array $path
1218 * @return bool Whether the data fit
1220 public function populateGeneratorData( &$result, array $path = array() ) {
1221 if ( $result instanceof ApiResult
) {
1222 $data = $result->getResultData( $path );
1223 if ( $data === null ) {
1228 foreach ( $path as $key ) {
1229 if ( !isset( $data[$key] ) ) {
1230 // Path isn't in $result, so nothing to add, so everything
1234 $data = &$data[$key];
1237 foreach ( $this->mGeneratorData
as $ns => $dbkeys ) {
1240 foreach ( $this->mSpecialTitles
as $id => $title ) {
1241 $pages[$title->getDBkey()] = $id;
1244 if ( !isset( $this->mAllPages
[$ns] ) ) {
1245 // No known titles in the whole namespace. Skip it.
1248 $pages = $this->mAllPages
[$ns];
1250 foreach ( $dbkeys as $dbkey => $genData ) {
1251 if ( !isset( $pages[$dbkey] ) ) {
1252 // Unknown title. Forget it.
1255 $pageId = $pages[$dbkey];
1256 if ( !isset( $data[$pageId] ) ) {
1257 // $pageId didn't make it into the result. Ignore it.
1261 if ( $result instanceof ApiResult
) {
1262 $path2 = array_merge( $path, array( $pageId ) );
1263 foreach ( $genData as $key => $value ) {
1264 if ( !$result->addValue( $path2, $key, $value ) ) {
1269 $data[$pageId] = array_merge( $data[$pageId], $genData );
1277 * Get the database connection (read-only)
1278 * @return DatabaseBase
1280 protected function getDB() {
1281 return $this->mDbSource
->getDB();
1285 * Returns the input array of integers with all values < 0 removed
1287 * @param array $array
1290 private static function getPositiveIntegers( $array ) {
1291 // bug 25734 API: possible issue with revids validation
1292 // It seems with a load of revision rows, MySQL gets upset
1293 // Remove any < 0 integers, as they can't be valid
1294 foreach ( $array as $i => $int ) {
1296 unset( $array[$i] );
1303 public function getAllowedParams( $flags = 0 ) {
1306 ApiBase
::PARAM_ISMULTI
=> true,
1307 ApiBase
::PARAM_HELP_MSG
=> 'api-pageset-param-titles',
1310 ApiBase
::PARAM_TYPE
=> 'integer',
1311 ApiBase
::PARAM_ISMULTI
=> true,
1312 ApiBase
::PARAM_HELP_MSG
=> 'api-pageset-param-pageids',
1315 ApiBase
::PARAM_TYPE
=> 'integer',
1316 ApiBase
::PARAM_ISMULTI
=> true,
1317 ApiBase
::PARAM_HELP_MSG
=> 'api-pageset-param-revids',
1319 'generator' => array(
1320 ApiBase
::PARAM_TYPE
=> null,
1321 ApiBase
::PARAM_HELP_MSG
=> 'api-pageset-param-generator',
1322 ApiBase
::PARAM_SUBMODULE_PARAM_PREFIX
=> 'g',
1324 'redirects' => array(
1325 ApiBase
::PARAM_DFLT
=> false,
1326 ApiBase
::PARAM_HELP_MSG
=> $this->mAllowGenerator
1327 ?
'api-pageset-param-redirects-generator'
1328 : 'api-pageset-param-redirects-nogenerator',
1330 'converttitles' => array(
1331 ApiBase
::PARAM_DFLT
=> false,
1332 ApiBase
::PARAM_HELP_MSG
=> array(
1333 'api-pageset-param-converttitles',
1334 new DeferredStringifier(
1335 function ( IContextSource
$context ) {
1336 return $context->getLanguage()
1337 ->commaList( LanguageConverter
::$languagesWithVariants );
1345 if ( !$this->mAllowGenerator
) {
1346 unset( $result['generator'] );
1347 } elseif ( $flags & ApiBase
::GET_VALUES_FOR_HELP
) {
1348 $result['generator'][ApiBase
::PARAM_TYPE
] = 'submodule';
1349 $result['generator'][ApiBase
::PARAM_SUBMODULE_MAP
] = $this->getGenerators();
1355 private static $generators = null;
1358 * Get an array of all available generators
1361 private function getGenerators() {
1362 if ( self
::$generators === null ) {
1363 $query = $this->mDbSource
;
1364 if ( !( $query instanceof ApiQuery
) ) {
1365 // If the parent container of this pageset is not ApiQuery,
1366 // we must create it to get module manager
1367 $query = $this->getMain()->getModuleManager()->getModule( 'query' );
1370 $prefix = $query->getModulePath() . '+';
1371 $mgr = $query->getModuleManager();
1372 foreach ( $mgr->getNamesWithClasses() as $name => $class ) {
1373 if ( is_subclass_of( $class, 'ApiQueryGeneratorBase' ) ) {
1374 $gens[$name] = $prefix . $name;
1378 self
::$generators = $gens;
1381 return self
::$generators;