DB forge/utilities polishing (docs) following #3375, #3378
diff --git a/system/database/DB_forge.php b/system/database/DB_forge.php
index 85505ce..4238e37 100644
--- a/system/database/DB_forge.php
+++ b/system/database/DB_forge.php
@@ -207,12 +207,7 @@
*/
public function drop_database($db_name)
{
- if ($db_name === '')
- {
- show_error('A table name is required for that operation.');
- return FALSE;
- }
- elseif ($this->_drop_database === FALSE)
+ if ($this->_drop_database === FALSE)
{
return ($this->db->db_debug) ? $this->db->display_error('db_unsupported_feature') : FALSE;
}
@@ -242,13 +237,8 @@
* @param bool $primary
* @return CI_DB_forge
*/
- public function add_key($key = '', $primary = FALSE)
+ public function add_key($key, $primary = FALSE)
{
- if (empty($key))
- {
- show_error('Key information is required for that operation.');
- }
-
if ($primary === TRUE && is_array($key))
{
foreach ($key as $one)
@@ -279,13 +269,8 @@
* @param array $field
* @return CI_DB_forge
*/
- public function add_field($field = '')
+ public function add_field($field)
{
- if (empty($field))
- {
- show_error('Field information is required.');
- }
-
if (is_string($field))
{
if ($field === 'id')
@@ -328,7 +313,7 @@
* @param array $attributes Associative array of table attributes
* @return bool
*/
- public function create_table($table = '', $if_not_exists = FALSE, array $attributes = array())
+ public function create_table($table, $if_not_exists = FALSE, array $attributes = array())
{
if ($table === '')
{
@@ -575,18 +560,10 @@
* @param string $_after Column for AFTER clause (deprecated)
* @return bool
*/
- public function add_column($table = '', $field = array(), $_after = NULL)
+ public function add_column($table, $field, $_after = NULL)
{
- if ($table === '')
- {
- show_error('A table name is required for that operation.');
- }
-
// Work-around for literal column definitions
- if ( ! is_array($field))
- {
- $field = array($field);
- }
+ is_array($field) OR $field = array($field);
foreach (array_keys($field) as $k)
{
@@ -626,18 +603,8 @@
* @param string $column_name Column name
* @return bool
*/
- public function drop_column($table = '', $column_name = '')
+ public function drop_column($table, $column_name)
{
- if ($table === '')
- {
- show_error('A table name is required for that operation.');
- }
-
- if ($column_name === '')
- {
- show_error('A column name is required for that operation.');
- }
-
$sql = $this->_alter_table('DROP', $this->db->dbprefix.$table, $column_name);
if ($sql === FALSE)
{
@@ -656,18 +623,10 @@
* @param string $field Column definition
* @return bool
*/
- public function modify_column($table = '', $field = array())
+ public function modify_column($table, $field)
{
- if ($table === '')
- {
- show_error('A table name is required for that operation.');
- }
-
// Work-around for literal column definitions
- if ( ! is_array($field))
- {
- $field = array($field);
- }
+ is_array($field) OR $field = array($field);
foreach (array_keys($field) as $k)
{
diff --git a/user_guide_src/source/database/forge.rst b/user_guide_src/source/database/forge.rst
index 371397d..59a6591 100644
--- a/user_guide_src/source/database/forge.rst
+++ b/user_guide_src/source/database/forge.rst
@@ -185,7 +185,6 @@
// gives KEY `blog_name_blog_label` (`blog_name`, `blog_label`)
-
Creating a table
================
@@ -242,7 +241,6 @@
// gives ALTER TABLE old_table_name RENAME TO new_table_name
-
****************
Modifying Tables
****************
@@ -318,104 +316,93 @@
Class Reference
***************
-.. class:: DB_forge
+.. class:: CI_DB_forge
- .. method:: __construct(&$db)
+ .. method:: add_column($table[, $field = array()[, $_after = NULL]])
- :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 $table: Table name to add the column to
+ :param array $field: Column definition(s)
:param string $_after: Column for AFTER clause (deprecated)
- :returns: TRUE on success, FALSE on failure
- :rtype: boolean
+ :returns: TRUE on success, FALSE on failure
+ :rtype: bool
- Add a column to a table. Usage: See `Adding a Column to a Table`_.
+ Adds a column to a table. Usage: See `Adding a Column to a Table`_.
- .. method:: add_field($field = '')
+ .. method:: add_field($field)
- :param array $field: Field to add
- :returns: DB_forge instance
- :rtype: object
+ :param array $field: Field definition to add
+ :returns: CI_DB_forge instance (method chaining)
+ :rtype: CI_DB_forge
- Add a field to the set that will be used to create a table. Usage: See `Adding fields`_.
+ Adds a field to the set that will be used to create a table. Usage: See `Adding fields`_.
- .. method:: add_key($key = '', $primary = FALSE)
+ .. 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
+ :param bool $primary: Set to TRUE if it should be a primary key or a regular one
+ :returns: CI_DB_forge instance (method chaining)
+ :rtype: CI_DB_forge
- Specify a key field to be used to create a table. Usage: See `Adding Keys`_.
+ Adds a key to the set that will 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
+ :returns: TRUE on success, FALSE on failure
+ :rtype: bool
- Create a new database. Usage: See `Creating and Dropping Databases`_.
+ Creates a new database. Usage: See `Creating and Dropping Databases`_.
- .. method:: create_table($table = '', $if_not_exists = FALSE, array $attributes = array())
+ .. 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
+ :param string $if_not_exists: Set to TRUE to add an 'IF NOT EXISTS' clause
+ :param string $attributes: An associative array of table attributes
+ :returns: TRUE on success, FALSE on failure
+ :rtype: bool
- Create a new table. Usage: See `Creating a table`_.
+ Creates a new table. Usage: See `Creating a table`_.
- .. method:: drop_column($table = '', $column_name = '')
+ .. 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
+ :param array $column_name: The column name to drop
+ :returns: TRUE on success, FALSE on failure
+ :rtype: bool
- Drop a column from a table. Usage: See `Dropping a Column From a Table`_.
+ Drops 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
+ :returns: TRUE on success, FALSE on failure
+ :rtype: bool
- Drop a database. Usage: See `Creating and Dropping Databases`_.
+ Drops a database. Usage: See `Creating and Dropping Databases`_.
- .. method:: drop_table($table_name, $if_exists = FALSE)
+ .. 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
+ :param string $table: Name of the table to drop
+ :param string $if_exists: Set to TRUE to add an 'IF EXISTS' clause
+ :returns: TRUE on success, FALSE on failure
+ :rtype: bool
- Drop a table. Usage: See `Dropping a table`_.
+ Drops a table. Usage: See `Dropping a table`_.
- .. method:: modify_column($table = '', $field = array())
+ .. method:: modify_column($table, $field)
:param string $table: Table name
- :param array $field: Column definitions
- :returns: TRUE on success, FALSE on failure
- :rtype: boolean
+ :param array $field: Column definition(s)
+ :returns: TRUE on success, FALSE on failure
+ :rtype: bool
- Modify a column in a table. Usage: See `Modifying a Column in a Table`_.
+ Modifies a table column. 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 $table: Current of the table
:param string $new_table_name: New name of the table
- :returns: DB_driver on success, FALSE on failure
- :rtype: mixed
+ :returns: TRUE on success, FALSE on failure
+ :rtype: bool
- Rename a table. Usage: See `Renaming a table`_.
-
-
-
+ Renames a table. Usage: See `Renaming a table`_.
\ No newline at end of file
diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst
index d15cef0..0d8137d 100644
--- a/user_guide_src/source/database/utilities.rst
+++ b/user_guide_src/source/database/utilities.rst
@@ -9,7 +9,6 @@
:local:
:depth: 2
-
******************************
Initializing the Utility Class
******************************
@@ -248,66 +247,70 @@
Class Reference
***************
-.. class:: DB_utility
+.. class:: CI_DB_utility
- .. method:: backup($params)
+ .. method:: backup([$params = array()])
- :param array $params: associative array of backup preferences
+ :param array $params: An associative array of options
:returns: void
- :rtype: void
+ :rtype: void
- Perform a database backup, per user preferences
-
- .. method:: csv_from_results($query, $delim = ',', $newline = "\n", $enclosure = '"')
-
- :param object $query: DB_result with data to backup
- :param string $delim: Delimniter character for the CSV file, default is ','
- :param string $newline: Character to use for newlines, default is "\n"
- :param string $enclosure: Delimiter used for enclosure, default is '"'
- :returns: The generated CSV file as a string
- :rtype: string
+ Perform a database backup, per user preferences.
.. method:: database_exists($database_name)
- :param string $database_name: name of the database to check for
+ :param string $database_name: Database name
:returns: TRUE if the database exists, FALSE otherwise
- :rtype: boolean
+ :rtype: bool
- Check for the existence of a database
+ Check for the existence of a database.
.. method:: list_databases()
:returns: Array of database names found
- :rtype: array
+ :rtype: array
- Retrieve all the database names
+ Retrieve a list of all the database names.
.. method:: optimize_database()
- :returns: Array of optimization messages, FALSE on failure
- :rtype: array
+ :returns: Array of optimization messages or FALSE on failure
+ :rtype: array
- Optimizes a database
+ Optimizes the database.
.. method:: optimize_table($table_name)
- :param string $table_name: Name of the table to optimize
- :returns: Array of optimization messages, FALSE on failure
- :rtype: array
+ :param string $table_name: Name of the table to optimize
+ :returns: Array of optimization messages or FALSE on failure
+ :rtype: array
- Optimizes a database table
+ Optimizes a database table.
.. method:: repair_table($table_name)
- :param string $table_name: Name of the table to repair
- :returns: Array of repair messages, FALSE on failure
- :rtype: array
+ :param string $table_name: Name of the table to repair
+ :returns: Array of repair messages or FALSE on failure
+ :rtype: array
- Repairs a database table
+ Repairs a database table.
- .. method:: xml_from_results($query, $params)
+ .. method:: csv_from_results($query[, $delim = ','[, $newline = "\n"[, $enclosure = '"']]])
- :param object $query: DB_result with data to backup
- :param array $params: Associative array of preferences
- :returns: The generated XML document as a string
- :rtype: string
+ :param object $query: A database result object
+ :param string $delim: The CSV field delimiter to use
+ :param string $newline: The newline character to use
+ :param string $enclosure: The enclosure delimiter to use
+ :returns: The generated CSV file as a string
+ :rtype: string
+
+ Translates a database result object into a CSV document.
+
+ .. method:: xml_from_results($query[, $params = array()])
+
+ :param object $query: A database result object
+ :param array $params: An associative array of preferences
+ :returns: The generated XML document as a string
+ :rtype: string
+
+ Translates a database result object into an XML document.
\ No newline at end of file
diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst
index f29ebf4..2d0ee23 100644
--- a/user_guide_src/source/libraries/encryption.rst
+++ b/user_guide_src/source/libraries/encryption.rst
@@ -533,6 +533,7 @@
:param int $length: Optional output length
:param string $info: Optional context/application-specific info
:returns: A pseudo-random key or FALSE on failure
+ :rtype: string
Derives a key from another, presumably weaker key.