/framework/Db/lib/Horde/Db/Adapter.php
PHP | 314 lines | 31 code | 32 blank | 251 comment | 0 complexity | 17498494170e689a0aa0fc65b04edaa5 MD5 | raw file
- <?php
- /**
- * Copyright 2007 Maintainable Software, LLC
- * Copyright 2008-2014 Horde LLC (http://www.horde.org/)
- *
- * @author Mike Naberezny <mike@maintainable.com>
- * @author Derek DeVries <derek@maintainable.com>
- * @author Chuck Hagenbuch <chuck@horde.org>
- * @license http://www.horde.org/licenses/bsd
- * @category Horde
- * @package Db
- * @subpackage Adapter
- */
- /**
- * @author Mike Naberezny <mike@maintainable.com>
- * @author Derek DeVries <derek@maintainable.com>
- * @author Chuck Hagenbuch <chuck@horde.org>
- * @license http://www.horde.org/licenses/bsd
- * @category Horde
- * @package Db
- * @subpackage Adapter
- */
- interface Horde_Db_Adapter
- {
- /**
- * Returns the human-readable name of the adapter. Use mixed case - one
- * can always use downcase if needed.
- *
- * @return string
- */
- public function adapterName();
- /**
- * Does this adapter support migrations? Backend specific, as the
- * abstract adapter always returns +false+.
- *
- * @return boolean
- */
- public function supportsMigrations();
- /**
- * Does this adapter support using DISTINCT within COUNT? This is +true+
- * for all adapters except sqlite.
- *
- * @return boolean
- */
- public function supportsCountDistinct();
- /**
- * Should primary key values be selected from their corresponding
- * sequence before the insert statement? If true, next_sequence_value
- * is called before each insert to set the record's primary key.
- * This is false for all adapters but Firebird.
- *
- * @return boolean
- */
- public function prefetchPrimaryKey($tableName = null);
- /*##########################################################################
- # Connection Management
- ##########################################################################*/
- /**
- * Connect to the db.
- */
- public function connect();
- /**
- * Is the connection active?
- *
- * @return boolean
- */
- public function isActive();
- /**
- * Reconnect to the db.
- */
- public function reconnect();
- /**
- * Disconnect from db.
- */
- public function disconnect();
- /**
- * Provides access to the underlying database connection. Useful for when
- * you need to call a proprietary method such as postgresql's
- * lo_* methods.
- *
- * @return resource
- */
- public function rawConnection();
- /*##########################################################################
- # Quoting
- ##########################################################################*/
- /**
- * Quotes a string, escaping any special characters.
- *
- * @param string $string
- * @return string
- */
- public function quoteString($string);
- /*##########################################################################
- # Database Statements
- ##########################################################################*/
- /**
- * Returns an array of records with the column names as keys, and
- * column values as values.
- *
- * @param string $sql SQL statement.
- * @param mixed $arg1 Either an array of bound parameters or a query
- * name.
- * @param string $arg2 If $arg1 contains bound parameters, the query
- * name.
- *
- * @return Horde_Db_Adapter_Base_Result
- * @throws Horde_Db_Exception
- */
- public function select($sql, $arg1 = null, $arg2 = null);
- /**
- * Returns an array of record hashes with the column names as keys and
- * column values as values.
- *
- * @param string $sql SQL statement.
- * @param mixed $arg1 Either an array of bound parameters or a query
- * name.
- * @param string $arg2 If $arg1 contains bound parameters, the query
- * name.
- *
- * @return array
- * @throws Horde_Db_Exception
- */
- public function selectAll($sql, $arg1 = null, $arg2 = null);
- /**
- * Returns a record hash with the column names as keys and column values
- * as values.
- *
- * @param string $sql SQL statement.
- * @param mixed $arg1 Either an array of bound parameters or a query
- * name.
- * @param string $arg2 If $arg1 contains bound parameters, the query
- * name.
- *
- * @return array
- * @throws Horde_Db_Exception
- */
- public function selectOne($sql, $arg1 = null, $arg2 = null);
- /**
- * Returns a single value from a record
- *
- * @param string $sql SQL statement.
- * @param mixed $arg1 Either an array of bound parameters or a query
- * name.
- * @param string $arg2 If $arg1 contains bound parameters, the query
- * name.
- *
- * @return string
- * @throws Horde_Db_Exception
- */
- public function selectValue($sql, $arg1 = null, $arg2 = null);
- /**
- * Returns an array of the values of the first column in a select:
- * selectValues("SELECT id FROM companies LIMIT 3") => [1,2,3]
- *
- * @param string $sql SQL statement.
- * @param mixed $arg1 Either an array of bound parameters or a query
- * name.
- * @param string $arg2 If $arg1 contains bound parameters, the query
- * name.
- *
- * @return array
- * @throws Horde_Db_Exception
- */
- public function selectValues($sql, $arg1 = null, $arg2 = null);
- /**
- * Returns an array where the keys are the first column of a select, and the
- * values are the second column:
- *
- * selectAssoc("SELECT id, name FROM companies LIMIT 3") => [1 => 'Ford', 2 => 'GM', 3 => 'Chrysler']
- *
- * @param string $sql SQL statement.
- * @param mixed $arg1 Either an array of bound parameters or a query
- * name.
- * @param string $arg2 If $arg1 contains bound parameters, the query
- * name.
- *
- * @return array
- * @throws Horde_Db_Exception
- */
- public function selectAssoc($sql, $arg1 = null, $arg2 = null);
- /**
- * Executes the SQL statement in the context of this connection.
- *
- * @deprecated Deprecated for external usage. Use select() instead.
- *
- * @param string $sql SQL statement.
- * @param mixed $arg1 Either an array of bound parameters or a query
- * name.
- * @param string $arg2 If $arg1 contains bound parameters, the query
- * name.
- *
- * @return mixed
- * @throws Horde_Db_Exception
- */
- public function execute($sql, $arg1 = null, $arg2 = null);
- /**
- * Inserts a row into a table.
- *
- * @param string $sql SQL statement.
- * @param array|string $arg1 Either an array of bound parameters or a
- * query name.
- * @param string $arg2 If $arg1 contains bound parameters, the
- * query name.
- * @param string $pk The primary key column.
- * @param integer $idValue The primary key value. This parameter is
- * required if the primary key is inserted
- * manually.
- * @param string $sequenceName The sequence name.
- *
- * @return integer Last inserted ID.
- * @throws Horde_Db_Exception
- */
- public function insert($sql, $arg1 = null, $arg2 = null, $pk = null,
- $idValue = null, $sequenceName = null);
- /**
- * Executes the update statement and returns the number of rows affected.
- *
- * @param string $sql SQL statement.
- * @param mixed $arg1 Either an array of bound parameters or a query
- * name.
- * @param string $arg2 If $arg1 contains bound parameters, the query
- * name.
- *
- * @return integer Number of rows affected.
- * @throws Horde_Db_Exception
- */
- public function update($sql, $arg1 = null, $arg2 = null);
- /**
- * Executes the delete statement and returns the number of rows affected.
- *
- * @param string $sql SQL statement.
- * @param mixed $arg1 Either an array of bound parameters or a query
- * name.
- * @param string $arg2 If $arg1 contains bound parameters, the query
- * name.
- *
- * @return integer Number of rows affected.
- * @throws Horde_Db_Exception
- */
- public function delete($sql, $arg1 = null, $arg2 = null);
- /**
- * Check if a transaction has been started.
- *
- * @return boolean True if transaction has been started.
- */
- public function transactionStarted();
- /**
- * Begins the transaction (and turns off auto-committing).
- */
- public function beginDbTransaction();
- /**
- * Commits the transaction (and turns on auto-committing).
- */
- public function commitDbTransaction();
- /**
- * Rolls back the transaction (and turns on auto-committing). Must be
- * done if the transaction block raises an exception or returns false.
- */
- public function rollbackDbTransaction();
- /**
- * Appends +LIMIT+ and +OFFSET+ options to a SQL statement.
- *
- * @param string $sql SQL statement.
- * @param array $options TODO
- *
- * @return string
- */
- public function addLimitOffset($sql, $options);
- /**
- * Appends a locking clause to an SQL statement.
- * This method *modifies* the +sql+ parameter.
- *
- * # SELECT * FROM suppliers FOR UPDATE
- * add_lock! 'SELECT * FROM suppliers', :lock => true
- * add_lock! 'SELECT * FROM suppliers', :lock => ' FOR UPDATE'
- *
- * @param string &$sql SQL statment.
- * @param array $options TODO.
- */
- public function addLock(&$sql, array $options = array());
- }