Localisation updates from https://translatewiki.net.

[mediawiki.git] / includes / api / ApiQueryBase.php

<?php
/**
 * Copyright © 2006 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 * http://www.gnu.org/copyleft/gpl.html
 *
 * @file
 */

namespace MediaWiki\Api;

use MediaWiki\MediaWikiServices;
use MediaWiki\Title\MalformedTitleException;
use MediaWiki\Title\Title;
use MediaWiki\Title\TitleValue;
use stdClass;
use Wikimedia\Rdbms\IDatabase;
use Wikimedia\Rdbms\IExpression;
use Wikimedia\Rdbms\IReadableDatabase;
use Wikimedia\Rdbms\IResultWrapper;
use Wikimedia\Rdbms\SelectQueryBuilder;

/**
 * This is a base class for all Query modules.
 * It provides some common functionality such as constructing various SQL
 * queries.
 *
 * @stable to extend
 *
 * @ingroup API
 */
abstract class ApiQueryBase extends ApiBase {
        use ApiQueryBlockInfoTrait;

        private ApiQuery $mQueryModule;
        private ?IReadableDatabase $mDb;

        /**
         * @var SelectQueryBuilder|null
         */
        private $queryBuilder;

        /**
         * @stable to call
         * @param ApiQuery $queryModule
         * @param string $moduleName
         * @param string $paramPrefix
         */
        public function __construct( ApiQuery $queryModule, string $moduleName, $paramPrefix = '' ) {
                parent::__construct( $queryModule->getMain(), $moduleName, $paramPrefix );
                $this->mQueryModule = $queryModule;
                $this->mDb = null;
                $this->resetQueryParams();
        }

        /***************************************************************************/
        // region   Methods to implement
        /** @name   Methods to implement */

        /**
         * Get the cache mode for the data generated by this module. Override
         * this in the module subclass. For possible return values and other
         * details about cache modes, see ApiMain::setCacheMode()
         *
         * Public caching will only be allowed if *all* the modules that supply
         * data for a given request return a cache mode of public.
         *
         * @stable to override
         * @param array $params
         * @return string
         */
        public function getCacheMode( $params ) {
                return 'private';
        }

        /**
         * Override this method to request extra fields from the pageSet
         * using $pageSet->requestField('fieldName')
         *
         * Note this only makes sense for 'prop' modules, as 'list' and 'meta'
         * modules should not be using the pageset.
         *
         * @stable to override
         * @param ApiPageSet $pageSet
         */
        public function requestExtraData( $pageSet ) {
        }

        // endregion -- end of methods to implement

        /***************************************************************************/
        // region   Data access
        /** @name   Data access */

        /**
         * Get the main Query module
         * @return ApiQuery
         */
        public function getQuery() {
                return $this->mQueryModule;
        }

        /** @inheritDoc */
        public function getParent() {
                return $this->getQuery();
        }

        /**
         * Get the Query database connection (read-only)
         * @stable to override
         * @return IReadableDatabase
         */
        protected function getDB() {
                $this->mDb ??= $this->getQuery()->getDB();

                return $this->mDb;
        }

        /**
         * Get the PageSet object to work on
         * @stable to override
         * @return ApiPageSet
         */
        protected function getPageSet() {
                return $this->getQuery()->getPageSet();
        }

        // endregion -- end of data access

        /***************************************************************************/
        // region   Querying
        /** @name   Querying */

        /**
         * Blank the internal arrays with query parameters
         */
        protected function resetQueryParams() {
                $this->queryBuilder = null;
        }

        /**
         * Get the SelectQueryBuilder.
         *
         * This is lazy initialised since getDB() fails in ApiQueryAllImages if it
         * is called before the constructor completes.
         *
         * @return SelectQueryBuilder
         */
        protected function getQueryBuilder() {
                $this->queryBuilder ??= $this->getDB()->newSelectQueryBuilder();
                return $this->queryBuilder;
        }

        /**
         * Add a set of tables to the internal array
         * @param string|array $tables Table name or array of table names
         *  or nested arrays for joins using parentheses for grouping
         * @param string|null $alias Table alias, or null for no alias. Cannot be
         *  used with multiple tables
         */
        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 );
                }
        }

        /**
         * Add a set of JOIN conditions to the internal array
         *
         * JOIN conditions are formatted as [ tablename => [ jointype, conditions ] ]
         * e.g. [ 'page' => [ 'LEFT JOIN', 'page_id=rev_page' ] ].
         * Conditions may be a string or an addWhere()-style array.
         * @param array $join_conds JOIN conditions
         */
        protected function addJoinConds( $join_conds ) {
                if ( !is_array( $join_conds ) ) {
                        ApiBase::dieDebug( __METHOD__, 'Join conditions have to be arrays' );
                }
                $this->getQueryBuilder()->joinConds( $join_conds );
        }

        /**
         * Add a set of fields to select to the internal array
         * @param array|string $value Field name or array of field names
         */
        protected function addFields( $value ) {
                $this->getQueryBuilder()->fields( $value );
        }

        /**
         * Same as addFields(), but add the fields only if a condition is met
         * @param array|string $value See addFields()
         * @param bool $condition If false, do nothing
         * @return bool
         */
        protected function addFieldsIf( $value, $condition ) {
                if ( $condition ) {
                        $this->addFields( $value );

                        return true;
                }

                return false;
        }

        /**
         * Add a set of WHERE clauses to the internal array.
         *
         * The array should be appropriate for passing as $conds to
         * IDatabase::select(). Arrays from multiple calls are merged with
         * array_merge(). A string is treated as a single-element array.
         *
         * When passing `'field' => $arrayOfIDs` where the IDs are taken from user
         * input, consider using addWhereIDsFld() instead.
         *
         * @see IDatabase::select()
         * @param string|array|IExpression $value
         */
        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 );
                }
        }

        /**
         * Same as addWhere(), but add the WHERE clauses only if a condition is met
         * @param string|array|IExpression $value
         * @param bool $condition If false, do nothing
         * @return bool
         */
        protected function addWhereIf( $value, $condition ) {
                if ( $condition ) {
                        $this->addWhere( $value );

                        return true;
                }

                return false;
        }

        /**
         * Equivalent to addWhere( [ $field => $value ] )
         *
         * When $value is an array of integer IDs taken from user input,
         * consider using addWhereIDsFld() instead.
         *
         * @param string $field Field name
         * @param int|string|(string|int|null)[] $value Value; ignored if null or empty array
         */
        protected function addWhereFld( $field, $value ) {
                if ( $value !== null && !( is_array( $value ) && !$value ) ) {
                        $this->getQueryBuilder()->where( [ $field => $value ] );
                }
        }

        /**
         * Like addWhereFld for an integer list of IDs
         *
         * When passed wildly out-of-range values for integer comparison,
         * the database may choose a poor query plan. This method validates the
         * passed IDs against the range of values in the database to omit
         * out-of-range values.
         *
         * This should be used when the IDs are derived from arbitrary user input;
         * it is not necessary if the IDs are already known to be within a sensible
         * range.
         *
         * This should not be used when there is not a suitable index on $field to
         * quickly retrieve the minimum and maximum values.
         *
         * @since 1.33
         * @param string $table Table name
         * @param string $field Field name
         * @param int[] $ids
         * @return int Count of IDs actually included
         */
        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 );
        }

        /**
         * Add a WHERE clause corresponding to a range, and an ORDER BY
         * clause to sort in the right direction
         * @param string $field Field name
         * @param string $dir If 'newer', sort in ascending order, otherwise
         *  sort in descending order
         * @param string|int|null $start Value to start the list at. If $dir == 'newer'
         *  this is the lower boundary, otherwise it's the upper boundary
         * @param string|int|null $end Value to end the list at. If $dir == 'newer' this
         *  is the upper boundary, otherwise it's the lower boundary
         * @param bool $sort If false, don't add an ORDER BY clause
         */
        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' );
                }
        }

        /**
         * Add a WHERE clause corresponding to a range, similar to addWhereRange,
         * but converts $start and $end to database timestamps.
         * @see addWhereRange
         * @param string $field
         * @param string $dir
         * @param string|int|null $start
         * @param string|int|null $end
         * @param bool $sort
         */
        protected function addTimestampWhereRange( $field, $dir, $start, $end, $sort = true ) {
                $db = $this->getDB();
                $this->addWhereRange( $field, $dir,
                        $db->timestampOrNull( $start ), $db->timestampOrNull( $end ), $sort );
        }

        /**
         * Add an option such as LIMIT or USE INDEX. If an option was set
         * before, the old value will be overwritten
         * @param string $name Option name
         * @param mixed $value The option value, or null for a boolean option
         */
        protected function addOption( $name, $value = null ) {
                $this->getQueryBuilder()->option( $name, $value );
        }

        /**
         * Execute a SELECT query based on the values in the internal arrays
         * @param string $method Function the query should be attributed to.
         *  You should usually use __METHOD__ here
         * @param array $extraQuery Query data to add but not store in the object
         *  Format is [
         *    'tables' => ...,
         *    'fields' => ...,
         *    'where' => ...,
         *    'options' => ...,
         *    'join_conds' => ...
         *  ]
         * @param array|null &$hookData If set, the ApiQueryBaseBeforeQuery and
         *  ApiQueryBaseAfterQuery hooks will be called, and the
         *  ApiQueryBaseProcessRow hook will be expected.
         * @return IResultWrapper
         */
        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;
        }

        /**
         * Call the ApiQueryBaseProcessRow hook
         *
         * Generally, a module that passed $hookData to self::select() will call
         * this just before calling ApiResult::addValue(), and treat a false return
         * here in the same way it treats a false return from addValue().
         *
         * @since 1.28
         * @param stdClass $row Database row
         * @param array &$data Data to be added to the result
         * @param array &$hookData Hook data from ApiQueryBase::select() @phan-output-reference
         * @return bool Return false if row processing should end with continuation
         */
        protected function processRow( $row, array &$data, array &$hookData ) {
                return $this->getHookRunner()->onApiQueryBaseProcessRow( $this, $row, $data, $hookData );
        }

        // endregion -- end of querying

        /***************************************************************************/
        // region   Utility methods
        /** @name   Utility methods */

        /**
         * Add information (title and namespace) about a Title object to a
         * result array
         * @param array &$arr Result array à la ApiResult
         * @param Title $title
         * @param string $prefix Module prefix
         */
        public static function addTitleInfo( &$arr, $title, $prefix = '' ) {
                $arr[$prefix . 'ns'] = $title->getNamespace();
                $arr[$prefix . 'title'] = $title->getPrefixedText();
        }

        /**
         * Add a sub-element under the page element with the given page ID
         * @param int $pageId
         * @param array $data Data array à la ApiResult
         * @return bool Whether the element fit in the result
         */
        protected function addPageSubItems( $pageId, $data ) {
                $result = $this->getResult();
                ApiResult::setIndexedTagName( $data, $this->getModulePrefix() );

                return $result->addValue( [ 'query', 'pages', (int)$pageId ],
                        $this->getModuleName(),
                        $data );
        }

        /**
         * Same as addPageSubItems(), but one element of $data at a time
         * @param int $pageId
         * @param mixed $item Data à la ApiResult
         * @param string|null $elemname XML element name. If null, getModuleName()
         *  is used
         * @return bool Whether the element fit in the result
         */
        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;
        }

        /**
         * Set a query-continue value
         * @param string $paramName Parameter name
         * @param int|string|array $paramValue Parameter value
         */
        protected function setContinueEnumParameter( $paramName, $paramValue ) {
                $this->getContinuationManager()->addContinueParam( $this, $paramName, $paramValue );
        }

        /**
         * Convert an input title or title prefix into a dbkey.
         *
         * $namespace should always be specified in order to handle per-namespace
         * capitalization settings.
         *
         * @param string $titlePart
         * @param int $namespace Namespace of the title
         * @return string DBkey (no namespace prefix)
         */
        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 );
        }

        /**
         * Convert an input title or title prefix into a TitleValue.
         *
         * @since 1.35
         * @param string $titlePart
         * @param int $defaultNamespace Default namespace if none is given
         * @return TitleValue
         */
        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 ) );
        }

        /**
         * @param string $hash
         * @return bool
         */
        public function validateSha1Hash( $hash ) {
                return (bool)preg_match( '/^[a-f0-9]{40}$/', $hash );
        }

        /**
         * @param string $hash
         * @return bool
         */
        public function validateSha1Base36Hash( $hash ) {
                return (bool)preg_match( '/^[a-z0-9]{31}$/', $hash );
        }

        /**
         * Check whether the current user has permission to view revision-deleted
         * fields.
         * @return bool
         */
        public function userCanSeeRevDel() {
                return $this->getAuthority()->isAllowedAny(
                        'deletedhistory',
                        'deletedtext',
                        'deleterevision',
                        'suppressrevision',
                        'viewsuppressed'
                );
        }

        /**
         * Preprocess the result set to fill the GenderCache with the necessary information
         * before using self::addTitleInfo
         *
         * @param IResultWrapper $res Result set to work on.
         *  The result set must have _namespace and _title fields with the provided field prefix
         * @param string $fname The caller function name, always use __METHOD__ @phan-mandatory-param
         * @param string $fieldPrefix Prefix for fields to check gender for
         */
        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
}

/** @deprecated class alias since 1.43 */
class_alias( ApiQueryBase::class, 'ApiQueryBase' );