362 lines
10 KiB
PHP
362 lines
10 KiB
PHP
<?php
|
|
|
|
namespace Wikimedia\Rdbms;
|
|
|
|
use InvalidArgumentException;
|
|
use UnexpectedValueException;
|
|
|
|
// Very long type annotations :(
|
|
// phpcs:disable Generic.Files.LineLength
|
|
|
|
/**
|
|
* Build UPDATE queries with a fluent interface.
|
|
*
|
|
* Each query builder object must be used for a single database query only,
|
|
* and not be reused afterwards. To run multiple similar queries, you can
|
|
* create a query builder to set up most of your query, which you can use
|
|
* as a "template" to clone. You can then modify the cloned object for
|
|
* each individual query.
|
|
*
|
|
* @since 1.41
|
|
* @stable to extend
|
|
* @ingroup Database
|
|
*/
|
|
class UpdateQueryBuilder {
|
|
/**
|
|
* @var string The table name to be passed to IDatabase::update()
|
|
*/
|
|
private $table = '';
|
|
|
|
/**
|
|
* @var array The set values to be passed to IDatabase::update()
|
|
*/
|
|
private $set = [];
|
|
|
|
/**
|
|
* @var array The conditions to be passed to IDatabase::update()
|
|
*/
|
|
private $conds = [];
|
|
|
|
/**
|
|
* @var string The caller (function name) to be passed to IDatabase::update()
|
|
*/
|
|
private $caller = __CLASS__;
|
|
|
|
/**
|
|
* @var array The options to be passed to IDatabase::update()
|
|
*/
|
|
protected $options = [];
|
|
|
|
/** @var IDatabase */
|
|
protected $db;
|
|
|
|
/**
|
|
* Only for use in subclasses. To create a UpdateQueryBuilder instance,
|
|
* use `$db->newUpdateQueryBuilder()` instead.
|
|
*
|
|
* @param IDatabase $db
|
|
*/
|
|
public function __construct( IDatabase $db ) {
|
|
$this->db = $db;
|
|
}
|
|
|
|
/**
|
|
* Change the IDatabase object the query builder is bound to. The specified
|
|
* IDatabase will subsequently be used to execute the query.
|
|
*
|
|
* @param IDatabase $db
|
|
* @return $this
|
|
*/
|
|
public function connection( IDatabase $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;
|
|
}
|
|
|
|
/**
|
|
* Set the query parameters to the given values, appending to the values
|
|
* which were already set. This can be used to interface with legacy code.
|
|
* If a key is omitted, the previous value will be retained.
|
|
*
|
|
* The parameters must be formatted as required by Database::update.
|
|
*
|
|
* @param array $info Associative array of query info, with keys:
|
|
* - table: The table name to be passed to Database::update()
|
|
* - set: The set conditions
|
|
* - conds: The conditions
|
|
* - options: The query options
|
|
* - caller: The caller signature.
|
|
*
|
|
* @return $this
|
|
*/
|
|
public function queryInfo( $info ) {
|
|
if ( isset( $info['table'] ) ) {
|
|
$this->table( $info['table'] );
|
|
}
|
|
if ( isset( $info['set'] ) ) {
|
|
$this->set( $info['set'] );
|
|
}
|
|
if ( isset( $info['conds'] ) ) {
|
|
$this->where( $info['conds'] );
|
|
}
|
|
if ( isset( $info['options'] ) ) {
|
|
$this->options( (array)$info['options'] );
|
|
}
|
|
if ( isset( $info['caller'] ) ) {
|
|
$this->caller( $info['caller'] );
|
|
}
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Manually set the table name to be passed to IDatabase::update()
|
|
*
|
|
* @param string $table The unqualified name of a table
|
|
* @param-taint $table exec_sql
|
|
* @return $this
|
|
*/
|
|
public function table( $table ) {
|
|
$this->table = $table;
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Set table for the query. Alias for table().
|
|
*
|
|
* @param string $table The unqualified name of a table
|
|
* @param-taint $table exec_sql
|
|
* @return $this
|
|
*/
|
|
public function update( string $table ) {
|
|
return $this->table( $table );
|
|
}
|
|
|
|
/**
|
|
* Manually set an option in the $options array to be passed to
|
|
* IDatabase::update()
|
|
*
|
|
* @param string $name The option name
|
|
* @param mixed $value The option value, or null for a boolean option
|
|
* @return $this
|
|
*/
|
|
public function option( $name, $value = null ) {
|
|
if ( $value === null ) {
|
|
$this->options[] = $name;
|
|
} else {
|
|
$this->options[$name] = $value;
|
|
}
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Manually set multiple options in the $options array to be passed to
|
|
* IDatabase::update().
|
|
*
|
|
* @param array $options
|
|
* @return $this
|
|
*/
|
|
public function options( array $options ) {
|
|
$this->options = array_merge( $this->options, $options );
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Add conditions to the query. The supplied conditions will be appended
|
|
* to the existing conditions, separated by AND.
|
|
*
|
|
* @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds
|
|
* @param-taint $conds exec_sql_numkey
|
|
*
|
|
* May be either a string containing a single condition, or an array of
|
|
* conditions. If an array is given, the conditions constructed from each
|
|
* element are combined with AND.
|
|
*
|
|
* Array elements may take one of two forms:
|
|
*
|
|
* - Elements with a numeric key are interpreted as raw SQL fragments.
|
|
* - Elements with a string key are interpreted as equality conditions,
|
|
* where the key is the field name.
|
|
* - If the value of such an array element is a scalar (such as a
|
|
* string), it will be treated as data and thus quoted appropriately.
|
|
* If it is null, an IS NULL clause will be added.
|
|
* - If the value is an array, an IN (...) clause will be constructed
|
|
* from its non-null elements, and an IS NULL clause will be added
|
|
* if null is present, such that the field may match any of the
|
|
* elements in the array. The non-null elements will be quoted.
|
|
*
|
|
* Note that expressions are often DBMS-dependent in their syntax.
|
|
* DBMS-independent wrappers are provided for constructing several types of
|
|
* expression commonly used in condition queries. See:
|
|
* - IDatabase::buildLike()
|
|
* - IDatabase::conditional()
|
|
*
|
|
* Untrusted user input is safe in the values of string keys, however untrusted
|
|
* input must not be used in the array key names or in the values of numeric keys.
|
|
* Escaping of untrusted input used in values of numeric keys should be done via
|
|
* IDatabase::addQuotes()
|
|
*
|
|
* @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 ], IDatabase::LIST_AND );
|
|
} else {
|
|
$this->conds[$key] = $cond;
|
|
}
|
|
}
|
|
} else {
|
|
$this->conds[] = $conds;
|
|
}
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Add conditions to the query. Alias for where().
|
|
*
|
|
* @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds
|
|
* @param-taint $conds exec_sql_numkey
|
|
* @return $this
|
|
*/
|
|
public function andWhere( $conds ) {
|
|
return $this->where( $conds );
|
|
}
|
|
|
|
/**
|
|
* Add conditions to the query. Alias for where().
|
|
*
|
|
* @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds
|
|
* @param-taint $conds exec_sql_numkey
|
|
* @return $this
|
|
*/
|
|
public function conds( $conds ) {
|
|
return $this->where( $conds );
|
|
}
|
|
|
|
/**
|
|
* Add SET part to the query. It takes an array containing arrays of column names map to
|
|
* the set values.
|
|
*
|
|
* @param string|array<string,?scalar|RawSQLValue>|array<int,string> $set
|
|
* @param-taint $set exec_sql_numkey
|
|
*
|
|
* Combination map/list where each string-keyed entry maps a column
|
|
* to a literal assigned value and each integer-keyed value is a SQL expression in the
|
|
* format of a column assignment within UPDATE...SET. The (column => value) entries are
|
|
* convenient due to automatic value quoting and conversion of null to NULL. The SQL
|
|
* assignment format is useful for updates like "column = column + X". All assignments
|
|
* have no defined execution order, so they should not depend on each other. Do not
|
|
* modify AUTOINCREMENT or UUID columns in assignments.
|
|
*
|
|
* Untrusted user input is safe in the values of string keys, however untrusted
|
|
* input must not be used in the array key names or in the values of numeric keys.
|
|
* Escaping of untrusted input used in values of numeric keys should be done via
|
|
* IDatabase::addQuotes()
|
|
*
|
|
* @return $this
|
|
*/
|
|
public function set( $set ) {
|
|
if ( is_array( $set ) ) {
|
|
foreach ( $set as $key => $value ) {
|
|
if ( is_int( $key ) ) {
|
|
$this->set[] = $value;
|
|
} else {
|
|
$this->set[$key] = $value;
|
|
}
|
|
}
|
|
} else {
|
|
$this->set[] = $set;
|
|
}
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* Add set values to the query. Alias for set().
|
|
*
|
|
* @param string|array<string,?scalar|RawSQLValue>|array<int,string> $set
|
|
* @param-taint $set exec_sql_numkey
|
|
* @return $this
|
|
*/
|
|
public function andSet( $set ) {
|
|
return $this->set( $set );
|
|
}
|
|
|
|
/**
|
|
* Enable the IGNORE option.
|
|
*
|
|
* Skip update of rows that would cause unique key conflicts.
|
|
* IDatabase::affectedRows() can be used to determine how many rows were updated.
|
|
*
|
|
* @return $this
|
|
*/
|
|
public function ignore() {
|
|
$this->options[] = 'IGNORE';
|
|
return $this;
|
|
}
|
|
|
|
/**
|
|
* 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 UPDATE query.
|
|
*/
|
|
public function execute(): void {
|
|
if ( !$this->conds ) {
|
|
throw new UnexpectedValueException(
|
|
__METHOD__ . ' expects at least one condition to be set' );
|
|
}
|
|
if ( !$this->set ) {
|
|
throw new UnexpectedValueException(
|
|
__METHOD__ . ' can\t have empty $set value' );
|
|
}
|
|
if ( $this->table === '' ) {
|
|
throw new UnexpectedValueException(
|
|
__METHOD__ . ' expects table not to be empty' );
|
|
}
|
|
$this->db->update( $this->table, $this->set, $this->conds, $this->caller, $this->options );
|
|
}
|
|
|
|
/**
|
|
* Get an associative array describing the query in terms of its raw parameters to
|
|
* Database::update(). This can be used to interface with legacy code.
|
|
*
|
|
* @return array The query info array, with keys:
|
|
* - table: The table name
|
|
* - set: The set array
|
|
* - conds: The conditions
|
|
* - options: The query options
|
|
* - caller: The caller signature
|
|
*/
|
|
public function getQueryInfo() {
|
|
$info = [
|
|
'table' => $this->table,
|
|
'set' => $this->set,
|
|
'conds' => $this->conds,
|
|
'options' => $this->options,
|
|
];
|
|
if ( $this->caller !== __CLASS__ ) {
|
|
$info['caller'] = $this->caller;
|
|
}
|
|
return $info;
|
|
}
|
|
}
|