function Connection::prepareStatement

Same name in this branch
  1. 9 core/modules/sqlite/src/Driver/Database/sqlite/Connection.php \Drupal\sqlite\Driver\Database\sqlite\Connection::prepareStatement()
  2. 9 core/modules/pgsql/src/Driver/Database/pgsql/Connection.php \Drupal\pgsql\Driver\Database\pgsql\Connection::prepareStatement()
Same name in other branches
  1. 10 core/modules/sqlite/src/Driver/Database/sqlite/Connection.php \Drupal\sqlite\Driver\Database\sqlite\Connection::prepareStatement()
  2. 10 core/modules/pgsql/src/Driver/Database/pgsql/Connection.php \Drupal\pgsql\Driver\Database\pgsql\Connection::prepareStatement()
  3. 10 core/lib/Drupal/Core/Database/Connection.php \Drupal\Core\Database\Connection::prepareStatement()
  4. 11.x core/modules/sqlite/src/Driver/Database/sqlite/Connection.php \Drupal\sqlite\Driver\Database\sqlite\Connection::prepareStatement()
  5. 11.x core/modules/pgsql/src/Driver/Database/pgsql/Connection.php \Drupal\pgsql\Driver\Database\pgsql\Connection::prepareStatement()
  6. 11.x core/lib/Drupal/Core/Database/Connection.php \Drupal\Core\Database\Connection::prepareStatement()

Returns a prepared statement given a SQL string.

This method caches prepared statements, reusing them when possible. It also prefixes tables names enclosed in curly braces and, optionally, quotes identifiers enclosed in square brackets.

Parameters

string $query: The query string as SQL, with curly braces surrounding the table names, and square brackets surrounding identifiers.

array $options: An associative array of options to control how the query is run. See the documentation for self::defaultOptions() for details. The content of the 'pdo' key will be passed to the prepared statement.

bool $allow_row_count: (optional) A flag indicating if row count is allowed on the statement object. Defaults to FALSE.

Return value

\Drupal\Core\Database\StatementInterface A prepared statement ready for its execute() method.

Throws

\InvalidArgumentException If multiple statements are included in the string, and delimiters are not allowed in the query.

\Drupal\Core\Database\DatabaseExceptionWrapper

3 calls to Connection::prepareStatement()
Connection::prepareQuery in core/lib/Drupal/Core/Database/Connection.php
Prepares a query string and returns the prepared statement.
Connection::prepareStatement in core/modules/pgsql/src/Driver/Database/pgsql/Connection.php
Returns a prepared statement given a SQL string.
Connection::query in core/lib/Drupal/Core/Database/Connection.php
Executes a query string against the database.
2 methods override Connection::prepareStatement()
Connection::prepareStatement in core/modules/sqlite/src/Driver/Database/sqlite/Connection.php
Returns a prepared statement given a SQL string.
Connection::prepareStatement in core/modules/pgsql/src/Driver/Database/pgsql/Connection.php
Returns a prepared statement given a SQL string.

File

core/lib/Drupal/Core/Database/Connection.php, line 619

Class

Connection
Base Database API class.

Namespace

Drupal\Core\Database

Code

public function prepareStatement(string $query, array $options, bool $allow_row_count = FALSE) : StatementInterface {
    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);
    }
    try {
        $query = $this->preprocessStatement($query, $options);
        // @todo in Drupal 10, only return the StatementWrapper.
        // @see https://www.drupal.org/node/3177490
        $statement = $this->statementWrapperClass ? new $this->statementWrapperClass($this, $this->connection, $query, $options['pdo'] ?? [], $allow_row_count) : $this->connection
            ->prepare($query, $options['pdo'] ?? []);
    } catch (\Exception $e) {
        $this->exceptionHandler()
            ->handleStatementException($e, $query, $options);
    }
    // BC layer: $options['throw_exception'] = FALSE or a \PDO::prepare() call
    // returning false would lead to returning a value that fails the return
    // typehint. Throw an exception in that case.
    // @todo in Drupal 10, remove the check.
    if (!isset($statement) || !$statement instanceof StatementInterface) {
        throw new DatabaseExceptionWrapper("Statement preparation failure for query: {$query}");
    }
    return $statement;
}

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.