Commit fcd75dd0 authored by Nathaniel Catchpole's avatar Nathaniel Catchpole
Browse files

Issue #3248575 by mfb, xjm: Documentation conflict re: affected rows vs. matched rows

parent e1e56ac4
......@@ -287,9 +287,11 @@ public function __destruct() {
* 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 affected by an
* UPDATE or DELETE query. Be aware that means the number of rows actually
* changed, not the number of rows matched by the WHERE clause.
* - 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.
......@@ -747,8 +749,8 @@ protected function filterComment($comment = '') {
* $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).
* 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.
......
......@@ -38,7 +38,7 @@ abstract class Database {
const RETURN_STATEMENT = 1;
/**
* Flag to indicate a query call should return the number of affected rows.
* Flag to indicate a query call should return the number of matched rows.
*
* @deprecated in drupal:9.4.0 and is removed from drupal:11.0.0. There is no
* replacement.
......
......@@ -9,7 +9,7 @@ class RowCountException extends \RuntimeException implements DatabaseException {
public function __construct($message = '', $code = 0, \Exception $previous = NULL) {
if (empty($message)) {
$message = "rowCount() is supported for DELETE, INSERT, or UPDATE statements performed with structured query builders only, since they would not be portable across database engines otherwise. If the query builders are not sufficient, use a prepareStatement() with an \$allow_row_count argument set to TRUE, execute() the Statement and get the number of affected rows via rowCount().";
$message = "rowCount() is supported for DELETE, INSERT, or UPDATE statements performed with structured query builders only, since they would not be portable across database engines otherwise. If the query builders are not sufficient, use a prepareStatement() with an \$allow_row_count argument set to TRUE, execute() the Statement and get the number of matched rows via rowCount().";
}
parent::__construct($message, $code, $previous);
}
......
......@@ -53,10 +53,10 @@ public function getQueryString();
public function getConnectionTarget(): string;
/**
* Returns the number of rows affected by the last SQL statement.
* Returns the number of rows matched by the last SQL statement.
*
* @return int
* The number of rows affected by the last DELETE, INSERT, or UPDATE
* The number of rows matched by the last DELETE, INSERT, or UPDATE
* statement executed or throws \Drupal\Core\Database\RowCountException
* if the last executed statement was SELECT.
*
......
......@@ -68,7 +68,7 @@ class StatementPrefetch implements \Iterator, StatementInterface {
protected $columnNames = NULL;
/**
* The number of rows affected by the last query.
* The number of rows matched by the last query.
*
* @var int
*/
......@@ -139,7 +139,7 @@ class StatementPrefetch implements \Iterator, StatementInterface {
* @param array $driver_options
* Driver-specific options.
* @param bool $row_count_enabled
* (optional) Enables counting the rows affected. Defaults to FALSE.
* (optional) Enables counting the rows matched. Defaults to FALSE.
*/
public function __construct(\PDO $pdo_connection, Connection $connection, $query, array $driver_options = [], bool $row_count_enabled = FALSE) {
$this->pdoConnection = $pdo_connection;
......
......@@ -44,7 +44,7 @@ class StatementWrapper implements \IteratorAggregate, StatementInterface {
* @param array $options
* Array of query options.
* @param bool $row_count_enabled
* (optional) Enables counting the rows affected. Defaults to FALSE.
* (optional) Enables counting the rows matched. Defaults to FALSE.
*/
public function __construct(Connection $connection, $client_connection, string $query, array $options, bool $row_count_enabled = FALSE) {
$this->connection = $connection;
......
......@@ -15,7 +15,7 @@ class RowCountExceptionTest extends UnitTestCase {
/**
* The default exception message.
*/
private const DEFAULT_EXCEPTION_MESSAGE = "rowCount() is supported for DELETE, INSERT, or UPDATE statements performed with structured query builders only, since they would not be portable across database engines otherwise. If the query builders are not sufficient, use a prepareStatement() with an \$allow_row_count argument set to TRUE, execute() the Statement and get the number of affected rows via rowCount().";
private const DEFAULT_EXCEPTION_MESSAGE = "rowCount() is supported for DELETE, INSERT, or UPDATE statements performed with structured query builders only, since they would not be portable across database engines otherwise. If the query builders are not sufficient, use a prepareStatement() with an \$allow_row_count argument set to TRUE, execute() the Statement and get the number of matched rows via rowCount().";
/**
* Data provider for ::testExceptionMessage()
......
Supports Markdown
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