ApiQueryBase.php

Go to the documentation of this file.

<?php
use MediaWiki\MediaWikiServices;
use MediaWiki\Title\MalformedTitleException;
use MediaWiki\Title\Title;
use MediaWiki\Title\TitleValue;
use Wikimedia\Rdbms\IDatabase;
use Wikimedia\Rdbms\IExpression;
use Wikimedia\Rdbms\IReadableDatabase;
use Wikimedia\Rdbms\IResultWrapper;
use Wikimedia\Rdbms\SelectQueryBuilder;
 
abstract class ApiQueryBase extends ApiBase {
    use ApiQueryBlockInfoTrait;
 
    private ApiQuery $mQueryModule;
    private ?IReadableDatabase $mDb;
 
    private $queryBuilder;
 
    public function __construct( ApiQuery $queryModule, $moduleName, $paramPrefix = '' ) {
        parent::__construct( $queryModule->getMain(), $moduleName, $paramPrefix );
        $this->mQueryModule = $queryModule;
        $this->mDb = null;
        $this->resetQueryParams();
    }
 
    /***************************************************************************/
    // region   Methods to implement
    public function getCacheMode( $params ) {
        return 'private';
    }
 
    public function requestExtraData( $pageSet ) {
    }
 
    // endregion -- end of methods to implement
 
    /***************************************************************************/
    // region   Data access
    public function getQuery() {
        return $this->mQueryModule;
    }
 
    public function getParent() {
        return $this->getQuery();
    }
 
    protected function getDB() {
        $this->mDb ??= $this->getQuery()->getDB();
 
        return $this->mDb;
    }
 
    protected function getPageSet() {
        return $this->getQuery()->getPageSet();
    }
 
    // endregion -- end of data access
 
    /***************************************************************************/
    // region   Querying
    protected function resetQueryParams() {
        $this->queryBuilder = null;
    }
 
    protected function getQueryBuilder() {
        $this->queryBuilder ??= $this->getDB()->newSelectQueryBuilder();
        return $this->queryBuilder;
    }
 
    protected function addTables( $tables, $alias = null ) {
        if ( is_array( $tables ) ) {
            if ( $alias !== null ) {
                ApiBase::dieDebug( __METHOD__, 'Multiple table aliases not supported' );
            }
            $this->getQueryBuilder()->rawTables( $tables );
        } else {
            $this->getQueryBuilder()->table( $tables, $alias );
        }
    }
 
    protected function addJoinConds( $join_conds ) {
        if ( !is_array( $join_conds ) ) {
            ApiBase::dieDebug( __METHOD__, 'Join conditions have to be arrays' );
        }
        $this->getQueryBuilder()->joinConds( $join_conds );
    }
 
    protected function addFields( $value ) {
        $this->getQueryBuilder()->fields( $value );
    }
 
    protected function addFieldsIf( $value, $condition ) {
        if ( $condition ) {
            $this->addFields( $value );
 
            return true;
        }
 
        return false;
    }
 
    protected function addWhere( $value ) {
        if ( is_array( $value ) ) {
            // Double check: don't insert empty arrays,
            // Database::makeList() chokes on them
            if ( count( $value ) ) {
                $this->getQueryBuilder()->where( $value );
            }
        } else {
            $this->getQueryBuilder()->where( $value );
        }
    }
 
    protected function addWhereIf( $value, $condition ) {
        if ( $condition ) {
            $this->addWhere( $value );
 
            return true;
        }
 
        return false;
    }
 
    protected function addWhereFld( $field, $value ) {
        if ( $value !== null && !( is_array( $value ) && !$value ) ) {
            $this->getQueryBuilder()->where( [ $field => $value ] );
        }
    }
 
    protected function addWhereIDsFld( $table, $field, $ids ) {
        // Use count() to its full documented capabilities to simultaneously
        // test for null, empty array or empty countable object
        if ( count( $ids ) ) {
            $ids = $this->filterIDs( [ [ $table, $field ] ], $ids );
 
            if ( $ids === [] ) {
                // Return nothing, no IDs are valid
                $this->getQueryBuilder()->where( '0 = 1' );
            } else {
                $this->getQueryBuilder()->where( [ $field => $ids ] );
            }
        }
        return count( $ids );
    }
 
    protected function addWhereRange( $field, $dir, $start, $end, $sort = true ) {
        $isDirNewer = ( $dir === 'newer' );
        $after = ( $isDirNewer ? '>=' : '<=' );
        $before = ( $isDirNewer ? '<=' : '>=' );
        $db = $this->getDB();
 
        if ( $start !== null ) {
            $this->addWhere( $db->expr( $field, $after, $start ) );
        }
 
        if ( $end !== null ) {
            $this->addWhere( $db->expr( $field, $before, $end ) );
        }
 
        if ( $sort ) {
            $this->getQueryBuilder()->orderBy( $field, $isDirNewer ? null : 'DESC' );
        }
    }
 
    protected function addTimestampWhereRange( $field, $dir, $start, $end, $sort = true ) {
        $db = $this->getDB();
        $this->addWhereRange( $field, $dir,
            $db->timestampOrNull( $start ), $db->timestampOrNull( $end ), $sort );
    }
 
    protected function addOption( $name, $value = null ) {
        $this->getQueryBuilder()->option( $name, $value );
    }
 
    protected function select( $method, $extraQuery = [], array &$hookData = null ) {
        $queryBuilder = clone $this->getQueryBuilder();
        if ( isset( $extraQuery['tables'] ) ) {
            $queryBuilder->rawTables( (array)$extraQuery['tables'] );
        }
        if ( isset( $extraQuery['fields'] ) ) {
            $queryBuilder->fields( (array)$extraQuery['fields'] );
        }
        if ( isset( $extraQuery['where'] ) ) {
            $queryBuilder->where( (array)$extraQuery['where'] );
        }
        if ( isset( $extraQuery['options'] ) ) {
            $queryBuilder->options( (array)$extraQuery['options'] );
        }
        if ( isset( $extraQuery['join_conds'] ) ) {
            $queryBuilder->joinConds( (array)$extraQuery['join_conds'] );
        }
 
        if ( $hookData !== null && $this->getHookContainer()->isRegistered( 'ApiQueryBaseBeforeQuery' ) ) {
            $info = $queryBuilder->getQueryInfo();
            $this->getHookRunner()->onApiQueryBaseBeforeQuery(
                $this, $info['tables'], $info['fields'], $info['conds'],
                $info['options'], $info['join_conds'], $hookData
            );
            $queryBuilder = $this->getDB()->newSelectQueryBuilder()->queryInfo( $info );
        }
 
        $queryBuilder->caller( $method );
        $res = $queryBuilder->fetchResultSet();
 
        if ( $hookData !== null ) {
            $this->getHookRunner()->onApiQueryBaseAfterQuery( $this, $res, $hookData );
        }
 
        return $res;
    }
 
    protected function processRow( $row, array &$data, array &$hookData ) {
        return $this->getHookRunner()->onApiQueryBaseProcessRow( $this, $row, $data, $hookData );
    }
 
    // endregion -- end of querying
 
    /***************************************************************************/
    // region   Utility methods
    public static function addTitleInfo( &$arr, $title, $prefix = '' ) {
        $arr[$prefix . 'ns'] = $title->getNamespace();
        $arr[$prefix . 'title'] = $title->getPrefixedText();
    }
 
    protected function addPageSubItems( $pageId, $data ) {
        $result = $this->getResult();
        ApiResult::setIndexedTagName( $data, $this->getModulePrefix() );
 
        return $result->addValue( [ 'query', 'pages', (int)$pageId ],
            $this->getModuleName(),
            $data );
    }
 
    protected function addPageSubItem( $pageId, $item, $elemname = null ) {
        $result = $this->getResult();
        $fit = $result->addValue( [ 'query', 'pages', $pageId,
            $this->getModuleName() ], null, $item );
        if ( !$fit ) {
            return false;
        }
        $result->addIndexedTagName(
            [ 'query', 'pages', $pageId, $this->getModuleName() ],
            $elemname ?? $this->getModulePrefix()
        );
 
        return true;
    }
 
    protected function setContinueEnumParameter( $paramName, $paramValue ) {
        $this->getContinuationManager()->addContinueParam( $this, $paramName, $paramValue );
    }
 
    public function titlePartToKey( $titlePart, $namespace = NS_MAIN ) {
        $t = Title::makeTitleSafe( $namespace, $titlePart . 'x' );
        if ( !$t || $t->hasFragment() ) {
            // Invalid title (e.g. bad chars) or contained a '#'.
            $this->dieWithError( [ 'apierror-invalidtitle', wfEscapeWikiText( $titlePart ) ] );
        }
        if ( $namespace != $t->getNamespace() || $t->isExternal() ) {
            // This can happen in two cases. First, if you call titlePartToKey with a title part
            // that looks like a namespace, but with $defaultNamespace = NS_MAIN. It would be very
            // difficult to handle such a case. Such cases cannot exist and are therefore treated
            // as invalid user input. The second case is when somebody specifies a title interwiki
            // prefix.
            $this->dieWithError( [ 'apierror-invalidtitle', wfEscapeWikiText( $titlePart ) ] );
        }
 
        return substr( $t->getDBkey(), 0, -1 );
    }
 
    protected function parsePrefixedTitlePart( $titlePart, $defaultNamespace = NS_MAIN ) {
        try {
            $titleParser = MediaWikiServices::getInstance()->getTitleParser();
            $t = $titleParser->parseTitle( $titlePart . 'X', $defaultNamespace );
        } catch ( MalformedTitleException $e ) {
            $t = null;
        }
 
        if ( !$t || $t->hasFragment() || $t->isExternal() || $t->getDBkey() === 'X' ) {
            // Invalid title (e.g. bad chars) or contained a '#'.
            $this->dieWithError( [ 'apierror-invalidtitle', wfEscapeWikiText( $titlePart ) ] );
        }
 
        return new TitleValue( $t->getNamespace(), substr( $t->getDBkey(), 0, -1 ) );
    }
 
    public function validateSha1Hash( $hash ) {
        return (bool)preg_match( '/^[a-f0-9]{40}$/', $hash );
    }
 
    public function validateSha1Base36Hash( $hash ) {
        return (bool)preg_match( '/^[a-z0-9]{31}$/', $hash );
    }
 
    public function userCanSeeRevDel() {
        return $this->getAuthority()->isAllowedAny(
            'deletedhistory',
            'deletedtext',
            'deleterevision',
            'suppressrevision',
            'viewsuppressed'
        );
    }
 
    protected function executeGenderCacheFromResultWrapper(
        IResultWrapper $res, $fname = __METHOD__, $fieldPrefix = 'page'
    ) {
        if ( !$res->numRows() ) {
            return;
        }
 
        $services = MediaWikiServices::getInstance();
        if ( !$services->getContentLanguage()->needsGenderDistinction() ) {
            return;
        }
 
        $nsInfo = $services->getNamespaceInfo();
        $namespaceField = $fieldPrefix . '_namespace';
        $titleField = $fieldPrefix . '_title';
 
        $usernames = [];
        foreach ( $res as $row ) {
            if ( $nsInfo->hasGenderDistinction( $row->$namespaceField ) ) {
                $usernames[] = $row->$titleField;
            }
        }
 
        if ( $usernames === [] ) {
            return;
        }
 
        $genderCache = $services->getGenderCache();
        $genderCache->doQuery( $usernames, $fname );
    }
 
    // endregion -- end of utility methods
}