DrupalAPI.de

1. drupal
   1. drupal7

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.

Übergabeparameter

$query The query to execute. In most cases this will be a string containing an SQL query with placeholders. An already-prepared instance of DatabaseStatementInterface may also be passed in order to allow calling code to manually bind variables to a query. If a DatabaseStatementInterface is passed, the $args array will be ignored.

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.

$args 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.

$options An associative array of options to control how the query is run. See the documentation for DatabaseConnection::defaultOptions() for details.

Rückgabewert

This method will return one of: The executed statement, the number of rows affected by the query (not the number matched), or the generated insert id of the last query, depending on the value of $options['return']. Typically that value will be set by default or a query builder and should not be set by a user. If there is an error, this method will return NULL and may throw an exception if $options['throw_exception'] is TRUE.

Verwandte Themen

Database abstraction layer

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

Code

includes/database/database.inc, line 561

<?php
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.
    if ($query instanceof DatabaseStatementInterface) {
      $stmt = $query;
      $stmt->execute(NULL, $options);
    }
    else {
      $modified = $this->expandArguments($query, $args);
      $stmt = $this->prepareQuery($query, !$modified);
      $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:
        return $stmt->rowCount();
      case Database::RETURN_INSERT_ID:
        return $this->lastInsertId();
      case Database::RETURN_NULL:
        return;
      default:
        throw new PDOException('Invalid return directive: ' . $options['return']);
    }
  }
  catch (PDOException $e) {
    _db_check_install_needed();
    if ($options['throw_exception']) {
      if ($query instanceof DatabaseStatementInterface) {
        $query_string = $stmt->getQueryString();
      }
      else {
        $query_string = $query;
      }
      throw new PDOException($query_string . " - \n" . print_r($args, 1) . $e->getMessage());
    }
    return NULL;
  }
}
?>