Merge branch 'develop' of github.com:bcit-ci/CodeIgniter into userguide/database_utilities

3 files changed, 172 insertions, 18 deletions

diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst
index 242881c99..f01ff8a5d 100644
--- a/user_guide_src/source/changelog.rst
+++ b/user_guide_src/source/changelog.rst
@@ -473,6 +473,7 @@ Release Date: Not Released
       -  Changed default value of the ``$xss_clean`` parameter to NULL for all methods that utilize it, the default value is now determined by the ``$config['global_xss_filtering']`` setting.
       -  Added method ``post_get()`` and changed ``get_post()`` to search in GET data first. Both methods' names now properly match their GET/POST data search priorities.
       -  Changed method ``_fetch_from_array()`` to parse array notation in field name.
+      -  Changed method ``_fetch_from_array()`` to allow retrieving multiple fields at once.
       -  Added an option for ``_clean_input_keys()`` to return FALSE instead of terminating the whole script.
       -  Deprecated the ``is_cli_request()`` method, it is now an alias for the new :func:`is_cli()` common function.
       -  Added an ``$xss_clean`` parameter to method ``user_agent()`` and removed the ``$user_agent`` property.
diff --git a/user_guide_src/source/database/forge.rst b/user_guide_src/source/database/forge.rst
index 48642ad7e..371397d26 100644
--- a/user_guide_src/source/database/forge.rst
+++ b/user_guide_src/source/database/forge.rst
@@ -6,6 +6,7 @@ The Database Forge Class contains methods that help you manage your
 database.
 
 .. contents:: Table of Contents
+    :depth: 3
 
 ****************************
 Initializing the Forge Class
@@ -35,8 +36,11 @@ object::
 
 	$this->dbforge->some_method();
 
-$this->dbforge->create_database('db_name')
-==========================================
+*******************************
+Creating and Dropping Databases
+*******************************
+
+**$this->dbforge->create_database('db_name')**
 
 Permits you to create the database specified in the first parameter.
 Returns TRUE/FALSE based on success or failure::
@@ -46,8 +50,7 @@ Returns TRUE/FALSE based on success or failure::
 		echo 'Database created!';
 	}
 
-$this->dbforge->drop_database('db_name')
-==========================================
+**$this->dbforge->drop_database('db_name')**
 
 Permits you to drop the database specified in the first parameter.
 Returns TRUE/FALSE based on success or failure::
@@ -57,6 +60,7 @@ Returns TRUE/FALSE based on success or failure::
 		echo 'Database deleted!';
 	}
 
+
 ****************************
 Creating and Dropping Tables
 ****************************
@@ -123,11 +127,11 @@ After the fields have been defined, they can be added using
 ``$this->dbforge->add_field($fields);`` followed by a call to the
 ``create_table()`` method.
 
-$this->dbforge->add_field()
----------------------------
+**$this->dbforge->add_field()**
 
 The add fields method will accept the above array.
 
+
 Passing strings as fields
 -------------------------
 
@@ -181,6 +185,7 @@ below is for MySQL.
 	// gives KEY `blog_name_blog_label` (`blog_name`, `blog_label`)
 
 
+
 Creating a table
 ================
 
@@ -211,6 +216,7 @@ You could also pass optional table attributes, such as MySQL's ``ENGINE``::
 	``create_table()`` will always add them with your configured *char_set*
 	and *dbcollat* values, as long as they are not empty (MySQL only).
 
+
 Dropping a table
 ================
 
@@ -224,6 +230,7 @@ Execute a DROP TABLE statement and optionally add an IF EXISTS clause.
 	// Produces: DROP TABLE IF EXISTS table_name
 	$this->dbforge->drop_table('table_name');
 
+
 Renaming a table
 ================
 
@@ -235,12 +242,15 @@ Executes a TABLE rename
 	// gives ALTER TABLE old_table_name RENAME TO new_table_name
 
 
+
 ****************
 Modifying Tables
 ****************
 
-$this->dbforge->add_column()
-============================
+Adding a Column to a Table
+==========================
+
+**$this->dbforge->add_column()**
 
 The ``add_column()`` method is used to modify an existing table. It
 accepts the same field array as above, and can be used for an unlimited
@@ -269,8 +279,11 @@ Examples::
 		'preferences' => array('type' => 'TEXT', 'first' => TRUE)
 	);
 
-$this->dbforge->drop_column()
-=============================
+
+Dropping a Column From a Table
+==============================
+
+**$this->dbforge->drop_column()**
 
 Used to remove a column from a table.
 
@@ -279,8 +292,11 @@ Used to remove a column from a table.
 	$this->dbforge->drop_column('table_name', 'column_to_drop');
 
 
-$this->dbforge->modify_column()
-===============================
+
+Modifying a Column in a Table
+=============================
+
+**$this->dbforge->modify_column()**
 
 The usage of this method is identical to ``add_column()``, except it
 alters an existing column rather than adding a new one. In order to
@@ -295,4 +311,111 @@ change the name you can add a "name" key into the field defining array.
 		),
 	);
 	$this->dbforge->modify_column('table_name', $fields);
-	// gives ALTER TABLE table_name CHANGE old_name new_name TEXT
\ No newline at end of file
+	// gives ALTER TABLE table_name CHANGE old_name new_name TEXT
+
+
+***************
+Class Reference
+***************
+
+.. class:: DB_forge
+
+	.. method:: __construct(&$db)
+
+		:param	object	$db: Database object
+		:returns:	DB_forge object for the specified database
+		:rtype:	DB_forge
+
+		Initializes a database forge.
+
+	.. method:: add_column($table = '', $field = array(), $_after = NULL)
+
+		:param	string	$table: Table name
+		:param	array	$field: Column definitions
+		:param	string	$_after: Column for AFTER clause (deprecated)
+                :returns:   TRUE on success, FALSE on failure
+		:rtype:	boolean
+
+                Add a column to a table. Usage:  See `Adding a Column to a Table`_.
+
+	.. method:: add_field($field = '')
+
+		:param	array	$field: Field to add
+                :returns:   DB_forge instance
+		:rtype:	object
+
+                Add a field to the set that will be used to create a table. Usage:  See `Adding fields`_.
+
+	.. method:: add_key($key = '', $primary = FALSE)
+
+		:param	array	$key: Name of a key field
+                :param  boolean $primary:   TRUE if this key is to be a primary key
+                :returns:   DB_forge instance
+		:rtype:	object
+
+                Specify a key field to be used to create a table. Usage:  See `Adding Keys`_.
+
+	.. method:: create_database($db_name)
+
+		:param	string	$db_name: Name of the database to create
+                :returns:   TRUE on success, FALSE on failure
+		:rtype:	boolean
+
+                Create a new database. Usage:  See `Creating and Dropping Databases`_.
+
+	.. method:: create_table($table = '', $if_not_exists = FALSE, array $attributes = array())
+
+		:param	string	$table: Name of the table to create
+		:param	string	$if_not_exists: TRUE to add an 'IF NOT EXISTS' clause
+		:param	string	$attributes: Associative array of table attributes
+                :returns:   DB_driver on success, FALSE on failure
+		:rtype:	mixed
+
+                Create a new table. Usage:  See `Creating a table`_.
+
+	.. method:: drop_column($table = '', $column_name = '')
+
+		:param	string	$table: Table name
+		:param	array	$column_name: Column to drop
+                :returns:   DB_driver on success, FALSE on failure
+		:rtype:	mixed
+
+                Drop a column from a table. Usage:  See `Dropping a Column From a Table`_.
+
+	.. method:: drop_database($db_name)
+
+		:param	string	$db_name: Name of the database to drop
+                :returns:   TRUE on success, FALSE on failure
+		:rtype:	boolean
+
+                Drop a database. Usage:  See `Creating and Dropping Databases`_.
+
+	.. method:: drop_table($table_name, $if_exists = FALSE)
+
+		:param	string	$table: Name of the table to create
+		:param	string	$if_exists: TRUE to add an 'IF EXISTS' clause
+                :returns:   DB_driver on success, FALSE on failure
+		:rtype:	mixed
+
+                Drop a table. Usage:  See `Dropping a table`_.
+
+	.. method:: modify_column($table = '', $field = array())
+
+		:param	string	$table: Table name
+		:param	array	$field: Column definitions
+		:returns:   TRUE on success, FALSE on failure
+		:rtype:	boolean
+
+                Modify a column in a table. Usage:  See `Modifying a Column in a Table`_.
+
+	.. method:: rename_table($table_name, $new_table_name)
+
+		:param	string	$table: Name of the table
+		:param	string	$new_table_name: New name of the table
+                :returns:   DB_driver on success, FALSE on failure
+		:rtype:	mixed
+
+                Rename a table. Usage:  See `Renaming a table`_.
+
+
+
diff --git a/user_guide_src/source/libraries/input.rst b/user_guide_src/source/libraries/input.rst
index f9dbf1686..112347129 100644
--- a/user_guide_src/source/libraries/input.rst
+++ b/user_guide_src/source/libraries/input.rst
@@ -108,7 +108,7 @@ Class Reference
 
 	.. method:: post([$index = NULL[, $xss_clean = NULL]])
 
-		:param	string	$index: POST parameter name
+		:param	mixed	$index: POST parameter name
 		:param	bool	$xss_clean: Whether to apply XSS filtering
 		:returns:	$_POST if no parameters supplied, otherwise the POST value if found or NULL if not
 		:rtype:	mixed
@@ -136,10 +136,20 @@ Class Reference
 
 			$this->input->post(NULL, TRUE); // returns all POST items with XSS filter
 			$this->input->post(NULL, FALSE); // returns all POST items without XSS filter
+		
+		To return an array of multiple POST parameters, pass all the required keys
+		as an array.
+		::
+			$this->input->post(array('field1', 'field2'));
+		
+		Same rule applied here, to retrive the parameters with XSS filtering enabled, set the
+		second parameter to boolean TRUE.
+		::
+			$this->input->post(array('field1', 'field2'), TRUE);
 
 	.. method:: get([$index = NULL[, $xss_clean = NULL]])
 
-		:param	string	$index: GET parameter name
+		:param	mixed	$index: GET parameter name
 		:param	bool	$xss_clean: Whether to apply XSS filtering
 		:returns:	$_GET if no parameters supplied, otherwise the GET value if found or NULL if not
 		:rtype:	mixed
@@ -157,6 +167,16 @@ Class Reference
 
 			$this->input->get(NULL, TRUE); // returns all GET items with XSS filter
 			$this->input->get(NULL, FALSE); // returns all GET items without XSS filtering
+		
+		To return an array of multiple GET parameters, pass all the required keys
+		as an array.
+		::
+			$this->input->get(array('field1', 'field2'));
+		
+		Same rule applied here, to retrive the parameters with XSS filtering enabled, set the
+		second parameter to boolean TRUE.
+		::
+			$this->input->get(array('field1', 'field2'), TRUE);
 
 	.. method:: post_get($index[, $xss_clean = NULL])
 
@@ -188,7 +208,7 @@ Class Reference
 
 	.. method:: cookie([$index = NULL[, $xss_clean = NULL]])
 
-		:param	string	$index: COOKIE parameter name
+		:param	mixed	$index: COOKIE name
 		:param	bool	$xss_clean: Whether to apply XSS filtering
 		:returns:	$_COOKIE if no parameters supplied, otherwise the COOKIE value if found or NULL if not
 		:rtype:	mixed
@@ -198,10 +218,15 @@ Class Reference
 
 			$this->input->cookie('some_cookie');
 			$this->input->cookie('some_cookie, TRUE); // with XSS filter
+		
+		To return an array of multiple cookie values, pass all the required keys
+		as an array.
+		::
+			$this->input->cookie(array('some_cookie', 'some_cookie2'));
 
 	.. method:: server($index[, $xss_clean = NULL])
 
-		:param	string	$index: Value name
+		:param	mixed	$index: Value name
 		:param	bool	$xss_clean: Whether to apply XSS filtering
 		:returns:	$_SERVER item value if found, NULL if not
 		:rtype:	mixed
@@ -211,9 +236,14 @@ Class Reference
 
 			$this->input->server('some_data');
 
+		To return an array of multiple ``$_SERVER`` values, pass all the required keys
+		as an array.
+		::
+			$this->input->server(array('SERVER_PROTOCOL', 'REQUEST_URI'));		
+
 	.. method:: input_stream([$index = NULL[, $xss_clean = NULL]])
 
-		:param	string	$index: Key name
+		:param	mixed	$index: Key name
 		:param	bool	$xss_clean: Whether to apply XSS filtering
 		:returns:	Input stream array if no parameters supplied, otherwise the specified value if found or NULL if not
 		:rtype:	mixed