function Connection::query
Same name in this branch
- 9 core/modules/pgsql/src/Driver/Database/pgsql/Connection.php \Drupal\pgsql\Driver\Database\pgsql\Connection::query()
Same name in other branches
- 8.9.x core/lib/Drupal/Core/Database/Driver/mysql/Connection.php \Drupal\Core\Database\Driver\mysql\Connection::query()
- 8.9.x core/lib/Drupal/Core/Database/Driver/pgsql/Connection.php \Drupal\Core\Database\Driver\pgsql\Connection::query()
- 8.9.x core/lib/Drupal/Core/Database/Connection.php \Drupal\Core\Database\Connection::query()
- 10 core/modules/pgsql/src/Driver/Database/pgsql/Connection.php \Drupal\pgsql\Driver\Database\pgsql\Connection::query()
- 10 core/lib/Drupal/Core/Database/Connection.php \Drupal\Core\Database\Connection::query()
- 11.x core/modules/pgsql/src/Driver/Database/pgsql/Connection.php \Drupal\pgsql\Driver\Database\pgsql\Connection::query()
- 11.x core/lib/Drupal/Core/Database/Connection.php \Drupal\Core\Database\Connection::query()
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 prepared statements.
Parameters
string|\Drupal\Core\Database\StatementInterface|\PDOStatement $query: The query to execute. This is a string containing an SQL query with placeholders. (deprecated) An already-prepared instance of StatementInterface or of \PDOStatement may also be passed in order to allow calling code to manually bind variables to a query. In such cases, the content of 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.
array $args: The associative array of arguments for the prepared statement.
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.
Return value
\Drupal\Core\Database\StatementInterface|int|string|null 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 matched by the query (not the number affected).
- If $options['return'] === self::RETURN_INSERT_ID, returns the generated insert ID of the last query as a string.
- If $options['return'] === self::RETURN_NULL, returns NULL.
Throws
\Drupal\Core\Database\DatabaseExceptionWrapper
\Drupal\Core\Database\IntegrityConstraintViolationException
\InvalidArgumentException
See also
\Drupal\Core\Database\Connection::defaultOptions()
16 calls to Connection::query()
- Connection::attachDatabase in core/
modules/ sqlite/ src/ Driver/ Database/ sqlite/ Connection.php - Allows the connection to access additional databases.
- Connection::handleQueryException in core/
modules/ sqlite/ src/ Driver/ Database/ sqlite/ Connection.php - Wraps and re-throws any PDO exception thrown by static::query().
- Connection::hasJson in core/
lib/ Drupal/ Core/ Database/ Connection.php - Runs a simple query to validate json datatype support.
- Connection::nextId in core/
modules/ mysql/ src/ Driver/ Database/ mysql/ Connection.php - Retrieves a unique ID from a given sequence.
- Connection::nextId in core/
modules/ sqlite/ src/ Driver/ Database/ sqlite/ Connection.php - Retrieves a unique ID from a given sequence.
1 method overrides Connection::query()
- Connection::query in core/
modules/ pgsql/ src/ Driver/ Database/ pgsql/ Connection.php - Executes a query string against the database.
File
-
core/
lib/ Drupal/ Core/ Database/ Connection.php, line 918
Class
- Connection
- Base Database API class.
Namespace
Drupal\Core\DatabaseCode
public function query($query, array $args = [], $options = []) {
// Use default values if not already set.
$options += $this->defaultOptions();
if (isset($options['return'])) {
@trigger_error('Passing "return" option to ' . __METHOD__ . '() is deprecated in drupal:9.4.0 and is removed in drupal:11.0.0. For data manipulation operations, use dynamic queries instead. See https://www.drupal.org/node/3185520', E_USER_DEPRECATED);
}
assert(!isset($options['target']), 'Passing "target" option to query() has no effect. See https://www.drupal.org/node/2993033');
// We allow either a pre-bound statement object (deprecated) or a literal
// string. In either case, we want to end up with an executed statement
// object, which we pass to StatementInterface::execute.
if (is_string($query)) {
$this->expandArguments($query, $args);
$stmt = $this->prepareStatement($query, $options);
}
elseif ($query instanceof StatementInterface) {
@trigger_error('Passing a StatementInterface object as a $query argument to ' . __METHOD__ . ' is deprecated in drupal:9.2.0 and is removed in drupal:10.0.0. Call the execute method from the StatementInterface object directly instead. See https://www.drupal.org/node/3154439', E_USER_DEPRECATED);
$stmt = $query;
}
elseif ($query instanceof \PDOStatement) {
@trigger_error('Passing a \\PDOStatement object as a $query argument to ' . __METHOD__ . ' is deprecated in drupal:9.2.0 and is removed in drupal:10.0.0. Call the execute method from the StatementInterface object directly instead. See https://www.drupal.org/node/3154439', E_USER_DEPRECATED);
$stmt = $query;
}
try {
if (is_string($query)) {
$stmt->execute($args, $options);
}
elseif ($query instanceof StatementInterface) {
$stmt->execute(NULL, $options);
}
elseif ($query instanceof \PDOStatement) {
$stmt->execute();
}
// Depending on the type of query we may need to return a different value.
// See DatabaseConnection::defaultOptions() for a description of each
// value.
// @todo the block below is deprecated and as of Drupal 11 will be
// removed, query() will only return a StatementInterface object.
// @see https://www.drupal.org/project/drupal/issues/3256524
switch ($options['return'] ?? Database::RETURN_STATEMENT) {
case Database::RETURN_STATEMENT:
return $stmt;
// Database::RETURN_AFFECTED should not be used; enable row counting
// by passing the appropriate argument to the constructor instead.
// @see https://www.drupal.org/node/3186368
case Database::RETURN_AFFECTED:
$stmt->allowRowCount = TRUE;
return $stmt->rowCount();
case Database::RETURN_INSERT_ID:
$sequence_name = $options['sequence_name'] ?? NULL;
return $this->lastInsertId($sequence_name);
case Database::RETURN_NULL:
return NULL;
default:
throw new \PDOException('Invalid return directive: ' . $options['return']);
}
} catch (\Exception $e) {
// 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().
if (is_string($query)) {
return $this->exceptionHandler()
->handleExecutionException($e, $stmt, $args, $options);
}
else {
return $this->handleQueryException($e, $query, $args, $options);
}
}
}
Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.