summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source
diff options
context:
space:
mode:
Diffstat (limited to 'user_guide_src/source')
-rw-r--r--user_guide_src/source/database/db_driver_reference.rst381
-rw-r--r--user_guide_src/source/general/reserved_names.rst4
-rw-r--r--user_guide_src/source/installation/upgrade_300.rst37
-rw-r--r--user_guide_src/source/libraries/form_validation.rst8
4 files changed, 230 insertions, 200 deletions
diff --git a/user_guide_src/source/database/db_driver_reference.rst b/user_guide_src/source/database/db_driver_reference.rst
index 872077a7e..7bee555c8 100644
--- a/user_guide_src/source/database/db_driver_reference.rst
+++ b/user_guide_src/source/database/db_driver_reference.rst
@@ -9,129 +9,140 @@ class for the specific database will extend and instantiate it.
The how-to material for this has been split over several articles.
This article is intended to be a reference for them.
+.. important:: Not all methods are supported by all database drivers,
+ some of them may fail (and return FALSE) if the underlying
+ driver does not support them.
+
.. class:: CI_DB_driver
.. method:: initialize()
:returns: TRUE on success, FALSE on failure
- :rtype: boolean
+ :rtype: bool
+
+ Initialize database settings, establish a connection to
+ the database.
+
+ .. method:: db_connect($persistent = TRUE)
+
+ :param bool $persistent: Whether to establish a persistent connection or a regular one
+ :returns: Database connection resource/object or FALSE on failure
+ :rtype: mixed
+
+ Establish a connection with the database.
- Initialize Database Settings;
- establish a connection to the database.
+ .. note:: The returned value depends on the underlying
+ driver in use. For example, a ``mysqli`` instance
+ will be returned with the 'mysqli' driver.
.. method:: db_pconnect()
- :returns: TRUE on success, FALSE on failure
- :rtype: boolean
+ :returns: Database connection resource/object or FALSE on failure
+ :rtype: mixed
+
+ Establish a persistent connection with the database.
- Establish a persistent database connection
+ .. note:: This method is just an alias for ``db_connect(TRUE)``.
.. method:: reconnect()
:returns: TRUE on success, FALSE on failure
- :rtype: boolean
+ :rtype: bool
- Keep / reestablish the db connection if no queries have been
- sent for a length of time exceeding the server's idle timeout.
+ Keep / reestablish the database connection if no queries
+ have been sent for a length of time exceeding the
+ server's idle timeout.
- This is only available in drivers that support it.
-
- .. method:: db_select()
+ .. method:: db_select([$database = ''])
+ :param string $database: Database name
:returns: TRUE on success, FALSE on failure
- :rtype: boolean
+ :rtype: bool
- Select database
+ Select / switch the current database.
.. method:: db_set_charset($charset)
:param string $charset: Character set name
:returns: TRUE on success, FALSE on failure
- :rtype: boolean
+ :rtype: bool
- Set client character set
+ Set client character set.
.. method:: platform()
:returns: Platform name
:rtype: string
- The name of the platform in use (mysql, mssql, etc...)
+ The name of the platform in use (mysql, mssql, etc...).
.. method:: version()
- :returns: The version of the database being used.
+ :returns: The version of the database being used
:rtype: string
- Database version number
+ Database version number.
.. method:: query($sql[, $binds = FALSE[, $return_object = NULL]]])
:param string $sql: The SQL statement to execute
:param array $binds: An array of binding data
- :param bool $return_object: Character set name
- :returns: True on "update" success, DB_result object on "query" success, FALSE on failure
+ :param bool $return_object: Whether to return a result object or not
+ :returns: TRUE for successful "write-type" queries, CI_DB_result instance (method chaining) on "query" success, FALSE on failure
:rtype: mixed
- Execute the query
+ Execute an SQL query.
- Accepts an SQL string as input and returns a result object
- upon
- successful execution of a "read" type query. Returns boolean
- TRUE
- upon successful execution of a "write" type query.
- Returns boolean
- FALSE upon failure, and if the $db_debug variable is set
- to TRUE
- will raise an error.
+ Accepts an SQL string as input and returns a result object
+ upon successful execution of a "read" type query.
- .. method:: load_rdriver()
+ Returns:
- :returns: The DB_result object appropriate for the driver in use
- :rtype: DB_result
+ - Boolean TRUE upon successful execution of a "write type" queries
+ - Boolean FALSE upon failure
+ - ``CI_DB_result`` object for "read type" queries
- Load the result drivers
+ .. note: If 'db_debug' setting is set to TRUE, an error
+ page will be displayed instead of returning FALSE
+ on failures and script execution will stop.
.. method:: simple_query($sql)
:param string $sql: The SQL statement to execute
- :returns: True on "update" success, DB_result object on "query" success, FALSE on failure
+ :returns: Whatever the underlying driver's "query" function returns
:rtype: mixed
- Simple Query
-
- This is a simplified version of the query() function. Internally
- we only use it when running transaction commands since they do
- not require all the features of the main query() function.
+ A simplified version of the ``query()`` method, appropriate
+ for use when you don't need to get a result object or to
+ just send a query to the database and not care for the result.
- .. method:: trans_off()
+ .. method:: trans_strict([$mode = TRUE])
+ :param bool $mode: Strict mode flag
:rtype: void
- Disable Transactions.
+ Enable/disable transaction "strict" mode.
- This permits transactions to be disabled at run-time.
+ When strict mode is enabled, if you are running multiple
+ groups of transactions and one group fails, all groups
+ will be rolled back.
- .. method:: trans_strict([$mode = TRUE])
+ If strict mode is disabled, each group is treated
+ autonomously, meaning a failure of one group will not
+ affect any others.
- :param boolean $mode: TRUE for strict mode
- :rtype: void
+ .. method:: trans_off()
- Enable/disable Transaction Strict Mode.
+ :rtype: void
- When strict mode is enabled, if you are running multiple
- groups of
- transactions, if one group fails all groups will be rolled back.
- If strict mode is disabled, each group is treated autonomously,
- meaning
- a failure of one group will not affect any others.
+ Disables transactions at run-time.
- .. method:: trans_start([$test_mode = FALSE[)
+ .. method:: trans_start([$test_mode = FALSE])
- :param boolean $test_mode: TRUE for testing mode
+ :param bool $test_mode: Test mode flag
:rtype: void
- Start Transaction.
+ Start a transaction.
.. method:: trans_complete()
@@ -141,11 +152,11 @@ This article is intended to be a reference for them.
.. method:: trans_status()
- :returns: TRUE if the transaction succeeded, FALSE if it failed
- :rtype: boolean
+ :returns: TRUE if the transaction succeeded, FALSE if it failed
+ :rtype: bool
- Lets you retrieve the transaction flag to determine if it
- has failed.
+ Lets you retrieve the transaction status flag to
+ determine if it has failed.
.. method:: compile_binds($sql, $binds)
@@ -154,15 +165,16 @@ This article is intended to be a reference for them.
:returns: The updated SQL statement
:rtype: string
- Compile Bindings
+ Compiles an SQL query with the bind values passed for it.
.. method:: is_write_type($sql)
:param string $sql: The SQL statement
- :returns: TRUE if the SQL statement is a "write" type of statement
- :rtype: boolean
+ :returns: TRUE if the SQL statement is of "write type", FALSE if not
+ :rtype: bool
- Determines if a query is a "write" type.
+ Determines if a query is of a "write" type (such as
+ INSERT, UPDATE, DELETE) or "read" type (i.e. SELECT).
.. method:: elapsed_time([$decimals = 6])
@@ -174,10 +186,11 @@ This article is intended to be a reference for them.
.. method:: total_queries()
- :returns: The total number of queries
+ :returns: The total number of queries executed
:rtype: int
- Returns the total number of queries.
+ Returns the total number of queries that have been
+ executed so far.
.. method:: last_query()
@@ -188,220 +201,220 @@ This article is intended to be a reference for them.
.. method:: escape($str)
- :param string $str: The string to work with
- :returns: The escaped string
+ :param mixed $str: The value to escape, or an array of multiple ones
+ :returns: The escaped value(s)
:rtype: mixed
- "Smart" Escape String.
-
- Escapes data based on type.
- Sets boolean and null types
+ Escapes input data based on type, including boolean and
+ NULLs.
.. method:: escape_str($str[, $like = FALSE])
- :param mixed $str: The string or array of strings to work with
- :param boolean $like: Whether or not the string will be used in a LIKE condition
+ :param mixed $str: A string value or array of multiple ones
+ :param bool $like: Whether or not the string will be used in a LIKE condition
:returns: The escaped string(s)
:rtype: mixed
- Escape String.
+ Escapes string values.
+
+ .. warning:: The returned strings do NOT include quotes
+ around them.
.. method:: escape_like_str($str)
- :param mixed $str: The string or array of strings to work with
- :returns: The escaped string(s)
+ :param mixed $str: A string value or array of multiple ones
+ :returns: The escaped string(s)
:rtype: mixed
- Escape LIKE String.
-
- Calls the individual driver for platform
- specific escaping for LIKE conditions.
+ Escape LIKE strings.
- .. method:: primary([$table = ''])
+ Similar to ``escape_str()``, but will also escape the ``%``
+ and ``_`` wildcard characters, so that they don't cause
+ false-positives in LIKE conditions.
- :param string $table: The table name
- :returns: The primary key name, FALSE if none
- :rtype: mixed
+ .. method:: primary($table)
- Primary.
-
- Retrieves the primary key. It assumes that the row in the first
- position is the primary key.
+ :param string $table: Table name
+ :returns: The primary key name, FALSE if none
+ :rtype: string
+
+ Retrieves the primary key of a table.
+
+ .. note:: If the database platform does not support primary
+ key detection, the first column name may be assumed
+ as the primary key.
.. method:: count_all([$table = ''])
- :param string $table: The table name
- :returns: Record count for specified table
+ :param string $table: Table name
+ :returns: Row count for the specified table
:rtype: int
- "Count All" query.
-
- Generates a platform-specific query string that counts
- all records in
- the specified database.
+ Returns the total number of rows in a table, or 0 if no
+ table was provided.
.. method:: list_tables([$constrain_by_prefix = FALSE])
- :param boolean $constrain_by_prefix: TRUE to constrain the tables considered
- :returns: Array of table names, FALSE if the operation is unsupported
- :rtype: mixed
+ :param bool $constrain_by_prefix: TRUE to match table names by the configured dbprefix
+ :returns: Array of table names or FALSE on failure
+ :rtype: array
- Returns an array of table names.
+ Gets a list of the tables in the current database.
.. method:: table_exists($table_name)
:param string $table_name: The table name
- :returns: TRUE if that table exists
- :rtype: boolean
+ :returns: TRUE if that table exists, FALSE if not
+ :rtype: bool
Determine if a particular table exists.
- .. method:: list_fields([$table = ''])
+ .. method:: list_fields($table)
:param string $table: The table name
- :returns: Array of field names, FALSE if the table doesn't exist or the operation is un-supported
- :rtype: mixed
+ :returns: Array of field names or FALSE on failure
+ :rtype: array
- Fetch Field Names.
+ Gets a list of the field names in a table.
.. method:: field_exists($field_name, $table_name)
:param string $table_name: The table name
- :param string $field_name: The field name
- :returns: TRUE if that field exists in that table
- :rtype: boolean
+ :param string $field_name: The field name
+ :returns: TRUE if that field exists in that table, FALSE if not
+ :rtype: bool
Determine if a particular field exists.
- .. method:: field_data([$table = ''])
+ .. method:: field_data($table)
:param string $table: The table name
- :returns: Object with field data, FALSE if no table given
- :rtype: mixed
+ :returns: Array of field data items or FALSE on failure
+ :rtype: array
- Returns an object with field data.
+ Gets a list containing field data about a table.
.. method:: escape_identifiers($item)
:param mixed $item: The item or array of items to escape
- :returns: The item(s), escaped
+ :returns: The input item(s), escaped
:rtype: mixed
- Escape the SQL Identifiers.
-
- This function escapes column and table names
+ Escape SQL identifiers, such as column, table and names.
.. method:: insert_string($table, $data)
- :param string $table: The table upon which the query will be performed
- :param array $data: an associative array of data key/values
- :returns: The SQL insert string
+ :param string $table: The target table
+ :param array $data: An associative array of key/value pairs
+ :returns: The SQL INSERT statement, as a string
:rtype: string
- Generate an insert string.
+ Generate an INSERT statement string.
.. method:: update_string($table, $data, $where)
- :param string $table: The table upon which the query will be performed
- :param array $data: an associative array of data key/values
- :param mixed $where: the "where" statement
- :returns: The SQL update string
+ :param string $table: The target table
+ :param array $data: An associative array of key/value pairs
+ :param mixed $where: The WHERE statement conditions
+ :returns: The SQL UPDATE statement, as a string
:rtype: string
- Generate an update string.
+ Generate an UPDATE statement string.
.. method:: call_function($function)
:param string $function: Function name
- :returns: The function result
+ :returns: The function result
:rtype: string
- Enables a native PHP function to be run, using a platform
- agnostic wrapper.
+ Runs a native PHP function , using a platform agnostic
+ wrapper.
.. method:: cache_set_path([$path = ''])
- :param string $path: the path to the cache directory
- :rtype: void
+ :param string $path: Path to the cache directory
+ :rtype: void
- Set Cache Directory Path.
+ Sets the directory path to use for caching storage.
.. method:: cache_on()
- :returns: cache_on value
- :rtype: boolean
+ :returns: TRUE if caching is on, FALSE if not
+ :rtype: bool
- Enable Query Caching.
+ Enable database results caching.
.. method:: cache_off()
- :returns: cache_on value
- :rtype: boolean
+ :returns: TRUE if caching is on, FALSE if not
+ :rtype: bool
- Disable Query Caching.
+ Disable database results caching.
.. method:: cache_delete([$segment_one = ''[, $segment_two = '']])
- :param string $segment_one: first URI segment
- :param string $segment_two: second URI segment
- :returns: TRUE on success, FALSE on failure
- :rtype: boolean
+ :param string $segment_one: First URI segment
+ :param string $segment_two: Second URI segment
+ :returns: TRUE on success, FALSE on failure
+ :rtype: bool
- Delete the cache files associated with a particular URI
+ Delete the cache files associated with a particular URI.
.. method:: cache_delete_all()
- :returns: TRUE on success, FALSE on failure
- :rtype: boolean
+ :returns: TRUE on success, FALSE on failure
+ :rtype: bool
- Delete All cache files
+ Delete all cache files.
.. method:: close()
- :rtype: void
+ :rtype: void
- Close DB Connection
+ Close the DB Connection.
.. method:: display_error([$error = ''[, $swap = ''[, $native = FALSE]]])
- :param string $error: the error message
- :param string $swap: any "swap" values
- :param boolean $native: whether to localize the message
- :returns: sends the application/views/errors/error_db.php template
+ :param string $error: The error message
+ :param string $swap: Any "swap" values
+ :param bool $native: Whether to localize the message
+ :rtype: void
+
+ :returns: Displays the DB error screensends the application/views/errors/error_db.php template
:rtype: string
- Display an error message
+ Display an error message and stop script execution.
+
+ The message is displayed using the
+ *application/views/errors/error_db.php* template.
.. method:: protect_identifiers($item[, $prefix_single = FALSE[, $protect_identifiers = NULL[, $field_exists = TRUE]]])
- :param string $item: the item
- :param boolean $prefix_single: whether to use a single prefix
- :param boolean $protect_identifiers: whether to protect identifiers
- :param boolean $field_exists: whether the supplied item does not contain a field name.
- :returns: the modified item
- :rtype: string
+ :param string $item: The item to work with
+ :param bool $prefix_single: Whether to apply the dbprefix even if the input item is a single identifier
+ :param bool $protect_identifiers: Whether to quote identifiers
+ :param bool $field_exists: Whether the supplied item contains a field name or not
+ :returns: The modified item
+ :rtype: string
+
+ Takes a column or table name (optionally with an alias)
+ and applies the configured *dbprefix* to it.
+
+ Some logic is necessary in order to deal with
+ column names that include the path.
+
+ Consider a query like this::
+
+ SELECT * FROM hostname.database.table.column AS c FROM hostname.database.table
+
+ Or a query with aliasing::
+
+ SELECT m.member_id, m.member_name FROM members AS m
+
+ Since the column name can include up to four segments
+ (host, DB, table, column) or also have an alias prefix,
+ we need to do a bit of work to figure this out and
+ insert the table prefix (if it exists) in the proper
+ position, and escape only the correct identifiers.
- Protect Identifiers.
-
- This function is used extensively by the Query Builder class,
- and by
- a couple functions in this class.
- It takes a column or table name (optionally with an alias)
- and inserts
- the table prefix onto it. Some logic is necessary in order
- to deal with
- column names that include the path. Consider a query like this::
-
- SELECT * FROM hostname.database.table.column AS c FROM hostname.database.table
-
- Or a query with aliasing::
-
- SELECT m.member_id, m.member_name FROM members AS m
-
- Since the column name can include up to four segments
- (host, DB, table, column)
- or also have an alias prefix, we need to do a bit of work
- to figure this out and
- insert the table prefix (if it exists) in the proper position,
- and escape only
- the correct identifiers. \ No newline at end of file
+ This method is used extensively by the Query Builder class. \ No newline at end of file
diff --git a/user_guide_src/source/general/reserved_names.rst b/user_guide_src/source/general/reserved_names.rst
index 09c4549fd..9da94b398 100644
--- a/user_guide_src/source/general/reserved_names.rst
+++ b/user_guide_src/source/general/reserved_names.rst
@@ -16,9 +16,7 @@ the ones used by that class, otherwise your local methods will
override them. The following is a list of reserved names. Do not name
your controller any of these:
-- Controller
-- CI_Base
-- _ci_initialize
+- CI_Controller
- Default
- index
diff --git a/user_guide_src/source/installation/upgrade_300.rst b/user_guide_src/source/installation/upgrade_300.rst
index 0aaadeebc..c84d16b31 100644
--- a/user_guide_src/source/installation/upgrade_300.rst
+++ b/user_guide_src/source/installation/upgrade_300.rst
@@ -239,8 +239,29 @@ If your application has relied on this feature, you should update it to
filter URI segments through ``$this->security->xss_clean()`` whenever you
output them.
+****************************************************************
+Step 13: Check for usage of the 'xss_clean' Form validation rule
+****************************************************************
+
+A largely unknown rule about XSS cleaning is that it should *only be
+applied to output*, as opposed to input data.
+
+We've made that mistake ourselves with our automatic and global XSS cleaning
+feature (see previous step about XSS above), so now in an effort to discourage that
+practice, we're also removing 'xss_clean' from the officially supported
+list of :doc:`form validation <../libraries/form_validation>` rules.
+
+Because the :doc:`Form Validation library <../libraries/form_validation>`
+generally validates *input* data, the 'xss_clean' rule simply doesn't
+belong in it.
+
+If you really, really need to apply that rule, you should now also load the
+:doc:`Security Helper <../helpers/security_helper>`, which contains
+``xss_clean()`` as a regular function and therefore can be also used as
+a validation rule.
+
********************************************************
-Step 13: Update usage of Input Class's get_post() method
+Step 14: Update usage of Input Class's get_post() method
********************************************************
Previously, the :doc:`Input Class <../libraries/input>` method ``get_post()``
@@ -250,15 +271,15 @@ modified so that it searches in GET then in POST, as its name suggests.
A method has been added, ``post_get()``, which searches in POST then in GET, as
``get_post()`` was doing before.
-***********************************************************************
-Step 14: Update usage of Directory Helper's directory_map() function
-***********************************************************************
+********************************************************************
+Step 15: Update usage of Directory Helper's directory_map() function
+********************************************************************
In the resulting array, directories now end with a trailing directory
separator (i.e. a slash, usually).
*************************************************************
-Step 15: Update usage of Database Forge's drop_table() method
+Step 16: Update usage of Database Forge's drop_table() method
*************************************************************
Up until now, ``drop_table()`` added an IF EXISTS clause by default or it didn't work
@@ -280,7 +301,7 @@ If your application relies on IF EXISTS, you'll have to change its usage.
all drivers with the exception of ODBC.
***********************************************************
-Step 16: Change usage of Email library with multiple emails
+Step 17: Change usage of Email library with multiple emails
***********************************************************
The :doc:`Email Library <../libraries/email>` will automatically clear the
@@ -295,7 +316,7 @@ pass FALSE as the first parameter in the ``send()`` method:
}
***************************************************
-Step 17: Update your Form_validation language lines
+Step 18: Update your Form_validation language lines
***************************************************
Two improvements have been made to the :doc:`Form Validation Library
@@ -326,7 +347,7 @@ files and error messages format:
later.
****************************************************************
-Step 18: Remove usage of (previously) deprecated functionalities
+Step 19: Remove usage of (previously) deprecated functionalities
****************************************************************
In addition to the ``$autoload['core']`` configuration setting, there's a
diff --git a/user_guide_src/source/libraries/form_validation.rst b/user_guide_src/source/libraries/form_validation.rst
index aae9e3b89..f964965ec 100644
--- a/user_guide_src/source/libraries/form_validation.rst
+++ b/user_guide_src/source/libraries/form_validation.rst
@@ -326,14 +326,13 @@ In addition to the validation method like the ones we used above, you
can also prep your data in various ways. For example, you can set up
rules like this::
- $this->form_validation->set_rules('username', 'Username', 'trim|required|min_length[5]|max_length[12]|xss_clean');
+ $this->form_validation->set_rules('username', 'Username', 'trim|required|min_length[5]|max_length[12]');
$this->form_validation->set_rules('password', 'Password', 'trim|required|md5');
$this->form_validation->set_rules('passconf', 'Password Confirmation', 'trim|required|matches[password]');
$this->form_validation->set_rules('email', 'Email', 'trim|required|valid_email');
-In the above example, we are "trimming" the fields, converting the
-password to MD5, and running the username through the `xss_clean()`
-method, which removes malicious data.
+In the above example, we are "trimming" the fields, checking for length
+where necessary and converting the password to MD5.
**Any native PHP function that accepts one parameter can be used as a
rule, like htmlspecialchars, trim, md5, etc.**
@@ -1002,7 +1001,6 @@ to use:
==================== ========= =======================================================================================================
Name Parameter Description
==================== ========= =======================================================================================================
-**xss_clean** No Runs the data through the XSS filtering method, described in the :doc:`Security Class <security>` page.
**prep_for_form** No Converts special characters so that HTML data can be shown in a form field without breaking it.
**prep_url** No Adds "\http://" to URLs if missing.
**strip_image_tags** No Strips the HTML from image tags leaving the raw URL.