[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Part of the Joomla Framework Database Package
   4   *
   5   * @copyright  Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
   6   * @license    GNU General Public License version 2 or later; see LICENSE
   7   */
   8  
   9  namespace Joomla\Database;
  10  
  11  /**
  12   * Joomla Framework Database Interface
  13   *
  14   * @since  1.0
  15   */
  16  interface DatabaseInterface
  17  {
  18      /**
  19       * Connects to the database if needed.
  20       *
  21       * @return  void
  22       *
  23       * @since   2.0.0
  24       * @throws  \RuntimeException
  25       */
  26  	public function connect();
  27  
  28      /**
  29       * Determines if the connection to the server is active.
  30       *
  31       * @return  boolean
  32       *
  33       * @since   2.0.0
  34       */
  35  	public function connected();
  36  
  37      /**
  38       * Create a new database using information from $options object.
  39       *
  40       * @param   \stdClass  $options  Object used to pass user and database name to database driver. This object must have "db_name" and "db_user" set.
  41       * @param   boolean    $utf      True if the database supports the UTF-8 character set.
  42       *
  43       * @return  boolean|resource
  44       *
  45       * @since   2.0.0
  46       * @throws  \RuntimeException
  47       */
  48  	public function createDatabase($options, $utf = true);
  49  
  50      /**
  51       * Replace special placeholder representing binary field with the original string.
  52       *
  53       * @param   string|resource  $data  Encoded string or resource.
  54       *
  55       * @return  string  The original string.
  56       *
  57       * @since   1.7.0
  58       */
  59  	public function decodeBinary($data);
  60  
  61      /**
  62       * Disconnects the database.
  63       *
  64       * @return  void
  65       *
  66       * @since   2.0.0
  67       */
  68  	public function disconnect();
  69  
  70      /**
  71       * Drops a table from the database.
  72       *
  73       * @param   string   $table     The name of the database table to drop.
  74       * @param   boolean  $ifExists  Optionally specify that the table must exist before it is dropped.
  75       *
  76       * @return  $this
  77       *
  78       * @since   2.0.0
  79       * @throws  \RuntimeException
  80       */
  81  	public function dropTable($table, $ifExists = true);
  82  
  83      /**
  84       * Escapes a string for usage in an SQL statement.
  85       *
  86       * @param   string   $text   The string to be escaped.
  87       * @param   boolean  $extra  Optional parameter to provide extra escaping.
  88       *
  89       * @return  string   The escaped string.
  90       *
  91       * @since   2.0.0
  92       */
  93  	public function escape($text, $extra = false);
  94  
  95      /**
  96       * Execute the SQL statement.
  97       *
  98       * @return  boolean
  99       *
 100       * @since   2.0.0
 101       * @throws  \RuntimeException
 102       */
 103  	public function execute();
 104  
 105      /**
 106       * Get the number of affected rows for the previous executed SQL statement.
 107       *
 108       * @return  integer
 109       *
 110       * @since   2.0.0
 111       */
 112  	public function getAffectedRows();
 113  
 114      /**
 115       * Method to get the database collation in use by sampling a text field of a table in the database.
 116       *
 117       * @return  string|boolean  The collation in use by the database or boolean false if not supported.
 118       *
 119       * @since   2.0.0
 120       */
 121  	public function getCollation();
 122  
 123      /**
 124       * Method that provides access to the underlying database connection.
 125       *
 126       * @return  resource  The underlying database connection resource.
 127       *
 128       * @since   2.0.0
 129       */
 130  	public function getConnection();
 131  
 132      /**
 133       * Method to get the database connection collation, as reported by the driver.
 134       *
 135       * If the connector doesn't support reporting this value please return an empty string.
 136       *
 137       * @return  string
 138       *
 139       * @since   2.0.0
 140       */
 141  	public function getConnectionCollation();
 142  
 143      /**
 144       * Method to get the database encryption details (cipher and protocol) in use.
 145       *
 146       * @return  string  The database encryption details.
 147       *
 148       * @since   2.0.0
 149       */
 150  	public function getConnectionEncryption(): string;
 151  
 152      /**
 153       * Method to test if the database TLS connections encryption are supported.
 154       *
 155       * @return  boolean  Whether the database supports TLS connections encryption.
 156       *
 157       * @since   2.0.0
 158       */
 159  	public function isConnectionEncryptionSupported(): bool;
 160  
 161      /**
 162       * Method to check whether the installed database version is supported by the database driver
 163       *
 164       * @return  boolean  True if the database version is supported
 165       *
 166       * @since   2.0.0
 167       */
 168  	public function isMinimumVersion();
 169  
 170      /**
 171       * Get the total number of SQL statements executed by the database driver.
 172       *
 173       * @return  integer
 174       *
 175       * @since   2.0.0
 176       */
 177  	public function getCount();
 178  
 179      /**
 180       * Returns a PHP date() function compliant date format for the database driver.
 181       *
 182       * @return  string
 183       *
 184       * @since   2.0.0
 185       */
 186  	public function getDateFormat();
 187  
 188      /**
 189       * Get the minimum supported database version.
 190       *
 191       * @return  string
 192       *
 193       * @since   2.0.0
 194       */
 195  	public function getMinimum();
 196  
 197      /**
 198       * Get the name of the database driver.
 199       *
 200       * @return  string
 201       *
 202       * @since   2.0.0
 203       */
 204  	public function getName();
 205  
 206      /**
 207       * Get the null or zero representation of a timestamp for the database driver.
 208       *
 209       * @return  string
 210       *
 211       * @since   2.0.0
 212       */
 213  	public function getNullDate();
 214  
 215      /**
 216       * Get the number of returned rows for the previous executed SQL statement.
 217       *
 218       * @return  integer
 219       *
 220       * @since   2.0.0
 221       */
 222  	public function getNumRows();
 223  
 224      /**
 225       * Get the current query object or a new QueryInterface object.
 226       *
 227       * @param   boolean  $new  False to return the current query object, True to return a new QueryInterface object.
 228       *
 229       * @return  QueryInterface
 230       *
 231       * @since   2.0.0
 232       * @throws  \RuntimeException
 233       */
 234  	public function getQuery($new = false);
 235  
 236      /**
 237       * Get the server family type.
 238       *
 239       * @return  string
 240       *
 241       * @since   2.0.0
 242       */
 243  	public function getServerType();
 244  
 245      /**
 246       * Retrieves field information about the given tables.
 247       *
 248       * @param   string   $table     The name of the database table.
 249       * @param   boolean  $typeOnly  True (default) to only return field types.
 250       *
 251       * @return  array
 252       *
 253       * @since   2.0.0
 254       * @throws  \RuntimeException
 255       */
 256  	public function getTableColumns($table, $typeOnly = true);
 257  
 258      /**
 259       * Retrieves field information about the given tables.
 260       *
 261       * @param   mixed  $tables  A table name or a list of table names.
 262       *
 263       * @return  array
 264       *
 265       * @since   2.0.0
 266       * @throws  \RuntimeException
 267       */
 268  	public function getTableKeys($tables);
 269  
 270      /**
 271       * Method to get an array of all tables in the database.
 272       *
 273       * @return  array
 274       *
 275       * @since   2.0.0
 276       * @throws  \RuntimeException
 277       */
 278  	public function getTableList();
 279  
 280      /**
 281       * Get the version of the database connector.
 282       *
 283       * @return  string
 284       *
 285       * @since   2.0.0
 286       */
 287  	public function getVersion();
 288  
 289      /**
 290       * Determine whether or not the database engine supports UTF-8 character encoding.
 291       *
 292       * @return  boolean  True if the database engine supports UTF-8 character encoding.
 293       *
 294       * @since   2.0.0
 295       */
 296  	public function hasUtfSupport();
 297  
 298      /**
 299       * Method to get the auto-incremented value from the last INSERT statement.
 300       *
 301       * @return  mixed  The value of the auto-increment field from the last inserted row.
 302       *
 303       * @since   2.0.0
 304       */
 305  	public function insertid();
 306  
 307      /**
 308       * Inserts a row into a table based on an object's properties.
 309       *
 310       * @param   string  $table   The name of the database table to insert into.
 311       * @param   object  $object  A reference to an object whose public properties match the table fields.
 312       * @param   string  $key     The name of the primary key. If provided the object property is updated.
 313       *
 314       * @return  boolean
 315       *
 316       * @since   2.0.0
 317       * @throws  \RuntimeException
 318       */
 319  	public function insertObject($table, &$object, $key = null);
 320  
 321      /**
 322       * Test to see if the connector is available.
 323       *
 324       * @return  boolean
 325       *
 326       * @since   1.0
 327       */
 328  	public static function isSupported();
 329  
 330      /**
 331       * Method to get the first row of the result set from the database query as an associative array of ['field_name' => 'row_value'].
 332       *
 333       * @return  mixed  The return value or null if the query failed.
 334       *
 335       * @since   2.0.0
 336       * @throws  \RuntimeException
 337       */
 338  	public function loadAssoc();
 339  
 340      /**
 341       * Method to get an array of the result set rows from the database query where each row is an associative array
 342       * of ['field_name' => 'row_value'].  The array of rows can optionally be keyed by a field name, but defaults to
 343       * a sequential numeric array.
 344       *
 345       * NOTE: Choosing to key the result array by a non-unique field name can result in unwanted
 346       * behavior and should be avoided.
 347       *
 348       * @param   string  $key     The name of a field on which to key the result array.
 349       * @param   string  $column  An optional column name. Instead of the whole row, only this column value will be in the result array.
 350       *
 351       * @return  mixed   The return value or null if the query failed.
 352       *
 353       * @since   2.0.0
 354       * @throws  \RuntimeException
 355       */
 356  	public function loadAssocList($key = null, $column = null);
 357  
 358      /**
 359       * Method to get an array of values from the <var>$offset</var> field in each row of the result set from the database query.
 360       *
 361       * @param   integer  $offset  The row offset to use to build the result array.
 362       *
 363       * @return  mixed  The return value or null if the query failed.
 364       *
 365       * @since   2.0.0
 366       * @throws  \RuntimeException
 367       */
 368  	public function loadColumn($offset = 0);
 369  
 370      /**
 371       * Method to get the first row of the result set from the database query as an object.
 372       *
 373       * @param   string  $class  The class name to use for the returned row object.
 374       *
 375       * @return  mixed  The return value or null if the query failed.
 376       *
 377       * @since   2.0.0
 378       * @throws  \RuntimeException
 379       */
 380  	public function loadObject($class = \stdClass::class);
 381  
 382      /**
 383       * Method to get an array of the result set rows from the database query where each row is an object.  The array
 384       * of objects can optionally be keyed by a field name, but defaults to a sequential numeric array.
 385       *
 386       * NOTE: Choosing to key the result array by a non-unique field name can result in unwanted behavior and should be avoided.
 387       *
 388       * @param   string  $key    The name of a field on which to key the result array.
 389       * @param   string  $class  The class name to use for the returned row objects.
 390       *
 391       * @return  mixed  The return value or null if the query failed.
 392       *
 393       * @since   2.0.0
 394       * @throws  \RuntimeException
 395       */
 396  	public function loadObjectList($key = '', $class = \stdClass::class);
 397  
 398      /**
 399       * Method to get the first field of the first row of the result set from the database query.
 400       *
 401       * @return  mixed  The return value or null if the query failed.
 402       *
 403       * @since   2.0.0
 404       * @throws  \RuntimeException
 405       */
 406  	public function loadResult();
 407  
 408      /**
 409       * Method to get the first row of the result set from the database query as an array.
 410       *
 411       * Columns are indexed numerically so the first column in the result set would be accessible via <var>$row[0]</var>, etc.
 412       *
 413       * @return  mixed  The return value or null if the query failed.
 414       *
 415       * @since   2.0.0
 416       * @throws  \RuntimeException
 417       */
 418  	public function loadRow();
 419  
 420      /**
 421       * Method to get an array of the result set rows from the database query where each row is an array.  The array
 422       * of objects can optionally be keyed by a field offset, but defaults to a sequential numeric array.
 423       *
 424       * NOTE: Choosing to key the result array by a non-unique field can result in unwanted behavior and should be avoided.
 425       *
 426       * @param   string  $key  The name of a field on which to key the result array.
 427       *
 428       * @return  mixed   The return value or null if the query failed.
 429       *
 430       * @since   2.0.0
 431       * @throws  \RuntimeException
 432       */
 433  	public function loadRowList($key = null);
 434  
 435      /**
 436       * Locks a table in the database.
 437       *
 438       * @param   string  $tableName  The name of the table to unlock.
 439       *
 440       * @return  $this
 441       *
 442       * @since   2.0.0
 443       * @throws  \RuntimeException
 444       */
 445  	public function lockTable($tableName);
 446  
 447      /**
 448       * Quotes and optionally escapes a string to database requirements for use in database queries.
 449       *
 450       * @param   array|string  $text    A string or an array of strings to quote.
 451       * @param   boolean       $escape  True (default) to escape the string, false to leave it unchanged.
 452       *
 453       * @return  string
 454       *
 455       * @since   2.0.0
 456       */
 457  	public function quote($text, $escape = true);
 458  
 459      /**
 460       * Quotes a binary string to database requirements for use in database queries.
 461       *
 462       * @param   string  $data  A binary string to quote.
 463       *
 464       * @return  string  The binary quoted input string.
 465       *
 466       * @since   1.7.0
 467       */
 468  	public function quoteBinary($data);
 469  
 470      /**
 471       * Wrap an SQL statement identifier name such as column, table or database names in quotes to prevent injection
 472       * risks and reserved word conflicts.
 473       *
 474       * @param   array|string  $name  The identifier name to wrap in quotes, or an array of identifier names to wrap in quotes.
 475       *                               Each type supports dot-notation name.
 476       * @param   array|string  $as    The AS query part associated to $name. It can be string or array, in latter case it has to be
 477       *                               same length of $name; if is null there will not be any AS part for string or array element.
 478       *
 479       * @return  array|string  The quote wrapped name, same type of $name.
 480       *
 481       * @since   2.0.0
 482       */
 483  	public function quoteName($name, $as = null);
 484  
 485      /**
 486       * Renames a table in the database.
 487       *
 488       * @param   string  $oldTable  The name of the table to be renamed
 489       * @param   string  $newTable  The new name for the table.
 490       * @param   string  $backup    Table prefix
 491       * @param   string  $prefix    For the table - used to rename constraints in non-mysql databases
 492       *
 493       * @return  $this
 494       *
 495       * @since   2.0.0
 496       * @throws  \RuntimeException
 497       */
 498  	public function renameTable($oldTable, $newTable, $backup = null, $prefix = null);
 499  
 500      /**
 501       * This function replaces a string identifier with the configured table prefix.
 502       *
 503       * @param   string  $sql     The SQL statement to prepare.
 504       * @param   string  $prefix  The table prefix.
 505       *
 506       * @return  string  The processed SQL statement.
 507       *
 508       * @since   2.0.0
 509       */
 510  	public function replacePrefix($sql, $prefix = '#__');
 511  
 512      /**
 513       * Select a database for use.
 514       *
 515       * @param   string  $database  The name of the database to select for use.
 516       *
 517       * @return  boolean
 518       *
 519       * @since   2.0.0
 520       * @throws  \RuntimeException
 521       */
 522  	public function select($database);
 523  
 524      /**
 525       * Sets the SQL statement string for later execution.
 526       *
 527       * @param   mixed    $query   The SQL statement to set either as a Query object or a string.
 528       * @param   integer  $offset  The affected row offset to set. {@deprecated 3.0 Use LimitableInterface::setLimit() instead}
 529       * @param   integer  $limit   The maximum affected rows to set. {@deprecated 3.0 Use LimitableInterface::setLimit() instead}
 530       *
 531       * @return  $this
 532       *
 533       * @since   2.0.0
 534       */
 535  	public function setQuery($query, $offset = 0, $limit = 0);
 536  
 537      /**
 538       * Method to commit a transaction.
 539       *
 540       * @param   boolean  $toSavepoint  If true, commit to the last savepoint.
 541       *
 542       * @return  void
 543       *
 544       * @since   2.0.0
 545       * @throws  \RuntimeException
 546       */
 547  	public function transactionCommit($toSavepoint = false);
 548  
 549      /**
 550       * Method to roll back a transaction.
 551       *
 552       * @param   boolean  $toSavepoint  If true, rollback to the last savepoint.
 553       *
 554       * @return  void
 555       *
 556       * @since   2.0.0
 557       * @throws  \RuntimeException
 558       */
 559  	public function transactionRollback($toSavepoint = false);
 560  
 561      /**
 562       * Method to initialize a transaction.
 563       *
 564       * @param   boolean  $asSavepoint  If true and a transaction is already active, a savepoint will be created.
 565       *
 566       * @return  void
 567       *
 568       * @since   2.0.0
 569       * @throws  \RuntimeException
 570       */
 571  	public function transactionStart($asSavepoint = false);
 572  
 573      /**
 574       * Method to truncate a table.
 575       *
 576       * @param   string  $table  The table to truncate
 577       *
 578       * @return  void
 579       *
 580       * @since   2.0.0
 581       * @throws  \RuntimeException
 582       */
 583  	public function truncateTable($table);
 584  
 585      /**
 586       * Unlocks tables in the database.
 587       *
 588       * @return  $this
 589       *
 590       * @since   2.0.0
 591       * @throws  \RuntimeException
 592       */
 593  	public function unlockTables();
 594  
 595      /**
 596       * Updates a row in a table based on an object's properties.
 597       *
 598       * @param   string        $table   The name of the database table to update.
 599       * @param   object        $object  A reference to an object whose public properties match the table fields.
 600       * @param   array|string  $key     The name of the primary key.
 601       * @param   boolean       $nulls   True to update null fields or false to ignore them.
 602       *
 603       * @return  boolean
 604       *
 605       * @since   2.0.0
 606       * @throws  \RuntimeException
 607       */
 608  	public function updateObject($table, &$object, $key, $nulls = false);
 609  }