Connection.php 44.5 KB
Newer Older
1 2
<?php

3 4
/**
 * @file
5
 * Contains \Drupal\Core\Database\Connection.
6 7
 */

8
namespace Drupal\Core\Database;
9 10 11 12 13 14 15 16 17

/**
 * Base Database API class.
 *
 * This class provides a Drupal-specific extension of the PDO database
 * abstraction class in PHP. Every database driver implementation must provide a
 * concrete implementation of it to support special handling required by that
 * database.
 *
18
 * @see http://php.net/manual/book.pdo.php
19
 */
20
abstract class Connection {
21 22 23 24 25 26

  /**
   * The database target this connection is for.
   *
   * We need this information for later auditing and logging.
   *
27
   * @var string|null
28 29 30 31 32 33 34
   */
  protected $target = NULL;

  /**
   * The key representing this connection.
   *
   * The key is a unique string which identifies a database connection. A
35 36
   * connection can be a single server or a cluster of primary and replicas
   * (use target to pick between primary and replica).
37
   *
38
   * @var string|null
39 40 41 42 43 44
   */
  protected $key = NULL;

  /**
   * The current database logging object for this connection.
   *
45
   * @var \Drupal\Core\Database\Log|null
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
   */
  protected $logger = NULL;

  /**
   * Tracks the number of "layers" of transactions currently active.
   *
   * On many databases transactions cannot nest.  Instead, we track
   * nested calls to transactions and collapse them into a single
   * transaction.
   *
   * @var array
   */
  protected $transactionLayers = array();

  /**
   * Index of what driver-specific class to use for various operations.
   *
   * @var array
   */
  protected $driverClasses = array();

  /**
   * The name of the Statement class for this connection.
   *
   * @var string
   */
72
  protected $statementClass = 'Drupal\Core\Database\Statement';
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96

  /**
   * Whether this database connection supports transactions.
   *
   * @var bool
   */
  protected $transactionSupport = TRUE;

  /**
   * Whether this database connection supports transactional DDL.
   *
   * Set to FALSE by default because few databases support this feature.
   *
   * @var bool
   */
  protected $transactionalDDLSupport = FALSE;

  /**
   * An index used to generate unique temporary table names.
   *
   * @var integer
   */
  protected $temporaryNameIndex = 0;

97 98 99 100 101 102 103
  /**
   * The actual PDO connection.
   *
   * @var \PDO
   */
  protected $connection;

104 105 106 107 108 109 110 111 112 113
  /**
   * The connection information for this connection object.
   *
   * @var array
   */
  protected $connectionOptions = array();

  /**
   * The schema object for this connection.
   *
114 115 116
   * Set to NULL when the schema is destroyed.
   *
   * @var \Drupal\Core\Database\Schema|null
117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140
   */
  protected $schema = NULL;

  /**
   * The prefixes used by this database connection.
   *
   * @var array
   */
  protected $prefixes = array();

  /**
   * List of search values for use in prefixTables().
   *
   * @var array
   */
  protected $prefixSearch = array();

  /**
   * List of replacement values for use in prefixTables().
   *
   * @var array
   */
  protected $prefixReplace = array();

141 142
  /**
   * Constructs a Connection object.
143 144 145 146 147 148 149 150
   *
   * @param \PDO $connection
   *   An object of the PDO class representing a database connection.
   * @param array $connection_options
   *   An array of options for the connection. May include the following:
   *   - prefix
   *   - namespace
   *   - Other driver-specific options.
151
   */
152
  public function __construct(\PDO $connection, array $connection_options) {
153
    // Initialize and prepare the connection prefix.
154
    $this->setPrefix(isset($connection_options['prefix']) ? $connection_options['prefix'] : '');
155

156
    // Set a Statement class, unless the driver opted out.
157
    if (!empty($this->statementClass)) {
158
      $connection->setAttribute(\PDO::ATTR_STATEMENT_CLASS, array($this->statementClass, array($this)));
159
    }
160 161 162

    $this->connection = $connection;
    $this->connectionOptions = $connection_options;
163 164
  }

165 166 167 168 169 170 171 172 173 174 175
  /**
   * Opens a PDO connection.
   *
   * @param array $connection_options
   *   The database connection settings array.
   *
   * @return \PDO
   *   A \PDO object.
   */
  public static function open(array &$connection_options = array()) { }

176 177 178 179 180 181 182 183 184 185 186 187
  /**
   * Destroys this Connection object.
   *
   * PHP does not destruct an object if it is still referenced in other
   * variables. In case of PDO database connection objects, PHP only closes the
   * connection when the PDO object is destructed, so any references to this
   * object may cause the number of maximum allowed connections to be exceeded.
   */
  public function destroy() {
    // Destroy all references to this connection by setting them to NULL.
    // The Statement class attribute only accepts a new value that presents a
    // proper callable, so we reset it to PDOStatement.
188
    $this->connection->setAttribute(\PDO::ATTR_STATEMENT_CLASS, array('PDOStatement', array()));
189 190 191
    $this->schema = NULL;
  }

192 193 194 195 196 197
  /**
   * Returns the default query options for any given query.
   *
   * A given query can be customized with a number of option flags in an
   * associative array:
   * - target: The database "target" against which to execute a query. Valid
198
   *   values are "default" or "replica". The system will first try to open a
199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233
   *   connection to a database specified with the user-supplied key. If one
   *   is not available, it will silently fall back to the "default" target.
   *   If multiple databases connections are specified with the same target,
   *   one will be selected at random for the duration of the request.
   * - fetch: This element controls how rows from a result set will be
   *   returned. Legal values include PDO::FETCH_ASSOC, PDO::FETCH_BOTH,
   *   PDO::FETCH_OBJ, PDO::FETCH_NUM, or a string representing the name of a
   *   class. If a string is specified, each record will be fetched into a new
   *   object of that class. The behavior of all other values is defined by PDO.
   *   See http://php.net/manual/pdostatement.fetch.php
   * - return: Depending on the type of query, different return values may be
   *   meaningful. This directive instructs the system which type of return
   *   value is desired. The system will generally set the correct value
   *   automatically, so it is extremely rare that a module developer will ever
   *   need to specify this value. Setting it incorrectly will likely lead to
   *   unpredictable results or fatal errors. Legal values include:
   *   - Database::RETURN_STATEMENT: Return the prepared statement object for
   *     the query. This is usually only meaningful for SELECT queries, where
   *     the statement object is how one accesses the result set returned by the
   *     query.
   *   - Database::RETURN_AFFECTED: Return the number of rows affected by an
   *     UPDATE or DELETE query. Be aware that means the number of rows actually
   *     changed, not the number of rows matched by the WHERE clause.
   *   - Database::RETURN_INSERT_ID: Return the sequence ID (primary key)
   *     created by an INSERT statement on a table that contains a serial
   *     column.
   *   - Database::RETURN_NULL: Do not return anything, as there is no
   *     meaningful value to return. That is the case for INSERT queries on
   *     tables that do not contain a serial column.
   * - throw_exception: By default, the database system will catch any errors
   *   on a query as an Exception, log it, and then rethrow it so that code
   *   further up the call chain can take an appropriate action. To suppress
   *   that behavior and simply return NULL on failure, set this option to
   *   FALSE.
   *
234
   * @return array
235 236 237 238 239
   *   An array of default query options.
   */
  protected function defaultOptions() {
    return array(
      'target' => 'default',
240
      'fetch' => \PDO::FETCH_OBJ,
241 242 243 244 245 246 247 248 249 250 251 252 253
      'return' => Database::RETURN_STATEMENT,
      'throw_exception' => TRUE,
    );
  }

  /**
   * Returns the connection information for this connection object.
   *
   * Note that Database::getConnectionInfo() is for requesting information
   * about an arbitrary database connection that is defined. This method
   * is for requesting the connection information of this specific
   * open connection object.
   *
254
   * @return array
255 256 257 258 259 260 261 262 263 264
   *   An array of the connection information. The exact list of
   *   properties is driver-dependent.
   */
  public function getConnectionOptions() {
    return $this->connectionOptions;
  }

  /**
   * Set the list of prefixes used by this database connection.
   *
265 266 267
   * @param array|string $prefix
   *   Either a single prefix, or an array of prefixes, in any of the multiple
   *   forms documented in default.settings.php.
268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301
   */
  protected function setPrefix($prefix) {
    if (is_array($prefix)) {
      $this->prefixes = $prefix + array('default' => '');
    }
    else {
      $this->prefixes = array('default' => $prefix);
    }

    // Set up variables for use in prefixTables(). Replace table-specific
    // prefixes first.
    $this->prefixSearch = array();
    $this->prefixReplace = array();
    foreach ($this->prefixes as $key => $val) {
      if ($key != 'default') {
        $this->prefixSearch[] = '{' . $key . '}';
        $this->prefixReplace[] = $val . $key;
      }
    }
    // Then replace remaining tables with the default prefix.
    $this->prefixSearch[] = '{';
    $this->prefixReplace[] = $this->prefixes['default'];
    $this->prefixSearch[] = '}';
    $this->prefixReplace[] = '';
  }

  /**
   * Appends a database prefix to all tables in a query.
   *
   * Queries sent to Drupal should wrap all table names in curly brackets. This
   * function searches for this syntax and adds Drupal's table prefix to all
   * tables, allowing Drupal to coexist with other systems in the same database
   * and/or schema if necessary.
   *
302
   * @param string $sql
303 304
   *   A string containing a partial or entire SQL query.
   *
305
   * @return string
306 307 308 309 310 311 312 313 314 315 316
   *   The properly-prefixed string.
   */
  public function prefixTables($sql) {
    return str_replace($this->prefixSearch, $this->prefixReplace, $sql);
  }

  /**
   * Find the prefix for a table.
   *
   * This function is for when you want to know the prefix of a table. This
   * is not used in prefixTables due to performance reasons.
317 318 319
   *
   * @param string $table
   *   (optional) The table to find the prefix for.
320 321 322 323 324 325 326 327 328 329
   */
  public function tablePrefix($table = 'default') {
    if (isset($this->prefixes[$table])) {
      return $this->prefixes[$table];
    }
    else {
      return $this->prefixes['default'];
    }
  }

330 331 332 333 334 335 336 337 338 339 340 341 342 343
  /**
   * Get a fully qualified table name.
   *
   * @param string $table
   *   The name of the table in question.
   *
   * @return string
   */
  public function getFullQualifiedTableName($table) {
    $options = $this->getConnectionOptions();
    $prefix = $this->tablePrefix($table);
    return $options['database'] . '.' . $prefix . $table;
  }

344 345 346 347 348 349 350 351 352 353
  /**
   * Prepares a query string and returns the prepared statement.
   *
   * This method caches prepared statements, reusing them when
   * possible. It also prefixes tables names enclosed in curly-braces.
   *
   * @param $query
   *   The query string as SQL, with curly-braces surrounding the
   *   table names.
   *
354
   * @return \Drupal\Core\Database\StatementInterface
355 356 357 358 359
   *   A PDO prepared statement ready for its execute() method.
   */
  public function prepareQuery($query) {
    $query = $this->prefixTables($query);

360
    return $this->connection->prepare($query);
361 362 363 364 365 366 367 368 369 370
  }

  /**
   * Tells this connection object what its target value is.
   *
   * This is needed for logging and auditing. It's sloppy to do in the
   * constructor because the constructor for child classes has a different
   * signature. We therefore also ensure that this function is only ever
   * called once.
   *
371 372
   * @param string $target
   *   (optional) The target this connection is for.
373 374 375 376 377 378 379 380 381 382
   */
  public function setTarget($target = NULL) {
    if (!isset($this->target)) {
      $this->target = $target;
    }
  }

  /**
   * Returns the target this connection is associated with.
   *
383 384
   * @return string|null
   *   The target string of this connection, or NULL if no target is set.
385 386 387 388 389 390 391 392
   */
  public function getTarget() {
    return $this->target;
  }

  /**
   * Tells this connection object what its key is.
   *
393
   * @param string $key
394 395 396 397 398 399 400 401 402 403 404
   *   The key this connection is for.
   */
  public function setKey($key) {
    if (!isset($this->key)) {
      $this->key = $key;
    }
  }

  /**
   * Returns the key this connection is associated with.
   *
405 406
   * @return string|null
   *   The key of this connection, or NULL if no key is set.
407 408 409 410 411 412 413 414
   */
  public function getKey() {
    return $this->key;
  }

  /**
   * Associates a logging object with this connection.
   *
415
   * @param \Drupal\Core\Database\Log $logger
416 417
   *   The logging object we want to use.
   */
418
  public function setLogger(Log $logger) {
419 420 421 422 423 424
    $this->logger = $logger;
  }

  /**
   * Gets the current logging object for this connection.
   *
425
   * @return \Drupal\Core\Database\Log|null
426 427 428 429 430 431 432 433 434 435 436 437 438
   *   The current logging object for this connection. If there isn't one,
   *   NULL is returned.
   */
  public function getLogger() {
    return $this->logger;
  }

  /**
   * Creates the appropriate sequence name for a given table and serial field.
   *
   * This information is exposed to all database drivers, although it is only
   * useful on some of them. This method is table prefix-aware.
   *
439
   * @param string $table
440
   *   The table name to use for the sequence.
441
   * @param string $field
442 443
   *   The field name to use for the sequence.
   *
444
   * @return string
445 446 447 448 449 450 451 452 453 454 455
   *   A table prefix-parsed string for the sequence name.
   */
  public function makeSequenceName($table, $field) {
    return $this->prefixTables('{' . $table . '}_' . $field . '_seq');
  }

  /**
   * Flatten an array of query comments into a single comment string.
   *
   * The comment string will be sanitized to avoid SQL injection attacks.
   *
456
   * @param string[] $comments
457 458
   *   An array of query comment strings.
   *
459
   * @return string
460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497
   *   A sanitized comment string.
   */
  public function makeComment($comments) {
    if (empty($comments))
      return '';

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

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

  /**
   * Sanitize a query comment string.
   *
   * Ensure a query comment does not include strings such as "* /" that might
   * terminate the comment early. This avoids SQL injection attacks via the
   * query comment. The comment strings in this example are separated by a
   * space to avoid PHP parse errors.
   *
   * For example, the comment:
   * @code
   * db_update('example')
   *  ->condition('id', $id)
   *  ->fields(array('field2' => 10))
   *  ->comment('Exploit * / DROP TABLE node; --')
   *  ->execute()
   * @endcode
   *
   * Would result in the following SQL statement being generated:
   * @code
   * "/ * Exploit * / DROP TABLE node; -- * / UPDATE example SET field2=..."
   * @endcode
   *
   * Unless the comment is sanitised first, the SQL server would drop the
   * node table and ignore the rest of the SQL statement.
   *
498
   * @param string $comment
499 500
   *   A query comment string.
   *
501
   * @return string
502 503 504 505 506 507 508 509 510 511 512 513 514
   *   A sanitized version of the query comment string.
   */
  protected function filterComment($comment = '') {
    return preg_replace('/(\/\*\s*)|(\s*\*\/)/', '', $comment);
  }

  /**
   * Executes a query string against the database.
   *
   * This method provides a central handler for the actual execution of every
   * query. All queries executed by Drupal are executed as PDO prepared
   * statements.
   *
515
   * @param string|\Drupal\Core\Database\StatementInterface $query
516 517
   *   The query to execute. In most cases this will be a string containing
   *   an SQL query with placeholders. An already-prepared instance of
518
   *   StatementInterface may also be passed in order to allow calling
519
   *   code to manually bind variables to a query. If a
520
   *   StatementInterface is passed, the $args array will be ignored.
521 522 523
   *   It is extremely rare that module code will need to pass a statement
   *   object to this method. It is used primarily for database drivers for
   *   databases that require special LOB field handling.
524
   * @param array $args
525 526 527
   *   An array of arguments for the prepared statement. If the prepared
   *   statement uses ? placeholders, this array must be an indexed array.
   *   If it contains named placeholders, it must be an associative array.
528 529 530 531 532 533
   * @param array $options
   *   An associative array of options to control how the query is run. The
   *   given options will be merged with self::defaultOptions(). See the
   *   documentation for self::defaultOptions() for details.
   *   Typically, $options['return'] will be set by a default or by a query
   *   builder, and should not be set by a user.
534
   *
535
   * @return \Drupal\Core\Database\StatementInterface|int|null
536 537 538 539 540 541 542 543 544 545 546 547
   *   This method will return one of the following:
   *   - If either $options['return'] === self::RETURN_STATEMENT, or
   *     $options['return'] is not set (due to self::defaultOptions()),
   *     returns the executed statement.
   *   - If $options['return'] === self::RETURN_AFFECTED,
   *     returns the number of rows affected by the query
   *     (not the number matched).
   *   - If $options['return'] === self::RETURN_INSERT_ID,
   *     returns the generated insert ID of the last query.
   *   - If either $options['return'] === self::RETURN_NULL, or
   *     an exception occurs and $options['throw_exception'] evaluates to FALSE,
   *     returns NULL.
548
   *
549
   * @throws \Drupal\Core\Database\DatabaseExceptionWrapper
550
   * @throws \Drupal\Core\Database\IntegrityConstraintViolationException
551
   * @throws \InvalidArgumentException
552 553
   *
   * @see \Drupal\Core\Database\Connection::defaultOptions()
554 555 556 557 558 559 560 561 562
   */
  public function query($query, array $args = array(), $options = array()) {
    // Use default values if not already set.
    $options += $this->defaultOptions();

    try {
      // We allow either a pre-bound statement object or a literal string.
      // In either case, we want to end up with an executed statement object,
      // which we pass to PDOStatement::execute.
563
      if ($query instanceof StatementInterface) {
564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579
        $stmt = $query;
        $stmt->execute(NULL, $options);
      }
      else {
        $this->expandArguments($query, $args);
        $stmt = $this->prepareQuery($query);
        $stmt->execute($args, $options);
      }

      // Depending on the type of query we may need to return a different value.
      // See DatabaseConnection::defaultOptions() for a description of each
      // value.
      switch ($options['return']) {
        case Database::RETURN_STATEMENT:
          return $stmt;
        case Database::RETURN_AFFECTED:
580
          $stmt->allowRowCount = TRUE;
581 582
          return $stmt->rowCount();
        case Database::RETURN_INSERT_ID:
583 584
          $sequence_name = isset($options['sequence_name']) ? $options['sequence_name'] : NULL;
          return $this->connection->lastInsertId($sequence_name);
585
        case Database::RETURN_NULL:
586
          return NULL;
587
        default:
588
          throw new \PDOException('Invalid return directive: ' . $options['return']);
589 590
      }
    }
591
    catch (\PDOException $e) {
592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628
      // Most database drivers will return NULL here, but some of them
      // (e.g. the SQLite driver) may need to re-run the query, so the return
      // value will be the same as for static::query().
      return $this->handleQueryException($e, $query, $args, $options);
    }
  }

  /**
   * Wraps and re-throws any PDO exception thrown by static::query().
   *
   * @param \PDOException $e
   *   The exception thrown by static::query().
   * @param $query
   *   The query executed by static::query().
   * @param array $args
   *   An array of arguments for the prepared statement.
   * @param array $options
   *   An associative array of options to control how the query is run.
   *
   * @return \Drupal\Core\Database\StatementInterface|int|null
   *   Most database drivers will return NULL when a PDO exception is thrown for
   *   a query, but some of them may need to re-run the query, so they can also
   *   return a \Drupal\Core\Database\StatementInterface object or an integer.
   *
   * @throws \Drupal\Core\Database\DatabaseExceptionWrapper
   * @throws \Drupal\Core\Database\IntegrityConstraintViolationException
   */
  protected function handleQueryException(\PDOException $e, $query, array $args = array(), $options = array()) {
    if ($options['throw_exception']) {
      // Wrap the exception in another exception, because PHP does not allow
      // overriding Exception::getMessage(). Its message is the extra database
      // debug information.
      $query_string = ($query instanceof StatementInterface) ? $query->getQueryString() : $query;
      $message = $e->getMessage() . ": " . $query_string . "; " . print_r($args, TRUE);
      // Match all SQLSTATE 23xxx errors.
      if (substr($e->getCode(), -6, -3) == '23') {
        $exception = new IntegrityConstraintViolationException($message, $e->getCode(), $e);
629
      }
630 631 632 633 634
      else {
        $exception = new DatabaseExceptionWrapper($message, 0, $e);
      }

      throw $exception;
635
    }
636 637

    return NULL;
638 639 640 641 642 643 644 645
  }

  /**
   * Expands out shorthand placeholders.
   *
   * Drupal supports an alternate syntax for doing arrays of values. We
   * therefore need to expand them out into a full, executable query string.
   *
646
   * @param string $query
647
   *   The query string to modify.
648
   * @param array $args
649 650
   *   The arguments for the query.
   *
651
   * @return bool
652
   *   TRUE if the query was modified, FALSE otherwise.
653 654 655 656 657 658 659
   *
   * @throws \InvalidArgumentException
   *   This exception is thrown when:
   *   - A placeholder that ends in [] is supplied, and the supplied value is
   *     not an array.
   *   - A placeholder that does not end in [] is supplied, and the supplied
   *     value is an array.
660 661 662 663
   */
  protected function expandArguments(&$query, &$args) {
    $modified = FALSE;

664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680
    // If the placeholder indicated the value to use is an array,  we need to
    // expand it out into a comma-delimited set of placeholders.
    foreach ($args as $key => $data) {
      $is_bracket_placeholder = substr($key, -2) === '[]';
      $is_array_data = is_array($data);
      if ($is_bracket_placeholder && !$is_array_data) {
        throw new \InvalidArgumentException('Placeholders with a trailing [] can only be expanded with an array of values.');
      }
      elseif (!$is_bracket_placeholder) {
        if ($is_array_data) {
          throw new \InvalidArgumentException('Placeholders must have a trailing [] if they are to be expanded with an array of values.');
        }
        // Scalar placeholder - does not need to be expanded.
        continue;
      }
      // Handle expansion of arrays.
      $key_name = str_replace('[]', '__', $key);
681
      $new_keys = array();
682 683
      // We require placeholders to have trailing brackets if the developer
      // intends them to be expanded to an array to make the intent explicit.
684
      foreach (array_values($data) as $i => $value) {
685
        // This assumes that there are no other placeholders that use the same
686
        // name.  For example, if the array placeholder is defined as :example[]
687 688 689
        // and there is already an :example_2 placeholder, this will generate
        // a duplicate key.  We do not account for that as the calling code
        // is already broken if that happens.
690
        $new_keys[$key_name . $i] = $value;
691 692 693
      }

      // Update the query with the new placeholders.
694
      $query = str_replace($key, implode(', ', array_keys($new_keys)), $query);
695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713

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

      $modified = TRUE;
    }

    return $modified;
  }

  /**
   * Gets the driver-specific override class if any for the specified class.
   *
   * @param string $class
   *   The class for which we want the potentially driver-specific class.
   * @return string
   *   The name of the class that should be used for this driver.
   */
714
  public function getDriverClass($class) {
715 716
    if (empty($this->driverClasses[$class])) {
      $driver = $this->driver();
717 718 719 720 721 722 723
      if (!empty($this->connectionOptions['namespace'])) {
        $driver_class  = $this->connectionOptions['namespace'] . '\\' . $class;
      }
      else {
        // Fallback for Drupal 7 settings.php.
        $driver_class = "Drupal\\Core\\Database\\Driver\\{$driver}\\{$class}";
      }
724
      $this->driverClasses[$class] = class_exists($driver_class) ? $driver_class : $class;
725 726 727 728 729 730 731
    }
    return $this->driverClasses[$class];
  }

  /**
   * Prepares and returns a SELECT query object.
   *
732
   * @param string $table
733 734 735
   *   The base table for this query, that is, the first table in the FROM
   *   clause. This table will also be used as the "base" table for query_alter
   *   hook implementations.
736 737
   * @param string $alias
   *   (optional) The alias of the base table of this query.
738 739 740
   * @param $options
   *   An array of options on the query.
   *
741
   * @return \Drupal\Core\Database\Query\SelectInterface
742 743 744 745
   *   An appropriate SelectQuery object for this database connection. Note that
   *   it may be a driver-specific subclass of SelectQuery, depending on the
   *   driver.
   *
746
   * @see \Drupal\Core\Database\Query\Select
747 748
   */
  public function select($table, $alias = NULL, array $options = array()) {
749
    $class = $this->getDriverClass('Select');
750 751 752 753 754 755
    return new $class($table, $alias, $this, $options);
  }

  /**
   * Prepares and returns an INSERT query object.
   *
756 757 758 759
   * @param string $table
   *   The table to use for the insert statement.
   * @param array $options
   *   (optional) An array of options on the query.
760
   *
761
   * @return \Drupal\Core\Database\Query\Insert
762
   *   A new Insert query object.
763
   *
764
   * @see \Drupal\Core\Database\Query\Insert
765 766
   */
  public function insert($table, array $options = array()) {
767
    $class = $this->getDriverClass('Insert');
768 769 770 771 772 773
    return new $class($this, $table, $options);
  }

  /**
   * Prepares and returns a MERGE query object.
   *
774 775 776 777
   * @param string $table
   *   The table to use for the merge statement.
   * @param array $options
   *   (optional) An array of options on the query.
778
   *
779
   * @return \Drupal\Core\Database\Query\Merge
780
   *   A new Merge query object.
781
   *
782
   * @see \Drupal\Core\Database\Query\Merge
783 784
   */
  public function merge($table, array $options = array()) {
785
    $class = $this->getDriverClass('Merge');
786 787 788 789 790 791 792
    return new $class($this, $table, $options);
  }


  /**
   * Prepares and returns an UPDATE query object.
   *
793 794 795 796
   * @param string $table
   *   The table to use for the update statement.
   * @param array $options
   *   (optional) An array of options on the query.
797
   *
798
   * @return \Drupal\Core\Database\Query\Update
799
   *   A new Update query object.
800
   *
801
   * @see \Drupal\Core\Database\Query\Update
802 803
   */
  public function update($table, array $options = array()) {
804
    $class = $this->getDriverClass('Update');
805 806 807 808 809 810
    return new $class($this, $table, $options);
  }

  /**
   * Prepares and returns a DELETE query object.
   *
811 812 813 814
   * @param string $table
   *   The table to use for the delete statement.
   * @param array $options
   *   (optional) An array of options on the query.
815
   *
816
   * @return \Drupal\Core\Database\Query\Delete
817
   *   A new Delete query object.
818
   *
819
   * @see \Drupal\Core\Database\Query\Delete
820 821
   */
  public function delete($table, array $options = array()) {
822
    $class = $this->getDriverClass('Delete');
823 824 825 826 827 828
    return new $class($this, $table, $options);
  }

  /**
   * Prepares and returns a TRUNCATE query object.
   *
829 830 831 832
   * @param string $table
   *   The table to use for the truncate statement.
   * @param array $options
   *   (optional) An array of options on the query.
833
   *
834
   * @return \Drupal\Core\Database\Query\Truncate
835
   *   A new Truncate query object.
836
   *
837
   * @see \Drupal\Core\Database\Query\Truncate
838 839
   */
  public function truncate($table, array $options = array()) {
840
    $class = $this->getDriverClass('Truncate');
841 842 843 844 845 846 847 848
    return new $class($this, $table, $options);
  }

  /**
   * Returns a DatabaseSchema object for manipulating the schema.
   *
   * This method will lazy-load the appropriate schema library file.
   *
849
   * @return \Drupal\Core\Database\Schema
850
   *   The database Schema object for this connection.
851 852 853
   */
  public function schema() {
    if (empty($this->schema)) {
854
      $class = $this->getDriverClass('Schema');
ayelet_Cr's avatar
ayelet_Cr committed
855
      $this->schema = new $class($this);
856 857 858 859
    }
    return $this->schema;
  }

860 861 862 863 864 865 866
  /**
   * Escapes a database name string.
   *
   * Force all database names to be strictly alphanumeric-plus-underscore.
   * For some database drivers, it may also wrap the database name in
   * database-specific escape characters.
   *
867 868 869
   * @param string $database
   *   An unsanitized database name.
   *
870
   * @return string
871
   *   The sanitized database name.
872 873 874 875 876
   */
  public function escapeDatabase($database) {
    return preg_replace('/[^A-Za-z0-9_.]+/', '', $database);
  }

877 878 879 880 881 882 883
  /**
   * Escapes a table name string.
   *
   * Force all table names to be strictly alphanumeric-plus-underscore.
   * For some database drivers, it may also wrap the table name in
   * database-specific escape characters.
   *
884 885 886 887 888
   * @param string $table
   *   An unsanitized table name.
   *
   * @return string
   *   The sanitized table name.
889 890 891 892 893 894 895 896 897 898 899 900
   */
  public function escapeTable($table) {
    return preg_replace('/[^A-Za-z0-9_.]+/', '', $table);
  }

  /**
   * Escapes a field name string.
   *
   * Force all field names to be strictly alphanumeric-plus-underscore.
   * For some database drivers, it may also wrap the field name in
   * database-specific escape characters.
   *
901 902 903 904 905
   * @param string $field
   *   An unsanitized field name.
   *
   * @return string
   *   The sanitized field name.
906 907 908 909 910 911 912 913 914 915 916 917 918
   */
  public function escapeField($field) {
    return preg_replace('/[^A-Za-z0-9_.]+/', '', $field);
  }

  /**
   * Escapes an alias name string.
   *
   * Force all alias names to be strictly alphanumeric-plus-underscore. In
   * contrast to DatabaseConnection::escapeField() /
   * DatabaseConnection::escapeTable(), this doesn't allow the period (".")
   * because that is not allowed in aliases.
   *
919 920 921 922 923
   * @param string $field
   *   An unsanitized alias name.
   *
   * @return string
   *   The sanitized alias name.
924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945
   */
  public function escapeAlias($field) {
    return preg_replace('/[^A-Za-z0-9_]+/', '', $field);
  }

  /**
   * Escapes characters that work as wildcard characters in a LIKE pattern.
   *
   * The wildcard characters "%" and "_" as well as backslash are prefixed with
   * a backslash. Use this to do a search for a verbatim string without any
   * wildcard behavior.
   *
   * For example, the following does a case-insensitive query for all rows whose
   * name starts with $prefix:
   * @code
   * $result = db_query(
   *   'SELECT * FROM person WHERE name LIKE :pattern',
   *   array(':pattern' => db_like($prefix) . '%')
   * );
   * @endcode
   *
   * Backslash is defined as escape character for LIKE patterns in
946
   * Drupal\Core\Database\Query\Condition::mapConditionOperator().
947
   *
948
   * @param string $string
949 950
   *   The string to escape.
   *
951
   * @return string
952 953 954 955 956 957 958 959 960
   *   The escaped string.
   */
  public function escapeLike($string) {
    return addcslashes($string, '\%_');
  }

  /**
   * Determines if there is an active transaction open.
   *
961
   * @return bool
962 963 964 965 966 967 968
   *   TRUE if we're currently in a transaction, FALSE otherwise.
   */
  public function inTransaction() {
    return ($this->transactionDepth() > 0);
  }

  /**
969 970 971 972
   * Determines the current transaction depth.
   *
   * @return int
   *   The current transaction depth.
973 974 975 976 977 978 979 980
   */
  public function transactionDepth() {
    return count($this->transactionLayers);
  }

  /**
   * Returns a new DatabaseTransaction object on this connection.
   *
981 982
   * @param string $name
   *   (optional) The name of the savepoint.
983
   *
984 985
   * @return \Drupal\Core\Database\Transaction
   *   A Transaction object.
986
   *
987
   * @see \Drupal\Core\Database\Transaction
988 989 990 991 992 993 994 995 996 997 998
   */
  public function startTransaction($name = '') {
    $class = $this->getDriverClass('Transaction');
    return new $class($this, $name);
  }

  /**
   * Rolls back the transaction entirely or to a named savepoint.
   *
   * This method throws an exception if no transaction is active.
   *
999 1000 1001
   * @param string $savepoint_name
   *   (optional) The name of the savepoint. The default, 'drupal_transaction',
   *    will roll the entire transaction back.
1002
   *
1003
   * @throws \Drupal\Core\Database\TransactionOutOfOrderException
1004
   * @throws \Drupal\Core\Database\TransactionNoActiveException
1005
   *
1006
   * @see \Drupal\Core\Database\Transaction::rollback()
1007 1008 1009 1010 1011 1012
   */
  public function rollback($savepoint_name = 'drupal_transaction') {
    if (!$this->supportsTransactions()) {
      return;
    }
    if (!$this->inTransaction()) {
1013
      throw new TransactionNoActiveException();
1014 1015
    }
    // A previous rollback to an earlier savepoint may mean that the savepoint
Crell's avatar
Crell committed
1016 1017
    // in question has already been accidentally committed.
    if (!isset($this->transactionLayers[$savepoint_name])) {
1018
      throw new TransactionNoActiveException();
1019
    }
1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035

    // We need to find the point we're rolling back to, all other savepoints
    // before are no longer needed. If we rolled back other active savepoints,
    // we need to throw an exception.
    $rolled_back_other_active_savepoints = FALSE;
    while ($savepoint = array_pop($this->transactionLayers)) {
      if ($savepoint == $savepoint_name) {
        // If it is the last the transaction in the stack, then it is not a
        // savepoint, it is the transaction itself so we will need to roll back
        // the transaction rather than a savepoint.
        if (empty($this->transactionLayers)) {
          break;
        }
        $this->query('ROLLBACK TO SAVEPOINT ' . $savepoint);
        $this->popCommittableTransactions();
        if ($rolled_back_other_active_savepoints) {
1036
          throw new TransactionOutOfOrderException();
1037 1038 1039 1040 1041 1042 1043
        }
        return;
      }
      else {
        $rolled_back_other_active_savepoints = TRUE;
      }
    }
1044
    $this->connection->rollBack();
1045
    if ($rolled_back_other_active_savepoints) {
1046
      throw new TransactionOutOfOrderException();
1047 1048 1049 1050 1051 1052 1053 1054
    }
  }

  /**
   * Increases the depth of transaction nesting.
   *
   * If no transaction is already active, we begin a new transaction.
   *
1055 1056 1057
   * @param string $name
   *   The name of the transaction.
   *
1058
   * @throws \Drupal\Core\Database\TransactionNameNonUniqueException
1059
   *
1060
   * @see \Drupal\Core\Database\Transaction
1061 1062 1063 1064 1065 1066
   */
  public function pushTransaction($name) {
    if (!$this->supportsTransactions()) {
      return;
    }
    if (isset($this->transactionLayers[$name])) {
1067
      throw new TransactionNameNonUniqueException($name . " is already in use.");
1068 1069 1070 1071 1072 1073 1074
    }
    // If we're already in a transaction then we want to create a savepoint
    // rather than try to create another transaction.
    if ($this->inTransaction()) {
      $this->query('SAVEPOINT ' . $name);
    }
    else {
1075
      $this->connection->beginTransaction();
1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086
    }
    $this->transactionLayers[$name] = $name;
  }

  /**
   * Decreases the depth of transaction nesting.
   *
   * If we pop off the last transaction layer, then we either commit or roll
   * back the transaction as necessary. If no transaction is active, we return
   * because the transaction may have manually been rolled back.
   *
1087 1088
   * @param string $name
   *   The name of the savepoint.
1089
   *
1090 1091
   * @throws \Drupal\Core\Database\TransactionNoActiveException
   * @throws \Drupal\Core\Database\TransactionCommitFailedException
1092
   *
1093
   * @see \Drupal\Core\Database\Transaction
1094 1095 1096 1097 1098
   */
  public function popTransaction($name) {
    if (!$this->supportsTransactions()) {
      return;
    }
Crell's avatar
Crell committed
1099 1100 1101 1102
    // The transaction has already been committed earlier. There is nothing we
    // need to do. If this transaction was part of an earlier out-of-order
    // rollback, an exception would already have been thrown by
    // Database::rollback().
1103
    if (!isset($this->transactionLayers[$name])) {
Crell's avatar
Crell committed
1104
      return;
1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125
    }

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

  /**
   * Internal function: commit all the transaction layers that can commit.
   */
  protected function popCommittableTransactions() {
    // Commit all the committable layers.
    foreach (array_reverse($this->transactionLayers) as $name => $active) {
      // Stop once we found an active transaction.
      if ($active) {
        break;
      }

      // If there are no more layers left then we should commit.
      unset($this->transactionLayers[$name]);
      if (empty($this->transactionLayers)) {
1126
        if (!$this->connection->commit()) {
1127
          throw new TransactionCommitFailedException();
1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143
        }
      }
      else {
        $this->query('RELEASE SAVEPOINT ' . $name);
      }
    }
  }

  /**
   * Runs a limited-range query on this database object.
   *
   * Use this as a substitute for ->query() when a subset of the query is to be
   * returned. User-supplied arguments to the query should be passed in as
   * separate parameters so that they can be properly escaped to avoid SQL
   * injection attacks.
   *
1144
   * @param string $query
1145
   *   A string containing an SQL query.
1146
   * @param int $from
1147
   *   The first result row to return.
1148
   * @param int $count
1149
   *   The maximum number of result rows to return.
1150 1151 1152 1153 1154
   * @param array $args
   *   (optional) An array of values to substitute into the query at placeholder
   *    markers.
   * @param array $options
   *   (optional) An array of options on the query.
1155
   *
1156
   * @return \Drupal\Core\Database\StatementInterface
1157 1158 1159 1160 1161 1162 1163 1164
   *   A database query result resource, or NULL if the query was not executed
   *   correctly.
   */
  abstract public function queryRange($query, $from, $count, array $args = array(), array $options = array());

  /**
   * Generates a temporary table name.
   *
1165
   * @return string
1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183
   *   A table name.
   */
  protected function generateTemporaryTableName() {
    return "db_temporary_" . $this->temporaryNameIndex++;
  }

  /**
   * Runs a SELECT query and stores its results in a temporary table.
   *
   * Use this as a substitute for ->query() when the results need to stored
   * in a temporary table. Temporary tables exist for the duration of the page
   * request. User-supplied arguments to the query should be passed in as
   * separate parameters so that they can be properly escaped to avoid SQL
   * injection attacks.
   *
   * Note that if you need to know how many results were returned, you should do
   * a SELECT COUNT(*) on the temporary table afterwards.
   *
1184
   * @param string $query
1185
   *   A string containing a normal SELECT SQL query.
1186 1187 1188 1189 1190 1191 1192
   * @param array $args
   *   (optional) An array of values to substitute into the query at placeholder
   *   markers.
   * @param array $options
   *   (optional) An associative array of options to control how the query is
   *   run. See the documentation for DatabaseConnection::defaultOptions() for
   *   details.
1193
   *
1194
   * @return string
1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205
   *   The name of the temporary table.
   */
  abstract function queryTemporary($query, array $args = array(), array $options = array());

  /**
   * Returns the type of database driver.
   *
   * This is not necessarily the same as the type of the database itself. For
   * instance, there could be two MySQL drivers, mysql and mysql_mock. This
   * function would return different values for each, but both would return
   * "mysql" for databaseType().
1206 1207 1208
   *
   * @return string
   *   The type of database driver.
1209 1210 1211 1212 1213 1214 1215
   */
  abstract public function driver();

  /**
   * Returns the version of the database server.
   */
  public function version() {
1216
    return $this->connection->getAttribute(\PDO::ATTR_SERVER_VERSION);
1217 1218 1219 1220 1221
  }

  /**
   * Determines if this driver supports transactions.
   *
1222
   * @return bool
1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233
   *   TRUE if this connection supports transactions, FALSE otherwise.
   */
  public function supportsTransactions() {
    return $this->transactionSupport;
  }

  /**
   * Determines if this driver supports transactional DDL.
   *
   * DDL queries are those that change the schema, such as ALTER queries.
   *
1234
   * @return bool
1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246
   *   TRUE if this connection supports transactions for DDL queries, FALSE
   *   otherwise.
   */
  public function supportsTransactionalDDL() {
    return $this->transactionalDDLSupport;
  }

  /**
   * Returns the name of the PDO driver for this connection.
   */
  abstract public function databaseType();

1247 1248 1249 1250 1251 1252 1253 1254 1255 1256
  /**
   * Creates a database.
   *
   * In order to use this method, you must be connected without a database
   * specified.
   *
   * @param string $database
   *   The name of the database to create.
   */
  abstract public function createDatabase($database);
1257 1258 1259 1260 1261 1262 1263 1264 1265

  /**
   * Gets any special processing requirements for the condition operator.
   *
   * Some condition types require special processing, such as IN, because
   * the value data they pass in is not a simple value. This is a simple
   * overridable lookup function. Database connections should define only
   * those operators they wish to be handled differently than the default.
   *
1266
   * @param string $operator
1267 1268 1269 1270 1271
   *   The condition operator, such as "IN", "BETWEEN", etc. Case-sensitive.
   *
   * @return
   *   The extra handling directives for the specified operator, or NULL.
   *
1272
   * @see \Drupal\Core\Database\Query\Condition::compile()
1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283
   */
  abstract public function mapConditionOperator($operator);

  /**
   * Throws an exception to deny direct access to transaction commits.
   *
   * We do not want to allow users to commit transactions at any time, only
   * by destroying the transaction object or allowing it to go out of scope.
   * A direct commit bypasses all of the safety checks we've built on top of
   * PDO's transaction routines.
   *
1284
   * @throws \Drupal\Core\Database\TransactionExplicitCommitNotAllowedException
1285
   *
1286
   * @see \Drupal\Core\Database\Transaction
1287 1288
   */
  public function commit() {
1289
    throw new TransactionExplicitCommitNotAllowedException();
1290 1291 1292
  }

  /**
1293
   * Retrieves an unique ID from a given sequence.
1294 1295 1296 1297 1298 1299 1300
   *
   * Use this function if for some reason you can't use a serial field. For
   * example, MySQL has no ways of reading of the current value of a sequence
   * and PostgreSQL can not advance the sequence to be larger than a given
   * value. Or sometimes you just need a unique integer.
   *
   * @param $existing_id
1301 1302 1303
   *   (optional) After a database import, it might be that the sequences table
   *   is behind, so by passing in the maximum existing ID, it can be assured
   *   that we never issue the same ID.
1304 1305 1306 1307 1308 1309
   *
   * @return
   *   An integer number larger than any number returned by earlier calls and
   *   also larger than the $existing_id if one was passed in.
   */
  abstract public function nextId($existing_id = 0);
1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360

  /**
   * Prepares a statement for execution and returns a statement object
   *
   * Emulated prepared statements does not communicate with the database server
   * so this method does not check the statement.
   *
   * @param string $statement
   *   This must be a valid SQL statement for the target database server.
   * @param array $driver_options
   *   (optional) This array holds one or more key=>value pairs to set
   *   attribute values for the PDOStatement object that this method returns.
   *   You would most commonly use this to set the \PDO::ATTR_CURSOR value to
   *   \PDO::CURSOR_SCROLL to request a scrollable cursor. Some drivers have
   *   driver specific options that may be set at prepare-time. Defaults to an
   *   empty array.
   *
   * @return \PDOStatement|false
   *   If the database server successfully prepares the statement, returns a
   *   \PDOStatement object.
   *   If the database server cannot successfully prepare the statement  returns
   *   FALSE or emits \PDOException (depending on error handling).
   *
   * @throws \PDOException
   *
   * @see \PDO::prepare()
   */
  public function prepare($statement, array $driver_options = array()) {
    return $this->connection->prepare($statement, $driver_options);
  }

  /**
   * Quotes a string for use in a query.
   *
   * @param string $string
   *   The string to be quoted.
   * @param int $parameter_type
   *   (optional) Provides a data type hint for drivers that have alternate
   *   quoting styles. Defaults to \PDO::PARAM_STR.
   *
   * @return string|bool
   *   A quoted string that is theoretically safe to pass into an SQL statement.
   *   Returns FALSE if the driver does not support quoting in this way.
   *
   * @see \PDO::quote()
   */
  public function quote($string, $parameter_type = \PDO::PARAM_STR) {
    return $this->connection->quote($string, $parameter_type);
  }

  /**
1361
   * Prevents the database connection from being serialized.
1362
   */
1363 1364
  public function __sleep() {
    throw new \LogicException('The database connection is not serializable. This probably means you are serializing an object that has an indirect reference to the database connection. Adjust your code so that is not necessary. Alternatively, look at DependencySerializationTrait as a temporary solution.');
1365 1366
  }

1367
}