Skip to content

Commit

Permalink
Merge pull request #1484 from corpsee/1.7/develop
Browse files Browse the repository at this point in the history 
Improved documentation
  • Loading branch information
@frankdejonge
frankdejonge committed Jul 16, 2013
2 parents a1ac30d + 318fac8 commit 1a25193
Show file tree
Hide file tree
Showing 13 changed files with 354 additions and 135 deletions.
54 changes: 37 additions & 17 deletions classes/database/connection.php
View file
Expand Up @@ -33,9 +33,12 @@ abstract class Database_Connection
* // Create a custom configured instance
* $db = static::instance('custom', $config);
*
* @param string instance name
* @param array configuration parameters
* @param string $name instance name
* @param array $config configuration parameters
*
* @return Database_Connection
*
* @throws \FuelException
*/
public static function instance($name = null, array $config = null)
{
Expand Down Expand Up @@ -99,7 +102,8 @@ public static function instance($name = null, array $config = null)
*
* [!!] This method cannot be accessed directly, you must use [static::instance].
*
* @return void
* @param string $name
* @param array $config
*/
protected function __construct($name, array $config)
{
Expand Down Expand Up @@ -167,7 +171,7 @@ abstract public function disconnect();
* $db->set_charset('utf8');
*
* @throws Database_Exception
* @param string character set name
* @param string $charset character set name
* @return void
*/
abstract public function set_charset($charset);
Expand All @@ -181,9 +185,10 @@ abstract public function set_charset($charset);
* // Make a SELECT query and use "Model_User" for the results
* $db->query(static::SELECT, 'SELECT * FROM users LIMIT 1', 'Model_User');
*
* @param integer static::SELECT, static::INSERT, etc
* @param string SQL query
* @param mixed result object class, true for stdClass, false for assoc array
* @param integer $type static::SELECT, static::INSERT, etc
* @param string $sql SQL query
* @param mixed $as_object result object class, true for stdClass, false for assoc array
*
* @return object Database_Result for SELECT queries
* @return array list (insert id, row count) for INSERT queries
* @return integer number of affected rows for all other queries
Expand Down Expand Up @@ -240,6 +245,7 @@ public function count_last_query()
* Per connection cache controlle setter/getter
*
* @param bool $bool wether to enable it [optional]
*
* @return mixed cache boolean when getting, current instance when setting.
*/
public function caching($bool = null)
Expand All @@ -258,7 +264,8 @@ public function caching($bool = null)
* // Get the total number of records in the "users" table
* $count = $db->count_records('users');
*
* @param mixed table name string or array(query, alias)
* @param mixed $table table name string or array(query, alias)
*
* @return integer
*/
public function count_records($table)
Expand All @@ -275,7 +282,8 @@ public function count_records($table)
*
* $db->datatype('char');
*
* @param string SQL data type
* @param string $type SQL data type
*
* @return array
*/
public function datatype($type)
Expand Down Expand Up @@ -350,7 +358,8 @@ public function datatype($type)
* // Get all user-related tables
* $tables = $db->list_tables('user%');
*
* @param string table to search for
* @param string $like table to search for
*
* @return array
*/
abstract public function list_tables($like = null);
Expand All @@ -365,8 +374,9 @@ abstract public function list_tables($like = null);
* // Get all name-related columns
* $columns = $db->list_columns('users', '%name%');
*
* @param string table to get columns from
* @param string column to search for
* @param string $table table to get columns from
* @param string $like column to search for
*
* @return array
*/
abstract public function list_columns($table, $like = null);
Expand All @@ -377,7 +387,8 @@ abstract public function list_columns($table, $like = null);
* // Returns: array('CHAR', '6')
* list($type, $length) = $db->_parse_type('CHAR(6)');
*
* @param string
* @param string $type
*
* @return array list containing the type and length, if any
*/
protected function _parse_type($type)
Expand Down Expand Up @@ -405,6 +416,8 @@ protected function _parse_type($type)
*
* $prefix = $db->table_prefix();
*
* @param string $table
*
* @return string
*/
public function table_prefix($table = null)
Expand All @@ -429,8 +442,10 @@ public function table_prefix($table = null)
* [Database_Query] objects will be compiled and converted to a sub-query.
* All other objects will be converted using the `__toString` method.
*
* @param mixed any value to quote
* @param mixed $value any value to quote
*
* @return string
*
* @uses static::escape
*/
public function quote($value)
Expand Down Expand Up @@ -487,8 +502,10 @@ public function quote($value)
*
* $table = $db->quote_table($table);
*
* @param mixed table name or array(table, alias)
* @param mixed $value table name or array(table, alias)
*
* @return string
*
* @uses static::quote_identifier
* @uses static::table_prefix
*/
Expand Down Expand Up @@ -578,8 +595,10 @@ public function quote_table($value)
* [Database_Query] objects will be compiled and converted to a sub-query.
* All other objects will be converted using the `__toString` method.
*
* @param mixed any identifier
* @param mixed $value any identifier
*
* @return string
*
* @uses static::table_prefix
*/
public function quote_identifier($value)
Expand Down Expand Up @@ -654,7 +673,8 @@ public function quote_identifier($value)
*
* $value = $db->escape('any string');
*
* @param string value to quote
* @param string $value value to quote
*
* @return string
*/
abstract public function escape($value);
Expand Down
2 changes: 1 addition & 1 deletion classes/database/expression.php
View file
Expand Up @@ -30,7 +30,7 @@ class Database_Expression
*
* $expression = new Database_Expression('COUNT(users.id)');
*
* @return void
* @param string $value expression string
*/
public function __construct($value)
{
Expand Down
59 changes: 59 additions & 0 deletions classes/database/pdo/connection.php
View file
Expand Up @@ -34,6 +34,10 @@ class Database_PDO_Connection extends \Database_Connection
*/
public $_db_type = '';

/**
* @param string $name
* @param array $config
*/
protected function __construct($name, array $config)
{
parent::__construct($name, $config);
Expand All @@ -45,6 +49,9 @@ protected function __construct($name, array $config)
}
}

/**
* @throws \Database_Exception
*/
public function connect()
{
if ($this->_connection)
Expand Down Expand Up @@ -109,6 +116,9 @@ public function connect()
}
}

/**
* @return bool
*/
public function disconnect()
{
// Destroy the PDO object
Expand All @@ -119,13 +129,17 @@ public function disconnect()

/**
* Get the current PDO Driver name
*
* @return string
*/
public function driver_name()
{
return $this->_connection->getAttribute(\PDO::ATTR_DRIVER_NAME);
}

/**
* @param string $charset
*/
public function set_charset($charset)
{
// Make sure the database is connected
Expand All @@ -135,6 +149,15 @@ public function set_charset($charset)
$this->_connection->exec('SET NAMES '.$this->quote($charset));
}

/**
* @param integer $type
* @param string $sql
* @param mixed $as_object
*
* @return mixed
*
* @throws \Database_Exception
*/
public function query($type, $sql, $as_object)
{
// Make sure the database is connected
Expand Down Expand Up @@ -263,11 +286,22 @@ public function query($type, $sql, $as_object)
}
}

/**
* @param string $like
*
* @throws \FuelException
*/
public function list_tables($like = null)
{
throw new \FuelException('Database method '.__METHOD__.' is not supported by '.__CLASS__);
}

/**
* @param string $table
* @param string $like
*
* @return array
*/
public function list_columns($table, $like = null)
{
$this->_connection or $this->connect();
Expand Down Expand Up @@ -343,6 +377,11 @@ public function list_columns($table, $like = null)
return $columns;
}

/**
* @param integer $type
*
* @return array
*/
public function datatype($type)
{
// try to determine the datatype
Expand All @@ -352,6 +391,11 @@ public function datatype($type)
return empty($datatype) ? array('type' => 'string') : $datatype;
}

/**
* @param mixed $value
*
* @return string
*/
public function escape($value)
{
// Make sure the database is connected
Expand All @@ -366,29 +410,44 @@ public function escape($value)
return $result;
}

/**
* @return array
*/
public function error_info()
{
return $this->_connection->errorInfo();
}

/**
* @return bool
*/
public function in_transaction()
{
return $this->_in_transaction;
}

/**
* @return bool
*/
public function start_transaction()
{
$this->_connection or $this->connect();
$this->_in_transaction = true;
return $this->_connection->beginTransaction();
}

/**
* @return bool
*/
public function commit_transaction()
{
$this->_in_transaction = false;
return $this->_connection->commit();
}

/**
* @return bool
*/
public function rollback_transaction()
{
$this->_in_transaction = false;
Expand Down

0 comments on commit 1a25193

Please sign in to comment.