gplx/mediawiki/includes/libs/rdbms/querybuilder/UnionQueryBuilder.php

<?php

namespace Wikimedia\Rdbms;

use Wikimedia\Rdbms\Platform\ISQLPlatform;

/**
 * A query builder for UNION queries takes SelectQueryBuilder objects
 *
 * Any particular query builder object should only be used for a single database query,
 * and not be reused afterwards.
 *
 * @since 1.41
 * @ingroup Database
 */
class UnionQueryBuilder {
	/** sort the results in ascending order */
	public const SORT_ASC = 'ASC';

	/** sort the results in descending order */
	public const SORT_DESC = 'DESC';

	/**
	 * @var SelectQueryBuilder[]
	 */
	private $sqbs = [];

	/** @var IDatabase */
	private $db;

	/** @var bool */
	private $all = IReadableDatabase::UNION_DISTINCT;

	/** @var array */
	private $options = [];

	/**
	 * @var string The caller (function name) to be passed to IDatabase::query()
	 */
	private $caller = __CLASS__;

	/**
	 * To create a UnionQueryBuilder instance, use `$db->newUnionQueryBuilder()` instead.
	 *
	 * @param IDatabase $db
	 */
	public function __construct( IDatabase $db ) {
		$this->db = $db;
	}

	/**
	 * Add a select query builder object to the list of union
	 *
	 * @return $this
	 */
	public function add( SelectQueryBuilder $selectQueryBuilder ) {
		$this->sqbs[] = $selectQueryBuilder;
		return $this;
	}

	/**
	 * Enable UNION_ALL option, the default is UNION_DISTINCT
	 *
	 * @return $this
	 */
	public function all() {
		$this->all = $this->db::UNION_ALL;
		return $this;
	}

	/**
	 * Set the query limit. Return at most this many rows. The rows are sorted
	 * and then the first rows are taken until the limit is reached. Limit
	 * is applied to a result set after offset.
	 *
	 * If the query builder already has a limit, the old limit will be discarded.
	 * This would be also ignored if the DB does not support limit in union queries.
	 *
	 * @param int $limit
	 * @return $this
	 */
	public function limit( $limit ) {
		if ( !$this->db->unionSupportsOrderAndLimit() ) {
			return $this;
		}
		$this->options['LIMIT'] = $limit;
		return $this;
	}

	/**
	 * Set the offset. Skip this many rows at the start of the result set. Offset
	 * with limit() can theoretically be used for paging through a result set,
	 * but this is discouraged for performance reasons.
	 *
	 * If the query builder already has an offset, the old offset will be discarded.
	 * This would be also ignored if the DB does not support offset in union queries.
	 *
	 * @param int $offset
	 * @return $this
	 */
	public function offset( $offset ) {
		if ( !$this->db->unionSupportsOrderAndLimit() ) {
			return $this;
		}
		$this->options['OFFSET'] = $offset;
		return $this;
	}

	/**
	 * Set the ORDER BY clause. If it has already been set, append the
	 * additional fields to it.
	 *
	 * This would be ignored if the DB does not support order by in union queries.
	 *
	 * @param string[]|string $fields The field or list of fields to order by.
	 * @param-taint $fields exec_sql
	 * @param string|null $direction self::SORT_ASC or self::SORT_DESC.
	 * If this is null then $fields is assumed to optionally contain ASC or DESC
	 * after each field name.
	 * @param-taint $direction exec_sql
	 * @return $this
	 */
	public function orderBy( $fields, $direction = null ) {
		if ( !$this->db->unionSupportsOrderAndLimit() ) {
			return $this;
		}
		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;
	}

	/**
	 * Add a value to an option which may be not set or a string or array.
	 *
	 * @param string $name
	 * @param string|string[] $newArrayOrValue
	 */
	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;
	}

	/**
	 * Set the method name to be included in an SQL comment.
	 *
	 * @param string $fname
	 * @param-taint $fname exec_sql
	 * @return $this
	 */
	public function caller( $fname ) {
		$this->caller = $fname;
		return $this;
	}

	/**
	 * Run the constructed UNION query and return all results.
	 *
	 * @return IResultWrapper
	 */
	public function fetchResultSet() {
		$query = new Query( $this->getSQL(), ISQLPlatform::QUERY_CHANGE_NONE, 'SELECT' );
		return $this->db->query( $query, $this->caller );
	}

	/**
	 * Run the constructed UNION query, and return a single field extracted
	 * from the first result row. If there were no result rows, false is
	 * returned. This may only be called when only one field has been added to
	 * the constituent queries.
	 *
	 * @since 1.42
	 * @return mixed
	 * @return-taint tainted
	 */
	public function fetchField() {
		$this->limit( 1 );
		foreach ( $this->fetchResultSet() as $row ) {
			$row = (array)$row;
			if ( count( $row ) !== 1 ) {
				throw new \UnexpectedValueException(
					__METHOD__ . ' expects the query to have only one field' );
			}
			return $row[ array_key_first( $row ) ];
		}
		return false;
	}

	/**
	 * Run the constructed UNION query, and extract a single field from each
	 * result row, returning an array containing all the values. This may only
	 * be called when only one field has been added to the constituent queries.
	 *
	 * @since 1.42
	 * @return array
	 * @return-taint tainted
	 */
	public function fetchFieldValues() {
		$values = [];
		foreach ( $this->fetchResultSet() as $row ) {
			$row = (array)$row;
			if ( count( $row ) !== 1 ) {
				throw new \UnexpectedValueException(
					__METHOD__ . ' expects the query to have only one field' );
			}
			$values[] = $row[ array_key_first( $row ) ];
		}
		return $values;
	}

	/**
	 * Run the constructed UNION query, and return the first result row. If
	 * there were no results, return false.
	 *
	 * @since 1.42
	 * @return \stdClass|false
	 * @return-taint tainted
	 */
	public function fetchRow() {
		$this->limit( 1 );
		foreach ( $this->fetchResultSet() as $row ) {
			return $row;
		}
		return false;
	}

	/**
	 * Get the SQL query string which would be used by fetchResultSet().
	 *
	 * @since 1.42
	 * @return string
	 */
	public function getSQL() {
		$sqls = [];
		foreach ( $this->sqbs as $sqb ) {
			$sqls[] = $sqb->getSQL();
		}
		return $this->db->unionQueries( $sqls, $this->all, $this->options );
	}

}