Unverified Commit a13f7aca authored by alexpott's avatar alexpott

Issue #2987399 by Mile23, alexpott: Update database.api.php to remove deprecated db_*() functions

(cherry picked from commit e3d81645)
parent c5bbae9b
......@@ -22,7 +22,7 @@
* practices.
*
* For more detailed information on the database abstraction layer, see
* https://www.drupal.org/developing/api/database.
* https://www.drupal.org/docs/8/api/database-api/database-api-overview.
*
* @section sec_entity Querying entities
* Any query on Drupal entities or fields should use the Entity Query API. See
......@@ -30,19 +30,20 @@
*
* @section sec_simple Simple SELECT database queries
* For simple SELECT queries that do not involve entities, the Drupal database
* abstraction layer provides the functions db_query() and db_query_range(),
* which execute SELECT queries (optionally with range limits) and return result
* sets that you can iterate over using foreach loops. (The result sets are
* objects implementing the \Drupal\Core\Database\StatementInterface interface.)
* abstraction layer provides the functions \Drupal::database()->query() and
* \Drupal::database()->queryRange(), which execute SELECT queries (optionally
* with range limits) and return result sets that you can iterate over using
* foreach loops. (The result sets are objects implementing the
* \Drupal\Core\Database\StatementInterface interface.)
* You can use the simple query functions for query strings that are not
* dynamic (except for placeholders, see below), and that you are certain will
* work in any database engine. See @ref sec_dynamic below if you have a more
* complex query, or a query whose syntax would be different in some databases.
*
* As a note, db_query() and similar functions are wrappers on connection object
* methods. In most classes, you should use dependency injection and the
* database connection object instead of these wrappers; See @ref sec_connection
* below for details.
* 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.
*
* To use the simple database query functions, you will need to make a couple of
* modifications to your bare SQL query:
......@@ -55,7 +56,8 @@
* putting variables directly into the query, to protect against SQL
* injection attacks.
* - LIMIT syntax differs between databases, so if you have a ranged query,
* use db_query_range() instead of db_query().
* use \Drupal::database()->queryRange() instead of
* \Drupal::database()->query().
*
* For example, if the query you want to run is:
* @code
......@@ -64,7 +66,7 @@
* @endcode
* you would do it like this:
* @code
* $result = db_query_range('SELECT e.id, e.title, e.created
* $result = \Drupal::database()->queryRange('SELECT e.id, e.title, e.created
* FROM {example} e
* WHERE e.uid = :uid
* ORDER BY e.created DESC',
......@@ -91,16 +93,11 @@
* fields (see the @link entity_api Entity API topic @endlink for more on
* entity queries).
*
* As a note, db_select() and similar functions are wrappers on connection
* object methods. In most classes, you should use dependency injection and the
* database connection object instead of these wrappers; 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:
* @code
* $result = db_select('example', 'e')
* $result = \Drupal::database()->select('example', 'e')
* ->fields('e', array('id', 'title', 'created'))
* ->condition('e.uid', $uid)
* ->orderBy('e.created', 'DESC')
......@@ -109,7 +106,7 @@
* @endcode
*
* There are also methods to join to other tables, add fields with aliases,
* isNull() to have a @code WHERE e.foo IS NULL @endcode condition, etc. See
* isNull() to query for NULL values, etc. See
* https://www.drupal.org/developing/api/database for many more details.
*
* One note on chaining: It is common in the dynamic database API to chain
......@@ -123,17 +120,19 @@
* returns the query or something else, and only chain methods that return the
* query.
*
* @section_insert INSERT, UPDATE, and DELETE queries
* @section sec_insert INSERT, UPDATE, and DELETE queries
* INSERT, UPDATE, and DELETE queries need special care in order to behave
* consistently across databases; you should never use db_query() to run
* an INSERT, UPDATE, or DELETE query. Instead, use functions db_insert(),
* db_update(), and db_delete() to obtain a base query on your table, and then
* add dynamic conditions (as illustrated in @ref sec_dynamic above).
*
* As a note, db_insert() and similar functions are wrappers on connection
* object methods. In most classes, you should use dependency injection and the
* database connection object instead of these wrappers; See @ref sec_connection
* below for details.
* consistently across databases; you should never use
* \Drupal::database()->query() to run an INSERT, UPDATE, or DELETE query.
* Instead, use functions \Drupal::database()->insert(),
* \Drupal::database()->update(), and \Drupal::database()->delete() to obtain
* a base query on your table, and then add dynamic conditions (as illustrated
* in @ref sec_dynamic above).
*
* 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.
*
* For example, if your query is:
* @code
......@@ -142,7 +141,7 @@
* You can execute it via:
* @code
* $fields = array('id' => 1, 'uid' => 2, 'path' => 'path', 'name' => 'Name');
* db_insert('example')
* \Drupal::database()->insert('example')
* ->fields($fields)
* ->execute();
* @endcode
......@@ -150,21 +149,26 @@
* @section sec_transaction Transactions
* Drupal supports transactions, including a transparent fallback for
* databases that do not support transactions. To start a new transaction,
* call @code $txn = db_transaction(); @endcode The transaction will
* remain open for as long as the variable $txn remains in scope; when $txn is
* destroyed, the transaction will be committed. If your transaction is nested
* inside of another then Drupal will track each transaction and only commit
* the outer-most transaction when the last transaction object goes out out of
* scope (when all relevant queries have completed successfully).
* call startTransaction(), like this:
* @code
* $transaction = \Drupal::database()->startTransaction();
* @endcode
* The transaction will remain open for as long as the variable $transaction
* remains in scope; when $transaction is destroyed, the transaction will be
* committed. If your transaction is nested inside of another then Drupal will
* track each transaction and only commit the outer-most transaction when the
* last transaction object goes out out of scope (when all relevant queries have
* completed successfully).
*
* Example:
* @code
* function my_transaction_function() {
* $connection = \Drupal::database();
* // The transaction opens here.
* $txn = db_transaction();
* $transaction = $connection->startTransaction();
*
* try {
* $id = db_insert('example')
* $id = $connection->insert('example')
* ->fields(array(
* 'field1' => 'mystring',
* 'field2' => 5,
......@@ -177,20 +181,21 @@
* }
* catch (Exception $e) {
* // Something went wrong somewhere, so roll back now.
* $txn->rollBack();
* $transaction->rollBack();
* // Log the exception to watchdog.
* watchdog_exception('type', $e);
* }
*
* // $txn goes out of scope here. Unless the transaction was rolled back, it
* // gets automatically committed here.
* // $transaction goes out of scope here. Unless the transaction was rolled
* // back, it gets automatically committed here.
* }
*
* function my_other_function($id) {
* $connection = \Drupal::database();
* // The transaction is still open here.
*
* if ($id % 2 == 0) {
* db_update('example')
* $connection->update('example')
* ->condition('id', $id)
* ->fields(array('field2' => 10))
* ->execute();
......@@ -199,18 +204,19 @@
* @endcode
*
* @section sec_connection Database connection objects
* The examples here all use functions like db_select() and db_query(), which
* can be called from any Drupal method or function code. In some classes, you
* may already have a database connection object in a member variable, or it may
* be passed into a class constructor via dependency injection. If that is the
* case, you can look at the code for db_select() and the other functions to see
* how to get a query object from your connection variable. For example:
* The examples here all use functions like \Drupal::database()->select() and
* \Drupal::database()->query(), which can be called from any Drupal method or
* function code. In some classes, you may already have a database connection
* object in a member variable, or it may be passed into a class constructor
* via dependency injection. If that is the case, you can look at the code for
* \Drupal::database()->select() and the other functions to see how to get a
* query object from your connection variable. For example:
* @code
* $query = $connection->select('example', 'e');
* @endcode
* would be the equivalent of
* @code
* $query = db_select('example', 'e');
* $query = \Drupal::database()->select('example', 'e');
* @endcode
* if you had a connection object variable $connection available to use. See
* also the @link container Services and Dependency Injection topic. @endlink
......
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