ApiQuery.php

Go to the documentation of this file.

<?php
class ApiQuery extends ApiBase {

    private static $QueryPropModules = array(
        'categories' => 'ApiQueryCategories',
        'categoryinfo' => 'ApiQueryCategoryInfo',
        'contributors' => 'ApiQueryContributors',
        'duplicatefiles' => 'ApiQueryDuplicateFiles',
        'extlinks' => 'ApiQueryExternalLinks',
        'images' => 'ApiQueryImages',
        'imageinfo' => 'ApiQueryImageInfo',
        'info' => 'ApiQueryInfo',
        'links' => 'ApiQueryLinks',
        'iwlinks' => 'ApiQueryIWLinks',
        'langlinks' => 'ApiQueryLangLinks',
        'pageprops' => 'ApiQueryPageProps',
        'redirects' => 'ApiQueryRedirects',
        'revisions' => 'ApiQueryRevisions',
        'stashimageinfo' => 'ApiQueryStashImageInfo',
        'templates' => 'ApiQueryLinks',
    );

    private static $QueryListModules = array(
        'allcategories' => 'ApiQueryAllCategories',
        'allfileusages' => 'ApiQueryAllLinks',
        'allimages' => 'ApiQueryAllImages',
        'alllinks' => 'ApiQueryAllLinks',
        'allpages' => 'ApiQueryAllPages',
        'allredirects' => 'ApiQueryAllLinks',
        'alltransclusions' => 'ApiQueryAllLinks',
        'allusers' => 'ApiQueryAllUsers',
        'backlinks' => 'ApiQueryBacklinks',
        'blocks' => 'ApiQueryBlocks',
        'categorymembers' => 'ApiQueryCategoryMembers',
        'deletedrevs' => 'ApiQueryDeletedrevs',
        'embeddedin' => 'ApiQueryBacklinks',
        'exturlusage' => 'ApiQueryExtLinksUsage',
        'filearchive' => 'ApiQueryFilearchive',
        'imageusage' => 'ApiQueryBacklinks',
        'iwbacklinks' => 'ApiQueryIWBacklinks',
        'langbacklinks' => 'ApiQueryLangBacklinks',
        'logevents' => 'ApiQueryLogEvents',
        'pageswithprop' => 'ApiQueryPagesWithProp',
        'pagepropnames' => 'ApiQueryPagePropNames',
        'prefixsearch' => 'ApiQueryPrefixSearch',
        'protectedtitles' => 'ApiQueryProtectedTitles',
        'querypage' => 'ApiQueryQueryPage',
        'random' => 'ApiQueryRandom',
        'recentchanges' => 'ApiQueryRecentChanges',
        'search' => 'ApiQuerySearch',
        'tags' => 'ApiQueryTags',
        'usercontribs' => 'ApiQueryContributions',
        'users' => 'ApiQueryUsers',
        'watchlist' => 'ApiQueryWatchlist',
        'watchlistraw' => 'ApiQueryWatchlistRaw',
    );

    private static $QueryMetaModules = array(
        'allmessages' => 'ApiQueryAllMessages',
        'siteinfo' => 'ApiQuerySiteinfo',
        'userinfo' => 'ApiQueryUserInfo',
        'filerepoinfo' => 'ApiQueryFileRepoInfo',
    );

    private $mPageSet;

    private $mParams;
    private $mNamedDB = array();
    private $mModuleMgr;
    private $mGeneratorContinue;
    private $mUseLegacyContinue;

    public function __construct( $main, $action ) {
        parent::__construct( $main, $action );

        $this->mModuleMgr = new ApiModuleManager( $this );

        // Allow custom modules to be added in LocalSettings.php
        global $wgAPIPropModules, $wgAPIListModules, $wgAPIMetaModules;
        $this->mModuleMgr->addModules( self::$QueryPropModules, 'prop' );
        $this->mModuleMgr->addModules( $wgAPIPropModules, 'prop' );
        $this->mModuleMgr->addModules( self::$QueryListModules, 'list' );
        $this->mModuleMgr->addModules( $wgAPIListModules, 'list' );
        $this->mModuleMgr->addModules( self::$QueryMetaModules, 'meta' );
        $this->mModuleMgr->addModules( $wgAPIMetaModules, 'meta' );

        // Create PageSet that will process titles/pageids/revids/generator
        $this->mPageSet = new ApiPageSet( $this );
    }

    public function getModuleManager() {
        return $this->mModuleMgr;
    }

    public function getNamedDB( $name, $db, $groups ) {
        if ( !array_key_exists( $name, $this->mNamedDB ) ) {
            $this->profileDBIn();
            $this->mNamedDB[$name] = wfGetDB( $db, $groups );
            $this->profileDBOut();
        }

        return $this->mNamedDB[$name];
    }

    public function getPageSet() {
        return $this->mPageSet;
    }

    public function getModules() {
        wfDeprecated( __METHOD__, '1.21' );

        return $this->getModuleManager()->getNamesWithClasses();
    }

    public function getGenerators() {
        wfDeprecated( __METHOD__, '1.21' );
        $gens = array();
        foreach ( $this->mModuleMgr->getNamesWithClasses() as $name => $class ) {
            if ( is_subclass_of( $class, 'ApiQueryGeneratorBase' ) ) {
                $gens[$name] = $class;
            }
        }

        return $gens;
    }

    function getModuleType( $moduleName ) {
        return $this->getModuleManager()->getModuleGroup( $moduleName );
    }

    public function getCustomPrinter() {
        // If &exportnowrap is set, use the raw formatter
        if ( $this->getParameter( 'export' ) &&
            $this->getParameter( 'exportnowrap' )
        ) {
            return new ApiFormatRaw( $this->getMain(),
                $this->getMain()->createPrinterByName( 'xml' ) );
        } else {
            return null;
        }
    }

    public function execute() {
        $this->mParams = $this->extractRequestParams();

        // $pagesetParams is a array of parameter names used by the pageset generator
        //   or null if pageset has already finished and is no longer needed
        // $completeModules is a set of complete modules with the name as key
        $this->initContinue( $pagesetParams, $completeModules );

        // Instantiate requested modules
        $allModules = array();
        $this->instantiateModules( $allModules, 'prop' );
        $propModules = $allModules; // Keep a copy
        $this->instantiateModules( $allModules, 'list' );
        $this->instantiateModules( $allModules, 'meta' );

        // Filter modules based on continue parameter
        $modules = $this->initModules( $allModules, $completeModules, $pagesetParams !== null );

        // Execute pageset if in legacy mode or if pageset is not done
        if ( $completeModules === null || $pagesetParams !== null ) {
            // Populate page/revision information
            $this->mPageSet->execute();
            // Record page information (title, namespace, if exists, etc)
            $this->outputGeneralPageInfo();
        } else {
            $this->mPageSet->executeDryRun();
        }

        $cacheMode = $this->mPageSet->getCacheMode();

        // Execute all unfinished modules
        foreach ( $modules as $module ) {
            $params = $module->extractRequestParams();
            $cacheMode = $this->mergeCacheMode(
                $cacheMode, $module->getCacheMode( $params ) );
            $module->profileIn();
            $module->execute();
            wfRunHooks( 'APIQueryAfterExecute', array( &$module ) );
            $module->profileOut();
        }

        // Set the cache mode
        $this->getMain()->setCacheMode( $cacheMode );

        if ( $completeModules === null ) {
            return; // Legacy continue, we are done
        }

        // Reformat query-continue result section
        $result = $this->getResult();
        $qc = $result->getData();
        if ( isset( $qc['query-continue'] ) ) {
            $qc = $qc['query-continue'];
            $result->unsetValue( null, 'query-continue' );
        } elseif ( $this->mGeneratorContinue !== null ) {
            $qc = array();
        } else {
            // no more "continue"s, we are done!
            return;
        }

        // we are done with all the modules that do not have result in query-continue
        $completeModules = array_merge( $completeModules, array_diff_key( $modules, $qc ) );
        if ( $pagesetParams !== null ) {
            // The pageset is still in use, check if all props have finished
            $incompleteProps = array_intersect_key( $propModules, $qc );
            if ( count( $incompleteProps ) > 0 ) {
                // Properties are not done, continue with the same pageset state - copy current parameters
                $main = $this->getMain();
                $contValues = array();
                foreach ( $pagesetParams as $param ) {
                    // The param name is already prefix-encoded
                    $contValues[$param] = $main->getVal( $param );
                }
            } elseif ( $this->mGeneratorContinue !== null ) {
                // Move to the next set of pages produced by pageset, properties need to be restarted
                $contValues = $this->mGeneratorContinue;
                $pagesetParams = array_keys( $contValues );
                $completeModules = array_diff_key( $completeModules, $propModules );
            } else {
                // Done with the pageset, finish up with the the lists and meta modules
                $pagesetParams = null;
            }
        }

        $continue = '||' . implode( '|', array_keys( $completeModules ) );
        if ( $pagesetParams !== null ) {
            // list of all pageset parameters to use in the next request
            $continue = implode( '|', $pagesetParams ) . $continue;
        } else {
            // we are done with the pageset
            $contValues = array();
            $continue = '-' . $continue;
        }
        $contValues['continue'] = $continue;
        foreach ( $qc as $qcModule ) {
            foreach ( $qcModule as $qcKey => $qcValue ) {
                $contValues[$qcKey] = $qcValue;
            }
        }
        $this->getResult()->addValue( null, 'continue', $contValues );
    }

    private function initContinue( &$pagesetParams, &$completeModules ) {
        $pagesetParams = array();
        $continue = $this->mParams['continue'];
        if ( $continue !== null ) {
            $this->mUseLegacyContinue = false;
            if ( $continue !== '' ) {
                // Format: ' pagesetParam1 | pagesetParam2 || module1 | module2 | module3 | ...
                // If pageset is done, use '-'
                $continue = explode( '||', $continue );
                $this->dieContinueUsageIf( count( $continue ) !== 2 );
                if ( $continue[0] === '-' ) {
                    $pagesetParams = null; // No need to execute pageset
                } elseif ( $continue[0] !== '' ) {
                    // list of pageset params that might need to be repeated
                    $pagesetParams = explode( '|', $continue[0] );
                }
                $continue = $continue[1];
            }
            if ( $continue !== '' ) {
                $completeModules = array_flip( explode( '|', $continue ) );
            } else {
                $completeModules = array();
            }
        } else {
            $this->mUseLegacyContinue = true;
            $completeModules = null;
        }
    }

    private function initModules( $allModules, $completeModules, $usePageset ) {
        $modules = $allModules;
        $tmp = $completeModules;
        $wasPosted = $this->getRequest()->wasPosted();

        foreach ( $allModules as $moduleName => $module ) {
            if ( !$wasPosted && $module->mustBePosted() ) {
                $this->dieUsageMsgOrDebug( array( 'mustbeposted', $moduleName ) );
            }
            if ( $completeModules !== null && array_key_exists( $moduleName, $completeModules ) ) {
                // If this module is done, mark all its params as used
                $module->extractRequestParams();
                // Make sure this module is not used during execution
                unset( $modules[$moduleName] );
                unset( $tmp[$moduleName] );
            } elseif ( $completeModules === null || $usePageset ) {
                // Query modules may optimize data requests through the $this->getPageSet()
                // object by adding extra fields from the page table.
                // This function will gather all the extra request fields from the modules.
                $module->requestExtraData( $this->mPageSet );
            } else {
                // Error - this prop module must have finished before generator is done
                $this->dieContinueUsageIf( $this->mModuleMgr->getModuleGroup( $moduleName ) === 'prop' );
            }
        }
        $this->dieContinueUsageIf( $completeModules !== null && count( $tmp ) !== 0 );

        return $modules;
    }

    protected function mergeCacheMode( $cacheMode, $modCacheMode ) {
        if ( $modCacheMode === 'anon-public-user-private' ) {
            if ( $cacheMode !== 'private' ) {
                $cacheMode = 'anon-public-user-private';
            }
        } elseif ( $modCacheMode === 'public' ) {
            // do nothing, if it's public already it will stay public
        } else { // private
            $cacheMode = 'private';
        }

        return $cacheMode;
    }

    private function instantiateModules( &$modules, $param ) {
        if ( isset( $this->mParams[$param] ) ) {
            foreach ( $this->mParams[$param] as $moduleName ) {
                $instance = $this->mModuleMgr->getModule( $moduleName, $param );
                if ( $instance === null ) {
                    ApiBase::dieDebug( __METHOD__, 'Error instantiating module' );
                }
                // Ignore duplicates. TODO 2.0: die()?
                if ( !array_key_exists( $moduleName, $modules ) ) {
                    $modules[$moduleName] = $instance;
                }
            }
        }
    }

    private function outputGeneralPageInfo() {
        $pageSet = $this->getPageSet();
        $result = $this->getResult();

        // We don't check for a full result set here because we can't be adding
        // more than 380K. The maximum revision size is in the megabyte range,
        // and the maximum result size must be even higher than that.

        $values = $pageSet->getNormalizedTitlesAsResult( $result );
        if ( $values ) {
            $result->addValue( 'query', 'normalized', $values );
        }
        $values = $pageSet->getConvertedTitlesAsResult( $result );
        if ( $values ) {
            $result->addValue( 'query', 'converted', $values );
        }
        $values = $pageSet->getInterwikiTitlesAsResult( $result, $this->mParams['iwurl'] );
        if ( $values ) {
            $result->addValue( 'query', 'interwiki', $values );
        }
        $values = $pageSet->getRedirectTitlesAsResult( $result );
        if ( $values ) {
            $result->addValue( 'query', 'redirects', $values );
        }
        $values = $pageSet->getMissingRevisionIDsAsResult( $result );
        if ( $values ) {
            $result->addValue( 'query', 'badrevids', $values );
        }

        // Page elements
        $pages = array();

        // Report any missing titles
        foreach ( $pageSet->getMissingTitles() as $fakeId => $title ) {
            $vals = array();
            ApiQueryBase::addTitleInfo( $vals, $title );
            $vals['missing'] = '';
            $pages[$fakeId] = $vals;
        }
        // Report any invalid titles
        foreach ( $pageSet->getInvalidTitles() as $fakeId => $title ) {
            $pages[$fakeId] = array( 'title' => $title, 'invalid' => '' );
        }
        // Report any missing page ids
        foreach ( $pageSet->getMissingPageIDs() as $pageid ) {
            $pages[$pageid] = array(
                'pageid' => $pageid,
                'missing' => ''
            );
        }
        // Report special pages
        foreach ( $pageSet->getSpecialTitles() as $fakeId => $title ) {
            $vals = array();
            ApiQueryBase::addTitleInfo( $vals, $title );
            $vals['special'] = '';
            if ( $title->isSpecialPage() &&
                !SpecialPageFactory::exists( $title->getDBkey() )
            ) {
                $vals['missing'] = '';
            } elseif ( $title->getNamespace() == NS_MEDIA &&
                !wfFindFile( $title )
            ) {
                $vals['missing'] = '';
            }
            $pages[$fakeId] = $vals;
        }

        // Output general page information for found titles
        foreach ( $pageSet->getGoodTitles() as $pageid => $title ) {
            $vals = array();
            $vals['pageid'] = $pageid;
            ApiQueryBase::addTitleInfo( $vals, $title );
            $pages[$pageid] = $vals;
        }

        if ( count( $pages ) ) {
            if ( $this->mParams['indexpageids'] ) {
                $pageIDs = array_keys( $pages );
                // json treats all map keys as strings - converting to match
                $pageIDs = array_map( 'strval', $pageIDs );
                $result->setIndexedTagName( $pageIDs, 'id' );
                $result->addValue( 'query', 'pageids', $pageIDs );
            }

            $result->setIndexedTagName( $pages, 'page' );
            $result->addValue( 'query', 'pages', $pages );
        }
        if ( $this->mParams['export'] ) {
            $this->doExport( $pageSet, $result );
        }
    }

    public function setGeneratorContinue( $module, $paramName, $paramValue ) {
        if ( $this->mUseLegacyContinue ) {
            return false;
        }
        $paramName = $module->encodeParamName( $paramName );
        if ( $this->mGeneratorContinue === null ) {
            $this->mGeneratorContinue = array();
        }
        $this->mGeneratorContinue[$paramName] = $paramValue;

        return true;
    }

    private function doExport( $pageSet, $result ) {
        $exportTitles = array();
        $titles = $pageSet->getGoodTitles();
        if ( count( $titles ) ) {
            $user = $this->getUser();
            foreach ( $titles as $title ) {
                if ( $title->userCan( 'read', $user ) ) {
                    $exportTitles[] = $title;
                }
            }
        }

        $exporter = new WikiExporter( $this->getDB() );
        // WikiExporter writes to stdout, so catch its
        // output with an ob
        ob_start();
        $exporter->openStream();
        foreach ( $exportTitles as $title ) {
            $exporter->pageByTitle( $title );
        }
        $exporter->closeStream();
        $exportxml = ob_get_contents();
        ob_end_clean();

        // Don't check the size of exported stuff
        // It's not continuable, so it would cause more
        // problems than it'd solve
        $result->disableSizeCheck();
        if ( $this->mParams['exportnowrap'] ) {
            $result->reset();
            // Raw formatter will handle this
            $result->addValue( null, 'text', $exportxml );
            $result->addValue( null, 'mime', 'text/xml' );
        } else {
            $r = array();
            ApiResult::setContent( $r, $exportxml );
            $result->addValue( 'query', 'export', $r );
        }
        $result->enableSizeCheck();
    }

    public function getAllowedParams( $flags = 0 ) {
        $result = array(
            'prop' => array(
                ApiBase::PARAM_ISMULTI => true,
                ApiBase::PARAM_TYPE => $this->mModuleMgr->getNames( 'prop' )
            ),
            'list' => array(
                ApiBase::PARAM_ISMULTI => true,
                ApiBase::PARAM_TYPE => $this->mModuleMgr->getNames( 'list' )
            ),
            'meta' => array(
                ApiBase::PARAM_ISMULTI => true,
                ApiBase::PARAM_TYPE => $this->mModuleMgr->getNames( 'meta' )
            ),
            'indexpageids' => false,
            'export' => false,
            'exportnowrap' => false,
            'iwurl' => false,
            'continue' => null,
        );
        if ( $flags ) {
            $result += $this->getPageSet()->getFinalParams( $flags );
        }

        return $result;
    }

    public function makeHelpMsg() {

        // Use parent to make default message for the query module
        $msg = parent::makeHelpMsg();

        $querySeparator = str_repeat( '--- ', 12 );
        $moduleSeparator = str_repeat( '*** ', 14 );
        $msg .= "\n$querySeparator Query: Prop  $querySeparator\n\n";
        $msg .= $this->makeHelpMsgHelper( 'prop' );
        $msg .= "\n$querySeparator Query: List  $querySeparator\n\n";
        $msg .= $this->makeHelpMsgHelper( 'list' );
        $msg .= "\n$querySeparator Query: Meta  $querySeparator\n\n";
        $msg .= $this->makeHelpMsgHelper( 'meta' );
        $msg .= "\n\n$moduleSeparator Modules: continuation  $moduleSeparator\n\n";

        return $msg;
    }

    private function makeHelpMsgHelper( $group ) {
        $moduleDescriptions = array();

        $moduleNames = $this->mModuleMgr->getNames( $group );
        sort( $moduleNames );
        foreach ( $moduleNames as $name ) {
            $module = $this->mModuleMgr->getModule( $name );

            $msg = ApiMain::makeHelpMsgHeader( $module, $group );
            $msg2 = $module->makeHelpMsg();
            if ( $msg2 !== false ) {
                $msg .= $msg2;
            }
            if ( $module instanceof ApiQueryGeneratorBase ) {
                $msg .= "Generator:\n  This module may be used as a generator\n";
            }
            $moduleDescriptions[] = $msg;
        }

        return implode( "\n", $moduleDescriptions );
    }

    public function shouldCheckMaxlag() {
        return true;
    }

    public function getParamDescription() {
        return $this->getPageSet()->getFinalParamDescription() + array(
            'prop' => 'Which properties to get for the titles/revisions/pageids. ' .
                'Module help is available below',
            'list' => 'Which lists to get. Module help is available below',
            'meta' => 'Which metadata to get about the site. Module help is available below',
            'indexpageids' => 'Include an additional pageids section listing all returned page IDs',
            'export' => 'Export the current revisions of all given or generated pages',
            'exportnowrap' => 'Return the export XML without wrapping it in an ' .
                'XML result (same format as Special:Export). Can only be used with export',
            'iwurl' => 'Whether to get the full URL if the title is an interwiki link',
            'continue' => array(
                'When present, formats query-continue as key-value pairs that ' .
                    'should simply be merged into the original request.',
                'This parameter must be set to an empty string in the initial query.',
                'This parameter is recommended for all new development, and ' .
                    'will be made default in the next API version.'
            ),
        );
    }

    public function getDescription() {
        return array(
            'Query API module allows applications to get needed pieces of data ' .
                'from the MediaWiki databases,',
            'and is loosely based on the old query.php interface.',
            'All data modifications will first have to use query to acquire a ' .
                'token to prevent abuse from malicious sites.'
        );
    }

    public function getPossibleErrors() {
        return array_merge(
            parent::getPossibleErrors(),
            $this->getPageSet()->getFinalPossibleErrors()
        );
    }

    public function getExamples() {
        return array(
            'api.php?action=query&prop=revisions&meta=siteinfo&' .
                'titles=Main%20Page&rvprop=user|comment&continue=',
            'api.php?action=query&generator=allpages&gapprefix=API/&prop=revisions&continue=',
        );
    }

    public function getHelpUrls() {
        return array(
            'https://www.mediawiki.org/wiki/API:Query',
            'https://www.mediawiki.org/wiki/API:Meta',
            'https://www.mediawiki.org/wiki/API:Properties',
            'https://www.mediawiki.org/wiki/API:Lists',
        );
    }
}