adding better comments to database classes.

laravel/database/connection.php

@@ -1,5 +1,8 @@
 <?php namespace Laravel\Database;
 
+use PDO;
+use PDOStatement;
+
 class Connection {
 
 	/**
@@ -7,14 +10,21 @@ class Connection {
 	 *
 	 * @var string
 	 */
-	public $name;
+	protected $name;
 
 	/**
 	 * The connection configuration.
 	 *
 	 * @var array
 	 */
-	public $config;
+	protected $config;
+
+	/**
+	 * The database connector instance.
+	 *
+	 * @var Connector\Connector
+	 */
+	protected $connector;
 
 	/**
 	 * The PDO connection.
@@ -30,24 +40,17 @@ class Connection {
 	 */
 	public $queries = array();
 
-	/**
-	 * The database connector instance.
-	 *
-	 * @var Connector
-	 */
-	private $connector;
-
 	/**
 	 * Create a new Connection instance.
 	 *
-	 * @param  Connector         $connector
-	 * @param  Query\Factory     $factory
-	 * @param  Compiler\Factory  $compiler
-	 * @param  string            $name
-	 * @param  array             $config
+	 * @param  Connector\Connector $connector
+	 * @param  Query\Factory       $factory
+	 * @param  Compiler\Factory    $compiler
+	 * @param  string              $name
+	 * @param  array               $config
 	 * @return void
 	 */
-	public function __construct(Connector $connector, Query\Factory $query, Query\Compiler\Factory $compiler, $name, $config)
+	public function __construct(Connector\Connector $connector, Query\Factory $query, Query\Compiler\Factory $compiler, $name, $config)
 	{
 		$this->name = $name;
 		$this->query = $query;
@@ -79,9 +82,17 @@ class Connection {
 	/**
 	 * Execute a SQL query against the connection and return a scalar result.
 	 *
-	 * @param  string  $sql
-	 * @param  array   $bindings
-	 * @return mixed
+	 * <code>
+	 *		// Get the number of rows in the "users" table
+	 *		$count = DB::connection()->scalar('select count(*) from users');
+	 *
+	 *		// Get the sum of payments from the "bank" table
+	 *		$sum = DB::connection()->scalar('select sum(payment) from banks where bank_id = ?', array(1));
+	 * </code>
+	 *
+	 * @param  string     $sql
+	 * @param  array      $bindings
+	 * @return int|float
 	 */
 	public function scalar($sql, $bindings = array())
 	{
@@ -93,6 +104,14 @@ class Connection {
 	/**
 	 * Execute a SQL query against the connection and return the first result.
 	 *
+	 * <code>
+	 *		// Get the first result from the "users" table
+	 *		$user = DB::connection()->first('select * from users limit 1');
+	 *
+	 *		// Get the first result from a specified group of users
+	 *		$user = DB::connection()->first('select * from users where group_id = ?', array(1));
+	 * </code>
+	 *
 	 * @param  string  $sql
 	 * @param  array   $bindings
 	 * @return object
@@ -112,6 +131,14 @@ class Connection {
 	 *     DELETE -> Number of Rows affected.
 	 *     ELSE   -> Boolean true / false depending on success.
 	 *
+	 * <code>
+	 *		// Execute a query against the connection
+	 *		$users = DB::connection()->query('select * from users');
+	 *
+	 *		// Execute a query against the connection using bindings
+	 *		$users = DB::connection()->query('select * from users where group_id = ?', array(1));
+	 * </code>
+	 *
 	 * @param  string  $sql
 	 * @param  array   $bindings
 	 * @return mixed
@@ -132,13 +159,13 @@ class Connection {
 	 * @param  array         $results
 	 * @return mixed
 	 */
-	private function execute(\PDOStatement $statement, $bindings)
+	protected function execute(PDOStatement $statement, $bindings)
 	{
 		$result = $statement->execute($bindings);
 
 		if (strpos(strtoupper($statement->queryString), 'SELECT') === 0)
 		{
-			return $statement->fetchAll(\PDO::FETCH_CLASS, 'stdClass');
+			return $statement->fetchAll(PDO::FETCH_CLASS, 'stdClass');
 		}
 		elseif (strpos(strtoupper($statement->queryString), 'INSERT') === 0)
 		{
@@ -151,6 +178,11 @@ class Connection {
 	/**
 	 * Begin a fluent query against a table.
 	 *
+	 * <code>
+	 *		// Begin a fluent query against the "users" table
+	 *		$query = DB::connection()->table('users');
+	 * </code>
+	 *
 	 * @param  string  $table
 	 * @return Query
 	 */
@@ -168,11 +200,16 @@ class Connection {
 	{
 		if ( ! $this->connected()) $this->connect();
 
-		return $this->pdo->getAttribute(\PDO::ATTR_DRIVER_NAME);
+		return $this->pdo->getAttribute(PDO::ATTR_DRIVER_NAME);
 	}
 
 	/**
 	 * Magic Method for dynamically beginning queries on database tables.
+	 *
+	 * <code>
+	 *		// Begin a query against the "users" table
+	 *		$query = DB::connection()->users();
+	 * </code>
 	 */
 	public function __call($method, $parameters)
 	{

laravel/database/manager.php

@@ -7,7 +7,7 @@ class Manager {
 	 *
 	 * @var array
 	 */
-	public $connections = array();
+	protected $connections = array();
 
 	/**
 	 * The connector factory instance.
@@ -51,6 +51,14 @@ class Manager {
 	 *
 	 * Note: Database connections are managed as singletons.
 	 *
+	 * <code>
+	 *		// Get the default database connection
+	 *		$connection = DB::connection();
+	 *
+	 *		// Get a database connection by name
+	 *		$connection = DB::connection('slave');
+	 * </code>
+	 *
 	 * @param  string               $connection
 	 * @return Database\Connection
 	 */
@@ -76,7 +84,13 @@ class Manager {
 	/**
 	 * Begin a fluent query against a table.
 	 *
-	 * This method primarily serves as a short-cut to the $connection->table() method.
+	 * <code>
+	 *		// Begin a fluent query against the "users" table using the default connection
+	 *		$query = DB::table('users');
+	 *
+	 *		// Begin a fluent query against the "users" table using a specified connection
+	 *		$query = DB::table('users', 'slave');
+	 * </code>
 	 *
 	 * @param  string          $table
 	 * @param  string          $connection
@@ -91,6 +105,14 @@ class Manager {
 	 * Magic Method for calling methods on the default database connection.
 	 *
 	 * This provides a convenient API for querying or examining the default database connection.
+	 *
+	 * <code>
+	 *		// Perform a query against the default connection
+	 *		$results = DB::query('select * from users');
+	 *
+	 *		// Get the name of the PDO driver being used by the default connection
+	 *		$driver = DB::driver();
+	 * </code>
 	 */
 	public function __call($method, $parameters)
 	{