From fabf46115687b5bc7e007b538247df7f2f40d1ae Mon Sep 17 00:00:00 2001 From: Chuck Hagenbuch Date: Sat, 29 May 2010 22:20:30 -0400 Subject: [PATCH] Add Horde_Db_Adapter interface --- framework/Db/lib/Horde/Db/Adapter.php | 297 +++++++++++++++++++++++++++++ framework/Db/lib/Horde/Db/Adapter/Base.php | 8 +- framework/Db/package.xml | 2 + 3 files changed, 300 insertions(+), 7 deletions(-) create mode 100644 framework/Db/lib/Horde/Db/Adapter.php diff --git a/framework/Db/lib/Horde/Db/Adapter.php b/framework/Db/lib/Horde/Db/Adapter.php new file mode 100644 index 000000000..d0cf41e9e --- /dev/null +++ b/framework/Db/lib/Horde/Db/Adapter.php @@ -0,0 +1,297 @@ + + * @author Derek DeVries + * @author Chuck Hagenbuch + * @license http://opensource.org/licenses/bsd-license.php + * @category Horde + * @package Horde_Db + * @subpackage Adapter + */ + +/** + * @author Mike Naberezny + * @author Derek DeVries + * @author Chuck Hagenbuch + * @license http://opensource.org/licenses/bsd-license.php + * @category Horde + * @package Horde_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(); + + + /*########################################################################## + # 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 PDOStatement + * @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. + * + * @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 PDOStatement + * @throws Horde_Db_Exception + */ + public function execute($sql, $arg1 = null, $arg2 = null); + + /** + * Returns the last auto-generated ID from the affected table. + * + * @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. + * @param string $pk TODO + * @param integer $idValue TODO + * @param string $sequenceName TODO + * + * @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()); +} diff --git a/framework/Db/lib/Horde/Db/Adapter/Base.php b/framework/Db/lib/Horde/Db/Adapter/Base.php index 0b6b5de62..120083a37 100644 --- a/framework/Db/lib/Horde/Db/Adapter/Base.php +++ b/framework/Db/lib/Horde/Db/Adapter/Base.php @@ -21,7 +21,7 @@ * @package Horde_Db * @subpackage Adapter */ -abstract class Horde_Db_Adapter_Base +abstract class Horde_Db_Adapter_Base implements Horde_Db_Adapter { /** * Config options. @@ -316,11 +316,6 @@ abstract class Horde_Db_Adapter_Base ##########################################################################*/ /** - * Connect to the db. - */ - abstract public function connect(); - - /** * Is the connection active? * * @return boolean @@ -768,5 +763,4 @@ abstract class Horde_Db_Adapter_Base { return "SQL $message \n\t" . wordwrap(preg_replace("/\s+/", ' ', $sql), 70, "\n\t ", 1); } - } diff --git a/framework/Db/package.xml b/framework/Db/package.xml index 837919df1..7a12a3d9e 100644 --- a/framework/Db/package.xml +++ b/framework/Db/package.xml @@ -84,6 +84,7 @@ http://pear.php.net/dtd/package-2.0.xsd"> + @@ -153,6 +154,7 @@ http://pear.php.net/dtd/package-2.0.xsd"> + -- 2.11.0