1 <?php

     2 

     3 /**

     4  * @addtogroup database

     5  * @{

     6  */

     7 

     8 /**

     9  * @file

    10  * Non-specific Database query code. Used by all engines.

    11  */

    12 

    13 /**

    14  * Interface for a conditional clause in a query.

    15  */

    16 interface QueryConditionInterface {

    17 

    18   /**

    19    * Helper function: builds the most common conditional clauses.

    20    *

    21    * This method can take a variable number of parameters. If called with two

    22    * parameters, they are taken as $field and $value with $operator having a

    23    * value of IN if $value is an array and = otherwise.

    24    *

    25    * Do not use this method to test for NULL values. Instead, use

    26    * QueryConditionInterface::isNull() or QueryConditionInterface::isNotNull().

    27    *

    28    * @param $field

    29    *   The name of the field to check. If you would like to add a more complex

    30    *   condition involving operators or functions, use where().

    31    * @param $value

    32    *   The value to test the field against. In most cases, this is a scalar.

    33    *   For more complex options, it is an array. The meaning of each element in

    34    *   the array is dependent on the $operator.

    35    * @param $operator

    36    *   The comparison operator, such as =, <, or >=. It also accepts more

    37    *   complex options such as IN, LIKE, or BETWEEN. Defaults to IN if $value is

    38    *   an array, and = otherwise.

    39    *

    40    * @return QueryConditionInterface

    41    *   The called object.

    42    *

    43    * @see QueryConditionInterface::isNull()

    44    * @see QueryConditionInterface::isNotNull()

    45    */

    46   public function condition($field, $value = NULL, $operator = NULL);

    47 

    48   /**

    49    * Adds an arbitrary WHERE clause to the query.

    50    *

    51    * @param $snippet

    52    *   A portion of a WHERE clause as a prepared statement. It must use named

    53    *   placeholders, not ? placeholders.

    54    * @param $args

    55    *   An associative array of arguments.

    56    *

    57    * @return QueryConditionInterface

    58    *   The called object.

    59    */

    60   public function where($snippet, $args = array());

    61 

    62   /**

    63    * Sets a condition that the specified field be NULL.

    64    *

    65    * @param $field

    66    *   The name of the field to check.

    67    *

    68    * @return QueryConditionInterface

    69    *   The called object.

    70    */

    71   public function isNull($field);

    72 

    73   /**

    74    * Sets a condition that the specified field be NOT NULL.

    75    *

    76    * @param $field

    77    *   The name of the field to check.

    78    *

    79    * @return QueryConditionInterface

    80    *   The called object.

    81    */

    82   public function isNotNull($field);

    83 

    84   /**

    85    * Sets a condition that the specified subquery returns values.

    86    *

    87    * @param SelectQueryInterface $select

    88    *   The subquery that must contain results.

    89    *

    90    * @return QueryConditionInterface

    91    *   The called object.

    92    */

    93   public function exists(SelectQueryInterface $select);

    94 

    95   /**

    96    * Sets a condition that the specified subquery returns no values.

    97    *

    98    * @param SelectQueryInterface $select

    99    *   The subquery that must not contain results.

   100    *

   101    * @return QueryConditionInterface

   102    *   The called object.

   103    */

   104   public function notExists(SelectQueryInterface $select);

   105 

   106   /**

   107    * Gets a complete list of all conditions in this conditional clause.

   108    *

   109    * This method returns by reference. That allows alter hooks to access the

   110    * data structure directly and manipulate it before it gets compiled.

   111    *

   112    * The data structure that is returned is an indexed array of entries, where

   113    * each entry looks like the following:

   114    * @code

   115    * array(

   116    *   'field' => $field,

   117    *   'value' => $value,

   118    *   'operator' => $operator,

   119    * );

   120    * @endcode

   121    *

   122    * In the special case that $operator is NULL, the $field is taken as a raw

   123    * SQL snippet (possibly containing a function) and $value is an associative

   124    * array of placeholders for the snippet.

   125    *

   126    * There will also be a single array entry of #conjunction, which is the

   127    * conjunction that will be applied to the array, such as AND.

   128    */

   129   public function &conditions();

   130 

   131   /**

   132    * Gets a complete list of all values to insert into the prepared statement.

   133    *

   134    * @return

   135    *   An associative array of placeholders and values.

   136    */

   137   public function arguments();

   138 

   139   /**

   140    * Compiles the saved conditions for later retrieval.

   141    *

   142    * This method does not return anything, but simply prepares data to be

   143    * retrieved via __toString() and arguments().

   144    *

   145    * @param $connection

   146    *   The database connection for which to compile the conditionals.

   147    * @param $queryPlaceholder

   148    *   The query this condition belongs to. If not given, the current query is

   149    *   used.

   150    */

   151   public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder);

   152 

   153   /**

   154    * Check whether a condition has been previously compiled.

   155    *

   156    * @return

   157    *   TRUE if the condition has been previously compiled.

   158    */

   159   public function compiled();

   160 }

   161 

   162 

   163 /**

   164  * Interface for a query that can be manipulated via an alter hook.

   165  */

   166 interface QueryAlterableInterface {

   167 

   168   /**

   169    * Adds a tag to a query.

   170    *

   171    * Tags are strings that identify a query. A query may have any number of

   172    * tags. Tags are used to mark a query so that alter hooks may decide if they

   173    * wish to take action. Tags should be all lower-case and contain only

   174    * letters, numbers, and underscore, and start with a letter. That is, they

   175    * should follow the same rules as PHP identifiers in general.

   176    *

   177    * @param $tag

   178    *   The tag to add.

   179    *

   180    * @return QueryAlterableInterface

   181    *   The called object.

   182    */

   183   public function addTag($tag);

   184 

   185   /**

   186    * Determines if a given query has a given tag.

   187    *

   188    * @param $tag

   189    *   The tag to check.

   190    *

   191    * @return

   192    *   TRUE if this query has been marked with this tag, FALSE otherwise.

   193    */

   194   public function hasTag($tag);

   195 

   196   /**

   197    * Determines if a given query has all specified tags.

   198    *

   199    * @param $tags

   200    *   A variable number of arguments, one for each tag to check.

   201    *

   202    * @return

   203    *   TRUE if this query has been marked with all specified tags, FALSE

   204    *   otherwise.

   205    */

   206   public function hasAllTags();

   207 

   208   /**

   209    * Determines if a given query has any specified tag.

   210    *

   211    * @param $tags

   212    *   A variable number of arguments, one for each tag to check.

   213    *

   214    * @return

   215    *   TRUE if this query has been marked with at least one of the specified

   216    *   tags, FALSE otherwise.

   217    */

   218   public function hasAnyTag();

   219 

   220   /**

   221    * Adds additional metadata to the query.

   222    *

   223    * Often, a query may need to provide additional contextual data to alter

   224    * hooks. Alter hooks may then use that information to decide if and how

   225    * to take action.

   226    *

   227    * @param $key

   228    *   The unique identifier for this piece of metadata. Must be a string that

   229    *   follows the same rules as any other PHP identifier.

   230    * @param $object

   231    *   The additional data to add to the query. May be any valid PHP variable.

   232    *

   233    * @return QueryAlterableInterface

   234    *   The called object.

   235    */

   236   public function addMetaData($key, $object);

   237 

   238   /**

   239    * Retrieves a given piece of metadata.

   240    *

   241    * @param $key

   242    *   The unique identifier for the piece of metadata to retrieve.

   243    *

   244    * @return

   245    *   The previously attached metadata object, or NULL if one doesn't exist.

   246    */

   247   public function getMetaData($key);

   248 }

   249 

   250 /**

   251  * Interface for a query that accepts placeholders.

   252  */

   253 interface QueryPlaceholderInterface {

   254 

   255   /**

   256    * Returns a unique identifier for this object.

   257    */

   258   public function uniqueIdentifier();

   259 

   260   /**

   261    * Returns the next placeholder ID for the query.

   262    *

   263    * @return

   264    *   The next available placeholder ID as an integer.

   265    */

   266   public function nextPlaceholder();

   267 }

   268 

   269 /**

   270  * Base class for query builders.

   271  *

   272  * Note that query builders use PHP's magic __toString() method to compile the

   273  * query object into a prepared statement.

   274  */

   275 abstract class Query implements QueryPlaceholderInterface {

   276 

   277   /**

   278    * The connection object on which to run this query.

   279    *

   280    * @var DatabaseConnection

   281    */

   282   protected $connection;

   283 

   284   /**

   285    * The target of the connection object.

   286    *

   287    * @var string

   288    */

   289   protected $connectionTarget;

   290 

   291   /**

   292    * The key of the connection object.

   293    *

   294    * @var string

   295    */

   296   protected $connectionKey;

   297 

   298   /**

   299    * The query options to pass on to the connection object.

   300    *

   301    * @var array

   302    */

   303   protected $queryOptions;

   304 

   305   /**

   306    * A unique identifier for this query object.

   307    */

   308   protected $uniqueIdentifier;

   309 

   310   /**

   311    * The placeholder counter.

   312    */

   313   protected $nextPlaceholder = 0;

   314 

   315   /**

   316    * An array of comments that can be prepended to a query.

   317    *

   318    * @var array

   319    */

   320   protected $comments = array();

   321 

   322   /**

   323    * Constructs a Query object.

   324    *

   325    * @param DatabaseConnection $connection

   326    *   Database connection object.

   327    * @param array $options

   328    *   Array of query options.

   329    */

   330   public function __construct(DatabaseConnection $connection, $options) {

   331     $this->uniqueIdentifier = uniqid('', TRUE);

   332 

   333     $this->connection = $connection;

   334     $this->connectionKey = $this->connection->getKey();

   335     $this->connectionTarget = $this->connection->getTarget();

   336 

   337     $this->queryOptions = $options;

   338   }

   339 

   340   /**

   341    * Implements the magic __sleep function to disconnect from the database.

   342    */

   343   public function __sleep() {

   344     $keys = get_object_vars($this);

   345     unset($keys['connection']);

   346     return array_keys($keys);

   347   }

   348 

   349   /**

   350    * Implements the magic __wakeup function to reconnect to the database.

   351    */

   352   public function __wakeup() {

   353     $this->connection = Database::getConnection($this->connectionTarget, $this->connectionKey);

   354   }

   355 

   356   /**

   357    * Implements the magic __clone function.

   358    */

   359   public function __clone() {

   360     $this->uniqueIdentifier = uniqid('', TRUE);

   361   }

   362 

   363   /**

   364    * Runs the query against the database.

   365    */

   366   abstract protected function execute();

   367 

   368   /**

   369    * Implements PHP magic __toString method to convert the query to a string.

   370    *

   371    * The toString operation is how we compile a query object to a prepared

   372    * statement.

   373    *

   374    * @return

   375    *   A prepared statement query string for this object.

   376    */

   377   abstract public function __toString();

   378 

   379   /**

   380    * Returns a unique identifier for this object.

   381    */

   382   public function uniqueIdentifier() {

   383     return $this->uniqueIdentifier;

   384   }

   385 

   386   /**

   387    * Gets the next placeholder value for this query object.

   388    *

   389    * @return int

   390    *   Next placeholder value.

   391    */

   392   public function nextPlaceholder() {

   393     return $this->nextPlaceholder++;

   394   }

   395 

   396   /**

   397    * Adds a comment to the query.

   398    *

   399    * By adding a comment to a query, you can more easily find it in your

   400    * query log or the list of active queries on an SQL server. This allows

   401    * for easier debugging and allows you to more easily find where a query

   402    * with a performance problem is being generated.

   403    *

   404    * The comment string will be sanitized to remove * / and other characters

   405    * that may terminate the string early so as to avoid SQL injection attacks.

   406    *

   407    * @param $comment

   408    *   The comment string to be inserted into the query.

   409    *

   410    * @return Query

   411    *   The called object.

   412    */

   413   public function comment($comment) {

   414     $this->comments[] = $comment;

   415     return $this;

   416   }

   417 

   418   /**

   419    * Returns a reference to the comments array for the query.

   420    *

   421    * Because this method returns by reference, alter hooks may edit the comments

   422    * array directly to make their changes. If just adding comments, however, the

   423    * use of comment() is preferred.

   424    *

   425    * Note that this method must be called by reference as well:

   426    * @code

   427    * $comments =& $query->getComments();

   428    * @endcode

   429    *

   430    * @return

   431    *   A reference to the comments array structure.

   432    */

   433   public function &getComments() {

   434     return $this->comments;

   435   }

   436 }

   437 

   438 /**

   439  * General class for an abstracted INSERT query.

   440  */

   441 class InsertQuery extends Query {

   442 

   443   /**

   444    * The table on which to insert.

   445    *

   446    * @var string

   447    */

   448   protected $table;

   449 

   450   /**

   451    * An array of fields on which to insert.

   452    *

   453    * @var array

   454    */

   455   protected $insertFields = array();

   456 

   457   /**

   458    * An array of fields that should be set to their database-defined defaults.

   459    *

   460    * @var array

   461    */

   462   protected $defaultFields = array();

   463 

   464   /**

   465    * A nested array of values to insert.

   466    *

   467    * $insertValues is an array of arrays. Each sub-array is either an

   468    * associative array whose keys are field names and whose values are field

   469    * values to insert, or a non-associative array of values in the same order

   470    * as $insertFields.

   471    *

   472    * Whether multiple insert sets will be run in a single query or multiple

   473    * queries is left to individual drivers to implement in whatever manner is

   474    * most appropriate. The order of values in each sub-array must match the

   475    * order of fields in $insertFields.

   476    *

   477    * @var array

   478    */

   479   protected $insertValues = array();

   480 

   481   /**

   482    * A SelectQuery object to fetch the rows that should be inserted.

   483    *

   484    * @var SelectQueryInterface

   485    */

   486   protected $fromQuery;

   487 

   488   /**

   489    * Constructs an InsertQuery object.

   490    *

   491    * @param DatabaseConnection $connection

   492    *   A DatabaseConnection object.

   493    * @param string $table

   494    *   Name of the table to associate with this query.

   495    * @param array $options

   496    *   Array of database options.

   497    */

   498   public function __construct($connection, $table, array $options = array()) {

   499     if (!isset($options['return'])) {

   500       $options['return'] = Database::RETURN_INSERT_ID;

   501     }

   502     parent::__construct($connection, $options);

   503     $this->table = $table;

   504   }

   505 

   506   /**

   507    * Adds a set of field->value pairs to be inserted.

   508    *

   509    * This method may only be called once. Calling it a second time will be

   510    * ignored. To queue up multiple sets of values to be inserted at once,

   511    * use the values() method.

   512    *

   513    * @param $fields

   514    *   An array of fields on which to insert. This array may be indexed or

   515    *   associative. If indexed, the array is taken to be the list of fields.

   516    *   If associative, the keys of the array are taken to be the fields and

   517    *   the values are taken to be corresponding values to insert. If a

   518    *   $values argument is provided, $fields must be indexed.

   519    * @param $values

   520    *   An array of fields to insert into the database. The values must be

   521    *   specified in the same order as the $fields array.

   522    *

   523    * @return InsertQuery

   524    *   The called object.

   525    */

   526   public function fields(array $fields, array $values = array()) {

   527     if (empty($this->insertFields)) {

   528       if (empty($values)) {

   529         if (!is_numeric(key($fields))) {

   530           $values = array_values($fields);

   531           $fields = array_keys($fields);

   532         }

   533       }

   534       $this->insertFields = $fields;

   535       if (!empty($values)) {

   536         $this->insertValues[] = $values;

   537       }

   538     }

   539 

   540     return $this;

   541   }

   542 

   543   /**

   544    * Adds another set of values to the query to be inserted.

   545    *

   546    * If $values is a numeric-keyed array, it will be assumed to be in the same

   547    * order as the original fields() call. If it is associative, it may be

   548    * in any order as long as the keys of the array match the names of the

   549    * fields.

   550    *

   551    * @param $values

   552    *   An array of values to add to the query.

   553    *

   554    * @return InsertQuery

   555    *   The called object.

   556    */

   557   public function values(array $values) {

   558     if (is_numeric(key($values))) {

   559       $this->insertValues[] = $values;

   560     }

   561     else {

   562       // Reorder the submitted values to match the fields array.

   563       foreach ($this->insertFields as $key) {

   564         $insert_values[$key] = $values[$key];

   565       }

   566       // For consistency, the values array is always numerically indexed.

   567       $this->insertValues[] = array_values($insert_values);

   568     }

   569     return $this;

   570   }

   571 

   572   /**

   573    * Specifies fields for which the database defaults should be used.

   574    *

   575    * If you want to force a given field to use the database-defined default,

   576    * not NULL or undefined, use this method to instruct the database to use

   577    * default values explicitly. In most cases this will not be necessary

   578    * unless you are inserting a row that is all default values, as you cannot

   579    * specify no values in an INSERT query.

   580    *

   581    * Specifying a field both in fields() and in useDefaults() is an error

   582    * and will not execute.

   583    *

   584    * @param $fields

   585    *   An array of values for which to use the default values

   586    *   specified in the table definition.

   587    *

   588    * @return InsertQuery

   589    *   The called object.

   590    */

   591   public function useDefaults(array $fields) {

   592     $this->defaultFields = $fields;

   593     return $this;

   594   }

   595 

   596   /**

   597    * Sets the fromQuery on this InsertQuery object.

   598    *

   599    * @param SelectQueryInterface $query

   600    *   The query to fetch the rows that should be inserted.

   601    *

   602    * @return InsertQuery

   603    *   The called object.

   604    */

   605   public function from(SelectQueryInterface $query) {

   606     $this->fromQuery = $query;

   607     return $this;

   608   }

   609 

   610   /**

   611    * Executes the insert query.

   612    *

   613    * @return

   614    *   The last insert ID of the query, if one exists. If the query

   615    *   was given multiple sets of values to insert, the return value is

   616    *   undefined. If no fields are specified, this method will do nothing and

   617    *   return NULL. That makes it safe to use in multi-insert loops.

   618    */

   619   public function execute() {

   620     // If validation fails, simply return NULL. Note that validation routines

   621     // in preExecute() may throw exceptions instead.

   622     if (!$this->preExecute()) {

   623       return NULL;

   624     }

   625 

   626     // If we're selecting from a SelectQuery, finish building the query and

   627     // pass it back, as any remaining options are irrelevant.

   628     if (!empty($this->fromQuery)) {

   629       $sql = (string) $this;

   630       // The SelectQuery may contain arguments, load and pass them through.

   631       return $this->connection->query($sql, $this->fromQuery->getArguments(), $this->queryOptions);

   632     }

   633 

   634     $last_insert_id = 0;

   635 

   636     // Each insert happens in its own query in the degenerate case. However,

   637     // we wrap it in a transaction so that it is atomic where possible. On many

   638     // databases, such as SQLite, this is also a notable performance boost.

   639     $transaction = $this->connection->startTransaction();

   640 

   641     try {

   642       $sql = (string) $this;

   643       foreach ($this->insertValues as $insert_values) {

   644         $last_insert_id = $this->connection->query($sql, $insert_values, $this->queryOptions);

   645       }

   646     }

   647     catch (Exception $e) {

   648       // One of the INSERTs failed, rollback the whole batch.

   649       $transaction->rollback();

   650       // Rethrow the exception for the calling code.

   651       throw $e;

   652     }

   653 

   654     // Re-initialize the values array so that we can re-use this query.

   655     $this->insertValues = array();

   656 

   657     // Transaction commits here where $transaction looses scope.

   658 

   659     return $last_insert_id;

   660   }

   661 

   662   /**

   663    * Implements PHP magic __toString method to convert the query to a string.

   664    *

   665    * @return string

   666    *   The prepared statement.

   667    */

   668   public function __toString() {

   669     // Create a sanitized comment string to prepend to the query.

   670     $comments = $this->connection->makeComment($this->comments);

   671 

   672     // Default fields are always placed first for consistency.

   673     $insert_fields = array_merge($this->defaultFields, $this->insertFields);

   674 

   675     if (!empty($this->fromQuery)) {

   676       return $comments . 'INSERT INTO {' . $this->table . '} (' . implode(', ', $insert_fields) . ') ' . $this->fromQuery;

   677     }

   678 

   679     // For simplicity, we will use the $placeholders array to inject

   680     // default keywords even though they are not, strictly speaking,

   681     // placeholders for prepared statements.

   682     $placeholders = array();

   683     $placeholders = array_pad($placeholders, count($this->defaultFields), 'default');

   684     $placeholders = array_pad($placeholders, count($this->insertFields), '?');

   685 

   686     return $comments . 'INSERT INTO {' . $this->table . '} (' . implode(', ', $insert_fields) . ') VALUES (' . implode(', ', $placeholders) . ')';

   687   }

   688 

   689   /**

   690    * Preprocesses and validates the query.

   691    *

   692    * @return

   693    *   TRUE if the validation was successful, FALSE if not.

   694    *

   695    * @throws FieldsOverlapException

   696    * @throws NoFieldsException

   697    */

   698   public function preExecute() {

   699     // Confirm that the user did not try to specify an identical

   700     // field and default field.

   701     if (array_intersect($this->insertFields, $this->defaultFields)) {

   702       throw new FieldsOverlapException('You may not specify the same field to have a value and a schema-default value.');

   703     }

   704 

   705     if (!empty($this->fromQuery)) {

   706       // We have to assume that the used aliases match the insert fields.

   707       // Regular fields are added to the query before expressions, maintain the

   708       // same order for the insert fields.

   709       // This behavior can be overridden by calling fields() manually as only the

   710       // first call to fields() does have an effect.

   711       $this->fields(array_merge(array_keys($this->fromQuery->getFields()), array_keys($this->fromQuery->getExpressions())));

   712     }

   713     else {

   714       // Don't execute query without fields.

   715       if (count($this->insertFields) + count($this->defaultFields) == 0) {

   716         throw new NoFieldsException('There are no fields available to insert with.');

   717       }

   718     }

   719 

   720     // If no values have been added, silently ignore this query. This can happen

   721     // if values are added conditionally, so we don't want to throw an

   722     // exception.

   723     if (!isset($this->insertValues[0]) && count($this->insertFields) > 0 && empty($this->fromQuery)) {

   724       return FALSE;

   725     }

   726     return TRUE;

   727   }

   728 }

   729 

   730 /**

   731  * General class for an abstracted DELETE operation.

   732  */

   733 class DeleteQuery extends Query implements QueryConditionInterface {

   734 

   735   /**

   736    * The table from which to delete.

   737    *

   738    * @var string

   739    */

   740   protected $table;

   741 

   742   /**

   743    * The condition object for this query.

   744    *

   745    * Condition handling is handled via composition.

   746    *

   747    * @var DatabaseCondition

   748    */

   749   protected $condition;

   750 

   751   /**

   752    * Constructs a DeleteQuery object.

   753    *

   754    * @param DatabaseConnection $connection

   755    *   A DatabaseConnection object.

   756    * @param string $table

   757    *   Name of the table to associate with this query.

   758    * @param array $options

   759    *   Array of database options.

   760    */

   761   public function __construct(DatabaseConnection $connection, $table, array $options = array()) {

   762     $options['return'] = Database::RETURN_AFFECTED;

   763     parent::__construct($connection, $options);

   764     $this->table = $table;

   765 

   766     $this->condition = new DatabaseCondition('AND');

   767   }

   768 

   769   /**

   770    * Implements QueryConditionInterface::condition().

   771    */

   772   public function condition($field, $value = NULL, $operator = NULL) {

   773     $this->condition->condition($field, $value, $operator);

   774     return $this;

   775   }

   776 

   777   /**

   778    * Implements QueryConditionInterface::isNull().

   779    */

   780   public function isNull($field) {

   781     $this->condition->isNull($field);

   782     return $this;

   783   }

   784 

   785   /**

   786    * Implements QueryConditionInterface::isNotNull().

   787    */

   788   public function isNotNull($field) {

   789     $this->condition->isNotNull($field);

   790     return $this;

   791   }

   792 

   793   /**

   794    * Implements QueryConditionInterface::exists().

   795    */

   796   public function exists(SelectQueryInterface $select) {

   797     $this->condition->exists($select);

   798     return $this;

   799   }

   800 

   801   /**

   802    * Implements QueryConditionInterface::notExists().

   803    */

   804   public function notExists(SelectQueryInterface $select) {

   805     $this->condition->notExists($select);

   806     return $this;

   807   }

   808 

   809   /**

   810    * Implements QueryConditionInterface::conditions().

   811    */

   812   public function &conditions() {

   813     return $this->condition->conditions();

   814   }

   815 

   816   /**

   817    * Implements QueryConditionInterface::arguments().

   818    */

   819   public function arguments() {

   820     return $this->condition->arguments();

   821   }

   822 

   823   /**

   824    * Implements QueryConditionInterface::where().

   825    */

   826   public function where($snippet, $args = array()) {

   827     $this->condition->where($snippet, $args);

   828     return $this;

   829   }

   830 

   831   /**

   832    * Implements QueryConditionInterface::compile().

   833    */

   834   public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder) {

   835     return $this->condition->compile($connection, $queryPlaceholder);

   836   }

   837 

   838   /**

   839    * Implements QueryConditionInterface::compiled().

   840    */

   841   public function compiled() {

   842     return $this->condition->compiled();

   843   }

   844 

   845   /**

   846    * Executes the DELETE query.

   847    *

   848    * @return int

   849    *   The number of rows affected by the delete query.

   850    */

   851   public function execute() {

   852     $values = array();

   853     if (count($this->condition)) {

   854       $this->condition->compile($this->connection, $this);

   855       $values = $this->condition->arguments();

   856     }

   857 

   858     return $this->connection->query((string) $this, $values, $this->queryOptions);

   859   }

   860 

   861   /**

   862    * Implements PHP magic __toString method to convert the query to a string.

   863    *

   864    * @return string

   865    *   The prepared statement.

   866    */

   867   public function __toString() {

   868     // Create a sanitized comment string to prepend to the query.

   869     $comments = $this->connection->makeComment($this->comments);

   870 

   871     $query = $comments . 'DELETE FROM {' . $this->connection->escapeTable($this->table) . '} ';

   872 

   873     if (count($this->condition)) {

   874 

   875       $this->condition->compile($this->connection, $this);

   876       $query .= "\nWHERE " . $this->condition;

   877     }

   878 

   879     return $query;

   880   }

   881 }

   882 

   883 

   884 /**

   885  * General class for an abstracted TRUNCATE operation.

   886  */

   887 class TruncateQuery extends Query {

   888 

   889   /**

   890    * The table to truncate.

   891    *

   892    * @var string

   893    */

   894   protected $table;

   895 

   896   /**

   897    * Constructs a TruncateQuery object.

   898    *

   899    * @param DatabaseConnection $connection

   900    *   A DatabaseConnection object.

   901    * @param string $table

   902    *   Name of the table to associate with this query.

   903    * @param array $options

   904    *   Array of database options.

   905    */

   906   public function __construct(DatabaseConnection $connection, $table, array $options = array()) {

   907     $options['return'] = Database::RETURN_AFFECTED;

   908     parent::__construct($connection, $options);

   909     $this->table = $table;

   910   }

   911 

   912   /**

   913    * Implements QueryConditionInterface::compile().

   914    */

   915   public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder) {

   916     return $this->condition->compile($connection, $queryPlaceholder);

   917   }

   918 

   919   /**

   920    * Implements QueryConditionInterface::compiled().

   921    */

   922   public function compiled() {

   923     return $this->condition->compiled();

   924   }

   925 

   926   /**

   927    * Executes the TRUNCATE query.

   928    *

   929    * @return

   930    *   Return value is dependent on the database type.

   931    */

   932   public function execute() {

   933     return $this->connection->query((string) $this, array(), $this->queryOptions);

   934   }

   935 

   936   /**

   937    * Implements PHP magic __toString method to convert the query to a string.

   938    *

   939    * @return string

   940    *   The prepared statement.

   941    */

   942   public function __toString() {

   943     // Create a sanitized comment string to prepend to the query.

   944     $comments = $this->connection->makeComment($this->comments);

   945 

   946     // In most cases, TRUNCATE is not a transaction safe statement as it is a

   947     // DDL statement which results in an implicit COMMIT. When we are in a

   948     // transaction, fallback to the slower, but transactional, DELETE.

   949     // PostgreSQL also locks the entire table for a TRUNCATE strongly reducing

   950     // the concurrency with other transactions.

   951     if ($this->connection->inTransaction()) {

   952       return $comments . 'DELETE FROM {' . $this->connection->escapeTable($this->table) . '}';

   953     }

   954     else {

   955       return $comments . 'TRUNCATE {' . $this->connection->escapeTable($this->table) . '} ';

   956     }

   957   }

   958 }

   959 

   960 /**

   961  * General class for an abstracted UPDATE operation.

   962  */

   963 class UpdateQuery extends Query implements QueryConditionInterface {

   964 

   965   /**

   966    * The table to update.

   967    *

   968    * @var string

   969    */

   970   protected $table;

   971 

   972   /**

   973    * An array of fields that will be updated.

   974    *

   975    * @var array

   976    */

   977   protected $fields = array();

   978 

   979   /**

   980    * An array of values to update to.

   981    *

   982    * @var array

   983    */

   984   protected $arguments = array();

   985 

   986   /**

   987    * The condition object for this query.

   988    *

   989    * Condition handling is handled via composition.

   990    *

   991    * @var DatabaseCondition

   992    */

   993   protected $condition;

   994 

   995   /**

   996    * Array of fields to update to an expression in case of a duplicate record.

   997    *

   998    * This variable is a nested array in the following format:

   999    * @code

  1000    * <some field> => array(

  1001    *  'condition' => <condition to execute, as a string>,

  1002    *  'arguments' => <array of arguments for condition, or NULL for none>,

  1003    * );

  1004    * @endcode

  1005    *

  1006    * @var array

  1007    */

  1008   protected $expressionFields = array();

  1009 

  1010   /**

  1011    * Constructs an UpdateQuery object.

  1012    *

  1013    * @param DatabaseConnection $connection

  1014    *   A DatabaseConnection object.

  1015    * @param string $table

  1016    *   Name of the table to associate with this query.

  1017    * @param array $options

  1018    *   Array of database options.

  1019    */

  1020   public function __construct(DatabaseConnection $connection, $table, array $options = array()) {

  1021     $options['return'] = Database::RETURN_AFFECTED;

  1022     parent::__construct($connection, $options);

  1023     $this->table = $table;

  1024 

  1025     $this->condition = new DatabaseCondition('AND');

  1026   }

  1027 

  1028   /**

  1029    * Implements QueryConditionInterface::condition().

  1030    */

  1031   public function condition($field, $value = NULL, $operator = NULL) {

  1032     $this->condition->condition($field, $value, $operator);

  1033     return $this;

  1034   }

  1035 

  1036   /**

  1037    * Implements QueryConditionInterface::isNull().

  1038    */

  1039   public function isNull($field) {

  1040     $this->condition->isNull($field);

  1041     return $this;

  1042   }

  1043 

  1044   /**

  1045    * Implements QueryConditionInterface::isNotNull().

  1046    */

  1047   public function isNotNull($field) {

  1048     $this->condition->isNotNull($field);

  1049     return $this;

  1050   }

  1051 

  1052   /**

  1053    * Implements QueryConditionInterface::exists().

  1054    */

  1055   public function exists(SelectQueryInterface $select) {

  1056     $this->condition->exists($select);

  1057     return $this;

  1058   }

  1059 

  1060   /**

  1061    * Implements QueryConditionInterface::notExists().

  1062    */

  1063   public function notExists(SelectQueryInterface $select) {

  1064     $this->condition->notExists($select);

  1065     return $this;

  1066   }

  1067 

  1068   /**

  1069    * Implements QueryConditionInterface::conditions().

  1070    */

  1071   public function &conditions() {

  1072     return $this->condition->conditions();

  1073   }

  1074 

  1075   /**

  1076    * Implements QueryConditionInterface::arguments().

  1077    */

  1078   public function arguments() {

  1079     return $this->condition->arguments();

  1080   }

  1081 

  1082   /**

  1083    * Implements QueryConditionInterface::where().

  1084    */

  1085   public function where($snippet, $args = array()) {

  1086     $this->condition->where($snippet, $args);

  1087     return $this;

  1088   }

  1089 

  1090   /**

  1091    * Implements QueryConditionInterface::compile().

  1092    */

  1093   public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder) {

  1094     return $this->condition->compile($connection, $queryPlaceholder);

  1095   }

  1096 

  1097   /**

  1098    * Implements QueryConditionInterface::compiled().

  1099    */

  1100   public function compiled() {

  1101     return $this->condition->compiled();

  1102   }

  1103 

  1104   /**

  1105    * Adds a set of field->value pairs to be updated.

  1106    *

  1107    * @param $fields

  1108    *   An associative array of fields to write into the database. The array keys

  1109    *   are the field names and the values are the values to which to set them.

  1110    *

  1111    * @return UpdateQuery

  1112    *   The called object.

  1113    */

  1114   public function fields(array $fields) {

  1115     $this->fields = $fields;

  1116     return $this;

  1117   }

  1118 

  1119   /**

  1120    * Specifies fields to be updated as an expression.

  1121    *

  1122    * Expression fields are cases such as counter=counter+1. This method takes

  1123    * precedence over fields().

  1124    *

  1125    * @param $field

  1126    *   The field to set.

  1127    * @param $expression

  1128    *   The field will be set to the value of this expression. This parameter

  1129    *   may include named placeholders.

  1130    * @param $arguments

  1131    *   If specified, this is an array of key/value pairs for named placeholders

  1132    *   corresponding to the expression.

  1133    *

  1134    * @return UpdateQuery

  1135    *   The called object.

  1136    */