<?php
/**
* Part of the Joomla Framework Database Package
*
* @copyright Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE
*/
namespace Joomla\Database;
/**
* Joomla Framework Database Interface
*
* @since 1.0
*/
interface DatabaseInterface
{
/**
* Connects to the database if needed.
*
* @return void
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function connect();
/**
* Determines if the connection to the server is active.
*
* @return boolean
*
* @since 2.0.0
*/
public function connected();
/**
* Create a new database using information from $options object.
*
* @param \stdClass $options Object used to pass user and database name to database driver. This object must have "db_name" and "db_user" set.
* @param boolean $utf True if the database supports the UTF-8 character set.
*
* @return boolean|resource
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function createDatabase($options, $utf = true);
/**
* Replace special placeholder representing binary field with the original string.
*
* @param string|resource $data Encoded string or resource.
*
* @return string The original string.
*
* @since 1.7.0
*/
public function decodeBinary($data);
/**
* Disconnects the database.
*
* @return void
*
* @since 2.0.0
*/
public function disconnect();
/**
* Drops a table from the database.
*
* @param string $table The name of the database table to drop.
* @param boolean $ifExists Optionally specify that the table must exist before it is dropped.
*
* @return $this
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function dropTable($table, $ifExists = true);
/**
* Escapes a string for usage in an SQL statement.
*
* @param string $text The string to be escaped.
* @param boolean $extra Optional parameter to provide extra escaping.
*
* @return string The escaped string.
*
* @since 2.0.0
*/
public function escape($text, $extra = false);
/**
* Execute the SQL statement.
*
* @return boolean
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function execute();
/**
* Get the number of affected rows for the previous executed SQL statement.
*
* @return integer
*
* @since 2.0.0
*/
public function getAffectedRows();
/**
* Method to get the database collation in use by sampling a text field of a table in the database.
*
* @return string|boolean The collation in use by the database or boolean false if not supported.
*
* @since 2.0.0
*/
public function getCollation();
/**
* Method that provides access to the underlying database connection.
*
* @return resource The underlying database connection resource.
*
* @since 2.0.0
*/
public function getConnection();
/**
* Method to get the database connection collation, as reported by the driver.
*
* If the connector doesn't support reporting this value please return an empty string.
*
* @return string
*
* @since 2.0.0
*/
public function getConnectionCollation();
/**
* Method to get the database encryption details (cipher and protocol) in use.
*
* @return string The database encryption details.
*
* @since 2.0.0
*/
public function getConnectionEncryption(): string;
/**
* Method to test if the database TLS connections encryption are supported.
*
* @return boolean Whether the database supports TLS connections encryption.
*
* @since 2.0.0
*/
public function isConnectionEncryptionSupported(): bool;
/**
* Method to check whether the installed database version is supported by the database driver
*
* @return boolean True if the database version is supported
*
* @since 2.0.0
*/
public function isMinimumVersion();
/**
* Get the total number of SQL statements executed by the database driver.
*
* @return integer
*
* @since 2.0.0
*/
public function getCount();
/**
* Returns a PHP date() function compliant date format for the database driver.
*
* @return string
*
* @since 2.0.0
*/
public function getDateFormat();
/**
* Get the minimum supported database version.
*
* @return string
*
* @since 2.0.0
*/
public function getMinimum();
/**
* Get the name of the database driver.
*
* @return string
*
* @since 2.0.0
*/
public function getName();
/**
* Get the null or zero representation of a timestamp for the database driver.
*
* @return string
*
* @since 2.0.0
*/
public function getNullDate();
/**
* Get the common table prefix for the database driver.
*
* @return string The common database table prefix.
*
* @since 3.0
*/
public function getPrefix();
/**
* Get the number of returned rows for the previous executed SQL statement.
*
* @return integer
*
* @since 2.0.0
*/
public function getNumRows();
/**
* Get the current query object or a new QueryInterface object.
*
* @param boolean $new False to return the current query object, True to return a new QueryInterface object.
*
* @return QueryInterface
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function getQuery($new = false);
/**
* Get the server family type.
*
* @return string
*
* @since 2.0.0
*/
public function getServerType();
/**
* Retrieves field information about the given tables.
*
* @param string $table The name of the database table.
* @param boolean $typeOnly True (default) to only return field types.
*
* @return array
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function getTableColumns($table, $typeOnly = true);
/**
* Retrieves field information about the given tables.
*
* @param mixed $tables A table name or a list of table names.
*
* @return array
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function getTableKeys($tables);
/**
* Method to get an array of all tables in the database.
*
* @return array
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function getTableList();
/**
* Get the version of the database connector.
*
* @return string
*
* @since 2.0.0
*/
public function getVersion();
/**
* Determine whether or not the database engine supports UTF-8 character encoding.
*
* @return boolean True if the database engine supports UTF-8 character encoding.
*
* @since 2.0.0
*/
public function hasUtfSupport();
/**
* Method to get the auto-incremented value from the last INSERT statement.
*
* @return mixed The value of the auto-increment field from the last inserted row.
*
* @since 2.0.0
*/
public function insertid();
/**
* Inserts a row into a table based on an object's properties.
*
* @param string $table The name of the database table to insert into.
* @param object $object A reference to an object whose public properties match the table fields.
* @param string $key The name of the primary key. If provided the object property is updated.
*
* @return boolean
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function insertObject($table, &$object, $key = null);
/**
* Test to see if the connector is available.
*
* @return boolean
*
* @since 1.0
*/
public static function isSupported();
/**
* Method to get the first row of the result set from the database query as an associative array of ['field_name' => 'row_value'].
*
* @return mixed The return value or null if the query failed.
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function loadAssoc();
/**
* Method to get an array of the result set rows from the database query where each row is an associative array
* of ['field_name' => 'row_value']. The array of rows can optionally be keyed by a field name, but defaults to
* a sequential numeric array.
*
* NOTE: Choosing to key the result array by a non-unique field name can result in unwanted
* behavior and should be avoided.
*
* @param string $key The name of a field on which to key the result array.
* @param string $column An optional column name. Instead of the whole row, only this column value will be in the result array.
*
* @return mixed The return value or null if the query failed.
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function loadAssocList($key = null, $column = null);
/**
* Method to get an array of values from the <var>$offset</var> field in each row of the result set from the database query.
*
* @param integer $offset The row offset to use to build the result array.
*
* @return mixed The return value or null if the query failed.
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function loadColumn($offset = 0);
/**
* Method to get the first row of the result set from the database query as an object.
*
* @param string $class The class name to use for the returned row object.
*
* @return mixed The return value or null if the query failed.
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function loadObject($class = \stdClass::class);
/**
* Method to get an array of the result set rows from the database query where each row is an object. The array
* of objects can optionally be keyed by a field name, but defaults to a sequential numeric array.
*
* NOTE: Choosing to key the result array by a non-unique field name can result in unwanted behavior and should be avoided.
*
* @param string $key The name of a field on which to key the result array.
* @param string $class The class name to use for the returned row objects.
*
* @return mixed The return value or null if the query failed.
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function loadObjectList($key = '', $class = \stdClass::class);
/**
* Method to get the first field of the first row of the result set from the database query.
*
* @return mixed The return value or null if the query failed.
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function loadResult();
/**
* Method to get the first row of the result set from the database query as an array.
*
* Columns are indexed numerically so the first column in the result set would be accessible via <var>$row[0]</var>, etc.
*
* @return mixed The return value or null if the query failed.
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function loadRow();
/**
* Method to get an array of the result set rows from the database query where each row is an array. The array
* of objects can optionally be keyed by a field offset, but defaults to a sequential numeric array.
*
* NOTE: Choosing to key the result array by a non-unique field can result in unwanted behavior and should be avoided.
*
* @param string $key The name of a field on which to key the result array.
*
* @return mixed The return value or null if the query failed.
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function loadRowList($key = null);
/**
* Locks a table in the database.
*
* @param string $tableName The name of the table to unlock.
*
* @return $this
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function lockTable($tableName);
/**
* Quotes and optionally escapes a string to database requirements for use in database queries.
*
* @param array|string $text A string or an array of strings to quote.
* @param boolean $escape True (default) to escape the string, false to leave it unchanged.
*
* @return string
*
* @since 2.0.0
*/
public function quote($text, $escape = true);
/**
* Quotes a binary string to database requirements for use in database queries.
*
* @param string $data A binary string to quote.
*
* @return string The binary quoted input string.
*
* @since 1.7.0
*/
public function quoteBinary($data);
/**
* Wrap an SQL statement identifier name such as column, table or database names in quotes to prevent injection
* risks and reserved word conflicts.
*
* @param array|string $name The identifier name to wrap in quotes, or an array of identifier names to wrap in quotes.
* Each type supports dot-notation name.
* @param array|string $as The AS query part associated to $name. It can be string or array, in latter case it has to be
* same length of $name; if is null there will not be any AS part for string or array element.
*
* @return array|string The quote wrapped name, same type of $name.
*
* @since 2.0.0
*/
public function quoteName($name, $as = null);
/**
* Renames a table in the database.
*
* @param string $oldTable The name of the table to be renamed
* @param string $newTable The new name for the table.
* @param string $backup Table prefix
* @param string $prefix For the table - used to rename constraints in non-mysql databases
*
* @return $this
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function renameTable($oldTable, $newTable, $backup = null, $prefix = null);
/**
* This function replaces a string identifier with the configured table prefix.
*
* @param string $sql The SQL statement to prepare.
* @param string $prefix The table prefix.
*
* @return string The processed SQL statement.
*
* @since 2.0.0
*/
public function replacePrefix($sql, $prefix = '#__');
/**
* Select a database for use.
*
* @param string $database The name of the database to select for use.
*
* @return boolean
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function select($database);
/**
* Sets the SQL statement string for later execution.
*
* @param mixed $query The SQL statement to set either as a Query object or a string.
* @param integer $offset The affected row offset to set. {@deprecated 3.0 Use LimitableInterface::setLimit() instead}
* @param integer $limit The maximum affected rows to set. {@deprecated 3.0 Use LimitableInterface::setLimit() instead}
*
* @return $this
*
* @since 2.0.0
*/
public function setQuery($query, $offset = 0, $limit = 0);
/**
* Method to commit a transaction.
*
* @param boolean $toSavepoint If true, commit to the last savepoint.
*
* @return void
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function transactionCommit($toSavepoint = false);
/**
* Method to roll back a transaction.
*
* @param boolean $toSavepoint If true, rollback to the last savepoint.
*
* @return void
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function transactionRollback($toSavepoint = false);
/**
* Method to initialize a transaction.
*
* @param boolean $asSavepoint If true and a transaction is already active, a savepoint will be created.
*
* @return void
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function transactionStart($asSavepoint = false);
/**
* Method to truncate a table.
*
* @param string $table The table to truncate
*
* @return void
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function truncateTable($table);
/**
* Unlocks tables in the database.
*
* @return $this
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function unlockTables();
/**
* Updates a row in a table based on an object's properties.
*
* @param string $table The name of the database table to update.
* @param object $object A reference to an object whose public properties match the table fields.
* @param array|string $key The name of the primary key.
* @param boolean $nulls True to update null fields or false to ignore them.
*
* @return boolean
*
* @since 2.0.0
* @throws \RuntimeException
*/
public function updateObject($table, &$object, $key, $nulls = false);
}