Newer
Older
Dries Buytaert
committed
<?php
/**
* @ingroup database
* @{
*/
/**
* Interface for a conditional clause in a query.
*/
interface QueryConditionInterface {
/**
* Helper function to build most common conditional clauses.
*
Dries Buytaert
committed
* This method can take a variable number of parameters. If called with two
Dries Buytaert
committed
* parameters, they are taken as $field and $value with $operator having a value
* of =.
*
* @param $field
* The name of the field to check.
* @param $value
Dries Buytaert
committed
* The value to test the field against. In most cases, this is a scalar. For more
* complex options, it is an array. The meaning of each element in the array is
Dries Buytaert
committed
* dependent on the $operator.
* @param $operator
Dries Buytaert
committed
* The comparison operator, such as =, <, or >=. It also accepts more complex
Dries Buytaert
committed
* options such as IN, LIKE, or BETWEEN.
* @param $num_args
Dries Buytaert
committed
* For internal use only. This argument is used to track the recursive calls when
Dries Buytaert
committed
* processing complex conditions.
* @return
* The called object.
*/
public function condition($field, $value = NULL, $operator = NULL);
/**
* Add an arbitrary WHERE clause to the query.
*
* @param $snippet
Dries Buytaert
committed
* A portion of a WHERE clause as a prepared statement. It must use named placeholders,
Dries Buytaert
committed
* not ? placeholders.
* @param $args
* An associative array of arguments.
* @return
* The called object.
*/
public function where($snippet, $args = array());
/**
* Gets a complete list of all conditions in this conditional clause.
*
Dries Buytaert
committed
* This method returns by reference. That allows alter hooks to access the
Dries Buytaert
committed
* data structure directly and manipulate it before it gets compiled.
Angie Byron
committed
*
Dries Buytaert
committed
* The data structure that is returned is an indexed array of entries, where
* each entry looks like the following:
Angie Byron
committed
*
Dries Buytaert
committed
* array(
* 'field' => $field,
* 'value' => $value,
* 'operator' => $operator,
* );
Angie Byron
committed
*
Dries Buytaert
committed
* In the special case that $operator is NULL, the $field is taken as a raw
Angie Byron
committed
* SQL snippet (possibly containing a function) and $value is an associative
Dries Buytaert
committed
* array of placeholders for the snippet.
Angie Byron
committed
*
* There will also be a single array entry of #conjunction, which is the
Dries Buytaert
committed
* conjunction that will be applied to the array, such as AND.
*/
public function &conditions();
/**
* Gets a complete list of all values to insert into the prepared statement.
*
* @returns
* An associative array of placeholders and values.
*/
public function arguments();
Angie Byron
committed
Dries Buytaert
committed
/**
* Compiles the saved conditions for later retrieval.
*
* This method does not return anything, but simply prepares data to be
* retrieved via __toString() and arguments().
*
* @param $connection
* The database connection for which to compile the conditionals.
*/
public function compile(DatabaseConnection $connection);
}
/**
* Interface for a query that can be manipulated via an alter hook.
*/
interface QueryAlterableInterface {
Angie Byron
committed
Dries Buytaert
committed
/**
* Adds a tag to a query.
*
Dries Buytaert
committed
* Tags are strings that identify a query. A query may have any number of
* tags. Tags are used to mark a query so that alter hooks may decide if they
* wish to take action. Tags should be all lower-case and contain only letters,
* numbers, and underscore, and start with a letter. That is, they should
Dries Buytaert
committed
* follow the same rules as PHP identifiers in general.
*
* @param $tag
* The tag to add.
*/
public function addTag($tag);
Angie Byron
committed
Dries Buytaert
committed
/**
* Determines if a given query has a given tag.
*
* @param $tag
* The tag to check.
* @return
* TRUE if this query has been marked with this tag, FALSE otherwise.
*/
public function hasTag($tag);
Angie Byron
committed
Dries Buytaert
committed
/**
* Determines if a given query has all specified tags.
*
* @param $tags
* A variable number of arguments, one for each tag to check.
* @return
* TRUE if this query has been marked with all specified tags, FALSE otherwise.
*/
public function hasAllTags();
/**
* Determines if a given query has any specified tag.
*
* @param $tags
* A variable number of arguments, one for each tag to check.
* @return
* TRUE if this query has been marked with at least one of the specified
* tags, FALSE otherwise.
*/
public function hasAnyTag();
Angie Byron
committed
Dries Buytaert
committed
/**
* Adds additional metadata to the query.
*
* Often, a query may need to provide additional contextual data to alter
Dries Buytaert
committed
* hooks. Alter hooks may then use that information to decide if and how
Dries Buytaert
committed
* to take action.
*
* @param $key
Dries Buytaert
committed
* The unique identifier for this piece of metadata. Must be a string that
Dries Buytaert
committed
* follows the same rules as any other PHP identifier.
* @param $object
Dries Buytaert
committed
* The additional data to add to the query. May be any valid PHP variable.
Dries Buytaert
committed
*
*/
public function addMetaData($key, $object);
Angie Byron
committed
Dries Buytaert
committed
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
/**
* Retrieves a given piece of metadata.
*
* @param $key
* The unique identifier for the piece of metadata to retrieve.
* @return
* The previously attached metadata object, or NULL if one doesn't exist.
*/
public function getMetaData($key);
}
/**
* Base class for the query builders.
*
* All query builders inherit from a common base class.
*/
abstract class Query {
/**
* The connection object on which to run this query.
*
* @var DatabaseConnection
*/
protected $connection;
/**
* The query options to pass on to the connection object.
*
* @var array
*/
protected $queryOptions;
public function __construct(DatabaseConnection $connection, $options) {
$this->connection = $connection;
$this->queryOptions = $options;
}
/**
* Run the query against the database.
*/
abstract protected function execute();
/**
* Returns the query as a prepared statement string.
*/
Dries Buytaert
committed
abstract public function __toString();
Dries Buytaert
committed
}
/**
* General class for an abstracted INSERT operation.
*/
class InsertQuery extends Query {
/**
* The table on which to insert.
*
* @var string
*/
protected $table;
/**
Dries Buytaert
committed
* Whether or not this query is "delay-safe". Different database drivers
Dries Buytaert
committed
* may or may not implement this feature in their own ways.
*
* @var boolean
*/
protected $delay;
/**
* An array of fields on which to insert.
*
* @var array
*/
protected $insertFields = array();
/**
* An array of fields which should be set to their database-defined defaults.
*
* @var array
*/
protected $defaultFields = array();
/**
* A nested array of values to insert.
*
Dries Buytaert
committed
* $insertValues itself is an array of arrays. Each sub-array is an array of
* field names to values to insert. Whether multiple insert sets
Dries Buytaert
committed
* will be run in a single query or multiple queries is left to individual drivers
Dries Buytaert
committed
* to implement in whatever manner is most efficient. The order of values in each
Dries Buytaert
committed
* sub-array must match the order of fields in $insertFields.
*
* @var string
*/
protected $insertValues = array();
public function __construct($connection, $table, array $options = array()) {
Dries Buytaert
committed
$options['return'] = Database::RETURN_INSERT_ID;
$options += array('delay' => FALSE);
parent::__construct($connection, $options);
$this->table = $table;
}
/**
* Add a set of field->value pairs to be inserted.
*
Dries Buytaert
committed
* This method may only be called once. Calling it a second time will be
* ignored. To queue up multiple sets of values to be inserted at once,
Dries Buytaert
committed
* use the values() method.
*
* @param $fields
Dries Buytaert
committed
* An array of fields on which to insert. This array may be indexed or
* associative. If indexed, the array is taken to be the list of fields.
Dries Buytaert
committed
* If associative, the keys of the array are taken to be the fields and
Dries Buytaert
committed
* the values are taken to be corresponding values to insert. If a
Dries Buytaert
committed
* $values argument is provided, $fields must be indexed.
* @param $values
Dries Buytaert
committed
* An array of fields to insert into the database. The values must be
Dries Buytaert
committed
* specified in the same order as the $fields array.
* @return
* The called object.
*/
public function fields(array $fields, array $values = array()) {
Dries Buytaert
committed
if (empty($this->insertFields)) {
if (empty($values)) {
if (!is_numeric(key($fields))) {
$values = array_values($fields);
$fields = array_keys($fields);
}
}
$this->insertFields = $fields;
if (!empty($values)) {
$this->insertValues[] = $values;
}
}
return $this;
}
/**
* Add another set of values to the query to be inserted.
*
* If $values is a numeric array, it will be assumed to be in the same
Dries Buytaert
committed
* order as the original fields() call. If it is associative, it may be
Dries Buytaert
committed
* in any order as long as the keys of the array match the names of the
* fields.
*
* @param $values
* An array of values to add to the query.
* @return
* The called object.
*/
public function values(array $values) {
Dries Buytaert
committed
if (is_numeric(key($values))) {
$this->insertValues[] = $values;
}
else {
// Reorder the submitted values to match the fields array.
foreach ($this->insertFields as $key) {
$insert_values[$key] = $values[$key];
}
// For consistency, the values array is always numerically indexed.
$this->insertValues[] = array_values($insert_values);
}
return $this;
}
/**
* Specify fields for which the database-defaults should be used.
*
Angie Byron
committed
* If you want to force a given field to use the database-defined default,
Dries Buytaert
committed
* not NULL or undefined, use this method to instruct the database to use
Dries Buytaert
committed
* default values explicitly. In most cases this will not be necessary
Dries Buytaert
committed
* unless you are inserting a row that is all default values, as you cannot
* specify no values in an INSERT query.
Angie Byron
committed
*
Dries Buytaert
committed
* Specifying a field both in fields() and in useDefaults() is an error
* and will not execute.
Angie Byron
committed
*
Dries Buytaert
committed
* @param $fields
* An array of values for which to use the default values
* specified in the table definition.
* @return
* The called object.
*/
public function useDefaults(array $fields) {
Dries Buytaert
committed
$this->defaultFields = $fields;
return $this;
}
Angie Byron
committed
Dries Buytaert
committed
/**
* Flag this query as being delay-safe or not.
*
* If this method is never called, it is assumed that the query must be
Dries Buytaert
committed
* executed immediately. If delay is set to TRUE, then the query will be
Dries Buytaert
committed
* flagged to run "delayed" or "low priority" on databases that support such
Dries Buytaert
committed
* capabilities. In that case, the database will return immediately and the
* query will be run at some point in the future. That makes it useful for
Dries Buytaert
committed
* logging-style queries.
Angie Byron
committed
*
Dries Buytaert
committed
* If the database does not support delayed INSERT queries, this method
* has no effect.
Angie Byron
committed
*
* Note that for a delayed query there is no serial ID returned, as it won't
Dries Buytaert
committed
* be created until later when the query runs. It should therefore not be
* used if the value of the ID is known.
*
Dries Buytaert
committed
* @param $delay
* If TRUE, this query is delay-safe and will run delayed on supported databases.
* @return
* The called object.
*/
public function delay($delay = TRUE) {
$this->delay = $delay;
return $this;
}
/**
* Executes the insert query.
*
* @return
Dries Buytaert
committed
* The last insert ID of the query, if one exists. If the query
Dries Buytaert
committed
* was given multiple sets of values to insert, the return value is
Dries Buytaert
committed
* undefined. If the query is flagged "delayed", then the insert ID
* won't be created until later when the query actually runs so the
Dries Buytaert
committed
* return value is also undefined. If no fields are specified, this
* method will do nothing and return NULL. That makes it safe to use
* in multi-insert loops.
Dries Buytaert
committed
*/
public function execute() {
$last_insert_id = 0;
// Confirm that the user did not try to specify an identical
// field and default field.
if (array_intersect($this->insertFields, $this->defaultFields)) {
throw new PDOException('You may not specify the same field to have a value and a schema-default value.');
}
Angie Byron
committed
Dries Buytaert
committed
if (count($this->insertFields) + count($this->defaultFields) == 0) {
return NULL;
}
Dries Buytaert
committed
// Each insert happens in its own query in the degenerate case. However,
// we wrap it in a transaction so that it is atomic where possible. On many
Dries Buytaert
committed
// databases, such as SQLite, this is also a notable performance boost.
$transaction = $this->connection->startTransaction();
$sql = (string)$this;
foreach ($this->insertValues as $insert_values) {
$last_insert_id = $this->connection->query($sql, $insert_values, $this->queryOptions);
}
$transaction->commit();
// Re-initialize the values array so that we can re-use this query.
$this->insertValues = array();
return $last_insert_id;
}
public function __toString() {
Angie Byron
committed
Dries Buytaert
committed
// Default fields are always placed first for consistency.
$insert_fields = array_merge($this->defaultFields, $this->insertFields);
Angie Byron
committed
// For simplicity, we will use the $placeholders array to inject
Dries Buytaert
committed
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
// default keywords even though they are not, strictly speaking,
// placeholders for prepared statements.
$placeholders = array();
$placeholders = array_pad($placeholders, count($this->defaultFields), 'default');
$placeholders = array_pad($placeholders, count($this->insertFields), '?');
return 'INSERT INTO {'. $this->table .'} ('. implode(', ', $insert_fields) .') VALUES ('. implode(', ', $placeholders) .')';
}
}
/**
* General class for an abstracted MERGE operation.
*/
class MergeQuery extends Query {
/**
* The table on which to insert.
*
* @var string
*/
protected $table;
/**
* An array of fields on which to insert.
*
* @var array
*/
protected $insertFields = array();
/**
* An array of fields to update instead of the values specified in
* $insertFields;
*
* @var array
*/
protected $updateFields = array();
/**
* An array of key fields for this query.
*
* @var array
*/
protected $keyFields = array();
/**
* An array of fields to not update in case of a duplicate record.
*
* @var array
*/
protected $excludeFields = array();
/**
* An array of fields to update to an expression in case of a duplicate record.
*
* This variable is a nested array in the following format:
* <some field> => array(
* 'condition' => <condition to execute, as a string>
* 'arguments' => <array of arguments for condition, or NULL for none>
* );
*
* @var array
*/
protected $expressionFields = array();
public function __construct($connection, $table, array $options = array()) {
Dries Buytaert
committed
$options['return'] = Database::RETURN_AFFECTED;
parent::__construct($connection, $options);
$this->table = $table;
}
/**
* Set the field->value pairs to be merged into the table.
*
Dries Buytaert
committed
* This method should only be called once. It may be called either
* with a single associative array or two indexed arrays. If called
Dries Buytaert
committed
* with an associative array, the keys are taken to be the fields
* and the values are taken to be the corresponding values to set.
* If called with two arrays, the first array is taken as the fields
* and the second array is taken as the corresponding values.
*
* @param $fields
* An array of fields to set.
* @param $values
Dries Buytaert
committed
* An array of fields to set into the database. The values must be
Dries Buytaert
committed
* specified in the same order as the $fields array.
* @return
* The called object.
*/
public function fields(array $fields, array $values = array()) {
Dries Buytaert
committed
if (count($values) > 0) {
$fields = array_combine($fields, $values);
}
$this->insertFields = $fields;
Angie Byron
committed
Dries Buytaert
committed
return $this;
}
Angie Byron
committed
Dries Buytaert
committed
/**
* Set the key field(s) to be used to insert or update into the table.
*
Dries Buytaert
committed
* This method should only be called once. It may be called either
* with a single associative array or two indexed arrays. If called
Dries Buytaert
committed
* with an associative array, the keys are taken to be the fields
* and the values are taken to be the corresponding values to set.
* If called with two arrays, the first array is taken as the fields
* and the second array is taken as the corresponding values.
*
Dries Buytaert
committed
* These fields are the "pivot" fields of the query. Typically they
* will be the fields of the primary key. If the record does not
Dries Buytaert
committed
* yet exist, they will be inserted into the table along with the
Dries Buytaert
committed
* values set in the fields() method. If the record does exist,
Dries Buytaert
committed
* these fields will be used in the WHERE clause to select the
* record to update.
*
* @param $fields
* An array of fields to set.
* @param $values
Dries Buytaert
committed
* An array of fields to set into the database. The values must be
Dries Buytaert
committed
* specified in the same order as the $fields array.
* @return
* The called object.
*/
public function key(array $fields, array $values = array()) {
Dries Buytaert
committed
if ($values) {
$fields = array_combine($fields, $values);
}
$this->keyFields = $fields;
return $this;
}
/**
* Specify fields to update in case of a duplicate record.
*
* If a record with the values in keys() already exists, the fields and values
Dries Buytaert
committed
* specified here will be updated in that record. If this method is not called,
Dries Buytaert
committed
* it defaults to the same values as were passed to the fields() method.
*
* @param $fields
* An array of fields to set.
* @param $values
Dries Buytaert
committed
* An array of fields to set into the database. The values must be
Dries Buytaert
committed
* specified in the same order as the $fields array.
* @return
* The called object.
*/
public function update(array $fields, array $values = array()) {
Dries Buytaert
committed
if ($values) {
$fields = array_combine($fields, $values);
}
$this->updateFields = $fields;
return $this;
}
/**
* Specify fields that should not be updated in case of a duplicate record.
*
* If this method is called and a record with the values in keys() already
* exists, Drupal will instead update the record with the values passed
* in the fields() method except for the fields specified in this method. That
* is, calling this method is equivalent to calling update() with identical
* parameters as fields() minus the keys specified here.
*
Dries Buytaert
committed
* The update() method takes precedent over this method. If update() is called,
Dries Buytaert
committed
* this method has no effect.
*
* @param $exclude_fields
* An array of fields in the query that should not be updated to match those
* specified by the fields() method.
* Alternatively, the fields may be specified as a variable number of string
* parameters.
* @return
* The called object.
*/
public function updateExcept($exclude_fields) {
if (!is_array($exclude_fields)) {
$exclude_fields = func_get_args();
}
$this->excludeFields = $exclude_fields;
Angie Byron
committed
Dries Buytaert
committed
return $this;
}
/**
* Specify fields to be updated as an expression.
*
Dries Buytaert
committed
* Expression fields are cases such as counter=counter+1. This method only
* applies if a duplicate key is detected. This method takes precedent over
Dries Buytaert
committed
* both update() and updateExcept().
*
* @param $field
* The field to set.
* @param $expression
Dries Buytaert
committed
* The field will be set to the value of this expression. This parameter
Dries Buytaert
committed
* may include named placeholders.
* @param $arguments
* If specified, this is an array of key/value pairs for named placeholders
* corresponding to the expression.
* @return
* The called object.
*/
public function expression($field, $expression, array $arguments = NULL) {
Dries Buytaert
committed
$this->expressionFields[$field] = array(
'expression' => $expression,
'arguments' => $arguments,
);
Angie Byron
committed
Dries Buytaert
committed
return $this;
}
public function execute() {
// In the degenerate case of this query type, we have to run multiple
// queries as there is no universal single-query mechanism that will work.
// Our degenerate case is not designed for performance efficiency but
Dries Buytaert
committed
// for comprehensibility. Any practical database driver will override
Dries Buytaert
committed
// this method with database-specific logic, so this function serves only
// as a fallback to aid developers of new drivers.
Angie Byron
committed
// Wrap multiple queries in a transaction, if the database supports it.
Dries Buytaert
committed
$transaction = $this->connection->startTransaction();
Angie Byron
committed
Dries Buytaert
committed
// Manually check if the record already exists.
$select = $this->connection->select($this->table);
foreach ($this->keyFields as $field => $value) {
$select->condition($field, $value);
}
Angie Byron
committed
Dries Buytaert
committed
$select = $select->countQuery();
$sql = (string)$select;
$arguments = $select->getArguments();
$num_existing = db_query($sql, $arguments)->fetchField();
Angie Byron
committed
Dries Buytaert
committed
if ($num_existing) {
// If there is already an existing record, run an update query.
Angie Byron
committed
Dries Buytaert
committed
if ($this->updateFields) {
$update_fields = $this->updateFields;
}
else {
$update_fields = $this->insertFields;
// If there are no exclude fields, this is a no-op.
foreach ($this->excludeFields as $exclude_field) {
unset($update_fields[$exclude_field]);
}
}
$update = $this->connection->update($this->table, $this->queryOptions)->fields($update_fields);
foreach ($this->keyFields as $field => $value) {
$update->condition($field, $value);
}
foreach ($this->expressionFields as $field => $expression) {
$update->expression($field, $expression['expression'], $expression['arguments']);
}
$update->execute();
}
else {
// If there is no existing record, run an insert query.
$insert_fields = $this->insertFields + $this->keyFields;
$this->connection->insert($this->table, $this->queryOptions)->fields($insert_fields)->execute();
}
Angie Byron
committed
Dries Buytaert
committed
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
// Commit the transaction.
$transaction->commit();
}
public function __toString() {
// In the degenerate case, there is no string-able query as this operation
// is potentially two queries.
return '';
}
}
/**
* General class for an abstracted DELETE operation.
*
* The conditional WHERE handling of this class is all inherited from Query.
*/
class DeleteQuery extends Query implements QueryConditionInterface {
/**
* The table from which to delete.
*
* @var string
*/
protected $table;
/**
Dries Buytaert
committed
* The condition object for this query. Condition handling is handled via
Dries Buytaert
committed
* composition.
*
* @var DatabaseCondition
*/
protected $condition;
public function __construct(DatabaseConnection $connection, $table, array $options = array()) {
Dries Buytaert
committed
$options['return'] = Database::RETURN_AFFECTED;
parent::__construct($connection, $options);
$this->table = $table;
Angie Byron
committed
Dries Buytaert
committed
$this->condition = new DatabaseCondition('AND');
}
public function condition($field, $value = NULL, $operator = '=') {
if (!isset($num_args)) {
$num_args = func_num_args();
}
$this->condition->condition($field, $value, $operator, $num_args);
return $this;
}
public function &conditions() {
return $this->condition->conditions();
}
public function arguments() {
return $this->condition->arguments();
}
public function where($snippet, $args = array()) {
$this->condition->where($snippet, $args);
return $this;
}
Angie Byron
committed
Dries Buytaert
committed
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
public function compile(DatabaseConnection $connection) {
return $this->condition->compile($connection);
}
public function execute() {
$values = array();
if (count($this->condition)) {
$this->condition->compile($this->connection);
$values = $this->condition->arguments();
}
return $this->connection->query((string)$this, $values, $this->queryOptions);
}
public function __toString() {
$query = 'DELETE FROM {' . $this->connection->escapeTable($this->table) . '} ';
if (count($this->condition)) {
$this->condition->compile($this->connection);
$query .= "\nWHERE " . $this->condition;
}
return $query;
}
}
/**
* General class for an abstracted UPDATE operation.
*
* The conditional WHERE handling of this class is all inherited from Query.
*/
class UpdateQuery extends Query implements QueryConditionInterface {
/**
* The table to update.
*
* @var string
*/
protected $table;
/**
* An array of fields that will be updated.
*
* @var array
*/
Angie Byron
committed
protected $fields = array();
Dries Buytaert
committed
/**
* An array of values to update to.
*
* @var array
*/
protected $arguments = array();
/**
Dries Buytaert
committed
* The condition object for this query. Condition handling is handled via
Dries Buytaert
committed
* composition.
*
* @var DatabaseCondition
*/
protected $condition;
/**
* An array of fields to update to an expression in case of a duplicate record.
*
* This variable is a nested array in the following format:
* <some field> => array(
* 'condition' => <condition to execute, as a string>
* 'arguments' => <array of arguments for condition, or NULL for none>
* );
*
* @var array
*/
protected $expressionFields = array();
public function __construct(DatabaseConnection $connection, $table, array $options = array()) {
Dries Buytaert
committed
$options['return'] = Database::RETURN_AFFECTED;
parent::__construct($connection, $options);
$this->table = $table;
Angie Byron
committed
Dries Buytaert
committed
$this->condition = new DatabaseCondition('AND');
}
public function condition($field, $value = NULL, $operator = '=') {
if (!isset($num_args)) {
$num_args = func_num_args();
}
$this->condition->condition($field, $value, $operator, $num_args);
return $this;
}
public function &conditions() {
return $this->condition->conditions();
}
public function arguments() {
return $this->condition->arguments();
}
public function where($snippet, $args = array()) {
$this->condition->where($snippet, $args);
return $this;
}
Angie Byron
committed
Dries Buytaert
committed
public function compile(DatabaseConnection $connection) {
return $this->condition->compile($connection);
}
/**
* Add a set of field->value pairs to be updated.
*
* @param $fields
Dries Buytaert
committed
* An associative array of fields to write into the database. The array keys
Dries Buytaert
committed
* are the field names while the values are the values to which to set them.
* @return
* The called object.
*/
public function fields(array $fields) {
Dries Buytaert
committed
$this->fields = $fields;
return $this;
}
/**
* Specify fields to be updated as an expression.
*
Dries Buytaert
committed
* Expression fields are cases such as counter=counter+1. This method takes
Dries Buytaert
committed
* precedence over fields().
*
* @param $field
* The field to set.
* @param $expression
Dries Buytaert
committed
* The field will be set to the value of this expression. This parameter
Dries Buytaert
committed
* may include named placeholders.
* @param $arguments
* If specified, this is an array of key/value pairs for named placeholders
* corresponding to the expression.
* @return
* The called object.
*/
public function expression($field, $expression, array $arguments = NULL) {
Dries Buytaert
committed
$this->expressionFields[$field] = array(
'expression' => $expression,
'arguments' => $arguments,
);
Angie Byron
committed
Dries Buytaert
committed
return $this;
}
public function execute() {
Angie Byron
committed
Dries Buytaert
committed
// Expressions take priority over literal fields, so we process those first
// and remove any literal fields that conflict.
$fields = $this->fields;
$update_values = array();
foreach ($this->expressionFields as $field => $data) {
if (!empty($data['arguments'])) {
$update_values += $data['arguments'];
}
unset($fields[$field]);
}
Angie Byron
committed
Dries Buytaert
committed
// Because we filter $fields the same way here and in __toString(), the
// placeholders will all match up properly.
$max_placeholder = 0;
foreach ($fields as $field => $value) {
$update_values[':db_update_placeholder_' . ($max_placeholder++)] = $value;
}
Angie Byron
committed
Dries Buytaert
committed
if (count($this->condition)) {
$this->condition->compile($this->connection);
$update_values = array_merge($update_values, $this->condition->arguments());
}
return $this->connection->query((string)$this, $update_values, $this->queryOptions);
}
public function __toString() {
// Expressions take priority over literal fields, so we process those first
// and remove any literal fields that conflict.
$fields = $this->fields;
$update_fields = array();
foreach ($this->expressionFields as $field => $data) {
$update_fields[] = $field . '=' . $data['expression'];
unset($fields[$field]);
}
Angie Byron
committed
Dries Buytaert
committed
$max_placeholder = 0;
foreach ($fields as $field => $value) {
$update_fields[] = $field . '=:db_update_placeholder_' . ($max_placeholder++);
}
$query = 'UPDATE {' . $this->connection->escapeTable($this->table) . '} SET ' . implode(', ', $update_fields);
if (count($this->condition)) {
$this->condition->compile($this->connection);
// There is an implicit string cast on $this->condition.
$query .= "\nWHERE " . $this->condition;
}
return $query;
}
}
/**
* Generic class for a series of conditions in a query.
*/
class DatabaseCondition implements QueryConditionInterface, Countable {
protected $conditions = array();
protected $arguments = array();
Angie Byron
committed
Dries Buytaert
committed
protected $changed = TRUE;
public function __construct($conjunction) {
$this->conditions['#conjunction'] = $conjunction;
}
Angie Byron
committed
Dries Buytaert
committed
/**
Dries Buytaert
committed
* Return the size of this conditional. This is part of the Countable interface.
Dries Buytaert
committed
*
* The size of the conditional is the size of its conditional array minus
* one, because one element is the the conjunction.
*/
public function count() {
return count($this->conditions) - 1;
}
Angie Byron
committed
Dries Buytaert
committed
public function condition($field, $value = NULL, $operator = '=') {
$this->conditions[] = array(
'field' => $field,
'value' => $value,
'operator' => $operator,
);
Angie Byron
committed
Dries Buytaert
committed
$this->changed = TRUE;
Angie Byron
committed
Dries Buytaert
committed
return $this;
}
public function where($snippet, $args = array()) {
$this->conditions[] = array(
'field' => $snippet,
'value' => $args,
'operator' => NULL,
);
$this->changed = TRUE;
Angie Byron
committed
Dries Buytaert
committed
return $this;