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/changelog.rst2
-rw-r--r--user_guide_src/source/contributing/index.rst4
-rw-r--r--user_guide_src/source/database/configuration.rst3
-rw-r--r--user_guide_src/source/database/forge.rst149
-rw-r--r--user_guide_src/source/database/helpers.rst61
-rw-r--r--user_guide_src/source/database/index.rst2
-rw-r--r--user_guide_src/source/database/queries.rst24
-rw-r--r--user_guide_src/source/database/query_builder.rst230
-rw-r--r--user_guide_src/source/database/results.rst43
-rw-r--r--user_guide_src/source/database/utilities.rst126
-rw-r--r--user_guide_src/source/documentation/index.rst18
-rw-r--r--user_guide_src/source/index.rst17
-rw-r--r--user_guide_src/source/libraries/input.rst40
-rw-r--r--user_guide_src/source/libraries/language.rst90
-rw-r--r--user_guide_src/source/libraries/pagination.rst78
-rw-r--r--user_guide_src/source/libraries/parser.rst230
16 files changed, 804 insertions, 313 deletions
diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst
index 00cdd58c5..08b692168 100644
--- a/user_guide_src/source/changelog.rst
+++ b/user_guide_src/source/changelog.rst
@@ -477,6 +477,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.
@@ -503,6 +504,7 @@ Release Date: Not Released
- Added methods ``get_content_type()`` and ``get_header()``.
- Added method ``delete_cache()``.
- Changed caching behavior to compress the output before storing it, if ``$config['compress_output']`` is enabled.
+ - Changed caching to take the query string into account.
- :doc:`Config Library <libraries/config>` changes include:
diff --git a/user_guide_src/source/contributing/index.rst b/user_guide_src/source/contributing/index.rst
index c784a59e5..3548dbca1 100644
--- a/user_guide_src/source/contributing/index.rst
+++ b/user_guide_src/source/contributing/index.rst
@@ -31,9 +31,9 @@ If you are having trouble using a feature of CodeIgniter, ask for help on the fo
If you are wondering if you are using
something correctly or if you have found a bug, ask on the forum first.
-***************************
+****************************
Tips for a Good Issue Report
-***************************
+****************************
Use a descriptive subject line (eg parser library chokes on commas) rather than a vague one (eg. your code broke).
diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst
index 34cefffbd..9f52ad2a2 100644
--- a/user_guide_src/source/database/configuration.rst
+++ b/user_guide_src/source/database/configuration.rst
@@ -141,7 +141,8 @@ Query Builder
The :doc:`Query Builder Class <query_builder>` is globally enabled or
disabled by setting the $query_builder variable in the database
-configuration file to TRUE/FALSE (boolean). If you are not using the
+configuration file to TRUE/FALSE (boolean). The default setting is TRUE.
+If you are not using the
query builder class, setting it to FALSE will utilize fewer resources
when the database classes are initialized.
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/database/helpers.rst b/user_guide_src/source/database/helpers.rst
index 77bf1b5d2..2d997a9e0 100644
--- a/user_guide_src/source/database/helpers.rst
+++ b/user_guide_src/source/database/helpers.rst
@@ -1,9 +1,11 @@
-######################
-Query Helper Functions
-######################
+####################
+Query Helper Methods
+####################
-$this->db->insert_id()
-======================
+Information From Executing a Query
+==================================
+
+**$this->db->insert_id()**
The insert ID number when performing database inserts.
@@ -11,8 +13,7 @@ The insert ID number when performing database inserts.
driver, this function requires a $name parameter, which specifies the
appropriate sequence to check for the insert id.
-$this->db->affected_rows()
-==========================
+**$this->db->affected_rows()**
Displays the number of affected rows, when doing "write" type queries
(insert, update, etc.).
@@ -22,8 +23,23 @@ Displays the number of affected rows, when doing "write" type queries
affected rows. By default this hack is enabled but it can be turned off
in the database driver file.
-$this->db->count_all()
-======================
+**$this->db->last_query()**
+
+Returns the last query that was run (the query string, not the result).
+Example::
+
+ $str = $this->db->last_query();
+
+ // Produces: SELECT * FROM sometable....
+
+
+.. note:: Disabling the **save_queries** setting in your database
+ configuration will render this function useless.
+
+Information About Your Database
+===============================
+
+**$this->db->count_all()**
Permits you to determine the number of rows in a particular table.
Submit the table name in the first parameter. Example::
@@ -32,38 +48,24 @@ Submit the table name in the first parameter. Example::
// Produces an integer, like 25
-$this->db->platform()
-=====================
+**$this->db->platform()**
Outputs the database platform you are running (MySQL, MS SQL, Postgres,
etc...)::
echo $this->db->platform();
-$this->db->version()
-====================
+**$this->db->version()**
Outputs the database version you are running::
echo $this->db->version();
-$this->db->last_query()
-=======================
-
-Returns the last query that was run (the query string, not the result).
-Example::
-
- $str = $this->db->last_query();
-
- // Produces: SELECT * FROM sometable....
-
-
-.. note:: Disabling the **save_queries** setting in your database
- configuration will render this function useless.
-
-$this->db->insert_string()
+Making Your Queries Easier
==========================
+**$this->db->insert_string()**
+
This function simplifies the process of writing database inserts. It
returns a correctly formatted SQL insert string. Example::
@@ -78,8 +80,7 @@ array with the data to be inserted. The above example produces::
.. note:: Values are automatically escaped, producing safer queries.
-$this->db->update_string()
-==========================
+**$this->db->update_string()**
This function simplifies the process of writing database updates. It
returns a correctly formatted SQL update string. Example::
diff --git a/user_guide_src/source/database/index.rst b/user_guide_src/source/database/index.rst
index 7ccb8fb00..cfd624238 100644
--- a/user_guide_src/source/database/index.rst
+++ b/user_guide_src/source/database/index.rst
@@ -1,5 +1,5 @@
##################
-The Database Class
+Database Reference
##################
CodeIgniter comes with a full-featured and very fast abstracted database
diff --git a/user_guide_src/source/database/queries.rst b/user_guide_src/source/database/queries.rst
index 76ff1083f..43a0a30bf 100644
--- a/user_guide_src/source/database/queries.rst
+++ b/user_guide_src/source/database/queries.rst
@@ -2,10 +2,14 @@
Queries
#######
-$this->db->query();
-===================
+************
+Query Basics
+************
-To submit a query, use the following function::
+Regular Queries
+===============
+
+To submit a query, use the **query** function::
$this->db->query('YOUR QUERY HERE');
@@ -18,10 +22,11 @@ this::
$query = $this->db->query('YOUR QUERY HERE');
-$this->db->simple_query();
-==========================
+Simplified Queries
+==================
-This is a simplified version of the $this->db->query() method. It DOES
+The **simple_query** method is a simplified version of the
+$this->db->query() method. It DOES
NOT return a database result set, nor does it set the query timer, or
compile bind data, or store your query for debugging. It simply lets you
submit a query. Most users will rarely use this function.
@@ -116,7 +121,9 @@ this:
::
- $search = '20% raise'; $sql = "SELECT id FROM table WHERE column LIKE '%".$this->db->escape_like_str($search)."%'";
+ $search = '20% raise';
+ $sql = "SELECT id FROM table WHERE column LIKE '%" .
+ $this->db->escape_like_str($search)."%'";
**************
@@ -150,8 +157,7 @@ you.
Handling Errors
***************
-$this->db->error();
-===================
+**$this->db->error();**
If you need to get the last error that has occured, the error() method
will return an array containing its code and message. Here's a quick
diff --git a/user_guide_src/source/database/query_builder.rst b/user_guide_src/source/database/query_builder.rst
index 5bfdfdb52..3203ff103 100644
--- a/user_guide_src/source/database/query_builder.rst
+++ b/user_guide_src/source/database/query_builder.rst
@@ -19,7 +19,9 @@ system.
class in your database config file, allowing the core database library
and adapter to utilize fewer resources.
-.. contents:: Page Contents
+.. contents::
+ :local:
+ :depth: 1
**************
Selecting Data
@@ -28,7 +30,7 @@ Selecting Data
The following functions allow you to build SQL **SELECT** statements.
$this->db->get()
-================
+----------------
Runs the selection query and returns the result. Can be used by itself
to retrieve all records from a table::
@@ -39,7 +41,8 @@ The second and third parameters enable you to set a limit and offset
clause::
$query = $this->db->get('mytable', 10, 20);
- // Produces: SELECT * FROM mytable LIMIT 20, 10 (in MySQL. Other databases have slightly different syntax)
+ // Produces: SELECT * FROM mytable LIMIT 20, 10
+ // (in MySQL. Other databases have slightly different syntax)
You'll notice that the above function is assigned to a variable named
$query, which can be used to show the results::
@@ -54,10 +57,13 @@ $query, which can be used to show the results::
Please visit the :doc:`result functions <results>` page for a full
discussion regarding result generation.
+:returns: DB_Result for a successful "read",
+ TRUE for a successful "write", FALSE if an error
+
$this->db->get_compiled_select()
-================================
+--------------------------------
-Compiles the selection query just like `$this->db->get()`_ but does not *run*
+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::
@@ -79,14 +85,15 @@ will be reset (by default it will be reset, just like when using `$this->db->get
// Produces string: SELECT title, content, date FROM mytable LIMIT 20, 10
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
+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()`_.
+executed using **$this->db->get()** which resets values or reset directly
+using **$this->db->reset_query()**.
+:returns: The SQL select string
$this->db->get_where()
-======================
+----------------------
Identical to the above function except that it permits you to add a
"where" clause in the second parameter, instead of using the db->where()
@@ -98,8 +105,11 @@ Please read the about the where function below for more information.
.. note:: get_where() was formerly known as getwhere(), which has been removed
+:returns: DB_Result for a successful "read",
+ TRUE for a successful "write", FALSE if an error
+
$this->db->select()
-===================
+-------------------
Permits you to write the SELECT portion of your query::
@@ -119,9 +129,10 @@ 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);
$query = $this->db->get('mytable');
+:returns: The query builder object
$this->db->select_max()
-=======================
+-----------------------
Writes a "SELECT MAX(field)" portion for your query. You can optionally
include a second parameter to rename the resulting field.
@@ -135,8 +146,7 @@ include a second parameter to rename the resulting field.
$query = $this->db->get('members'); // Produces: SELECT MAX(age) as member_age FROM members
-$this->db->select_min()
-=======================
+**$this->db->select_min()**
Writes a "SELECT MIN(field)" portion for your query. As with
select_max(), You can optionally include a second parameter to rename
@@ -148,8 +158,7 @@ the resulting field.
$query = $this->db->get('members'); // Produces: SELECT MIN(age) as age FROM members
-$this->db->select_avg()
-=======================
+**$this->db->select_avg()**
Writes a "SELECT AVG(field)" portion for your query. As with
select_max(), You can optionally include a second parameter to rename
@@ -161,8 +170,7 @@ the resulting field.
$query = $this->db->get('members'); // Produces: SELECT AVG(age) as age FROM members
-$this->db->select_sum()
-=======================
+**$this->db->select_sum()**
Writes a "SELECT SUM(field)" portion for your query. As with
select_max(), You can optionally include a second parameter to rename
@@ -173,9 +181,11 @@ the resulting field.
$this->db->select_sum('age');
$query = $this->db->get('members'); // Produces: SELECT SUM(age) as age FROM members
+:returns: The query builder object
+
$this->db->from()
-=================
+-----------------
Permits you to write the FROM portion of your query::
@@ -186,8 +196,10 @@ Permits you to write the FROM portion of your query::
.. note:: As shown earlier, the FROM portion of your query can be specified
in the $this->db->get() function, so use whichever method you prefer.
+:returns: The query builder object
+
$this->db->join()
-=================
+-----------------
Permits you to write the JOIN portion of your query::
@@ -211,8 +223,14 @@ outer, and right outer.
$this->db->join('comments', 'comments.id = blogs.id', 'left');
// Produces: LEFT JOIN comments ON comments.id = blogs.id
+:returns: The query builder object
+
+*************************
+Looking for Specific Data
+*************************
+
$this->db->where()
-==================
+------------------
This function enables you to set **WHERE** clauses using one of four
methods:
@@ -277,9 +295,7 @@ with backticks.
$this->db->where('MATCH (field) AGAINST ("value")', NULL, FALSE);
-
-$this->db->or_where()
-=====================
+**$this->db->or_where()**
This function is identical to the one above, except that multiple
instances are joined by OR::
@@ -290,8 +306,10 @@ instances are joined by OR::
.. note:: or_where() was formerly known as orwhere(), which has been
removed.
+:returns: The query builder object
+
$this->db->where_in()
-=====================
+---------------------
Generates a WHERE field IN ('item', 'item') SQL query joined with AND if
appropriate
@@ -303,8 +321,7 @@ appropriate
// Produces: WHERE username IN ('Frank', 'Todd', 'James')
-$this->db->or_where_in()
-========================
+**$this->db->or_where_in()**
Generates a WHERE field IN ('item', 'item') SQL query joined with OR if
appropriate
@@ -315,9 +332,10 @@ appropriate
$this->db->or_where_in('username', $names);
// Produces: OR username IN ('Frank', 'Todd', 'James')
+:returns: The query builder object
$this->db->where_not_in()
-=========================
+-------------------------
Generates a WHERE field NOT IN ('item', 'item') SQL query joined with
AND if appropriate
@@ -329,8 +347,7 @@ AND if appropriate
// Produces: WHERE username NOT IN ('Frank', 'Todd', 'James')
-$this->db->or_where_not_in()
-============================
+**$this->db->or_where_not_in()**
Generates a WHERE field NOT IN ('item', 'item') SQL query joined with OR
if appropriate
@@ -341,9 +358,15 @@ if appropriate
$this->db->or_where_not_in('username', $names);
// Produces: OR username NOT IN ('Frank', 'Todd', 'James')
+:returns: The query builder object
+
+
+************************
+Looking for Similar Data
+************************
$this->db->like()
-=================
+-----------------
This method enables you to generate **LIKE** clauses, useful for doing
searches.
@@ -383,8 +406,7 @@ searches.
// WHERE `title` LIKE '%match%' ESCAPE '!' AND `page1` LIKE '%match%' ESCAPE '!' AND `page2` LIKE '%match%' ESCAPE '!'
-$this->db->or_like()
-====================
+**$this->db->or_like()**
This method is identical to the one above, except that multiple
instances are joined by OR::
@@ -394,16 +416,14 @@ instances are joined by OR::
.. note:: ``or_like()`` was formerly known as ``orlike()``, which has been removed.
-$this->db->not_like()
-=====================
+**$this->db->not_like()**
This method is identical to ``like()``, except that it generates
NOT LIKE statements::
$this->db->not_like('title', 'match'); // WHERE `title` NOT LIKE '%match% ESCAPE '!'
-$this->db->or_not_like()
-========================
+**$this->db->or_not_like()**
This method is identical to ``not_like()``, except that multiple
instances are joined by OR::
@@ -412,8 +432,10 @@ instances are joined by OR::
$this->db->or_not_like('body', 'match');
// WHERE `title` LIKE '%match% OR `body` NOT LIKE '%match%' ESCAPE '!'
+:returns: The query builder object
+
$this->db->group_by()
-=====================
+---------------------
Permits you to write the GROUP BY portion of your query::
@@ -426,8 +448,10 @@ You can also pass an array of multiple values as well::
.. note:: group_by() was formerly known as groupby(), which has been
removed.
+:returns: The query builder object
+
$this->db->distinct()
-=====================
+---------------------
Adds the "DISTINCT" keyword to a query
@@ -436,9 +460,10 @@ Adds the "DISTINCT" keyword to a query
$this->db->distinct();
$this->db->get('table'); // Produces: SELECT DISTINCT * FROM table
+:returns: The query builder object
$this->db->having()
-===================
+-------------------
Permits you to write the HAVING portion of your query. There are 2
possible syntaxes, 1 argument or 2::
@@ -462,13 +487,18 @@ setting it to FALSE.
$this->db->having('user_id', 45, FALSE); // Produces: HAVING user_id = 45
-$this->db->or_having()
-======================
+**$this->db->or_having()**
Identical to having(), only separates multiple clauses with "OR".
+:returns: The query builder object
+
+****************
+Ordering results
+****************
+
$this->db->order_by()
-=====================
+---------------------
Lets you set an ORDER BY clause.
@@ -512,8 +542,14 @@ be ignored, unless you specify a numeric seed value.
.. note:: Random ordering is not currently supported in Oracle and
will default to ASC instead.
+:returns: The query builder object
+
+****************************
+Limiting or Counting Results
+****************************
+
$this->db->limit()
-==================
+------------------
Lets you limit the number of rows you would like returned by the query::
@@ -525,8 +561,10 @@ The second parameter lets you set a result offset.
$this->db->limit(10, 20); // Produces: LIMIT 20, 10 (in MySQL. Other databases have slightly different syntax)
+:returns: The query builder object
+
$this->db->count_all_results()
-==============================
+------------------------------
Permits you to determine the number of rows in a particular Active
Record query. Queries will accept Query Builder restrictors such as
@@ -537,14 +575,18 @@ where(), or_where(), like(), or_like(), etc. Example::
$this->db->from('my_table');
echo $this->db->count_all_results(); // Produces an integer, like 17
+:returns: Count of all the records returned by a query
+
$this->db->count_all()
-======================
+----------------------
Permits you to determine the number of rows in a particular table.
Submit the table name in the first parameter. Example::
echo $this->db->count_all('my_table'); // Produces an integer, like 25
+:returns: Count of all the records in the specified table
+
**************
Query grouping
**************
@@ -568,37 +610,34 @@ you to create queries with complex WHERE clauses. Nested groups are supported. E
.. note:: groups need to be balanced, make sure every group_start() is matched by a group_end().
-$this->db->group_start()
-========================
+**$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()
-===========================
+**$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()
-============================
+**$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()
-===============================
+**$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()
-======================
+**$this->db->group_end()**
Ends the current group by adding an closing parenthesis to the WHERE clause of the query.
+:returns: The query builder object
+
**************
Inserting Data
**************
$this->db->insert()
-===================
+-------------------
Generates an insert string based on the data you supply, and runs the
query. You can either pass an **array** or an **object** to the
@@ -635,8 +674,11 @@ object.
.. note:: All values are escaped automatically producing safer queries.
+:returns: DB_Query on success, FALSE on failure
+
$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.
@@ -672,8 +714,10 @@ using `$this->db->insert()` which resets values or reset directly using
.. note:: This method doesn't work for batched inserts.
+:returns: The SQL insert string
+
$this->db->insert_batch()
-=========================
+-------------------------
Generates an insert string based on the data you supply, and runs the
query. You can either pass an **array** or an **object** to the
@@ -700,8 +744,14 @@ associative array of values.
.. note:: All values are escaped automatically producing safer queries.
+:returns: Count of the number of records inserted on success, FALSE on failure
+
+*************
+Updating Data
+*************
+
$this->db->replace()
-====================
+--------------------
This method executes a REPLACE statement, which is basically the SQL
standard for (optional) DELETE + INSERT, using *PRIMARY* and *UNIQUE*
@@ -729,8 +779,10 @@ will be deleted with our new row data replacing it.
Usage of the ``set()`` method is also allowed and all fields are
automatically escaped, just like with ``insert()``.
+:returns: DB_query object on success, FALSE on failure
+
$this->db->set()
-================
+----------------
This function enables you to set values for inserts or updates.
@@ -788,12 +840,10 @@ Or an object::
$this->db->set($object);
$this->db->insert('mytable');
-*************
-Updating Data
-*************
+:returns: The query builder object
$this->db->update()
-===================
+-------------------
Generates an update string and runs the query based on the data you
supply. You can pass an **array** or an **object** to the function. Here
@@ -839,9 +889,10 @@ Or as an array::
You may also use the $this->db->set() function described above when
performing updates.
+:returns: DB_query object on success, FALSE on failure
$this->db->update_batch()
-=========================
+-------------------------
Generates an update string based on the data you supply, and runs the query.
You can either pass an **array** or an **object** to the function.
@@ -882,8 +933,10 @@ array of values, the third parameter is the where key.
due to the very nature of how it works. Instead, ``update_batch()``
returns the number of rows affected.
+:returns: Count of the number of records affected on success, FALSE on failure
+
$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.
@@ -892,12 +945,14 @@ For more information view documentation for `$this->db->get_compiled_insert()`.
.. note:: This method doesn't work for batched updates.
+:returns: The SQL update string
+
*************
Deleting Data
*************
$this->db->delete()
-===================
+-------------------
Generates a delete SQL string and runs the query.
@@ -930,17 +985,21 @@ delete data from more than 1 table.
If you want to delete all data from a table, you can use the truncate()
function, or empty_table().
+:returns: DB_Query on success, FALSE on failure
+
$this->db->empty_table()
-========================
+------------------------
Generates a delete SQL string and runs the
query.::
$this->db->empty_table('mytable'); // Produces: DELETE FROM mytable
+:returns: DB_Query on success, FALSE on failure
+
$this->db->truncate()
-=====================
+---------------------
Generates a truncate SQL string and runs the query.
@@ -959,13 +1018,20 @@ Generates a truncate SQL string and runs the query.
.. note:: If the TRUNCATE command isn't available, truncate() will
execute as "DELETE FROM table".
+:returns: DB_Query on success, FALSE on failure
+
$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()`_.
+:returns: The SQL delete string
+
+
+
***************
Method Chaining
***************
@@ -994,23 +1060,25 @@ Cached calls are cumulative. If you make 2 cached select() calls, and
then 2 uncached select() calls, this will result in 4 select() calls.
There are three Caching functions available:
-$this->db->start_cache()
-========================
+**$this->db->start_cache()**
This function must be called to begin caching. All Query Builder queries
of the correct type (see below for supported queries) are stored for
later use.
-$this->db->stop_cache()
-=======================
+**$this->db->stop_cache()**
This function can be called to stop caching.
-$this->db->flush_cache()
-========================
+**$this->db->flush_cache()**
This function deletes all items from the Query Builder cache.
+:returns: void
+
+An example of caching
+---------------------
+
Here's a usage example::
$this->db->start_cache();
@@ -1033,8 +1101,12 @@ Here's a usage example::
where, like, group_by, having, order_by, set
+***********************
+Resetting Query Builder
+***********************
+
$this->db->reset_query()
-========================
+------------------------
Resetting Query Builder allows you to start fresh with your query without
executing it first using a method like $this->db->get() or $this->db->insert().
@@ -1063,4 +1135,6 @@ run the query::
.. note:: Double calls to ``get_compiled_select()`` while you're using the
Query Builder Caching functionality and NOT resetting your queries
will results in the cache being merged twice. That in turn will
- i.e. if you're caching a ``select()`` - select the same field twice. \ No newline at end of file
+ i.e. if you're caching a ``select()`` - select the same field twice.
+
+:returns: void
diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst
index e0a87a851..e06985130 100644
--- a/user_guide_src/source/database/results.rst
+++ b/user_guide_src/source/database/results.rst
@@ -4,10 +4,14 @@ Generating Query Results
There are several ways to generate query results:
+*************
+Result Arrays
+*************
+
result()
========
-This function returns the query result as an array of **objects**, or
+This method returns the query result as an array of **objects**, or
**an empty array** on failure. Typically you'll use this in a foreach
loop, like this::
@@ -20,7 +24,7 @@ loop, like this::
echo $row->body;
}
-The above function is an alias of result_object().
+The above method is an alias of result_object().
If you run queries that might **not** produce a result, you are
encouraged to test the result first::
@@ -53,7 +57,7 @@ instantiate for each result object (note: this class must be loaded)
result_array()
===============
-This function returns the query result as a pure array, or an empty
+This method returns the query result as a pure array, or an empty
array when no result is produced. Typically you'll use this in a foreach
loop, like this::
@@ -66,10 +70,14 @@ loop, like this::
echo $row['body'];
}
+***********
+Result Rows
+***********
+
row()
=====
-This function returns a single result row. If your query has more than
+This method returns a single result row. If your query has more than
one row, it returns only the first row. The result is returned as an
**object**. Here's a usage example::
@@ -101,7 +109,7 @@ to instantiate the row with::
row_array()
===========
-Identical to the above row() function, except it returns an array.
+Identical to the above row() method, except it returns an array.
Example::
$query = $this->db->query("YOUR QUERY");
@@ -136,7 +144,8 @@ parameter:
| **$row = $query->next_row('array')**
| **$row = $query->previous_row('array')**
-.. note:: all the functions above will load the whole result into memory (prefetching) use unbuffered_row() for processing large result sets.
+.. note:: all the methods above will load the whole result into memory
+ (prefetching) use unbuffered_row() for processing large result sets.
unbuffered_row()
================
@@ -163,12 +172,11 @@ the returned value's type::
$query->unbuffered_row('object'); // object
$query->unbuffered_row('array'); // associative array
-***********************
-Result Helper Functions
-***********************
+*********************
+Result Helper Methods
+*********************
-$query->num_rows()
-==================
+**$query->num_rows()**
The number of rows returned by the query. Note: In this example, $query
is the variable that the query result object is assigned to::
@@ -181,20 +189,18 @@ is the variable that the query result object is assigned to::
Not all database drivers have a native way of getting the total
number of rows for a result set. When this is the case, all of
the data is prefetched and count() is manually called on the
- resulting array in order to achieve the same functionality.
+ resulting array in order to achieve the same methodality.
-$query->num_fields()
-====================
+**$query->num_fields()**
The number of FIELDS (columns) returned by the query. Make sure to call
-the function using your query result object::
+the method using your query result object::
$query = $this->db->query('SELECT * FROM my_table');
echo $query->num_fields();
-$query->free_result()
-=====================
+**$query->free_result()**
It frees the memory associated with the result and deletes the result
resource ID. Normally PHP frees its memory automatically at the end of
@@ -217,8 +223,7 @@ Example::
echo $row->name;
$query2->free_result(); // The $query2 result object will no longer be available
-data_seek()
-===========
+**data_seek()**
This method sets the internal pointer for the next result row to be
fetched. It is only useful in combination with ``unbuffered_row()``.
diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst
index bd40cdadd..d15cef06d 100644
--- a/user_guide_src/source/database/utilities.rst
+++ b/user_guide_src/source/database/utilities.rst
@@ -5,15 +5,14 @@ Database Utility Class
The Database Utility Class contains methods that help you manage your
database.
-.. contents:: Table of Contents
+.. contents::
+ :local:
+ :depth: 2
-******************
-Function Reference
-******************
-
+******************************
Initializing the Utility Class
-==============================
+******************************
.. important:: In order to initialize the Utility class, your database
driver must already be running, since the utilities class relies on it.
@@ -39,7 +38,11 @@ object::
$this->dbutil->some_method()
-$this->dbutil->list_databases();
+****************************
+Using the Database Utilities
+****************************
+
+Retrieve list of database names
================================
Returns an array of database names::
@@ -51,8 +54,9 @@ Returns an array of database names::
echo $db;
}
-$this->dbutil->database_exists();
-=================================
+
+Determine If a Database Exists
+==============================
Sometimes it's helpful to know whether a particular database exists.
Returns a boolean TRUE/FALSE. Usage example::
@@ -65,8 +69,8 @@ Returns a boolean TRUE/FALSE. Usage example::
.. note:: Replace *database_name* with the name of the table you are
looking for. This method is case sensitive.
-$this->dbutil->optimize_table('table_name');
-============================================
+Optimize a Table
+================
Permits you to optimize a table using the table name specified in the
first parameter. Returns TRUE/FALSE based on success or failure::
@@ -79,8 +83,8 @@ first parameter. Returns TRUE/FALSE based on success or failure::
.. note:: Not all database platforms support table optimization. It is
mostly for use with MySQL.
-$this->dbutil->repair_table('table_name');
-==========================================
+Repair a Table
+==============
Permits you to repair a table using the table name specified in the
first parameter. Returns TRUE/FALSE based on success or failure::
@@ -92,8 +96,8 @@ first parameter. Returns TRUE/FALSE based on success or failure::
.. note:: Not all database platforms support table repairs.
-$this->dbutil->optimize_database();
-====================================
+Optimize a Database
+===================
Permits you to optimize the database your DB class is currently
connected to. Returns an array containing the DB status messages or
@@ -111,8 +115,8 @@ FALSE on failure.
.. note:: Not all database platforms support table optimization. It
it is mostly for use with MySQL.
-$this->dbutil->csv_from_result($db_result);
-===========================================
+Export a Query Result as a CSV File
+===================================
Permits you to generate a CSV file from a query result. The first
parameter of the method must contain the result object from your
@@ -139,8 +143,8 @@ is used as the enclosure. Example::
simply creates the CSV layout. If you need to write the file
use the :doc:`File Helper <../helpers/file_helper>`.
-$this->dbutil->xml_from_result($db_result);
-===========================================
+Export a Query Result as an XML Document
+========================================
Permits you to generate an XML file from a query result. The first
parameter expects a query result object, the second may contain an
@@ -163,8 +167,12 @@ optional array of config parameters. Example::
simply creates the XML layout. If you need to write the file
use the :doc:`File Helper <../helpers/file_helper>`.
-$this->dbutil->backup();
-========================
+********************
+Backup Your Database
+********************
+
+Database Backup Notes
+=====================
Permits you to backup your full database or individual tables. The
backup data can be compressed in either Zip or Gzip format.
@@ -182,7 +190,7 @@ backup data can be compressed in either Zip or Gzip format.
have root privileges.
Usage Example
--------------
+=============
::
@@ -201,7 +209,7 @@ Usage Example
force_download('mybackup.gz', $backup);
Setting Backup Preferences
---------------------------
+==========================
Backup preferences are set by submitting an array of values to the first
parameter of the ``backup()`` method. Example::
@@ -219,7 +227,7 @@ parameter of the ``backup()`` method. Example::
$this->dbutil->backup($prefs);
Description of Backup Preferences
----------------------------------
+=================================
======================= ======================= ======================= ========================================================================
Preference Default Value Options Description
@@ -234,4 +242,72 @@ Preference Default Value Options Descript
**add_insert** TRUE TRUE/FALSE Whether to include INSERT statements in your SQL export file.
**newline** "\\n" "\\n", "\\r", "\\r\\n" Type of newline to use in your SQL export file.
**foreign_key_checks** TRUE TRUE/FALSE Whether output should keep foreign key checks enabled.
-======================= ======================= ======================= ======================================================================== \ No newline at end of file
+======================= ======================= ======================= ========================================================================
+
+***************
+Class Reference
+***************
+
+.. class:: DB_utility
+
+ .. method:: backup($params)
+
+ :param array $params: associative array of backup preferences
+ :returns: 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
+
+ .. method:: database_exists($database_name)
+
+ :param string $database_name: name of the database to check for
+ :returns: TRUE if the database exists, FALSE otherwise
+ :rtype: boolean
+
+ Check for the existence of a database
+
+ .. method:: list_databases()
+
+ :returns: Array of database names found
+ :rtype: array
+
+ Retrieve all the database names
+
+ .. method:: optimize_database()
+
+ :returns: Array of optimization messages, FALSE on failure
+ :rtype: array
+
+ Optimizes a 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
+
+ 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
+
+ Repairs a database table
+
+ .. method:: xml_from_results($query, $params)
+
+ :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
diff --git a/user_guide_src/source/documentation/index.rst b/user_guide_src/source/documentation/index.rst
index 38124f7f2..6d4c94bc1 100644
--- a/user_guide_src/source/documentation/index.rst
+++ b/user_guide_src/source/documentation/index.rst
@@ -5,11 +5,11 @@ Writing CodeIgniter Documentation
CodeIgniter uses Sphinx to generate its documentation in a variety of formats,
using reStructuredText to handle the formatting. If you are familiar with
Markdown or Textile, you will quickly grasp reStructuredText. The focus is
-on readability, user friendliness, and an "I've got your hand, baby" feel.
+on readability and user friendliness.
While they can be quite technical, we always write for humans!
-A local table of contents should always be included like the one below.
-It is created automatically by inserting the the following:
+A local table of contents should always be included, like the one below.
+It is created automatically by inserting the following:
::
@@ -110,8 +110,8 @@ Method Documentation
********************
When documenting class methods for third party developers, Sphinx provides
-directives to assist and keep things simple. For example, consider the following
-ReST:
+directives to assist and keep things simple.
+For example, consider the following ReST:
.. code-block:: rst
@@ -124,7 +124,7 @@ ReST:
parameter.
:param int $foo: the foo id to do something in
- :param mixed $bar: A data array that must contain aa something and something else
+ :param mixed $bar: A data array that must contain a something and something else
:param bool $bat: whether or not to do something
:returns: FALSE on failure, TRUE if successful
:rtype: bool
@@ -153,7 +153,7 @@ ReST:
.. method:: should_do_something()
- :returns: Whether or something should be done or not
+ :returns: Whether or not something should be done
:rtype: bool
@@ -169,7 +169,7 @@ It creates the following display:
parameter.
:param int $foo: the foo id to do something in
- :param mixed $bar: A data array that must contain aa something and something else
+ :param mixed $bar: A data array that must contain a something and something else
:param bool $bat: whether or not to do something
:returns: FALSE on failure, TRUE if successful
:rtype: bool
@@ -198,5 +198,5 @@ It creates the following display:
.. method:: should_do_something()
- :returns: Whether or something should be done or not
+ :returns: Whether or not something should be done
:rtype: bool \ No newline at end of file
diff --git a/user_guide_src/source/index.rst b/user_guide_src/source/index.rst
index 09bf770fc..d8f60e360 100644
--- a/user_guide_src/source/index.rst
+++ b/user_guide_src/source/index.rst
@@ -72,14 +72,15 @@ Library Reference
libraries/index
-****************
-Driver Reference
-****************
+******************
+Database Reference
+******************
-- :doc:`libraries/caching`
-- :doc:`database/index`
-- :doc:`libraries/javascript`
-- :doc:`libraries/sessions`
+.. toctree::
+ :glob:
+ :titlesonly:
+
+ database/index
****************
Helper Reference
@@ -100,6 +101,7 @@ Contributing to CodeIgniter
:titlesonly:
contributing/index
+ documentation/index
DCO
.. toctree::
@@ -116,6 +118,5 @@ Contributing to CodeIgniter
libraries/index
helpers/index
database/index
- documentation/index
tutorial/index
general/credits
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
diff --git a/user_guide_src/source/libraries/language.rst b/user_guide_src/source/libraries/language.rst
index 6949c11c9..c3f9b6d5a 100644
--- a/user_guide_src/source/libraries/language.rst
+++ b/user_guide_src/source/libraries/language.rst
@@ -5,14 +5,24 @@ Language Class
The Language Class provides functions to retrieve language files and
lines of text for purposes of internationalization.
-In your CodeIgniter system folder you'll find one called language
-containing sets of language files. You can create your own language
-files as needed in order to display error and other messages in other
-languages.
-
-Language files are typically stored in your **system/language/** directory.
-Alternately you can create a directory called language inside your
-application folder and store them there. CodeIgniter will always load the
+In your CodeIgniter **system** folder, you will find a **language**
+subfolder containing a set of language files for the **english** idiom.
+The files in this folder (**system/language/english/**) define the regular messages,
+error messages, and other generally output terms or expressions, for the different parts
+of the CodeIgniter core framework.
+
+You can create or incorporate your own language
+files, as needed, in order to provide application-specific error and other messages,
+or to provide translations of the core messages into other languages.
+These translations or additional messages would go inside your application/language folder,
+with separate subfolders for each idiom (for instance french or german).
+
+The CodeIgniter framework comes with a set of language files for the "english" idiom.
+Additional approved translations for different idioms may be found in the
+`CodeIgniter 3 Translations repositories <https://github.com/codeigniter3-translations>`_.
+Each repository deals with a single idiom.
+
+When CodeIgniter loads language files, it will load the
one in **system/language/** first and will then look for an override in
your **application/language/** directory.
@@ -26,6 +36,70 @@ your **application/language/** directory.
<div class="custom-index container"></div>
+***************************
+Handling Multiple Languages
+***************************
+
+If you want to support multiple languages in your application, you would provide folders inside
+your **application/language/** directory for each of them, and you would specify the default
+language in your **application/config/config.php**.
+
+The **application/language/english/** directory would contain any additional language files
+needed by your application, for instance for error messages.
+
+Each of the other idiom-specific directories would contain the core language files that you
+obtained from the translations repositories, or that you translated yourself, as well as
+any additional ones needed by your application.
+
+You would store the language you are currently using, for instance in a session variable.
+
+Sample Language Files
+=====================
+
+::
+
+ system/
+ language/
+ english/
+ ...
+ email_lang.php
+ form_validation_lang.php
+ ...
+
+ application/
+ language/
+ english/
+ error_messages_lang.php
+ french/
+ ...
+ email_lang.php
+ error_messages_lang.php
+ form_validation_lang.php
+ ...
+
+Example of switching languages
+==============================
+
+::
+
+ $idiom = $this->session->get_userdata('language');
+ $this->lang->load('error_messages',$idiom);
+ $oops = $this->lang->line('nessage_key');
+
+********************
+Internationalization
+********************
+
+The Language class in CodeIgniter is meant to provide an easy and lightweight way to support multiple
+languages in your application. It is not meant to be a full implementation of what is commonly called
+`internationalization and localization <http://en.wikipedia.org/wiki/Internationalization_and_localization>`_.
+
+We use the term "idiom" to refer to a language using its common name,
+rather than using any of the international standards, such as "en", "en-US", or "en-CA-x-ca" for English
+and some of its variants.
+
+.. note:: There is nothing to prevent you from using those abbreviations in your application!
+
************************
Using the Language Class
************************
diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst
index 8a62376f1..8c5c2c63a 100644
--- a/user_guide_src/source/libraries/pagination.rst
+++ b/user_guide_src/source/libraries/pagination.rst
@@ -73,29 +73,25 @@ Customizing the Pagination
The following is a list of all the preferences you can pass to the
initialization function to tailor the display.
-$config['uri_segment'] = 3;
-===========================
+**$config['uri_segment'] = 3;**
The pagination function automatically determines which segment of your
URI contains the page number. If you need something different you can
specify it.
-$config['num_links'] = 2;
-=========================
+**$config['num_links'] = 2;**
The number of "digit" links you would like before and after the selected
page number. For example, the number 2 will place two digits on either
side, as in the example links at the very top of this page.
-$config['use_page_numbers'] = TRUE;
-===================================
+**$config['use_page_numbers'] = TRUE;**
By default, the URI segment will use the starting index for the items
you are paginating. If you prefer to show the the actual page number,
set this to TRUE.
-$config['page_query_string'] = TRUE;
-====================================
+**$config['page_query_string'] = TRUE;**
By default, the pagination library assume you are using :doc:`URI
Segments <../general/urls>`, and constructs your links something
@@ -113,8 +109,7 @@ the pagination link will become::
Note that "per_page" is the default query string passed, however can be
configured using ``$config['query_string_segment'] = 'your_string'``
-$config['reuse_query_string'] = FALSE;
-======================================
+**$config['reuse_query_string'] = FALSE;**
By default your Query String arguments (nothing to do with other
query string options) will be ignored. Setting this config to
@@ -126,14 +121,12 @@ URL after the URI segment and before the suffix.::
This helps you mix together normal :doc:`URI Segments <../general/urls>`
as well as query string arguments, which until 3.0 was not possible.
-$config['prefix'] = '';
-=======================
+**$config['prefix'] = '';**
A custom prefix added to the path. The prefix value will be right before
the offset segment.
-$config['suffix'] = '';
-=======================
+**$config['suffix'] = '';**
A custom suffix added to the path. The sufix value will be right after
the offset segment.
@@ -145,13 +138,11 @@ Adding Enclosing Markup
If you would like to surround the entire pagination with some markup you
can do it with these two preferences:
-$config['full_tag_open'] = '<p>';
-=================================
+**$config['full_tag_open'] = '<p>';**
The opening tag placed on the left side of the entire result.
-$config['full_tag_close'] = '</p>';
-===================================
+**$config['full_tag_close'] = '</p>';**
The closing tag placed on the right side of the entire result.
@@ -159,26 +150,22 @@ The closing tag placed on the right side of the entire result.
Customizing the First Link
**************************
-$config['first_link'] = 'First';
-================================
+**$config['first_link'] = 'First';**
The text you would like shown in the "first" link on the left. If you do
not want this link rendered, you can set its value to FALSE.
.. note:: This value can also be translated via a language file.
-$config['first_tag_open'] = '<div>';
-====================================
+**$config['first_tag_open'] = '<div>';**
The opening tag for the "first" link.
-$config['first_tag_close'] = '</div>';
-======================================
+**$config['first_tag_close'] = '</div>';**
The closing tag for the "first" link.
-$config['first_url'] = '';
-==========================
+**$config['first_url'] = '';**
An alternative URL to use for the "first page" link.
@@ -186,21 +173,18 @@ An alternative URL to use for the "first page" link.
Customizing the Last Link
*************************
-$config['last_link'] = 'Last';
-==============================
+**$config['last_link'] = 'Last';**
The text you would like shown in the "last" link on the right. If you do
not want this link rendered, you can set its value to FALSE.
.. note:: This value can also be translated via a language file.
-$config['last_tag_open'] = '<div>';
-===================================
+**$config['last_tag_open'] = '<div>';**
The opening tag for the "last" link.
-$config['last_tag_close'] = '</div>';
-=====================================
+**$config['last_tag_close'] = '</div>';**
The closing tag for the "last" link.
@@ -208,21 +192,18 @@ The closing tag for the "last" link.
Customizing the "Next" Link
***************************
-$config['next_link'] = '&gt;';
-==============================
+**$config['next_link'] = '&gt;';**
The text you would like shown in the "next" page link. If you do not
want this link rendered, you can set its value to FALSE.
.. note:: This value can also be translated via a language file.
-$config['next_tag_open'] = '<div>';
-===================================
+**$config['next_tag_open'] = '<div>';**
The opening tag for the "next" link.
-$config['next_tag_close'] = '</div>';
-=====================================
+**$config['next_tag_close'] = '</div>';**
The closing tag for the "next" link.
@@ -230,21 +211,18 @@ The closing tag for the "next" link.
Customizing the "Previous" Link
*******************************
-$config['prev_link'] = '&lt;';
-==============================
+**$config['prev_link'] = '&lt;';**
The text you would like shown in the "previous" page link. If you do not
want this link rendered, you can set its value to FALSE.
.. note:: This value can also be translated via a language file.
-$config['prev_tag_open'] = '<div>';
-===================================
+**$config['prev_tag_open'] = '<div>';**
The opening tag for the "previous" link.
-$config['prev_tag_close'] = '</div>';
-=====================================
+**$config['prev_tag_close'] = '</div>';**
The closing tag for the "previous" link.
@@ -252,13 +230,11 @@ The closing tag for the "previous" link.
Customizing the "Current Page" Link
***********************************
-$config['cur_tag_open'] = '<b>';
-================================
+**$config['cur_tag_open'] = '<b>';**
The opening tag for the "current" link.
-$config['cur_tag_close'] = '</b>';
-==================================
+**$config['cur_tag_close'] = '</b>';**
The closing tag for the "current" link.
@@ -266,13 +242,11 @@ The closing tag for the "current" link.
Customizing the "Digit" Link
****************************
-$config['num_tag_open'] = '<div>';
-==================================
+**$config['num_tag_open'] = '<div>';**
The opening tag for the "digit" link.
-$config['num_tag_close'] = '</div>';
-====================================
+**$config['num_tag_close'] = '</div>';**
The closing tag for the "digit" link.
diff --git a/user_guide_src/source/libraries/parser.rst b/user_guide_src/source/libraries/parser.rst
index 5af504a03..e7c7e3abd 100644
--- a/user_guide_src/source/libraries/parser.rst
+++ b/user_guide_src/source/libraries/parser.rst
@@ -2,24 +2,26 @@
Template Parser Class
#####################
-The Template Parser Class enables you to parse pseudo-variables
-contained within your view files. It can parse simple variables or
-variable tag pairs. If you've never used a template engine,
-pseudo-variables look like this::
+The Template Parser Class can perform simple text substitution for
+pseudo-variables contained within your view files.
+It can parse simple variables or variable tag pairs.
+
+If you've never used a template engine,
+pseudo-variable names are enclosed in braces, like this::
<html>
- <head>
- <title>{blog_title}</title>
- </head>
- <body>
-
- <h3>{blog_heading}</h3>
-
- {blog_entries}
- <h5>{title}</h5>
- <p>{body}</p>
- {/blog_entries}
- </body>
+ <head>
+ <title>{blog_title}</title>
+ </head>
+ <body>
+
+ <h3>{blog_heading}</h3>
+
+ {blog_entries}
+ <h5>{title}</h5>
+ <p>{body}</p>
+ {/blog_entries}
+ </body>
</html>
These variables are not actual PHP variables, but rather plain text
@@ -28,8 +30,9 @@ representations that allow you to eliminate PHP from your templates
.. note:: CodeIgniter does **not** require you to use this class since
using pure PHP in your view pages lets them run a little faster.
- However, some developers prefer to use a template engine if they work
- with designers who they feel would find some confusion working with PHP.
+ However, some developers prefer to use a template engine if
+ they work with designers who they feel would find some
+ confusion working with PHP.
.. important:: The Template Parser Class is **not** a full-blown
template parsing solution. We've kept it very lean on purpose in order
@@ -42,6 +45,10 @@ representations that allow you to eliminate PHP from your templates
<div class="custom-index container"></div>
+*******************************
+Using the Template Parser Class
+*******************************
+
Initializing the Class
======================
@@ -56,12 +63,13 @@ $this->parser
Parsing templates
=================
-You can use the ``parse()`` method to parse (or render) simple templates, like this::
+You can use the ``parse()`` method to parse (or render) simple templates,
+like this::
$data = array(
- 'blog_title' => 'My Blog Title',
- 'blog_heading' => 'My Blog Heading'
- );
+ 'blog_title' => 'My Blog Title',
+ 'blog_heading' => 'My Blog Heading'
+ );
$this->parser->parse('blog_template', $data);
@@ -74,7 +82,7 @@ template would contain two variables: {blog_title} and {blog_heading}
There is no need to "echo" or do something with the data returned by
$this->parser->parse(). It is automatically passed to the output class
to be sent to the browser. However, if you do want the data returned
-instead of sent to the output class you can pass TRUE (boolean) to the
+instead of sent to the output class you can pass TRUE (boolean) as the
third parameter::
$string = $this->parser->parse('blog_template', $data, TRUE);
@@ -88,24 +96,24 @@ iteration containing new values? Consider the template example we showed
at the top of the page::
<html>
- <head>
- <title>{blog_title}</title>
- </head>
- <body>
-
- <h3>{blog_heading}</h3>
-
- {blog_entries}
- <h5>{title}</h5>
- <p>{body}</p>
- {/blog_entries}
- </body>
+ <head>
+ <title>{blog_title}</title>
+ </head>
+ <body>
+
+ <h3>{blog_heading}</h3>
+
+ {blog_entries}
+ <h5>{title}</h5>
+ <p>{body}</p>
+ {/blog_entries}
+ </body>
</html>
In the above code you'll notice a pair of variables: {blog_entries}
data... {/blog_entries}. In a case like this, the entire chunk of data
between these pairs would be repeated multiple times, corresponding to
-the number of rows in a result.
+the number of rows in the "blog_entries" element of the parameters array.
Parsing variable pairs is done using the identical code shown above to
parse single variables, except, you will add a multi-dimensional array
@@ -114,16 +122,16 @@ corresponding to your variable pair data. Consider this example::
$this->load->library('parser');
$data = array(
- 'blog_title' => 'My Blog Title',
- 'blog_heading' => 'My Blog Heading',
- 'blog_entries' => array(
- array('title' => 'Title 1', 'body' => 'Body 1'),
- array('title' => 'Title 2', 'body' => 'Body 2'),
- array('title' => 'Title 3', 'body' => 'Body 3'),
- array('title' => 'Title 4', 'body' => 'Body 4'),
- array('title' => 'Title 5', 'body' => 'Body 5')
- )
- );
+ 'blog_title' => 'My Blog Title',
+ 'blog_heading' => 'My Blog Heading',
+ 'blog_entries' => array(
+ array('title' => 'Title 1', 'body' => 'Body 1'),
+ array('title' => 'Title 2', 'body' => 'Body 2'),
+ array('title' => 'Title 3', 'body' => 'Body 3'),
+ array('title' => 'Title 4', 'body' => 'Body 4'),
+ array('title' => 'Title 5', 'body' => 'Body 5')
+ )
+ );
$this->parser->parse('blog_template', $data);
@@ -136,13 +144,128 @@ function::
$this->load->library('parser');
$data = array(
- 'blog_title' => 'My Blog Title',
- 'blog_heading' => 'My Blog Heading',
- 'blog_entries' => $query->result_array()
- );
+ 'blog_title' => 'My Blog Title',
+ 'blog_heading' => 'My Blog Heading',
+ 'blog_entries' => $query->result_array()
+ );
$this->parser->parse('blog_template', $data);
+Usage Notes
+===========
+
+If you include substitution parameters that are not referenced in your
+template, they are ignored::
+
+ $template = 'Hello, {firstname} {lastname}';
+ $data = array(
+ 'title' => 'Mr',
+ 'firstname' => 'John',
+ 'lastname' => 'Doe'
+ );
+ $this->parser->parse_string($template, $data);
+
+ Result: Hello, John Doe
+
+If you do not include a substitution parameter that is referenced in your
+template, the original pseudo-variable is shown in the result::
+
+ $template = 'Hello, {firstname} {initials} {lastname}';
+ $data = array(
+ 'title' => 'Mr',
+ 'firstname' => 'John',
+ 'lastname' => 'Doe'
+ );
+ $this->parser->parse_string($template, $data);
+
+ Result: Hello, John {initials} Doe
+
+If you provide a string substitution parameter when an array is expected,
+i.e. for a variable pair, the substitution is done for the opening variable
+pair tag, but the closing variable pair tag is not rendered properly::
+
+ $template = 'Hello, {firstname} {lastname} ({degrees}{degree} {/degrees})';
+ $data = array(
+ 'degrees' => 'Mr',
+ 'firstname' => 'John',
+ 'lastname' => 'Doe',
+ 'titles' => array(
+ array('degree' => 'BSc'),
+ array('degree' => 'PhD')
+
+ )
+ );
+ $this->parser->parse_string($template, $data);
+
+ Result: Hello, John Doe (Mr{degree} {/degrees})
+
+If you name one of your individual substitution parameters the same as one
+used inside a variable pair, the results
+may not be as expected::
+
+ $template = 'Hello, {firstname} {lastname} ({degrees}{degree} {/degrees})';
+ $data = array(
+ 'degree' => 'Mr',
+ 'firstname' => 'John',
+ 'lastname' => 'Doe',
+ 'degrees' => array(
+ array('degree' => 'BSc'),
+ array('degree' => 'PhD')
+
+ )
+ );
+ $this->parser->parse_string($template, $data);
+
+ Result: Hello, John Doe (Mr Mr )
+
+View Fragments
+==============
+
+You do not have to use variable pairs to get the effect of iteration in
+your views. It is possible to use a view fragment for what would be inside
+a variable pair, and to control the iteration in your controller instead
+of in the view.
+
+An example with the iteration controlled in the view::
+
+ $template = '<ul>{menuitems}
+ <li><a href="{link}">{title}</a></li>
+ {/menuitems}</ul>';
+ $data = array(
+ 'menuitems' => array(
+ array('title' => 'First Link', 'link' => '/first'),
+ array('title' => 'Second Link', 'link' => '/second'),
+ )
+ );
+ $this->parser->parse_string($template, $data);
+
+ Result:
+ - First Link
+ - Second Link
+
+An example with the iteration controlled in the controller,
+using a view fragment::
+
+ $temp = '';
+ $template1 = '<li><a href="{link}">{title}</a></li>';
+ $data1 = array(
+ array('title' => 'First Link', 'link' => '/first'),
+ array('title' => 'Second Link', 'link' => '/second'),
+ );
+ foreach ($data1 as $menuitem) {
+ $temp .= $this->parser->parse_string($template1, $menuitem, TRUE);
+ }
+
+ $template = '<ul>{menuitems}</ul>';
+ $data = array(
+ 'menuitems' => $temp
+ );
+ $this->parser->parse_string($template, $data);
+
+ Result:
+ - First Link
+ - Second Link
+
***************
Class Reference
***************
@@ -167,8 +290,8 @@ Class Reference
:returns: Parsed template string
:rtype: string
- This method works exactly like ``parse()``, only it accepts the template as a
- string instead of loading a view file.
+ This method works exactly like ``parse()``, only it accepts
+ the template as a string instead of loading a view file.
.. method:: set_delimiters([$l = '{'[, $r = '}']])
@@ -176,4 +299,5 @@ Class Reference
:param string $r: Right delimiter
:rtype: void
- Sets the delimiters (opening and closing) for a value "tag" in a template. \ No newline at end of file
+ Sets the delimiters (opening and closing) for a
+ pseudo-variable "tag" in a template. \ No newline at end of file