<?php

/**

 * @file

 * Core systems for the database layer.

 *

 * Classes required for basic functioning of the database system should be

 * placed in this file.  All utility functions should also be placed in this

 * file only, as they cannot auto-load the way classes can.

 */

/**

 * @defgroup database Database abstraction layer

 * @{

 * Allow the use of different database servers using the same code base.

 *

 * Drupal provides a database abstraction layer to provide developers with

 * the ability to support multiple database servers easily. The intent of

 * this layer is to preserve the syntax and power of SQL as much as possible,

 * but also allow developers a way to leverage more complex functionality in

 * a unified way. It also provides a structured interface for dynamically

 * constructing queries when appropriate, and enforcing security checks and

 * similar good practices.

 *

 * The system is built atop PHP's PDO (PHP Data Objects) database API and

 * inherits much of its syntax and semantics.

 *

 * Most Drupal database SELECT queries are performed by a call to db_query() or

 * db_query_range(). Module authors should also consider using the PagerDefault

 * Extender for queries that return results that need to be presented on

 * multiple pages (see https://drupal.org/node/508796), and the TableSort

 * Extender for generating appropriate queries for sortable tables

 * (see https://drupal.org/node/1848372).

 *

 * For example, one might wish to return a list of the most recent 10 nodes

 * authored by a given user. Instead of directly issuing the SQL query

 * @code

 * SELECT n.nid, n.title, n.created FROM node n WHERE n.uid = $uid

 *   ORDER BY n.created DESC LIMIT 0, 10;

 * @endcode

 * one would instead call the Drupal functions:

 * @code

 * $result = db_query_range('SELECT n.nid, n.title, n.created

 *   FROM {node} n WHERE n.uid = :uid

 *   ORDER BY n.created DESC', 0, 10, array(':uid' => $uid));

 * foreach ($result as $record) {

 *   // Perform operations on $record->title, etc. here.

 * }

 * @endcode

 * Curly braces are used around "node" to provide table prefixing via

 * DatabaseConnection::prefixTables(). The explicit use of a user ID is pulled

 * out into an argument passed to db_query() so that SQL injection attacks

 * from user input can be caught and nullified. The LIMIT syntax varies between

 * database servers, so that is abstracted into db_query_range() arguments.

 * Finally, note the PDO-based ability to iterate over the result set using

 * foreach ().

 *

 * All queries are passed as a prepared statement string. A

 * prepared statement is a "template" of a query that omits literal or variable

 * values in favor of placeholders. The values to place into those

 * placeholders are passed separately, and the database driver handles

 * inserting the values into the query in a secure fashion. That means you

 * should never quote or string-escape a value to be inserted into the query.

 *

 * There are two formats for placeholders: named and unnamed. Named placeholders

 * are strongly preferred in all cases as they are more flexible and

 * self-documenting. Named placeholders should start with a colon ":" and can be

 * followed by one or more letters, numbers or underscores.

 *

 * Named placeholders begin with a colon followed by a unique string. Example:

 * @code

 * SELECT nid, title FROM {node} WHERE uid=:uid;

 * @endcode

 *

 * ":uid" is a placeholder that will be replaced with a literal value when

 * the query is executed. A given placeholder label cannot be repeated in a

 * given query, even if the value should be the same. When using named

 * placeholders, the array of arguments to the query must be an associative

 * array where keys are a placeholder label (e.g., :uid) and the value is the

 * corresponding value to use. The array may be in any order.

 *

 * Unnamed placeholders are simply a question mark. Example:

 * @code

 * SELECT nid, title FROM {node} WHERE uid=?;

 * @endcode

 *

 * In this case, the array of arguments must be an indexed array of values to

 * use in the exact same order as the placeholders in the query.

 *

 * Note that placeholders should be a "complete" value. For example, when

 * running a LIKE query the SQL wildcard character, %, should be part of the

 * value, not the query itself. Thus, the following is incorrect:

 * @code

 * SELECT nid, title FROM {node} WHERE title LIKE :title%;

 * @endcode

 * It should instead read:

 * @code

 * SELECT nid, title FROM {node} WHERE title LIKE :title;

 * @endcode

 * and the value for :title should include a % as appropriate. Again, note the

 * lack of quotation marks around :title. Because the value is not inserted

 * into the query as one big string but as an explicitly separate value, the

 * database server knows where the query ends and a value begins. That is

 * considerably more secure against SQL injection than trying to remember

 * which values need quotation marks and string escaping and which don't.

 *

 * INSERT, UPDATE, and DELETE queries need special care in order to behave

 * consistently across all different databases. Therefore, they use a special

 * object-oriented API for defining a query structurally. For example, rather

 * than:

 * @code

 * INSERT INTO node (nid, title, body) VALUES (1, 'my title', 'my body');

 * @endcode

 * one would instead write:

 * @code

 * $fields = array('nid' => 1, 'title' => 'my title', 'body' => 'my body');

 * db_insert('node')->fields($fields)->execute();

 * @endcode

 * This method allows databases that need special data type handling to do so,

 * while also allowing optimizations such as multi-insert queries. UPDATE and

 * DELETE queries have a similar pattern.

 *

 * Drupal also supports transactions, including a transparent fallback for

 * databases that do not support transactions. To start a new transaction,

 * simply call $txn = db_transaction(); in your own code. The transaction will

 * remain open for as long as the variable $txn remains in scope.  When $txn is

 * destroyed, the transaction will be committed.  If your transaction is nested

 * inside of another then Drupal will track each transaction and only commit

 * the outer-most transaction when the last transaction object goes out out of

 * scope, that is, all relevant queries completed successfully.

 *

 * Example:

 * @code

 * function my_transaction_function() {

 *   // The transaction opens here.

 *   $txn = db_transaction();

 *

 *   try {

 *     $id = db_insert('example')

 *       ->fields(array(

 *         'field1' => 'mystring',

 *         'field2' => 5,

 *       ))

 *       ->execute();

 *

 *     my_other_function($id);

 *

 *     return $id;

 *   }

 *   catch (Exception $e) {

 *     // Something went wrong somewhere, so roll back now.

 *     $txn->rollback();

 *     // Log the exception to watchdog.

 *     watchdog_exception('type', $e);

 *   }

 *

 *   // $txn goes out of scope here.  Unless the transaction was rolled back, it

 *   // gets automatically committed here.

 * }

 *

 * function my_other_function($id) {

 *   // The transaction is still open here.

 *

 *   if ($id % 2 == 0) {

 *     db_update('example')

 *       ->condition('id', $id)

 *       ->fields(array('field2' => 10))

 *       ->execute();

 *   }

 * }

 * @endcode

 *

 * @see http://drupal.org/developing/api/database

 */

/**

 * Base Database API class.

 *

 * This class provides a Drupal-specific extension of the PDO database

 * abstraction class in PHP. Every database driver implementation must provide a

 * concrete implementation of it to support special handling required by that

 * database.

 *

 * @see http://php.net/manual/book.pdo.php

 */

abstract class DatabaseConnection extends PDO {

  /**

   * The database target this connection is for.

   *

   * We need this information for later auditing and logging.

   *

   * @var string

   */

  protected $target = NULL;

  /**

   * The key representing this connection.

   *

   * The key is a unique string which identifies a database connection. A

   * connection can be a single server or a cluster of master and slaves (use

   * target to pick between master and slave).

   *

   * @var string

   */

  protected $key = NULL;

  /**

   * The current database logging object for this connection.

   *

   * @var DatabaseLog

   */

  protected $logger = NULL;

  /**

   * Tracks the number of "layers" of transactions currently active.

   *

   * On many databases transactions cannot nest.  Instead, we track

   * nested calls to transactions and collapse them into a single

   * transaction.

   *

   * @var array

   */

  protected $transactionLayers = array();

  /**

   * Index of what driver-specific class to use for various operations.

   *

   * @var array

   */

  protected $driverClasses = array();

  /**

   * The name of the Statement class for this connection.

   *

   * @var string

   */

  protected $statementClass = 'DatabaseStatementBase';

  /**

   * Whether this database connection supports transactions.

   *

   * @var bool

   */

  protected $transactionSupport = TRUE;

  /**

   * Whether this database connection supports transactional DDL.

   *

   * Set to FALSE by default because few databases support this feature.

   *

   * @var bool

   */

  protected $transactionalDDLSupport = FALSE;

  /**

   * An index used to generate unique temporary table names.

   *

   * @var integer

   */

  protected $temporaryNameIndex = 0;

  /**

   * The connection information for this connection object.

   *

   * @var array

   */

  protected $connectionOptions = array();

  /**

   * The schema object for this connection.

   *

   * @var object

   */

  protected $schema = NULL;

  /**

   * The prefixes used by this database connection.

   *

   * @var array

   */

  protected $prefixes = array();

  /**

   * List of search values for use in prefixTables().

   *

   * @var array

   */

  protected $prefixSearch = array();

  /**

   * List of replacement values for use in prefixTables().

   *

   * @var array

   */

  protected $prefixReplace = array();

  /**

   * List of escaped database, table, and field names, keyed by unescaped names.

   *

   * @var array

   */

  protected $escapedNames = array();

  /**

   * List of escaped aliases names, keyed by unescaped aliases.

   *

   * @var array

   */

  protected $escapedAliases = array();

  function __construct($dsn, $username, $password, $driver_options = array()) {

    // Initialize and prepare the connection prefix.

    $this->setPrefix(isset($this->connectionOptions['prefix']) ? $this->connectionOptions['prefix'] : '');

    // Because the other methods don't seem to work right.

    $driver_options[PDO::ATTR_ERRMODE] = PDO::ERRMODE_EXCEPTION;

    // Call PDO::__construct and PDO::setAttribute.

    parent::__construct($dsn, $username, $password, $driver_options);

    // Set a Statement class, unless the driver opted out.

    if (!empty($this->statementClass)) {

      $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array($this->statementClass, array($this)));

    }

  }

  /**

   * Destroys this Connection object.

   *

   * PHP does not destruct an object if it is still referenced in other

   * variables. In case of PDO database connection objects, PHP only closes the

   * connection when the PDO object is destructed, so any references to this

   * object may cause the number of maximum allowed connections to be exceeded.

   */

  public function destroy() {

    // Destroy all references to this connection by setting them to NULL.

    // The Statement class attribute only accepts a new value that presents a

    // proper callable, so we reset it to PDOStatement.

    $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array('PDOStatement', array()));

    $this->schema = NULL;

  }

  /**

   * Returns the default query options for any given query.

   *

   * A given query can be customized with a number of option flags in an

   * associative array:

   * - target: The database "target" against which to execute a query. Valid

   *   values are "default" or "slave". The system will first try to open a

   *   connection to a database specified with the user-supplied key. If one

   *   is not available, it will silently fall back to the "default" target.

   *   If multiple databases connections are specified with the same target,

   *   one will be selected at random for the duration of the request.

   * - fetch: This element controls how rows from a result set will be

   *   returned. Legal values include PDO::FETCH_ASSOC, PDO::FETCH_BOTH,

   *   PDO::FETCH_OBJ, PDO::FETCH_NUM, or a string representing the name of a

   *   class. If a string is specified, each record will be fetched into a new

   *   object of that class. The behavior of all other values is defined by PDO.

   *   See http://php.net/manual/pdostatement.fetch.php

   * - return: Depending on the type of query, different return values may be

   *   meaningful. This directive instructs the system which type of return

   *   value is desired. The system will generally set the correct value

   *   automatically, so it is extremely rare that a module developer will ever

   *   need to specify this value. Setting it incorrectly will likely lead to

   *   unpredictable results or fatal errors. Legal values include:

   *   - Database::RETURN_STATEMENT: Return the prepared statement object for

   *     the query. This is usually only meaningful for SELECT queries, where

   *     the statement object is how one accesses the result set returned by the

   *     query.

   *   - Database::RETURN_AFFECTED: Return the number of rows affected by an

   *     UPDATE or DELETE query. Be aware that means the number of rows actually

   *     changed, not the number of rows matched by the WHERE clause.

   *   - Database::RETURN_INSERT_ID: Return the sequence ID (primary key)

   *     created by an INSERT statement on a table that contains a serial

   *     column.

   *   - Database::RETURN_NULL: Do not return anything, as there is no

   *     meaningful value to return. That is the case for INSERT queries on

   *     tables that do not contain a serial column.

   * - throw_exception: By default, the database system will catch any errors

   *   on a query as an Exception, log it, and then rethrow it so that code

   *   further up the call chain can take an appropriate action. To suppress

   *   that behavior and simply return NULL on failure, set this option to

   *   FALSE.

   *

   * @return

   *   An array of default query options.

   */

  protected function defaultOptions() {

    return array(

      'target' => 'default',

      'fetch' => PDO::FETCH_OBJ,

      'return' => Database::RETURN_STATEMENT,

      'throw_exception' => TRUE,

    );

  }

  /**

   * Returns the connection information for this connection object.

   *

   * Note that Database::getConnectionInfo() is for requesting information

   * about an arbitrary database connection that is defined. This method

   * is for requesting the connection information of this specific

   * open connection object.

   *

   * @return

   *   An array of the connection information. The exact list of

   *   properties is driver-dependent.

   */

  public function getConnectionOptions() {

    return $this->connectionOptions;

  }

  /**

   * Set the list of prefixes used by this database connection.

   *

   * @param $prefix

   *   The prefixes, in any of the multiple forms documented in

   *   default.settings.php.

   */

  protected function setPrefix($prefix) {

    if (is_array($prefix)) {

      $this->prefixes = $prefix + array('default' => '');

    }

    else {

      $this->prefixes = array('default' => $prefix);

    }

    // Set up variables for use in prefixTables(). Replace table-specific

    // prefixes first.

    $this->prefixSearch = array();

    $this->prefixReplace = array();

    foreach ($this->prefixes as $key => $val) {

      if ($key != 'default') {

        $this->prefixSearch[] = '{' . $key . '}';

        $this->prefixReplace[] = $val . $key;

      }

    }

    // Then replace remaining tables with the default prefix.

    $this->prefixSearch[] = '{';

    $this->prefixReplace[] = $this->prefixes['default'];

    $this->prefixSearch[] = '}';

    $this->prefixReplace[] = '';

  }

  /**

   * Appends a database prefix to all tables in a query.

   *

   * Queries sent to Drupal should wrap all table names in curly brackets. This

   * function searches for this syntax and adds Drupal's table prefix to all

   * tables, allowing Drupal to coexist with other systems in the same database

   * and/or schema if necessary.

   *

   * @param $sql

   *   A string containing a partial or entire SQL query.

   *

   * @return

   *   The properly-prefixed string.

   */

  public function prefixTables($sql) {

    return str_replace($this->prefixSearch, $this->prefixReplace, $sql);

  }

  /**

   * Find the prefix for a table.

   *

   * This function is for when you want to know the prefix of a table. This

   * is not used in prefixTables due to performance reasons.

   */

  public function tablePrefix($table = 'default') {

    if (isset($this->prefixes[$table])) {

      return $this->prefixes[$table];

    }

    else {

      return $this->prefixes['default'];