is7JP97x

1<?php
2
3/**
4 * @file
5 * Core systems for the database layer.
6 *
7 * Classes required for basic functioning of the database system should be
8 * placed in this file.  All utility functions should also be placed in this
9 * file only, as they cannot auto-load the way classes can.
10 */
11
12/**
13 * @defgroup database Database abstraction layer
14 * @{
15 * Allow the use of different database servers using the same code base.
16 *
17 * Drupal provides a database abstraction layer to provide developers with
18 * the ability to support multiple database servers easily. The intent of
19 * this layer is to preserve the syntax and power of SQL as much as possible,
20 * but also allow developers a way to leverage more complex functionality in
21 * a unified way. It also provides a structured interface for dynamically
22 * constructing queries when appropriate, and enforcing security checks and
23 * similar good practices.
24 *
25 * The system is built atop PHP's PDO (PHP Data Objects) database API and
26 * inherits much of its syntax and semantics.
27 *
28 * Most Drupal database SELECT queries are performed by a call to db_query() or
29 * db_query_range(). Module authors should also consider using the PagerDefault
30 * Extender for queries that return results that need to be presented on
31 * multiple pages (see https://drupal.org/node/508796), and the TableSort
32 * Extender for generating appropriate queries for sortable tables
33 * (see https://drupal.org/node/1848372).
34 *
35 * For example, one might wish to return a list of the most recent 10 nodes
36 * authored by a given user. Instead of directly issuing the SQL query
37 * @code
38 * SELECT n.nid, n.title, n.created FROM node n WHERE n.uid = $uid
39 *   ORDER BY n.created DESC LIMIT 0, 10;
40 * @endcode
41 * one would instead call the Drupal functions:
42 * @code
43 * $result = db_query_range('SELECT n.nid, n.title, n.created
44 *   FROM {node} n WHERE n.uid = :uid
45 *   ORDER BY n.created DESC', 0, 10, array(':uid' => $uid));
46 * foreach ($result as $record) {
47 *   // Perform operations on $record->title, etc. here.
48 * }
49 * @endcode
50 * Curly braces are used around "node" to provide table prefixing via
51 * DatabaseConnection::prefixTables(). The explicit use of a user ID is pulled
52 * out into an argument passed to db_query() so that SQL injection attacks
53 * from user input can be caught and nullified. The LIMIT syntax varies between
54 * database servers, so that is abstracted into db_query_range() arguments.
55 * Finally, note the PDO-based ability to iterate over the result set using
56 * foreach ().
57 *
58 * All queries are passed as a prepared statement string. A
59 * prepared statement is a "template" of a query that omits literal or variable
60 * values in favor of placeholders. The values to place into those
61 * placeholders are passed separately, and the database driver handles
62 * inserting the values into the query in a secure fashion. That means you
63 * should never quote or string-escape a value to be inserted into the query.
64 *
65 * There are two formats for placeholders: named and unnamed. Named placeholders
66 * are strongly preferred in all cases as they are more flexible and
67 * self-documenting. Named placeholders should start with a colon ":" and can be
68 * followed by one or more letters, numbers or underscores.
69 *
70 * Named placeholders begin with a colon followed by a unique string. Example:
71 * @code
72 * SELECT nid, title FROM {node} WHERE uid=:uid;
73 * @endcode
74 *
75 * ":uid" is a placeholder that will be replaced with a literal value when
76 * the query is executed. A given placeholder label cannot be repeated in a
77 * given query, even if the value should be the same. When using named
78 * placeholders, the array of arguments to the query must be an associative
79 * array where keys are a placeholder label (e.g., :uid) and the value is the
80 * corresponding value to use. The array may be in any order.
81 *
82 * Unnamed placeholders are simply a question mark. Example:
83 * @code
84 * SELECT nid, title FROM {node} WHERE uid=?;
85 * @endcode
86 *
87 * In this case, the array of arguments must be an indexed array of values to
88 * use in the exact same order as the placeholders in the query.
89 *
90 * Note that placeholders should be a "complete" value. For example, when
91 * running a LIKE query the SQL wildcard character, %, should be part of the
92 * value, not the query itself. Thus, the following is incorrect:
93 * @code
94 * SELECT nid, title FROM {node} WHERE title LIKE :title%;
95 * @endcode
96 * It should instead read:
97 * @code
98 * SELECT nid, title FROM {node} WHERE title LIKE :title;
99 * @endcode
100 * and the value for :title should include a % as appropriate. Again, note the
101 * lack of quotation marks around :title. Because the value is not inserted
102 * into the query as one big string but as an explicitly separate value, the
103 * database server knows where the query ends and a value begins. That is
104 * considerably more secure against SQL injection than trying to remember
105 * which values need quotation marks and string escaping and which don't.
106 *
107 * INSERT, UPDATE, and DELETE queries need special care in order to behave
108 * consistently across all different databases. Therefore, they use a special
109 * object-oriented API for defining a query structurally. For example, rather
110 * than:
111 * @code
112 * INSERT INTO node (nid, title, body) VALUES (1, 'my title', 'my body');
113 * @endcode
114 * one would instead write:
115 * @code
116 * $fields = array('nid' => 1, 'title' => 'my title', 'body' => 'my body');
117 * db_insert('node')->fields($fields)->execute();
118 * @endcode
119 * This method allows databases that need special data type handling to do so,
120 * while also allowing optimizations such as multi-insert queries. UPDATE and
121 * DELETE queries have a similar pattern.
122 *
123 * Drupal also supports transactions, including a transparent fallback for
124 * databases that do not support transactions. To start a new transaction,
125 * simply call $txn = db_transaction(); in your own code. The transaction will
126 * remain open for as long as the variable $txn remains in scope.  When $txn is
127 * destroyed, the transaction will be committed.  If your transaction is nested
128 * inside of another then Drupal will track each transaction and only commit
129 * the outer-most transaction when the last transaction object goes out out of
130 * scope, that is, all relevant queries completed successfully.
131 *
132 * Example:
133 * @code
134 * function my_transaction_function() {
135 *   // The transaction opens here.
136 *   $txn = db_transaction();
137 *
138 *   try {
139 *     $id = db_insert('example')
140 *       ->fields(array(
141 *         'field1' => 'mystring',
142 *         'field2' => 5,
143 *       ))
144 *       ->execute();
145 *
146 *     my_other_function($id);
147 *
148 *     return $id;
149 *   }
150 *   catch (Exception $e) {
151 *     // Something went wrong somewhere, so roll back now.
152 *     $txn->rollback();
153 *     // Log the exception to watchdog.
154 *     watchdog_exception('type', $e);
155 *   }
156 *
157 *   // $txn goes out of scope here.  Unless the transaction was rolled back, it
158 *   // gets automatically committed here.
159 * }
160 *
161 * function my_other_function($id) {
162 *   // The transaction is still open here.
163 *
164 *   if ($id % 2 == 0) {
165 *     db_update('example')
166 *       ->condition('id', $id)
167 *       ->fields(array('field2' => 10))
168 *       ->execute();
169 *   }
170 * }
171 * @endcode
172 *
173 * @see http://drupal.org/developing/api/database
174 */
175
176
177/**
178 * Base Database API class.
179 *
180 * This class provides a Drupal-specific extension of the PDO database
181 * abstraction class in PHP. Every database driver implementation must provide a
182 * concrete implementation of it to support special handling required by that
183 * database.
184 *
185 * @see http://php.net/manual/book.pdo.php
186 */
187abstract class DatabaseConnection extends PDO {
188
189  /**
190   * The database target this connection is for.
191   *
192   * We need this information for later auditing and logging.
193   *
194   * @var string
195   */
196  protected $target = NULL;
197
198  /**
199   * The key representing this connection.
200   *
201   * The key is a unique string which identifies a database connection. A
202   * connection can be a single server or a cluster of master and slaves (use
203   * target to pick between master and slave).
204   *
205   * @var string
206   */
207  protected $key = NULL;
208
209  /**
210   * The current database logging object for this connection.
211   *
212   * @var DatabaseLog
213   */
214  protected $logger = NULL;
215
216  /**
217   * Tracks the number of "layers" of transactions currently active.
218   *
219   * On many databases transactions cannot nest.  Instead, we track
220   * nested calls to transactions and collapse them into a single
221   * transaction.
222   *
223   * @var array
224   */
225  protected $transactionLayers = array();
226
227  /**
228   * Index of what driver-specific class to use for various operations.
229   *
230   * @var array
231   */
232  protected $driverClasses = array();
233
234  /**
235   * The name of the Statement class for this connection.
236   *
237   * @var string
238   */
239  protected $statementClass = 'DatabaseStatementBase';
240
241  /**
242   * Whether this database connection supports transactions.
243   *
244   * @var bool
245   */
246  protected $transactionSupport = TRUE;
247
248  /**
249   * Whether this database connection supports transactional DDL.
250   *
251   * Set to FALSE by default because few databases support this feature.
252   *
253   * @var bool
254   */
255  protected $transactionalDDLSupport = FALSE;
256
257  /**
258   * An index used to generate unique temporary table names.
259   *
260   * @var integer
261   */
262  protected $temporaryNameIndex = 0;
263
264  /**
265   * The connection information for this connection object.
266   *
267   * @var array
268   */
269  protected $connectionOptions = array();
270
271  /**
272   * The schema object for this connection.
273   *
274   * @var object
275   */
276  protected $schema = NULL;
277
278  /**
279   * The prefixes used by this database connection.
280   *
281   * @var array
282   */
283  protected $prefixes = array();
284
285  /**
286   * List of search values for use in prefixTables().
287   *
288   * @var array
289   */
290  protected $prefixSearch = array();
291
292  /**
293   * List of replacement values for use in prefixTables().
294   *
295   * @var array
296   */
297  protected $prefixReplace = array();
298
299  function __construct($dsn, $username, $password, $driver_options = array()) {
300    // Initialize and prepare the connection prefix.
301    $this->setPrefix(isset($this->connectionOptions['prefix']) ? $this->connectionOptions['prefix'] : '');
302
303    // Because the other methods don't seem to work right.
304    $driver_options[PDO::ATTR_ERRMODE] = PDO::ERRMODE_EXCEPTION;
305
306    // Call PDO::__construct and PDO::setAttribute.
307    parent::__construct($dsn, $username, $password, $driver_options);
308
309    // Set a Statement class, unless the driver opted out.
310    if (!empty($this->statementClass)) {
311      $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array($this->statementClass, array($this)));
312    }
313  }
314
315  /**
316   * Destroys this Connection object.
317   *
318   * PHP does not destruct an object if it is still referenced in other
319   * variables. In case of PDO database connection objects, PHP only closes the
320   * connection when the PDO object is destructed, so any references to this
321   * object may cause the number of maximum allowed connections to be exceeded.
322   */
323  public function destroy() {
324    // Destroy all references to this connection by setting them to NULL.
325    // The Statement class attribute only accepts a new value that presents a
326    // proper callable, so we reset it to PDOStatement.
327    $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array('PDOStatement', array()));
328    $this->schema = NULL;
329  }
330
331  /**
332   * Returns the default query options for any given query.
333   *
334   * A given query can be customized with a number of option flags in an
335   * associative array:
336   * - target: The database "target" against which to execute a query. Valid
337   *   values are "default" or "slave". The system will first try to open a
338   *   connection to a database specified with the user-supplied key. If one
339   *   is not available, it will silently fall back to the "default" target.
340   *   If multiple databases connections are specified with the same target,
341   *   one will be selected at random for the duration of the request.
342   * - fetch: This element controls how rows from a result set will be
343   *   returned. Legal values include PDO::FETCH_ASSOC, PDO::FETCH_BOTH,
344   *   PDO::FETCH_OBJ, PDO::FETCH_NUM, or a string representing the name of a
345   *   class. If a string is specified, each record will be fetched into a new
346   *   object of that class. The behavior of all other values is defined by PDO.
347   *   See http://php.net/manual/pdostatement.fetch.php
348   * - return: Depending on the type of query, different return values may be
349   *   meaningful. This directive instructs the system which type of return
350   *   value is desired. The system will generally set the correct value
351   *   automatically, so it is extremely rare that a module developer will ever
352   *   need to specify this value. Setting it incorrectly will likely lead to
353   *   unpredictable results or fatal errors. Legal values include:
354   *   - Database::RETURN_STATEMENT: Return the prepared statement object for
355   *     the query. This is usually only meaningful for SELECT queries, where
356   *     the statement object is how one accesses the result set returned by the
357   *     query.
358   *   - Database::RETURN_AFFECTED: Return the number of rows affected by an
359   *     UPDATE or DELETE query. Be aware that means the number of rows actually
360   *     changed, not the number of rows matched by the WHERE clause.
361   *   - Database::RETURN_INSERT_ID: Return the sequence ID (primary key)
362   *     created by an INSERT statement on a table that contains a serial
363   *     column.
364   *   - Database::RETURN_NULL: Do not return anything, as there is no
365   *     meaningful value to return. That is the case for INSERT queries on
366   *     tables that do not contain a serial column.
367   * - throw_exception: By default, the database system will catch any errors
368   *   on a query as an Exception, log it, and then rethrow it so that code
369   *   further up the call chain can take an appropriate action. To suppress
370   *   that behavior and simply return NULL on failure, set this option to
371   *   FALSE.
372   *
373   * @return
374   *   An array of default query options.
375   */
376  protected function defaultOptions() {
377    return array(
378      'target' => 'default',
379      'fetch' => PDO::FETCH_OBJ,
380      'return' => Database::RETURN_STATEMENT,
381      'throw_exception' => TRUE,
382    );
383  }
384
385  /**
386   * Returns the connection information for this connection object.
387   *
388   * Note that Database::getConnectionInfo() is for requesting information
389   * about an arbitrary database connection that is defined. This method
390   * is for requesting the connection information of this specific
391   * open connection object.
392   *
393   * @return
394   *   An array of the connection information. The exact list of
395   *   properties is driver-dependent.
396   */
397  public function getConnectionOptions() {
398    return $this->connectionOptions;
399  }
400
401  /**
402   * Set the list of prefixes used by this database connection.
403   *
404   * @param $prefix
405   *   The prefixes, in any of the multiple forms documented in
406   *   default.settings.php.
407   */
408  protected function setPrefix($prefix) {
409    if (is_array($prefix)) {
410      $this->prefixes = $prefix + array('default' => '');
411    }
412    else {
413      $this->prefixes = array('default' => $prefix);
414    }
415
416    // Set up variables for use in prefixTables(). Replace table-specific
417    // prefixes first.
418    $this->prefixSearch = array();
419    $this->prefixReplace = array();
420    foreach ($this->prefixes as $key => $val) {
421      if ($key != 'default') {
422        $this->prefixSearch[] = '{' . $key . '}';
423        $this->prefixReplace[] = $val . $key;
424      }
425    }
426    // Then replace remaining tables with the default prefix.
427    $this->prefixSearch[] = '{';
428    $this->prefixReplace[] = $this->prefixes['default'];
429    $this->prefixSearch[] = '}';
430    $this->prefixReplace[] = '';
431  }
432
433  /**
434   * Appends a database prefix to all tables in a query.
435   *
436   * Queries sent to Drupal should wrap all table names in curly brackets. This
437   * function searches for this syntax and adds Drupal's table prefix to all
438   * tables, allowing Drupal to coexist with other systems in the same database
439   * and/or schema if necessary.
440   *
441   * @param $sql
442   *   A string containing a partial or entire SQL query.
443   *
444   * @return
445   *   The properly-prefixed string.
446   */
447  public function prefixTables($sql) {
448    return str_replace($this->prefixSearch, $this->prefixReplace, $sql);
449  }
450
451  /**
452   * Find the prefix for a table.
453   *
454   * This function is for when you want to know the prefix of a table. This
455   * is not used in prefixTables due to performance reasons.
456   */
457  public function tablePrefix($table = 'default') {
458    if (isset($this->prefixes[$table])) {
459      return $this->prefixes[$table];
460    }
461    else {
462      return $this->prefixes['default'];
463    }
464  }
465
466  /**
467   * Prepares a query string and returns the prepared statement.
468   *
469   * This method caches prepared statements, reusing them when
470   * possible. It also prefixes tables names enclosed in curly-braces.
471   *
472   * @param $query
473   *   The query string as SQL, with curly-braces surrounding the
474   *   table names.
475   *
476   * @return DatabaseStatementInterface
477   *   A PDO prepared statement ready for its execute() method.
478   */
479  public function prepareQuery($query) {
480    $query = $this->prefixTables($query);
481
482    // Call PDO::prepare.
483    return parent::prepare($query);
484  }
485
486  /**
487   * Tells this connection object what its target value is.
488   *
489   * This is needed for logging and auditing. It's sloppy to do in the
490   * constructor because the constructor for child classes has a different
491   * signature. We therefore also ensure that this function is only ever
492   * called once.
493   *
494   * @param $target
495   *   The target this connection is for. Set to NULL (default) to disable
496   *   logging entirely.
497   */
498  public function setTarget($target = NULL) {
499    if (!isset($this->target)) {
500      $this->target = $target;
501    }
502  }
503
504  /**
505   * Returns the target this connection is associated with.
506   *
507   * @return
508   *   The target string of this connection.
509   */
510  public function getTarget() {
511    return $this->target;
512  }
513
514  /**
515   * Tells this connection object what its key is.
516   *
517   * @param $target
518   *   The key this connection is for.
519   */
520  public function setKey($key) {
521    if (!isset($this->key)) {
522      $this->key = $key;
523    }
524  }
525
526  /**
527   * Returns the key this connection is associated with.
528   *
529   * @return
530   *   The key of this connection.
531   */
532  public function getKey() {
533    return $this->key;
534  }
535
536  /**
537   * Associates a logging object with this connection.
538   *
539   * @param $logger
540   *   The logging object we want to use.
541   */
542  public function setLogger(DatabaseLog $logger) {
543    $this->logger = $logger;
544  }
545
546  /**
547   * Gets the current logging object for this connection.
548   *
549   * @return DatabaseLog
550   *   The current logging object for this connection. If there isn't one,
551   *   NULL is returned.
552   */
553  public function getLogger() {
554    return $this->logger;
555  }
556
557  /**
558   * Creates the appropriate sequence name for a given table and serial field.
559   *
560   * This information is exposed to all database drivers, although it is only
561   * useful on some of them. This method is table prefix-aware.
562   *
563   * @param $table
564   *   The table name to use for the sequence.
565   * @param $field
566   *   The field name to use for the sequence.
567   *
568   * @return
569   *   A table prefix-parsed string for the sequence name.
570   */
571  public function makeSequenceName($table, $field) {
572    return $this->prefixTables('{' . $table . '}_' . $field . '_seq');
573  }
574
575  /**
576   * Flatten an array of query comments into a single comment string.
577   *
578   * The comment string will be sanitized to avoid SQL injection attacks.
579   *
580   * @param $comments
581   *   An array of query comment strings.
582   *
583   * @return
584   *   A sanitized comment string.
585   */
586  public function makeComment($comments) {
587    if (empty($comments))
588      return '';
589
590    // Flatten the array of comments.
591    $comment = implode('; ', $comments);
592
593    // Sanitize the comment string so as to avoid SQL injection attacks.
594    return '/* ' . $this->filterComment($comment) . ' */ ';
595  }
596
597  /**
598   * Sanitize a query comment string.
599   *
600   * Ensure a query comment does not include strings such as "* /" that might
601   * terminate the comment early. This avoids SQL injection attacks via the
602   * query comment. The comment strings in this example are separated by a
603   * space to avoid PHP parse errors.
604   *
605   * For example, the comment:
606   * @code
607   * db_update('example')
608   *  ->condition('id', $id)
609   *  ->fields(array('field2' => 10))
610   *  ->comment('Exploit * / DROP TABLE node; --')
611   *  ->execute()
612   * @endcode
613   *
614   * Would result in the following SQL statement being generated:
615   * @code
616   * "/ * Exploit * / DROP TABLE node; -- * / UPDATE example SET field2=..."
617   * @endcode
618   *
619   * Unless the comment is sanitised first, the SQL server would drop the
620   * node table and ignore the rest of the SQL statement.
621   *
622   * @param $comment
623   *   A query comment string.
624   *
625   * @return
626   *   A sanitized version of the query comment string.
627   */
628  protected function filterComment($comment = '') {
629    return preg_replace('/(\/\*\s*)|(\s*\*\/)/', '', $comment);
630  }
631
632  /**
633   * Executes a query string against the database.
634   *
635   * This method provides a central handler for the actual execution of every
636   * query. All queries executed by Drupal are executed as PDO prepared
637   * statements.
638   *
639   * @param $query
640   *   The query to execute. In most cases this will be a string containing
641   *   an SQL query with placeholders. An already-prepared instance of
642   *   DatabaseStatementInterface may also be passed in order to allow calling
643   *   code to manually bind variables to a query. If a
644   *   DatabaseStatementInterface is passed, the $args array will be ignored.
645   *   It is extremely rare that module code will need to pass a statement
646   *   object to this method. It is used primarily for database drivers for
647   *   databases that require special LOB field handling.
648   * @param $args
649   *   An array of arguments for the prepared statement. If the prepared
650   *   statement uses ? placeholders, this array must be an indexed array.
651   *   If it contains named placeholders, it must be an associative array.
652   * @param $options
653   *   An associative array of options to control how the query is run. See
654   *   the documentation for DatabaseConnection::defaultOptions() for details.
655   *
656   * @return DatabaseStatementInterface
657   *   This method will return one of: the executed statement, the number of
658   *   rows affected by the query (not the number matched), or the generated
659   *   insert IT of the last query, depending on the value of
660   *   $options['return']. Typically that value will be set by default or a
661   *   query builder and should not be set by a user. If there is an error,
662   *   this method will return NULL and may throw an exception if
663   *   $options['throw_exception'] is TRUE.
664   *
665   * @throws PDOException
666   */
667  public function query($query, array $args = array(), $options = array()) {
668
669    // Use default values if not already set.
670    $options += $this->defaultOptions();
671
672    try {
673      // We allow either a pre-bound statement object or a literal string.
674      // In either case, we want to end up with an executed statement object,
675      // which we pass to PDOStatement::execute.
676      if ($query instanceof DatabaseStatementInterface) {
677        $stmt = $query;
678        $stmt->execute(NULL, $options);
679      }
680      else {
681        $this->expandArguments($query, $args);
682        $stmt = $this->prepareQuery($query);
683        $stmt->execute($args, $options);
684      }
685
686      // Depending on the type of query we may need to return a different value.
687      // See DatabaseConnection::defaultOptions() for a description of each
688      // value.
689      switch ($options['return']) {
690        case Database::RETURN_STATEMENT:
691          return $stmt;
692        case Database::RETURN_AFFECTED:
693          return $stmt->rowCount();
694        case Database::RETURN_INSERT_ID:
695          return $this->lastInsertId();
696        case Database::RETURN_NULL:
697          return;
698        default:
699          throw new PDOException('Invalid return directive: ' . $options['return']);
700      }
701    }
702    catch (PDOException $e) {
703      if ($options['throw_exception']) {
704        // Add additional debug information.
705        if ($query instanceof DatabaseStatementInterface) {
706          $e->query_string = $stmt->getQueryString();
707        }
708        else {
709          $e->query_string = $query;
710        }
711        $e->args = $args;
712        throw $e;
713      }
714      return NULL;
715    }
716  }
717
718  /**
719   * Expands out shorthand placeholders.
720   *
721   * Drupal supports an alternate syntax for doing arrays of values. We
722   * therefore need to expand them out into a full, executable query string.
723   *
724   * @param $query
725   *   The query string to modify.
726   * @param $args
727   *   The arguments for the query.
728   *
729   * @return
730   *   TRUE if the query was modified, FALSE otherwise.
731   */
732  protected function expandArguments(&$query, &$args) {
733    $modified = FALSE;
734
735    // If the placeholder value to insert is an array, assume that we need
736    // to expand it out into a comma-delimited set of placeholders.
737    foreach (array_filter($args, 'is_array') as $key => $data) {
738      $new_keys = array();
739      foreach (array_values($data) as $i => $value) {
740        // This assumes that there are no other placeholders that use the same
741        // name.  For example, if the array placeholder is defined as :example
742        // and there is already an :example_2 placeholder, this will generate
743        // a duplicate key.  We do not account for that as the calling code
744        // is already broken if that happens.
745        $new_keys[$key . '_' . $i] = $value;
746      }
747
748      // Update the query with the new placeholders.
749      // preg_replace is necessary to ensure the replacement does not affect
750      // placeholders that start with the same exact text. For example, if the
751      // query contains the placeholders :foo and :foobar, and :foo has an
752      // array of values, using str_replace would affect both placeholders,
753      // but using the following preg_replace would only affect :foo because
754      // it is followed by a non-word character.
755      $query = preg_replace('#' . $key . '\b#', implode(', ', array_keys($new_keys)), $query);
756
757      // Update the args array with the new placeholders.
758      unset($args[$key]);
759      $args += $new_keys;
760
761      $modified = TRUE;
762    }
763
764    return $modified;
765  }
766
767  /**
768   * Gets the driver-specific override class if any for the specified class.
769   *
770   * @param string $class
771   *   The class for which we want the potentially driver-specific class.
772   * @param array $files
773   *   The name of the files in which the driver-specific class can be.
774   * @param $use_autoload
775   *   If TRUE, attempt to load classes using PHP's autoload capability
776   *   as well as the manual approach here.
777   * @return string
778   *   The name of the class that should be used for this driver.
779   */
780  public function getDriverClass($class, array $files = array(), $use_autoload = FALSE) {
781    if (empty($this->driverClasses[$class])) {
782      $driver = $this->driver();
783      $this->driverClasses[$class] = $class . '_' . $driver;
784      Database::loadDriverFile($driver, $files);
785      if (!class_exists($this->driverClasses[$class], $use_autoload)) {
786        $this->driverClasses[$class] = $class;
787      }
788    }
789    return $this->driverClasses[$class];
790  }
791
792  /**
793   * Prepares and returns a SELECT query object.
794   *
795   * @param $table
796   *   The base table for this query, that is, the first table in the FROM
797   *   clause. This table will also be used as the "base" table for query_alter
798   *   hook implementations.
799   * @param $alias
800   *   The alias of the base table of this query.
801   * @param $options
802   *   An array of options on the query.
803   *
804   * @return SelectQueryInterface
805   *   An appropriate SelectQuery object for this database connection. Note that
806   *   it may be a driver-specific subclass of SelectQuery, depending on the
807   *   driver.
808   *
809   * @see SelectQuery
810   */
811  public function select($table, $alias = NULL, array $options = array()) {
812    $class = $this->getDriverClass('SelectQuery', array('query.inc', 'select.inc'));
813    return new $class($table, $alias, $this, $options);
814  }
815
816  /**
817   * Prepares and returns an INSERT query object.
818   *
819   * @param $options
820   *   An array of options on the query.
821   *
822   * @return InsertQuery
823   *   A new InsertQuery object.
824   *
825   * @see InsertQuery
826   */
827  public function insert($table, array $options = array()) {
828    $class = $this->getDriverClass('InsertQuery', array('query.inc'));
829    return new $class($this, $table, $options);
830  }
831
832  /**
833   * Prepares and returns a MERGE query object.
834   *
835   * @param $options
836   *   An array of options on the query.
837   *
838   * @return MergeQuery
839   *   A new MergeQuery object.
840   *
841   * @see MergeQuery
842   */
843  public function merge($table, array $options = array()) {
844    $class = $this->getDriverClass('MergeQuery', array('query.inc'));
845    return new $class($this, $table, $options);
846  }
847
848
849  /**
850   * Prepares and returns an UPDATE query object.
851   *
852   * @param $options
853   *   An array of options on the query.
854   *
855   * @return UpdateQuery
856   *   A new UpdateQuery object.
857   *
858   * @see UpdateQuery
859   */
860  public function update($table, array $options = array()) {
861    $class = $this->getDriverClass('UpdateQuery', array('query.inc'));
862    return new $class($this, $table, $options);
863  }
864
865  /**
866   * Prepares and returns a DELETE query object.
867   *
868   * @param $options
869   *   An array of options on the query.
870   *
871   * @return DeleteQuery
872   *   A new DeleteQuery object.
873   *
874   * @see DeleteQuery
875   */
876  public function delete($table, array $options = array()) {
877    $class = $this->getDriverClass('DeleteQuery', array('query.inc'));
878    return new $class($this, $table, $options);
879  }
880
881  /**
882   * Prepares and returns a TRUNCATE query object.
883   *
884   * @param $options
885   *   An array of options on the query.
886   *
887   * @return TruncateQuery
888   *   A new TruncateQuery object.
889   *
890   * @see TruncateQuery
891   */
892  public function truncate($table, array $options = array()) {
893    $class = $this->getDriverClass('TruncateQuery', array('query.inc'));
894    return new $class($this, $table, $options);
895  }
896
897  /**
898   * Returns a DatabaseSchema object for manipulating the schema.
899   *
900   * This method will lazy-load the appropriate schema library file.
901   *
902   * @return DatabaseSchema
903   *   The DatabaseSchema object for this connection.
904   */
905  public function schema() {
906    if (empty($this->schema)) {
907      $class = $this->getDriverClass('DatabaseSchema', array('schema.inc'));
908      if (class_exists($class)) {
909        $this->schema = new $class($this);
910      }
911    }
912    return $this->schema;
913  }
914
915  /**
916   * Escapes a table name string.
917   *
918   * Force all table names to be strictly alphanumeric-plus-underscore.
919   * For some database drivers, it may also wrap the table name in
920   * database-specific escape characters.
921   *
922   * @return
923   *   The sanitized table name string.
924   */
925  public function escapeTable($table) {
926    return preg_replace('/[^A-Za-z0-9_.]+/', '', $table);
927  }
928
929  /**
930   * Escapes a field name string.
931   *
932   * Force all field names to be strictly alphanumeric-plus-underscore.
933   * For some database drivers, it may also wrap the field name in
934   * database-specific escape characters.
935   *
936   * @return
937   *   The sanitized field name string.
938   */
939  public function escapeField($field) {
940    return preg_replace('/[^A-Za-z0-9_.]+/', '', $field);
941  }
942
943  /**
944   * Escapes an alias name string.
945   *
946   * Force all alias names to be strictly alphanumeric-plus-underscore. In
947   * contrast to DatabaseConnection::escapeField() /
948   * DatabaseConnection::escapeTable(), this doesn't allow the period (".")
949   * because that is not allowed in aliases.
950   *
951   * @return
952   *   The sanitized field name string.
953   */
954  public function escapeAlias($field) {
955    return preg_replace('/[^A-Za-z0-9_]+/', '', $field);
956  }
957
958  /**
959   * Escapes characters that work as wildcard characters in a LIKE pattern.
960   *
961   * The wildcard characters "%" and "_" as well as backslash are prefixed with
962   * a backslash. Use this to do a search for a verbatim string without any
963   * wildcard behavior.
964   *
965   * For example, the following does a case-insensitive query for all rows whose
966   * name starts with $prefix:
967   * @code
968   * $result = db_query(
969   *   'SELECT * FROM person WHERE name LIKE :pattern',
970   *   array(':pattern' => db_like($prefix) . '%')
971   * );
972   * @endcode
973   *
974   * Backslash is defined as escape character for LIKE patterns in
975   * DatabaseCondition::mapConditionOperator().
976   *
977   * @param $string
978   *   The string to escape.
979   *
980   * @return
981   *   The escaped string.
982   */
983  public function escapeLike($string) {
984    return addcslashes($string, '\%_');
985  }
986
987  /**
988   * Determines if there is an active transaction open.
989   *
990   * @return
991   *   TRUE if we're currently in a transaction, FALSE otherwise.
992   */
993  public function inTransaction() {
994    return ($this->transactionDepth() > 0);
995  }
996
997  /**
998   * Determines current transaction depth.
999   */
1000  public function transactionDepth() {
1001    return count($this->transactionLayers);
1002  }
1003
1004  /**
1005   * Returns a new DatabaseTransaction object on this connection.
1006   *
1007   * @param $name
1008   *   Optional name of the savepoint.
1009   *
1010   * @return DatabaseTransaction
1011   *   A DatabaseTransaction object.
1012   *
1013   * @see DatabaseTransaction
1014   */
1015  public function startTransaction($name = '') {
1016    $class = $this->getDriverClass('DatabaseTransaction');
1017    return new $class($this, $name);
1018  }
1019
1020  /**
1021   * Rolls back the transaction entirely or to a named savepoint.
1022   *
1023   * This method throws an exception if no transaction is active.
1024   *
1025   * @param $savepoint_name
1026   *   The name of the savepoint. The default, 'drupal_transaction', will roll
1027   *   the entire transaction back.
1028   *
1029   * @throws DatabaseTransactionNoActiveException
1030   *
1031   * @see DatabaseTransaction::rollback()
1032   */
1033  public function rollback($savepoint_name = 'drupal_transaction') {
1034    if (!$this->supportsTransactions()) {
1035      return;
1036    }
1037    if (!$this->inTransaction()) {
1038      throw new DatabaseTransactionNoActiveException();
1039    }
1040    // A previous rollback to an earlier savepoint may mean that the savepoint
1041    // in question has already been accidentally committed.
1042    if (!isset($this->transactionLayers[$savepoint_name])) {
1043      throw new DatabaseTransactionNoActiveException();
1044    }
1045
1046    // We need to find the point we're rolling back to, all other savepoints
1047    // before are no longer needed. If we rolled back other active savepoints,
1048    // we need to throw an exception.
1049    $rolled_back_other_active_savepoints = FALSE;
1050    while ($savepoint = array_pop($this->transactionLayers)) {
1051      if ($savepoint == $savepoint_name) {
1052        // If it is the last the transaction in the stack, then it is not a
1053        // savepoint, it is the transaction itself so we will need to roll back
1054        // the transaction rather than a savepoint.
1055        if (empty($this->transactionLayers)) {
1056          break;
1057        }
1058        $this->query('ROLLBACK TO SAVEPOINT ' . $savepoint);
1059        $this->popCommittableTransactions();
1060        if ($rolled_back_other_active_savepoints) {
1061          throw new DatabaseTransactionOutOfOrderException();
1062        }
1063        return;
1064      }
1065      else {
1066        $rolled_back_other_active_savepoints = TRUE;
1067      }
1068    }
1069    parent::rollBack();
1070    if ($rolled_back_other_active_savepoints) {
1071      throw new DatabaseTransactionOutOfOrderException();
1072    }
1073  }
1074
1075  /**
1076   * Increases the depth of transaction nesting.
1077   *
1078   * If no transaction is already active, we begin a new transaction.
1079   *
1080   * @throws DatabaseTransactionNameNonUniqueException
1081   *
1082   * @see DatabaseTransaction
1083   */
1084  public function pushTransaction($name) {
1085    if (!$this->supportsTransactions()) {
1086      return;
1087    }
1088    if (isset($this->transactionLayers[$name])) {
1089      throw new DatabaseTransactionNameNonUniqueException($name . " is already in use.");
1090    }
1091    // If we're already in a transaction then we want to create a savepoint
1092    // rather than try to create another transaction.
1093    if ($this->inTransaction()) {
1094      $this->query('SAVEPOINT ' . $name);
1095    }
1096    else {
1097      parent::beginTransaction();
1098    }
1099    $this->transactionLayers[$name] = $name;
1100  }
1101
1102  /**
1103   * Decreases the depth of transaction nesting.
1104   *
1105   * If we pop off the last transaction layer, then we either commit or roll
1106   * back the transaction as necessary. If no transaction is active, we return
1107   * because the transaction may have manually been rolled back.
1108   *
1109   * @param $name
1110   *   The name of the savepoint
1111   *
1112   * @throws DatabaseTransactionNoActiveException
1113   * @throws DatabaseTransactionCommitFailedException
1114   *
1115   * @see DatabaseTransaction
1116   */
1117  public function popTransaction($name) {
1118    if (!$this->supportsTransactions()) {
1119      return;
1120    }
1121    // The transaction has already been committed earlier. There is nothing we
1122    // need to do. If this transaction was part of an earlier out-of-order
1123    // rollback, an exception would already have been thrown by
1124    // Database::rollback().
1125    if (!isset($this->transactionLayers[$name])) {
1126      return;
1127    }
1128
1129    // Mark this layer as committable.
1130    $this->transactionLayers[$name] = FALSE;
1131    $this->popCommittableTransactions();
1132  }
1133
1134  /**
1135   * Internal function: commit all the transaction layers that can commit.
1136   */
1137  protected function popCommittableTransactions() {
1138    // Commit all the committable layers.
1139    foreach (array_reverse($this->transactionLayers) as $name => $active) {
1140      // Stop once we found an active transaction.
1141      if ($active) {
1142        break;
1143      }
1144
1145      // If there are no more layers left then we should commit.
1146      unset($this->transactionLayers[$name]);
1147      if (empty($this->transactionLayers)) {
1148        if (!parent::commit()) {
1149          throw new DatabaseTransactionCommitFailedException();
1150        }
1151      }
1152      else {
1153        $this->query('RELEASE SAVEPOINT ' . $name);
1154      }
1155    }
1156  }
1157
1158  /**
1159   * Runs a limited-range query on this database object.
1160   *
1161   * Use this as a substitute for ->query() when a subset of the query is to be
1162   * returned. User-supplied arguments to the query should be passed in as
1163   * separate parameters so that they can be properly escaped to avoid SQL
1164   * injection attacks.
1165   *
1166   * @param $query
1167   *   A string containing an SQL query.
1168   * @param $args
1169   *   An array of values to substitute into the query at placeholder markers.
1170   * @param $from
1171   *   The first result row to return.
1172   * @param $count
1173   *   The maximum number of result rows to return.
1174   * @param $options
1175   *   An array of options on the query.
1176   *
1177   * @return DatabaseStatementInterface
1178   *   A database query result resource, or NULL if the query was not executed
1179   *   correctly.
1180   */
1181  abstract public function queryRange($query, $from, $count, array $args = array(), array $options = array());
1182
1183  /**
1184   * Generates a temporary table name.
1185   *
1186   * @return
1187   *   A table name.
1188   */
1189  protected function generateTemporaryTableName() {
1190    return "db_temporary_" . $this->temporaryNameIndex++;
1191  }
1192
1193  /**
1194   * Runs a SELECT query and stores its results in a temporary table.
1195   *
1196   * Use this as a substitute for ->query() when the results need to stored
1197   * in a temporary table. Temporary tables exist for the duration of the page
1198   * request. User-supplied arguments to the query should be passed in as
1199   * separate parameters so that they can be properly escaped to avoid SQL
1200   * injection attacks.
1201   *
1202   * Note that if you need to know how many results were returned, you should do
1203   * a SELECT COUNT(*) on the temporary table afterwards.
1204   *
1205   * @param $query
1206   *   A string containing a normal SELECT SQL query.
1207   * @param $args
1208   *   An array of values to substitute into the query at placeholder markers.
1209   * @param $options
1210   *   An associative array of options to control how the query is run. See
1211   *   the documentation for DatabaseConnection::defaultOptions() for details.
1212   *
1213   * @return
1214   *   The name of the temporary table.
1215   */
1216  abstract function queryTemporary($query, array $args = array(), array $options = array());
1217
1218  /**
1219   * Returns the type of database driver.
1220   *
1221   * This is not necessarily the same as the type of the database itself. For
1222   * instance, there could be two MySQL drivers, mysql and mysql_mock. This
1223   * function would return different values for each, but both would return
1224   * "mysql" for databaseType().
1225   */
1226  abstract public function driver();
1227
1228  /**
1229   * Returns the version of the database server.
1230   */
1231  public function version() {
1232    return $this->getAttribute(PDO::ATTR_SERVER_VERSION);
1233  }
1234
1235  /**
1236   * Determines if this driver supports transactions.
1237   *
1238   * @return
1239   *   TRUE if this connection supports transactions, FALSE otherwise.
1240   */
1241  public function supportsTransactions() {
1242    return $this->transactionSupport;
1243  }
1244
1245  /**
1246   * Determines if this driver supports transactional DDL.
1247   *
1248   * DDL queries are those that change the schema, such as ALTER queries.
1249   *
1250   * @return
1251   *   TRUE if this connection supports transactions for DDL queries, FALSE
1252   *   otherwise.
1253   */
1254  public function supportsTransactionalDDL() {
1255    return $this->transactionalDDLSupport;
1256  }
1257
1258  /**
1259   * Returns the name of the PDO driver for this connection.
1260   */
1261  abstract public function databaseType();
1262
1263
1264  /**
1265   * Gets any special processing requirements for the condition operator.
1266   *
1267   * Some condition types require special processing, such as IN, because
1268   * the value data they pass in is not a simple value. This is a simple
1269   * overridable lookup function. Database connections should define only
1270   * those operators they wish to be handled differently than the default.
1271   *
1272   * @param $operator
1273   *   The condition operator, such as "IN", "BETWEEN", etc. Case-sensitive.
1274   *
1275   * @return
1276   *   The extra handling directives for the specified operator, or NULL.
1277   *
1278   * @see DatabaseCondition::compile()
1279   */
1280  abstract public function mapConditionOperator($operator);
1281
1282  /**
1283   * Throws an exception to deny direct access to transaction commits.
1284   *
1285   * We do not want to allow users to commit transactions at any time, only
1286   * by destroying the transaction object or allowing it to go out of scope.
1287   * A direct commit bypasses all of the safety checks we've built on top of
1288   * PDO's transaction routines.
1289   *
1290   * @throws DatabaseTransactionExplicitCommitNotAllowedException
1291   *
1292   * @see DatabaseTransaction
1293   */
1294  public function commit() {
1295    throw new DatabaseTransactionExplicitCommitNotAllowedException();
1296  }
1297
1298  /**
1299   * Retrieves an unique id from a given sequence.
1300   *
1301   * Use this function if for some reason you can't use a serial field. For
1302   * example, MySQL has no ways of reading of the current value of a sequence
1303   * and PostgreSQL can not advance the sequence to be larger than a given
1304   * value. Or sometimes you just need a unique integer.
1305   *
1306   * @param $existing_id
1307   *   After a database import, it might be that the sequences table is behind,
1308   *   so by passing in the maximum existing id, it can be assured that we
1309   *   never issue the same id.
1310   *
1311   * @return
1312   *   An integer number larger than any number returned by earlier calls and
1313   *   also larger than the $existing_id if one was passed in.
1314   */
1315  abstract public function nextId($existing_id = 0);
1316}
1317
1318/**
1319 * Primary front-controller for the database system.
1320 *
1321 * This class is uninstantiatable and un-extendable. It acts to encapsulate
1322 * all control and shepherding of database connections into a single location
1323 * without the use of globals.
1324 */
1325abstract class Database {
1326
1327  /**
1328   * Flag to indicate a query call should simply return NULL.
1329   *
1330   * This is used for queries that have no reasonable return value anyway, such
1331   * as INSERT statements to a table without a serial primary key.
1332   */
1333  const RETURN_NULL = 0;
1334
1335  /**
1336   * Flag to indicate a query call should return the prepared statement.
1337   */
1338  const RETURN_STATEMENT = 1;
1339
1340  /**
1341   * Flag to indicate a query call should return the number of affected rows.
1342   */
1343  const RETURN_AFFECTED = 2;
1344
1345  /**
1346   * Flag to indicate a query call should return the "last insert id".
1347   */
1348  const RETURN_INSERT_ID = 3;
1349
1350  /**
1351   * An nested array of all active connections. It is keyed by database name
1352   * and target.
1353   *
1354   * @var array
1355   */
1356  static protected $connections = array();
1357
1358  /**
1359   * A processed copy of the database connection information from settings.php.
1360   *
1361   * @var array
1362   */
1363  static protected $databaseInfo = NULL;
1364
1365  /**
1366   * A list of key/target credentials to simply ignore.
1367   *
1368   * @var array
1369   */
1370  static protected $ignoreTargets = array();
1371
1372  /**
1373   * The key of the currently active database connection.
1374   *
1375   * @var string
1376   */
1377  static protected $activeKey = 'default';
1378
1379  /**
1380   * An array of active query log objects.
1381   *
1382   * Every connection has one and only one logger object for all targets and
1383   * logging keys.
1384   *
1385   * array(
1386   *   '$db_key' => DatabaseLog object.
1387   * );
1388   *
1389   * @var array
1390   */
1391  static protected $logs = array();
1392
1393  /**
1394   * Starts logging a given logging key on the specified connection.
1395   *
1396   * @param $logging_key
1397   *   The logging key to log.
1398   * @param $key
1399   *   The database connection key for which we want to log.
1400   *
1401   * @return DatabaseLog
1402   *   The query log object. Note that the log object does support richer
1403   *   methods than the few exposed through the Database class, so in some
1404   *   cases it may be desirable to access it directly.
1405   *
1406   * @see DatabaseLog
1407   */
1408  final public static function startLog($logging_key, $key = 'default') {
1409    if (empty(self::$logs[$key])) {
1410      self::$logs[$key] = new DatabaseLog($key);
1411
1412      // Every target already active for this connection key needs to have the
1413      // logging object associated with it.
1414      if (!empty(self::$connections[$key])) {
1415        foreach (self::$connections[$key] as $connection) {
1416          $connection->setLogger(self::$logs[$key]);
1417        }
1418      }
1419    }
1420
1421    self::$logs[$key]->start($logging_key);
1422    return self::$logs[$key];
1423  }
1424
1425  /**
1426   * Retrieves the queries logged on for given logging key.
1427   *
1428   * This method also ends logging for the specified key. To get the query log
1429   * to date without ending the logger request the logging object by starting
1430   * it again (which does nothing to an open log key) and call methods on it as
1431   * desired.
1432   *
1433   * @param $logging_key
1434   *   The logging key to log.
1435   * @param $key
1436   *   The database connection key for which we want to log.
1437   *
1438   * @return array
1439   *   The query log for the specified logging key and connection.
1440   *
1441   * @see DatabaseLog
1442   */
1443  final public static function getLog($logging_key, $key = 'default') {
1444    if (empty(self::$logs[$key])) {
1445      return NULL;
1446    }
1447    $queries = self::$logs[$key]->get($logging_key);
1448    self::$logs[$key]->end($logging_key);
1449    return $queries;
1450  }
1451
1452  /**
1453   * Gets the connection object for the specified database key and target.
1454   *
1455   * @param $target
1456   *   The database target name.
1457   * @param $key
1458   *   The database connection key. Defaults to NULL which means the active key.
1459   *
1460   * @return DatabaseConnection
1461   *   The corresponding connection object.
1462   */
1463  final public static function getConnection($target = 'default', $key = NULL) {
1464    if (!isset($key)) {
1465      // By default, we want the active connection, set in setActiveConnection.
1466      $key = self::$activeKey;
1467    }
1468    // If the requested target does not exist, or if it is ignored, we fall back
1469    // to the default target. The target is typically either "default" or
1470    // "slave", indicating to use a slave SQL server if one is available. If
1471    // it's not available, then the default/master server is the correct server
1472    // to use.
1473    if (!empty(self::$ignoreTargets[$key][$target]) || !isset(self::$databaseInfo[$key][$target])) {
1474      $target = 'default';
1475    }
1476
1477    if (!isset(self::$connections[$key][$target])) {
1478      // If necessary, a new connection is opened.
1479      self::$connections[$key][$target] = self::openConnection($key, $target);
1480    }
1481    return self::$connections[$key][$target];
1482  }
1483
1484  /**
1485   * Determines if there is an active connection.
1486   *
1487   * Note that this method will return FALSE if no connection has been
1488   * established yet, even if one could be.
1489   *
1490   * @return
1491   *   TRUE if there is at least one database connection established, FALSE
1492   *   otherwise.
1493   */
1494  final public static function isActiveConnection() {
1495    return !empty(self::$activeKey) && !empty(self::$connections) && !empty(self::$connections[self::$activeKey]);
1496  }
1497
1498  /**
1499   * Sets the active connection to the specified key.
1500   *
1501   * @return
1502   *   The previous database connection key.
1503   */
1504  final public static function setActiveConnection($key = 'default') {
1505    if (empty(self::$databaseInfo)) {
1506      self::parseConnectionInfo();
1507    }
1508
1509    if (!empty(self::$databaseInfo[$key])) {
1510      $old_key = self::$activeKey;
1511      self::$activeKey = $key;
1512      return $old_key;
1513    }
1514  }
1515
1516  /**
1517   * Process the configuration file for database information.
1518   */
1519  final public static function parseConnectionInfo() {
1520    global $databases;
1521
1522    $database_info = is_array($databases) ? $databases : array();
1523    foreach ($database_info as $index => $info) {
1524      foreach ($database_info[$index] as $target => $value) {
1525        // If there is no "driver" property, then we assume it's an array of
1526        // possible connections for this target. Pick one at random. That allows
1527        //  us to have, for example, multiple slave servers.
1528        if (empty($value['driver'])) {
1529          $database_info[$index][$target] = $database_info[$index][$target][mt_rand(0, count($database_info[$index][$target]) - 1)];
1530        }
1531
1532        // Parse the prefix information.
1533        if (!isset($database_info[$index][$target]['prefix'])) {
1534          // Default to an empty prefix.
1535          $database_info[$index][$target]['prefix'] = array(
1536            'default' => '',
1537          );
1538        }
1539        elseif (!is_array($database_info[$index][$target]['prefix'])) {
1540          // Transform the flat form into an array form.
1541          $database_info[$index][$target]['prefix'] = array(
1542            'default' => $database_info[$index][$target]['prefix'],
1543          );
1544        }
1545      }
1546    }
1547
1548    if (!is_array(self::$databaseInfo)) {
1549      self::$databaseInfo = $database_info;
1550    }
1551
1552    // Merge the new $database_info into the existing.
1553    // array_merge_recursive() cannot be used, as it would make multiple
1554    // database, user, and password keys in the same database array.
1555    else {
1556      foreach ($database_info as $database_key => $database_values) {
1557        foreach ($database_values as $target => $target_values) {
1558          self::$databaseInfo[$database_key][$target] = $target_values;
1559        }
1560      }
1561    }
1562  }
1563
1564  /**
1565   * Adds database connection information for a given key/target.
1566   *
1567   * This method allows the addition of new connection credentials at runtime.
1568   * Under normal circumstances the preferred way to specify database
1569   * credentials is via settings.php. However, this method allows them to be
1570   * added at arbitrary times, such as during unit tests, when connecting to
1571   * admin-defined third party databases, etc.
1572   *
1573   * If the given key/target pair already exists, this method will be ignored.
1574   *
1575   * @param $key
1576   *   The database key.
1577   * @param $target
1578   *   The database target name.
1579   * @param $info
1580   *   The database connection information, as it would be defined in
1581   *   settings.php. Note that the structure of this array will depend on the
1582   *   database driver it is connecting to.
1583   */
1584  public static function addConnectionInfo($key, $target, $info) {
1585    if (empty(self::$databaseInfo[$key][$target])) {
1586      self::$databaseInfo[$key][$target] = $info;
1587    }
1588  }
1589
1590  /**
1591   * Gets information on the specified database connection.
1592   *
1593   * @param $connection
1594   *   The connection key for which we want information.
1595   */
1596  final public static function getConnectionInfo($key = 'default') {
1597    if (empty(self::$databaseInfo)) {
1598      self::parseConnectionInfo();
1599    }
1600
1601    if (!empty(self::$databaseInfo[$key])) {
1602      return self::$databaseInfo[$key];
1603    }
1604  }
1605
1606  /**
1607   * Rename a connection and its corresponding connection information.
1608   *
1609   * @param $old_key
1610   *   The old connection key.
1611   * @param $new_key
1612   *   The new connection key.
1613   * @return
1614   *   TRUE in case of success, FALSE otherwise.
1615   */
1616  final public static function renameConnection($old_key, $new_key) {
1617    if (empty(self::$databaseInfo)) {
1618      self::parseConnectionInfo();
1619    }
1620
1621    if (!empty(self::$databaseInfo[$old_key]) && empty(self::$databaseInfo[$new_key])) {
1622      // Migrate the database connection information.
1623      self::$databaseInfo[$new_key] = self::$databaseInfo[$old_key];
1624      unset(self::$databaseInfo[$old_key]);
1625
1626      // Migrate over the DatabaseConnection object if it exists.
1627      if (isset(self::$connections[$old_key])) {
1628        self::$connections[$new_key] = self::$connections[$old_key];
1629        unset(self::$connections[$old_key]);
1630      }
1631
1632      return TRUE;
1633    }
1634    else {
1635      return FALSE;
1636    }
1637  }
1638
1639  /**
1640   * Remove a connection and its corresponding connection information.
1641   *
1642   * @param $key
1643   *   The connection key.
1644   * @return
1645   *   TRUE in case of success, FALSE otherwise.
1646   */
1647  final public static function removeConnection($key) {
1648    if (isset(self::$databaseInfo[$key])) {
1649      self::closeConnection(NULL, $key);
1650      unset(self::$databaseInfo[$key]);
1651      return TRUE;
1652    }
1653    else {
1654      return FALSE;
1655    }
1656  }
1657
1658  /**
1659   * Opens a connection to the server specified by the given key and target.
1660   *
1661   * @param $key
1662   *   The database connection key, as specified in settings.php. The default is
1663   *   "default".
1664   * @param $target
1665   *   The database target to open.
1666   *
1667   * @throws DatabaseConnectionNotDefinedException
1668   * @throws DatabaseDriverNotSpecifiedException
1669   */
1670  final protected static function openConnection($key, $target) {
1671    if (empty(self::$databaseInfo)) {
1672      self::parseConnectionInfo();
1673    }
1674
1675    // If the requested database does not exist then it is an unrecoverable
1676    // error.
1677    if (!isset(self::$databaseInfo[$key])) {
1678      throw new DatabaseConnectionNotDefinedException('The specified database connection is not defined: ' . $key);
1679    }
1680
1681    if (!$driver = self::$databaseInfo[$key][$target]['driver']) {
1682      throw new DatabaseDriverNotSpecifiedException('Driver not specified for this database connection: ' . $key);
1683    }
1684
1685    // We cannot rely on the registry yet, because the registry requires an
1686    // open database connection.
1687    $driver_class = 'DatabaseConnection_' . $driver;
1688    require_once DRUPAL_ROOT . '/includes/database/' . $driver . '/database.inc';
1689    $new_connection = new $driver_class(self::$databaseInfo[$key][$target]);
1690    $new_connection->setTarget($target);
1691    $new_connection->setKey($key);
1692
1693    // If we have any active logging objects for this connection key, we need
1694    // to associate them with the connection we just opened.
1695    if (!empty(self::$logs[$key])) {
1696      $new_connection->setLogger(self::$logs[$key]);
1697    }
1698
1699    return $new_connection;
1700  }
1701
1702  /**
1703   * Closes a connection to the server specified by the given key and target.
1704   *
1705   * @param $target
1706   *   The database target name.  Defaults to NULL meaning that all target
1707   *   connections will be closed.
1708   * @param $key
1709   *   The database connection key. Defaults to NULL which means the active key.
1710   */
1711  public static function closeConnection($target = NULL, $key = NULL) {
1712    // Gets the active connection by default.
1713    if (!isset($key)) {
1714      $key = self::$activeKey;
1715    }
1716    // To close a connection, it needs to be set to NULL and removed from the
1717    // static variable. In all cases, closeConnection() might be called for a
1718    // connection that was not opened yet, in which case the key is not defined
1719    // yet and we just ensure that the connection key is undefined.
1720    if (isset($target)) {
1721      if (isset(self::$connections[$key][$target])) {
1722        self::$connections[$key][$target]->destroy();
1723        self::$connections[$key][$target] = NULL;
1724      }
1725      unset(self::$connections[$key][$target]);
1726    }
1727    else {
1728      if (isset(self::$connections[$key])) {
1729        foreach (self::$connections[$key] as $target => $connection) {
1730          self::$connections[$key][$target]->destroy();
1731          self::$connections[$key][$target] = NULL;
1732        }
1733      }
1734      unset(self::$connections[$key]);
1735    }
1736  }
1737
1738  /**
1739   * Instructs the system to temporarily ignore a given key/target.
1740   *
1741   * At times we need to temporarily disable slave queries. To do so, call this
1742   * method with the database key and the target to disable. That database key
1743   * will then always fall back to 'default' for that key, even if it's defined.
1744   *
1745   * @param $key
1746   *   The database connection key.
1747   * @param $target
1748   *   The target of the specified key to ignore.
1749   */
1750  public static function ignoreTarget($key, $target) {
1751    self::$ignoreTargets[$key][$target] = TRUE;
1752  }
1753
1754  /**
1755   * Load a file for the database that might hold a class.
1756   *
1757   * @param $driver
1758   *   The name of the driver.
1759   * @param array $files
1760   *   The name of the files the driver specific class can be.
1761   */
1762  public static function loadDriverFile($driver, array $files = array()) {
1763    static $base_path;
1764
1765    if (empty($base_path)) {
1766      $base_path = dirname(realpath(__FILE__));
1767    }
1768
1769    $driver_base_path = "$base_path/$driver";
1770    foreach ($files as $file) {
1771      // Load the base file first so that classes extending base classes will
1772      // have the base class loaded.
1773      foreach (array("$base_path/$file", "$driver_base_path/$file") as $filename) {
1774        // The OS caches file_exists() and PHP caches require_once(), so
1775        // we'll let both of those take care of performance here.
1776        if (file_exists($filename)) {
1777          require_once $filename;
1778        }
1779      }
1780    }
1781  }
1782}
1783
1784/**
1785 * Exception for when popTransaction() is called with no active transaction.
1786 */
1787class DatabaseTransactionNoActiveException extends Exception { }
1788
1789/**
1790 * Exception thrown when a savepoint or transaction name occurs twice.
1791 */
1792class DatabaseTransactionNameNonUniqueException extends Exception { }
1793
1794/**
1795 * Exception thrown when a commit() function fails.
1796 */
1797class DatabaseTransactionCommitFailedException extends Exception { }
1798
1799/**
1800 * Exception to deny attempts to explicitly manage transactions.
1801 *
1802 * This exception will be thrown when the PDO connection commit() is called.
1803 * Code should never call this method directly.
1804 */
1805class DatabaseTransactionExplicitCommitNotAllowedException extends Exception { }
1806
1807/**
1808 * Exception thrown when a rollback() resulted in other active transactions being rolled-back.
1809 */
1810class DatabaseTransactionOutOfOrderException extends Exception { }
1811
1812/**
1813 * Exception thrown for merge queries that do not make semantic sense.
1814 *
1815 * There are many ways that a merge query could be malformed.  They should all
1816 * throw this exception and set an appropriately descriptive message.
1817 */
1818class InvalidMergeQueryException extends Exception {}
1819
1820/**
1821 * Exception thrown if an insert query specifies a field twice.
1822 *
1823 * It is not allowed to specify a field as default and insert field, this
1824 * exception is thrown if that is the case.
1825 */
1826class FieldsOverlapException extends Exception {}
1827
1828/**
1829 * Exception thrown if an insert query doesn't specify insert or default fields.
1830 */
1831class NoFieldsException extends Exception {}
1832
1833/**
1834 * Exception thrown if an undefined database connection is requested.
1835 */
1836class DatabaseConnectionNotDefinedException extends Exception {}
1837
1838/**
1839 * Exception thrown if no driver is specified for a database connection.
1840 */
1841class DatabaseDriverNotSpecifiedException extends Exception {}
1842
1843
1844/**
1845 * A wrapper class for creating and managing database transactions.
1846 *
1847 * Not all databases or database configurations support transactions. For
1848 * example, MySQL MyISAM tables do not. It is also easy to begin a transaction
1849 * and then forget to commit it, which can lead to connection errors when
1850 * another transaction is started.
1851 *
1852 * This class acts as a wrapper for transactions. To begin a transaction,
1853 * simply instantiate it. When the object goes out of scope and is destroyed
1854 * it will automatically commit. It also will check to see if the specified
1855 * connection supports transactions. If not, it will simply skip any transaction
1856 * commands, allowing user-space code to proceed normally. The only difference
1857 * is that rollbacks won't actually do anything.
1858 *
1859 * In the vast majority of cases, you should not instantiate this class
1860 * directly. Instead, call ->startTransaction(), from the appropriate connection
1861 * object.
1862 */
1863class DatabaseTransaction {
1864
1865  /**
1866   * The connection object for this transaction.
1867   *
1868   * @var DatabaseConnection
1869   */
1870  protected $connection;
1871
1872  /**
1873   * A boolean value to indicate whether this transaction has been rolled back.
1874   *
1875   * @var Boolean
1876   */
1877  protected $rolledBack = FALSE;
1878
1879  /**
1880   * The name of the transaction.
1881   *
1882   * This is used to label the transaction savepoint. It will be overridden to
1883   * 'drupal_transaction' if there is no transaction depth.
1884   */
1885  protected $name;
1886
1887  public function __construct(DatabaseConnection $connection, $name = NULL) {
1888    $this->connection = $connection;
1889    // If there is no transaction depth, then no transaction has started. Name
1890    // the transaction 'drupal_transaction'.
1891    if (!$depth = $connection->transactionDepth()) {
1892      $this->name = 'drupal_transaction';
1893    }
1894    // Within transactions, savepoints are used. Each savepoint requires a
1895    // name. So if no name is present we need to create one.
1896    elseif (!$name) {
1897      $this->name = 'savepoint_' . $depth;
1898    }
1899    else {
1900      $this->name = $name;
1901    }
1902    $this->connection->pushTransaction($this->name);
1903  }
1904
1905  public function __destruct() {
1906    // If we rolled back then the transaction would have already been popped.
1907    if (!$this->rolledBack) {
1908      $this->connection->popTransaction($this->name);
1909    }
1910  }
1911
1912  /**
1913   * Retrieves the name of the transaction or savepoint.
1914   */
1915  public function name() {
1916    return $this->name;
1917  }
1918
1919  /**
1920   * Rolls back the current transaction.
1921   *
1922   * This is just a wrapper method to rollback whatever transaction stack we are
1923   * currently in, which is managed by the connection object itself. Note that
1924   * logging (preferable with watchdog_exception()) needs to happen after a
1925   * transaction has been rolled back or the log messages will be rolled back
1926   * too.
1927   *
1928   * @see DatabaseConnection::rollback()
1929   * @see watchdog_exception()
1930   */
1931  public function rollback() {
1932    $this->rolledBack = TRUE;
1933    $this->connection->rollback($this->name);
1934  }
1935}
1936
1937/**
1938 * Represents a prepared statement.
1939 *
1940 * Some methods in that class are purposefully commented out. Due to a change in
1941 * how PHP defines PDOStatement, we can't define a signature for those methods
1942 * that will work the same way between versions older than 5.2.6 and later
1943 * versions.  See http://bugs.php.net/bug.php?id=42452 for more details.
1944 *
1945 * Child implementations should either extend PDOStatement:
1946 * @code
1947 * class DatabaseStatement_oracle extends PDOStatement implements DatabaseStatementInterface {}
1948 * @endcode
1949 * or define their own class. If defining their own class, they will also have
1950 * to implement either the Iterator or IteratorAggregate interface before
1951 * DatabaseStatementInterface:
1952 * @code
1953 * class DatabaseStatement_oracle implements Iterator, DatabaseStatementInterface {}
1954 * @endcode
1955 */
1956interface DatabaseStatementInterface extends Traversable {
1957
1958  /**
1959   * Executes a prepared statement
1960   *
1961   * @param $args
1962   *   An array of values with as many elements as there are bound parameters in
1963   *   the SQL statement being executed.
1964   * @param $options
1965   *   An array of options for this query.
1966   *
1967   * @return
1968   *   TRUE on success, or FALSE on failure.
1969   */
1970  public function execute($args = array(), $options = array());
1971
1972  /**
1973   * Gets the query string of this statement.
1974   *
1975   * @return
1976   *   The query string, in its form with placeholders.
1977   */
1978  public function getQueryString();
1979
1980  /**
1981   * Returns the number of rows affected by the last SQL statement.
1982   *
1983   * @return
1984   *   The number of rows affected by the last DELETE, INSERT, or UPDATE
1985   *   statement executed.
1986   */
1987  public function rowCount();
1988
1989  /**
1990   * Sets the default fetch mode for this statement.
1991   *
1992   * See http://php.net/manual/pdo.constants.php for the definition of the
1993   * constants used.
1994   *
1995   * @param $mode
1996   *   One of the PDO::FETCH_* constants.
1997   * @param $a1
1998   *   An option depending of the fetch mode specified by $mode:
1999   *   - for PDO::FETCH_COLUMN, the index of the column to fetch
2000   *   - for PDO::FETCH_CLASS, the name of the class to create
2001   *   - for PDO::FETCH_INTO, the object to add the data to
2002   * @param $a2
2003   *   If $mode is PDO::FETCH_CLASS, the optional arguments to pass to the
2004   *   constructor.
2005   */
2006  // public function setFetchMode($mode, $a1 = NULL, $a2 = array());
2007
2008  /**
2009   * Fetches the next row from a result set.
2010   *
2011   * See http://php.net/manual/pdo.constants.php for the definition of the
2012   * constants used.
2013   *
2014   * @param $mode
2015   *   One of the PDO::FETCH_* constants.
2016   *   Default to what was specified by setFetchMode().
2017   * @param $cursor_orientation
2018   *   Not implemented in all database drivers, don't use.
2019   * @param $cursor_offset
2020   *   Not implemented in all database drivers, don't use.
2021   *
2022   * @return
2023   *   A result, formatted according to $mode.
2024   */
2025  // public function fetch($mode = NULL, $cursor_orientation = NULL, $cursor_offset = NULL);
2026
2027  /**
2028   * Returns a single field from the next record of a result set.
2029   *
2030   * @param $index
2031   *   The numeric index of the field to return. Defaults to the first field.
2032   *
2033   * @return
2034   *   A single field from the next record, or FALSE if there is no next record.
2035   */
2036  public function fetchField($index = 0);
2037
2038  /**
2039   * Fetches the next row and returns it as an object.
2040   *
2041   * The object will be of the class specified by DatabaseStatementInterface::setFetchMode()
2042   * or stdClass if not specified.
2043   */
2044  // public function fetchObject();
2045
2046  /**
2047   * Fetches the next row and returns it as an associative array.
2048   *
2049   * This method corresponds to PDOStatement::fetchObject(), but for associative
2050   * arrays. For some reason PDOStatement does not have a corresponding array
2051   * helper method, so one is added.
2052   *
2053   * @return
2054   *   An associative array, or FALSE if there is no next row.
2055   */
2056  public function fetchAssoc();
2057
2058  /**
2059   * Returns an array containing all of the result set rows.
2060   *
2061   * @param $mode
2062   *   One of the PDO::FETCH_* constants.
2063   * @param $column_index
2064   *   If $mode is PDO::FETCH_COLUMN, the index of the column to fetch.
2065   * @param $constructor_arguments
2066   *   If $mode is PDO::FETCH_CLASS, the arguments to pass to the constructor.
2067   *
2068   * @return
2069   *   An array of results.
2070   */
2071  // function fetchAll($mode = NULL, $column_index = NULL, array $constructor_arguments);
2072
2073  /**
2074   * Returns an entire single column of a result set as an indexed array.
2075   *
2076   * Note that this method will run the result set to the end.
2077   *
2078   * @param $index
2079   *   The index of the column number to fetch.
2080   *
2081   * @return
2082   *   An indexed array, or an empty array if there is no result set.
2083   */
2084  public function fetchCol($index = 0);
2085
2086  /**
2087   * Returns the entire result set as a single associative array.
2088   *
2089   * This method is only useful for two-column result sets. It will return an
2090   * associative array where the key is one column from the result set and the
2091   * value is another field. In most cases, the default of the first two columns
2092   * is appropriate.
2093   *
2094   * Note that this method will run the result set to the end.
2095   *
2096   * @param $key_index
2097   *   The numeric index of the field to use as the array key.
2098   * @param $value_index
2099   *   The numeric index of the field to use as the array value.
2100   *
2101   * @return
2102   *   An associative array, or an empty array if there is no result set.
2103   */
2104  public function fetchAllKeyed($key_index = 0, $value_index = 1);
2105
2106  /**
2107   * Returns the result set as an associative array keyed by the given field.
2108   *
2109   * If the given key appears multiple times, later records will overwrite
2110   * earlier ones.
2111   *
2112   * @param $key
2113   *   The name of the field on which to index the array.
2114   * @param $fetch
2115   *   The fetchmode to use. If set to PDO::FETCH_ASSOC, PDO::FETCH_NUM, or
2116   *   PDO::FETCH_BOTH the returned value with be an array of arrays. For any
2117   *   other value it will be an array of objects. By default, the fetch mode
2118   *   set for the query will be used.
2119   *
2120   * @return
2121   *   An associative array, or an empty array if there is no result set.
2122   */
2123  public function fetchAllAssoc($key, $fetch = NULL);
2124}
2125
2126/**
2127 * Default implementation of DatabaseStatementInterface.
2128 *
2129 * PDO allows us to extend the PDOStatement class to provide additional
2130 * functionality beyond that offered by default. We do need extra
2131 * functionality. By default, this class is not driver-specific. If a given
2132 * driver needs to set a custom statement class, it may do so in its
2133 * constructor.
2134 *
2135 * @see http://us.php.net/pdostatement
2136 */
2137class DatabaseStatementBase extends PDOStatement implements DatabaseStatementInterface {
2138
2139  /**
2140   * Reference to the database connection object for this statement.
2141   *
2142   * The name $dbh is inherited from PDOStatement.
2143   *
2144   * @var DatabaseConnection
2145   */
2146  public $dbh;
2147
2148  protected function __construct($dbh) {
2149    $this->dbh = $dbh;
2150    $this->setFetchMode(PDO::FETCH_OBJ);
2151  }
2152
2153  public function execute($args = array(), $options = array()) {
2154    if (isset($options['fetch'])) {
2155      if (is_string($options['fetch'])) {
2156        // Default to an object. Note: db fields will be added to the object
2157        // before the constructor is run. If you need to assign fields after
2158        // the constructor is run, see http://drupal.org/node/315092.
2159        $this->setFetchMode(PDO::FETCH_CLASS, $options['fetch']);
2160      }
2161      else {
2162        $this->setFetchMode($options['fetch']);
2163      }
2164    }
2165
2166    $logger = $this->dbh->getLogger();
2167    if (!empty($logger)) {
2168      $query_start = microtime(TRUE);
2169    }
2170
2171    $return = parent::execute($args);
2172
2173    if (!empty($logger)) {
2174      $query_end = microtime(TRUE);
2175      $logger->log($this, $args, $query_end - $query_start);
2176    }
2177
2178    return $return;
2179  }
2180
2181  public function getQueryString() {
2182    return $this->queryString;
2183  }
2184
2185  public function fetchCol($index = 0) {
2186    return $this->fetchAll(PDO::FETCH_COLUMN, $index);
2187  }
2188
2189  public function fetchAllAssoc($key, $fetch = NULL) {
2190    $return = array();
2191    if (isset($fetch)) {
2192      if (is_string($fetch)) {
2193        $this->setFetchMode(PDO::FETCH_CLASS, $fetch);
2194      }
2195      else {
2196        $this->setFetchMode($fetch);
2197      }
2198    }
2199
2200    foreach ($this as $record) {
2201      $record_key = is_object($record) ? $record->$key : $record[$key];
2202      $return[$record_key] = $record;
2203    }
2204
2205    return $return;
2206  }
2207
2208  public function fetchAllKeyed($key_index = 0, $value_index = 1) {
2209    $return = array();
2210    $this->setFetchMode(PDO::FETCH_NUM);
2211    foreach ($this as $record) {
2212      $return[$record[$key_index]] = $record[$value_index];
2213    }
2214    return $return;
2215  }
2216
2217  public function fetchField($index = 0) {
2218    // Call PDOStatement::fetchColumn to fetch the field.
2219    return $this->fetchColumn($index);
2220  }
2221
2222  public function fetchAssoc() {
2223    // Call PDOStatement::fetch to fetch the row.
2224    return $this->fetch(PDO::FETCH_ASSOC);
2225  }
2226}
2227
2228/**
2229 * Empty implementation of a database statement.
2230 *
2231 * This class satisfies the requirements of being a database statement/result
2232 * object, but does not actually contain data.  It is useful when developers
2233 * need to safely return an "empty" result set without connecting to an actual
2234 * database.  Calling code can then treat it the same as if it were an actual
2235 * result set that happens to contain no records.
2236 *
2237 * @see SearchQuery
2238 */
2239class DatabaseStatementEmpty implements Iterator, DatabaseStatementInterface {
2240
2241  public function execute($args = array(), $options = array()) {
2242    return FALSE;
2243  }
2244
2245  public function getQueryString() {
2246    return '';
2247  }
2248
2249  public function rowCount() {
2250    return 0;
2251  }
2252
2253  public function setFetchMode($mode, $a1 = NULL, $a2 = array()) {
2254    return;
2255  }
2256
2257  public function fetch($mode = NULL, $cursor_orientation = NULL, $cursor_offset = NULL) {
2258    return NULL;
2259  }
2260
2261  public function fetchField($index = 0) {
2262    return NULL;
2263  }
2264
2265  public function fetchObject() {
2266    return NULL;
2267  }
2268
2269  public function fetchAssoc() {
2270    return NULL;
2271  }
2272
2273  function fetchAll($mode = NULL, $column_index = NULL, array $constructor_arguments = array()) {
2274    return array();
2275  }
2276
2277  public function fetchCol($index = 0) {
2278    return array();
2279  }
2280
2281  public function fetchAllKeyed($key_index = 0, $value_index = 1) {
2282    return array();
2283  }
2284
2285  public function fetchAllAssoc($key, $fetch = NULL) {
2286    return array();
2287  }
2288
2289  /* Implementations of Iterator. */
2290
2291  public function current() {
2292    return NULL;
2293  }
2294
2295  public function key() {
2296    return NULL;
2297  }
2298
2299  public function rewind() {
2300    // Nothing to do: our DatabaseStatement can't be rewound.
2301  }
2302
2303  public function next() {
2304    // Do nothing, since this is an always-empty implementation.
2305  }
2306
2307  public function valid() {
2308    return FALSE;
2309  }
2310}
2311
2312/**
2313 * The following utility functions are simply convenience wrappers.
2314 *
2315 * They should never, ever have any database-specific code in them.
2316 */
2317
2318/**
2319 * Executes an arbitrary query string against the active database.
2320 *
2321 * Use this function for SELECT queries if it is just a simple query string.
2322 * If the caller or other modules need to change the query, use db_select()
2323 * instead.
2324 *
2325 * Do not use this function for INSERT, UPDATE, or DELETE queries. Those should
2326 * be handled via db_insert(), db_update() and db_delete() respectively.
2327 *
2328 * @param $query
2329 *   The prepared statement query to run. Although it will accept both named and
2330 *   unnamed placeholders, named placeholders are strongly preferred as they are
2331 *   more self-documenting.
2332 * @param $args
2333 *   An array of values to substitute into the query. If the query uses named
2334 *   placeholders, this is an associative array in any order. If the query uses
2335 *   unnamed placeholders (?), this is an indexed array and the order must match
2336 *   the order of placeholders in the query string.
2337 * @param $options
2338 *   An array of options to control how the query operates.
2339 *
2340 * @return DatabaseStatementInterface
2341 *   A prepared statement object, already executed.
2342 *
2343 * @see DatabaseConnection::defaultOptions()
2344 */
2345function db_query($query, array $args = array(), array $options = array()) {
2346  if (empty($options['target'])) {
2347    $options['target'] = 'default';
2348  }
2349
2350  return Database::getConnection($options['target'])->query($query, $args, $options);
2351}
2352
2353/**
2354 * Executes a query against the active database, restricted to a range.
2355 *
2356 * @param $query
2357 *   The prepared statement query to run. Although it will accept both named and
2358 *   unnamed placeholders, named placeholders are strongly preferred as they are
2359 *   more self-documenting.
2360 * @param $from
2361 *   The first record from the result set to return.
2362 * @param $count
2363 *   The number of records to return from the result set.
2364 * @param $args
2365 *   An array of values to substitute into the query. If the query uses named
2366 *   placeholders, this is an associative array in any order. If the query uses
2367 *   unnamed placeholders (?), this is an indexed array and the order must match
2368 *   the order of placeholders in the query string.
2369 * @param $options
2370 *   An array of options to control how the query operates.
2371 *
2372 * @return DatabaseStatementInterface
2373 *   A prepared statement object, already executed.
2374 *
2375 * @see DatabaseConnection::defaultOptions()
2376 */
2377function db_query_range($query, $from, $count, array $args = array(), array $options = array()) {
2378  if (empty($options['target'])) {
2379    $options['target'] = 'default';
2380  }
2381
2382  return Database::getConnection($options['target'])->queryRange($query, $from, $count, $args, $options);
2383}
2384
2385/**
2386 * Executes a SELECT query string and saves the result set to a temporary table.
2387 *
2388 * The execution of the query string happens against the active database.
2389 *
2390 * @param $query
2391 *   The prepared SELECT statement query to run. Although it will accept both
2392 *   named and unnamed placeholders, named placeholders are strongly preferred
2393 *   as they are more self-documenting.
2394 * @param $args
2395 *   An array of values to substitute into the query. If the query uses named
2396 *   placeholders, this is an associative array in any order. If the query uses
2397 *   unnamed placeholders (?), this is an indexed array and the order must match
2398 *   the order of placeholders in the query string.
2399 * @param $options
2400 *   An array of options to control how the query operates.
2401 *
2402 * @return
2403 *   The name of the temporary table.
2404 *
2405 * @see DatabaseConnection::defaultOptions()
2406 */
2407function db_query_temporary($query, array $args = array(), array $options = array()) {
2408  if (empty($options['target'])) {
2409    $options['target'] = 'default';
2410  }
2411
2412  return Database::getConnection($options['target'])->queryTemporary($query, $args, $options);
2413}
2414
2415/**
2416 * Returns a new InsertQuery object for the active database.
2417 *
2418 * @param $table
2419 *   The table into which to insert.
2420 * @param $options
2421 *   An array of options to control how the query operates.
2422 *
2423 * @return InsertQuery
2424 *   A new InsertQuery object for this connection.
2425 */
2426function db_insert($table, array $options = array()) {
2427  if (empty($options['target']) || $options['target'] == 'slave') {
2428    $options['target'] = 'default';
2429  }
2430  return Database::getConnection($options['target'])->insert($table, $options);
2431}
2432
2433/**
2434 * Returns a new MergeQuery object for the active database.
2435 *
2436 * @param $table
2437 *   The table into which to merge.
2438 * @param $options
2439 *   An array of options to control how the query operates.
2440 *
2441 * @return MergeQuery
2442 *   A new MergeQuery object for this connection.
2443 */
2444function db_merge($table, array $options = array()) {
2445  if (empty($options['target']) || $options['target'] == 'slave') {
2446    $options['target'] = 'default';
2447  }
2448  return Database::getConnection($options['target'])->merge($table, $options);
2449}
2450
2451/**
2452 * Returns a new UpdateQuery object for the active database.
2453 *
2454 * @param $table
2455 *   The table to update.
2456 * @param $options
2457 *   An array of options to control how the query operates.
2458 *
2459 * @return UpdateQuery
2460 *   A new UpdateQuery object for this connection.
2461 */
2462function db_update($table, array $options = array()) {
2463  if (empty($options['target']) || $options['target'] == 'slave') {
2464    $options['target'] = 'default';
2465  }
2466  return Database::getConnection($options['target'])->update($table, $options);
2467}
2468
2469/**
2470 * Returns a new DeleteQuery object for the active database.
2471 *
2472 * @param $table
2473 *   The table from which to delete.
2474 * @param $options
2475 *   An array of options to control how the query operates.
2476 *
2477 * @return DeleteQuery
2478 *   A new DeleteQuery object for this connection.
2479 */
2480function db_delete($table, array $options = array()) {
2481  if (empty($options['target']) || $options['target'] == 'slave') {
2482    $options['target'] = 'default';
2483  }
2484  return Database::getConnection($options['target'])->delete($table, $options);
2485}
2486
2487/**
2488 * Returns a new TruncateQuery object for the active database.
2489 *
2490 * @param $table
2491 *   The table from which to delete.
2492 * @param $options
2493 *   An array of options to control how the query operates.
2494 *
2495 * @return TruncateQuery
2496 *   A new TruncateQuery object for this connection.
2497 */
2498function db_truncate($table, array $options = array()) {
2499  if (empty($options['target']) || $options['target'] == 'slave') {
2500    $options['target'] = 'default';
2501  }
2502  return Database::getConnection($options['target'])->truncate($table, $options);
2503}
2504
2505/**
2506 * Returns a new SelectQuery object for the active database.
2507 *
2508 * @param $table
2509 *   The base table for this query. May be a string or another SelectQuery
2510 *   object. If a query object is passed, it will be used as a subselect.
2511 * @param $alias
2512 *   The alias for the base table of this query.
2513 * @param $options
2514 *   An array of options to control how the query operates.
2515 *
2516 * @return SelectQuery
2517 *   A new SelectQuery object for this connection.
2518 */
2519function db_select($table, $alias = NULL, array $options = array()) {
2520  if (empty($options['target'])) {
2521    $options['target'] = 'default';
2522  }
2523  return Database::getConnection($options['target'])->select($table, $alias, $options);
2524}
2525
2526/**
2527 * Returns a new transaction object for the active database.
2528 *
2529 * @param string $name
2530 *   Optional name of the transaction.
2531 * @param array $options
2532 *   An array of options to control how the transaction operates:
2533 *   - target: The database target name.
2534 *
2535 * @return DatabaseTransaction
2536 *   A new DatabaseTransaction object for this connection.
2537 */
2538function db_transaction($name = NULL, array $options = array()) {
2539  if (empty($options['target'])) {
2540    $options['target'] = 'default';
2541  }
2542  return Database::getConnection($options['target'])->startTransaction($name);
2543}
2544
2545/**
2546 * Sets a new active database.
2547 *
2548 * @param $key
2549 *   The key in the $databases array to set as the default database.
2550 *
2551 * @return
2552 *   The key of the formerly active database.
2553 */
2554function db_set_active($key = 'default') {
2555  return Database::setActiveConnection($key);
2556}
2557
2558/**
2559 * Restricts a dynamic table name to safe characters.
2560 *
2561 * Only keeps alphanumeric and underscores.
2562 *
2563 * @param $table
2564 *   The table name to escape.
2565 *
2566 * @return
2567 *   The escaped table name as a string.
2568 */
2569function db_escape_table($table) {
2570  return Database::getConnection()->escapeTable($table);
2571}
2572
2573/**
2574 * Restricts a dynamic column or constraint name to safe characters.
2575 *
2576 * Only keeps alphanumeric and underscores.
2577 *
2578 * @param $field
2579 *   The field name to escape.
2580 *
2581 * @return
2582 *   The escaped field name as a string.
2583 */
2584function db_escape_field($field) {
2585  return Database::getConnection()->escapeField($field);
2586}
2587
2588/**
2589 * Escapes characters that work as wildcard characters in a LIKE pattern.
2590 *
2591 * The wildcard characters "%" and "_" as well as backslash are prefixed with
2592 * a backslash. Use this to do a search for a verbatim string without any
2593 * wildcard behavior.
2594 *
2595 * For example, the following does a case-insensitive query for all rows whose
2596 * name starts with $prefix:
2597 * @code
2598 * $result = db_query(
2599 *   'SELECT * FROM person WHERE name LIKE :pattern',
2600 *   array(':pattern' => db_like($prefix) . '%')
2601 * );
2602 * @endcode
2603 *
2604 * Backslash is defined as escape character for LIKE patterns in
2605 * DatabaseCondition::mapConditionOperator().
2606 *
2607 * @param $string
2608 *   The string to escape.
2609 *
2610 * @return
2611 *   The escaped string.
2612 */
2613function db_like($string) {
2614  return Database::getConnection()->escapeLike($string);
2615}
2616
2617/**
2618 * Retrieves the name of the currently active database driver.
2619 *
2620 * @return
2621 *   The name of the currently active database driver.
2622 */
2623function db_driver() {
2624  return Database::getConnection()->driver();
2625}
2626
2627/**
2628 * Closes the active database connection.
2629 *
2630 * @param $options
2631 *   An array of options to control which connection is closed. Only the target
2632 *   key has any meaning in this case.
2633 */
2634function db_close(array $options = array()) {
2635  if (empty($options['target'])) {
2636    $options['target'] = NULL;
2637  }
2638  Database::closeConnection($options['target']);
2639}
2640
2641/**
2642 * Retrieves a unique id.
2643 *
2644 * Use this function if for some reason you can't use a serial field. Using a
2645 * serial field is preferred, and InsertQuery::execute() returns the value of
2646 * the last ID inserted.
2647 *
2648 * @param $existing_id
2649 *   After a database import, it might be that the sequences table is behind, so
2650 *   by passing in a minimum ID, it can be assured that we never issue the same
2651 *   ID.
2652 *
2653 * @return
2654 *   An integer number larger than any number returned before for this sequence.
2655 */
2656function db_next_id($existing_id = 0) {
2657  return Database::getConnection()->nextId($existing_id);
2658}
2659
2660/**
2661 * Returns a new DatabaseCondition, set to "OR" all conditions together.
2662 *
2663 * @return DatabaseCondition
2664 */
2665function db_or() {
2666  return new DatabaseCondition('OR');
2667}
2668
2669/**
2670 * Returns a new DatabaseCondition, set to "AND" all conditions together.
2671 *
2672 * @return DatabaseCondition
2673 */
2674function db_and() {
2675  return new DatabaseCondition('AND');
2676}
2677
2678/**
2679 * Returns a new DatabaseCondition, set to "XOR" all conditions together.
2680 *
2681 * @return DatabaseCondition
2682 */
2683function db_xor() {
2684  return new DatabaseCondition('XOR');
2685}
2686
2687/**
2688 * Returns a new DatabaseCondition, set to the specified conjunction.
2689 *
2690 * Internal API function call.  The db_and(), db_or(), and db_xor()
2691 * functions are preferred.
2692 *
2693 * @param $conjunction
2694 *   The conjunction to use for query conditions (AND, OR or XOR).
2695 * @return DatabaseCondition
2696 */
2697function db_condition($conjunction) {
2698  return new DatabaseCondition($conjunction);
2699}
2700
2701/**
2702 * @} End of "defgroup database".
2703 */
2704
2705
2706/**
2707 * @addtogroup schemaapi
2708 * @{
2709 */
2710
2711/**
2712 * Creates a new table from a Drupal table definition.
2713 *
2714 * @param $name
2715 *   The name of the table to create.
2716 * @param $table
2717 *   A Schema API table definition array.
2718 */
2719function db_create_table($name, $table) {
2720  return Database::getConnection()->schema()->createTable($name, $table);
2721}
2722
2723/**
2724 * Returns an array of field names from an array of key/index column specifiers.
2725 *
2726 * This is usually an identity function but if a key/index uses a column prefix
2727 * specification, this function extracts just the name.
2728 *
2729 * @param $fields
2730 *   An array of key/index column specifiers.
2731 *
2732 * @return
2733 *   An array of field names.
2734 */
2735function db_field_names($fields) {
2736  return Database::getConnection()->schema()->fieldNames($fields);
2737}
2738
2739/**
2740 * Checks if an index exists in the given table.
2741 *
2742 * @param $table
2743 *   The name of the table in drupal (no prefixing).
2744 * @param $name
2745 *   The name of the index in drupal (no prefixing).
2746 *
2747 * @return
2748 *   TRUE if the given index exists, otherwise FALSE.
2749 */
2750function db_index_exists($table, $name) {
2751  return Database::getConnection()->schema()->indexExists($table, $name);
2752}
2753
2754/**
2755 * Checks if a table exists.
2756 *
2757 * @param $table
2758 *   The name of the table in drupal (no prefixing).
2759 *
2760 * @return
2761 *   TRUE if the given table exists, otherwise FALSE.
2762 */
2763function db_table_exists($table) {
2764  return Database::getConnection()->schema()->tableExists($table);
2765}
2766
2767/**
2768 * Checks if a column exists in the given table.
2769 *
2770 * @param $table
2771 *   The name of the table in drupal (no prefixing).
2772 * @param $field
2773 *   The name of the field.
2774 *
2775 * @return
2776 *   TRUE if the given column exists, otherwise FALSE.
2777 */
2778function db_field_exists($table, $field) {
2779  return Database::getConnection()->schema()->fieldExists($table, $field);
2780}
2781
2782/**
2783 * Finds all tables that are like the specified base table name.
2784 *
2785 * @param $table_expression
2786 *   An SQL expression, for example "simpletest%" (without the quotes).
2787 *   BEWARE: this is not prefixed, the caller should take care of that.
2788 *
2789 * @return
2790 *   Array, both the keys and the values are the matching tables.
2791 */
2792function db_find_tables($table_expression) {
2793  return Database::getConnection()->schema()->findTables($table_expression);
2794}
2795
2796function _db_create_keys_sql($spec) {
2797  return Database::getConnection()->schema()->createKeysSql($spec);
2798}
2799
2800/**
2801 * Renames a table.
2802 *
2803 * @param $table
2804 *   The current name of the table to be renamed.
2805 * @param $new_name
2806 *   The new name for the table.
2807 */
2808function db_rename_table($table, $new_name) {
2809  return Database::getConnection()->schema()->renameTable($table, $new_name);
2810}
2811
2812/**
2813 * Drops a table.
2814 *
2815 * @param $table
2816 *   The table to be dropped.
2817 */
2818function db_drop_table($table) {
2819  return Database::getConnection()->schema()->dropTable($table);
2820}
2821
2822/**
2823 * Adds a new field to a table.
2824 *
2825 * @param $table
2826 *   Name of the table to be altered.
2827 * @param $field
2828 *   Name of the field to be added.
2829 * @param $spec
2830 *   The field specification array, as taken from a schema definition. The
2831 *   specification may also contain the key 'initial'; the newly-created field
2832 *   will be set to the value of the key in all rows. This is most useful for
2833 *   creating NOT NULL columns with no default value in existing tables.
2834 * @param $keys_new
2835 *   Optional keys and indexes specification to be created on the table along
2836 *   with adding the field. The format is the same as a table specification, but
2837 *   without the 'fields' element. If you are adding a type 'serial' field, you
2838 *   MUST specify at least one key or index including it in this array. See
2839 *   db_change_field() for more explanation why.
2840 *
2841 * @see db_change_field()
2842 */
2843function db_add_field($table, $field, $spec, $keys_new = array()) {
2844  return Database::getConnection()->schema()->addField($table, $field, $spec, $keys_new);
2845}
2846
2847/**
2848 * Drops a field.
2849 *
2850 * @param $table
2851 *   The table to be altered.
2852 * @param $field
2853 *   The field to be dropped.
2854 */
2855function db_drop_field($table, $field) {
2856  return Database::getConnection()->schema()->dropField($table, $field);
2857}
2858
2859/**
2860 * Sets the default value for a field.
2861 *
2862 * @param $table
2863 *   The table to be altered.
2864 * @param $field
2865 *   The field to be altered.
2866 * @param $default
2867 *   Default value to be set. NULL for 'default NULL'.
2868 */
2869function db_field_set_default($table, $field, $default) {
2870  return Database::getConnection()->schema()->fieldSetDefault($table, $field, $default);
2871}
2872
2873/**
2874 * Sets a field to have no default value.
2875 *
2876 * @param $table
2877 *   The table to be altered.
2878 * @param $field
2879 *   The field to be altered.
2880 */
2881function db_field_set_no_default($table, $field) {
2882  return Database::getConnection()->schema()->fieldSetNoDefault($table, $field);
2883}
2884
2885/**
2886 * Adds a primary key to a database table.
2887 *
2888 * @param $table
2889 *   Name of the table to be altered.
2890 * @param $fields
2891 *   Array of fields for the primary key.
2892 */
2893function db_add_primary_key($table, $fields) {
2894  return Database::getConnection()->schema()->addPrimaryKey($table, $fields);
2895}
2896
2897/**
2898 * Drops the primary key of a database table.
2899 *
2900 * @param $table
2901 *   Name of the table to be altered.
2902 */
2903function db_drop_primary_key($table) {
2904  return Database::getConnection()->schema()->dropPrimaryKey($table);
2905}
2906
2907/**
2908 * Adds a unique key.
2909 *
2910 * @param $table
2911 *   The table to be altered.
2912 * @param $name
2913 *   The name of the key.
2914 * @param $fields
2915 *   An array of field names.
2916 */
2917function db_add_unique_key($table, $name, $fields) {
2918  return Database::getConnection()->schema()->addUniqueKey($table, $name, $fields);
2919}
2920
2921/**
2922 * Drops a unique key.
2923 *
2924 * @param $table
2925 *   The table to be altered.
2926 * @param $name
2927 *   The name of the key.
2928 */
2929function db_drop_unique_key($table, $name) {
2930  return Database::getConnection()->schema()->dropUniqueKey($table, $name);
2931}
2932
2933/**
2934 * Adds an index.
2935 *
2936 * @param $table
2937 *   The table to be altered.
2938 * @param $name
2939 *   The name of the index.
2940 * @param $fields
2941 *   An array of field names.
2942 */
2943function db_add_index($table, $name, $fields) {
2944  return Database::getConnection()->schema()->addIndex($table, $name, $fields);
2945}
2946
2947/**
2948 * Drops an index.
2949 *
2950 * @param $table
2951 *   The table to be altered.
2952 * @param $name
2953 *   The name of the index.
2954 */
2955function db_drop_index($table, $name) {
2956  return Database::getConnection()->schema()->dropIndex($table, $name);
2957}
2958
2959/**
2960 * Changes a field definition.
2961 *
2962 * IMPORTANT NOTE: To maintain database portability, you have to explicitly
2963 * recreate all indices and primary keys that are using the changed field.
2964 *
2965 * That means that you have to drop all affected keys and indexes with
2966 * db_drop_{primary_key,unique_key,index}() before calling db_change_field().
2967 * To recreate the keys and indices, pass the key definitions as the optional
2968 * $keys_new argument directly to db_change_field().
2969 *
2970 * For example, suppose you have:
2971 * @code
2972 * $schema['foo'] = array(
2973 *   'fields' => array(
2974 *     'bar' => array('type' => 'int', 'not null' => TRUE)
2975 *   ),
2976 *   'primary key' => array('bar')
2977 * );
2978 * @endcode
2979 * and you want to change foo.bar to be type serial, leaving it as the primary
2980 * key. The correct sequence is:
2981 * @code
2982 * db_drop_primary_key('foo');
2983 * db_change_field('foo', 'bar', 'bar',
2984 *   array('type' => 'serial', 'not null' => TRUE),
2985 *   array('primary key' => array('bar')));
2986 * @endcode
2987 *
2988 * The reasons for this are due to the different database engines:
2989 *
2990 * On PostgreSQL, changing a field definition involves adding a new field and
2991 * dropping an old one which causes any indices, primary keys and sequences
2992 * (from serial-type fields) that use the changed field to be dropped.
2993 *
2994 * On MySQL, all type 'serial' fields must be part of at least one key or index
2995 * as soon as they are created. You cannot use
2996 * db_add_{primary_key,unique_key,index}() for this purpose because the ALTER
2997 * TABLE command will fail to add the column without a key or index
2998 * specification. The solution is to use the optional $keys_new argument to
2999 * create the key or index at the same time as field.
3000 *
3001 * You could use db_add_{primary_key,unique_key,index}() in all cases unless you
3002 * are converting a field to be type serial. You can use the $keys_new argument
3003 * in all cases.
3004 *
3005 * @param $table
3006 *   Name of the table.
3007 * @param $field
3008 *   Name of the field to change.
3009 * @param $field_new
3010 *   New name for the field (set to the same as $field if you don't want to
3011 *   change the name).
3012 * @param $spec
3013 *   The field specification for the new field.
3014 * @param $keys_new
3015 *   Optional keys and indexes specification to be created on the table along
3016 *   with changing the field. The format is the same as a table specification
3017 *   but without the 'fields' element.
3018 */
3019function db_change_field($table, $field, $field_new, $spec, $keys_new = array()) {
3020  return Database::getConnection()->schema()->changeField($table, $field, $field_new, $spec, $keys_new);
3021}
3022
3023/**
3024 * @} End of "addtogroup schemaapi".
3025 */
3026
3027/**
3028 * Sets a session variable specifying the lag time for ignoring a slave server.
3029 */
3030function db_ignore_slave() {
3031  $connection_info = Database::getConnectionInfo();
3032  // Only set ignore_slave_server if there are slave servers being used, which
3033  // is assumed if there are more than one.
3034  if (count($connection_info) > 1) {
3035    // Five minutes is long enough to allow the slave to break and resume
3036    // interrupted replication without causing problems on the Drupal site from
3037    // the old data.
3038    $duration = variable_get('maximum_replication_lag', 300);
3039    // Set session variable with amount of time to delay before using slave.
3040    $_SESSION['ignore_slave_server'] = REQUEST_TIME + $duration;
3041  }
3042}