SelectQueryBuilder.php

Go to the documentation of this file.

<?php
 
namespace Wikimedia\Rdbms;
 
use Wikimedia\Rdbms\Platform\ISQLPlatform;
 
class SelectQueryBuilder extends JoinGroupBase {
 
    public const SORT_ASC = 'ASC';
 
    public const SORT_DESC = 'DESC';
 
    private $fields = [];
 
    private $aliasesUsed = [];
 
    private $conds = [];
 
    private $caller = __CLASS__;
 
    protected $options = [];
 
    private $nextAutoAlias = 1;
 
    private $isCallerOverridden = false;
 
    protected IReadableDatabase $db;
 
    public function __construct( IReadableDatabase $db ) {
        $this->db = $db;
    }
 
    public function connection( IReadableDatabase $db ) {
        if ( $this->db->getType() !== $db->getType() ) {
            throw new \InvalidArgumentException( __METHOD__ .
                ' cannot switch to a database of a different type.' );
        }
        $this->db = $db;
        return $this;
    }
 
    public function queryInfo( $info ) {
        if ( isset( $info['tables'] ) ) {
            $this->rawTables( $info['tables'] );
        }
        if ( isset( $info['fields'] ) ) {
            $this->fields( $info['fields'] );
        }
        if ( isset( $info['conds'] ) ) {
            $this->where( $info['conds'] );
        }
        if ( isset( $info['options'] ) ) {
            $this->options( (array)$info['options'] );
        }
        if ( isset( $info['join_conds'] ) ) {
            $this->joinConds( (array)$info['join_conds'] );
        }
        if ( isset( $info['joins'] ) ) {
            $this->joinConds( (array)$info['joins'] );
        }
        if ( isset( $info['caller'] ) ) {
            $this->caller( $info['caller'] );
        }
        return $this;
    }
 
    public function rawTables( $tables ) {
        if ( is_array( $tables ) ) {
            $this->tables = array_merge( $this->tables, $tables );
        } elseif ( is_string( $tables ) ) {
            $this->tables[] = $tables;
        } else {
            throw new \InvalidArgumentException( __METHOD__ .
                ': $tables must be a string or array' );
        }
        return $this;
    }
 
    public function merge( SelectQueryBuilder $builder ) {
        $this->rawTables( $builder->tables );
        $this->fields( $builder->fields );
        $this->where( $builder->conds );
        $this->options( $builder->options );
        $this->joinConds( $builder->joinConds );
        if ( $builder->isCallerOverridden ) {
            $this->caller( $builder->caller );
        }
        return $this;
    }
 
    public function newSubquery() {
        return new self( $this->db );
    }
 
    public function from( $table, $alias = null ) {
        return $this->table( $table, $alias );
    }
 
    public function tables( $tables ) {
        foreach ( $tables as $alias => $table ) {
            if ( is_string( $alias ) ) {
                $this->table( $table, $alias );
            } else {
                $this->table( $table );
            }
        }
        return $this;
    }
 
    public function fields( $fields ) {
        if ( !is_array( $fields ) ) {
            return $this->field( $fields );
        }
 
        foreach ( $fields as $alias => $field ) {
            $this->field( $field, is_numeric( $alias ) ? null : $alias );
        }
 
        return $this;
    }
 
    public function select( $fields ) {
        return $this->fields( $fields );
    }
 
    public function field( $field, $alias = null ) {
        $usedAlias = $alias ?? $field;
        if ( isset( $this->aliasesUsed[$usedAlias] ) ) {
            if ( $this->aliasesUsed[$usedAlias] !== $field ) {
                throw new \LogicException( __METHOD__ .
                    ": field alias \"$usedAlias\" is already used for a different field" );
            }
            // Identical field/alias combination was already added, don't add it again
            return $this;
        }
        $this->aliasesUsed[$usedAlias] = $field;
 
        if ( $alias === null ) {
            $this->fields[] = $field;
        } else {
            $this->fields[$alias] = $field;
        }
        return $this;
    }
 
    public function clearFields() {
        $this->fields = [];
        $this->aliasesUsed = [];
        return $this;
    }
 
    public function where( $conds ) {
        if ( is_array( $conds ) ) {
            foreach ( $conds as $key => $cond ) {
                if ( is_int( $key ) ) {
                    $this->conds[] = $cond;
                } elseif ( isset( $this->conds[$key] ) ) {
                    // @phan-suppress-previous-line PhanTypeMismatchDimFetch
                    // T288882
                    $this->conds[] = $this->db->makeList(
                        [ $key => $cond ], IReadableDatabase::LIST_AND );
                } else {
                    $this->conds[$key] = $cond;
                }
            }
        } else {
            $this->conds[] = $conds;
        }
        return $this;
    }
 
    public function andWhere( $conds ) {
        return $this->where( $conds );
    }
 
    public function conds( $conds ) {
        return $this->where( $conds );
    }
 
    public function joinConds( array $joinConds ) {
        $this->joinConds = array_merge( $this->joinConds, $joinConds );
        return $this;
    }
 
    protected function getAutoAlias() {
        return 'sqb' . ( $this->nextAutoAlias++ );
    }
 
    public function newJoinGroup() {
        return new JoinGroup( $this->getAutoAlias() );
    }
 
    public function offset( $offset ) {
        $this->options['OFFSET'] = $offset;
        return $this;
    }
 
    public function limit( $limit ) {
        $this->options['LIMIT'] = $limit;
        return $this;
    }
 
    public function lockInShareMode() {
        $this->options[] = 'LOCK IN SHARE MODE';
        return $this;
    }
 
    public function forUpdate() {
        $this->options[] = 'FOR UPDATE';
        return $this;
    }
 
    public function distinct() {
        $this->options[] = 'DISTINCT';
        return $this;
    }
 
    public function setMaxExecutionTime( int $time ) {
        $this->options['MAX_EXECUTION_TIME'] = $time;
        return $this;
    }
 
    public function groupBy( $group ) {
        $this->mergeOption( 'GROUP BY', $group );
        return $this;
    }
 
    public function having( $having ) {
        $this->mergeOption( 'HAVING', $having );
        return $this;
    }
 
    public function orderBy( $fields, $direction = null ) {
        if ( $direction === null ) {
            $this->mergeOption( 'ORDER BY', $fields );
        } elseif ( is_array( $fields ) ) {
            $fieldsWithDirection = [];
            foreach ( $fields as $field ) {
                $fieldsWithDirection[] = "$field $direction";
            }
            $this->mergeOption( 'ORDER BY', $fieldsWithDirection );
        } else {
            $this->mergeOption( 'ORDER BY', "$fields $direction" );
        }
        return $this;
    }
 
    private function mergeOption( $name, $newArrayOrValue ) {
        $value = isset( $this->options[$name] )
            ? (array)$this->options[$name] : [];
        if ( is_array( $newArrayOrValue ) ) {
            $value = array_merge( $value, $newArrayOrValue );
        } else {
            $value[] = $newArrayOrValue;
        }
        $this->options[$name] = $value;
    }
 
    public function useIndex( $index ) {
        $this->setIndexHint( 'USE INDEX', $index );
        return $this;
    }
 
    public function ignoreIndex( $index ) {
        $this->setIndexHint( 'IGNORE INDEX', $index );
        return $this;
    }
 
    private function setIndexHint( $type, $value ) {
        if ( !isset( $this->options[$type] ) ) {
            $this->options[$type] = [];
        } elseif ( !is_array( $this->options[$type] ) ) {
            throw new \UnexpectedValueException(
                __METHOD__ . ": The $type option cannot be appended to " .
                'because it is not an array. This may have been caused by a prior ' .
                'call to option() or options().' );
        }
        if ( is_array( $value ) ) {
            $this->options[$type] = array_merge( $this->options[$type], $value );
        } elseif ( $this->lastAlias === null ) {
            throw new \UnexpectedValueException(
                __METHOD__ . ': Cannot append index value since there is no' .
                'prior table' );
        } else {
            $this->options[$type][$this->lastAlias] = $value;
        }
    }
 
    public function explain() {
        $this->options['EXPLAIN'] = true;
        return $this;
    }
 
    public function straightJoinOption() {
        $this->options[] = 'STRAIGHT_JOIN';
        return $this;
    }
 
    public function bigResult() {
        $this->options[] = 'SQL_BIG_RESULT';
        return $this;
    }
 
    public function bufferResult() {
        $this->options[] = 'SQL_BUFFER_RESULT';
        return $this;
    }
 
    public function smallResult() {
        $this->options[] = 'SQL_SMALL_RESULT';
        return $this;
    }
 
    public function calcFoundRows() {
        $this->options[] = 'SQL_CALC_FOUND_ROWS';
        return $this;
    }
 
    public function option( $name, $value = null ) {
        if ( $value === null ) {
            $this->options[] = $name;
        } else {
            $this->options[$name] = $value;
        }
        return $this;
    }
 
    public function options( array $options ) {
        $this->options = array_merge( $this->options, $options );
        return $this;
    }
 
    public function recency( $recency ) {
        if ( ( $recency & IDBAccessObject::READ_EXCLUSIVE ) == IDBAccessObject::READ_EXCLUSIVE ) {
            $this->forUpdate();
        } elseif ( ( $recency & IDBAccessObject::READ_LOCKING ) == IDBAccessObject::READ_LOCKING ) {
            $this->lockInShareMode();
        }
        return $this;
    }
 
    public function caller( $fname ) {
        $this->caller = $fname;
        $this->isCallerOverridden = true;
        return $this;
    }
 
    final protected function getCaller(): string {
        return $this->caller;
    }
 
    public function fetchResultSet(): IResultWrapper {
        return $this->db->select( $this->tables, $this->fields, $this->conds, $this->caller,
            $this->options, $this->joinConds );
    }
 
    public function fetchField() {
        if ( count( $this->fields ) !== 1 ) {
            throw new \UnexpectedValueException(
                __METHOD__ . ' expects the query to have only one field' );
        }
        $field = reset( $this->fields );
        return $this->db->selectField( $this->tables, $field, $this->conds, $this->caller,
            $this->options, $this->joinConds );
    }
 
    public function fetchFieldValues(): array {
        if ( count( $this->fields ) !== 1 ) {
            throw new \UnexpectedValueException(
                __METHOD__ . ' expects the query to have only one field' );
        }
        $field = reset( $this->fields );
        return $this->db->selectFieldValues( $this->tables, $field, $this->conds, $this->caller,
            $this->options, $this->joinConds );
    }
 
    public function fetchRow() {
        return $this->db->selectRow( $this->tables, $this->fields, $this->conds, $this->caller,
            $this->options, $this->joinConds );
    }
 
    public function fetchRowCount(): int {
        return $this->db->selectRowCount( $this->tables, $this->getRowCountVar(), $this->conds,
            $this->caller, $this->options, $this->joinConds );
    }
 
    public function estimateRowCount(): int {
        return $this->db->estimateRowCount( $this->tables, $this->getRowCountVar(), $this->conds,
            $this->caller, $this->options, $this->joinConds );
    }
 
    private function getRowCountVar() {
        if ( count( $this->fields ) === 0 ) {
            return '*';
        } elseif ( count( $this->fields ) === 1 ) {
            return reset( $this->fields );
        } else {
            throw new \UnexpectedValueException(
                __METHOD__ . ' expects the query to have at most one field' );
        }
    }
 
    public function buildGroupConcatField( $delim ) {
        if ( count( $this->fields ) !== 1 ) {
            throw new \UnexpectedValueException(
                __METHOD__ . ' expects the query to have only one field' );
        }
        $field = reset( $this->fields );
        return $this->db->buildGroupConcatField( $delim, $this->tables, $field,
            $this->conds, $this->joinConds );
    }
 
    public function getSQL() {
        // Assume that whoever is calling this method is doing it to build a subquery
        $caller = $this->isCallerOverridden ? $this->caller : ISQLPlatform::CALLER_SUBQUERY;
        return $this->db->selectSQLText( $this->tables, $this->fields, $this->conds, $caller,
            $this->options, $this->joinConds );
    }
 
    public function getQueryInfo( $joinsName = 'join_conds' ) {
        $info = [
            'tables' => $this->tables,
            'fields' => $this->fields,
            'conds' => $this->conds,
            'options' => $this->options,
        ];
        if ( $this->caller !== __CLASS__ ) {
            $info['caller'] = $this->caller;
        }
        $info[ $joinsName ] = $this->joinConds;
        return $info;
    }
 
    public function acquireRowLocks(): void {
        if ( !array_intersect( $this->options, [ 'FOR UPDATE', 'LOCK IN SHARE MODE' ] ) ) {
            throw new \UnexpectedValueException( __METHOD__ . ' can only be called ' .
                'after forUpdate() or lockInShareMode()' );
        }
        $fields = $this->fields ?: '1';
        $this->db->select( $this->tables, $fields, $this->conds, $this->caller,
            $this->options, $this->joinConds );
    }
}