Merge branch 'develop' of https://github.com/EllisLab/CodeIgniter into develop

4 files changed, 271 insertions, 61 deletions

diff --git a/user_guide_src/source/database/active_record.rst b/user_guide_src/source/database/active_record.rst
index e1fc00bc5..c04e67d2a 100644
--- a/user_guide_src/source/database/active_record.rst
+++ b/user_guide_src/source/database/active_record.rst
@@ -45,7 +45,7 @@ You'll notice that the above function is assigned to a variable named
 $query, which can be used to show the results::
 
 	$query = $this->db->get('mytable');
-	
+
 	foreach ($query->result() as $row)
 	{
 		echo $row->title;
@@ -54,6 +54,37 @@ $query, which can be used to show the results::
 Please visit the :doc:`result functions <results>` page for a full
 discussion regarding result generation.
 
+$this->db->get_compiled_select()
+================================
+
+Compiles the selection query just like `$this->db->get()`_ but does not *run*
+the query. This method simply returns the SQL query as a string.
+
+Example::
+
+	$sql = $this->db->get_compiled_select('mytable');
+	echo $sql;
+
+	// Produces string: SELECT * FROM mytable
+
+The second parameter enables you to set whether or not the active record query
+will be reset (by default it will be&mdash;just like `$this->db->get()`)::
+
+	echo $this->db->limit(10,20)->get_compiled_select('mytable', FALSE);
+	// Produces string: SELECT * FROM mytable LIMIT 20, 10
+	// (in MySQL. Other databases have slightly different syntax)
+
+	echo $this->db->select('title, content, date')->get_compiled_select();
+
+	// Produces string: SELECT title, content, date FROM mytable
+
+The key thing to notice in the above example is that the second query did not
+utilize `$this->db->from()`_ and did not pass a table name into the first
+parameter. The reason for this outcome is because the query has not been
+executed using `$this->db->get()`_ which resets values or reset directly
+using `$this->db->reset_query()`_.
+
+
 $this->db->get_where()
 ======================
 
@@ -65,8 +96,7 @@ function::
 
 Please read the about the where function below for more information.
 
-Note: get_where() was formerly known as getwhere(), which has been
-removed
+.. note:: get_where() was formerly known as getwhere(), which has been removed
 
 $this->db->select()
 ===================
@@ -86,7 +116,7 @@ with backticks. This is useful if you need a compound select statement.
 
 ::
 
-	$this->db->select('(SELECT SUM(payments.amount) FROM payments WHERE payments.invoice_id=4') AS amount_paid', FALSE); 
+	$this->db->select('(SELECT SUM(payments.amount) FROM payments WHERE payments.invoice_id=4') AS amount_paid', FALSE);
 	$query = $this->db->get('mytable');
 
 
@@ -100,7 +130,7 @@ include a second parameter to rename the resulting field.
 
 	$this->db->select_max('age');
 	$query = $this->db->get('members');  // Produces: SELECT MAX(age) as age FROM members
-	
+
 	$this->db->select_max('age', 'member_age');
 	$query = $this->db->get('members'); // Produces: SELECT MAX(age) as member_age FROM members
 
@@ -165,9 +195,9 @@ Permits you to write the JOIN portion of your query::
 	$this->db->from('blogs');
 	$this->db->join('comments', 'comments.id = blogs.id');
 	$query = $this->db->get();
-	
+
 	// Produces:
-	// SELECT * FROM blogs // JOIN comments ON comments.id = blogs.id
+	// SELECT * FROM blogs JOIN comments ON comments.id = blogs.id
 
 Multiple function calls can be made if you need several joins in one
 query.
@@ -194,7 +224,7 @@ methods:
 
 	::
 
-		$this->db->where('name', $name); // Produces: WHERE name = 'Joe' 
+		$this->db->where('name', $name); // Produces: WHERE name = 'Joe'
 
 	Notice that the equal sign is added for you.
 
@@ -206,7 +236,7 @@ methods:
 		$this->db->where('name', $name);
 		$this->db->where('title', $title);
 		$this->db->where('status', $status);
-		// WHERE name = 'Joe' AND title = 'boss' AND status = 'active'  
+		// WHERE name = 'Joe' AND title = 'boss' AND status = 'active'
 
 #. **Custom key/value method:**
 	You can include an operator in the first parameter in order to
@@ -215,7 +245,7 @@ methods:
 	::
 
 		$this->db->where('name !=', $name);
-		$this->db->where('id <', $id); // Produces: WHERE name != 'Joe' AND id < 45    
+		$this->db->where('id <', $id); // Produces: WHERE name != 'Joe' AND id < 45
 
 #. **Associative array method:**
 
@@ -223,7 +253,7 @@ methods:
 
 		$array = array('name' => $name, 'title' => $title, 'status' => $status);
 		$this->db->where($array);
-		// Produces: WHERE name = 'Joe' AND title = 'boss' AND status = 'active'    
+		// Produces: WHERE name = 'Joe' AND title = 'boss' AND status = 'active'
 
 	You can include your own operators using this method as well:
 
@@ -324,7 +354,7 @@ searches.
 
 	::
 
-		$this->db->like('title', 'match');     // Produces: WHERE title LIKE '%match%' 
+		$this->db->like('title', 'match');     // Produces: WHERE title LIKE '%match%'
 
 	If you use multiple function calls they will be chained together with
 	AND between them::
@@ -341,7 +371,7 @@ searches.
 
 		$this->db->like('title', 'match', 'before');	// Produces: WHERE title LIKE '%match'
 		$this->db->like('title', 'match', 'after');		// Produces: WHERE title LIKE 'match%'
-		$this->db->like('title', 'match', 'both');		// Produces: WHERE title LIKE '%match%' 
+		$this->db->like('title', 'match', 'both');		// Produces: WHERE title LIKE '%match%'
 
 #. **Associative array method:**
 
@@ -413,7 +443,7 @@ Permits you to write the HAVING portion of your query. There are 2
 possible syntaxes, 1 argument or 2::
 
 	$this->db->having('user_id = 45');  // Produces: HAVING user_id = 45
-	$this->db->having('user_id',  45);  // Produces: HAVING user_id = 45 
+	$this->db->having('user_id',  45);  // Produces: HAVING user_id = 45
 
 You can also pass an array of multiple values as well::
 
@@ -456,7 +486,7 @@ Or multiple function calls can be made if you need multiple fields.
 ::
 
 	$this->db->order_by("title", "desc");
-	$this->db->order_by("name", "asc"); // Produces: ORDER BY title DESC, name ASC     
+	$this->db->order_by("name", "asc"); // Produces: ORDER BY title DESC, name ASC
 
 
 .. note:: order_by() was formerly known as orderby(), which has been
@@ -488,7 +518,7 @@ where(), or_where(), like(), or_like(), etc. Example::
 	echo $this->db->count_all_results('my_table');  // Produces an integer, like 25
 	$this->db->like('title', 'match');
 	$this->db->from('my_table');
-	echo $this->db->count_all_results(); // Produces an integer, like 17 
+	echo $this->db->count_all_results(); // Produces an integer, like 17
 
 $this->db->count_all()
 ======================
@@ -499,6 +529,54 @@ Submit the table name in the first parameter. Example::
 	echo $this->db->count_all('my_table');  // Produces an integer, like 25
 
 **************
+Query grouping
+**************
+
+Query grouping allows you to create groups of WHERE clauses by enclosing them in parentheses. This will allow
+you to create queries with complex WHERE clauses. Nested groups are supported. Example:
+
+	$this->db->select('*')->from('my_table')
+		->group_start()
+			->where('a', 'a')
+			->or_group_start()
+				->where('b', 'b')
+				->where('c', 'c')
+			->group_end()
+		->group_end()
+		->where('d', 'd')
+	->get();
+
+	// Generates:
+	// SELECT * FROM (`my_table`) WHERE ( `a` = 'a' OR ( `b` = 'b' AND `c` = 'c' ) ) AND `d` = 'd'
+
+.. note:: groups need to be balanced, make sure every group_start() is matched by a group_end().
+
+$this->db->group_start()
+========================
+
+Starts a new group by adding an opening parenthesis to the WHERE clause of the query.
+
+$this->db->or_group_start()
+===========================
+
+Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'OR'.
+
+$this->db->not_group_start()
+============================
+
+Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'NOT'.
+
+$this->db->or_not_group_start()
+===============================
+
+Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'OR NOT'.
+
+$this->db->group_end()
+======================
+
+Ends the current group by adding an closing parenthesis to the WHERE clause of the query.
+
+**************
 Inserting Data
 **************
 
@@ -514,7 +592,7 @@ function. Here is an example using an array::
 		'name' => 'My Name',
 		'date' => 'My date'
 	);
-	
+
 	$this->db->insert('mytable', $data);
 	// Produces: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date')
 
@@ -530,7 +608,7 @@ Here is an example using an object::
 		var  $date = 'My Date';
 	}
 	*/
-	
+
 	$object = new Myclass;
 	$this->db->insert('mytable', $object);
 	// Produces: INSERT INTO mytable (title, content, date) VALUES ('My Title', 'My Content', 'My Date')
@@ -540,6 +618,41 @@ object.
 
 .. note:: All values are escaped automatically producing safer queries.
 
+$this->db->get_compiled_insert()
+================================
+Compiles the insertion query just like `$this->db->insert()`_ but does not
+*run* the query. This method simply returns the SQL query as a string.
+
+Example::
+
+	$data = array(
+		'title' => 'My title',
+		'name'  => 'My Name',
+		'date'  => 'My date'
+	);
+
+	$sql = $this->db->set($data)->get_compiled_insert('mytable');
+	echo $sql;
+
+	// Produces string: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date')
+
+The second parameter enables you to set whether or not the active record query
+will be reset (by default it will be--just like `$this->db->insert()`_)::
+
+	echo $this->db->set('title', 'My Title')->get_compiled_insert('mytable', FALSE);
+
+	// Produces string: INSERT INTO mytable (title) VALUES ('My Title')
+
+	echo $this->db->set('content', 'My Content')->get_compiled_insert();
+
+	// Produces string: INSERT INTO mytable (title, content) VALUES ('My Title', 'My Content')
+
+The key thing to notice in the above example is that the second query did not
+utlize `$this->db->from()`_ nor did it pass a table name into the first
+parameter. The reason this worked is because the query has not been executed
+using `$this->db->insert()`_ which resets values or reset directly using
+`$this->db->reset_query()`_.
+
 $this->db->insert_batch()
 =========================
 
@@ -559,7 +672,7 @@ function. Here is an example using an array::
 			'date' => 'Another date'
 		)
 	);
-	
+
 	$this->db->insert_batch('mytable', $data);
 	// Produces: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date'),  ('Another title', 'Another name', 'Another date')
 
@@ -587,7 +700,7 @@ based on whether you are doing an insert or an update::
 	$this->db->set('name', $name);
 	$this->db->set('title', $title);
 	$this->db->set('status', $status);
-	$this->db->insert('mytable'); 
+	$this->db->insert('mytable');
 
 **set()** will also accept an optional third parameter ($escape), that
 will prevent data from being escaped if set to FALSE. To illustrate the
@@ -609,7 +722,7 @@ You can also pass an associative array to this function::
 		'title' => $title,
 		'status' => $status
 	);
-	
+
 	$this->db->set($array);
 	$this->db->insert('mytable');
 
@@ -622,7 +735,7 @@ Or an object::
 		var  $date = 'My Date';
 	}
 	*/
-	
+
 	$object = new Myclass;
 	$this->db->set($object);
 	$this->db->insert('mytable');
@@ -644,7 +757,7 @@ is an example using an array::
 		'name' => $name,
 		'date' => $date
 	);
-	
+
 	$this->db->where('id', $id);
 	$this->db->update('mytable', $data);
 	// Produces: // UPDATE mytable  // SET title = '{$title}', name = '{$name}', date = '{$date}' // WHERE id = $id
@@ -658,7 +771,7 @@ Or you can supply an object::
 		var  $date = 'My Date';
 	}
 	*/
-	
+
 	$object = new Myclass;
 	$this->db->where('id', $id);
 	$this->db->update('mytable', $object);
@@ -699,14 +812,14 @@ Here is an example using an array::
 	   )
 	);
 
-	$this->db->update_batch('mytable', $data, 'title'); 
+	$this->db->update_batch('mytable', $data, 'title');
 
-	// Produces: 
+	// Produces:
 	// UPDATE `mytable` SET `name` = CASE
 	// WHEN `title` = 'My title' THEN 'My Name 2'
 	// WHEN `title` = 'Another title' THEN 'Another Name 2'
 	// ELSE `name` END,
-	// `date` = CASE 
+	// `date` = CASE
 	// WHEN `title` = 'My title' THEN 'My date 2'
 	// WHEN `title` = 'Another title' THEN 'Another date 2'
 	// ELSE `date` END
@@ -717,6 +830,14 @@ array of values, the third parameter is the where key.
 
 .. note:: All values are escaped automatically producing safer queries.
 
+$this->db->get_compiled_update()
+================================
+
+This works exactly the same way as ``$this->db->get_compiled_insert()`` except
+that it produces an UPDATE SQL string instead of an INSERT SQL string.
+
+For more information view documentation for `$this->db->get_compiled_insert()`_.
+
 
 *************
 Deleting Data
@@ -737,7 +858,7 @@ the data to the second parameter of the function::
 
 	$this->db->where('id', $id);
 	$this->db->delete('mytable');
-	
+
 	// Produces:
 	// DELETE FROM mytable
 	// WHERE id = $id
@@ -762,7 +883,7 @@ $this->db->empty_table()
 Generates a delete SQL string and runs the
 query.::
 
-	  $this->db->empty_table('mytable'); // Produces // DELETE FROM mytable
+	  $this->db->empty_table('mytable'); // Produces: DELETE FROM mytable
 
 
 $this->db->truncate()
@@ -773,18 +894,25 @@ Generates a truncate SQL string and runs the query.
 ::
 
 	$this->db->from('mytable');
-	$this->db->truncate();  
-	
-	// or  
-	
+	$this->db->truncate();
+
+	// or
+
 	$this->db->truncate('mytable');
-	
+
 	// Produce:
-	// TRUNCATE mytable 
+	// TRUNCATE mytable
 
 .. note:: If the TRUNCATE command isn't available, truncate() will
 	execute as "DELETE FROM table".
 
+$this->db->get_compiled_delete()
+================================
+This works exactly the same way as ``$this->db->get_compiled_insert()`` except
+that it produces a DELETE SQL string instead of an INSERT SQL string.
+
+For more information view documentation for `$this->db->get_compiled_insert()`_.
+
 ***************
 Method Chaining
 ***************
@@ -797,8 +925,6 @@ multiple functions. Consider this example::
 				->limit(10, 20)
 				->get('mytable');
 
-.. note:: Method chaining only works with PHP 5.
-
 .. _ar-caching:
 
 *********************
@@ -839,11 +965,11 @@ Here's a usage example::
 	$this->db->stop_cache();
 	$this->db->get('tablename');
 	//Generates: SELECT `field1` FROM (`tablename`)
-	
+
 	$this->db->select('field2');
 	$this->db->get('tablename');
 	//Generates:  SELECT `field1`, `field2` FROM (`tablename`)
-	
+
 	$this->db->flush_cache();
 	$this->db->select('field2');
 	$this->db->get('tablename');
@@ -854,3 +980,29 @@ Here's a usage example::
 	where, like, group_by, having, order_by, set
 
 
+$this->db->reset_query()
+========================
+
+Resetting Active Record allows you to start fresh with your query without
+executing it first using a method like $this->db->get() or $this->db->insert().
+Just like the methods that execute a query, this will *not* reset items you've
+cached using `Active Record Caching`_.
+
+This is useful in situations where you are using Active Record to generate SQL
+(ex. ``$this->db->get_compiled_select()``) but then choose to, for instance,
+run the query::
+
+	// Note that the second parameter of the get_compiled_select method is FALSE
+	$sql = $this->db->select(array('field1','field2'))
+					->where('field3',5)
+					->get_compiled_select('mytable', FALSE);
+
+	// ...
+	// Do something crazy with the SQL code... like add it to a cron script for
+	// later execution or something...
+	// ...
+
+	$data = $this->db->get()->result_array();
+
+	// Would execute and return an array of results of the following query:
+	// SELECT field1, field1 from mytable where field3 = 5;
diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst
index 687f0d920..040e7e33f 100644
--- a/user_guide_src/source/database/configuration.rst
+++ b/user_guide_src/source/database/configuration.rst
@@ -28,6 +28,52 @@ prototype::
 	$db['default']['autoinit'] = TRUE;
 	$db['default']['stricton'] = FALSE;
 
+If you use PDO as your dbdriver, you can specify the full DSN string describe a connection to the database like this::
+
+	$db['default']['dsn'] = 'pgsql:host=localhost;port=5432;dbname=database_name';
+
+You can also specify failovers for the situation when the main connection cannot connect for some reason.
+These failovers can be specified by setting the failover for a connection like this::
+
+	$db['default']['failover'] = array(
+			array(
+				'hostname' => 'localhost1',
+				'username' => '',
+				'password' => '',
+				'database' => '',
+				'dbdriver' => 'mysql',
+				'dbprefix' => '',
+				'pconnect' => TRUE,
+				'db_debug' => TRUE,
+				'cache_on' => FALSE,
+				'cachedir' => '',
+				'char_set' => 'utf8',
+				'dbcollat' => 'utf8_general_ci',
+				'swap_pre' => '',
+				'autoinit' => TRUE,
+				'stricton' => FALSE
+			),
+			array(
+				'hostname' => 'localhost2',
+				'username' => '',
+				'password' => '',
+				'database' => '',
+				'dbdriver' => 'mysql',
+				'dbprefix' => '',
+				'pconnect' => TRUE,
+				'db_debug' => TRUE,
+				'cache_on' => FALSE,
+				'cachedir' => '',
+				'char_set' => 'utf8',
+				'dbcollat' => 'utf8_general_ci',
+				'swap_pre' => '',
+				'autoinit' => TRUE,
+				'stricton' => FALSE
+			)
+		);
+
+You can specify as many failovers as you like.
+
 The reason we use a multi-dimensional array rather than a more simple
 one is to permit you to optionally store multiple sets of connection
 values. If, for example, you run multiple environments (development,
@@ -116,6 +162,7 @@ Explanation of Values:
 			while developing an application.
 **port**		The database port number. To use this value you have to add a line to the database config array.
 			::
+			
 				$db['default']['port'] =  5432;
 ======================  ==================================================================================================
 
diff --git a/user_guide_src/source/database/connecting.rst b/user_guide_src/source/database/connecting.rst
index 64adc3047..a834cc0f7 100644
--- a/user_guide_src/source/database/connecting.rst
+++ b/user_guide_src/source/database/connecting.rst
@@ -57,7 +57,19 @@ file.
 To connect manually to a desired database you can pass an array of
 values::
 
-	$config['hostname'] = "localhost"; $config['username'] = "myusername"; $config['password'] = "mypassword"; $config['database'] = "mydatabase"; $config['dbdriver'] = "mysql"; $config['dbprefix'] = ""; $config['pconnect'] = FALSE; $config['db_debug'] = TRUE; $config['cache_on'] = FALSE; $config['cachedir'] = ""; $config['char_set'] = "utf8"; $config['dbcollat'] = "utf8_general_ci";  $this->load->database($config);
+	$config['hostname'] = "localhost"; 
+	$config['username'] = "myusername"; 
+	$config['password'] = "mypassword"; 
+	$config['database'] = "mydatabase"; 
+	$config['dbdriver'] = "mysql"; 
+	$config['dbprefix'] = ""; 
+	$config['pconnect'] = FALSE; 
+	$config['db_debug'] = TRUE; 
+	$config['cache_on'] = FALSE; 
+	$config['cachedir'] = ""; 
+	$config['char_set'] = "utf8"; 
+	$config['dbcollat'] = "utf8_general_ci";  
+	$this->load->database($config);
 
 For information on each of these values please see the :doc:`configuration
 page <configuration>`.
@@ -68,14 +80,16 @@ page <configuration>`.
 Or you can submit your database values as a Data Source Name. DSNs must
 have this prototype::
 
-	$dsn = 'dbdriver://username:password@hostname/database';  $this->load->database($dsn);
+	$dsn = 'dbdriver://username:password@hostname/database';  
+	$this->load->database($dsn);
 
 To override default config values when connecting with a DSN string, add
 the config variables as a query string.
 
 ::
 
-	$dsn = 'dbdriver://username:password@hostname/database?char_set=utf8&dbcollat=utf8_general_ci&cache_on=true&cachedir=/path/to/cache';  $this->load->database($dsn);
+	$dsn = 'dbdriver://username:password@hostname/database?char_set=utf8&dbcollat=utf8_general_ci&cache_on=true&cachedir=/path/to/cache';  
+	$this->load->database($dsn);
 
 Connecting to Multiple Databases
 ================================
@@ -83,7 +97,8 @@ Connecting to Multiple Databases
 If you need to connect to more than one database simultaneously you can
 do so as follows::
 
-	$DB1 = $this->load->database('group_one', TRUE); $DB2 = $this->load->database('group_two', TRUE);
+	$DB1 = $this->load->database('group_one', TRUE); 
+	$DB2 = $this->load->database('group_two', TRUE);
 
 Note: Change the words "group_one" and "group_two" to the specific
 group names you are connecting to (or you can pass the connection values
diff --git a/user_guide_src/source/database/index.rst b/user_guide_src/source/database/index.rst
index 3b59986be..ab12b7cb7 100644
--- a/user_guide_src/source/database/index.rst
+++ b/user_guide_src/source/database/index.rst
@@ -6,24 +6,20 @@ CodeIgniter comes with a full-featured and very fast abstracted database
 class that supports both traditional structures and Active Record
 patterns. The database functions offer clear, simple syntax.
 
--  :doc:`Quick Start: Usage Examples <examples>`
--  :doc:`Database Configuration <configuration>`
--  :doc:`Connecting to a Database <connecting>`
--  :doc:`Running Queries <queries>`
--  :doc:`Generating Query Results <results>`
--  :doc:`Query Helper Functions <helpers>`
--  :doc:`Active Record Class <active_record>`
--  :doc:`Transactions <transactions>`
--  :doc:`Table MetaData <table_data>`
--  :doc:`Field MetaData <fields>`
--  :doc:`Custom Function Calls <call_function>`
--  :doc:`Query Caching <caching>`
--  :doc:`Database manipulation with Database Forge <forge>`
--  :doc:`Database Utilities Class <utilities>`
-
 .. toctree::
-	:glob:
 	:titlesonly:
-	:hidden:
 	
-	*
\ No newline at end of file
+	Quick Start: Usage Examples <examples>
+	Database Configuration <configuration>
+	Connecting to a Database <connecting>
+	Running Queries <queries>
+	Generating Query Results <results>
+	Query Helper Functions <helpers>
+	Active Record Class <active_record>
+	Transactions <transactions>
+	Table MetaData <table_data>
+	Field MetaData <fields>
+	Custom Function Calls <call_function>
+	Query Caching <caching>
+	Database Manipulation with Database Forge <forge>
+	Database Utilities Class <utilities>
\ No newline at end of file