Projet

Général

Profil

Paste
Télécharger (96,3 ko) Statistiques
| Branche: | Révision:

root / drupal7 / includes / database / database.inc @ 01dfd3b5

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
 */
187
abstract 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
  /**
300
   * List of escaped database, table, and field names, keyed by unescaped names.
301
   *
302
   * @var array
303
   */
304
  protected $escapedNames = array();
305

    
306
  /**
307
   * List of escaped aliases names, keyed by unescaped aliases.
308
   *
309
   * @var array
310
   */
311
  protected $escapedAliases = array();
312

    
313
  /**
314
   * List of un-prefixed table names, keyed by prefixed table names.
315
   *
316
   * @var array
317
   */
318
  protected $unprefixedTablesMap = array();
319

    
320
  function __construct($dsn, $username, $password, $driver_options = array()) {
321
    // Initialize and prepare the connection prefix.
322
    $this->setPrefix(isset($this->connectionOptions['prefix']) ? $this->connectionOptions['prefix'] : '');
323

    
324
    // Because the other methods don't seem to work right.
325
    $driver_options[PDO::ATTR_ERRMODE] = PDO::ERRMODE_EXCEPTION;
326

    
327
    // Call PDO::__construct and PDO::setAttribute.
328
    parent::__construct($dsn, $username, $password, $driver_options);
329

    
330
    // Set a Statement class, unless the driver opted out.
331
    if (!empty($this->statementClass)) {
332
      $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array($this->statementClass, array($this)));
333
    }
334
  }
335

    
336
  /**
337
   * Destroys this Connection object.
338
   *
339
   * PHP does not destruct an object if it is still referenced in other
340
   * variables. In case of PDO database connection objects, PHP only closes the
341
   * connection when the PDO object is destructed, so any references to this
342
   * object may cause the number of maximum allowed connections to be exceeded.
343
   */
344
  public function destroy() {
345
    // Destroy all references to this connection by setting them to NULL.
346
    // The Statement class attribute only accepts a new value that presents a
347
    // proper callable, so we reset it to PDOStatement.
348
    if (!empty($this->statementClass)) {
349
      $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array('PDOStatement', array()));
350
    }
351
    $this->schema = NULL;
352
  }
353

    
354
  /**
355
   * Returns the default query options for any given query.
356
   *
357
   * A given query can be customized with a number of option flags in an
358
   * associative array:
359
   * - target: The database "target" against which to execute a query. Valid
360
   *   values are "default" or "slave". The system will first try to open a
361
   *   connection to a database specified with the user-supplied key. If one
362
   *   is not available, it will silently fall back to the "default" target.
363
   *   If multiple databases connections are specified with the same target,
364
   *   one will be selected at random for the duration of the request.
365
   * - fetch: This element controls how rows from a result set will be
366
   *   returned. Legal values include PDO::FETCH_ASSOC, PDO::FETCH_BOTH,
367
   *   PDO::FETCH_OBJ, PDO::FETCH_NUM, or a string representing the name of a
368
   *   class. If a string is specified, each record will be fetched into a new
369
   *   object of that class. The behavior of all other values is defined by PDO.
370
   *   See http://php.net/manual/pdostatement.fetch.php
371
   * - return: Depending on the type of query, different return values may be
372
   *   meaningful. This directive instructs the system which type of return
373
   *   value is desired. The system will generally set the correct value
374
   *   automatically, so it is extremely rare that a module developer will ever
375
   *   need to specify this value. Setting it incorrectly will likely lead to
376
   *   unpredictable results or fatal errors. Legal values include:
377
   *   - Database::RETURN_STATEMENT: Return the prepared statement object for
378
   *     the query. This is usually only meaningful for SELECT queries, where
379
   *     the statement object is how one accesses the result set returned by the
380
   *     query.
381
   *   - Database::RETURN_AFFECTED: Return the number of rows affected by an
382
   *     UPDATE or DELETE query. Be aware that means the number of rows actually
383
   *     changed, not the number of rows matched by the WHERE clause.
384
   *   - Database::RETURN_INSERT_ID: Return the sequence ID (primary key)
385
   *     created by an INSERT statement on a table that contains a serial
386
   *     column.
387
   *   - Database::RETURN_NULL: Do not return anything, as there is no
388
   *     meaningful value to return. That is the case for INSERT queries on
389
   *     tables that do not contain a serial column.
390
   * - throw_exception: By default, the database system will catch any errors
391
   *   on a query as an Exception, log it, and then rethrow it so that code
392
   *   further up the call chain can take an appropriate action. To suppress
393
   *   that behavior and simply return NULL on failure, set this option to
394
   *   FALSE.
395
   *
396
   * @return
397
   *   An array of default query options.
398
   */
399
  protected function defaultOptions() {
400
    return array(
401
      'target' => 'default',
402
      'fetch' => PDO::FETCH_OBJ,
403
      'return' => Database::RETURN_STATEMENT,
404
      'throw_exception' => TRUE,
405
    );
406
  }
407

    
408
  /**
409
   * Returns the connection information for this connection object.
410
   *
411
   * Note that Database::getConnectionInfo() is for requesting information
412
   * about an arbitrary database connection that is defined. This method
413
   * is for requesting the connection information of this specific
414
   * open connection object.
415
   *
416
   * @return
417
   *   An array of the connection information. The exact list of
418
   *   properties is driver-dependent.
419
   */
420
  public function getConnectionOptions() {
421
    return $this->connectionOptions;
422
  }
423

    
424
  /**
425
   * Set the list of prefixes used by this database connection.
426
   *
427
   * @param $prefix
428
   *   The prefixes, in any of the multiple forms documented in
429
   *   default.settings.php.
430
   */
431
  protected function setPrefix($prefix) {
432
    if (is_array($prefix)) {
433
      $this->prefixes = $prefix + array('default' => '');
434
    }
435
    else {
436
      $this->prefixes = array('default' => $prefix);
437
    }
438

    
439
    // Set up variables for use in prefixTables(). Replace table-specific
440
    // prefixes first.
441
    $this->prefixSearch = array();
442
    $this->prefixReplace = array();
443
    foreach ($this->prefixes as $key => $val) {
444
      if ($key != 'default') {
445
        $this->prefixSearch[] = '{' . $key . '}';
446
        $this->prefixReplace[] = $val . $key;
447
      }
448
    }
449
    // Then replace remaining tables with the default prefix.
450
    $this->prefixSearch[] = '{';
451
    $this->prefixReplace[] = $this->prefixes['default'];
452
    $this->prefixSearch[] = '}';
453
    $this->prefixReplace[] = '';
454

    
455
    // Set up a map of prefixed => un-prefixed tables.
456
    foreach ($this->prefixes as $table_name => $prefix) {
457
      if ($table_name !== 'default') {
458
        $this->unprefixedTablesMap[$prefix . $table_name] = $table_name;
459
      }
460
    }
461
  }
462

    
463
  /**
464
   * Appends a database prefix to all tables in a query.
465
   *
466
   * Queries sent to Drupal should wrap all table names in curly brackets. This
467
   * function searches for this syntax and adds Drupal's table prefix to all
468
   * tables, allowing Drupal to coexist with other systems in the same database
469
   * and/or schema if necessary.
470
   *
471
   * @param $sql
472
   *   A string containing a partial or entire SQL query.
473
   *
474
   * @return
475
   *   The properly-prefixed string.
476
   */
477
  public function prefixTables($sql) {
478
    return str_replace($this->prefixSearch, $this->prefixReplace, $sql);
479
  }
480

    
481
  /**
482
   * Find the prefix for a table.
483
   *
484
   * This function is for when you want to know the prefix of a table. This
485
   * is not used in prefixTables due to performance reasons.
486
   */
487
  public function tablePrefix($table = 'default') {
488
    if (isset($this->prefixes[$table])) {
489
      return $this->prefixes[$table];
490
    }
491
    else {
492
      return $this->prefixes['default'];
493
    }
494
  }
495

    
496
  /**
497
   * Gets a list of individually prefixed table names.
498
   *
499
   * @return array
500
   *   An array of un-prefixed table names, keyed by their fully qualified table
501
   *   names (i.e. prefix + table_name).
502
   */
503
  public function getUnprefixedTablesMap() {
504
    return $this->unprefixedTablesMap;
505
  }
506

    
507
  /**
508
   * Prepares a query string and returns the prepared statement.
509
   *
510
   * This method caches prepared statements, reusing them when
511
   * possible. It also prefixes tables names enclosed in curly-braces.
512
   *
513
   * @param $query
514
   *   The query string as SQL, with curly-braces surrounding the
515
   *   table names.
516
   *
517
   * @return DatabaseStatementInterface
518
   *   A PDO prepared statement ready for its execute() method.
519
   */
520
  public function prepareQuery($query) {
521
    $query = $this->prefixTables($query);
522

    
523
    // Call PDO::prepare.
524
    return parent::prepare($query);
525
  }
526

    
527
  /**
528
   * Tells this connection object what its target value is.
529
   *
530
   * This is needed for logging and auditing. It's sloppy to do in the
531
   * constructor because the constructor for child classes has a different
532
   * signature. We therefore also ensure that this function is only ever
533
   * called once.
534
   *
535
   * @param $target
536
   *   The target this connection is for. Set to NULL (default) to disable
537
   *   logging entirely.
538
   */
539
  public function setTarget($target = NULL) {
540
    if (!isset($this->target)) {
541
      $this->target = $target;
542
    }
543
  }
544

    
545
  /**
546
   * Returns the target this connection is associated with.
547
   *
548
   * @return
549
   *   The target string of this connection.
550
   */
551
  public function getTarget() {
552
    return $this->target;
553
  }
554

    
555
  /**
556
   * Tells this connection object what its key is.
557
   *
558
   * @param $target
559
   *   The key this connection is for.
560
   */
561
  public function setKey($key) {
562
    if (!isset($this->key)) {
563
      $this->key = $key;
564
    }
565
  }
566

    
567
  /**
568
   * Returns the key this connection is associated with.
569
   *
570
   * @return
571
   *   The key of this connection.
572
   */
573
  public function getKey() {
574
    return $this->key;
575
  }
576

    
577
  /**
578
   * Associates a logging object with this connection.
579
   *
580
   * @param $logger
581
   *   The logging object we want to use.
582
   */
583
  public function setLogger(DatabaseLog $logger) {
584
    $this->logger = $logger;
585
  }
586

    
587
  /**
588
   * Gets the current logging object for this connection.
589
   *
590
   * @return DatabaseLog
591
   *   The current logging object for this connection. If there isn't one,
592
   *   NULL is returned.
593
   */
594
  public function getLogger() {
595
    return $this->logger;
596
  }
597

    
598
  /**
599
   * Creates the appropriate sequence name for a given table and serial field.
600
   *
601
   * This information is exposed to all database drivers, although it is only
602
   * useful on some of them. This method is table prefix-aware.
603
   *
604
   * @param $table
605
   *   The table name to use for the sequence.
606
   * @param $field
607
   *   The field name to use for the sequence.
608
   *
609
   * @return
610
   *   A table prefix-parsed string for the sequence name.
611
   */
612
  public function makeSequenceName($table, $field) {
613
    return $this->prefixTables('{' . $table . '}_' . $field . '_seq');
614
  }
615

    
616
  /**
617
   * Flatten an array of query comments into a single comment string.
618
   *
619
   * The comment string will be sanitized to avoid SQL injection attacks.
620
   *
621
   * @param $comments
622
   *   An array of query comment strings.
623
   *
624
   * @return
625
   *   A sanitized comment string.
626
   */
627
  public function makeComment($comments) {
628
    if (empty($comments))
629
      return '';
630

    
631
    // Flatten the array of comments.
632
    $comment = implode('; ', $comments);
633

    
634
    // Sanitize the comment string so as to avoid SQL injection attacks.
635
    return '/* ' . $this->filterComment($comment) . ' */ ';
636
  }
637

    
638
  /**
639
   * Sanitize a query comment string.
640
   *
641
   * Ensure a query comment does not include strings such as "* /" that might
642
   * terminate the comment early. This avoids SQL injection attacks via the
643
   * query comment. The comment strings in this example are separated by a
644
   * space to avoid PHP parse errors.
645
   *
646
   * For example, the comment:
647
   * @code
648
   * db_update('example')
649
   *  ->condition('id', $id)
650
   *  ->fields(array('field2' => 10))
651
   *  ->comment('Exploit * / DROP TABLE node; --')
652
   *  ->execute()
653
   * @endcode
654
   *
655
   * Would result in the following SQL statement being generated:
656
   * @code
657
   * "/ * Exploit * / DROP TABLE node; -- * / UPDATE example SET field2=..."
658
   * @endcode
659
   *
660
   * Unless the comment is sanitised first, the SQL server would drop the
661
   * node table and ignore the rest of the SQL statement.
662
   *
663
   * @param $comment
664
   *   A query comment string.
665
   *
666
   * @return
667
   *   A sanitized version of the query comment string.
668
   */
669
  protected function filterComment($comment = '') {
670
    return strtr($comment, array('*' => ' * '));
671
  }
672

    
673
  /**
674
   * Executes a query string against the database.
675
   *
676
   * This method provides a central handler for the actual execution of every
677
   * query. All queries executed by Drupal are executed as PDO prepared
678
   * statements.
679
   *
680
   * @param $query
681
   *   The query to execute. In most cases this will be a string containing
682
   *   an SQL query with placeholders. An already-prepared instance of
683
   *   DatabaseStatementInterface may also be passed in order to allow calling
684
   *   code to manually bind variables to a query. If a
685
   *   DatabaseStatementInterface is passed, the $args array will be ignored.
686
   *   It is extremely rare that module code will need to pass a statement
687
   *   object to this method. It is used primarily for database drivers for
688
   *   databases that require special LOB field handling.
689
   * @param $args
690
   *   An array of arguments for the prepared statement. If the prepared
691
   *   statement uses ? placeholders, this array must be an indexed array.
692
   *   If it contains named placeholders, it must be an associative array.
693
   * @param $options
694
   *   An associative array of options to control how the query is run. See
695
   *   the documentation for DatabaseConnection::defaultOptions() for details.
696
   *
697
   * @return DatabaseStatementInterface
698
   *   This method will return one of: the executed statement, the number of
699
   *   rows affected by the query (not the number matched), or the generated
700
   *   insert ID of the last query, depending on the value of
701
   *   $options['return']. Typically that value will be set by default or a
702
   *   query builder and should not be set by a user. If there is an error,
703
   *   this method will return NULL and may throw an exception if
704
   *   $options['throw_exception'] is TRUE.
705
   *
706
   * @throws PDOException
707
   */
708
  public function query($query, array $args = array(), $options = array()) {
709

    
710
    // Use default values if not already set.
711
    $options += $this->defaultOptions();
712

    
713
    try {
714
      // We allow either a pre-bound statement object or a literal string.
715
      // In either case, we want to end up with an executed statement object,
716
      // which we pass to PDOStatement::execute.
717
      if ($query instanceof DatabaseStatementInterface) {
718
        $stmt = $query;
719
        $stmt->execute(NULL, $options);
720
      }
721
      else {
722
        $this->expandArguments($query, $args);
723
        $stmt = $this->prepareQuery($query);
724
        $stmt->execute($args, $options);
725
      }
726

    
727
      // Depending on the type of query we may need to return a different value.
728
      // See DatabaseConnection::defaultOptions() for a description of each
729
      // value.
730
      switch ($options['return']) {
731
        case Database::RETURN_STATEMENT:
732
          return $stmt;
733
        case Database::RETURN_AFFECTED:
734
          return $stmt->rowCount();
735
        case Database::RETURN_INSERT_ID:
736
          return $this->lastInsertId();
737
        case Database::RETURN_NULL:
738
          return;
739
        default:
740
          throw new PDOException('Invalid return directive: ' . $options['return']);
741
      }
742
    }
743
    catch (PDOException $e) {
744
      if ($options['throw_exception']) {
745
        // Add additional debug information.
746
        if ($query instanceof DatabaseStatementInterface) {
747
          $e->query_string = $stmt->getQueryString();
748
        }
749
        else {
750
          $e->query_string = $query;
751
        }
752
        $e->args = $args;
753
        throw $e;
754
      }
755
      return NULL;
756
    }
757
  }
758

    
759
  /**
760
   * Expands out shorthand placeholders.
761
   *
762
   * Drupal supports an alternate syntax for doing arrays of values. We
763
   * therefore need to expand them out into a full, executable query string.
764
   *
765
   * @param $query
766
   *   The query string to modify.
767
   * @param $args
768
   *   The arguments for the query.
769
   *
770
   * @return
771
   *   TRUE if the query was modified, FALSE otherwise.
772
   */
773
  protected function expandArguments(&$query, &$args) {
774
    $modified = FALSE;
775

    
776
    // If the placeholder value to insert is an array, assume that we need
777
    // to expand it out into a comma-delimited set of placeholders.
778
    foreach (array_filter($args, 'is_array') as $key => $data) {
779
      $new_keys = array();
780
      foreach (array_values($data) as $i => $value) {
781
        // This assumes that there are no other placeholders that use the same
782
        // name.  For example, if the array placeholder is defined as :example
783
        // and there is already an :example_2 placeholder, this will generate
784
        // a duplicate key.  We do not account for that as the calling code
785
        // is already broken if that happens.
786
        $new_keys[$key . '_' . $i] = $value;
787
      }
788

    
789
      // Update the query with the new placeholders.
790
      // preg_replace is necessary to ensure the replacement does not affect
791
      // placeholders that start with the same exact text. For example, if the
792
      // query contains the placeholders :foo and :foobar, and :foo has an
793
      // array of values, using str_replace would affect both placeholders,
794
      // but using the following preg_replace would only affect :foo because
795
      // it is followed by a non-word character.
796
      $query = preg_replace('#' . $key . '\b#', implode(', ', array_keys($new_keys)), $query);
797

    
798
      // Update the args array with the new placeholders.
799
      unset($args[$key]);
800
      $args += $new_keys;
801

    
802
      $modified = TRUE;
803
    }
804

    
805
    return $modified;
806
  }
807

    
808
  /**
809
   * Gets the driver-specific override class if any for the specified class.
810
   *
811
   * @param string $class
812
   *   The class for which we want the potentially driver-specific class.
813
   * @param array $files
814
   *   The name of the files in which the driver-specific class can be.
815
   * @param $use_autoload
816
   *   If TRUE, attempt to load classes using PHP's autoload capability
817
   *   as well as the manual approach here.
818
   * @return string
819
   *   The name of the class that should be used for this driver.
820
   */
821
  public function getDriverClass($class, array $files = array(), $use_autoload = FALSE) {
822
    if (empty($this->driverClasses[$class])) {
823
      $driver = $this->driver();
824
      $this->driverClasses[$class] = $class . '_' . $driver;
825
      Database::loadDriverFile($driver, $files);
826
      if (!class_exists($this->driverClasses[$class], $use_autoload)) {
827
        $this->driverClasses[$class] = $class;
828
      }
829
    }
830
    return $this->driverClasses[$class];
831
  }
832

    
833
  /**
834
   * Prepares and returns a SELECT query object.
835
   *
836
   * @param $table
837
   *   The base table for this query, that is, the first table in the FROM
838
   *   clause. This table will also be used as the "base" table for query_alter
839
   *   hook implementations.
840
   * @param $alias
841
   *   The alias of the base table of this query.
842
   * @param $options
843
   *   An array of options on the query.
844
   *
845
   * @return SelectQueryInterface
846
   *   An appropriate SelectQuery object for this database connection. Note that
847
   *   it may be a driver-specific subclass of SelectQuery, depending on the
848
   *   driver.
849
   *
850
   * @see SelectQuery
851
   */
852
  public function select($table, $alias = NULL, array $options = array()) {
853
    $class = $this->getDriverClass('SelectQuery', array('query.inc', 'select.inc'));
854
    return new $class($table, $alias, $this, $options);
855
  }
856

    
857
  /**
858
   * Prepares and returns an INSERT query object.
859
   *
860
   * @param $options
861
   *   An array of options on the query.
862
   *
863
   * @return InsertQuery
864
   *   A new InsertQuery object.
865
   *
866
   * @see InsertQuery
867
   */
868
  public function insert($table, array $options = array()) {
869
    $class = $this->getDriverClass('InsertQuery', array('query.inc'));
870
    return new $class($this, $table, $options);
871
  }
872

    
873
  /**
874
   * Prepares and returns a MERGE query object.
875
   *
876
   * @param $options
877
   *   An array of options on the query.
878
   *
879
   * @return MergeQuery
880
   *   A new MergeQuery object.
881
   *
882
   * @see MergeQuery
883
   */
884
  public function merge($table, array $options = array()) {
885
    $class = $this->getDriverClass('MergeQuery', array('query.inc'));
886
    return new $class($this, $table, $options);
887
  }
888

    
889

    
890
  /**
891
   * Prepares and returns an UPDATE query object.
892
   *
893
   * @param $options
894
   *   An array of options on the query.
895
   *
896
   * @return UpdateQuery
897
   *   A new UpdateQuery object.
898
   *
899
   * @see UpdateQuery
900
   */
901
  public function update($table, array $options = array()) {
902
    $class = $this->getDriverClass('UpdateQuery', array('query.inc'));
903
    return new $class($this, $table, $options);
904
  }
905

    
906
  /**
907
   * Prepares and returns a DELETE query object.
908
   *
909
   * @param $options
910
   *   An array of options on the query.
911
   *
912
   * @return DeleteQuery
913
   *   A new DeleteQuery object.
914
   *
915
   * @see DeleteQuery
916
   */
917
  public function delete($table, array $options = array()) {
918
    $class = $this->getDriverClass('DeleteQuery', array('query.inc'));
919
    return new $class($this, $table, $options);
920
  }
921

    
922
  /**
923
   * Prepares and returns a TRUNCATE query object.
924
   *
925
   * @param $options
926
   *   An array of options on the query.
927
   *
928
   * @return TruncateQuery
929
   *   A new TruncateQuery object.
930
   *
931
   * @see TruncateQuery
932
   */
933
  public function truncate($table, array $options = array()) {
934
    $class = $this->getDriverClass('TruncateQuery', array('query.inc'));
935
    return new $class($this, $table, $options);
936
  }
937

    
938
  /**
939
   * Returns a DatabaseSchema object for manipulating the schema.
940
   *
941
   * This method will lazy-load the appropriate schema library file.
942
   *
943
   * @return DatabaseSchema
944
   *   The DatabaseSchema object for this connection.
945
   */
946
  public function schema() {
947
    if (empty($this->schema)) {
948
      $class = $this->getDriverClass('DatabaseSchema', array('schema.inc'));
949
      if (class_exists($class)) {
950
        $this->schema = new $class($this);
951
      }
952
    }
953
    return $this->schema;
954
  }
955

    
956
  /**
957
   * Escapes a table name string.
958
   *
959
   * Force all table names to be strictly alphanumeric-plus-underscore.
960
   * For some database drivers, it may also wrap the table name in
961
   * database-specific escape characters.
962
   *
963
   * @return string
964
   *   The sanitized table name string.
965
   */
966
  public function escapeTable($table) {
967
    if (!isset($this->escapedNames[$table])) {
968
      $this->escapedNames[$table] = preg_replace('/[^A-Za-z0-9_.]+/', '', $table);
969
    }
970
    return $this->escapedNames[$table];
971
  }
972

    
973
  /**
974
   * Escapes a field name string.
975
   *
976
   * Force all field names to be strictly alphanumeric-plus-underscore.
977
   * For some database drivers, it may also wrap the field name in
978
   * database-specific escape characters.
979
   *
980
   * @return string
981
   *   The sanitized field name string.
982
   */
983
  public function escapeField($field) {
984
    if (!isset($this->escapedNames[$field])) {
985
      $this->escapedNames[$field] = preg_replace('/[^A-Za-z0-9_.]+/', '', $field);
986
    }
987
    return $this->escapedNames[$field];
988
  }
989

    
990
  /**
991
   * Escapes an alias name string.
992
   *
993
   * Force all alias names to be strictly alphanumeric-plus-underscore. In
994
   * contrast to DatabaseConnection::escapeField() /
995
   * DatabaseConnection::escapeTable(), this doesn't allow the period (".")
996
   * because that is not allowed in aliases.
997
   *
998
   * @return string
999
   *   The sanitized field name string.
1000
   */
1001
  public function escapeAlias($field) {
1002
    if (!isset($this->escapedAliases[$field])) {
1003
      $this->escapedAliases[$field] = preg_replace('/[^A-Za-z0-9_]+/', '', $field);
1004
    }
1005
    return $this->escapedAliases[$field];
1006
  }
1007

    
1008
  /**
1009
   * Escapes characters that work as wildcard characters in a LIKE pattern.
1010
   *
1011
   * The wildcard characters "%" and "_" as well as backslash are prefixed with
1012
   * a backslash. Use this to do a search for a verbatim string without any
1013
   * wildcard behavior.
1014
   *
1015
   * For example, the following does a case-insensitive query for all rows whose
1016
   * name starts with $prefix:
1017
   * @code
1018
   * $result = db_query(
1019
   *   'SELECT * FROM person WHERE name LIKE :pattern',
1020
   *   array(':pattern' => db_like($prefix) . '%')
1021
   * );
1022
   * @endcode
1023
   *
1024
   * Backslash is defined as escape character for LIKE patterns in
1025
   * DatabaseCondition::mapConditionOperator().
1026
   *
1027
   * @param $string
1028
   *   The string to escape.
1029
   *
1030
   * @return
1031
   *   The escaped string.
1032
   */
1033
  public function escapeLike($string) {
1034
    return addcslashes($string, '\%_');
1035
  }
1036

    
1037
  /**
1038
   * Determines if there is an active transaction open.
1039
   *
1040
   * @return
1041
   *   TRUE if we're currently in a transaction, FALSE otherwise.
1042
   */
1043
  public function inTransaction() {
1044
    return ($this->transactionDepth() > 0);
1045
  }
1046

    
1047
  /**
1048
   * Determines current transaction depth.
1049
   */
1050
  public function transactionDepth() {
1051
    return count($this->transactionLayers);
1052
  }
1053

    
1054
  /**
1055
   * Returns a new DatabaseTransaction object on this connection.
1056
   *
1057
   * @param $name
1058
   *   Optional name of the savepoint.
1059
   *
1060
   * @return DatabaseTransaction
1061
   *   A DatabaseTransaction object.
1062
   *
1063
   * @see DatabaseTransaction
1064
   */
1065
  public function startTransaction($name = '') {
1066
    $class = $this->getDriverClass('DatabaseTransaction');
1067
    return new $class($this, $name);
1068
  }
1069

    
1070
  /**
1071
   * Rolls back the transaction entirely or to a named savepoint.
1072
   *
1073
   * This method throws an exception if no transaction is active.
1074
   *
1075
   * @param $savepoint_name
1076
   *   The name of the savepoint. The default, 'drupal_transaction', will roll
1077
   *   the entire transaction back.
1078
   *
1079
   * @throws DatabaseTransactionNoActiveException
1080
   *
1081
   * @see DatabaseTransaction::rollback()
1082
   */
1083
  public function rollback($savepoint_name = 'drupal_transaction') {
1084
    if (!$this->supportsTransactions()) {
1085
      return;
1086
    }
1087
    if (!$this->inTransaction()) {
1088
      throw new DatabaseTransactionNoActiveException();
1089
    }
1090
    // A previous rollback to an earlier savepoint may mean that the savepoint
1091
    // in question has already been accidentally committed.
1092
    if (!isset($this->transactionLayers[$savepoint_name])) {
1093
      throw new DatabaseTransactionNoActiveException();
1094
    }
1095

    
1096
    // We need to find the point we're rolling back to, all other savepoints
1097
    // before are no longer needed. If we rolled back other active savepoints,
1098
    // we need to throw an exception.
1099
    $rolled_back_other_active_savepoints = FALSE;
1100
    while ($savepoint = array_pop($this->transactionLayers)) {
1101
      if ($savepoint == $savepoint_name) {
1102
        // If it is the last the transaction in the stack, then it is not a
1103
        // savepoint, it is the transaction itself so we will need to roll back
1104
        // the transaction rather than a savepoint.
1105
        if (empty($this->transactionLayers)) {
1106
          break;
1107
        }
1108
        $this->query('ROLLBACK TO SAVEPOINT ' . $savepoint);
1109
        $this->popCommittableTransactions();
1110
        if ($rolled_back_other_active_savepoints) {
1111
          throw new DatabaseTransactionOutOfOrderException();
1112
        }
1113
        return;
1114
      }
1115
      else {
1116
        $rolled_back_other_active_savepoints = TRUE;
1117
      }
1118
    }
1119
    parent::rollBack();
1120
    if ($rolled_back_other_active_savepoints) {
1121
      throw new DatabaseTransactionOutOfOrderException();
1122
    }
1123
  }
1124

    
1125
  /**
1126
   * Increases the depth of transaction nesting.
1127
   *
1128
   * If no transaction is already active, we begin a new transaction.
1129
   *
1130
   * @throws DatabaseTransactionNameNonUniqueException
1131
   *
1132
   * @see DatabaseTransaction
1133
   */
1134
  public function pushTransaction($name) {
1135
    if (!$this->supportsTransactions()) {
1136
      return;
1137
    }
1138
    if (isset($this->transactionLayers[$name])) {
1139
      throw new DatabaseTransactionNameNonUniqueException($name . " is already in use.");
1140
    }
1141
    // If we're already in a transaction then we want to create a savepoint
1142
    // rather than try to create another transaction.
1143
    if ($this->inTransaction()) {
1144
      $this->query('SAVEPOINT ' . $name);
1145
    }
1146
    else {
1147
      parent::beginTransaction();
1148
    }
1149
    $this->transactionLayers[$name] = $name;
1150
  }
1151

    
1152
  /**
1153
   * Decreases the depth of transaction nesting.
1154
   *
1155
   * If we pop off the last transaction layer, then we either commit or roll
1156
   * back the transaction as necessary. If no transaction is active, we return
1157
   * because the transaction may have manually been rolled back.
1158
   *
1159
   * @param $name
1160
   *   The name of the savepoint
1161
   *
1162
   * @throws DatabaseTransactionNoActiveException
1163
   * @throws DatabaseTransactionCommitFailedException
1164
   *
1165
   * @see DatabaseTransaction
1166
   */
1167
  public function popTransaction($name) {
1168
    if (!$this->supportsTransactions()) {
1169
      return;
1170
    }
1171
    // The transaction has already been committed earlier. There is nothing we
1172
    // need to do. If this transaction was part of an earlier out-of-order
1173
    // rollback, an exception would already have been thrown by
1174
    // Database::rollback().
1175
    if (!isset($this->transactionLayers[$name])) {
1176
      return;
1177
    }
1178

    
1179
    // Mark this layer as committable.
1180
    $this->transactionLayers[$name] = FALSE;
1181
    $this->popCommittableTransactions();
1182
  }
1183

    
1184
  /**
1185
   * Internal function: commit all the transaction layers that can commit.
1186
   */
1187
  protected function popCommittableTransactions() {
1188
    // Commit all the committable layers.
1189
    foreach (array_reverse($this->transactionLayers) as $name => $active) {
1190
      // Stop once we found an active transaction.
1191
      if ($active) {
1192
        break;
1193
      }
1194

    
1195
      // If there are no more layers left then we should commit.
1196
      unset($this->transactionLayers[$name]);
1197
      if (empty($this->transactionLayers)) {
1198
        if (!parent::commit()) {
1199
          throw new DatabaseTransactionCommitFailedException();
1200
        }
1201
      }
1202
      else {
1203
        $this->query('RELEASE SAVEPOINT ' . $name);
1204
      }
1205
    }
1206
  }
1207

    
1208
  /**
1209
   * Runs a limited-range query on this database object.
1210
   *
1211
   * Use this as a substitute for ->query() when a subset of the query is to be
1212
   * returned. User-supplied arguments to the query should be passed in as
1213
   * separate parameters so that they can be properly escaped to avoid SQL
1214
   * injection attacks.
1215
   *
1216
   * @param $query
1217
   *   A string containing an SQL query.
1218
   * @param $args
1219
   *   An array of values to substitute into the query at placeholder markers.
1220
   * @param $from
1221
   *   The first result row to return.
1222
   * @param $count
1223
   *   The maximum number of result rows to return.
1224
   * @param $options
1225
   *   An array of options on the query.
1226
   *
1227
   * @return DatabaseStatementInterface
1228
   *   A database query result resource, or NULL if the query was not executed
1229
   *   correctly.
1230
   */
1231
  abstract public function queryRange($query, $from, $count, array $args = array(), array $options = array());
1232

    
1233
  /**
1234
   * Generates a temporary table name.
1235
   *
1236
   * @return
1237
   *   A table name.
1238
   */
1239
  protected function generateTemporaryTableName() {
1240
    return "db_temporary_" . $this->temporaryNameIndex++;
1241
  }
1242

    
1243
  /**
1244
   * Runs a SELECT query and stores its results in a temporary table.
1245
   *
1246
   * Use this as a substitute for ->query() when the results need to stored
1247
   * in a temporary table. Temporary tables exist for the duration of the page
1248
   * request. User-supplied arguments to the query should be passed in as
1249
   * separate parameters so that they can be properly escaped to avoid SQL
1250
   * injection attacks.
1251
   *
1252
   * Note that if you need to know how many results were returned, you should do
1253
   * a SELECT COUNT(*) on the temporary table afterwards.
1254
   *
1255
   * @param $query
1256
   *   A string containing a normal SELECT SQL query.
1257
   * @param $args
1258
   *   An array of values to substitute into the query at placeholder markers.
1259
   * @param $options
1260
   *   An associative array of options to control how the query is run. See
1261
   *   the documentation for DatabaseConnection::defaultOptions() for details.
1262
   *
1263
   * @return
1264
   *   The name of the temporary table.
1265
   */
1266
  abstract function queryTemporary($query, array $args = array(), array $options = array());
1267

    
1268
  /**
1269
   * Returns the type of database driver.
1270
   *
1271
   * This is not necessarily the same as the type of the database itself. For
1272
   * instance, there could be two MySQL drivers, mysql and mysql_mock. This
1273
   * function would return different values for each, but both would return
1274
   * "mysql" for databaseType().
1275
   */
1276
  abstract public function driver();
1277

    
1278
  /**
1279
   * Returns the version of the database server.
1280
   */
1281
  public function version() {
1282
    return $this->getAttribute(PDO::ATTR_SERVER_VERSION);
1283
  }
1284

    
1285
  /**
1286
   * Determines if this driver supports transactions.
1287
   *
1288
   * @return
1289
   *   TRUE if this connection supports transactions, FALSE otherwise.
1290
   */
1291
  public function supportsTransactions() {
1292
    return $this->transactionSupport;
1293
  }
1294

    
1295
  /**
1296
   * Determines if this driver supports transactional DDL.
1297
   *
1298
   * DDL queries are those that change the schema, such as ALTER queries.
1299
   *
1300
   * @return
1301
   *   TRUE if this connection supports transactions for DDL queries, FALSE
1302
   *   otherwise.
1303
   */
1304
  public function supportsTransactionalDDL() {
1305
    return $this->transactionalDDLSupport;
1306
  }
1307

    
1308
  /**
1309
   * Returns the name of the PDO driver for this connection.
1310
   */
1311
  abstract public function databaseType();
1312

    
1313

    
1314
  /**
1315
   * Gets any special processing requirements for the condition operator.
1316
   *
1317
   * Some condition types require special processing, such as IN, because
1318
   * the value data they pass in is not a simple value. This is a simple
1319
   * overridable lookup function. Database connections should define only
1320
   * those operators they wish to be handled differently than the default.
1321
   *
1322
   * @param $operator
1323
   *   The condition operator, such as "IN", "BETWEEN", etc. Case-sensitive.
1324
   *
1325
   * @return
1326
   *   The extra handling directives for the specified operator, or NULL.
1327
   *
1328
   * @see DatabaseCondition::compile()
1329
   */
1330
  abstract public function mapConditionOperator($operator);
1331

    
1332
  /**
1333
   * Throws an exception to deny direct access to transaction commits.
1334
   *
1335
   * We do not want to allow users to commit transactions at any time, only
1336
   * by destroying the transaction object or allowing it to go out of scope.
1337
   * A direct commit bypasses all of the safety checks we've built on top of
1338
   * PDO's transaction routines.
1339
   *
1340
   * @throws DatabaseTransactionExplicitCommitNotAllowedException
1341
   *
1342
   * @see DatabaseTransaction
1343
   */
1344
  public function commit() {
1345
    throw new DatabaseTransactionExplicitCommitNotAllowedException();
1346
  }
1347

    
1348
  /**
1349
   * Retrieves an unique id from a given sequence.
1350
   *
1351
   * Use this function if for some reason you can't use a serial field. For
1352
   * example, MySQL has no ways of reading of the current value of a sequence
1353
   * and PostgreSQL can not advance the sequence to be larger than a given
1354
   * value. Or sometimes you just need a unique integer.
1355
   *
1356
   * @param $existing_id
1357
   *   After a database import, it might be that the sequences table is behind,
1358
   *   so by passing in the maximum existing id, it can be assured that we
1359
   *   never issue the same id.
1360
   *
1361
   * @return
1362
   *   An integer number larger than any number returned by earlier calls and
1363
   *   also larger than the $existing_id if one was passed in.
1364
   */
1365
  abstract public function nextId($existing_id = 0);
1366

    
1367
  /**
1368
   * Checks whether utf8mb4 support is configurable in settings.php.
1369
   *
1370
   * @return bool
1371
   */
1372
  public function utf8mb4IsConfigurable() {
1373
    // Since 4 byte UTF-8 is not supported by default, there is nothing to
1374
    // configure.
1375
    return FALSE;
1376
  }
1377

    
1378
  /**
1379
   * Checks whether utf8mb4 support is currently active.
1380
   *
1381
   * @return bool
1382
   */
1383
  public function utf8mb4IsActive() {
1384
    // Since 4 byte UTF-8 is not supported by default, there is nothing to
1385
    // activate.
1386
    return FALSE;
1387
  }
1388

    
1389
  /**
1390
   * Checks whether utf8mb4 support is available on the current database system.
1391
   *
1392
   * @return bool
1393
   */
1394
  public function utf8mb4IsSupported() {
1395
    // By default we assume that the database backend may not support 4 byte
1396
    // UTF-8.
1397
    return FALSE;
1398
  }
1399
}
1400

    
1401
/**
1402
 * Primary front-controller for the database system.
1403
 *
1404
 * This class is uninstantiatable and un-extendable. It acts to encapsulate
1405
 * all control and shepherding of database connections into a single location
1406
 * without the use of globals.
1407
 */
1408
abstract class Database {
1409

    
1410
  /**
1411
   * Flag to indicate a query call should simply return NULL.
1412
   *
1413
   * This is used for queries that have no reasonable return value anyway, such
1414
   * as INSERT statements to a table without a serial primary key.
1415
   */
1416
  const RETURN_NULL = 0;
1417

    
1418
  /**
1419
   * Flag to indicate a query call should return the prepared statement.
1420
   */
1421
  const RETURN_STATEMENT = 1;
1422

    
1423
  /**
1424
   * Flag to indicate a query call should return the number of affected rows.
1425
   */
1426
  const RETURN_AFFECTED = 2;
1427

    
1428
  /**
1429
   * Flag to indicate a query call should return the "last insert id".
1430
   */
1431
  const RETURN_INSERT_ID = 3;
1432

    
1433
  /**
1434
   * An nested array of all active connections. It is keyed by database name
1435
   * and target.
1436
   *
1437
   * @var array
1438
   */
1439
  static protected $connections = array();
1440

    
1441
  /**
1442
   * A processed copy of the database connection information from settings.php.
1443
   *
1444
   * @var array
1445
   */
1446
  static protected $databaseInfo = NULL;
1447

    
1448
  /**
1449
   * A list of key/target credentials to simply ignore.
1450
   *
1451
   * @var array
1452
   */
1453
  static protected $ignoreTargets = array();
1454

    
1455
  /**
1456
   * The key of the currently active database connection.
1457
   *
1458
   * @var string
1459
   */
1460
  static protected $activeKey = 'default';
1461

    
1462
  /**
1463
   * An array of active query log objects.
1464
   *
1465
   * Every connection has one and only one logger object for all targets and
1466
   * logging keys.
1467
   *
1468
   * array(
1469
   *   '$db_key' => DatabaseLog object.
1470
   * );
1471
   *
1472
   * @var array
1473
   */
1474
  static protected $logs = array();
1475

    
1476
  /**
1477
   * Starts logging a given logging key on the specified connection.
1478
   *
1479
   * @param $logging_key
1480
   *   The logging key to log.
1481
   * @param $key
1482
   *   The database connection key for which we want to log.
1483
   *
1484
   * @return DatabaseLog
1485
   *   The query log object. Note that the log object does support richer
1486
   *   methods than the few exposed through the Database class, so in some
1487
   *   cases it may be desirable to access it directly.
1488
   *
1489
   * @see DatabaseLog
1490
   */
1491
  final public static function startLog($logging_key, $key = 'default') {
1492
    if (empty(self::$logs[$key])) {
1493
      self::$logs[$key] = new DatabaseLog($key);
1494

    
1495
      // Every target already active for this connection key needs to have the
1496
      // logging object associated with it.
1497
      if (!empty(self::$connections[$key])) {
1498
        foreach (self::$connections[$key] as $connection) {
1499
          $connection->setLogger(self::$logs[$key]);
1500
        }
1501
      }
1502
    }
1503

    
1504
    self::$logs[$key]->start($logging_key);
1505
    return self::$logs[$key];
1506
  }
1507

    
1508
  /**
1509
   * Retrieves the queries logged on for given logging key.
1510
   *
1511
   * This method also ends logging for the specified key. To get the query log
1512
   * to date without ending the logger request the logging object by starting
1513
   * it again (which does nothing to an open log key) and call methods on it as
1514
   * desired.
1515
   *
1516
   * @param $logging_key
1517
   *   The logging key to log.
1518
   * @param $key
1519
   *   The database connection key for which we want to log.
1520
   *
1521
   * @return array
1522
   *   The query log for the specified logging key and connection.
1523
   *
1524
   * @see DatabaseLog
1525
   */
1526
  final public static function getLog($logging_key, $key = 'default') {
1527
    if (empty(self::$logs[$key])) {
1528
      return NULL;
1529
    }
1530
    $queries = self::$logs[$key]->get($logging_key);
1531
    self::$logs[$key]->end($logging_key);
1532
    return $queries;
1533
  }
1534

    
1535
  /**
1536
   * Gets the connection object for the specified database key and target.
1537
   *
1538
   * @param $target
1539
   *   The database target name.
1540
   * @param $key
1541
   *   The database connection key. Defaults to NULL which means the active key.
1542
   *
1543
   * @return DatabaseConnection
1544
   *   The corresponding connection object.
1545
   */
1546
  final public static function getConnection($target = 'default', $key = NULL) {
1547
    if (!isset($key)) {
1548
      // By default, we want the active connection, set in setActiveConnection.
1549
      $key = self::$activeKey;
1550
    }
1551
    // If the requested target does not exist, or if it is ignored, we fall back
1552
    // to the default target. The target is typically either "default" or
1553
    // "slave", indicating to use a slave SQL server if one is available. If
1554
    // it's not available, then the default/master server is the correct server
1555
    // to use.
1556
    if (!empty(self::$ignoreTargets[$key][$target]) || !isset(self::$databaseInfo[$key][$target])) {
1557
      $target = 'default';
1558
    }
1559

    
1560
    if (!isset(self::$connections[$key][$target])) {
1561
      // If necessary, a new connection is opened.
1562
      self::$connections[$key][$target] = self::openConnection($key, $target);
1563
    }
1564
    return self::$connections[$key][$target];
1565
  }
1566

    
1567
  /**
1568
   * Determines if there is an active connection.
1569
   *
1570
   * Note that this method will return FALSE if no connection has been
1571
   * established yet, even if one could be.
1572
   *
1573
   * @return
1574
   *   TRUE if there is at least one database connection established, FALSE
1575
   *   otherwise.
1576
   */
1577
  final public static function isActiveConnection() {
1578
    return !empty(self::$activeKey) && !empty(self::$connections) && !empty(self::$connections[self::$activeKey]);
1579
  }
1580

    
1581
  /**
1582
   * Sets the active connection to the specified key.
1583
   *
1584
   * @return
1585
   *   The previous database connection key.
1586
   */
1587
  final public static function setActiveConnection($key = 'default') {
1588
    if (empty(self::$databaseInfo)) {
1589
      self::parseConnectionInfo();
1590
    }
1591

    
1592
    if (!empty(self::$databaseInfo[$key])) {
1593
      $old_key = self::$activeKey;
1594
      self::$activeKey = $key;
1595
      return $old_key;
1596
    }
1597
  }
1598

    
1599
  /**
1600
   * Process the configuration file for database information.
1601
   */
1602
  final public static function parseConnectionInfo() {
1603
    global $databases;
1604

    
1605
    $database_info = is_array($databases) ? $databases : array();
1606
    foreach ($database_info as $index => $info) {
1607
      foreach ($database_info[$index] as $target => $value) {
1608
        // If there is no "driver" property, then we assume it's an array of
1609
        // possible connections for this target. Pick one at random. That allows
1610
        //  us to have, for example, multiple slave servers.
1611
        if (empty($value['driver'])) {
1612
          $database_info[$index][$target] = $database_info[$index][$target][mt_rand(0, count($database_info[$index][$target]) - 1)];
1613
        }
1614

    
1615
        // Parse the prefix information.
1616
        if (!isset($database_info[$index][$target]['prefix'])) {
1617
          // Default to an empty prefix.
1618
          $database_info[$index][$target]['prefix'] = array(
1619
            'default' => '',
1620
          );
1621
        }
1622
        elseif (!is_array($database_info[$index][$target]['prefix'])) {
1623
          // Transform the flat form into an array form.
1624
          $database_info[$index][$target]['prefix'] = array(
1625
            'default' => $database_info[$index][$target]['prefix'],
1626
          );
1627
        }
1628
      }
1629
    }
1630

    
1631
    if (!is_array(self::$databaseInfo)) {
1632
      self::$databaseInfo = $database_info;
1633
    }
1634

    
1635
    // Merge the new $database_info into the existing.
1636
    // array_merge_recursive() cannot be used, as it would make multiple
1637
    // database, user, and password keys in the same database array.
1638
    else {
1639
      foreach ($database_info as $database_key => $database_values) {
1640
        foreach ($database_values as $target => $target_values) {
1641
          self::$databaseInfo[$database_key][$target] = $target_values;
1642
        }
1643
      }
1644
    }
1645
  }
1646

    
1647
  /**
1648
   * Adds database connection information for a given key/target.
1649
   *
1650
   * This method allows the addition of new connection credentials at runtime.
1651
   * Under normal circumstances the preferred way to specify database
1652
   * credentials is via settings.php. However, this method allows them to be
1653
   * added at arbitrary times, such as during unit tests, when connecting to
1654
   * admin-defined third party databases, etc.
1655
   *
1656
   * If the given key/target pair already exists, this method will be ignored.
1657
   *
1658
   * @param $key
1659
   *   The database key.
1660
   * @param $target
1661
   *   The database target name.
1662
   * @param $info
1663
   *   The database connection information, as it would be defined in
1664
   *   settings.php. Note that the structure of this array will depend on the
1665
   *   database driver it is connecting to.
1666
   */
1667
  public static function addConnectionInfo($key, $target, $info) {
1668
    if (empty(self::$databaseInfo[$key][$target])) {
1669
      self::$databaseInfo[$key][$target] = $info;
1670
    }
1671
  }
1672

    
1673
  /**
1674
   * Gets information on the specified database connection.
1675
   *
1676
   * @param $connection
1677
   *   The connection key for which we want information.
1678
   */
1679
  final public static function getConnectionInfo($key = 'default') {
1680
    if (empty(self::$databaseInfo)) {
1681
      self::parseConnectionInfo();
1682
    }
1683

    
1684
    if (!empty(self::$databaseInfo[$key])) {
1685
      return self::$databaseInfo[$key];
1686
    }
1687
  }
1688

    
1689
  /**
1690
   * Rename a connection and its corresponding connection information.
1691
   *
1692
   * @param $old_key
1693
   *   The old connection key.
1694
   * @param $new_key
1695
   *   The new connection key.
1696
   * @return
1697
   *   TRUE in case of success, FALSE otherwise.
1698
   */
1699
  final public static function renameConnection($old_key, $new_key) {
1700
    if (empty(self::$databaseInfo)) {
1701
      self::parseConnectionInfo();
1702
    }
1703

    
1704
    if (!empty(self::$databaseInfo[$old_key]) && empty(self::$databaseInfo[$new_key])) {
1705
      // Migrate the database connection information.
1706
      self::$databaseInfo[$new_key] = self::$databaseInfo[$old_key];
1707
      unset(self::$databaseInfo[$old_key]);
1708

    
1709
      // Migrate over the DatabaseConnection object if it exists.
1710
      if (isset(self::$connections[$old_key])) {
1711
        self::$connections[$new_key] = self::$connections[$old_key];
1712
        unset(self::$connections[$old_key]);
1713
      }
1714

    
1715
      return TRUE;
1716
    }
1717
    else {
1718
      return FALSE;
1719
    }
1720
  }
1721

    
1722
  /**
1723
   * Remove a connection and its corresponding connection information.
1724
   *
1725
   * @param $key
1726
   *   The connection key.
1727
   * @return
1728
   *   TRUE in case of success, FALSE otherwise.
1729
   */
1730
  final public static function removeConnection($key) {
1731
    if (isset(self::$databaseInfo[$key])) {
1732
      self::closeConnection(NULL, $key);
1733
      unset(self::$databaseInfo[$key]);
1734
      return TRUE;
1735
    }
1736
    else {
1737
      return FALSE;
1738
    }
1739
  }
1740

    
1741
  /**
1742
   * Opens a connection to the server specified by the given key and target.
1743
   *
1744
   * @param $key
1745
   *   The database connection key, as specified in settings.php. The default is
1746
   *   "default".
1747
   * @param $target
1748
   *   The database target to open.
1749
   *
1750
   * @throws DatabaseConnectionNotDefinedException
1751
   * @throws DatabaseDriverNotSpecifiedException
1752
   */
1753
  final protected static function openConnection($key, $target) {
1754
    if (empty(self::$databaseInfo)) {
1755
      self::parseConnectionInfo();
1756
    }
1757

    
1758
    // If the requested database does not exist then it is an unrecoverable
1759
    // error.
1760
    if (!isset(self::$databaseInfo[$key])) {
1761
      throw new DatabaseConnectionNotDefinedException('The specified database connection is not defined: ' . $key);
1762
    }
1763

    
1764
    if (!$driver = self::$databaseInfo[$key][$target]['driver']) {
1765
      throw new DatabaseDriverNotSpecifiedException('Driver not specified for this database connection: ' . $key);
1766
    }
1767

    
1768
    // We cannot rely on the registry yet, because the registry requires an
1769
    // open database connection.
1770
    $driver_class = 'DatabaseConnection_' . $driver;
1771
    require_once DRUPAL_ROOT . '/includes/database/' . $driver . '/database.inc';
1772
    $new_connection = new $driver_class(self::$databaseInfo[$key][$target]);
1773
    $new_connection->setTarget($target);
1774
    $new_connection->setKey($key);
1775

    
1776
    // If we have any active logging objects for this connection key, we need
1777
    // to associate them with the connection we just opened.
1778
    if (!empty(self::$logs[$key])) {
1779
      $new_connection->setLogger(self::$logs[$key]);
1780
    }
1781

    
1782
    return $new_connection;
1783
  }
1784

    
1785
  /**
1786
   * Closes a connection to the server specified by the given key and target.
1787
   *
1788
   * @param $target
1789
   *   The database target name.  Defaults to NULL meaning that all target
1790
   *   connections will be closed.
1791
   * @param $key
1792
   *   The database connection key. Defaults to NULL which means the active key.
1793
   */
1794
  public static function closeConnection($target = NULL, $key = NULL) {
1795
    // Gets the active connection by default.
1796
    if (!isset($key)) {
1797
      $key = self::$activeKey;
1798
    }
1799
    // To close a connection, it needs to be set to NULL and removed from the
1800
    // static variable. In all cases, closeConnection() might be called for a
1801
    // connection that was not opened yet, in which case the key is not defined
1802
    // yet and we just ensure that the connection key is undefined.
1803
    if (isset($target)) {
1804
      if (isset(self::$connections[$key][$target])) {
1805
        self::$connections[$key][$target]->destroy();
1806
        self::$connections[$key][$target] = NULL;
1807
      }
1808
      unset(self::$connections[$key][$target]);
1809
    }
1810
    else {
1811
      if (isset(self::$connections[$key])) {
1812
        foreach (self::$connections[$key] as $target => $connection) {
1813
          self::$connections[$key][$target]->destroy();
1814
          self::$connections[$key][$target] = NULL;
1815
        }
1816
      }
1817
      unset(self::$connections[$key]);
1818
    }
1819
  }
1820

    
1821
  /**
1822
   * Instructs the system to temporarily ignore a given key/target.
1823
   *
1824
   * At times we need to temporarily disable slave queries. To do so, call this
1825
   * method with the database key and the target to disable. That database key
1826
   * will then always fall back to 'default' for that key, even if it's defined.
1827
   *
1828
   * @param $key
1829
   *   The database connection key.
1830
   * @param $target
1831
   *   The target of the specified key to ignore.
1832
   */
1833
  public static function ignoreTarget($key, $target) {
1834
    self::$ignoreTargets[$key][$target] = TRUE;
1835
  }
1836

    
1837
  /**
1838
   * Load a file for the database that might hold a class.
1839
   *
1840
   * @param $driver
1841
   *   The name of the driver.
1842
   * @param array $files
1843
   *   The name of the files the driver specific class can be.
1844
   */
1845
  public static function loadDriverFile($driver, array $files = array()) {
1846
    static $base_path;
1847

    
1848
    if (empty($base_path)) {
1849
      $base_path = dirname(realpath(__FILE__));
1850
    }
1851

    
1852
    $driver_base_path = "$base_path/$driver";
1853
    foreach ($files as $file) {
1854
      // Load the base file first so that classes extending base classes will
1855
      // have the base class loaded.
1856
      foreach (array("$base_path/$file", "$driver_base_path/$file") as $filename) {
1857
        // The OS caches file_exists() and PHP caches require_once(), so
1858
        // we'll let both of those take care of performance here.
1859
        if (file_exists($filename)) {
1860
          require_once $filename;
1861
        }
1862
      }
1863
    }
1864
  }
1865
}
1866

    
1867
/**
1868
 * Exception for when popTransaction() is called with no active transaction.
1869
 */
1870
class DatabaseTransactionNoActiveException extends Exception { }
1871

    
1872
/**
1873
 * Exception thrown when a savepoint or transaction name occurs twice.
1874
 */
1875
class DatabaseTransactionNameNonUniqueException extends Exception { }
1876

    
1877
/**
1878
 * Exception thrown when a commit() function fails.
1879
 */
1880
class DatabaseTransactionCommitFailedException extends Exception { }
1881

    
1882
/**
1883
 * Exception to deny attempts to explicitly manage transactions.
1884
 *
1885
 * This exception will be thrown when the PDO connection commit() is called.
1886
 * Code should never call this method directly.
1887
 */
1888
class DatabaseTransactionExplicitCommitNotAllowedException extends Exception { }
1889

    
1890
/**
1891
 * Exception thrown when a rollback() resulted in other active transactions being rolled-back.
1892
 */
1893
class DatabaseTransactionOutOfOrderException extends Exception { }
1894

    
1895
/**
1896
 * Exception thrown for merge queries that do not make semantic sense.
1897
 *
1898
 * There are many ways that a merge query could be malformed.  They should all
1899
 * throw this exception and set an appropriately descriptive message.
1900
 */
1901
class InvalidMergeQueryException extends Exception {}
1902

    
1903
/**
1904
 * Exception thrown if an insert query specifies a field twice.
1905
 *
1906
 * It is not allowed to specify a field as default and insert field, this
1907
 * exception is thrown if that is the case.
1908
 */
1909
class FieldsOverlapException extends Exception {}
1910

    
1911
/**
1912
 * Exception thrown if an insert query doesn't specify insert or default fields.
1913
 */
1914
class NoFieldsException extends Exception {}
1915

    
1916
/**
1917
 * Exception thrown if an undefined database connection is requested.
1918
 */
1919
class DatabaseConnectionNotDefinedException extends Exception {}
1920

    
1921
/**
1922
 * Exception thrown if no driver is specified for a database connection.
1923
 */
1924
class DatabaseDriverNotSpecifiedException extends Exception {}
1925

    
1926

    
1927
/**
1928
 * A wrapper class for creating and managing database transactions.
1929
 *
1930
 * Not all databases or database configurations support transactions. For
1931
 * example, MySQL MyISAM tables do not. It is also easy to begin a transaction
1932
 * and then forget to commit it, which can lead to connection errors when
1933
 * another transaction is started.
1934
 *
1935
 * This class acts as a wrapper for transactions. To begin a transaction,
1936
 * simply instantiate it. When the object goes out of scope and is destroyed
1937
 * it will automatically commit. It also will check to see if the specified
1938
 * connection supports transactions. If not, it will simply skip any transaction
1939
 * commands, allowing user-space code to proceed normally. The only difference
1940
 * is that rollbacks won't actually do anything.
1941
 *
1942
 * In the vast majority of cases, you should not instantiate this class
1943
 * directly. Instead, call ->startTransaction(), from the appropriate connection
1944
 * object.
1945
 */
1946
class DatabaseTransaction {
1947

    
1948
  /**
1949
   * The connection object for this transaction.
1950
   *
1951
   * @var DatabaseConnection
1952
   */
1953
  protected $connection;
1954

    
1955
  /**
1956
   * A boolean value to indicate whether this transaction has been rolled back.
1957
   *
1958
   * @var Boolean
1959
   */
1960
  protected $rolledBack = FALSE;
1961

    
1962
  /**
1963
   * The name of the transaction.
1964
   *
1965
   * This is used to label the transaction savepoint. It will be overridden to
1966
   * 'drupal_transaction' if there is no transaction depth.
1967
   */
1968
  protected $name;
1969

    
1970
  public function __construct(DatabaseConnection $connection, $name = NULL) {
1971
    $this->connection = $connection;
1972
    // If there is no transaction depth, then no transaction has started. Name
1973
    // the transaction 'drupal_transaction'.
1974
    if (!$depth = $connection->transactionDepth()) {
1975
      $this->name = 'drupal_transaction';
1976
    }
1977
    // Within transactions, savepoints are used. Each savepoint requires a
1978
    // name. So if no name is present we need to create one.
1979
    elseif (!$name) {
1980
      $this->name = 'savepoint_' . $depth;
1981
    }
1982
    else {
1983
      $this->name = $name;
1984
    }
1985
    $this->connection->pushTransaction($this->name);
1986
  }
1987

    
1988
  public function __destruct() {
1989
    // If we rolled back then the transaction would have already been popped.
1990
    if (!$this->rolledBack) {
1991
      $this->connection->popTransaction($this->name);
1992
    }
1993
  }
1994

    
1995
  /**
1996
   * Retrieves the name of the transaction or savepoint.
1997
   */
1998
  public function name() {
1999
    return $this->name;
2000
  }
2001

    
2002
  /**
2003
   * Rolls back the current transaction.
2004
   *
2005
   * This is just a wrapper method to rollback whatever transaction stack we are
2006
   * currently in, which is managed by the connection object itself. Note that
2007
   * logging (preferable with watchdog_exception()) needs to happen after a
2008
   * transaction has been rolled back or the log messages will be rolled back
2009
   * too.
2010
   *
2011
   * @see DatabaseConnection::rollback()
2012
   * @see watchdog_exception()
2013
   */
2014
  public function rollback() {
2015
    $this->rolledBack = TRUE;
2016
    $this->connection->rollback($this->name);
2017
  }
2018
}
2019

    
2020
/**
2021
 * Represents a prepared statement.
2022
 *
2023
 * Some methods in that class are purposefully commented out. Due to a change in
2024
 * how PHP defines PDOStatement, we can't define a signature for those methods
2025
 * that will work the same way between versions older than 5.2.6 and later
2026
 * versions.  See http://bugs.php.net/bug.php?id=42452 for more details.
2027
 *
2028
 * Child implementations should either extend PDOStatement:
2029
 * @code
2030
 * class DatabaseStatement_oracle extends PDOStatement implements DatabaseStatementInterface {}
2031
 * @endcode
2032
 * or define their own class. If defining their own class, they will also have
2033
 * to implement either the Iterator or IteratorAggregate interface before
2034
 * DatabaseStatementInterface:
2035
 * @code
2036
 * class DatabaseStatement_oracle implements Iterator, DatabaseStatementInterface {}
2037
 * @endcode
2038
 */
2039
interface DatabaseStatementInterface extends Traversable {
2040

    
2041
  /**
2042
   * Executes a prepared statement
2043
   *
2044
   * @param $args
2045
   *   An array of values with as many elements as there are bound parameters in
2046
   *   the SQL statement being executed.
2047
   * @param $options
2048
   *   An array of options for this query.
2049
   *
2050
   * @return
2051
   *   TRUE on success, or FALSE on failure.
2052
   */
2053
  public function execute($args = array(), $options = array());
2054

    
2055
  /**
2056
   * Gets the query string of this statement.
2057
   *
2058
   * @return
2059
   *   The query string, in its form with placeholders.
2060
   */
2061
  public function getQueryString();
2062

    
2063
  /**
2064
   * Returns the number of rows affected by the last SQL statement.
2065
   *
2066
   * @return
2067
   *   The number of rows affected by the last DELETE, INSERT, or UPDATE
2068
   *   statement executed.
2069
   */
2070
  public function rowCount();
2071

    
2072
  /**
2073
   * Sets the default fetch mode for this statement.
2074
   *
2075
   * See http://php.net/manual/pdo.constants.php for the definition of the
2076
   * constants used.
2077
   *
2078
   * @param $mode
2079
   *   One of the PDO::FETCH_* constants.
2080
   * @param $a1
2081
   *   An option depending of the fetch mode specified by $mode:
2082
   *   - for PDO::FETCH_COLUMN, the index of the column to fetch
2083
   *   - for PDO::FETCH_CLASS, the name of the class to create
2084
   *   - for PDO::FETCH_INTO, the object to add the data to
2085
   * @param $a2
2086
   *   If $mode is PDO::FETCH_CLASS, the optional arguments to pass to the
2087
   *   constructor.
2088
   */
2089
  // public function setFetchMode($mode, $a1 = NULL, $a2 = array());
2090

    
2091
  /**
2092
   * Fetches the next row from a result set.
2093
   *
2094
   * See http://php.net/manual/pdo.constants.php for the definition of the
2095
   * constants used.
2096
   *
2097
   * @param $mode
2098
   *   One of the PDO::FETCH_* constants.
2099
   *   Default to what was specified by setFetchMode().
2100
   * @param $cursor_orientation
2101
   *   Not implemented in all database drivers, don't use.
2102
   * @param $cursor_offset
2103
   *   Not implemented in all database drivers, don't use.
2104
   *
2105
   * @return
2106
   *   A result, formatted according to $mode.
2107
   */
2108
  // public function fetch($mode = NULL, $cursor_orientation = NULL, $cursor_offset = NULL);
2109

    
2110
  /**
2111
   * Returns a single field from the next record of a result set.
2112
   *
2113
   * @param $index
2114
   *   The numeric index of the field to return. Defaults to the first field.
2115
   *
2116
   * @return
2117
   *   A single field from the next record, or FALSE if there is no next record.
2118
   */
2119
  public function fetchField($index = 0);
2120

    
2121
  /**
2122
   * Fetches the next row and returns it as an object.
2123
   *
2124
   * The object will be of the class specified by DatabaseStatementInterface::setFetchMode()
2125
   * or stdClass if not specified.
2126
   */
2127
  // public function fetchObject();
2128

    
2129
  /**
2130
   * Fetches the next row and returns it as an associative array.
2131
   *
2132
   * This method corresponds to PDOStatement::fetchObject(), but for associative
2133
   * arrays. For some reason PDOStatement does not have a corresponding array
2134
   * helper method, so one is added.
2135
   *
2136
   * @return
2137
   *   An associative array, or FALSE if there is no next row.
2138
   */
2139
  public function fetchAssoc();
2140

    
2141
  /**
2142
   * Returns an array containing all of the result set rows.
2143
   *
2144
   * @param $mode
2145
   *   One of the PDO::FETCH_* constants.
2146
   * @param $column_index
2147
   *   If $mode is PDO::FETCH_COLUMN, the index of the column to fetch.
2148
   * @param $constructor_arguments
2149
   *   If $mode is PDO::FETCH_CLASS, the arguments to pass to the constructor.
2150
   *
2151
   * @return
2152
   *   An array of results.
2153
   */
2154
  // function fetchAll($mode = NULL, $column_index = NULL, array $constructor_arguments);
2155

    
2156
  /**
2157
   * Returns an entire single column of a result set as an indexed array.
2158
   *
2159
   * Note that this method will run the result set to the end.
2160
   *
2161
   * @param $index
2162
   *   The index of the column number to fetch.
2163
   *
2164
   * @return
2165
   *   An indexed array, or an empty array if there is no result set.
2166
   */
2167
  public function fetchCol($index = 0);
2168

    
2169
  /**
2170
   * Returns the entire result set as a single associative array.
2171
   *
2172
   * This method is only useful for two-column result sets. It will return an
2173
   * associative array where the key is one column from the result set and the
2174
   * value is another field. In most cases, the default of the first two columns
2175
   * is appropriate.
2176
   *
2177
   * Note that this method will run the result set to the end.
2178
   *
2179
   * @param $key_index
2180
   *   The numeric index of the field to use as the array key.
2181
   * @param $value_index
2182
   *   The numeric index of the field to use as the array value.
2183
   *
2184
   * @return
2185
   *   An associative array, or an empty array if there is no result set.
2186
   */
2187
  public function fetchAllKeyed($key_index = 0, $value_index = 1);
2188

    
2189
  /**
2190
   * Returns the result set as an associative array keyed by the given field.
2191
   *
2192
   * If the given key appears multiple times, later records will overwrite
2193
   * earlier ones.
2194
   *
2195
   * @param $key
2196
   *   The name of the field on which to index the array.
2197
   * @param $fetch
2198
   *   The fetchmode to use. If set to PDO::FETCH_ASSOC, PDO::FETCH_NUM, or
2199
   *   PDO::FETCH_BOTH the returned value with be an array of arrays. For any
2200
   *   other value it will be an array of objects. By default, the fetch mode
2201
   *   set for the query will be used.
2202
   *
2203
   * @return
2204
   *   An associative array, or an empty array if there is no result set.
2205
   */
2206
  public function fetchAllAssoc($key, $fetch = NULL);
2207
}
2208

    
2209
/**
2210
 * Default implementation of DatabaseStatementInterface.
2211
 *
2212
 * PDO allows us to extend the PDOStatement class to provide additional
2213
 * functionality beyond that offered by default. We do need extra
2214
 * functionality. By default, this class is not driver-specific. If a given
2215
 * driver needs to set a custom statement class, it may do so in its
2216
 * constructor.
2217
 *
2218
 * @see http://us.php.net/pdostatement
2219
 */
2220
class DatabaseStatementBase extends PDOStatement implements DatabaseStatementInterface {
2221

    
2222
  /**
2223
   * Reference to the database connection object for this statement.
2224
   *
2225
   * The name $dbh is inherited from PDOStatement.
2226
   *
2227
   * @var DatabaseConnection
2228
   */
2229
  public $dbh;
2230

    
2231
  protected function __construct($dbh) {
2232
    $this->dbh = $dbh;
2233
    $this->setFetchMode(PDO::FETCH_OBJ);
2234
  }
2235

    
2236
  public function execute($args = array(), $options = array()) {
2237
    if (isset($options['fetch'])) {
2238
      if (is_string($options['fetch'])) {
2239
        // Default to an object. Note: db fields will be added to the object
2240
        // before the constructor is run. If you need to assign fields after
2241
        // the constructor is run, see http://drupal.org/node/315092.
2242
        $this->setFetchMode(PDO::FETCH_CLASS, $options['fetch']);
2243
      }
2244
      else {
2245
        $this->setFetchMode($options['fetch']);
2246
      }
2247
    }
2248

    
2249
    $logger = $this->dbh->getLogger();
2250
    if (!empty($logger)) {
2251
      $query_start = microtime(TRUE);
2252
    }
2253

    
2254
    $return = parent::execute($args);
2255

    
2256
    if (!empty($logger)) {
2257
      $query_end = microtime(TRUE);
2258
      $logger->log($this, $args, $query_end - $query_start);
2259
    }
2260

    
2261
    return $return;
2262
  }
2263

    
2264
  public function getQueryString() {
2265
    return $this->queryString;
2266
  }
2267

    
2268
  public function fetchCol($index = 0) {
2269
    return $this->fetchAll(PDO::FETCH_COLUMN, $index);
2270
  }
2271

    
2272
  public function fetchAllAssoc($key, $fetch = NULL) {
2273
    $return = array();
2274
    if (isset($fetch)) {
2275
      if (is_string($fetch)) {
2276
        $this->setFetchMode(PDO::FETCH_CLASS, $fetch);
2277
      }
2278
      else {
2279
        $this->setFetchMode($fetch);
2280
      }
2281
    }
2282

    
2283
    foreach ($this as $record) {
2284
      $record_key = is_object($record) ? $record->$key : $record[$key];
2285
      $return[$record_key] = $record;
2286
    }
2287

    
2288
    return $return;
2289
  }
2290

    
2291
  public function fetchAllKeyed($key_index = 0, $value_index = 1) {
2292
    $return = array();
2293
    $this->setFetchMode(PDO::FETCH_NUM);
2294
    foreach ($this as $record) {
2295
      $return[$record[$key_index]] = $record[$value_index];
2296
    }
2297
    return $return;
2298
  }
2299

    
2300
  public function fetchField($index = 0) {
2301
    // Call PDOStatement::fetchColumn to fetch the field.
2302
    return $this->fetchColumn($index);
2303
  }
2304

    
2305
  public function fetchAssoc() {
2306
    // Call PDOStatement::fetch to fetch the row.
2307
    return $this->fetch(PDO::FETCH_ASSOC);
2308
  }
2309
}
2310

    
2311
/**
2312
 * Empty implementation of a database statement.
2313
 *
2314
 * This class satisfies the requirements of being a database statement/result
2315
 * object, but does not actually contain data.  It is useful when developers
2316
 * need to safely return an "empty" result set without connecting to an actual
2317
 * database.  Calling code can then treat it the same as if it were an actual
2318
 * result set that happens to contain no records.
2319
 *
2320
 * @see SearchQuery
2321
 */
2322
class DatabaseStatementEmpty implements Iterator, DatabaseStatementInterface {
2323

    
2324
  public function execute($args = array(), $options = array()) {
2325
    return FALSE;
2326
  }
2327

    
2328
  public function getQueryString() {
2329
    return '';
2330
  }
2331

    
2332
  public function rowCount() {
2333
    return 0;
2334
  }
2335

    
2336
  public function setFetchMode($mode, $a1 = NULL, $a2 = array()) {
2337
    return;
2338
  }
2339

    
2340
  public function fetch($mode = NULL, $cursor_orientation = NULL, $cursor_offset = NULL) {
2341
    return NULL;
2342
  }
2343

    
2344
  public function fetchField($index = 0) {
2345
    return NULL;
2346
  }
2347

    
2348
  public function fetchObject() {
2349
    return NULL;
2350
  }
2351

    
2352
  public function fetchAssoc() {
2353
    return NULL;
2354
  }
2355

    
2356
  function fetchAll($mode = NULL, $column_index = NULL, array $constructor_arguments = array()) {
2357
    return array();
2358
  }
2359

    
2360
  public function fetchCol($index = 0) {
2361
    return array();
2362
  }
2363

    
2364
  public function fetchAllKeyed($key_index = 0, $value_index = 1) {
2365
    return array();
2366
  }
2367

    
2368
  public function fetchAllAssoc($key, $fetch = NULL) {
2369
    return array();
2370
  }
2371

    
2372
  /* Implementations of Iterator. */
2373

    
2374
  public function current() {
2375
    return NULL;
2376
  }
2377

    
2378
  public function key() {
2379
    return NULL;
2380
  }
2381

    
2382
  public function rewind() {
2383
    // Nothing to do: our DatabaseStatement can't be rewound.
2384
  }
2385

    
2386
  public function next() {
2387
    // Do nothing, since this is an always-empty implementation.
2388
  }
2389

    
2390
  public function valid() {
2391
    return FALSE;
2392
  }
2393
}
2394

    
2395
/**
2396
 * The following utility functions are simply convenience wrappers.
2397
 *
2398
 * They should never, ever have any database-specific code in them.
2399
 */
2400

    
2401
/**
2402
 * Executes an arbitrary query string against the active database.
2403
 *
2404
 * Use this function for SELECT queries if it is just a simple query string.
2405
 * If the caller or other modules need to change the query, use db_select()
2406
 * instead.
2407
 *
2408
 * Do not use this function for INSERT, UPDATE, or DELETE queries. Those should
2409
 * be handled via db_insert(), db_update() and db_delete() respectively.
2410
 *
2411
 * @param $query
2412
 *   The prepared statement query to run. Although it will accept both named and
2413
 *   unnamed placeholders, named placeholders are strongly preferred as they are
2414
 *   more self-documenting.
2415
 * @param $args
2416
 *   An array of values to substitute into the query. If the query uses named
2417
 *   placeholders, this is an associative array in any order. If the query uses
2418
 *   unnamed placeholders (?), this is an indexed array and the order must match
2419
 *   the order of placeholders in the query string.
2420
 * @param $options
2421
 *   An array of options to control how the query operates.
2422
 *
2423
 * @return DatabaseStatementInterface
2424
 *   A prepared statement object, already executed.
2425
 *
2426
 * @see DatabaseConnection::defaultOptions()
2427
 */
2428
function db_query($query, array $args = array(), array $options = array()) {
2429
  if (empty($options['target'])) {
2430
    $options['target'] = 'default';
2431
  }
2432

    
2433
  return Database::getConnection($options['target'])->query($query, $args, $options);
2434
}
2435

    
2436
/**
2437
 * Executes a query against the active database, restricted to a range.
2438
 *
2439
 * @param $query
2440
 *   The prepared statement query to run. Although it will accept both named and
2441
 *   unnamed placeholders, named placeholders are strongly preferred as they are
2442
 *   more self-documenting.
2443
 * @param $from
2444
 *   The first record from the result set to return.
2445
 * @param $count
2446
 *   The number of records to return from the result set.
2447
 * @param $args
2448
 *   An array of values to substitute into the query. If the query uses named
2449
 *   placeholders, this is an associative array in any order. If the query uses
2450
 *   unnamed placeholders (?), this is an indexed array and the order must match
2451
 *   the order of placeholders in the query string.
2452
 * @param $options
2453
 *   An array of options to control how the query operates.
2454
 *
2455
 * @return DatabaseStatementInterface
2456
 *   A prepared statement object, already executed.
2457
 *
2458
 * @see DatabaseConnection::defaultOptions()
2459
 */
2460
function db_query_range($query, $from, $count, array $args = array(), array $options = array()) {
2461
  if (empty($options['target'])) {
2462
    $options['target'] = 'default';
2463
  }
2464

    
2465
  return Database::getConnection($options['target'])->queryRange($query, $from, $count, $args, $options);
2466
}
2467

    
2468
/**
2469
 * Executes a SELECT query string and saves the result set to a temporary table.
2470
 *
2471
 * The execution of the query string happens against the active database.
2472
 *
2473
 * @param $query
2474
 *   The prepared SELECT statement query to run. Although it will accept both
2475
 *   named and unnamed placeholders, named placeholders are strongly preferred
2476
 *   as they are more self-documenting.
2477
 * @param $args
2478
 *   An array of values to substitute into the query. If the query uses named
2479
 *   placeholders, this is an associative array in any order. If the query uses
2480
 *   unnamed placeholders (?), this is an indexed array and the order must match
2481
 *   the order of placeholders in the query string.
2482
 * @param $options
2483
 *   An array of options to control how the query operates.
2484
 *
2485
 * @return
2486
 *   The name of the temporary table.
2487
 *
2488
 * @see DatabaseConnection::defaultOptions()
2489
 */
2490
function db_query_temporary($query, array $args = array(), array $options = array()) {
2491
  if (empty($options['target'])) {
2492
    $options['target'] = 'default';
2493
  }
2494

    
2495
  return Database::getConnection($options['target'])->queryTemporary($query, $args, $options);
2496
}
2497

    
2498
/**
2499
 * Returns a new InsertQuery object for the active database.
2500
 *
2501
 * @param $table
2502
 *   The table into which to insert.
2503
 * @param $options
2504
 *   An array of options to control how the query operates.
2505
 *
2506
 * @return InsertQuery
2507
 *   A new InsertQuery object for this connection.
2508
 */
2509
function db_insert($table, array $options = array()) {
2510
  if (empty($options['target']) || $options['target'] == 'slave') {
2511
    $options['target'] = 'default';
2512
  }
2513
  return Database::getConnection($options['target'])->insert($table, $options);
2514
}
2515

    
2516
/**
2517
 * Returns a new MergeQuery object for the active database.
2518
 *
2519
 * @param $table
2520
 *   The table into which to merge.
2521
 * @param $options
2522
 *   An array of options to control how the query operates.
2523
 *
2524
 * @return MergeQuery
2525
 *   A new MergeQuery object for this connection.
2526
 */
2527
function db_merge($table, array $options = array()) {
2528
  if (empty($options['target']) || $options['target'] == 'slave') {
2529
    $options['target'] = 'default';
2530
  }
2531
  return Database::getConnection($options['target'])->merge($table, $options);
2532
}
2533

    
2534
/**
2535
 * Returns a new UpdateQuery object for the active database.
2536
 *
2537
 * @param $table
2538
 *   The table to update.
2539
 * @param $options
2540
 *   An array of options to control how the query operates.
2541
 *
2542
 * @return UpdateQuery
2543
 *   A new UpdateQuery object for this connection.
2544
 */
2545
function db_update($table, array $options = array()) {
2546
  if (empty($options['target']) || $options['target'] == 'slave') {
2547
    $options['target'] = 'default';
2548
  }
2549
  return Database::getConnection($options['target'])->update($table, $options);
2550
}
2551

    
2552
/**
2553
 * Returns a new DeleteQuery object for the active database.
2554
 *
2555
 * @param $table
2556
 *   The table from which to delete.
2557
 * @param $options
2558
 *   An array of options to control how the query operates.
2559
 *
2560
 * @return DeleteQuery
2561
 *   A new DeleteQuery object for this connection.
2562
 */
2563
function db_delete($table, array $options = array()) {
2564
  if (empty($options['target']) || $options['target'] == 'slave') {
2565
    $options['target'] = 'default';
2566
  }
2567
  return Database::getConnection($options['target'])->delete($table, $options);
2568
}
2569

    
2570
/**
2571
 * Returns a new TruncateQuery object for the active database.
2572
 *
2573
 * @param $table
2574
 *   The table from which to delete.
2575
 * @param $options
2576
 *   An array of options to control how the query operates.
2577
 *
2578
 * @return TruncateQuery
2579
 *   A new TruncateQuery object for this connection.
2580
 */
2581
function db_truncate($table, array $options = array()) {
2582
  if (empty($options['target']) || $options['target'] == 'slave') {
2583
    $options['target'] = 'default';
2584
  }
2585
  return Database::getConnection($options['target'])->truncate($table, $options);
2586
}
2587

    
2588
/**
2589
 * Returns a new SelectQuery object for the active database.
2590
 *
2591
 * @param $table
2592
 *   The base table for this query. May be a string or another SelectQuery
2593
 *   object. If a query object is passed, it will be used as a subselect.
2594
 * @param $alias
2595
 *   The alias for the base table of this query.
2596
 * @param $options
2597
 *   An array of options to control how the query operates.
2598
 *
2599
 * @return SelectQuery
2600
 *   A new SelectQuery object for this connection.
2601
 */
2602
function db_select($table, $alias = NULL, array $options = array()) {
2603
  if (empty($options['target'])) {
2604
    $options['target'] = 'default';
2605
  }
2606
  return Database::getConnection($options['target'])->select($table, $alias, $options);
2607
}
2608

    
2609
/**
2610
 * Returns a new transaction object for the active database.
2611
 *
2612
 * @param string $name
2613
 *   Optional name of the transaction.
2614
 * @param array $options
2615
 *   An array of options to control how the transaction operates:
2616
 *   - target: The database target name.
2617
 *
2618
 * @return DatabaseTransaction
2619
 *   A new DatabaseTransaction object for this connection.
2620
 */
2621
function db_transaction($name = NULL, array $options = array()) {
2622
  if (empty($options['target'])) {
2623
    $options['target'] = 'default';
2624
  }
2625
  return Database::getConnection($options['target'])->startTransaction($name);
2626
}
2627

    
2628
/**
2629
 * Sets a new active database.
2630
 *
2631
 * @param $key
2632
 *   The key in the $databases array to set as the default database.
2633
 *
2634
 * @return
2635
 *   The key of the formerly active database.
2636
 */
2637
function db_set_active($key = 'default') {
2638
  return Database::setActiveConnection($key);
2639
}
2640

    
2641
/**
2642
 * Restricts a dynamic table name to safe characters.
2643
 *
2644
 * Only keeps alphanumeric and underscores.
2645
 *
2646
 * @param $table
2647
 *   The table name to escape.
2648
 *
2649
 * @return
2650
 *   The escaped table name as a string.
2651
 */
2652
function db_escape_table($table) {
2653
  return Database::getConnection()->escapeTable($table);
2654
}
2655

    
2656
/**
2657
 * Restricts a dynamic column or constraint name to safe characters.
2658
 *
2659
 * Only keeps alphanumeric and underscores.
2660
 *
2661
 * @param $field
2662
 *   The field name to escape.
2663
 *
2664
 * @return
2665
 *   The escaped field name as a string.
2666
 */
2667
function db_escape_field($field) {
2668
  return Database::getConnection()->escapeField($field);
2669
}
2670

    
2671
/**
2672
 * Escapes characters that work as wildcard characters in a LIKE pattern.
2673
 *
2674
 * The wildcard characters "%" and "_" as well as backslash are prefixed with
2675
 * a backslash. Use this to do a search for a verbatim string without any
2676
 * wildcard behavior.
2677
 *
2678
 * For example, the following does a case-insensitive query for all rows whose
2679
 * name starts with $prefix:
2680
 * @code
2681
 * $result = db_query(
2682
 *   'SELECT * FROM person WHERE name LIKE :pattern',
2683
 *   array(':pattern' => db_like($prefix) . '%')
2684
 * );
2685
 * @endcode
2686
 *
2687
 * Backslash is defined as escape character for LIKE patterns in
2688
 * DatabaseCondition::mapConditionOperator().
2689
 *
2690
 * @param $string
2691
 *   The string to escape.
2692
 *
2693
 * @return
2694
 *   The escaped string.
2695
 */
2696
function db_like($string) {
2697
  return Database::getConnection()->escapeLike($string);
2698
}
2699

    
2700
/**
2701
 * Retrieves the name of the currently active database driver.
2702
 *
2703
 * @return
2704
 *   The name of the currently active database driver.
2705
 */
2706
function db_driver() {
2707
  return Database::getConnection()->driver();
2708
}
2709

    
2710
/**
2711
 * Closes the active database connection.
2712
 *
2713
 * @param $options
2714
 *   An array of options to control which connection is closed. Only the target
2715
 *   key has any meaning in this case.
2716
 */
2717
function db_close(array $options = array()) {
2718
  if (empty($options['target'])) {
2719
    $options['target'] = NULL;
2720
  }
2721
  Database::closeConnection($options['target']);
2722
}
2723

    
2724
/**
2725
 * Retrieves a unique id.
2726
 *
2727
 * Use this function if for some reason you can't use a serial field. Using a
2728
 * serial field is preferred, and InsertQuery::execute() returns the value of
2729
 * the last ID inserted.
2730
 *
2731
 * @param $existing_id
2732
 *   After a database import, it might be that the sequences table is behind, so
2733
 *   by passing in a minimum ID, it can be assured that we never issue the same
2734
 *   ID.
2735
 *
2736
 * @return
2737
 *   An integer number larger than any number returned before for this sequence.
2738
 */
2739
function db_next_id($existing_id = 0) {
2740
  return Database::getConnection()->nextId($existing_id);
2741
}
2742

    
2743
/**
2744
 * Returns a new DatabaseCondition, set to "OR" all conditions together.
2745
 *
2746
 * @return DatabaseCondition
2747
 */
2748
function db_or() {
2749
  return new DatabaseCondition('OR');
2750
}
2751

    
2752
/**
2753
 * Returns a new DatabaseCondition, set to "AND" all conditions together.
2754
 *
2755
 * @return DatabaseCondition
2756
 */
2757
function db_and() {
2758
  return new DatabaseCondition('AND');
2759
}
2760

    
2761
/**
2762
 * Returns a new DatabaseCondition, set to "XOR" all conditions together.
2763
 *
2764
 * @return DatabaseCondition
2765
 */
2766
function db_xor() {
2767
  return new DatabaseCondition('XOR');
2768
}
2769

    
2770
/**
2771
 * Returns a new DatabaseCondition, set to the specified conjunction.
2772
 *
2773
 * Internal API function call.  The db_and(), db_or(), and db_xor()
2774
 * functions are preferred.
2775
 *
2776
 * @param $conjunction
2777
 *   The conjunction to use for query conditions (AND, OR or XOR).
2778
 * @return DatabaseCondition
2779
 */
2780
function db_condition($conjunction) {
2781
  return new DatabaseCondition($conjunction);
2782
}
2783

    
2784
/**
2785
 * @} End of "defgroup database".
2786
 */
2787

    
2788

    
2789
/**
2790
 * @addtogroup schemaapi
2791
 * @{
2792
 */
2793

    
2794
/**
2795
 * Creates a new table from a Drupal table definition.
2796
 *
2797
 * @param $name
2798
 *   The name of the table to create.
2799
 * @param $table
2800
 *   A Schema API table definition array.
2801
 */
2802
function db_create_table($name, $table) {
2803
  return Database::getConnection()->schema()->createTable($name, $table);
2804
}
2805

    
2806
/**
2807
 * Returns an array of field names from an array of key/index column specifiers.
2808
 *
2809
 * This is usually an identity function but if a key/index uses a column prefix
2810
 * specification, this function extracts just the name.
2811
 *
2812
 * @param $fields
2813
 *   An array of key/index column specifiers.
2814
 *
2815
 * @return
2816
 *   An array of field names.
2817
 */
2818
function db_field_names($fields) {
2819
  return Database::getConnection()->schema()->fieldNames($fields);
2820
}
2821

    
2822
/**
2823
 * Checks if an index exists in the given table.
2824
 *
2825
 * @param $table
2826
 *   The name of the table in drupal (no prefixing).
2827
 * @param $name
2828
 *   The name of the index in drupal (no prefixing).
2829
 *
2830
 * @return
2831
 *   TRUE if the given index exists, otherwise FALSE.
2832
 */
2833
function db_index_exists($table, $name) {
2834
  return Database::getConnection()->schema()->indexExists($table, $name);
2835
}
2836

    
2837
/**
2838
 * Checks if a table exists.
2839
 *
2840
 * @param $table
2841
 *   The name of the table in drupal (no prefixing).
2842
 *
2843
 * @return
2844
 *   TRUE if the given table exists, otherwise FALSE.
2845
 */
2846
function db_table_exists($table) {
2847
  return Database::getConnection()->schema()->tableExists($table);
2848
}
2849

    
2850
/**
2851
 * Checks if a column exists in the given table.
2852
 *
2853
 * @param $table
2854
 *   The name of the table in drupal (no prefixing).
2855
 * @param $field
2856
 *   The name of the field.
2857
 *
2858
 * @return
2859
 *   TRUE if the given column exists, otherwise FALSE.
2860
 */
2861
function db_field_exists($table, $field) {
2862
  return Database::getConnection()->schema()->fieldExists($table, $field);
2863
}
2864

    
2865
/**
2866
 * Finds all tables that are like the specified base table name.
2867
 *
2868
 * @param $table_expression
2869
 *   An SQL expression, for example "simpletest%" (without the quotes).
2870
 *
2871
 * @return
2872
 *   Array, both the keys and the values are the matching tables.
2873
 */
2874
function db_find_tables($table_expression) {
2875
  return Database::getConnection()->schema()->findTables($table_expression);
2876
}
2877

    
2878
/**
2879
 * Finds all tables that are like the specified base table name. This is a
2880
 * backport of the change made to db_find_tables in Drupal 8 to work with
2881
 * virtual, un-prefixed table names. The original function is retained for
2882
 * Backwards Compatibility.
2883
 * @see https://www.drupal.org/node/2552435
2884
 *
2885
 * @param $table_expression
2886
 *   An SQL expression, for example "simpletest%" (without the quotes).
2887
 *
2888
 * @return
2889
 *   Array, both the keys and the values are the matching tables.
2890
 */
2891
function db_find_tables_d8($table_expression) {
2892
  return Database::getConnection()->schema()->findTablesD8($table_expression);
2893
}
2894

    
2895
function _db_create_keys_sql($spec) {
2896
  return Database::getConnection()->schema()->createKeysSql($spec);
2897
}
2898

    
2899
/**
2900
 * Renames a table.
2901
 *
2902
 * @param $table
2903
 *   The current name of the table to be renamed.
2904
 * @param $new_name
2905
 *   The new name for the table.
2906
 */
2907
function db_rename_table($table, $new_name) {
2908
  return Database::getConnection()->schema()->renameTable($table, $new_name);
2909
}
2910

    
2911
/**
2912
 * Drops a table.
2913
 *
2914
 * @param $table
2915
 *   The table to be dropped.
2916
 */
2917
function db_drop_table($table) {
2918
  return Database::getConnection()->schema()->dropTable($table);
2919
}
2920

    
2921
/**
2922
 * Adds a new field to a table.
2923
 *
2924
 * @param $table
2925
 *   Name of the table to be altered.
2926
 * @param $field
2927
 *   Name of the field to be added.
2928
 * @param $spec
2929
 *   The field specification array, as taken from a schema definition. The
2930
 *   specification may also contain the key 'initial'; the newly-created field
2931
 *   will be set to the value of the key in all rows. This is most useful for
2932
 *   creating NOT NULL columns with no default value in existing tables.
2933
 * @param $keys_new
2934
 *   (optional) Keys and indexes specification to be created on the table along
2935
 *   with adding the field. The format is the same as a table specification, but
2936
 *   without the 'fields' element. If you are adding a type 'serial' field, you
2937
 *   MUST specify at least one key or index including it in this array. See
2938
 *   db_change_field() for more explanation why.
2939
 *
2940
 * @see db_change_field()
2941
 */
2942
function db_add_field($table, $field, $spec, $keys_new = array()) {
2943
  return Database::getConnection()->schema()->addField($table, $field, $spec, $keys_new);
2944
}
2945

    
2946
/**
2947
 * Drops a field.
2948
 *
2949
 * @param $table
2950
 *   The table to be altered.
2951
 * @param $field
2952
 *   The field to be dropped.
2953
 */
2954
function db_drop_field($table, $field) {
2955
  return Database::getConnection()->schema()->dropField($table, $field);
2956
}
2957

    
2958
/**
2959
 * Sets the default value for a field.
2960
 *
2961
 * @param $table
2962
 *   The table to be altered.
2963
 * @param $field
2964
 *   The field to be altered.
2965
 * @param $default
2966
 *   Default value to be set. NULL for 'default NULL'.
2967
 */
2968
function db_field_set_default($table, $field, $default) {
2969
  return Database::getConnection()->schema()->fieldSetDefault($table, $field, $default);
2970
}
2971

    
2972
/**
2973
 * Sets a field to have no default value.
2974
 *
2975
 * @param $table
2976
 *   The table to be altered.
2977
 * @param $field
2978
 *   The field to be altered.
2979
 */
2980
function db_field_set_no_default($table, $field) {
2981
  return Database::getConnection()->schema()->fieldSetNoDefault($table, $field);
2982
}
2983

    
2984
/**
2985
 * Adds a primary key to a database table.
2986
 *
2987
 * @param $table
2988
 *   Name of the table to be altered.
2989
 * @param $fields
2990
 *   Array of fields for the primary key.
2991
 */
2992
function db_add_primary_key($table, $fields) {
2993
  return Database::getConnection()->schema()->addPrimaryKey($table, $fields);
2994
}
2995

    
2996
/**
2997
 * Drops the primary key of a database table.
2998
 *
2999
 * @param $table
3000
 *   Name of the table to be altered.
3001
 */
3002
function db_drop_primary_key($table) {
3003
  return Database::getConnection()->schema()->dropPrimaryKey($table);
3004
}
3005

    
3006
/**
3007
 * Adds a unique key.
3008
 *
3009
 * @param $table
3010
 *   The table to be altered.
3011
 * @param $name
3012
 *   The name of the key.
3013
 * @param $fields
3014
 *   An array of field names.
3015
 */
3016
function db_add_unique_key($table, $name, $fields) {
3017
  return Database::getConnection()->schema()->addUniqueKey($table, $name, $fields);
3018
}
3019

    
3020
/**
3021
 * Drops a unique key.
3022
 *
3023
 * @param $table
3024
 *   The table to be altered.
3025
 * @param $name
3026
 *   The name of the key.
3027
 */
3028
function db_drop_unique_key($table, $name) {
3029
  return Database::getConnection()->schema()->dropUniqueKey($table, $name);
3030
}
3031

    
3032
/**
3033
 * Adds an index.
3034
 *
3035
 * @param $table
3036
 *   The table to be altered.
3037
 * @param $name
3038
 *   The name of the index.
3039
 * @param $fields
3040
 *   An array of field names.
3041
 */
3042
function db_add_index($table, $name, $fields) {
3043
  return Database::getConnection()->schema()->addIndex($table, $name, $fields);
3044
}
3045

    
3046
/**
3047
 * Drops an index.
3048
 *
3049
 * @param $table
3050
 *   The table to be altered.
3051
 * @param $name
3052
 *   The name of the index.
3053
 */
3054
function db_drop_index($table, $name) {
3055
  return Database::getConnection()->schema()->dropIndex($table, $name);
3056
}
3057

    
3058
/**
3059
 * Changes a field definition.
3060
 *
3061
 * IMPORTANT NOTE: To maintain database portability, you have to explicitly
3062
 * recreate all indices and primary keys that are using the changed field.
3063
 *
3064
 * That means that you have to drop all affected keys and indexes with
3065
 * db_drop_{primary_key,unique_key,index}() before calling db_change_field().
3066
 * To recreate the keys and indices, pass the key definitions as the optional
3067
 * $keys_new argument directly to db_change_field().
3068
 *
3069
 * For example, suppose you have:
3070
 * @code
3071
 * $schema['foo'] = array(
3072
 *   'fields' => array(
3073
 *     'bar' => array('type' => 'int', 'not null' => TRUE)
3074
 *   ),
3075
 *   'primary key' => array('bar')
3076
 * );
3077
 * @endcode
3078
 * and you want to change foo.bar to be type serial, leaving it as the primary
3079
 * key. The correct sequence is:
3080
 * @code
3081
 * db_drop_primary_key('foo');
3082
 * db_change_field('foo', 'bar', 'bar',
3083
 *   array('type' => 'serial', 'not null' => TRUE),
3084
 *   array('primary key' => array('bar')));
3085
 * @endcode
3086
 *
3087
 * The reasons for this are due to the different database engines:
3088
 *
3089
 * On PostgreSQL, changing a field definition involves adding a new field and
3090
 * dropping an old one which causes any indices, primary keys and sequences
3091
 * (from serial-type fields) that use the changed field to be dropped.
3092
 *
3093
 * On MySQL, all type 'serial' fields must be part of at least one key or index
3094
 * as soon as they are created. You cannot use
3095
 * db_add_{primary_key,unique_key,index}() for this purpose because the ALTER
3096
 * TABLE command will fail to add the column without a key or index
3097
 * specification. The solution is to use the optional $keys_new argument to
3098
 * create the key or index at the same time as field.
3099
 *
3100
 * You could use db_add_{primary_key,unique_key,index}() in all cases unless you
3101
 * are converting a field to be type serial. You can use the $keys_new argument
3102
 * in all cases.
3103
 *
3104
 * @param $table
3105
 *   Name of the table.
3106
 * @param $field
3107
 *   Name of the field to change.
3108
 * @param $field_new
3109
 *   New name for the field (set to the same as $field if you don't want to
3110
 *   change the name).
3111
 * @param $spec
3112
 *   The field specification for the new field.
3113
 * @param $keys_new
3114
 *   (optional) Keys and indexes specification to be created on the table along
3115
 *   with changing the field. The format is the same as a table specification
3116
 *   but without the 'fields' element.
3117
 */
3118
function db_change_field($table, $field, $field_new, $spec, $keys_new = array()) {
3119
  return Database::getConnection()->schema()->changeField($table, $field, $field_new, $spec, $keys_new);
3120
}
3121

    
3122
/**
3123
 * @} End of "addtogroup schemaapi".
3124
 */
3125

    
3126
/**
3127
 * Sets a session variable specifying the lag time for ignoring a slave server.
3128
 */
3129
function db_ignore_slave() {
3130
  $connection_info = Database::getConnectionInfo();
3131
  // Only set ignore_slave_server if there are slave servers being used, which
3132
  // is assumed if there are more than one.
3133
  if (count($connection_info) > 1) {
3134
    // Five minutes is long enough to allow the slave to break and resume
3135
    // interrupted replication without causing problems on the Drupal site from
3136
    // the old data.
3137
    $duration = variable_get('maximum_replication_lag', 300);
3138
    // Set session variable with amount of time to delay before using slave.
3139
    $_SESSION['ignore_slave_server'] = REQUEST_TIME + $duration;
3140
  }
3141
}