<?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 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);
}