diff options
Diffstat (limited to 'user_guide_src')
26 files changed, 942 insertions, 388 deletions
diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst index 25f6f2cea..38fd75971 100644 --- a/user_guide_src/source/changelog.rst +++ b/user_guide_src/source/changelog.rst @@ -111,6 +111,7 @@ Release Date: Not Released - :doc:`Smiley Helper <helpers/smiley_helper>` changes include: + - Deprecated the whole helper as too specific for CodeIgniter. - Removed previously deprecated function ``js_insert_smiley()``. - Changed application and environment config files to be loaded in a cascade-like manner. - The smileys array is now cached and loaded only once. @@ -133,6 +134,7 @@ Release Date: Not Released - Added *colors* configuration to allow customization for the *background*, *border*, *text* and *grid* colors. - Added *filename* to the returned array elements. - Updated to use `imagepng()` in case that `imagejpeg()` isn't available. + - Added **font_size** option to allow customization of font size. - :doc:`Text Helper <helpers/text_helper>` changes include: @@ -315,6 +317,7 @@ Release Date: Not Released - :doc:`Cart Library <libraries/cart>` changes include: + - Deprecated the library as too specific for CodeIgniter. - Added method ``remove()`` to remove a cart item, updating with quantity of 0 seemed like a hack but has remained to retain compatibility. - Added method ``get_item()`` to enable retrieving data for a single cart item. - Added unicode support for product names. @@ -419,7 +422,11 @@ Release Date: Not Released - Added method chaining support. - Added support for setting table class defaults in a config file. - - :doc:`Zip Library <libraries/zip>` method ``read_file()`` can now also alter the original file path/name while adding files to an archive. + - :doc:`Zip Library <libraries/zip>` changes include: + + - Method ``read_file()`` can now also alter the original file path/name while adding files to an archive. + - Added support for changing the compression level. + - :doc:`Trackback Library <libraries/trackback>` method ``receive()`` will now utilize ``iconv()`` if it is available but ``mb_convert_encoding()`` is not. - Core @@ -472,6 +479,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. @@ -497,6 +505,7 @@ Release Date: Not Released - Added a second argument to method ``set_content_type()`` that allows setting the document charset as well. - Added methods ``get_content_type()`` and ``get_header()``. - Added method ``delete_cache()``. + - Added configuration option ``$config['cache_query_string']`` to enable taking the query string into account when caching. - Changed caching behavior to compress the output before storing it, if ``$config['compress_output']`` is enabled. - :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..59a6591b7 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 ------------------------- @@ -211,6 +215,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 +229,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 ================ @@ -239,8 +245,10 @@ Executes a TABLE rename 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 +277,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 +290,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 +309,100 @@ 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:: CI_DB_forge + + .. method:: add_column($table[, $field = array()[, $_after = NULL]]) + + :param string $table: Table name to add the column to + :param array $field: Column definition(s) + :param string $_after: Column for AFTER clause (deprecated) + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Adds a column to a table. Usage: See `Adding a Column to a Table`_. + + .. method:: add_field($field) + + :param array $field: Field definition to add + :returns: CI_DB_forge instance (method chaining) + :rtype: CI_DB_forge + + Adds 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 bool $primary: Set to TRUE if it should be a primary key or a regular one + :returns: CI_DB_forge instance (method chaining) + :rtype: CI_DB_forge + + Adds a key to the set that will be used to create a table. Usage: See `Adding Keys`_. + + .. method:: create_database($db_name) + + :param string $db_name: Name of the database to create + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Creates 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: Set to TRUE to add an 'IF NOT EXISTS' clause + :param string $attributes: An associative array of table attributes + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Creates a new table. Usage: See `Creating a table`_. + + .. method:: drop_column($table, $column_name) + + :param string $table: Table name + :param array $column_name: The column name to drop + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Drops a column from a table. Usage: See `Dropping a Column From a Table`_. + + .. method:: drop_database($db_name) + + :param string $db_name: Name of the database to drop + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Drops a database. Usage: See `Creating and Dropping Databases`_. + + .. method:: drop_table($table_name[, $if_exists = FALSE]) + + :param string $table: Name of the table to drop + :param string $if_exists: Set to TRUE to add an 'IF EXISTS' clause + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Drops a table. Usage: See `Dropping a table`_. + + .. method:: modify_column($table, $field) + + :param string $table: Table name + :param array $field: Column definition(s) + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Modifies a table column. Usage: See `Modifying a Column in a Table`_. + + .. method:: rename_table($table_name, $new_table_name) + + :param string $table: Current of the table + :param string $new_table_name: New name of the table + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Renames a table. Usage: See `Renaming a table`_.
\ No newline at end of file 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..4612daf9d 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 @@ -17,8 +17,7 @@ patterns. The database functions offer clear, simple syntax. Query Helper Functions <helpers> Query Builder Class <query_builder> Transactions <transactions> - Table MetaData <table_data> - Field MetaData <fields> + Getting MetaData <metadata> Custom Function Calls <call_function> Query Caching <caching> Database Manipulation with Database Forge <forge> diff --git a/user_guide_src/source/database/fields.rst b/user_guide_src/source/database/metadata.rst index b706ace7d..b8be809b6 100644 --- a/user_guide_src/source/database/fields.rst +++ b/user_guide_src/source/database/metadata.rst @@ -1,9 +1,53 @@ -########## -Field Data -########## +################# +Database Metadata +################# -$this->db->list_fields() -========================= +************** +Table MetaData +************** + +These functions let you fetch table information. + +List the Tables in Your Database +================================ + +**$this->db->list_tables();** + +Returns an array containing the names of all the tables in the database +you are currently connected to. Example:: + + $tables = $this->db->list_tables(); + + foreach ($tables as $table) + { + echo $table; + } + + +Determine If a Table Exists +=========================== + +**$this->db->table_exists();** + +Sometimes it's helpful to know whether a particular table exists before +running an operation on it. Returns a boolean TRUE/FALSE. Usage example:: + + if ($this->db->table_exists('table_name')) + { + // some code... + } + +.. note:: Replace *table_name* with the name of the table you are looking for. + + +************** +Field MetaData +************** + +List the Fields in a Table +========================== + +**$this->db->list_fields()** Returns an array containing the field names. This query can be called two ways: @@ -28,8 +72,11 @@ calling the function from your query result object:: echo $field; } -$this->db->field_exists() -========================== + +Determine If a Field is Present in a Table +========================================== + +**$this->db->field_exists()** Sometimes it's helpful to know whether a particular field exists before performing an action. Returns a boolean TRUE/FALSE. Usage example:: @@ -43,8 +90,11 @@ performing an action. Returns a boolean TRUE/FALSE. Usage example:: for, and replace *table_name* with the name of the table you are looking for. -$this->db->field_data() -======================== + +Retrieve Field Metadata +======================= + +**$this->db->field_data()** Returns an array of objects containing field information. @@ -77,4 +127,4 @@ database: - name - column name - max_length - maximum length of the column - primary_key - 1 if the column is a primary key -- type - the type of the column
\ No newline at end of file +- type - the type of the column 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/table_data.rst b/user_guide_src/source/database/table_data.rst deleted file mode 100644 index 744a05154..000000000 --- a/user_guide_src/source/database/table_data.rst +++ /dev/null @@ -1,31 +0,0 @@ -########## -Table Data -########## - -These functions let you fetch table information. - -$this->db->list_tables(); -========================== - -Returns an array containing the names of all the tables in the database -you are currently connected to. Example:: - - $tables = $this->db->list_tables(); - - foreach ($tables as $table) - { - echo $table; - } - -$this->db->table_exists(); -=========================== - -Sometimes it's helpful to know whether a particular table exists before -running an operation on it. Returns a boolean TRUE/FALSE. Usage example:: - - if ($this->db->table_exists('table_name')) - { - // some code... - } - -.. note:: Replace *table_name* with the name of the table you are looking for. diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst index bd40cdadd..0d8137dd7 100644 --- a/user_guide_src/source/database/utilities.rst +++ b/user_guide_src/source/database/utilities.rst @@ -5,15 +5,13 @@ Database Utility Class The Database Utility Class contains methods that help you manage your database. -.. contents:: Table of Contents - - -****************** -Function Reference -****************** +.. contents:: + :local: + :depth: 2 +****************************** 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 +37,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 +53,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 +68,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 +82,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 +95,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 +114,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 +142,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 +166,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 +189,7 @@ backup data can be compressed in either Zip or Gzip format. have root privileges. Usage Example -------------- +============= :: @@ -201,7 +208,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 +226,7 @@ parameter of the ``backup()`` method. Example:: $this->dbutil->backup($prefs); Description of Backup Preferences ---------------------------------- +================================= ======================= ======================= ======================= ======================================================================== Preference Default Value Options Description @@ -234,4 +241,76 @@ 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:: CI_DB_utility + + .. method:: backup([$params = array()]) + + :param array $params: An associative array of options + :returns: void + :rtype: void + + Perform a database backup, per user preferences. + + .. method:: database_exists($database_name) + + :param string $database_name: Database name + :returns: TRUE if the database exists, FALSE otherwise + :rtype: bool + + Check for the existence of a database. + + .. method:: list_databases() + + :returns: Array of database names found + :rtype: array + + Retrieve a list of all the database names. + + .. method:: optimize_database() + + :returns: Array of optimization messages or FALSE on failure + :rtype: array + + Optimizes the database. + + .. method:: optimize_table($table_name) + + :param string $table_name: Name of the table to optimize + :returns: Array of optimization messages or FALSE on failure + :rtype: array + + Optimizes a database table. + + .. method:: repair_table($table_name) + + :param string $table_name: Name of the table to repair + :returns: Array of repair messages or FALSE on failure + :rtype: array + + Repairs a database table. + + .. method:: csv_from_results($query[, $delim = ','[, $newline = "\n"[, $enclosure = '"']]]) + + :param object $query: A database result object + :param string $delim: The CSV field delimiter to use + :param string $newline: The newline character to use + :param string $enclosure: The enclosure delimiter to use + :returns: The generated CSV file as a string + :rtype: string + + Translates a database result object into a CSV document. + + .. method:: xml_from_results($query[, $params = array()]) + + :param object $query: A database result object + :param array $params: An associative array of preferences + :returns: The generated XML document as a string + :rtype: string + + Translates a database result object into an XML document.
\ No newline at end of file diff --git a/user_guide_src/source/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/helpers/captcha_helper.rst b/user_guide_src/source/helpers/captcha_helper.rst index 1b74d08ad..3cf51330b 100644 --- a/user_guide_src/source/helpers/captcha_helper.rst +++ b/user_guide_src/source/helpers/captcha_helper.rst @@ -33,6 +33,7 @@ Once loaded you can generate a CAPTCHA like this:: 'img_height' => 30, 'expiration' => 7200, 'word_length' => 8, + 'font_size' => 16, 'pool' => '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ', // White background and border, black text and red grid @@ -59,6 +60,7 @@ Once loaded you can generate a CAPTCHA like this:: in the captcha folder before it will be deleted. The default is two hours. - **word_length** defaults to 8, **pool** defaults to '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ' +- **font_size** defaults to 16, the native GD font has a size limit. Specify a "true type" font for bigger sizes. - If any of the **colors** values is missing, it will be replaced by the default. Adding a Database diff --git a/user_guide_src/source/helpers/email_helper.rst b/user_guide_src/source/helpers/email_helper.rst index b665ce548..3b771a0b6 100644 --- a/user_guide_src/source/helpers/email_helper.rst +++ b/user_guide_src/source/helpers/email_helper.rst @@ -6,7 +6,8 @@ The Email Helper provides some assistive functions for working with Email. For a more robust email solution, see CodeIgniter's :doc:`Email Class <../libraries/email>`. -.. important:: The Email helper is **deprecated**. +.. important:: The Email helper is DEPRECATED and is currently + only kept for backwards compatibility. .. contents:: :local: diff --git a/user_guide_src/source/helpers/smiley_helper.rst b/user_guide_src/source/helpers/smiley_helper.rst index e7a5724a8..5de1d83bb 100644 --- a/user_guide_src/source/helpers/smiley_helper.rst +++ b/user_guide_src/source/helpers/smiley_helper.rst @@ -5,6 +5,9 @@ Smiley Helper The Smiley Helper file contains functions that let you manage smileys (emoticons). +.. important:: The Smiley helper is DEPRECATED and should not be used. + It is currently only kept for backwards compatibility. + .. contents:: :local: 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/installation/upgrade_300.rst b/user_guide_src/source/installation/upgrade_300.rst index 81340e6ad..ef85106b7 100644 --- a/user_guide_src/source/installation/upgrade_300.rst +++ b/user_guide_src/source/installation/upgrade_300.rst @@ -331,11 +331,14 @@ Usage of the ``EXT`` constant has been deprecated since dropping support for PHP longer a need to maintain different filename extensions and in this new CodeIgniter version, the ``EXT`` constant has been removed. Use just '.php' instead. -Smiley helper js_insert_smiley() -================================ +Smiley helper +============= -:doc:`Smiley Helper <../helpers/smiley_helper>` function ``js_insert_smiley()`` has been deprecated -since CodeIgniter 1.7.2 and is now removed. You'll need to switch to ``smiley_js()`` instead. +The :doc:`Smiley Helper <../helpers/smiley_helper>` is a legacy feature from EllisLab's +ExpressionEngine product. However, it is too specific for a general purpose framework like +CodeIgniter and as such it is now deprecated. + +Also, the previously deprecated ``js_insert_smiley()`` (since version 1.7.2) is now removed. The Encrypt library =================== @@ -355,6 +358,16 @@ implemented cryptographic functions. .. important:: You are strongly encouraged to switch to the new :doc:`Encryption Library <../libraries/encryption>` as soon as possible! +The Cart library +================ + +The :doc:`Cart Library <../libraries/cart>`, similarly to the :doc:`Smiley Helper +<../helpers/smiley_helper>` is too specific for CodeIgniter. It is now deprecated +and scheduled for removal in CodeIgniter 3.1+. + +.. note:: The library is still available, but you're strongly encouraged to remove its usage sooner + rather than later. + Database drivers 'mysql', 'sqlite', 'mssql', 'pdo/dblib' ======================================================== diff --git a/user_guide_src/source/libraries/cart.rst b/user_guide_src/source/libraries/cart.rst index bedea4dbf..a023ccb36 100644 --- a/user_guide_src/source/libraries/cart.rst +++ b/user_guide_src/source/libraries/cart.rst @@ -7,6 +7,9 @@ while a user is browsing your site. These items can be retrieved and displayed in a standard "shopping cart" format, allowing the user to update the quantity or remove items from the cart. +.. important:: The Card library is DEPRECATED and should not be used. + It is currently only kept for backwards compatibility. + Please note that the Cart Class ONLY provides the core "cart" functionality. It does not provide shipping, credit card authorization, or other processing components. diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst index f29ebf4ed..2d0ee23a3 100644 --- a/user_guide_src/source/libraries/encryption.rst +++ b/user_guide_src/source/libraries/encryption.rst @@ -533,6 +533,7 @@ Class Reference :param int $length: Optional output length :param string $info: Optional context/application-specific info :returns: A pseudo-random key or FALSE on failure + :rtype: string Derives a key from another, presumably weaker key. 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/javascript.rst b/user_guide_src/source/libraries/javascript.rst index 9d0237e57..7f83b2f70 100644 --- a/user_guide_src/source/libraries/javascript.rst +++ b/user_guide_src/source/libraries/javascript.rst @@ -2,16 +2,16 @@ Javascript Class ################ -.. note:: This library is DEPRECATED and should not be used. It has always - been with an 'experimental' status and is now no longer supported. - Currently only kept for backwards compatibility. - CodeIgniter provides a library to help you with certain common functions that you may want to use with Javascript. Please note that CodeIgniter does not require the jQuery library to run, and that any scripting library will work equally well. The jQuery library is simply presented as a convenience if you choose to use it. +.. important:: This library is DEPRECATED and should not be used. It has always + been with an 'experimental' status and is now no longer supported. + Currently only kept for backwards compatibility. + .. contents:: :local: diff --git a/user_guide_src/source/libraries/language.rst b/user_guide_src/source/libraries/language.rst index 6949c11c9..e833d9757 100644 --- a/user_guide_src/source/libraries/language.rst +++ b/user_guide_src/source/libraries/language.rst @@ -5,16 +5,25 @@ 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 -one in **system/language/** first and will then look for an override in -your **application/language/** directory. +In your CodeIgniter **system** folder, you will find a **language** sub-directory +containing a set of language files for the **english** idiom. +The files in this directory (**system/language/english/**) define the regular messages, +error messages, and other generally output terms or expressions, for the different parts +of the CodeIgniter 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/** directory, with separate sub-directories 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. .. note:: Each language should be stored in its own folder. For example, the English files are located at: system/language/english @@ -26,6 +35,71 @@ 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('message_key'); + +******************** +Internationalization +******************** + +The Language class in CodeIgniter is meant to provide an easy and lightweight +way to support multiplelanguages 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'] = '>'; -============================== +**$config['next_link'] = '>';** 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'] = '<'; -============================== +**$config['prev_link'] = '<';** 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..d66684d9b 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,11 +45,15 @@ representations that allow you to eliminate PHP from your templates <div class="custom-index container"></div> +******************************* +Using the Template Parser Class +******************************* + Initializing the Class ====================== Like most other classes in CodeIgniter, the Parser class is initialized -in your controller using the $this->load->library function:: +in your controller using the ``$this->load->library()`` method:: $this->load->library('parser'); @@ -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,35 +122,156 @@ 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); If your "pair" data is coming from a database result, which is already a -multi-dimensional array, you can simply use the database result_array() -function:: +multi-dimensional array, you can simply use the database ``result_array()`` +method:: $query = $this->db->query("SELECT * FROM blog"); $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:: + + <ul> + <li><a href="/first">First Link</a></li> + <li><a href="/second">Second Link</a></li> + </ul> + +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:: + + <ul> + <li><a href="/first">First Link</a></li> + <li><a href="/second">Second Link</a></li> + </ul> + *************** Class Reference *************** @@ -167,8 +296,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 +305,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 diff --git a/user_guide_src/source/libraries/zip.rst b/user_guide_src/source/libraries/zip.rst index 4ca14086a..0f255755e 100644 --- a/user_guide_src/source/libraries/zip.rst +++ b/user_guide_src/source/libraries/zip.rst @@ -25,7 +25,9 @@ your controller using the $this->load->library function:: $this->load->library('zip'); -Once loaded, the Zip library object will be available using: $this->zip +Once loaded, the Zip library object will be available using: + + $this->zip Usage Example ============= @@ -52,6 +54,14 @@ Class Reference .. class:: CI_Zip + .. attribute:: $compression_level = 2 + + The compression level to use. + + It can range from 0 to 9, with 9 being the highest and 0 effectively disabling compression:: + + $this->zip->compression_level = 0; + .. method:: add_data($filepath[, $data = NULL]) :param mixed $filepath: A single file path or an array of file => data pairs @@ -60,7 +70,8 @@ Class Reference Adds data to the Zip archive. Can work both in single and multiple files mode. - When adding a single file, the first parameter must contain the name you would like given to the file and the second must contain the file contents:: + When adding a single file, the first parameter must contain the name you would + like given to the file and the second must contain the file contents:: $name = 'mydata1.txt'; $data = 'A Data String!'; @@ -70,7 +81,8 @@ Class Reference $data = 'Another Data String!'; $this->zip->add_data($name, $data); - When adding multiple files, the first parameter must contain *file => contents* pairs and the second parameter is ignored:: + When adding multiple files, the first parameter must contain *file => contents* pairs + and the second parameter is ignored:: $data = array( 'mydata1.txt' => 'A Data String!', @@ -79,7 +91,8 @@ Class Reference $this->zip->add_data($data); - If you would like your compressed data organized into sub-directories, simply include the path as part of the filename(s):: + If you would like your compressed data organized into sub-directories, simply include + the path as part of the filename(s):: $name = 'personal/my_bio.txt'; $data = 'I was born in an elevator...'; @@ -93,8 +106,9 @@ Class Reference :param mixed $directory: Directory name string or an array of multiple directories :rtype: void - Permits you to add a directory. Usually this method is unnecessary since you can place your data into directories when using - ``$this->zip->add_data()``, but if you would like to create an empty directory you can do so:: + Permits you to add a directory. Usually this method is unnecessary since you can place + your data into directories when using ``$this->zip->add_data()``, but if you would like + to create an empty directory you can do so:: $this->zip->add_dir('myfolder'); // Creates a directory called "myfolder" @@ -156,15 +170,16 @@ Class Reference // Download the file to your desktop. Name it "my_backup.zip" $this->zip->download('my_backup.zip'); - By default the Zip archive will place all directories listed in the first parameter inside the zip. - If you want the tree preceding the target directory to be ignored you can pass FALSE (boolean) in the second parameter. Example:: + By default the Zip archive will place all directories listed in the first parameter + inside the zip. If you want the tree preceding the target directory to be ignored, + you can pass FALSE (boolean) in the second parameter. Example:: $path = '/path/to/your/directory/'; $this->zip->read_dir($path, FALSE); - This will create a ZIP with a directory named "directory" inside, then all sub-directories stored correctly inside that, but will not include the - */path/to/your* part of the path. + This will create a ZIP with a directory named "directory" inside, then all sub-directories + stored correctly inside that, but will not include the */path/to/your* part of the path. .. method:: archive($filepath) @@ -172,8 +187,9 @@ Class Reference :returns: TRUE on success, FALSE on failure :rtype: bool - Writes the Zip-encoded file to a directory on your server. Submit a valid server path ending in the file name. - Make sure the directory is writable (755 is usually OK). Example:: + Writes the Zip-encoded file to a directory on your server. Submit a valid server path + ending in the file name. Make sure the directory is writable (755 is usually OK). + Example:: $this->zip->archive('/path/to/folder/myarchive.zip'); // Creates a file named myarchive.zip @@ -182,7 +198,8 @@ Class Reference :param string $filename: Archive file name :rtype: void - Causes the Zip file to be downloaded from your server. You must pass the name you would like the zip file called. Example:: + Causes the Zip file to be downloaded from your server. + You must pass the name you would like the zip file called. Example:: $this->zip->download('latest_stuff.zip'); // File will be named "latest_stuff.zip" @@ -195,7 +212,8 @@ Class Reference :returns: Zip file content :rtype: string - Returns the Zip-compressed file data. Generally you will not need this method unless you want to do something unique with the data. Example:: + Returns the Zip-compressed file data. Generally you will not need this method unless you + want to do something unique with the data. Example:: $name = 'my_bio.txt'; $data = 'I was born in an elevator...'; @@ -208,8 +226,9 @@ Class Reference :rtype: void - The Zip class caches your zip data so that it doesn't need to recompile the Zip archive for each method you use above. - If, however, you need to create multiple Zip archives, each with different data, you can clear the cache between calls. Example:: + The Zip class caches your zip data so that it doesn't need to recompile the Zip archive + for each method you use above. If, however, you need to create multiple Zip archives, + each with different data, you can clear the cache between calls. Example:: $name = 'my_bio.txt'; $data = 'I was born in an elevator...'; |