<?php

/**

 * @addtogroup database

 * @{

 */

/**

 * @file

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

 */

/**

 * Interface for a conditional clause in a query.

 */

interface QueryConditionInterface {

  /**

   * Helper function: builds the most common conditional clauses.

   *

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

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

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

   *

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

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

   *

   * @param $field

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

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

   * @param $value

   *   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 dependent on the $operator.

   * @param $operator

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

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

   *   an array, and = otherwise.

   *

   * @return QueryConditionInterface

   *   The called object.

   *

   * @see QueryConditionInterface::isNull()

   * @see QueryConditionInterface::isNotNull()

   */

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

  /**

   * Adds an arbitrary WHERE clause to the query.

   *

   * @param $snippet

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

   *   placeholders, not ? placeholders.

   * @param $args

   *   An associative array of arguments.

   *

   * @return QueryConditionInterface

   *   The called object.

   */

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

  /**

   * Sets a condition that the specified field be NULL.

   *

   * @param $field

   *   The name of the field to check.

   *

   * @return QueryConditionInterface

   *   The called object.

   */

  public function isNull($field);

  /**

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

   *

   * @param $field

   *   The name of the field to check.

   *

   * @return QueryConditionInterface

   *   The called object.

   */

  public function isNotNull($field);

  /**

   * Sets a condition that the specified subquery returns values.

   *

   * @param SelectQueryInterface $select

   *   The subquery that must contain results.

   *

   * @return QueryConditionInterface

   *   The called object.

   */

  public function exists(SelectQueryInterface $select);

  /**

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

   *

   * @param SelectQueryInterface $select

   *   The subquery that must not contain results.

   *

   * @return QueryConditionInterface

   *   The called object.

   */

  public function notExists(SelectQueryInterface $select);

  /**

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

   *

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

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

   *

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

   * each entry looks like the following:

   * @code

   * array(

   *   'field' => $field,

   *   'value' => $value,

   *   'operator' => $operator,

   * );

   * @endcode

   *

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

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

   * array of placeholders for the snippet.

   *

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

   * 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.

   *

   * @return

   *   An associative array of placeholders and values.

   */

  public function arguments();

  /**

   * 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.

   * @param $queryPlaceholder

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

   *   used.

   */

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

  /**

   * Check whether a condition has been previously compiled.

   *

   * @return

   *   TRUE if the condition has been previously compiled.

   */

  public function compiled();

}

/**

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

 */

interface QueryAlterableInterface {

  /**

   * Adds a tag to a query.

   *

   * 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 follow the same rules as PHP identifiers in general.

   *

   * @param $tag

   *   The tag to add.

   *

   * @return QueryAlterableInterface

   *   The called object.

   */

  public function addTag($tag);

  /**

   * 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);

  /**

   * 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();

  /**

   * Adds additional metadata to the query.

   *

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

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

   * to take action.

   *

   * @param $key

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

   *   follows the same rules as any other PHP identifier.

   * @param $object

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

   *

   * @return QueryAlterableInterface

   *   The called object.

   */

  public function addMetaData($key, $object);

  /**

   * 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);

}

/**

 * Interface for a query that accepts placeholders.

 */

interface QueryPlaceholderInterface {

  /**

   * Returns a unique identifier for this object.

   */

  public function uniqueIdentifier();

  /**

   * Returns the next placeholder ID for the query.

   *

   * @return

   *   The next available placeholder ID as an integer.

   */

  public function nextPlaceholder();

}

/**

 * Base class for query builders.

 *

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

 * query object into a prepared statement.

 */

abstract class Query implements QueryPlaceholderInterface {

  /**

   * The connection object on which to run this query.

   *

   * @var DatabaseConnection

   */

  protected $connection;

  /**

   * The target of the connection object.

   *

   * @var string

   */

  protected $connectionTarget;

  /**

   * The key of the connection object.

   *

   * @var string

   */

  protected $connectionKey;

  /**

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

   *

   * @var array

   */

  protected $queryOptions;

  /**

   * A unique identifier for this query object.

   */

  protected $uniqueIdentifier;

  /**

   * The placeholder counter.

   */

  protected $nextPlaceholder = 0;

  /**

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

   *

   * @var array

   */

  protected $comments = array();

  /**

   * Constructs a Query object.

   *

   * @param DatabaseConnection $connection

   *   Database connection object.

   * @param array $options

   *   Array of query options.

   */

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

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

    $this->connection = $connection;

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

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

    $this->queryOptions = $options;

  }

  /**

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

   */

  public function __sleep() {

    $keys = get_object_vars($this);

    unset($keys['connection']);

    return array_keys($keys);

  }

  /**

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

   */

  public function __wakeup() {

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

  }

  /**

   * Implements the magic __clone function.

   */

  public function __clone() {

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

  }

  /**

   * Runs the query against the database.

   */

  abstract protected function execute();

  /**

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

   *

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

   * statement.

   *

   * @return

   *   A prepared statement query string for this object.

   */

  abstract public function __toString();

  /**

   * Returns a unique identifier for this object.

   */

  public function uniqueIdentifier() {

    return $this->uniqueIdentifier;

  }

  /**

   * Gets the next placeholder value for this query object.

   *

   * @return int

   *   Next placeholder value.

   */

  public function nextPlaceholder() {

    return $this->nextPlaceholder++;

  }

  /**

   * Adds a comment to the query.

   *

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

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

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

   * with a performance problem is being generated.

   *

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

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

   *

   * @param $comment

   *   The comment string to be inserted into the query.

   *

   * @return Query

   *   The called object.

   */

  public function comment($comment) {

    $this->comments[] = $comment;

    return $this;

  }

  /**

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

   *

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

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

   * use of comment() is preferred.

   *

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

   * @code

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

   * @endcode

   *

   * @return

   *   A reference to the comments array structure.

   */

  public function &getComments() {

    return $this->comments;

  }

}

/**

 * General class for an abstracted INSERT query.

 */

class InsertQuery 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 that should be set to their database-defined defaults.

   *

   * @var array

   */

  protected $defaultFields = array();

  /**

   * A nested array of values to insert.

   *

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

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

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

   * as $insertFields.

   *

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

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

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

   * order of fields in $insertFields.

   *

   * @var array

   */

  protected $insertValues = array();

  /**