database.inc 51.5 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11
<?php

/**
 * @file
 * Core systems for the database layer.
 *
 * Classes required for basic functioning of the database system should be
 * placed in this file.  All utility functions should also be placed in this
 * file only, as they cannot auto-load the way classes can.
 */

12 13 14
use Drupal\Core\Database\Database;
use Drupal\Core\Database\Query\Condition;

15
/**
16
 * @addtogroup database
17 18 19 20 21 22 23 24 25 26 27 28 29
 * @{
 */

/**
 * 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.
 *
 * Do not use this function for INSERT, UPDATE, or DELETE queries. Those should
 * be handled via db_insert(), db_update() and db_delete() respectively.
 *
30
 * @param string|\Drupal\Core\Database\StatementInterface $query
31 32
 *   The prepared statement query to run. Although it will accept both named and
 *   unnamed placeholders, named placeholders are strongly preferred as they are
33
 *   more self-documenting. If the argument corresponding to a placeholder is
34 35
 *   an array of values to be expanded (for example, with an IN query), the
 *   placeholder should be named with a trailing bracket like :example[].
36
 * @param array $args
37 38 39 40
 *   An array of values to substitute into the query. If the query uses named
 *   placeholders, this is an associative array in any order. If the query uses
 *   unnamed placeholders (?), this is an indexed array and the order must match
 *   the order of placeholders in the query string.
41
 * @param array $options
42 43
 *   An array of options to control how the query operates.
 *
44
 * @return \Drupal\Core\Database\StatementInterface
45 46
 *   A prepared statement object, already executed.
 *
47 48 49
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container
 *   and call query() on it. For example,
50 51
 *   $injected_database->query($query, $args, $options);
 *
52
 * @see https://www.drupal.org/node/2993033
53
 * @see \Drupal\Core\Database\Connection::query()
54
 * @see \Drupal\Core\Database\Connection::defaultOptions()
55
 */
56
function db_query($query, array $args = [], array $options = []) {
57
  @trigger_error('db_query() is deprecated in drupal:8.0.0. It will be removed before drupal:9.0.0. Instead, get a database connection injected into your service from the container and call query() on it. For example, $injected_database->query($query, $args, $options). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
58
  return Database::getConnection(_db_get_target($options))->query($query, $args, $options);
59 60 61 62 63
}

/**
 * Executes a query against the active database, restricted to a range.
 *
64
 * @param string $query
65 66 67 68 69 70 71
 *   The prepared statement query to run. Although it will accept both named and
 *   unnamed placeholders, named placeholders are strongly preferred as they are
 *   more self-documenting.
 * @param $from
 *   The first record from the result set to return.
 * @param $count
 *   The number of records to return from the result set.
72
 * @param array $args
73 74 75 76
 *   An array of values to substitute into the query. If the query uses named
 *   placeholders, this is an associative array in any order. If the query uses
 *   unnamed placeholders (?), this is an indexed array and the order must match
 *   the order of placeholders in the query string.
77
 * @param array $options
78 79
 *   An array of options to control how the query operates.
 *
80
 * @return \Drupal\Core\Database\StatementInterface
81 82
 *   A prepared statement object, already executed.
 *
83 84 85
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container
 *   and call queryRange() on it. For example,
86 87
 *   $injected_database->queryRange($query, $from, $count, $args, $options);
 *
88
 * @see https://www.drupal.org/node/2993033
89
 * @see \Drupal\Core\Database\Connection::queryRange()
90
 * @see \Drupal\Core\Database\Connection::defaultOptions()
91
 */
92
function db_query_range($query, $from, $count, array $args = [], array $options = []) {
93
  @trigger_error('db_query_range() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container and call queryRange() on it. For example, $injected_database->queryRange($query, $from, $count, $args, $options). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
94
  return Database::getConnection(_db_get_target($options))->queryRange($query, $from, $count, $args, $options);
95 96 97
}

/**
98
 * Executes a SELECT query string and saves the result set to a temporary table.
99 100 101
 *
 * The execution of the query string happens against the active database.
 *
102
 * @param string $query
103 104 105
 *   The prepared SELECT statement query to run. Although it will accept both
 *   named and unnamed placeholders, named placeholders are strongly preferred
 *   as they are more self-documenting.
106
 * @param array $args
107 108 109 110
 *   An array of values to substitute into the query. If the query uses named
 *   placeholders, this is an associative array in any order. If the query uses
 *   unnamed placeholders (?), this is an indexed array and the order must match
 *   the order of placeholders in the query string.
111
 * @param array $options
112 113
 *   An array of options to control how the query operates.
 *
114
 * @return string
115 116
 *   The name of the temporary table.
 *
117 118 119
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container
 *   and call queryTemporary() on it. For example,
120 121
 *   $injected_database->queryTemporary($query, $args, $options);
 *
122
 * @see https://www.drupal.org/node/2993033
123
 * @see \Drupal\Core\Database\Connection::queryTemporary()
124
 * @see \Drupal\Core\Database\Connection::defaultOptions()
125
 */
126
function db_query_temporary($query, array $args = [], array $options = []) {
127
  @trigger_error('db_query_temporary() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container and call queryTemporary() on it. For example, $injected_database->queryTemporary($query, $args, $options). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
128
  return Database::getConnection(_db_get_target($options))->queryTemporary($query, $args, $options);
129 130 131 132 133
}

/**
 * Returns a new InsertQuery object for the active database.
 *
134
 * @param string $table
135
 *   The table into which to insert.
136
 * @param array $options
137 138
 *   An array of options to control how the query operates.
 *
139 140
 * @return \Drupal\Core\Database\Query\Insert
 *   A new Insert object for this connection.
141 142 143
 *
 * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
 *   a database connection injected into your service from the container and
144 145
 *   call insert() on it. For example,
 *   $injected_database->insert($table, $options);
146
 *
147
 * @see https://www.drupal.org/node/2993033
148 149
 * @see \Drupal\Core\Database\Connection::insert()
 * @see \Drupal\Core\Database\Connection::defaultOptions()
150
 */
151
function db_insert($table, array $options = []) {
152
  @trigger_error('db_insert() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container and call insert() on it. For example, $injected_database->insert($table, $options). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
153
  return Database::getConnection(_db_get_target($options, FALSE))->insert($table, $options);
154 155 156 157 158
}

/**
 * Returns a new MergeQuery object for the active database.
 *
159 160 161
 * @param string $table
 *   Name of the table to associate with this query.
 * @param array $options
162 163
 *   An array of options to control how the query operates.
 *
164 165
 * @return \Drupal\Core\Database\Query\Merge
 *   A new Merge object for this connection.
166 167 168
 *
 * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
 *   a database connection injected into your service from the container and
169 170
 *   call merge() on it. For example,
 *   $injected_database->merge($table, $options);
171
 *
172
 * @see https://www.drupal.org/node/2993033
173 174
 * @see \Drupal\Core\Database\Connection::merge()
 * @see \Drupal\Core\Database\Connection::defaultOptions()
175
 */
176
function db_merge($table, array $options = []) {
177
  @trigger_error('db_merge() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container and call merge() on it. For example, $injected_database->merge($table, $options). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
178
  return Database::getConnection(_db_get_target($options, FALSE))->merge($table, $options);
179 180 181 182 183
}

/**
 * Returns a new UpdateQuery object for the active database.
 *
184
 * @param string $table
185
 *   The table to update.
186
 * @param array $options
187 188
 *   An array of options to control how the query operates.
 *
189 190
 * @return \Drupal\Core\Database\Query\Update
 *   A new Update object for this connection.
191 192 193
 *
 * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
 *   a database connection injected into your service from the container and
194 195
 *   call update() on it. For example,
 *   $injected_database->update($table, $options);
196
 *
197
 * @see https://www.drupal.org/node/2993033
198 199
 * @see \Drupal\Core\Database\Connection::update()
 * @see \Drupal\Core\Database\Connection::defaultOptions()
200
 */
201
function db_update($table, array $options = []) {
202
  @trigger_error('db_update() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container and call call update() on it. For example, $injected_database->update($table, $options). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
203
  return Database::getConnection(_db_get_target($options, FALSE))->update($table, $options);
204 205 206 207 208
}

/**
 * Returns a new DeleteQuery object for the active database.
 *
209
 * @param string $table
210
 *   The table from which to delete.
211
 * @param array $options
212 213
 *   An array of options to control how the query operates.
 *
214 215
 * @return \Drupal\Core\Database\Query\Delete
 *   A new Delete object for this connection.
216 217 218
 *
 * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
 *   a database connection injected into your service from the container and
219 220
 *   call delete() on it. For example,
 *   $injected_database->delete($table, $options);
221
 *
222
 * @see https://www.drupal.org/node/2993033
223 224
 * @see \Drupal\Core\Database\Connection::delete()
 * @see \Drupal\Core\Database\Connection::defaultOptions()
225
 */
226
function db_delete($table, array $options = []) {
227
  @trigger_error('db_delete is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container and call delete() on it. For example, $injected_database->delete($table, $options). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
228
  return Database::getConnection(_db_get_target($options, FALSE))->delete($table, $options);
229 230 231 232 233
}

/**
 * Returns a new TruncateQuery object for the active database.
 *
234 235 236
 * @param string $table
 *   The table from which to truncate.
 * @param array $options
237 238
 *   An array of options to control how the query operates.
 *
239 240
 * @return \Drupal\Core\Database\Query\Truncate
 *   A new Truncate object for this connection.
241 242 243
 *
 * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
 *   a database connection injected into your service from the container and
244 245
 *   call truncate() on it. For example,
 *   $injected_database->truncate($table, $options);
246
 *
247
 * @see https://www.drupal.org/node/2993033
248 249
 * @see \Drupal\Core\Database\Connection::truncate()
 * @see \Drupal\Core\Database\Connection::defaultOptions()
250
 */
251
function db_truncate($table, array $options = []) {
252
  @trigger_error('db_truncate() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container and call truncate() on it. For example, $injected_database->truncate($table, $options). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
253
  return Database::getConnection(_db_get_target($options, FALSE))->truncate($table, $options);
254 255 256 257 258
}

/**
 * Returns a new SelectQuery object for the active database.
 *
259 260 261 262 263
 * @param string|\Drupal\Core\Database\Query\SelectInterface $table
 *   The base table for this query. May be a string or another SelectInterface
 *   object. If a SelectInterface object is passed, it will be used as a
 *   subselect.
 * @param string $alias
264
 *   (optional) The alias for the base table of this query.
265
 * @param array $options
266
 *   (optional) An array of options to control how the query operates.
267
 *
268 269
 * @return \Drupal\Core\Database\Query\Select
 *   A new Select object for this connection.
270 271 272
 *
 * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
 *   a database connection injected into your service from the container and
273
 *   call select() on it. For example,
274 275
 *   $injected_database->select($table, $alias, $options);
 *
276
 * @see https://www.drupal.org/node/2993033
277 278
 * @see \Drupal\Core\Database\Connection::select()
 * @see \Drupal\Core\Database\Connection::defaultOptions()
279
 */
280
function db_select($table, $alias = NULL, array $options = []) {
281
  @trigger_error('db_select() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container and call select() on it. For example, $injected_database->db_select($table, $alias, $options). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
282
  return Database::getConnection(_db_get_target($options))->select($table, $alias, $options);
283 284 285 286 287 288 289 290 291 292 293
}

/**
 * Returns a new transaction object for the active database.
 *
 * @param string $name
 *   Optional name of the transaction.
 * @param array $options
 *   An array of options to control how the transaction operates:
 *   - target: The database target name.
 *
294 295
 * @return \Drupal\Core\Database\Transaction
 *   A new Transaction object for this connection.
296
 *
297
 * @deprecated in drupal:8.0.x and will be removed from drupal:9.0.0. Instead, get
298
 *   a database connection injected into your service from the container and
299
 *   call startTransaction() on it. For example,
300 301
 *   $injected_database->startTransaction($name);
 *
302
 * @see https://www.drupal.org/node/2993033
303 304
 * @see \Drupal\Core\Database\Connection::startTransaction()
 * @see \Drupal\Core\Database\Connection::defaultOptions()
305
 */
306
function db_transaction($name = NULL, array $options = []) {
307
  @trigger_error('db_transaction is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container and call startTransaction() on it. For example, $injected_database->startTransaction($name). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
308
  return Database::getConnection(_db_get_target($options))->startTransaction($name);
309 310 311 312 313 314 315 316
}

/**
 * Sets a new active database.
 *
 * @param $key
 *   The key in the $databases array to set as the default database.
 *
317
 * @return string|null
318
 *   The key of the formerly active database.
319
 *
320
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Use
321
 * \Drupal\Core\Database\Database::setActiveConnection().
322 323
 *
 * @see https://www.drupal.org/node/2993033
324 325
 */
function db_set_active($key = 'default') {
326
  @trigger_error('db_set_active() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Use \Drupal\Core\Database\Database::setActiveConnection() instead. See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
327 328 329 330 331 332 333 334 335 336 337
  return Database::setActiveConnection($key);
}

/**
 * Restricts a dynamic table name to safe characters.
 *
 * Only keeps alphanumeric and underscores.
 *
 * @param $table
 *   The table name to escape.
 *
338
 * @return string
339
 *   The escaped table name as a string.
340
 *
341 342 343
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container
 *   and call escapeTable() on it. For example,
344
 *   $injected_database->escapeTable($table);
345
 *
346
 * @see https://www.drupal.org/node/2993033
347
 * @see \Drupal\Core\Database\Connection::escapeTable()
348 349
 */
function db_escape_table($table) {
350
  @trigger_error('db_escape_table() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container and call escapeTable() on it. For example, $injected_database->escapeTable($table). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
351 352 353 354 355 356 357 358
  return Database::getConnection()->escapeTable($table);
}

/**
 * Restricts a dynamic column or constraint name to safe characters.
 *
 * Only keeps alphanumeric and underscores.
 *
359
 * @param string $field
360 361
 *   The field name to escape.
 *
362
 * @return string
363
 *   The escaped field name as a string.
364
 *
365 366 367
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container
 *   and call escapeField() on it. For example,
368
 *   $injected_database->escapeField($field);
369
 *
370
 * @see https://www.drupal.org/node/2993033
371
 * @see \Drupal\Core\Database\Connection::escapeField()
372 373
 */
function db_escape_field($field) {
374
  @trigger_error('db_escape_field() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container and call escapeField() on it. For example, $injected_database->escapeField($field). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401
  return Database::getConnection()->escapeField($field);
}

/**
 * Escapes characters that work as wildcard characters in a LIKE pattern.
 *
 * The wildcard characters "%" and "_" as well as backslash are prefixed with
 * 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.
 *
 * For example, the following does a case-insensitive query for all rows whose
 * name starts with $prefix:
 * @code
 * $result = db_select('person', 'p')
 *   ->fields('p')
 *   ->condition('name', db_like($prefix) . '%', 'LIKE')
 *   ->execute()
 *   ->fetchAll();
 * @endcode
 *
 * Backslash is defined as escape character for LIKE patterns in
 * DatabaseCondition::mapConditionOperator().
 *
402
 * @param string $string
403 404
 *   The string to escape.
 *
405
 * @return string
406
 *   The escaped string.
407
 *
408 409 410
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container
 *   and call escapeLike() on it. For example,
411
 *   $injected_database->escapeLike($string);
412
 *
413
 * @see https://www.drupal.org/node/2993033
414
 * @see \Drupal\Core\Database\Connection::escapeLike()
415 416
 */
function db_like($string) {
417
  @trigger_error('db_like() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container and call escapeLike() on it. For example, $injected_database->escapeLike($string). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
418 419 420 421 422 423
  return Database::getConnection()->escapeLike($string);
}

/**
 * Retrieves the name of the currently active database driver.
 *
424
 * @return string
425
 *   The name of the currently active database driver.
426
 *
427 428 429
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container
 *   and call driver() on it. For example, $injected_database->driver($string);
430
 *
431
 * @see https://www.drupal.org/node/2993033
432
 * @see \Drupal\Core\Database\Connection::driver()
433 434
 */
function db_driver() {
435
  @trigger_error('db_driver() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container and call driver() on it. For example, $injected_database->driver($string). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
436 437 438 439 440 441
  return Database::getConnection()->driver();
}

/**
 * Closes the active database connection.
 *
442
 * @param array $options
443 444
 *   An array of options to control which connection is closed. Only the target
 *   key has any meaning in this case.
445
 *
446
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Use
447 448
 *   \Drupal\Core\Database\Database::closeConnection($target).
 *
449
 * @see https://www.drupal.org/node/2993033
450
 * @see \Drupal\Core\Database\Database::closeConnection()
451
 */
452
function db_close(array $options = []) {
453
  @trigger_error('db_close() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Use \Drupal\Core\Database\Database::closeConnection() instead. See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482
  Database::closeConnection(_db_get_target($options));
}

/**
 * Get target helper.
 *
 * Helps get "target" database from the query options.
 *
 * @param array $options
 *   An array of options to control how the query operates. The array is passed
 *   by reference, and its 'target' key is removed from it during the process,
 *   so that it will not leak in calls to methods in the Database class.
 * @param bool $allow_replica
 *   (Optional) When false, 'replica' connection will be redirected to the
 *   'default' one. Defaults to TRUE.
 *
 * @return string
 *   The target database key for the database connection.
 *
 * @internal
 *
 * @deprecated in drupal:8.8.0 and will be removed from drupal:9.0.0. There is
 *   no replacement, this function should not be used. It was introduced in
 *   Drupal 8.8.0 only as a byproduct of the deprecation of the db_* procedural
 *   functions.
 *
 * @see https://www.drupal.org/node/2993033
 */
function _db_get_target(array &$options, $allow_replica = TRUE) {
483
  @trigger_error('_db_get_target() is deprecated in drupal:8.8.0. Will be removed before drupal:9.0.0. See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
484 485
  if (empty($options['target']) || ($options['target'] === 'replica' && !$allow_replica)) {
    $options['target'] = 'default';
486
  }
487 488 489
  $target = $options['target'];
  unset($options['target']);
  return $target;
490 491 492 493 494 495 496 497 498
}

/**
 * Retrieves a unique id.
 *
 * Use this function if for some reason you can't use a serial field. Using a
 * serial field is preferred, and InsertQuery::execute() returns the value of
 * the last ID inserted.
 *
499
 * @param int $existing_id
500 501 502 503
 *   After a database import, it might be that the sequences table is behind, so
 *   by passing in a minimum ID, it can be assured that we never issue the same
 *   ID.
 *
504
 * @return int
505
 *   An integer number larger than any number returned before for this sequence.
506
 *
507 508 509 510
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container
 *   and call nextId() on it.
 *   For example, $injected_database->nextId($existing_id);
511
 *
512
 * @see https://www.drupal.org/node/2993033
513
 * @see \Drupal\Core\Database\Connection::nextId()
514 515
 */
function db_next_id($existing_id = 0) {
516
  @trigger_error('db_next_id() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container and call nextId() on it. For example, $injected_database->nextId($existing_id). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
517 518 519 520 521 522
  return Database::getConnection()->nextId($existing_id);
}

/**
 * Returns a new DatabaseCondition, set to "OR" all conditions together.
 *
523 524
 * @return \Drupal\Core\Database\Query\Condition
 *   A new Condition object, set to "OR" all conditions together.
525
 *
526
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Create
527 528 529
 *   a \Drupal\Core\Database\Query\Condition object, specifying an OR
 *   conjunction: new Condition('OR');
 *
530
 * @see https://www.drupal.org/node/2993033
531
 * @see \Drupal\Core\Database\Query\Condition
532 533
 */
function db_or() {
534
  @trigger_error('db_or() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Create a \Drupal\Core\Database\Query\Condition object, specifying an OR conjunction: new Condition(\'OR\'), instead. See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
535 536 537 538 539 540
  return new Condition('OR');
}

/**
 * Returns a new DatabaseCondition, set to "AND" all conditions together.
 *
541 542
 * @return \Drupal\Core\Database\Query\Condition
 *   A new Condition object, set to "AND" all conditions together.
543
 *
544
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Create
545 546 547
 *   a \Drupal\Core\Database\Query\Condition object, specifying an AND
 *   conjunction: new Condition('AND');
 *
548
 * @see https://www.drupal.org/node/2993033
549
 * @see \Drupal\Core\Database\Query\Condition
550 551
 */
function db_and() {
552
  @trigger_error('db_and() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Create a \Drupal\Core\Database\Query\Condition object, specifying an AND conjunction: new Condition(\'AND\'), instead. See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
553 554 555 556 557 558
  return new Condition('AND');
}

/**
 * Returns a new DatabaseCondition, set to "XOR" all conditions together.
 *
559 560
 * @return \Drupal\Core\Database\Query\Condition
 *   A new Condition object, set to "XOR" all conditions together.
561
 *
562
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Create
563
 *   a \Drupal\Core\Database\Query\Condition object, specifying a XOR
564 565
 *   conjunction: new Condition('XOR');
 *
566
 * @see https://www.drupal.org/node/2993033
567
 * @see \Drupal\Core\Database\Query\Condition
568 569
 */
function db_xor() {
570
  @trigger_error('db_xor() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Create a \Drupal\Core\Database\Query\Condition object, specifying a XOR conjunction: new Condition(\'XOR\'), instead. See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
571 572 573 574 575 576
  return new Condition('XOR');
}

/**
 * Returns a new DatabaseCondition, set to the specified conjunction.
 *
577 578 579
 * Internal API function call.  Creating a
 * \Drupal\Core\Database\Query\Condition object, specifying the desired
 * conjunction ('AND', 'OR' or 'XOR'), is preferred.
580
 *
581
 * @param string $conjunction
582
 *   The conjunction to use for query conditions (AND, OR or XOR).
583 584 585
 *
 * @return \Drupal\Core\Database\Query\Condition
 *   A new Condition object, set to the specified conjunction.
586
 *
587
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Create
588
 *   a \Drupal\Core\Database\Query\Condition object, specifying the desired
589
 *   conjunction: new Condition($conjunction);
590
 *
591
 * @see https://www.drupal.org/node/2993033
592
 * @see \Drupal\Core\Database\Query\Condition
593 594
 */
function db_condition($conjunction) {
595
  @trigger_error('db_condition() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Create a \Drupal\Core\Database\Query\Condition object, specifying the desired conjunction: new Condition($conjunction), instead. See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
596 597 598 599
  return new Condition($conjunction);
}

/**
600
 * @} End of "addtogroup database".
601 602 603 604
 */


/**
605
 * @addtogroup schemaapi
606 607 608 609 610 611
 * @{
 */

/**
 * Creates a new table from a Drupal table definition.
 *
612
 * @param string $name
613
 *   The name of the table to create.
614
 * @param array $table
615
 *   A Schema API table definition array.
616
 *
617 618 619
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container,
 *   get its schema driver, and call createTable() on it. For example,
620 621
 *   $injected_database->schema()->createTable($name, $table);
 *
622
 * @see https://www.drupal.org/node/2993033
623
 * @see \Drupal\Core\Database\Schema::createTable()
624 625
 */
function db_create_table($name, $table) {
626
  @trigger_error('db_create_table() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container, get its schema driver, and call createTable() on it. For example, $injected_database->schema()->createTable($name, $table). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
627 628 629 630 631 632 633 634 635
  return Database::getConnection()->schema()->createTable($name, $table);
}

/**
 * Returns an array of field names from an array of key/index column specifiers.
 *
 * This is usually an identity function but if a key/index uses a column prefix
 * specification, this function extracts just the name.
 *
636
 * @param array $fields
637 638
 *   An array of key/index column specifiers.
 *
639
 * @return array
640
 *   An array of field names.
641
 *
642 643 644
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container,
 *   get its schema driver, and call fieldNames() on it. For example,
645 646
 *   $injected_database->schema()->fieldNames($fields);
 *
647
 * @see https://www.drupal.org/node/2993033
648
 * @see \Drupal\Core\Database\Schema::fieldNames()
649 650
 */
function db_field_names($fields) {
651
  @trigger_error('db_field_names() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container, get its schema driver, and call fieldNames() on it. For example, $injected_database->schema()->fieldNames($fields). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
652 653 654 655 656 657
  return Database::getConnection()->schema()->fieldNames($fields);
}

/**
 * Checks if an index exists in the given table.
 *
658
 * @param string $table
659
 *   The name of the table in drupal (no prefixing).
660
 * @param string $name
661 662
 *   The name of the index in drupal (no prefixing).
 *
663
 * @return bool
664
 *   TRUE if the given index exists, otherwise FALSE.
665
 *
666 667 668
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container,
 *   get its schema driver, and call indexExists() on it. For example,
669 670
 *   $injected_database->schema()->indexExists($table, $name);
 *
671
 * @see https://www.drupal.org/node/2993033
672
 * @see \Drupal\Core\Database\Schema::indexExists()
673 674
 */
function db_index_exists($table, $name) {
675
  @trigger_error('db_index_exists() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container, get its schema driver, and call indexExists() on it. For example, $injected_database->schema()->indexExists($table, $name). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
676 677 678 679 680 681
  return Database::getConnection()->schema()->indexExists($table, $name);
}

/**
 * Checks if a table exists.
 *
682
 * @param string $table
683 684
 *   The name of the table in drupal (no prefixing).
 *
685
 * @return bool
686
 *   TRUE if the given table exists, otherwise FALSE.
687
 *
688 689 690
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container,
 *   get its schema driver, and call tableExists() on it. For example,
691 692
 *   $injected_database->schema()->tableExists($table);
 *
693
 * @see https://www.drupal.org/node/2993033
694
 * @see \Drupal\Core\Database\Schema::tableExists()
695 696
 */
function db_table_exists($table) {
697
  @trigger_error(
698
    'db_table_exists() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Use $injected_database->schema()->tableExists($table) instead. See https://www.drupal.org/node/2993033',
699 700 701
    E_USER_DEPRECATED
  );

702 703 704 705 706 707 708 709 710 711 712
  return Database::getConnection()->schema()->tableExists($table);
}

/**
 * Checks if a column exists in the given table.
 *
 * @param $table
 *   The name of the table in drupal (no prefixing).
 * @param $field
 *   The name of the field.
 *
713
 * @return bool
714
 *   TRUE if the given column exists, otherwise FALSE.
715
 *
716 717 718
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container,
 *   get its schema driver, and call fieldExists() on it. For example,
719 720
 *   $injected_database->schema()->fieldExists($table, $field);
 *
721
 * @see https://www.drupal.org/node/2993033
722
 * @see \Drupal\Core\Database\Schema::fieldExists()
723 724
 */
function db_field_exists($table, $field) {
725
  @trigger_error('db_field_exists() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container, get its schema driver, and call fieldExists() on it. For example, $injected_database->schema()->fieldExists($table, $field). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
726 727 728 729 730 731
  return Database::getConnection()->schema()->fieldExists($table, $field);
}

/**
 * Finds all tables that are like the specified base table name.
 *
732
 * @param string $table_expression
733 734
 *   An SQL expression, for example "simpletest%" (without the quotes).
 *
735
 * @return array
736
 *   Array, both the keys and the values are the matching tables.
737
 *
738 739 740
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container,
 *   get its schema driver, and call findTables() on it. For example,
741 742
 *   $injected_database->schema()->findTables($table_expression);
 *
743
 * @see https://www.drupal.org/node/2993033
744
 * @see \Drupal\Core\Database\Schema::findTables()
745 746
 */
function db_find_tables($table_expression) {
747
  @trigger_error(
748
    'db_find_tables() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Use $injected_database->schema()->findTables($table_expression) instead. See https://www.drupal.org/node/2993033',
749 750
    E_USER_DEPRECATED
  );
751 752 753 754 755 756 757
  return Database::getConnection()->schema()->findTables($table_expression);
}

/**
 * Renames a table.
 *
 * @param $table
758
 *   The current name of the table to be renamed.
759 760
 * @param $new_name
 *   The new name for the table.
761
 *
762 763 764
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container,
 *   get its schema driver, and call renameTable() on it. For example,
765 766
 *   $injected_database->schema()->renameTable($table, $new_name);
 *
767
 * @see https://www.drupal.org/node/2993033
768
 * @see \Drupal\Core\Database\Schema::renameTable()
769 770
 */
function db_rename_table($table, $new_name) {
771
  @trigger_error('db_rename_table() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container, get its schema driver, and call renameTable() on it. For example, $injected_database->schema()->renameTable($table, $new_name). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
772 773 774 775 776 777 778 779
  return Database::getConnection()->schema()->renameTable($table, $new_name);
}

/**
 * Drops a table.
 *
 * @param $table
 *   The table to be dropped.
780
 *
781 782 783
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container,
 *   get its schema driver, and call dropTable() on it. For example,
784 785
 *   $injected_database->schema()->dropTable($table);
 *
786
 * @see https://www.drupal.org/node/2993033
787
 * @see \Drupal\Core\Database\Schema::dropTable()
788 789
 */
function db_drop_table($table) {
790
  @trigger_error('db_drop_table() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Use \Drupal\Core\Database\Database::getConnection()->schema()->dropTable() instead. See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
791 792 793 794 795 796 797 798 799 800
  return Database::getConnection()->schema()->dropTable($table);
}

/**
 * Adds a new field to a table.
 *
 * @param $table
 *   Name of the table to be altered.
 * @param $field
 *   Name of the field to be added.
801
 * @param array $spec
802 803 804 805
 *   The field specification array, as taken from a schema definition. The
 *   specification may also contain the key 'initial'; the newly-created field
 *   will be set to the value of the key in all rows. This is most useful for
 *   creating NOT NULL columns with no default value in existing tables.
806
 * @param array $keys_new
807
 *   (optional) Keys and indexes specification to be created on the table along
808 809 810
 *   with adding the field. The format is the same as a table specification, but
 *   without the 'fields' element. If you are adding a type 'serial' field, you
 *   MUST specify at least one key or index including it in this array. See
811
 *   \Drupal\Core\Database\Schema::changeField() for more explanation why.
812
 *
813 814 815
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container,
 *   get its schema driver, and call addField() on it. For example,
816 817
 *   $injected_database->schema()->addField($table, $field, $spec, $keys_new);
 *
818
 * @see https://www.drupal.org/node/2993033
819
 * @see \Drupal\Core\Database\Schema::addField()
820
 * @see \Drupal\Core\Database\Schema::changeField()
821
 */
822
function db_add_field($table, $field, $spec, $keys_new = []) {
823
  @trigger_error('db_add_field() is deprecated in drupal:8.0.0. It will be removed from drupal:9.0.0. Instead, get a database connection injected into your service from the container, get its schema driver, and call addField() on it. For example, $injected_database->schema()->addField($table, $field, $spec, $keys_new). See https://www.drupal.org/node/2993033', E_USER_DEPRECATED);
824 825 826 827 828 829 830 831 832 833
  return Database::getConnection()->schema()->addField($table, $field, $spec, $keys_new);
}

/**
 * Drops a field.
 *
 * @param $table
 *   The table to be altered.
 * @param $field
 *   The field to be dropped.
834 835 836 837 838
 *
 * @return bool
 *   TRUE if the field was successfully dropped, FALSE if there was no field by
 *   that name to begin with.
 *
839 840 841
 * @deprecated in drupal:8.0.0 and will be removed from drupal:9.0.0. Instead,
 *   get a database connection injected into your service from the container,
 *   get its schema driver, and call dropField() on it. For example,
alexpott's avatar