diff options
Diffstat (limited to 'user_guide_src')
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. |