function Connection::defaultOptions

Same name in other branches
  1. 8.9.x core/lib/Drupal/Core/Database/Connection.php \Drupal\Core\Database\Connection::defaultOptions()
  2. 10 core/lib/Drupal/Core/Database/Connection.php \Drupal\Core\Database\Connection::defaultOptions()
  3. 11.x core/lib/Drupal/Core/Database/Connection.php \Drupal\Core\Database\Connection::defaultOptions()

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:

  • 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: (deprecated) 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 found (matched) by the WHERE clause of an UPDATE or DELETE query (not the number of rows actually changed). Note that although named RETURN_AFFECTED for historical reasons, the number of rows matched is returned for consistency across database engines.
    • 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: (deprecated) 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.
  • allow_delimiter_in_query: By default, queries which have the ; delimiter any place in them will cause an exception. This reduces the chance of SQL injection attacks that terminate the original query and add one or more additional queries (such as inserting new user accounts). In rare cases, such as creating an SQL function, a ; is needed and can be allowed by changing this option to TRUE.
  • allow_square_brackets: By default, queries which contain square brackets will have them replaced with the identifier quote character for the database type. In rare cases, such as creating an SQL function, [] characters might be needed and can be allowed by changing this option to TRUE.
  • pdo: By default, queries will execute with the client connection options set on the connection. In particular cases, it could be necessary to override the driver options on the statement level. In such case, pass the required setting as an array here, and they will be passed to the prepared statement.

Return value

array An array of default query options.

2 calls to Connection::defaultOptions()
Connection::query in core/modules/pgsql/src/Driver/Database/pgsql/Connection.php
Executes a query string against the database.
Connection::query in core/lib/Drupal/Core/Database/Connection.php
Executes a query string against the database.

File

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

Class

Connection
Base Database API class.

Namespace

Drupal\Core\Database

Code

protected function defaultOptions() {
    return [
        'fetch' => \PDO::FETCH_OBJ,
        'allow_delimiter_in_query' => FALSE,
        'allow_square_brackets' => FALSE,
        'pdo' => [],
    ];
}

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