Commit 554f9a46 authored by alexpott's avatar alexpott

Issue #2342521 by JacobSanford, ecrown, dylanf, martin107, bburg, donquixote,...

Issue #2342521 by JacobSanford, ecrown, dylanf, martin107, bburg, donquixote, dcmul, jhodgdon, Crell, pcorbett: Docblock fixes for core/lib/Drupal/Core/Database/Connection.php
parent 6f964114
......@@ -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 @@ protected function popCommittableTransactions() {
/**
* 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 @@ protected function generateTemporaryTableName() {
* 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 @@ public function supportsTransactionalDDL() {
* 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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment