diff --git a/core/lib/Drupal/Core/Database/Connection.php b/core/lib/Drupal/Core/Database/Connection.php index 7c4240202da68e6c74f39042d1c3655e3273caf9..33d033744c10b5156fa81b769e6997d00cd6b718 100644 --- a/core/lib/Drupal/Core/Database/Connection.php +++ b/core/lib/Drupal/Core/Database/Connection.php @@ -24,7 +24,7 @@ abstract class Connection { * * We need this information for later auditing and logging. * - * @var string + * @var string|null */ protected $target = NULL; @@ -35,14 +35,14 @@ abstract class Connection { * connection can be a single server or a cluster of primary and replicas * (use target to pick between primary and replica). * - * @var string + * @var string|null */ protected $key = NULL; /** * The current database logging object for this connection. * - * @var Log + * @var \Drupal\Core\Database\Log|null */ protected $logger = NULL; @@ -111,7 +111,9 @@ abstract class Connection { /** * The schema object for this connection. * - * @var object + * Set to NULL when the schema is destroyed. + * + * @var \Drupal\Core\Database\Schema|null */ protected $schema = NULL; @@ -138,6 +140,14 @@ abstract class Connection { /** * Constructs a Connection object. + * + * @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. */ public function __construct(\PDO $connection, array $connection_options) { // Initialize and prepare the connection prefix. @@ -221,7 +231,7 @@ public function destroy() { * that behavior and simply return NULL on failure, set this option to * FALSE. * - * @return + * @return array * An array of default query options. */ protected function defaultOptions() { @@ -241,7 +251,7 @@ protected function defaultOptions() { * is for requesting the connection information of this specific * open connection object. * - * @return + * @return array * An array of the connection information. The exact list of * properties is driver-dependent. */ @@ -252,9 +262,9 @@ public function getConnectionOptions() { /** * Set the list of prefixes used by this database connection. * - * @param $prefix - * The prefixes, in any of the multiple forms documented in - * default.settings.php. + * @param array|string $prefix + * Either a single prefix, or an array of prefixes, in any of the multiple + * forms documented in default.settings.php. */ protected function setPrefix($prefix) { if (is_array($prefix)) { @@ -289,10 +299,10 @@ protected function setPrefix($prefix) { * tables, allowing Drupal to coexist with other systems in the same database * and/or schema if necessary. * - * @param $sql + * @param string $sql * A string containing a partial or entire SQL query. * - * @return + * @return string * The properly-prefixed string. */ public function prefixTables($sql) { @@ -304,6 +314,9 @@ public function prefixTables($sql) { * * This function is for when you want to know the prefix of a table. This * is not used in prefixTables due to performance reasons. + * + * @param string $table + * (optional) The table to find the prefix for. */ public function tablePrefix($table = 'default') { if (isset($this->prefixes[$table])) { @@ -355,9 +368,8 @@ public function prepareQuery($query) { * signature. We therefore also ensure that this function is only ever * called once. * - * @param $target - * The target this connection is for. Set to NULL (default) to disable - * logging entirely. + * @param string $target + * (optional) The target this connection is for. */ public function setTarget($target = NULL) { if (!isset($this->target)) { @@ -368,8 +380,8 @@ public function setTarget($target = NULL) { /** * Returns the target this connection is associated with. * - * @return - * The target string of this connection. + * @return string|null + * The target string of this connection, or NULL if no target is set. */ public function getTarget() { return $this->target; @@ -378,7 +390,7 @@ public function getTarget() { /** * Tells this connection object what its key is. * - * @param $target + * @param string $key * The key this connection is for. */ public function setKey($key) { @@ -390,8 +402,8 @@ public function setKey($key) { /** * Returns the key this connection is associated with. * - * @return - * The key of this connection. + * @return string|null + * The key of this connection, or NULL if no key is set. */ public function getKey() { return $this->key; @@ -400,7 +412,7 @@ public function getKey() { /** * Associates a logging object with this connection. * - * @param $logger + * @param \Drupal\Core\Database\Log $logger * The logging object we want to use. */ public function setLogger(Log $logger) { @@ -410,7 +422,7 @@ public function setLogger(Log $logger) { /** * Gets the current logging object for this connection. * - * @return \Drupal\Core\Database\Log + * @return \Drupal\Core\Database\Log|null * The current logging object for this connection. If there isn't one, * NULL is returned. */ @@ -424,12 +436,12 @@ public function getLogger() { * This information is exposed to all database drivers, although it is only * useful on some of them. This method is table prefix-aware. * - * @param $table + * @param string $table * The table name to use for the sequence. - * @param $field + * @param string $field * The field name to use for the sequence. * - * @return + * @return string * A table prefix-parsed string for the sequence name. */ public function makeSequenceName($table, $field) { @@ -441,10 +453,10 @@ public function makeSequenceName($table, $field) { * * The comment string will be sanitized to avoid SQL injection attacks. * - * @param $comments + * @param string[] $comments * An array of query comment strings. * - * @return + * @return string * A sanitized comment string. */ public function makeComment($comments) { @@ -483,10 +495,10 @@ public function makeComment($comments) { * Unless the comment is sanitised first, the SQL server would drop the * node table and ignore the rest of the SQL statement. * - * @param $comment + * @param string $comment * A query comment string. * - * @return + * @return string * A sanitized version of the query comment string. */ protected function filterComment($comment = '') { @@ -500,7 +512,7 @@ protected function filterComment($comment = '') { * query. All queries executed by Drupal are executed as PDO prepared * statements. * - * @param $query + * @param string|\Drupal\Core\Database\StatementInterface $query * The query to execute. In most cases this will be a string containing * an SQL query with placeholders. An already-prepared instance of * StatementInterface may also be passed in order to allow calling @@ -509,26 +521,36 @@ protected function filterComment($comment = '') { * 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. - * @param $args + * @param array $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. - * @param $options - * An associative array of options to control how the query is run. See - * the documentation for DatabaseConnection::defaultOptions() for details. + * @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. * * @return \Drupal\Core\Database\StatementInterface|int|null - * 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. + * 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. * * @throws \Drupal\Core\Database\DatabaseExceptionWrapper * @throws \Drupal\Core\Database\IntegrityConstraintViolationException * @throws \InvalidArgumentException + * + * @see \Drupal\Core\Database\Connection::defaultOptions() */ public function query($query, array $args = array(), $options = array()) { // Use default values if not already set. @@ -628,6 +650,13 @@ protected function handleQueryException(\PDOException $e, $query, array $args = * * @return bool * TRUE if the query was modified, FALSE otherwise. + * + * @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. */ protected function expandArguments(&$query, &$args) { $modified = FALSE; @@ -700,12 +729,12 @@ public function getDriverClass($class) { /** * Prepares and returns a SELECT query object. * - * @param $table + * @param string $table * 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. - * @param $alias - * The alias of the base table of this query. + * @param string $alias + * (optional) The alias of the base table of this query. * @param $options * An array of options on the query. * @@ -724,8 +753,10 @@ public function select($table, $alias = NULL, array $options = array()) { /** * Prepares and returns an INSERT query object. * - * @param $options - * An array of options on the query. + * @param string $table + * The table to use for the insert statement. + * @param array $options + * (optional) An array of options on the query. * * @return \Drupal\Core\Database\Query\Insert * A new Insert query object. @@ -740,8 +771,10 @@ public function insert($table, array $options = array()) { /** * Prepares and returns a MERGE query object. * - * @param $options - * An array of options on the query. + * @param string $table + * The table to use for the merge statement. + * @param array $options + * (optional) An array of options on the query. * * @return \Drupal\Core\Database\Query\Merge * A new Merge query object. @@ -757,8 +790,10 @@ public function merge($table, array $options = array()) { /** * Prepares and returns an UPDATE query object. * - * @param $options - * An array of options on the query. + * @param string $table + * The table to use for the update statement. + * @param array $options + * (optional) An array of options on the query. * * @return \Drupal\Core\Database\Query\Update * A new Update query object. @@ -773,8 +808,10 @@ public function update($table, array $options = array()) { /** * Prepares and returns a DELETE query object. * - * @param $options - * An array of options on the query. + * @param string $table + * The table to use for the delete statement. + * @param array $options + * (optional) An array of options on the query. * * @return \Drupal\Core\Database\Query\Delete * A new Delete query object. @@ -789,8 +826,10 @@ public function delete($table, array $options = array()) { /** * Prepares and returns a TRUNCATE query object. * - * @param $options - * An array of options on the query. + * @param string $table + * The table to use for the truncate statement. + * @param array $options + * (optional) An array of options on the query. * * @return \Drupal\Core\Database\Query\Truncate * A new Truncate query object. @@ -825,8 +864,11 @@ public function schema() { * For some database drivers, it may also wrap the database name in * database-specific escape characters. * + * @param string $database + * An unsanitized database name. + * * @return string - * The sanitized database name string. + * The sanitized database name. */ public function escapeDatabase($database) { return preg_replace('/[^A-Za-z0-9_.]+/', '', $database); @@ -839,8 +881,11 @@ public function escapeDatabase($database) { * For some database drivers, it may also wrap the table name in * database-specific escape characters. * - * @return - * The sanitized table name string. + * @param string $table + * An unsanitized table name. + * + * @return string + * The sanitized table name. */ public function escapeTable($table) { return preg_replace('/[^A-Za-z0-9_.]+/', '', $table); @@ -853,8 +898,11 @@ public function escapeTable($table) { * For some database drivers, it may also wrap the field name in * database-specific escape characters. * - * @return - * The sanitized field name string. + * @param string $field + * An unsanitized field name. + * + * @return string + * The sanitized field name. */ public function escapeField($field) { return preg_replace('/[^A-Za-z0-9_.]+/', '', $field); @@ -868,8 +916,11 @@ public function escapeField($field) { * DatabaseConnection::escapeTable(), this doesn't allow the period (".") * because that is not allowed in aliases. * - * @return - * The sanitized field name string. + * @param string $field + * An unsanitized alias name. + * + * @return string + * The sanitized alias name. */ public function escapeAlias($field) { return preg_replace('/[^A-Za-z0-9_]+/', '', $field); @@ -894,10 +945,10 @@ public function escapeAlias($field) { * Backslash is defined as escape character for LIKE patterns in * Drupal\Core\Database\Query\Condition::mapConditionOperator(). * - * @param $string + * @param string $string * The string to escape. * - * @return + * @return string * The escaped string. */ public function escapeLike($string) { @@ -907,7 +958,7 @@ public function escapeLike($string) { /** * Determines if there is an active transaction open. * - * @return + * @return bool * TRUE if we're currently in a transaction, FALSE otherwise. */ public function inTransaction() { @@ -915,7 +966,10 @@ public function inTransaction() { } /** - * Determines current transaction depth. + * Determines the current transaction depth. + * + * @return int + * The current transaction depth. */ public function transactionDepth() { return count($this->transactionLayers); @@ -924,8 +978,8 @@ public function transactionDepth() { /** * Returns a new DatabaseTransaction object on this connection. * - * @param $name - * Optional name of the savepoint. + * @param string $name + * (optional) The name of the savepoint. * * @return \Drupal\Core\Database\Transaction * A Transaction object. @@ -942,10 +996,11 @@ public function startTransaction($name = '') { * * This method throws an exception if no transaction is active. * - * @param $savepoint_name - * The name of the savepoint. The default, 'drupal_transaction', will roll - * the entire transaction back. + * @param string $savepoint_name + * (optional) The name of the savepoint. The default, 'drupal_transaction', + * will roll the entire transaction back. * + * @throws \Drupal\Core\Database\TransactionOutOfOrderException * @throws \Drupal\Core\Database\TransactionNoActiveException * * @see \Drupal\Core\Database\Transaction::rollback() @@ -997,6 +1052,9 @@ public function rollback($savepoint_name = 'drupal_transaction') { * * If no transaction is already active, we begin a new transaction. * + * @param string $name + * The name of the transaction. + * * @throws \Drupal\Core\Database\TransactionNameNonUniqueException * * @see \Drupal\Core\Database\Transaction @@ -1026,8 +1084,8 @@ public function pushTransaction($name) { * back the transaction as necessary. If no transaction is active, we return * because the transaction may have manually been rolled back. * - * @param $name - * The name of the savepoint + * @param string $name + * The name of the savepoint. * * @throws \Drupal\Core\Database\TransactionNoActiveException * @throws \Drupal\Core\Database\TransactionCommitFailedException @@ -1083,16 +1141,17 @@ protected function popCommittableTransactions() { * separate parameters so that they can be properly escaped to avoid SQL * injection attacks. * - * @param $query + * @param string $query * A string containing an SQL query. - * @param $args - * An array of values to substitute into the query at placeholder markers. - * @param $from + * @param int $from * The first result row to return. - * @param $count + * @param int $count * The maximum number of result rows to return. - * @param $options - * An array of options on the query. + * @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. * * @return \Drupal\Core\Database\StatementInterface * A database query result resource, or NULL if the query was not executed @@ -1103,7 +1162,7 @@ abstract public function queryRange($query, $from, $count, array $args = array() /** * Generates a temporary table name. * - * @return + * @return string * A table name. */ protected function generateTemporaryTableName() { @@ -1122,15 +1181,17 @@ protected function generateTemporaryTableName() { * Note that if you need to know how many results were returned, you should do * a SELECT COUNT(*) on the temporary table afterwards. * - * @param $query + * @param string $query * A string containing a normal SELECT SQL query. - * @param $args - * An array of values to substitute into the query at placeholder markers. - * @param $options - * An associative array of options to control how the query is run. See - * the documentation for DatabaseConnection::defaultOptions() for details. + * @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. * - * @return + * @return string * The name of the temporary table. */ abstract function queryTemporary($query, array $args = array(), array $options = array()); @@ -1142,6 +1203,9 @@ abstract function queryTemporary($query, array $args = array(), array $options = * 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(). + * + * @return string + * The type of database driver. */ abstract public function driver(); @@ -1155,7 +1219,7 @@ public function version() { /** * Determines if this driver supports transactions. * - * @return + * @return bool * TRUE if this connection supports transactions, FALSE otherwise. */ public function supportsTransactions() { @@ -1167,7 +1231,7 @@ public function supportsTransactions() { * * DDL queries are those that change the schema, such as ALTER queries. * - * @return + * @return bool * TRUE if this connection supports transactions for DDL queries, FALSE * otherwise. */ @@ -1199,7 +1263,7 @@ abstract public function createDatabase($database); * overridable lookup function. Database connections should define only * those operators they wish to be handled differently than the default. * - * @param $operator + * @param string $operator * The condition operator, such as "IN", "BETWEEN", etc. Case-sensitive. * * @return @@ -1226,7 +1290,7 @@ public function commit() { } /** - * Retrieves an unique id from a given sequence. + * Retrieves an unique ID from a given sequence. * * 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 @@ -1234,9 +1298,9 @@ public function commit() { * value. Or sometimes you just need a unique integer. * * @param $existing_id - * 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. + * (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. * * @return * An integer number larger than any number returned by earlier calls and