From: Michael M Slusarz Date: Sat, 15 May 2010 22:20:04 +0000 (-0600) Subject: Db phpdoc X-Git-Url: https://git.internetallee.de/?a=commitdiff_plain;h=5d6be5721093385fbe36f81ab7b6053ad0a5a042;p=horde.git Db phpdoc --- diff --git a/framework/Db/lib/Horde/Db/Adapter/Base.php b/framework/Db/lib/Horde/Db/Adapter/Base.php index 14e489d6e..1b8c80fe6 100644 --- a/framework/Db/lib/Horde/Db/Adapter/Base.php +++ b/framework/Db/lib/Horde/Db/Adapter/Base.php @@ -97,9 +97,9 @@ abstract class Horde_Db_Adapter_Base * * @param array $config Configuration options and optional objects: * 
-     * 'cache' - TODO
+     * 'cache' - (Horde_Cache) Cache object.
      * 'charset' - (string) TODO
-     * 'logger' - TODO
+     * 'logger' - (Horde_Log_Logger) Logging object.
      * 'write_db' - (Horde_Db_Adapter_Base) Use this DB for write operations.
      *
*/ @@ -162,6 +162,8 @@ abstract class Horde_Db_Adapter_Base * * @param string $method * @param array $args + * + * @return TODO */ public function componentFactory($component, $args) { @@ -185,6 +187,9 @@ abstract class Horde_Db_Adapter_Base * * @param string $method * @param array $args + * + * @return mixed TODO + * @throws BadMethodCallException */ public function __call($method, $args) { @@ -204,7 +209,7 @@ abstract class Horde_Db_Adapter_Base * Returns the human-readable name of the adapter. Use mixed case - one * can always use downcase if needed. * - * @return string + * @return string */ public function adapterName() { @@ -215,7 +220,7 @@ abstract class Horde_Db_Adapter_Base * Does this adapter support migrations? Backend specific, as the * abstract adapter always returns +false+. * - * @return boolean + * @return boolean */ public function supportsMigrations() { @@ -226,7 +231,7 @@ abstract class Horde_Db_Adapter_Base * Does this adapter support using DISTINCT within COUNT? This is +true+ * for all adapters except sqlite. * - * @return boolean + * @return boolean */ public function supportsCountDistinct() { @@ -238,6 +243,8 @@ abstract class Horde_Db_Adapter_Base * 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) { @@ -247,12 +254,13 @@ abstract class Horde_Db_Adapter_Base /** * Reset the timer * - * @return int + * @return integer */ public function resetRuntime() { $runtime = $this->_runtime; $this->_runtime = 0; + return $this->_runtime; } @@ -262,14 +270,14 @@ abstract class Horde_Db_Adapter_Base ##########################################################################*/ /** - * Connect to the db + * Connect to the db. */ abstract public function connect(); /** - * Is the connection active + * Is the connection active? * - * @return boolean + * @return boolean */ public function isActive() { @@ -277,7 +285,7 @@ abstract class Horde_Db_Adapter_Base } /** - * Reconnect to the db + * Reconnect to the db. */ public function reconnect() { @@ -286,7 +294,7 @@ abstract class Horde_Db_Adapter_Base } /** - * Disconnect from db + * Disconnect from db. */ public function disconnect() { @@ -296,9 +304,10 @@ abstract class Horde_Db_Adapter_Base /** * Provides access to the underlying database connection. Useful for when - * you need to call a proprietary method such as postgresql's lo_* methods + * you need to call a proprietary method such as postgresql's + * lo_* methods. * - * @return resource + * @return resource */ public function rawConnection() { @@ -314,10 +323,14 @@ abstract class Horde_Db_Adapter_Base * Returns an array of records with the column names as keys, and * column values as values. * - * @param string $sql - * @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 Traversable + * @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 Traversable + * @throws Horde_Db_Exception */ public function select($sql, $arg1 = null, $arg2 = null) { @@ -328,9 +341,14 @@ abstract class Horde_Db_Adapter_Base * Returns an array of record hashes with the column names as keys and * column values as values. * - * @param string $sql - * @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 $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) { @@ -348,38 +366,56 @@ abstract class Horde_Db_Adapter_Base * Returns a record hash with the column names as keys and column values * as values. * - * @param string $sql - * @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 + * @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) { $result = $this->selectAll($sql, $arg1, $arg2); - return $result ? next($result) : array(); + return $result + ? next($result) + : array(); } /** * Returns a single value from a record * - * @param string $sql - * @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 + * @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) { $result = $this->selectOne($sql, $arg1, $arg2); - return $result ? next($result) : null; + + return $result + ? next($result) + : 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 - * @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 $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) { @@ -397,9 +433,14 @@ abstract class Horde_Db_Adapter_Base * * selectAssoc("SELECT id, name FROM companies LIMIT 3") => [1 => 'Ford', 2 => 'GM', 3 => 'Chrysler'] * - * @param string $sql - * @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 $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) { @@ -414,9 +455,14 @@ abstract class Horde_Db_Adapter_Base /** * Executes the SQL statement in the context of this connection. * - * @param string $sql - * @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 $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 Traversable + * @throws Horde_Db_Exception */ public function execute($sql, $arg1 = null, $arg2 = null) { @@ -439,37 +485,51 @@ abstract class Horde_Db_Adapter_Base } $this->_logInfo($sql, $name, $t->pop()); - $this->_rowCount = $stmt ? $stmt->rowCount() : 0; + return $stmt; } /** * Returns the last auto-generated ID from the affected table. * - * @param string $sql - * @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 - * @param int $idValue - * @param string $sequenceName + * @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 TODO + * @throws Horde_Db_Exception */ - public function insert($sql, $arg1 = null, $arg2 = null, $pk = null, $idValue = null, $sequenceName = null) + public function insert($sql, $arg1 = null, $arg2 = null, $pk = null, + $idValue = null, $sequenceName = null) { if ($this->_write) { return $this->_write->insert($sql, $arg1, $arg2, $pk, $idValue, $sequenceName); } $this->execute($sql, $arg1, $arg2); - return isset($idValue) ? $idValue : $this->_connection->lastInsertId(); + + return isset($idValue) + ? $idValue + : $this->_connection->lastInsertId(); } /** * Executes the update statement and returns the number of rows affected. * - * @param string $sql - * @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 $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) { @@ -484,9 +544,14 @@ abstract class Horde_Db_Adapter_Base /** * Executes the delete statement and returns the number of rows affected. * - * @param string $sql - * @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 $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) { @@ -499,7 +564,9 @@ abstract class Horde_Db_Adapter_Base } /** - * Check if a transaction has been started + * Check if a transaction has been started. + * + * @return boolean True if transaction has been started. */ public function transactionStarted() { @@ -515,7 +582,7 @@ abstract class Horde_Db_Adapter_Base { if ($this->_write) { $this->_write->beginDbTransaction(); - } else { + } elseif (!$this->_transactionStarted) { $this->_transactionStarted = true; $this->_connection->beginTransaction(); } @@ -528,7 +595,7 @@ abstract class Horde_Db_Adapter_Base { if ($this->_write) { $this->_write->commitDbTransaction(); - } else { + } elseif ($this->_transactionStarted) { $this->_connection->commit(); $this->_transactionStarted = false; } @@ -540,11 +607,9 @@ abstract class Horde_Db_Adapter_Base */ public function rollbackDbTransaction() { - if (! $this->_transactionStarted) { return; } - if ($this->_write) { $this->_write->rollbackDbTransaction(); - } else { + } elseif ($this->_transactionStarted) { $this->_connection->rollBack(); $this->_transactionStarted = false; } @@ -553,9 +618,10 @@ abstract class Horde_Db_Adapter_Base /** * Appends +LIMIT+ and +OFFSET+ options to a SQL statement. * - * @param string $sql - * @param array $options - * @return string + * @param string $sql SQL statement. + * @param array $options TODO + * + * @return string */ public function addLimitOffset($sql, $options) { @@ -569,32 +635,42 @@ abstract class Horde_Db_Adapter_Base return $sql; } + /** + * TODO + */ public function sanitizeLimit($limit) { - if (strpos($limit, ',') !== false) { - return implode(',', array_map(create_function('$i', 'return (int)$i;'), explode(',', $limit))); - } else return (int)$limit; + return (strpos($limit, ',') !== false) + ? implode(',', array_map('intval', explode(',', $limit))) + : intval($limit); } /** * 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, $options = array()) + public function addLock(&$sql, array $options = array()) { - if (isset($options['lock']) && is_string($options['lock'])) { - $sql .= ' ' . $lock; - } else { - $sql .= ' FOR UPDATE'; - } + $sql .= (isset($options['lock']) && is_string($options['lock'])) + ? ' ' . $lock + : ' FOR UPDATE'; } /** * Inserts the given fixture into the table. Overridden in adapters that * require something beyond a simple insert (eg. Oracle). + * + * @param TODO $fixture TODO + * @param TODO $tableName TODO + * + * @return TODO */ public function insertFixture($fixture, $tableName) { @@ -606,9 +682,16 @@ abstract class Horde_Db_Adapter_Base } } + /** + * TODO + * + * @param string $tableName TODO + * + * @return string TODO + */ public function emptyInsertStatement($tableName) { - return 'INSERT INTO '.$this->quoteTableName($tableName).' VALUES(DEFAULT)'; + return 'INSERT INTO ' . $this->quoteTableName($tableName) . ' VALUES(DEFAULT)'; } @@ -619,8 +702,11 @@ abstract class Horde_Db_Adapter_Base /** * Replace ? in a SQL statement with quoted values from $args * - * @param string $sql - * @param array $args + * @param string $sql SQL statement. + * @param array $args TODO + * + * @return string Modified SQL statement. + * @throws Horde_Db_Exception */ protected function _replaceParameters($sql, $args) { @@ -640,9 +726,9 @@ abstract class Horde_Db_Adapter_Base /** * Logs the SQL query for debugging. * - * @param string $sql - * @param string $name - * @param float $runtime + * @param string $sql SQL statement. + * @param string $name TODO + * @param float $runtime Runtime interval. */ protected function _logInfo($sql, $name, $runtime = null) { @@ -655,14 +741,14 @@ abstract class Horde_Db_Adapter_Base /** * Formats the log entry. * - * @param string $message - * @param string $sql + * @param string $message Message. + * @param string $sql SQL statment. + * + * @return string Formatted log entry. */ protected function _formatLogEntry($message, $sql) { - $sql = preg_replace("/\s+/", ' ', $sql); - $sql = "\n\t".wordwrap($sql, 70, "\n\t ", 1); - return "SQL $message $sql"; + return "SQL $message \n\t" . wordwrap(preg_replace("/\s+/", ' ', $sql), 70, "\n\t ", 1); } }