From 383b06f2d26b669c6ca18665a414f562f33f1947 Mon Sep 17 00:00:00 2001
From: catch <catch@35733.no-reply.drupal.org>
Date: Fri, 26 Jul 2019 11:17:02 +0100
Subject: [PATCH] Issue #2849745 by voleger, yogeshmpawar, gaurav.kapoor,
Berdir, Munavijayalakshmi, vacho, cilefen, daffie: Replace documentation
recommending db_*() wrappers
---
core/includes/database.inc | 37 ++++++++++---------
core/includes/form.inc | 2 +-
core/includes/pager.inc | 2 +-
.../Core/Database/Driver/pgsql/Select.php | 2 +-
.../Core/Database/Driver/sqlite/Schema.php | 2 +-
.../Database/Query/ConditionInterface.php | 2 +-
core/lib/Drupal/Core/Database/Schema.php | 6 +--
.../lib/Drupal/Core/Database/database.api.php | 5 +++
...NodeAccessLanguageAwareCombinationTest.php | 12 +++---
.../Kernel/NodeAccessLanguageAwareTest.php | 12 +++---
.../src/Kernel/NodeAccessLanguageTest.php | 12 +++---
.../Database/TemporaryQueryTest.php | 2 +-
.../Plugin/views/display/DefaultDisplay.php | 2 +-
.../Core/Database/RegressionTest.php | 2 +-
14 files changed, 54 insertions(+), 46 deletions(-)
diff --git a/core/includes/database.inc b/core/includes/database.inc
index 9f0f9939d74b..bd6e32572c36 100644
--- a/core/includes/database.inc
+++ b/core/includes/database.inc
@@ -21,11 +21,12 @@
* Executes an arbitrary query string against the active database.
*
* Use this function for SELECT queries if it is just a simple query string.
- * If the caller or other modules need to change the query, use db_select()
- * instead.
+ * If the caller or other modules need to change the query, use
+ * \Drupal::database()->select() instead.
*
* Do not use this function for INSERT, UPDATE, or DELETE queries. Those should
- * be handled via db_insert(), db_update() and db_delete() respectively.
+ * be handled via \Drupal::database()->insert(), \Drupal::database()->update(),
+ * \Drupal::database()->merge()and \Drupal::database()->delete().
*
* @param string|\Drupal\Core\Database\StatementInterface $query
* The prepared statement query to run. Although it will accept both named and
@@ -382,14 +383,15 @@ function db_escape_field($field) {
* a backslash. Use this to do a search for a verbatim string without any
* wildcard behavior.
*
- * You must use a query builder like db_select() in order to use db_like() on
- * all supported database systems. Using db_like() with db_query() or
- * db_query_range() is not supported.
+ * You must use a query builder like \Drupal::database()->select() in order to
+ * use \Drupal::database()->escapeLike() on all supported database systems. Using
+ * \Drupal::database()->escapeLike() with \Drupal::database()->query() or
+ * \Drupal::database()->queryRange() is not supported.
*
* For example, the following does a case-insensitive query for all rows whose
* name starts with $prefix:
* @code
- * $result = db_select('person', 'p')
+ * $result = \Drupal::database()->select('person', 'p')
* ->fields('p')
* ->condition('name', db_like($prefix) . '%', 'LIKE')
* ->execute()
@@ -1050,8 +1052,8 @@ function db_drop_index($table, $name) {
* recreate all indices and primary keys that are using the changed field.
*
* That means that you have to drop all affected keys and indexes with
- * db_drop_{primary_key,unique_key,index}() before calling
- * \Drupal\Core\Database\Schema::changeField().
+ * \Drupal::database()->schema()->drop{PrimaryKey,UniqueKey,Index}() before
+ * calling \Drupal\Core\Database\Schema::changeField().
* To recreate the keys and indices, pass the key definitions as the optional
* $keys_new argument directly to \Drupal\Core\Database\Schema::changeField().
*
@@ -1082,14 +1084,15 @@ function db_drop_index($table, $name) {
*
* On MySQL, all type 'serial' fields must be part of at least one key or index
* as soon as they are created. You cannot use
- * db_add_{primary_key,unique_key,index}() for this purpose because the ALTER
- * TABLE command will fail to add the column without a key or index
- * specification. The solution is to use the optional $keys_new argument to
- * create the key or index at the same time as field.
- *
- * You could use db_add_{primary_key,unique_key,index}() in all cases unless you
- * are converting a field to be type serial. You can use the $keys_new argument
- * in all cases.
+ * \Drupal::database()->schema()->add{PrimaryKey,UniqueKey,Index}() for this
+ * purpose because the ALTER TABLE command will fail to add the column without
+ * a key or index specification. The solution is to use the optional $keys_new
+ * argument to create the key or index at the same time as field.
+ *
+ * You could use
+ * \Drupal::database()->schema()->add{PrimaryKey,UniqueKey,Index}() in all
+ * cases unless you are converting a field to be type serial. You can use the
+ * $keys_new argument in all cases.
*
* @param $table
* Name of the table.
diff --git a/core/includes/form.inc b/core/includes/form.inc
index bd256ad16279..fefa9b3b872b 100644
--- a/core/includes/form.inc
+++ b/core/includes/form.inc
@@ -630,7 +630,7 @@ function template_preprocess_form_element_label(&$variables) {
* ->fetchField();
* }
* $limit = 5;
- * $result = db_select('example')
+ * $result = \Drupal::database()->select('example')
* ->fields('example', array('id'))
* ->condition('id', $context['sandbox']['current_id'], '>')
* ->orderBy('id')
diff --git a/core/includes/pager.inc b/core/includes/pager.inc
index 4c588419f66e..81daa34c6e53 100644
--- a/core/includes/pager.inc
+++ b/core/includes/pager.inc
@@ -50,7 +50,7 @@ function pager_find_page($element = 0) {
* can simply extend the query object with the 'PagerSelectExtender' extender
* before executing it. For example:
* @code
- * $query = db_select('some_table')
+ * $query = \Drupal::database()->select('some_table')
* ->extend('Drupal\Core\Database\Query\PagerSelectExtender');
* @endcode
*
diff --git a/core/lib/Drupal/Core/Database/Driver/pgsql/Select.php b/core/lib/Drupal/Core/Database/Driver/pgsql/Select.php
index e76cb0f9522e..2df730d6139c 100644
--- a/core/lib/Drupal/Core/Database/Driver/pgsql/Select.php
+++ b/core/lib/Drupal/Core/Database/Driver/pgsql/Select.php
@@ -30,7 +30,7 @@ public function orderRandom() {
* yet selected.
*
* @code
- * $query = db_select('example', 'e');
+ * $query = \Drupal::database()->select('example', 'e');
* $query->join('example_revision', 'er', 'e.vid = er.vid');
* $query
* ->distinct()
diff --git a/core/lib/Drupal/Core/Database/Driver/sqlite/Schema.php b/core/lib/Drupal/Core/Database/Driver/sqlite/Schema.php
index 51c8686c3831..c6f34c5c241f 100644
--- a/core/lib/Drupal/Core/Database/Driver/sqlite/Schema.php
+++ b/core/lib/Drupal/Core/Database/Driver/sqlite/Schema.php
@@ -157,7 +157,7 @@ protected function processField($field) {
* Create an SQL string for a field to be used in table creation or alteration.
*
* Before passing a field out of a schema definition into this function it has
- * to be processed by db_processField().
+ * to be processed by self::processField().
*
* @param $name
* Name of the field.
diff --git a/core/lib/Drupal/Core/Database/Query/ConditionInterface.php b/core/lib/Drupal/Core/Database/Query/ConditionInterface.php
index 12e99682b629..fe5140c2af42 100644
--- a/core/lib/Drupal/Core/Database/Query/ConditionInterface.php
+++ b/core/lib/Drupal/Core/Database/Query/ConditionInterface.php
@@ -30,7 +30,7 @@ interface ConditionInterface {
* Drupal considers LIKE case insensitive and the following is often used
* to tell the database that case insensitive equivalence is desired:
* @code
- * db_select('users')
+ * \Drupal::database()->select('users')
* ->condition('name', $injected_connection->escapeLike($name), 'LIKE')
* @endcode
* Use 'LIKE BINARY' instead of 'LIKE' for case sensitive queries.
diff --git a/core/lib/Drupal/Core/Database/Schema.php b/core/lib/Drupal/Core/Database/Schema.php
index f32d9fb289e7..ad5067789266 100644
--- a/core/lib/Drupal/Core/Database/Schema.php
+++ b/core/lib/Drupal/Core/Database/Schema.php
@@ -171,7 +171,7 @@ public function tableExists($table) {
$condition->compile($this->connection, $this);
// Normally, we would heartily discourage the use of string
// concatenation for conditionals like this however, we
- // couldn't use db_select() here because it would prefix
+ // couldn't use \Drupal::database()->select() here because it would prefix
// information_schema.tables and the query would fail.
// Don't use {} around information_schema.tables table.
return (bool) $this->connection->query("SELECT 1 FROM information_schema.tables WHERE " . (string) $condition, $condition->arguments())->fetchField();
@@ -198,7 +198,7 @@ public function findTables($table_expression) {
$tables = [];
// Normally, we would heartily discourage the use of string
// concatenation for conditionals like this however, we
- // couldn't use db_select() here because it would prefix
+ // couldn't use \Drupal::database()->select() here because it would prefix
// information_schema.tables and the query would fail.
// Don't use {} around information_schema.tables table.
$results = $this->connection->query("SELECT table_name as table_name FROM information_schema.tables WHERE " . (string) $condition, $condition->arguments());
@@ -253,7 +253,7 @@ public function fieldExists($table, $column) {
$condition->compile($this->connection, $this);
// Normally, we would heartily discourage the use of string
// concatenation for conditionals like this however, we
- // couldn't use db_select() here because it would prefix
+ // couldn't use \Drupal::database()->select() here because it would prefix
// information_schema.tables and the query would fail.
// Don't use {} around information_schema.columns table.
return (bool) $this->connection->query("SELECT 1 FROM information_schema.columns WHERE " . (string) $condition, $condition->arguments())->fetchField();
diff --git a/core/lib/Drupal/Core/Database/database.api.php b/core/lib/Drupal/Core/Database/database.api.php
index c39cf78cf4a9..82b6408669ae 100644
--- a/core/lib/Drupal/Core/Database/database.api.php
+++ b/core/lib/Drupal/Core/Database/database.api.php
@@ -93,6 +93,11 @@
* fields (see the @link entity_api Entity API topic @endlink for more on
* entity queries).
*
+ * Note: \Drupal::database() is used here as a shorthand way to get a reference
+ * to the database connection object. In most classes, you should use dependency
+ * injection and inject the 'database' service to perform queries. See
+ * @ref sec_connection below for details.
+ *
* The dynamic query API lets you build up a query dynamically using method
* calls. As an illustration, the query example from @ref sec_simple above
* would be:
diff --git a/core/modules/node/tests/src/Kernel/NodeAccessLanguageAwareCombinationTest.php b/core/modules/node/tests/src/Kernel/NodeAccessLanguageAwareCombinationTest.php
index b3a84d23ece0..6886f22db6d8 100644
--- a/core/modules/node/tests/src/Kernel/NodeAccessLanguageAwareCombinationTest.php
+++ b/core/modules/node/tests/src/Kernel/NodeAccessLanguageAwareCombinationTest.php
@@ -262,7 +262,7 @@ public function testNodeAccessLanguageAwareCombination() {
// Four nodes should be returned with public Hungarian translations or the
// no language public node.
- $this->assertEqual(count($nids), 4, 'db_select() returns 4 nodes when no langcode is specified.');
+ $this->assertEqual(count($nids), 4, 'Query returns 4 nodes when no langcode is specified.');
$this->assertTrue(array_key_exists($this->nodes['public_both_public']->id(), $nids), 'Returned node ID is full public node.');
$this->assertTrue(array_key_exists($this->nodes['public_ca_private']->id(), $nids), 'Returned node ID is Hungarian public only node.');
$this->assertTrue(array_key_exists($this->nodes['private_both_public']->id(), $nids), 'Returned node ID is both public non-language-aware private only node.');
@@ -277,7 +277,7 @@ public function testNodeAccessLanguageAwareCombination() {
$nids = $select->execute()->fetchAllAssoc('nid');
// Three nodes should be returned (with public Hungarian translations).
- $this->assertEqual(count($nids), 3, 'db_select() returns 3 nodes.');
+ $this->assertEqual(count($nids), 3, 'Query returns 3 nodes.');
$this->assertTrue(array_key_exists($this->nodes['public_both_public']->id(), $nids), 'Returned node ID is both public node.');
$this->assertTrue(array_key_exists($this->nodes['public_ca_private']->id(), $nids), 'Returned node ID is Hungarian public only node.');
$this->assertTrue(array_key_exists($this->nodes['private_both_public']->id(), $nids), 'Returned node ID is both public non-language-aware private only node.');
@@ -291,7 +291,7 @@ public function testNodeAccessLanguageAwareCombination() {
$nids = $select->execute()->fetchAllAssoc('nid');
// Three nodes should be returned (with public Catalan translations).
- $this->assertEqual(count($nids), 3, 'db_select() returns 3 nodes.');
+ $this->assertEqual(count($nids), 3, 'Query returns 3 nodes.');
$this->assertTrue(array_key_exists($this->nodes['public_both_public']->id(), $nids), 'Returned node ID is both public node.');
$this->assertTrue(array_key_exists($this->nodes['public_hu_private']->id(), $nids), 'Returned node ID is Catalan public only node.');
$this->assertTrue(array_key_exists($this->nodes['private_both_public']->id(), $nids), 'Returned node ID is both public non-language-aware private only node.');
@@ -305,7 +305,7 @@ public function testNodeAccessLanguageAwareCombination() {
$nids = $select->execute()->fetchAllAssoc('nid');
// There are no nodes with German translations, so no results are returned.
- $this->assertTrue(empty($nids), 'db_select() returns an empty result.');
+ $this->assertTrue(empty($nids), 'Query returns an empty result.');
// Query the nodes table as admin user (full access) with the node access
// tag and no specific langcode.
@@ -316,7 +316,7 @@ public function testNodeAccessLanguageAwareCombination() {
$nids = $select->execute()->fetchAllAssoc('nid');
// All nodes are returned.
- $this->assertEqual(count($nids), 10, 'db_select() returns all nodes.');
+ $this->assertEqual(count($nids), 10, 'Query returns all nodes.');
// Query the nodes table as admin user (full access) with the node access
// tag and langcode de.
@@ -329,7 +329,7 @@ public function testNodeAccessLanguageAwareCombination() {
// Even though there is no German translation, all nodes are returned
// because node access filtering does not occur when the user is user 1.
- $this->assertEqual(count($nids), 10, 'db_select() returns all nodes.');
+ $this->assertEqual(count($nids), 10, 'Query returns all nodes.');
}
}
diff --git a/core/modules/node/tests/src/Kernel/NodeAccessLanguageAwareTest.php b/core/modules/node/tests/src/Kernel/NodeAccessLanguageAwareTest.php
index 919ae2cd1e28..2576060efe1e 100644
--- a/core/modules/node/tests/src/Kernel/NodeAccessLanguageAwareTest.php
+++ b/core/modules/node/tests/src/Kernel/NodeAccessLanguageAwareTest.php
@@ -10,7 +10,7 @@
use Drupal\field\Entity\FieldStorageConfig;
/**
- * Tests node_access and db_select() with node_access tag functionality with
+ * Tests node_access and select queries with node_access tag functionality with
* multiple languages with node_access_test_language which is language-aware.
*
* @group node
@@ -220,7 +220,7 @@ public function testNodeAccessLanguageAware() {
// Two nodes should be returned: the node with both translations public, and
// the node with only the Catalan translation marked as private.
- $this->assertEqual(count($nids), 2, 'db_select() returns 2 nodes when the hu langcode is specified.');
+ $this->assertEqual(count($nids), 2, 'Query returns 2 nodes when the hu langcode is specified.');
$this->assertTrue(array_key_exists($this->nodes['both_public']->id(), $nids), 'The node with both translations public is returned.');
$this->assertTrue(array_key_exists($this->nodes['ca_private']->id(), $nids), 'The node with only the Catalan translation private is returned.');
@@ -234,7 +234,7 @@ public function testNodeAccessLanguageAware() {
// Two nodes should be returned: the node with both translations public, and
// the node with only the Hungarian translation marked as private.
- $this->assertEqual(count($nids), 2, 'db_select() returns 2 nodes when the hu langcode is specified.');
+ $this->assertEqual(count($nids), 2, 'Query returns 2 nodes when the hu langcode is specified.');
$this->assertTrue(array_key_exists($this->nodes['both_public']->id(), $nids), 'The node with both translations public is returned.');
$this->assertTrue(array_key_exists($this->nodes['hu_private']->id(), $nids), 'The node with only the Hungarian translation private is returned.');
@@ -247,7 +247,7 @@ public function testNodeAccessLanguageAware() {
$nids = $select->execute()->fetchAllAssoc('nid');
// There are no nodes with German translations, so no results are returned.
- $this->assertTrue(empty($nids), 'db_select() returns an empty result when the de langcode is specified.');
+ $this->assertTrue(empty($nids), 'Query returns an empty result when the de langcode is specified.');
// Query the nodes table as admin user (full access) with the node access
// tag and no specific langcode.
@@ -258,7 +258,7 @@ public function testNodeAccessLanguageAware() {
$nids = $select->execute()->fetchAllAssoc('nid');
// All nodes are returned.
- $this->assertEqual(count($nids), 6, 'db_select() returns all nodes.');
+ $this->assertEqual(count($nids), 6, 'Query returns all nodes.');
// Query the nodes table as admin user (full access) with the node access
// tag and langcode de.
@@ -271,7 +271,7 @@ public function testNodeAccessLanguageAware() {
// Even though there is no German translation, all nodes are returned
// because node access filtering does not occur when the user is user 1.
- $this->assertEqual(count($nids), 6, 'db_select() returns all nodes.');
+ $this->assertEqual(count($nids), 6, 'Query returns all nodes.');
}
}
diff --git a/core/modules/node/tests/src/Kernel/NodeAccessLanguageTest.php b/core/modules/node/tests/src/Kernel/NodeAccessLanguageTest.php
index 06709021c628..269240670b9e 100644
--- a/core/modules/node/tests/src/Kernel/NodeAccessLanguageTest.php
+++ b/core/modules/node/tests/src/Kernel/NodeAccessLanguageTest.php
@@ -9,7 +9,7 @@
use Drupal\user\Entity\User;
/**
- * Tests node_access and db_select() with node_access tag functionality with
+ * Tests node_access and select queries with node_access tag functionality with
* multiple languages with a test node access module that is not language-aware.
*
* @group node
@@ -175,7 +175,7 @@ public function testNodeAccessPrivate() {
}
/**
- * Tests db_select() with a 'node_access' tag and langcode metadata.
+ * Tests select queries with a 'node_access' tag and langcode metadata.
*/
public function testNodeAccessQueryTag() {
// Create a normal authenticated user.
@@ -214,7 +214,7 @@ public function testNodeAccessQueryTag() {
// The public node and no language node should be returned. Because no
// langcode is given it will use the fallback node.
- $this->assertEqual(count($nids), 2, 'db_select() returns 2 node');
+ $this->assertEqual(count($nids), 2, 'Query returns 2 node');
$this->assertTrue(array_key_exists($node_public->id(), $nids), 'Returned node ID is public node.');
$this->assertTrue(array_key_exists($node_no_language->id(), $nids), 'Returned node ID is no language node.');
@@ -228,7 +228,7 @@ public function testNodeAccessQueryTag() {
$nids = $select->execute()->fetchAllAssoc('nid');
// Because no nodes are created in German, no nodes are returned.
- $this->assertTrue(empty($nids), 'db_select() returns an empty result.');
+ $this->assertTrue(empty($nids), 'Query returns an empty result.');
// Query the nodes table as admin user (full access) with the node access
// tag and no specific langcode.
@@ -239,7 +239,7 @@ public function testNodeAccessQueryTag() {
$nids = $select->execute()->fetchAllAssoc('nid');
// All nodes are returned.
- $this->assertEqual(count($nids), 3, 'db_select() returns all three nodes.');
+ $this->assertEqual(count($nids), 3, 'Query returns all three nodes.');
// Query the nodes table as admin user (full access) with the node access
// tag and langcode de.
@@ -252,7 +252,7 @@ public function testNodeAccessQueryTag() {
// All nodes are returned because node access tag is not invoked when the
// user is user 1.
- $this->assertEqual(count($nids), 3, 'db_select() returns all three nodes.');
+ $this->assertEqual(count($nids), 3, 'Query returns all three nodes.');
}
}
diff --git a/core/modules/system/tests/src/Functional/Database/TemporaryQueryTest.php b/core/modules/system/tests/src/Functional/Database/TemporaryQueryTest.php
index 3e2cf5259b91..f44073571a8c 100644
--- a/core/modules/system/tests/src/Functional/Database/TemporaryQueryTest.php
+++ b/core/modules/system/tests/src/Functional/Database/TemporaryQueryTest.php
@@ -38,7 +38,7 @@ public function testTemporaryQuery() {
$this->fail('The creation of the temporary table failed.');
}
- // Now try to run two db_query_temporary() in the same request.
+ // Now try to run two temporary queries in the same request.
$table_name_test = $connection->queryTemporary('SELECT name FROM {test}', []);
$table_name_task = $connection->queryTemporary('SELECT pid FROM {test_task}', []);
diff --git a/core/modules/views/src/Plugin/views/display/DefaultDisplay.php b/core/modules/views/src/Plugin/views/display/DefaultDisplay.php
index 2d14cfb16cf4..2b5b3f291b6c 100644
--- a/core/modules/views/src/Plugin/views/display/DefaultDisplay.php
+++ b/core/modules/views/src/Plugin/views/display/DefaultDisplay.php
@@ -51,7 +51,7 @@ public function isDefaultDisplay() {
*
* If short circuited at any point, look in $view->build_info for
* information about the query. After execute, look in $view->result
- * for the array of objects returned from db_query.
+ * for the array of objects returned from \Drupal::database()->query().
*
* You can also do:
* @code
diff --git a/core/tests/Drupal/KernelTests/Core/Database/RegressionTest.php b/core/tests/Drupal/KernelTests/Core/Database/RegressionTest.php
index c5d05a2211a5..5b501d95b477 100644
--- a/core/tests/Drupal/KernelTests/Core/Database/RegressionTest.php
+++ b/core/tests/Drupal/KernelTests/Core/Database/RegressionTest.php
@@ -35,7 +35,7 @@ public function testRegression_310447() {
}
/**
- * Tests the db_table_exists() function.
+ * Tests the Schema::tableExists() method.
*/
public function testDBTableExists() {
$this->assertSame(TRUE, $this->connection->schema()->tableExists('test'), 'Returns true for existent table.');
--
GitLab