From 123bb20c52e0e9d6a622e14bac33e05b10ffc013 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Fri, 19 Jul 2013 16:37:51 -0700 Subject: Updating user guide :php:func: refs to :func: --- user_guide_src/source/libraries/language.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/language.rst b/user_guide_src/source/libraries/language.rst index d288cd65e..e772e8e27 100644 --- a/user_guide_src/source/libraries/language.rst +++ b/user_guide_src/source/libraries/language.rst @@ -79,7 +79,7 @@ Using language lines as form labels ----------------------------------- This feature has been deprecated from the language library and moved to -the :php:func:`lang()` function of the :doc:`Language Helper +the :func:`lang()` function of the :doc:`Language Helper <../helpers/language_helper>`. Auto-loading Languages -- cgit v1.2.3-24-g4f1b From da671680202c030a3347ab77f4fe0ead23c8886a Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Sun, 21 Jul 2013 13:34:18 -0700 Subject: Updating Benchmark lib docs --- user_guide_src/source/libraries/benchmark.rst | 51 +++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 3 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/benchmark.rst b/user_guide_src/source/libraries/benchmark.rst index 5b86142dd..7a0313f43 100644 --- a/user_guide_src/source/libraries/benchmark.rst +++ b/user_guide_src/source/libraries/benchmark.rst @@ -13,10 +13,16 @@ invoked, and ended by the output class right before sending the final view to the browser, enabling a very accurate timing of the entire system execution to be shown. -.. contents:: Table of Contents +.. contents:: + :local: +.. raw:: html + +
+ +************************* Using the Benchmark Class -========================= +************************* The Benchmark class can be used within your :doc:`controllers `, @@ -68,7 +74,7 @@ _end. Each pair of points must otherwise be named identically. Example:: // Some code happens here... - $this->benchmark->mark('my_mark_end'); + $this->benchmark->mark('my_mark_end'); $this->benchmark->mark('another_mark_start'); @@ -120,3 +126,42 @@ this pseudo-variable, if you prefer not to use the pure PHP:: {memory_usage} + +*************** +Class Reference +*************** + +.. class:: CI_Benchmark + + .. method:: mark($name) + + :param string $name: the name you wish to assign to your marker + :returns: void + + Sets a benchmark marker. + + + .. method:: elapsed_time([$point1 = ''[, $point2 = ''[, $decimals = 4]]]) + + :param string $point1: a particular marked point + :param string $point2: a particular marked point + :param int $decimals: number of decimal places for precision + :returns: string + + Calculates and returns the time difference between two marked points. + + If the first parameter is empty this function instead returns the + ``{elapsed_time}`` pseudo-variable. This permits the full system + execution time to be shown in a template. The output class will + swap the real value for this variable. + + + .. method:: memory_usage() + + :returns: string + + Simply returns the ``{memory_usage}`` marker. + + This permits it to be put it anywhere in a template without the memory + being calculated until the end. The :doc:`Output Class ` will + swap the real value for this variable. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From ca51e1a5695bfdf76d8db599ee6c7ba16c328bbc Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Sun, 21 Jul 2013 13:35:02 -0700 Subject: removing php: directive prefix from docs source as it is not necessary --- user_guide_src/source/libraries/caching.rst | 56 +++++++++++----------- .../source/libraries/form_validation.rst | 56 +++++++++++----------- 2 files changed, 56 insertions(+), 56 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/caching.rst b/user_guide_src/source/libraries/caching.rst index 8d7b4c440..ca4ad4935 100644 --- a/user_guide_src/source/libraries/caching.rst +++ b/user_guide_src/source/libraries/caching.rst @@ -20,16 +20,16 @@ available in the hosting environment. :: $this->load->driver('cache', array('adapter' => 'apc', 'backup' => 'file')); - + if ( ! $foo = $this->cache->get('foo')) { echo 'Saving to the cache!
'; $foo = 'foobarbaz!'; - + // Save into the cache for 5 minutes $this->cache->save('foo', $foo, 300); } - + echo $foo; You can also prefix cache item names via the **key_prefix** setting, which is useful @@ -47,24 +47,24 @@ to avoid collisions when you're running multiple applications on the same enviro Function Reference ****************** -.. php:class:: CI_Cache +.. class:: CI_Cache is_supported() ============== - .. php:method:: is_supported ( $driver ) + .. method:: is_supported ( $driver ) This function is automatically called when accessing drivers via $this->cache->get(). However, if the individual drivers are used, make sure to call this function to ensure the driver is supported in the hosting environment. - + :param string $driver: the name of the caching driver :returns: TRUE if supported, FALSE if not :rtype: Boolean - + :: - + if ($this->cache->apc->is_supported() { if ($data = $this->cache->apc->get('my_cache')) @@ -77,15 +77,15 @@ is_supported() get() ===== - .. php:method:: get ( $id ) - + .. method:: get ( $id ) + This function will attempt to fetch an item from the cache store. If the item does not exist, the function will return FALSE. :param string $id: name of cached item :returns: The item if it exists, FALSE if it does not :rtype: Mixed - + :: $foo = $this->cache->get('my_cached_item'); @@ -94,8 +94,8 @@ get() save() ====== - .. php:method:: save ( $id , $data [, $ttl]) - + .. method:: save ( $id , $data [, $ttl]) + This function will save an item to the cache store. If saving fails, the function will return FALSE. @@ -108,19 +108,19 @@ save() :: $this->cache->save('cache_item_id', 'data_to_cache'); - + delete() ======== - .. php:method:: delete ( $id ) - + .. method:: delete ( $id ) + This function will delete a specific item from the cache store. If item deletion fails, the function will return FALSE. :param string $id: name of cached item :returns: TRUE if deleted, FALSE if the deletion fails :rtype: Boolean - + :: $this->cache->delete('cache_item_id'); @@ -128,14 +128,14 @@ delete() clean() ======= - .. php:method:: clean ( ) - + .. method:: clean ( ) + This function will 'clean' the entire cache. If the deletion of the cache files fails, the function will return FALSE. :returns: TRUE if deleted, FALSE if the deletion fails :rtype: Boolean - + :: $this->cache->clean(); @@ -143,33 +143,33 @@ clean() cache_info() ============ - .. php:method:: cache_info ( ) + .. method:: cache_info ( ) This function will return information on the entire cache. :returns: information on the entire cache :rtype: Mixed - + :: var_dump($this->cache->cache_info()); - + .. note:: The information returned and the structure of the data is dependent on which adapter is being used. - + get_metadata() ============== - .. php:method:: get_metadata ( $id ) - + .. method:: get_metadata ( $id ) + This function will return detailed information on a specific item in the cache. - + :param string $id: name of cached item :returns: metadadta for the cached item :rtype: Mixed - + :: var_dump($this->cache->get_metadata('my_cached_item')); diff --git a/user_guide_src/source/libraries/form_validation.rst b/user_guide_src/source/libraries/form_validation.rst index 8b35fdc75..5dffb1cd1 100644 --- a/user_guide_src/source/libraries/form_validation.rst +++ b/user_guide_src/source/libraries/form_validation.rst @@ -477,8 +477,8 @@ following method:: Where rule corresponds to the name of a particular rule, and Error Message is the text you would like displayed. -If you'd like to include a field's "human" name, or the optional -parameter some rules allow for (such as max_length), you can add the +If you'd like to include a field's "human" name, or the optional +parameter some rules allow for (such as max_length), you can add the **{field}** and **{param}** tags to your message, respectively:: $this->form_validation->set_message('min_length', '{field} must have at least {param} characters.'); @@ -860,14 +860,14 @@ use: ========================= ========== ============================================================================================= ======================= Rule Parameter Description Example ========================= ========== ============================================================================================= ======================= -**required** No Returns FALSE if the form element is empty. -**matches** Yes Returns FALSE if the form element does not match the one in the parameter. matches[form_item] -**differs** Yes Returns FALSE if the form element does not differ from the one in the parameter. differs[form_item] -**is_unique** Yes Returns FALSE if the form element is not unique to the table and field name in the is_unique[table.field] - parameter. Note: This rule requires :doc:`Query Builder <../database/query_builder>` to be +**required** No Returns FALSE if the form element is empty. +**matches** Yes Returns FALSE if the form element does not match the one in the parameter. matches[form_item] +**differs** Yes Returns FALSE if the form element does not differ from the one in the parameter. differs[form_item] +**is_unique** Yes Returns FALSE if the form element is not unique to the table and field name in the is_unique[table.field] + parameter. Note: This rule requires :doc:`Query Builder <../database/query_builder>` to be enabled in order to work. -**max_length** Yes Returns FALSE if the form element is longer then the parameter value. max_length[12] -**exact_length** Yes Returns FALSE if the form element is not exactly the parameter value. exact_length[8] +**max_length** Yes Returns FALSE if the form element is longer then the parameter value. max_length[12] +**exact_length** Yes Returns FALSE if the form element is not exactly the parameter value. exact_length[8] **greater_than** Yes Returns FALSE if the form element is less than or equal to the parameter value or not greater_than[8] numeric. **greater_than_equal_to** Yes Returns FALSE if the form element is less than the parameter value, greater_than_equal_to[8] @@ -876,15 +876,15 @@ Rule Parameter Description not numeric. **less_than_equal_to** Yes Returns FALSE if the form element is greater than the parameter value, less_than_equal_to[8] or not numeric. -**alpha** No Returns FALSE if the form element contains anything other than alphabetical characters. +**alpha** No Returns FALSE if the form element contains anything other than alphabetical characters. **alpha_numeric** No Returns FALSE if the form element contains anything other than alpha-numeric characters. **alpha_numeric_spaces** No Returns FALSE if the form element contains anything other than alpha-numeric characters - or spaces. Should be used after trim to avoid spaces at the beginning or end. -**alpha_dash** No Returns FALSE if the form element contains anything other than alpha-numeric characters, - underscores or dashes. -**numeric** No Returns FALSE if the form element contains anything other than numeric characters. -**integer** No Returns FALSE if the form element contains anything other than an integer. -**decimal** No Returns FALSE if the form element contains anything other than a decimal number. + or spaces. Should be used after trim to avoid spaces at the beginning or end. +**alpha_dash** No Returns FALSE if the form element contains anything other than alpha-numeric characters, + underscores or dashes. +**numeric** No Returns FALSE if the form element contains anything other than numeric characters. +**integer** No Returns FALSE if the form element contains anything other than an integer. +**decimal** No Returns FALSE if the form element contains anything other than a decimal number. **is_natural** No Returns FALSE if the form element contains anything other than a natural number: 0, 1, 2, 3, etc. **is_natural_no_zero** No Returns FALSE if the form element contains anything other than a natural @@ -933,14 +933,14 @@ Name Parameter Description Class Reference *************** -.. php:class:: Form_validation +.. class:: Form_validation The following methods are intended for use in your controller. $this->form_validation->set_rules() =================================== - .. php:method:: set_rules ($field, $label = '', $rules = '') + .. method:: set_rules ($field, $label = '', $rules = '') :param string $field: The field name :param string $label: The field label @@ -955,8 +955,8 @@ $this->form_validation->set_rules() $this->form_validation->run() ============================= - - .. php:method:: run ($group = '') + + .. method:: run ($group = '') :param string $group: The name of the validation group to run :rtype: Boolean @@ -967,8 +967,8 @@ $this->form_validation->run() $this->form_validation->set_message() ===================================== - - .. php:method:: set_message ($lang, $val = '') + + .. method:: set_message ($lang, $val = '') :param string $lang: The rule the message is for :param string $val: The message @@ -978,8 +978,8 @@ $this->form_validation->set_message() $this->form_validation->set_data() ================================== - - .. php:method:: set_data ($data = '') + + .. method:: set_data ($data = '') :param array $data: The data to validate @@ -989,15 +989,15 @@ $this->form_validation->set_data() $this->form_validation->reset_validation() ========================================== - .. php:method:: reset_validation () + .. method:: reset_validation () Permits you to reset the validation when you validate more than one array. This method should be called before validating each new array. $this->form_validation->error_array() ===================================== - - .. php:method:: error_array () + + .. method:: error_array () :rtype: Array @@ -1031,7 +1031,7 @@ Shows all error messages as a string: Example:: -The error delimiters can be optionally specified. See the +The error delimiters can be optionally specified. See the :ref:`changing-delimiters` section above. set_value() -- cgit v1.2.3-24-g4f1b From 9fe093e1cc359d9f5140cd4f32fd98465e1a207f Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Sun, 21 Jul 2013 13:47:08 -0700 Subject: Update Cache driver docs --- user_guide_src/source/libraries/caching.rst | 75 ++++++++++++----------------- 1 file changed, 31 insertions(+), 44 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/caching.rst b/user_guide_src/source/libraries/caching.rst index ca4ad4935..0e7de57c9 100644 --- a/user_guide_src/source/libraries/caching.rst +++ b/user_guide_src/source/libraries/caching.rst @@ -7,7 +7,12 @@ fast and dynamic caching. All but file-based caching require specific server requirements, and a Fatal Exception will be thrown if server requirements are not met. -.. contents:: Table of Contents +.. contents:: + :local: + +.. raw:: html + +
************* Example Usage @@ -43,26 +48,23 @@ to avoid collisions when you're running multiple applications on the same enviro $this->cache->get('foo'); // Will get the cache entry named 'my_foo' -****************** -Function Reference -****************** +*************** +Class Reference +*************** .. class:: CI_Cache -is_supported() -============== - .. method:: is_supported ( $driver ) + :param string $driver: the name of the caching driver + :returns: TRUE if supported, FALSE if not + :rtype: Boolean + This function is automatically called when accessing drivers via $this->cache->get(). However, if the individual drivers are used, make sure to call this function to ensure the driver is supported in the hosting environment. - :param string $driver: the name of the caching driver - :returns: TRUE if supported, FALSE if not - :rtype: Boolean - :: if ($this->cache->apc->is_supported() @@ -74,30 +76,21 @@ is_supported() } -get() -===== - .. method:: get ( $id ) - This function will attempt to fetch an item from the cache store. If the - item does not exist, the function will return FALSE. - :param string $id: name of cached item :returns: The item if it exists, FALSE if it does not :rtype: Mixed + This function will attempt to fetch an item from the cache store. If the + item does not exist, the function will return FALSE. + :: $foo = $this->cache->get('my_cached_item'); -save() -====== - - .. method:: save ( $id , $data [, $ttl]) - - This function will save an item to the cache store. If saving fails, the - function will return FALSE. + .. method:: save ( $id , $data [, $ttl = 60]) :param string $id: name of the cached item :param mixed $data: the data to save @@ -105,51 +98,48 @@ save() :returns: TRUE on success, FALSE on failure :rtype: Boolean + This function will save an item to the cache store. If saving fails, the + function will return FALSE. + :: $this->cache->save('cache_item_id', 'data_to_cache'); -delete() -======== .. method:: delete ( $id ) - This function will delete a specific item from the cache store. If item - deletion fails, the function will return FALSE. - :param string $id: name of cached item :returns: TRUE if deleted, FALSE if the deletion fails :rtype: Boolean + This function will delete a specific item from the cache store. If item + deletion fails, the function will return FALSE. + :: $this->cache->delete('cache_item_id'); -clean() -======= .. method:: clean ( ) - This function will 'clean' the entire cache. If the deletion of the - cache files fails, the function will return FALSE. - :returns: TRUE if deleted, FALSE if the deletion fails :rtype: Boolean + This function will 'clean' the entire cache. If the deletion of the + cache files fails, the function will return FALSE. + :: $this->cache->clean(); -cache_info() -============ .. method:: cache_info ( ) - This function will return information on the entire cache. - :returns: information on the entire cache :rtype: Mixed + This function will return information on the entire cache. + :: var_dump($this->cache->cache_info()); @@ -158,18 +148,15 @@ cache_info() on which adapter is being used. -get_metadata() -============== - .. method:: get_metadata ( $id ) - This function will return detailed information on a specific item in the - cache. - :param string $id: name of cached item :returns: metadadta for the cached item :rtype: Mixed + This function will return detailed information on a specific item in the + cache. + :: var_dump($this->cache->get_metadata('my_cached_item')); -- cgit v1.2.3-24-g4f1b From 9046f20a2b34c6b27a86ac34da4e20d836f5e091 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Sun, 21 Jul 2013 13:54:19 -0700 Subject: function to method semantic change in Cache docs --- user_guide_src/source/libraries/caching.rst | 30 ++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/caching.rst b/user_guide_src/source/libraries/caching.rst index 0e7de57c9..55fdabca3 100644 --- a/user_guide_src/source/libraries/caching.rst +++ b/user_guide_src/source/libraries/caching.rst @@ -60,9 +60,9 @@ Class Reference :returns: TRUE if supported, FALSE if not :rtype: Boolean - This function is automatically called when accessing drivers via + This method is automatically called when accessing drivers via $this->cache->get(). However, if the individual drivers are used, make - sure to call this function to ensure the driver is supported in the + sure to call this method to ensure the driver is supported in the hosting environment. :: @@ -82,8 +82,8 @@ Class Reference :returns: The item if it exists, FALSE if it does not :rtype: Mixed - This function will attempt to fetch an item from the cache store. If the - item does not exist, the function will return FALSE. + This method will attempt to fetch an item from the cache store. If the + item does not exist, the method will return FALSE. :: @@ -98,8 +98,8 @@ Class Reference :returns: TRUE on success, FALSE on failure :rtype: Boolean - This function will save an item to the cache store. If saving fails, the - function will return FALSE. + This method will save an item to the cache store. If saving fails, the + method will return FALSE. :: @@ -112,8 +112,8 @@ Class Reference :returns: TRUE if deleted, FALSE if the deletion fails :rtype: Boolean - This function will delete a specific item from the cache store. If item - deletion fails, the function will return FALSE. + This method will delete a specific item from the cache store. If item + deletion fails, the method will return FALSE. :: @@ -125,8 +125,8 @@ Class Reference :returns: TRUE if deleted, FALSE if the deletion fails :rtype: Boolean - This function will 'clean' the entire cache. If the deletion of the - cache files fails, the function will return FALSE. + This method will 'clean' the entire cache. If the deletion of the + cache files fails, the method will return FALSE. :: @@ -138,7 +138,7 @@ Class Reference :returns: information on the entire cache :rtype: Mixed - This function will return information on the entire cache. + This method will return information on the entire cache. :: @@ -154,7 +154,7 @@ Class Reference :returns: metadadta for the cached item :rtype: Mixed - This function will return detailed information on a specific item in the + This method will return detailed information on a specific item in the cache. :: @@ -171,7 +171,7 @@ Drivers Alternative PHP Cache (APC) Caching =================================== -All of the functions listed above can be accessed without passing a +All of the methods listed above can be accessed without passing a specific adapter to the driver loader as follows:: $this->load->driver('cache'); @@ -188,7 +188,7 @@ allows for pieces of view files to be cached. Use this with care, and make sure to benchmark your application, as a point can come where disk I/O will negate positive gains by caching. -All of the functions listed above can be accessed without passing a +All of the methods listed above can be accessed without passing a specific adapter to the driver loader as follows:: $this->load->driver('cache'); @@ -214,7 +214,7 @@ WinCache Caching Under Windows, you can also utilize the WinCache driver. -All of the functions listed above can be accessed without passing a +All of the methods listed above can be accessed without passing a specific adapter to the driver loader as follows:: $this->load->driver('cache'); -- cgit v1.2.3-24-g4f1b From a756125436884dd622fdeff67084f3a62fc71b98 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Sun, 21 Jul 2013 14:21:41 -0700 Subject: Updating Calendar lib docs --- user_guide_src/source/libraries/calendar.rst | 108 ++++++++++++++++++++++++++- 1 file changed, 105 insertions(+), 3 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/calendar.rst b/user_guide_src/source/libraries/calendar.rst index 3964db25e..d9a336d08 100644 --- a/user_guide_src/source/libraries/calendar.rst +++ b/user_guide_src/source/libraries/calendar.rst @@ -7,6 +7,17 @@ calendars can be formatted through the use of a calendar template, allowing 100% control over every aspect of its design. In addition, you can pass data to your calendar cells. +.. contents:: + :local: + +.. raw:: html + +
+ +*************************** +Using the Calendaring Class +*************************** + Initializing the Class ====================== @@ -87,7 +98,7 @@ month heading, and the "short" day names. More information regarding preferences below. ====================== =========== =============================================== =================================================================== -Preference Default Options Description +Preference Default Options Description ====================== =========== =============================================== =================================================================== **template** None None A string containing your calendar template. See the template section below. @@ -95,7 +106,7 @@ Preference Default Options Description **start_day** sunday Any week day (sunday, monday, tuesday, etc.) Sets the day of the week the calendar should start on. **month_type** long long, short Determines what version of the month name to use in the header. long = January, short = Jan. -**day_type** abr long, short, abr Determines what version of the weekday names to use in +**day_type** abr long, short, abr Determines what version of the weekday names to use in the column headers. long = Sunday, short = Sun, abr = Su. **show_next_prev** FALSE TRUE/FALSE (boolean) Determines whether to display links allowing you to toggle to next/previous months. See information on this feature below. @@ -171,4 +182,95 @@ pair of pseudo-variables as shown here:: $this->load->library('calendar', $prefs); - echo $this->calendar->generate(); \ No newline at end of file + echo $this->calendar->generate(); + +*************** +Class Reference +*************** + +.. class:: CI_Calendar + + .. method:: initialize([$config = array()]) + + :param array $config: config preferences + :returns: void + + Initializes the Calendaring preferences. Accepts an associative array as input, containing display preferences. + + + .. method:: generate([$year = ''[, $month = ''[, $data = array()]]]) + + :param int $year: the year + :param int $month: the month + :param array $data: the data to be shown in the calendar cells + :returns: string + + Generate the calendar. + + + .. method:: get_month_name($month) + + :param int $month: the numeric month + :returns: string + + Generates a textual month name based on the numeric month provided. + + + .. method:: get_day_names($day_type = '') + + :param string $day_type: one of 'long', 'short', or 'abr' + :returns: array + + Returns an array of day names (Sunday, Monday, etc.) based on the type + provided. Options: long, short, abr. If no ``$day_type`` is provided (or + if an invalid type is provided) this method will return the "abbreviated" + style. + + + .. method:: adjust_date($month, $year) + + :param int $month: the month + :param int $year: the year + :returns: array + + This method makes usre that you have a valid month/year. For example, if + you submit 13 as the month, the year will increment and the month will + become January:: + + print_r($this->calendar->adjust_date(13, 2013)); + + outputs:: + + Array + (     + [month] => '01' + [year] => '2014' + ) + + + .. method:: get_total_days($month, $year) + + :param int $month: the month + :param int $year: the year + :returns: int + + Total days in a given month:: + + echo $this->calendar->get_total_days(2, 2012); + // 29 + + + .. method:: default_template() + + :returns: array + + Sets the default template. This method is used when you have not created + your own template. + + + .. method:: parse_template() + + :returns: void + + Harvests the data within the template ``{pseudo-variables}`` used to + display the calendar. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 82b34e6c10fa80e1b3a0d03c41d084e5ff121403 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Sun, 21 Jul 2013 23:07:20 -0700 Subject: Update Cart lib docs --- user_guide_src/source/libraries/cart.rst | 152 +++++++++++++++++++++---------- 1 file changed, 105 insertions(+), 47 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/cart.rst b/user_guide_src/source/libraries/cart.rst index 716e94bcb..ad1955d27 100644 --- a/user_guide_src/source/libraries/cart.rst +++ b/user_guide_src/source/libraries/cart.rst @@ -11,7 +11,16 @@ Please note that the Cart Class ONLY provides the core "cart" functionality. It does not provide shipping, credit card authorization, or other processing components. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + +
+ +******************** +Using the Cart Class +******************** Initializing the Shopping Cart Class ==================================== @@ -29,7 +38,7 @@ use the $this->load->library function:: $this->load->library('cart'); Once loaded, the Cart object will be available using:: - + $this->cart .. note:: The Cart Class will load and initialize the Session Class @@ -179,7 +188,7 @@ helper `.

- + Updating The Cart ================= @@ -197,7 +206,7 @@ function: 'qty' => 3 ); - $this->cart->update($data); + $this->cart->update($data); // Or a multi-dimensional array @@ -243,66 +252,115 @@ update form is submitted. Please examine the construction of the "view cart" page above for more information. -Function Reference -================== +*************** +Class Reference +*************** + +.. class:: CI_Cart + + .. attribute:: $product_id_rules = '\.a-z0-9_-' + + These are the regular expression rules that we use to validate the product + ID - alpha-numeric, dashes, underscores, or periods by default + + .. attribute:: $product_name_rules = '\w \-\.\:' + + These are the regular expression rules that we use to validate the product ID and product name - alpha-numeric, dashes, underscores, colons or periods by + default + + .. attribute:: $product_name_safe = TRUE + + Whether or not to only allow safe product names. Default TRUE. + + + .. method:: insert([$items = array()]) + + :param array $items: the items to insert into the cart + :returns: bool + + Insert items into the cart and save it to the session table. Returns TRUE + on success and FALSE on failure. + + + .. method:: update([$items = array()]) + + :param array $items: the items to update in the cart + :returns: bool + + This method permits the quantity of a given item to be changed. + Typically it is called from the "view cart" page if a user makes changes + to the quantity before checkout. That array must contain the product ID + and quantity for each item. + + + .. method:: remove($rowid) + + :param int $rowid: the ID of the item to remove from the cart + :returns: bool + + Allows you to remove an item from the shopping cart by passing it the + ``$rowid``. + + + .. method:: total() + + :returns: int + + Displays the total amount in the cart. + + + .. method:: total_items() + + :returns: int + + Displays the total number of items in the cart. -$this->cart->insert(); -********************** -Permits you to add items to the shopping cart, as outlined above. + .. method:: contents([$newest_first = FALSE]) -$this->cart->update(); -********************** + :param bool $newest_first: order the array with newest first? + :returns: array -Permits you to update items in the shopping cart, as outlined above. + Returns an array containing everything in the cart. You can sort the + order by which the array is returned by passing it TRUE where the contents + will be sorted from newest to oldest, otherwise it is sorted from oldest + to newest. -$this->cart->remove(rowid); -*************************** -Allows you to remove an item from the shopping cart by passing it the rowid. + .. method:: get_item($row_id) -$this->cart->total(); -********************* + :param int $row_id: the row ID to retrieve + :returns: array -Displays the total amount in the cart. + Returns an array containing data for the item matching the specified row + ID, or FALSE if no such item exists. -$this->cart->total_items(); -*************************** -Displays the total number of items in the cart. + .. method:: has_options($row_id = '') -$this->cart->contents(boolean); -******************************* + :param int $row_id: the row ID to inspect + :returns: bool -Returns an array containing everything in the cart. You can sort the order, -by which this is returned by passing it "true" where the contents will be sorted -from newest to oldest, by leaving this function blank, you'll automatically just get -first added to the basket to last added to the basket. + Returns TRUE (boolean) if a particular row in the cart contains options. + This method is designed to be used in a loop with :meth:contents:, since + you must pass the rowid to this function, as shown in the Displaying + the Cart example above. -$this->cart->get_item($row_id); -******************************* -Returns an array containing data for the item matching the specified row ID, -or FALSE if no such item exists. + .. method:: product_options([$row_id = '']) -$this->cart->has_options($row_id); -********************************** + :param int $row_id: the row ID + :returns: array -Returns TRUE (boolean) if a particular row in the cart contains options. -This function is designed to be used in a loop with -$this->cart->contents(), since you must pass the rowid to this function, -as shown in the Displaying the Cart example above. + Returns an array of options for a particular product. This method is + designed to be used in a loop with :meth:contents:, since you + must pass the rowid to this method, as shown in the Displaying the + Cart example above. -$this->cart->product_options($row_id); -************************************** -Returns an array of options for a particular product. This function is -designed to be used in a loop with $this->cart->contents(), since you -must pass the rowid to this function, as shown in the Displaying the -Cart example above. + .. method:: destroy() -$this->cart->destroy(); -*********************** + :returns: void -Permits you to destroy the cart. This function will likely be called -when you are finished processing the customer's order. + Permits you to destroy the cart. This method will likely be called + when you are finished processing the customer's order. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 912ee4c5ca099162b5accc153f1bb6f2cb9b5fa1 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Sun, 21 Jul 2013 23:52:27 -0700 Subject: Update Config lib docs --- user_guide_src/source/libraries/config.rst | 102 ++++++++++++++++++++++++----- 1 file changed, 85 insertions(+), 17 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/config.rst b/user_guide_src/source/libraries/config.rst index 08d9c2905..54aa70b2d 100644 --- a/user_guide_src/source/libraries/config.rst +++ b/user_guide_src/source/libraries/config.rst @@ -9,7 +9,16 @@ These preferences can come from the default config file .. note:: This class is initialized automatically by the system so there is no need to do it manually. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + +
+ +***************************** +Working with the Config Class +***************************** Anatomy of a Config File ======================== @@ -157,27 +166,86 @@ folders: that you wish to change for your environment. The config items declared in your environment folders always overwrite those in your global config files. -Helper Functions -================ -The config class has the following helper functions: +*************** +Class Reference +*************** -$this->config->site_url(); -*************************** +.. class:: CI_Config -This function retrieves the URL to your site, along with the "index" -value you've specified in the config file. + .. attribute:: $config -$this->config->base_url(); -*************************** + Array of all loaded config values -This function retrieves the URL to your site, plus an optional path such -as to a stylesheet or image. + .. attribute:: $is_loaded -The two functions above are normally accessed via the corresponding -functions in the :doc:`URL Helper `. + Array of all loaded config files -$this->config->system_url(); -***************************** -This function retrieves the URL to your system folder. + .. method:: item($item[, $index='']) + + :param string $item: config item name + :param string $index: index name, if the item is an element in a config + item that is itself an array. + :returns: mixed - the config item or FALSE if it does not exist + + Fetch a config file item. + + + .. method:: set_item($item, $value) + + :param string $item: config item name + :param string $value: config item value + :returns: void + + Sets a config file item to the specified value. + + + .. method:: slash_item($item) + + :param string $item: config item name + :returns: moxied - the config item (slashed) or FALSE if it does not exist + + This method is identical to :meth:item:, except it appends a forward + slash to the end of the item, if it exists. + + + .. method:: load([$file = ''[, $use_sections = FALSE[, $fail_gracefully = FALSE]]]) + + :param string $file: Configuration file name + :param bool $use_sections: Whether config values shoud be loaded into + their own section (index of the main config array) + :param bool $fail_gracefully: Whether to return FALSE or to display an + error message + :returns: bool + + Loads a configuration file. + + + .. method:: site_url() + + :returns: string + + This method retrieves the URL to your site, along with the "index" value + you've specified in the config file. + + This method is normally accessed via the corresponding functions in the + :doc:`URL Helper `. + + + .. method:: base_url() + + :returns: string + + This method retrieves the URL to your site, plus an optional path such + as to a stylesheet or image. + + This method is normally accessed via the corresponding functions in the + :doc:`URL Helper `. + + + .. method:: system_url() + + :returns: string + + This method retrieves the URL to your system folder. -- cgit v1.2.3-24-g4f1b From d386f25b4288bbe706c662ec169627d9e91ed31f Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 24 Jul 2013 17:35:45 -0700 Subject: Update Email lib docs --- user_guide_src/source/libraries/email.rst | 346 ++++++++++++++++++------------ 1 file changed, 206 insertions(+), 140 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/email.rst b/user_guide_src/source/libraries/email.rst index 39629ece1..1d9d2c171 100644 --- a/user_guide_src/source/libraries/email.rst +++ b/user_guide_src/source/libraries/email.rst @@ -16,6 +16,17 @@ CodeIgniter's robust Email Class supports the following features: BCC batches. - Email Debugging tools +.. contents:: + :local: + +.. raw:: html + +
+ +*********************** +Using the Email Library +*********************** + Sending Email ============= @@ -31,12 +42,12 @@ This example assumes you are sending the email from one of your $this->load->library('email'); $this->email->from('your@example.com', 'Your Name'); - $this->email->to('someone@example.com'); - $this->email->cc('another@another-example.com'); - $this->email->bcc('them@their-example.com'); + $this->email->to('someone@example.com'); + $this->email->cc('another@another-example.com'); + $this->email->bcc('them@their-example.com'); $this->email->subject('Email Test'); - $this->email->message('Testing the email class.'); + $this->email->message('Testing the email class.'); $this->email->send(); @@ -83,7 +94,7 @@ Preference Default Value Options Descript =================== ====================== ============================ ======================================================================= **useragent** CodeIgniter None The "user agent". **protocol** mail mail, sendmail, or smtp The mail sending protocol. -**mailpath** /usr/sbin/sendmail None The server path to Sendmail. +**mailpath** /usr/sbin/sendmail None The server path to Sendmail. **smtp_host** No Default None SMTP Server Address. **smtp_user** No Default None SMTP Username. **smtp_pass** No Default None SMTP Password. @@ -106,206 +117,261 @@ Preference Default Value Options Descript **dsn** FALSE TRUE or FALSE (boolean) Enable notify message from server =================== ====================== ============================ ======================================================================= -Email Methods Reference -======================= +Overriding Word Wrapping +======================== -$this->email->from() --------------------- +If you have word wrapping enabled (recommended to comply with RFC 822) +and you have a very long link in your email it can get wrapped too, +causing it to become un-clickable by the person receiving it. +CodeIgniter lets you manually override word wrapping within part of your +message like this:: -Sets the email address and name of the person sending the email:: + The text of your email that + gets wrapped normally. - $this->email->from('you@example.com', 'Your Name'); + {unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap} -You can also set a Return-Path, to help redirect undelivered mail:: + More text that will be + wrapped normally. - $this->email->from('you@example.com', 'Your Name', 'returned_emails@example.com'); - -.. note:: Return-Path can't be used if you've configured - 'smtp' as your protocol. -$this->email->reply_to() ------------------------- +Place the item you do not want word-wrapped between: {unwrap} {/unwrap} -Sets the reply-to address. If the information is not provided the -information in the "from" method is used. Example:: +*************** +Class Reference +*************** - $this->email->reply_to('you@example.com', 'Your Name'); +.. class:: CI_Email -$this->email->to() ------------------- + .. method:: from($from[, $name = ''[, $return_path = NULL]]) -Sets the email address(s) of the recipient(s). Can be a single email, a -comma-delimited list or an array:: + :param string $from: "From" email address + :param string $name: "From" display name + :param string $return_path: optional email address to redirect undelivered email + :returns: CI_Email object for method chaining - $this->email->to('someone@example.com'); + Sets the email address and name of the person sending the email:: -:: + $this->email->from('you@example.com', 'Your Name'); - $this->email->to('one@example.com, two@example.com, three@example.com'); + You can also set a Return-Path, to help redirect undelivered mail:: -:: + $this->email->from('you@example.com', 'Your Name', 'returned_emails@example.com'); - $list = array('one@example.com', 'two@example.com', 'three@example.com'); + .. note:: Return-Path can't be used if you've configured 'smtp' as + your protocol. - $this->email->to($list); -$this->email->cc() ------------------- + .. method:: reply_to($replyto[, $name = '']) -Sets the CC email address(s). Just like the "to", can be a single email, -a comma-delimited list or an array. + :param string $replyto: email address for replies + :param string $name: display name for reply email address + :returns: CI_Email object for method chaining -$this->email->bcc() -------------------- + Sets the reply-to address. If the information is not provided the + information in the :meth:from method is used. Example:: -Sets the BCC email address(s). Just like the "to", can be a single -email, a comma-delimited list or an array. + $this->email->reply_to('you@example.com', 'Your Name'); -$this->email->subject() ------------------------ -Sets the email subject:: + .. method:: to($to) - $this->email->subject('This is my subject'); + :param mixed $to: comma delimited string or array of email addresses + :returns: CI_Email object for method chaining -$this->email->message() ------------------------ + Sets the email address(s) of the recipient(s). Can be a single email + , a comma-delimited list or an array:: -Sets the email message body:: + $this->email->to('someone@example.com'); - $this->email->message('This is my message'); + :: -$this->email->set_alt_message() -------------------------------- + $this->email->to('one@example.com, two@example.com, three@example.com'); -Sets the alternative email message body:: + :: - $this->email->set_alt_message('This is the alternative message'); + $list = array('one@example.com', 'two@example.com', 'three@example.com'); -This is an optional message string which can be used if you send HTML -formatted email. It lets you specify an alternative message with no HTML -formatting which is added to the header string for people who do not -accept HTML email. If you do not set your own message CodeIgniter will -extract the message from your HTML email and strip the tags. + $this->email->to($list); -$this->email->set_header() --------------------------- -Appends additional headers to the e-mail:: + .. method:: cc($cc) - $this->email->set_header('Header1', 'Value1'); - $this->email->set_header('Header2', 'Value2'); + :param mixed $cc: comma delimited string or array of email addresses + :returns: CI_Email object for method chaining -$this->email->clear() ---------------------- + Sets the CC email address(s). Just like the "to", can be a single + email, a comma-delimited list or an array. -Initializes all the email variables to an empty state. This method is -intended for use if you run the email sending method in a loop, -permitting the data to be reset between cycles. -:: + .. method:: bcc($bcc, $limit = '') - foreach ($list as $name => $address) - { - $this->email->clear(); + :param mixed $bcc: comma delimited string or array of email addresses + :param int $limit: Maximum number of emails to send per batch + :returns: CI_Email object for method chaining - $this->email->to($address); - $this->email->from('your@example.com'); - $this->email->subject('Here is your info '.$name); - $this->email->message('Hi '.$name.' Here is the info you requested.'); - $this->email->send(); - } + Sets the BCC email address(s). Just like the "to", can be a single + email, a comma-delimited list or an array. -If you set the parameter to TRUE any attachments will be cleared as -well:: + If ``$limit`` is set, "batch mode" will be enabled, which will send + the emails to batches, with each batch not exceeding the specified + ``$limit``. - $this->email->clear(TRUE); -$this->email->send() --------------------- + .. method:: subject($subject) -The Email sending method. Returns boolean TRUE or FALSE based on -success or failure, enabling it to be used conditionally:: + :param string $subject: email subject line + :returns: CI_Email object for method chaining - if ( ! $this->email->send()) - { - // Generate error - } + Sets the email subject:: -This method will automatically clear all parameters if the request was -successful. To stop this behaviour pass FALSE:: + $this->email->subject('This is my subject'); - if ($this->email->send(FALSE)) - { - // Parameters won't be cleared - } -.. note:: In order to use the ``print_debugger()`` method, you need - to avoid clearing the email parameters. + .. method:: message($body) -$this->email->attach() ----------------------- + :param string $body: email body + :returns: CI_Email object for method chaining -Enables you to send an attachment. Put the file path/name in the first -parameter. Note: Use a file path, not a URL. For multiple attachments -use the method multiple times. For example:: + Sets the email message body:: - $this->email->attach('/path/to/photo1.jpg'); - $this->email->attach('/path/to/photo2.jpg'); - $this->email->attach('/path/to/photo3.jpg'); + $this->email->message('This is my message'); -To use the default disposition (attachment), leave the second parameter blank, -otherwise use a custom disposition:: - $this->email->attach('image.jpg', 'inline'); + .. method:: set_alt_message([$str = '']) -If you'd like to use a custom file name, you can use the third paramater:: + :param string $str: alternate email body + :returns: CI_Email object for method chaining - $this->email->attach('filename.pdf', 'attachment', 'report.pdf'); + Sets the alternative email message body:: -If you need to use a buffer string instead of a real - physical - file you can -use the first parameter as buffer, the third parameter as file name and the fourth -parameter as mime-type:: + $this->email->set_alt_message('This is the alternative message'); - $this->email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf'); + This is an optional message string which can be used if you send + HTML formatted email. It lets you specify an alternative message + with no HTML formatting which is added to the header string for + people who do not accept HTML email. If you do not set your own + message CodeIgniter will extract the message from your HTML email + and strip the tags. -$this->email->print_debugger() ------------------------------- -Returns a string containing any server messages, the email headers, and -the email messsage. Useful for debugging. + .. method:: set_header($header, $value) -You can optionally specify which parts of the message should be printed. -Valid options are: **headers**, **subject**, **body**. + :param string $header: header name + :param string $value: header value + :returns: void -Example:: + Appends additional headers to the e-mail:: - // You need to pass FALSE while sending in order for the email data - // to not be cleared - if that happens, print_debugger() would have - // nothing to output. - $this->email->send(FALSE); + $this->email->set_header('Header1', 'Value1'); + $this->email->set_header('Header2', 'Value2'); - // Will only print the email headers, excluding the message subject and body - $this->email->print_debugger(array('headers')); -.. note:: By default, all of the raw data will be printed. + .. method:: clear([$clear_attachments = FALSE]) -Overriding Word Wrapping -======================== + :param bool $clear_attachments: whether or not to clear attachments -If you have word wrapping enabled (recommended to comply with RFC 822) -and you have a very long link in your email it can get wrapped too, -causing it to become un-clickable by the person receiving it. -CodeIgniter lets you manually override word wrapping within part of your -message like this:: + Initializes all the email variables to an empty state. This method + is intended for use if you run the email sending method in a loop, + permitting the data to be reset between cycles. - The text of your email that - gets wrapped normally. + :: - {unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap} + foreach ($list as $name => $address) + { + $this->email->clear(); - More text that will be - wrapped normally. - + $this->email->to($address); + $this->email->from('your@example.com'); + $this->email->subject('Here is your info '.$name); + $this->email->message('Hi '.$name.' Here is the info you requested.'); + $this->email->send(); + } + + If you set the parameter to TRUE any attachments will be cleared as + well:: + + $this->email->clear(TRUE); + + + .. method:: send([$auto_clear = TRUE]) + + :param bool $auto_clear: Whether to :meth:clear automatically + :returns: bool + + The Email sending method. Returns boolean TRUE or FALSE based on + success or failure, enabling it to be used conditionally:: + + if ( ! $this->email->send()) + { + // Generate error + } + + This method will automatically clear all parameters if the request was + successful. To stop this behaviour pass FALSE:: + + if ($this->email->send(FALSE)) + { + // Parameters won't be cleared + } + + .. note:: In order to use the ``print_debugger()`` method, you need + to avoid clearing the email parameters. + + + .. method:: attach($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]]) + + :param string $filename: name of the file + :param string $disposition: 'disposition' of the attachment. Most + email clients make their own decision regardless of the MIME + specification used here. https://www.iana.org/assignments/cont-disp/cont-disp.xhtml + :param string $newname: custom name to use for the file in the email + :param string $mime: MIME type to use (useful for buffered data) + :returns: CI_Email object for method chaining + + Enables you to send an attachment. Put the file path/name in the first + parameter. Note: Use a file path, not a URL. For multiple attachments + use the method multiple times. For example:: + + $this->email->attach('/path/to/photo1.jpg'); + $this->email->attach('/path/to/photo2.jpg'); + $this->email->attach('/path/to/photo3.jpg'); + + To use the default disposition (attachment), leave the second parameter blank, + otherwise use a custom disposition:: + + $this->email->attach('image.jpg', 'inline'); + + If you'd like to use a custom file name, you can use the third paramater:: + + $this->email->attach('filename.pdf', 'attachment', 'report.pdf'); + + If you need to use a buffer string instead of a real - physical - file you can + use the first parameter as buffer, the third parameter as file name and the fourth + parameter as mime-type:: + + $this->email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf'); + + + .. method:: print_debugger([$include = array('headers', 'subject', 'body')]) + + :param array $include: Which parts of the message to print out + :returns: string + + Returns a string containing any server messages, the email headers, and + the email messsage. Useful for debugging. + + You can optionally specify which parts of the message should be printed. + Valid options are: **headers**, **subject**, **body**. + + Example:: + + // You need to pass FALSE while sending in order for the email data + // to not be cleared - if that happens, print_debugger() would have + // nothing to output. + $this->email->send(FALSE); + + // Will only print the email headers, excluding the message subject and body + $this->email->print_debugger(array('headers')); -Place the item you do not want word-wrapped between: {unwrap} {/unwrap} \ No newline at end of file + .. note:: By default, all of the raw data will be printed. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 5d80d0f215a48ed985e0e4ff9eb50f53f399e9bd Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 24 Jul 2013 17:44:29 -0700 Subject: Update Encrypt lib docs --- user_guide_src/source/libraries/encryption.rst | 176 +++++++++++++++---------- 1 file changed, 105 insertions(+), 71 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst index a38122203..f7235bfd2 100644 --- a/user_guide_src/source/libraries/encryption.rst +++ b/user_guide_src/source/libraries/encryption.rst @@ -10,6 +10,17 @@ reasonable degree of security for encrypted sessions or other such "light" purposes. If Mcrypt is available, you'll be provided with a high degree of security appropriate for storage. +.. contents:: + :local: + +.. raw:: html + +
+ +**************************** +Using the Encryption Library +**************************** + Setting your Key ================ @@ -61,104 +72,127 @@ initialized in your controller using the **$this->load->library** function:: $this->load->library('encrypt'); -Once loaded, the Encrypt library object will be available using: -$this->encrypt +Once loaded, the Encrypt library object will be available using +``$this->encrypt`` + +*************** +Class Reference +*************** + +.. class:: CI_Encrypt + + .. method:: encode($string, $key = '') + + :param string $string: contents to be encrypted + :param string $key: encryption key + :returns: string + + Performs the data encryption and returns it as a string. Example:: + + $msg = 'My secret message'; + + $encrypted_string = $this->encrypt->encode($msg); + + You can optionally pass your encryption key via the second parameter if + you don't want to use the one in your config file:: + + $msg = 'My secret message'; + $key = 'super-secret-key'; + + $encrypted_string = $this->encrypt->encode($msg, $key); + -$this->encrypt->encode() -======================== + .. method:: decode($string, $key = '') -Performs the data encryption and returns it as a string. Example:: + :param string $string: contents to be decrypted + :param string $key: encryption key + :returns: string - $msg = 'My secret message'; + Decrypts an encoded string. Example:: - $encrypted_string = $this->encrypt->encode($msg); - + $encrypted_string = 'APANtByIGI1BpVXZTJgcsAG8GZl8pdwwa84'; -You can optionally pass your encryption key via the second parameter if -you don't want to use the one in your config file:: + $plaintext_string = $this->encrypt->decode($encrypted_string); - $msg = 'My secret message'; - $key = 'super-secret-key'; + You can optionally pass your encryption key via the second parameter if + you don't want to use the one in your config file:: - $encrypted_string = $this->encrypt->encode($msg, $key); + $msg = 'My secret message'; + $key = 'super-secret-key'; -$this->encrypt->decode() -======================== + $encrypted_string = $this->encrypt->decode($msg, $key); -Decrypts an encoded string. Example:: - $encrypted_string = 'APANtByIGI1BpVXZTJgcsAG8GZl8pdwwa84'; + .. method:: set_cipher($cipher) - $plaintext_string = $this->encrypt->decode($encrypted_string); + :param int $cipher: valid PHP Mcrypt cypher constant + :returns: CI_Encrypt object for method chaining -You can optionally pass your encryption key via the second parameter if -you don't want to use the one in your config file:: + Permits you to set an Mcrypt cipher. By default it uses + **MCRYPT_RIJNDAEL_256**. Example:: - $msg = 'My secret message'; - $key = 'super-secret-key'; + $this->encrypt->set_cipher(MCRYPT_BLOWFISH); - $encrypted_string = $this->encrypt->decode($msg, $key); + Please visit php.net for a list of `available + ciphers `_. -$this->encrypt->set_cipher(); -============================== + If you'd like to manually test whether your server supports Mcrypt you + can use:: -Permits you to set an Mcrypt cipher. By default it uses -**MCRYPT_RIJNDAEL_256**. Example:: + echo ( ! function_exists('mcrypt_encrypt')) ? 'Nope' : 'Yup'; - $this->encrypt->set_cipher(MCRYPT_BLOWFISH); -Please visit php.net for a list of `available -ciphers `_. + .. method:: set_mode($mode) -If you'd like to manually test whether your server supports Mcrypt you -can use:: + :param int $mode: valid PHP Mcrypt mode constant + :returns: CI_Encrypt object for method chaining - echo ( ! function_exists('mcrypt_encrypt')) ? 'Nope' : 'Yup'; + Permits you to set an Mcrypt mode. By default it uses **MCRYPT_MODE_CBC**. + Example:: -$this->encrypt->set_mode(); -============================ + $this->encrypt->set_mode(MCRYPT_MODE_CFB); -Permits you to set an Mcrypt mode. By default it uses **MCRYPT_MODE_CBC**. -Example:: + Please visit php.net for a list of `available + modes `_. - $this->encrypt->set_mode(MCRYPT_MODE_CFB); -Please visit php.net for a list of `available -modes `_. + .. method:: encode_from_legacy($string[, $legacy_mode = MCRYPT_MODE_ECB[, $key = '']]) -$this->encrypt->encode_from_legacy($orig_data, $legacy_mode = MCRYPT_MODE_ECB, $key = ''); -========================================================================================== + :param string $string: contents to be encrypted + :param int $legacy_mode: valid PHP Mcrypt cypher constant + :param string $key: encryption key + :returns: string -Enables you to re-encode data that was originally encrypted with -CodeIgniter 1.x to be compatible with the Encryption library in -CodeIgniter 2.x. It is only necessary to use this method if you have -encrypted data stored permanently such as in a file or database and are -on a server that supports Mcrypt. "Light" use encryption such as -encrypted session data or transitory encrypted flashdata require no -intervention on your part. However, existing encrypted Sessions will be -destroyed since data encrypted prior to 2.x will not be decoded. + Enables you to re-encode data that was originally encrypted with + CodeIgniter 1.x to be compatible with the Encryption library in + CodeIgniter 2.x. It is only necessary to use this method if you have + encrypted data stored permanently such as in a file or database and are + on a server that supports Mcrypt. "Light" use encryption such as + encrypted session data or transitory encrypted flashdata require no + intervention on your part. However, existing encrypted Sessions will be + destroyed since data encrypted prior to 2.x will not be decoded. -.. important:: - **Why only a method to re-encode the data instead of maintaining legacy - methods for both encoding and decoding?** The algorithms in the - Encryption library have improved in CodeIgniter 2.x both for performance - and security, and we do not wish to encourage continued use of the older - methods. You can of course extend the Encryption library if you wish and - replace the new methods with the old and retain seamless compatibility - with CodeIgniter 1.x encrypted data, but this a decision that a - developer should make cautiously and deliberately, if at all. + .. important:: + **Why only a method to re-encode the data instead of maintaining legacy + methods for both encoding and decoding?** The algorithms in the + Encryption library have improved in CodeIgniter 2.x both for performance + and security, and we do not wish to encourage continued use of the older + methods. You can of course extend the Encryption library if you wish and + replace the new methods with the old and retain seamless compatibility + with CodeIgniter 1.x encrypted data, but this a decision that a + developer should make cautiously and deliberately, if at all. -:: + :: - $new_data = $this->encrypt->encode_from_legacy($old_encrypted_string); + $new_data = $this->encrypt->encode_from_legacy($old_encrypted_string); -====================== =============== ======================================================================= -Parameter Default Description -====================== =============== ======================================================================= -**$orig_data** n/a The original encrypted data from CodeIgniter 1.x's Encryption library -**$legacy_mode** MCRYPT_MODE_ECB The Mcrypt mode that was used to generate the original encrypted data. - CodeIgniter 1.x's default was MCRYPT_MODE_ECB, and it will assume that - to be the case unless overridden by this parameter. -**$key** n/a The encryption key. This it typically specified in your config file as - outlined above. -====================== =============== ======================================================================= \ No newline at end of file + ====================== =============== ======================================================================= + Parameter Default Description + ====================== =============== ======================================================================= + **$orig_data** n/a The original encrypted data from CodeIgniter 1.x's Encryption library + **$legacy_mode** MCRYPT_MODE_ECB The Mcrypt mode that was used to generate the original encrypted data. + CodeIgniter 1.x's default was MCRYPT_MODE_ECB, and it will assume that + to be the case unless overridden by this parameter. + **$key** n/a The encryption key. This it typically specified in your config file as + outlined above. + ====================== =============== ======================================================================= \ No newline at end of file -- cgit v1.2.3-24-g4f1b From c9bf303220f90b0e71acd54d150fafc87df3df81 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 24 Jul 2013 18:01:27 -0700 Subject: Update Upload lib docs --- user_guide_src/source/libraries/file_uploading.rst | 165 ++++++++++----------- 1 file changed, 82 insertions(+), 83 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/file_uploading.rst b/user_guide_src/source/libraries/file_uploading.rst index a92d3af34..695998d73 100644 --- a/user_guide_src/source/libraries/file_uploading.rst +++ b/user_guide_src/source/libraries/file_uploading.rst @@ -5,6 +5,13 @@ File Uploading Class CodeIgniter's File Uploading Class permits files to be uploaded. You can set various preferences, restricting the type and size of the files. +.. contents:: + :local: + +.. raw:: html + +
+ *********** The Process *********** @@ -240,105 +247,97 @@ preferences in a config file. Class Reference *************** -The following methods are available: +.. class:: CI_Upload -$this->upload->do_upload() -========================== + .. method:: do_upload([$field = 'userfile']) -Performs the upload based on the preferences you've set. + :param string $field: name of the form field + :returns: bool -.. note:: By default the upload routine expects the file to come from - a form field called userfile, and the form must be of type - "multipart". + Performs the upload based on the preferences you've set. -:: + .. note:: By default the upload routine expects the file to come from + a form field called userfile, and the form must be of type + "multipart". -
+ :: -If you would like to set your own field name simply pass its value to -the ``do_upload()`` method:: + - $field_name = "some_field_name"; - $this->upload->do_upload($field_name); + If you would like to set your own field name simply pass its value to + the ``do_upload()`` method:: -$this->upload->display_errors() -=============================== + $field_name = "some_field_name"; + $this->upload->do_upload($field_name); -Retrieves any error messages if the ``do_upload()`` method returned -false. The method does not echo automatically, it returns the data so -you can assign it however you need. -Formatting Errors -***************** + .. method:: display_errors([$open = '

'[, $close = '

']]) -By default the above method wraps any errors within

tags. You can -set your own delimiters like this:: + :param string $open: Opening markup + :param string $close: Closing markup + :returns: string - $this->upload->display_errors('

', '

'); + Retrieves any error messages if the ``do_upload()`` method returned + false. The method does not echo automatically, it returns the data so + you can assign it however you need. -$this->upload->data() -===================== + **Formatting Errors** -This is a helper method that returns an array containing all of the -data related to the file you uploaded. Here is the array prototype:: + By default the above method wraps any errors within

tags. You can + set your own delimiters like this:: - Array - ( - [file_name] => mypic.jpg - [file_type] => image/jpeg - [file_path] => /path/to/your/upload/ - [full_path] => /path/to/your/upload/jpg.jpg - [raw_name] => mypic - [orig_name] => mypic.jpg - [client_name] => mypic.jpg - [file_ext] => .jpg - [file_size] => 22.2 - [is_image] => 1 - [image_width] => 800 - [image_height] => 600 - [image_type] => jpeg - [image_size_str] => width="800" height="200" - ) + $this->upload->display_errors('

', '

'); -To return one element from the array:: - $this->upload->data('file_name'); // Returns: mypic.jpg + .. method:: data([$index = NULL]) -Explanation -*********** + :param string $data: element to return instead of the full array + :returns: mixed + + This is a helper method that returns an array containing all of the + data related to the file you uploaded. Here is the array prototype:: + + Array + ( + [file_name] => mypic.jpg + [file_type] => image/jpeg + [file_path] => /path/to/your/upload/ + [full_path] => /path/to/your/upload/jpg.jpg + [raw_name] => mypic + [orig_name] => mypic.jpg + [client_name] => mypic.jpg + [file_ext] => .jpg + [file_size] => 22.2 + [is_image] => 1 + [image_width] => 800 + [image_height] => 600 + [image_type] => jpeg + [image_size_str] => width="800" height="200" + ) + + To return one element from the array:: + + $this->upload->data('file_name'); // Returns: mypic.jpg + + **Explanation** + + Here is an explanation of the above array items. -Here is an explanation of the above array items. - -Item -Description -**file_name** -The name of the file that was uploaded including the file extension. -**file_type** -The file's Mime type -**file_path** -The absolute server path to the file -**full_path** -The absolute server path including the file name -**raw_name** -The file name without the extension -**orig_name** -The original file name. This is only useful if you use the encrypted -name option. -**client_name** -The file name as supplied by the client user agent, prior to any file -name preparation or incrementing. -**file_ext** -The file extension with period -**file_size** -The file size in kilobytes -**is_image** -Whether the file is an image or not. 1 = image. 0 = not. -**image_width** -Image width. -**image_height** -Image height -**image_type** -Image type. Typically the file extension without the period. -**image_size_str** -A string containing the width and height. Useful to put into an image -tag. \ No newline at end of file + ================ ================================================ + Item Description + ================ ================================================ + file_name The name of the file that was uploaded including the file extension. + file_type The file's Mime type + file_path The absolute server path to the file + full_path The absolute server path including the file name + raw_name The file name without the extension + orig_name The original file name. This is only useful if you use the encrypted name option. + client_name The file name as supplied by the client user agent, prior to any file name preparation or incrementing. + file_ext The file extension with period + file_size The file size in kilobytes + is_image Whether the file is an image or not. 1 = image. 0 = not. + image_width Image width. + image_height Image height + image_type Image type. Typically the file extension without the period. + image_size_str A string containing the width and height. Useful to put into an image tag. + ================ ================================================ \ No newline at end of file -- cgit v1.2.3-24-g4f1b From b799a0b3f09238fe46892b811025e7bf2ac81b19 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Tue, 6 Aug 2013 15:38:21 -0700 Subject: Partial update to FTP docs --- user_guide_src/source/libraries/ftp.rst | 87 +++++++++++++++++++-------------- 1 file changed, 49 insertions(+), 38 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/ftp.rst b/user_guide_src/source/libraries/ftp.rst index 05a3fdcc8..fd82590b9 100644 --- a/user_guide_src/source/libraries/ftp.rst +++ b/user_guide_src/source/libraries/ftp.rst @@ -10,9 +10,19 @@ directory to be recreated remotely via FTP. .. note:: SFTP and SSL FTP protocols are not supported, only standard FTP. -********************** +.. contents:: + :local: + +.. raw:: html + +
+ +************************** +Working with the FTP Class +************************** + Initializing the Class -********************** +====================== Like most other classes in CodeIgniter, the FTP class is initialized in your controller using the $this->load->library function:: @@ -79,53 +89,54 @@ In this example a local directory is mirrored on the server. $this->ftp->close(); -****************** -Function Reference -****************** +*************** +Class Reference +*************** -$this->ftp->connect() -===================== +.. class:: CI_FTP -Connects and logs into to the FTP server. Connection preferences are set -by passing an array to the function, or you can store them in a config -file. + .. method:: connect([$config = array()]) -Here is an example showing how you set preferences manually:: + :param array $config: Connection values + :returns: bool - $this->load->library('ftp'); + Connects and logs into to the FTP server. Connection preferences are set + by passing an array to the function, or you can store them in a config + file. - $config['hostname'] = 'ftp.example.com'; - $config['username'] = 'your-username'; - $config['password'] = 'your-password'; - $config['port'] = 21; - $config['passive'] = FALSE; - $config['debug'] = TRUE; + Here is an example showing how you set preferences manually:: - $this->ftp->connect($config); + $this->load->library('ftp'); -Setting FTP Preferences in a Config File -**************************************** + $config['hostname'] = 'ftp.example.com'; + $config['username'] = 'your-username'; + $config['password'] = 'your-password'; + $config['port'] = 21; + $config['passive'] = FALSE; + $config['debug'] = TRUE; -If you prefer you can store your FTP preferences in a config file. -Simply create a new file called the ftp.php, add the $config array in -that file. Then save the file at config/ftp.php and it will be used -automatically. + $this->ftp->connect($config); -Available connection options -**************************** + **Setting FTP Preferences in a Config File** -- **hostname** - the FTP hostname. Usually something like: - ftp.example.com -- **username** - the FTP username. -- **password** - the FTP password. -- **port** - The port number. Set to 21 by default. -- **debug** - TRUE/FALSE (boolean). Whether to enable debugging to - display error messages. -- **passive** - TRUE/FALSE (boolean). Whether to use passive mode. - Passive is set automatically by default. + If you prefer you can store your FTP preferences in a config file. + Simply create a new file called the ftp.php, add the $config array in + that file. Then save the file at config/ftp.php and it will be used + automatically. + + **Available connection options** + + ================== =================================== + Option Name Description + ================== =================================== + **hostname** the FTP hostname. Usually something like: ftp.example.com + **username** the FTP username + **password** the FTP password + **port** The port number. Set to 21 by default. + **debug** TRUE/FALSE (boolean). Whether to enable debugging to display error messages. + **passive** TRUE/FALSE (boolean). Whether to use passive mode. Passive is set automatically by default. + ================== =================================== -$this->ftp->upload() -==================== Uploads a file to your server. You must supply the local path and the remote path, and you can optionally set the mode and permissions. -- cgit v1.2.3-24-g4f1b From 2c08e4e4df83e67262d0cde8aed729e4343564fb Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 23 Sep 2013 15:20:21 +0300 Subject: [ci skip] Update Zip library docs --- user_guide_src/source/libraries/zip.rst | 229 ++++++++++++++++---------------- 1 file changed, 116 insertions(+), 113 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/zip.rst b/user_guide_src/source/libraries/zip.rst index c27718273..e0955e3d6 100644 --- a/user_guide_src/source/libraries/zip.rst +++ b/user_guide_src/source/libraries/zip.rst @@ -6,6 +6,17 @@ CodeIgniter's Zip Encoding Class classes permit you to create Zip archives. Archives can be downloaded to your desktop or saved to a directory. +.. contents:: + :local: + +.. raw:: html + +
+ +**************************** +Using the Zip Encoding Class +**************************** + Initializing the Class ====================== @@ -35,174 +46,166 @@ your server, and download it to your desktop. // Download the file to your desktop. Name it "my_backup.zip" $this->zip->download('my_backup.zip'); -****************** -Function Reference -****************** +*************** +Class Reference +*************** -$this->zip->add_data() -======================= +.. class:: CI_Zip -Permits you to add data to the Zip archive. The first parameter must -contain the name you would like given to the file, the second parameter -must contain the file data as a string:: + .. method:: add_data($filepath[, $data = NULL]) - $name = 'my_bio.txt'; - $data = 'I was born in an elevator...'; + :param mixed $filepath: a single file path or an array of file => data pairs + :param array $data: single file contents + :returns: void - $this->zip->add_data($name, $data); + Adds data to the Zip archive. Can work both in single and multiple files mode. -You are allowed multiple calls to this function in order to add several -files to your archive. Example:: + 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!'; - $this->zip->add_data($name, $data); + $name = 'mydata1.txt'; + $data = 'A Data String!'; + $this->zip->add_data($name, $data); - $name = 'mydata2.txt'; - $data = 'Another Data String!'; - $this->zip->add_data($name, $data); + $name = 'mydata2.txt'; + $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:: -Or you can pass multiple files using an array:: + $data = array( + 'mydata1.txt' => 'A Data String!', + 'mydata2.txt' => 'Another Data String!' + ); - $data = array( - 'mydata1.txt' => 'A Data String!', - 'mydata2.txt' => 'Another Data String!' - ); + $this->zip->add_data($data); - $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):: - $this->zip->download('my_backup.zip'); + $name = 'personal/my_bio.txt'; + $data = 'I was born in an elevator...'; -If you would like your compressed data organized into sub-folders, -include the path as part of the filename:: + $this->zip->add_data($name, $data); - $name = 'personal/my_bio.txt'; - $data = 'I was born in an elevator...'; + The above example will place my_bio.txt inside a folder called personal. - $this->zip->add_data($name, $data); + .. method:: add_dir($directory) -The above example will place my_bio.txt inside a folder called -personal. + :param mixed $directory: string directory name or an array of multiple directories + :returns: void -$this->zip->add_dir() -====================== + 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 function is unnecessary -since you can place your data into folders when using -$this->zip->add_data(), but if you would like to create an empty folder -you can do so. Example:: + $this->zip->add_dir('myfolder'); // Creates a directory called "myfolder" - $this->zip->add_dir('myfolder'); // Creates a folder called "myfolder" + .. method:: read_file($path[, $preserve_filepath = FALSE]) -$this->zip->read_file() -======================== + :param string $path: path to file + :param bool $preserve_filepath: whether to maintain the original filepath + :returns: bool -Permits you to compress a file that already exists somewhere on your -server. Supply a file path and the zip class will read it and add it to -the archive:: + Permits you to compress a file that already exists somewhere on your server. + Supply a file path and the zip class will read it and add it to the archive:: - $path = '/path/to/photo.jpg'; + $path = '/path/to/photo.jpg'; - $this->zip->read_file($path); + $this->zip->read_file($path); - // Download the file to your desktop. Name it "my_backup.zip" - $this->zip->download('my_backup.zip'); + // Download the file to your desktop. Name it "my_backup.zip" + $this->zip->download('my_backup.zip'); -If you would like the Zip archive to maintain the directory structure of -the file in it, pass TRUE (boolean) in the second parameter. Example:: + If you would like the Zip archive to maintain the directory structure of + the file in it, pass TRUE (boolean) in the second parameter. Example:: - $path = '/path/to/photo.jpg'; + $path = '/path/to/photo.jpg'; - $this->zip->read_file($path, TRUE); + $this->zip->read_file($path, TRUE); - // Download the file to your desktop. Name it "my_backup.zip" - $this->zip->download('my_backup.zip'); + // Download the file to your desktop. Name it "my_backup.zip" + $this->zip->download('my_backup.zip'); -In the above example, photo.jpg will be placed inside two folders: -path/to/ + In the above example, photo.jpg will be placed into the *path/to/* directory. -$this->zip->read_dir() -======================= + .. method:: read_dir($path[, $preserve_filepath = TRUE[, $root_path = NULL]]) -Permits you to compress a folder (and its contents) that already exists -somewhere on your server. Supply a file path to the directory and the -zip class will recursively read it and recreate it as a Zip archive. All -files contained within the supplied path will be encoded, as will any -sub-folders contained within it. Example:: + :param string $path: path to directory + :param bool $preserve_filepath: whether to maintain the original path + :param string $root_path: part of the path to exclude from the archive directory + :returns: bool - $path = '/path/to/your/directory/'; + Permits you to compress a directory (and its contents) that already exists somewhere on your server. + Supply a path to the directory and the zip class will recursively read and recreate it as a Zip archive. + All files contained within the supplied path will be encoded, as will any sub-directories contained within it. Example:: - $this->zip->read_dir($path); + $path = '/path/to/your/directory/'; - // Download the file to your desktop. Name it "my_backup.zip" - $this->zip->download('my_backup.zip'); + $this->zip->read_dir($path); -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 folder to be ignored you can pass FALSE (boolean) in the second -parameter. Example:: + // Download the file to your desktop. Name it "my_backup.zip" + $this->zip->download('my_backup.zip'); - $path = '/path/to/your/directory/'; + 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:: - $this->zip->read_dir($path, FALSE); + $path = '/path/to/your/directory/'; -This will create a ZIP with the folder "directory" inside, then all -sub-folders stored correctly inside that, but will not include the -folders /path/to/your. + $this->zip->read_dir($path, FALSE); -$this->zip->archive() -===================== + 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. -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 (666 or 777 is usually OK). Example:: + .. method:: archive($filepath) - $this->zip->archive('/path/to/folder/myarchive.zip'); // Creates a file named myarchive.zip + :param string $filepath: path to target zip archive + :returns: bool -$this->zip->download() -====================== + 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 (660 or 666 is usually OK). Example:: -Causes the Zip file to be downloaded from your server. The function must -be passed the name you would like the zip file called. Example:: + $this->zip->archive('/path/to/folder/myarchive.zip'); // Creates a file named myarchive.zip - $this->zip->download('latest_stuff.zip'); // File will be named "latest_stuff.zip" + .. method:: download($filename = 'backup.zip') -.. note:: Do not display any data in the controller in which you call - this function since it sends various server headers that cause the - download to happen and the file to be treated as binary. + :param string $filename: the archive file name + :returns: void -$this->zip->get_zip() -====================== + Causes the Zip file to be downloaded from your server. You must pass the name you would like the zip file called. Example:: -Returns the Zip-compressed file data. Generally you will not need this -function unless you want to do something unique with the data. Example:: + $this->zip->download('latest_stuff.zip'); // File will be named "latest_stuff.zip" - $name = 'my_bio.txt'; - $data = 'I was born in an elevator...'; + .. note:: Do not display any data in the controller in which you call + this method since it sends various server headers that cause the + download to happen and the file to be treated as binary. - $this->zip->add_data($name, $data); + .. method:: get_zip() - $zip_file = $this->zip->get_zip(); + :returns: string -$this->zip->clear_data() -========================= + Returns the Zip-compressed file data. Generally you will not need this method unless you want to do something unique with the data. Example:: -The Zip class caches your zip data so that it doesn't need to recompile -the Zip archive for each function you use above. If, however, you need -to create multiple Zips, each with different data, you can clear the -cache between calls. Example:: + $name = 'my_bio.txt'; + $data = 'I was born in an elevator...'; - $name = 'my_bio.txt'; - $data = 'I was born in an elevator...'; + $this->zip->add_data($name, $data); - $this->zip->add_data($name, $data); - $zip_file = $this->zip->get_zip(); + $zip_file = $this->zip->get_zip(); + + .. method:: clear_data() + + :returns: 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:: - $this->zip->clear_data(); + $name = 'my_bio.txt'; + $data = 'I was born in an elevator...'; - $name = 'photo.jpg'; - $this->zip->read_file("/path/to/photo.jpg"); // Read the file's contents + $this->zip->add_data($name, $data); + $zip_file = $this->zip->get_zip(); + $this->zip->clear_data(); - $this->zip->download('myphotos.zip'); + $name = 'photo.jpg'; + $this->zip->read_file("/path/to/photo.jpg"); // Read the file's contents + $this->zip->download('myphotos.zip'); \ No newline at end of file -- cgit v1.2.3-24-g4f1b From d8afb982f10e259142f33f882f6d6032a3ca9b1c Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 23 Sep 2013 16:01:46 +0300 Subject: [ci skip] Update XML-RPC library docs --- user_guide_src/source/libraries/xmlrpc.rst | 182 +++++++++++++++++------------ 1 file changed, 106 insertions(+), 76 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/xmlrpc.rst b/user_guide_src/source/libraries/xmlrpc.rst index a43c48837..c79f8bed9 100644 --- a/user_guide_src/source/libraries/xmlrpc.rst +++ b/user_guide_src/source/libraries/xmlrpc.rst @@ -5,6 +5,13 @@ XML-RPC and XML-RPC Server Classes CodeIgniter's XML-RPC classes permit you to send requests to another server, or set up your own XML-RPC server to receive requests. +.. contents:: + :local: + +.. raw:: html + +
+ **************** What is XML-RPC? **************** @@ -24,8 +31,11 @@ it to determine which class/method should be called to process the request. Once processed, the server will then send back a response message. -For detailed specifications, you can visit the -`XML-RPC `_ site. +For detailed specifications, you can visit the `XML-RPC `_ site. + +*********************** +Using the XML-RPC Class +*********************** Initializing the Class ====================== @@ -123,6 +133,7 @@ with the data type in the second position:: The `Data Types <#datatypes>`_ section below has a full list of data types. + Creating an XML-RPC Server ========================== @@ -425,114 +436,133 @@ the Server. $size = $parameters[1]['size']; $shape = $parameters[1]['shape']; -************************** -XML-RPC Function Reference -************************** +Data Types +========== -$this->xmlrpc->server() -======================= +According to the `XML-RPC spec `_ there are +seven types of values that you can send via XML-RPC: -Sets the URL and port number of the server to which a request is to be -sent:: +- *int* or *i4* +- *boolean* +- *string* +- *double* +- *dateTime.iso8601* +- *base64* +- *struct* (contains array of values) +- *array* (contains array of values) - $this->xmlrpc->server('http://www.sometimes.com/pings.php', 80); +*************** +Class Reference +*************** -$this->xmlrpc->timeout() -======================== +.. class:: CI_Xmlrpc -Set a time out period (in seconds) after which the request will be -canceled:: + .. method:: initialize([$config = array()]) - $this->xmlrpc->timeout(6); + :param array $config: configuration data + :returns: void -$this->xmlrpc->method() -======================= + Initializes the XML-RPC library. Accepts an associative array containing your settings. -Sets the method that will be requested from the XML-RPC server:: + .. method:: server($url[, $port = 80[, $proxy = FALSE[, $proxy_port = 8080]]]) - $this->xmlrpc->method('method'); + :param string $url: XML-RPC server URL + :param int $port: server port + :param string $proxy: optional proxy + :param int $proxy_port: proxy listening port + :returns: void -Where method is the name of the method. + Sets the URL and port number of the server to which a request is to be sent:: -$this->xmlrpc->request() -======================== + $this->xmlrpc->server('http://www.sometimes.com/pings.php', 80); -Takes an array of data and builds request to be sent to XML-RPC server:: + .. method:: timeout($seconds = 5) - $request = array(array('My Photoblog', 'string'), 'http://www.yoursite.com/photoblog/'); - $this->xmlrpc->request($request); + :param int $seconds: timeout in seconds + :returns: void -$this->xmlrpc->send_request() -============================== + Set a time out period (in seconds) after which the request will be canceled:: -The request sending function. Returns boolean TRUE or FALSE based on -success for failure, enabling it to be used conditionally. + $this->xmlrpc->timeout(6); -$this->xmlrpc->set_debug(TRUE); -================================ + .. method:: method($function) -Enables debugging, which will display a variety of information and error -data helpful during development. + :param string $function: method name + :returns: void -$this->xmlrpc->display_error() -=============================== + Sets the method that will be requested from the XML-RPC server:: -Returns an error message as a string if your request failed for some -reason. + $this->xmlrpc->method('method'); -:: + Where method is the name of the method. - echo $this->xmlrpc->display_error(); + .. method:: request($incoming) -$this->xmlrpc->display_response() -================================== + :param array $incoming: request data + :returns: void -Returns the response from the remote server once request is received. -The response will typically be an associative array. + Takes an array of data and builds request to be sent to XML-RPC server:: -:: + $request = array(array('My Photoblog', 'string'), 'http://www.yoursite.com/photoblog/'); + $this->xmlrpc->request($request); - $this->xmlrpc->display_response(); + .. method:: send_request() -$this->xmlrpc->send_error_message() -===================================== + :returns: bool -This function lets you send an error message from your server to the -client. First parameter is the error number while the second parameter -is the error message. + The request sending method. Returns boolean TRUE or FALSE based on success for failure, enabling it to be used conditionally. -:: + .. method set_debug($flag = TRUE) - return $this->xmlrpc->send_error_message('123', 'Requested data not available'); + :param bool $flag: debug status flag + :returns: void -$this->xmlrpc->send_response() -=============================== + Enables or disables debugging, which will display a variety of information and error data helpful during development. -Lets you send the response from your server to the client. An array of -valid data values must be sent with this method. + .. method:: display_error() -:: + :returns: string - $response = array( - array( - 'flerror' => array(FALSE, 'boolean'), - 'message' => "Thanks for the ping!" - ) - 'struct'); - return $this->xmlrpc->send_response($response); + Returns an error message as a string if your request failed for some reason. + :: -Data Types -========== + echo $this->xmlrpc->display_error(); -According to the `XML-RPC spec `_ there are -seven types of values that you can send via XML-RPC: + .. method:: display_response() -- *int* or *i4* -- *boolean* -- *string* -- *double* -- *dateTime.iso8601* -- *base64* -- *struct* (contains array of values) -- *array* (contains array of values) + :returns: mixed + + Returns the response from the remote server once request is received. The response will typically be an associative array. + :: + + $this->xmlrpc->display_response(); + + .. method:: send_error_message($number, $message) + + :param int $number: error number + :param string $message: error message + :returns: object + This method lets you send an error message from your server to the client. + First parameter is the error number while the second parameter is the error message. + :: + + return $this->xmlrpc->send_error_message(123, 'Requested data not available'); + + .. method send_response($response) + + :param array $response: response data + :returns: object + + Lets you send the response from your server to the client. An array of valid data values must be sent with this method. + :: + + $response = array( + array( + 'flerror' => array(FALSE, 'boolean'), + 'message' => "Thanks for the ping!" + ), + 'struct' + ); + + return $this->xmlrpc->send_response($response); \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 20d93e4806ce0084b3fd6540a626b761d5d66712 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 23 Sep 2013 16:22:23 +0300 Subject: [ci skip] Update the User Agent library docs --- user_guide_src/source/libraries/user_agent.rst | 242 ++++++++++++++----------- 1 file changed, 134 insertions(+), 108 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/user_agent.rst b/user_guide_src/source/libraries/user_agent.rst index 97abd2244..3662cf3ad 100644 --- a/user_guide_src/source/libraries/user_agent.rst +++ b/user_guide_src/source/libraries/user_agent.rst @@ -7,6 +7,17 @@ about the browser, mobile device, or robot visiting your site. In addition you can get referrer information as well as language and supported character-set information. +.. contents:: + :local: + +.. raw:: html + +
+ +************************** +Using the User Agent Class +************************** + Initializing the Class ====================== @@ -15,7 +26,7 @@ initialized in your controller using the $this->load->library function:: $this->load->library('user_agent'); -Once loaded, the object will be available using: $this->agent +Once loaded, the object will be available using: ``$this->agent`` User Agent Definitions ====================== @@ -38,163 +49,178 @@ is available. if ($this->agent->is_browser()) { - $agent = $this->agent->browser().' '.$this->agent->version(); + $agent = $this->agent->browser().' '.$this->agent->version(); } elseif ($this->agent->is_robot()) { - $agent = $this->agent->robot(); + $agent = $this->agent->robot(); } elseif ($this->agent->is_mobile()) { - $agent = $this->agent->mobile(); + $agent = $this->agent->mobile(); } else { - $agent = 'Unidentified User Agent'; + $agent = 'Unidentified User Agent'; } echo $agent; echo $this->agent->platform(); // Platform info (Windows, Linux, Mac, etc.) -****************** -Function Reference -****************** +*************** +Class Reference +*************** -$this->agent->is_browser() -=========================== +.. class: CI_User_agent -Returns TRUE/FALSE (boolean) if the user agent is a known web browser. + .. method:: is_browser([$key = NULL]) -:: + :param string $key: optional browser name + :returns: bool - if ($this->agent->is_browser('Safari')) - { - echo 'You are using Safari.'; - } - elseif ($this->agent->is_browser()) - { - echo 'You are using a browser.'; - } - + Returns TRUE/FALSE (boolean) if the user agent is a known web browser. + :: -.. note:: The string "Safari" in this example is an array key in the - list of browser definitions. You can find this list in - application/config/user_agents.php if you want to add new browsers or - change the stings. + if ($this->agent->is_browser('Safari')) + { + echo 'You are using Safari.'; + } + elseif ($this->agent->is_browser()) + { + echo 'You are using a browser.'; + } -$this->agent->is_mobile() -========================== + .. note:: The string "Safari" in this example is an array key in the list of browser definitions. + You can find this list in **application/config/user_agents.php** if you want to add new + browsers or change the stings. -Returns TRUE/FALSE (boolean) if the user agent is a known mobile device. + .. method:: is_mobile([$key = NULL]) -:: + :param string $key: optional mobile device name + :returns: bool - if ($this->agent->is_mobile('iphone')) - { - $this->load->view('iphone/home'); - } - elseif ($this->agent->is_mobile()) - { - $this->load->view('mobile/home'); - } - else - { - $this->load->view('web/home'); - } - + Returns TRUE/FALSE (boolean) if the user agent is a known mobile device. + :: -$this->agent->is_robot() -========================= + if ($this->agent->is_mobile('iphone')) + { + $this->load->view('iphone/home'); + } + elseif ($this->agent->is_mobile()) + { + $this->load->view('mobile/home'); + } + else + { + $this->load->view('web/home'); + } -Returns TRUE/FALSE (boolean) if the user agent is a known robot. + .. method:: is_robot([$key = NULL]) -.. note:: The user agent library only contains the most common robot - definitions. It is not a complete list of bots. There are hundreds of - them so searching for each one would not be very efficient. If you find - that some bots that commonly visit your site are missing from the list - you can add them to your application/config/user_agents.php file. + :param string $key: optional robot name + :returns: bool -$this->agent->is_referral() -============================ + Returns TRUE/FALSE (boolean) if the user agent is a known robot. -Returns TRUE/FALSE (boolean) if the user agent was referred from another -site. + .. note:: The user agent library only contains the most common robot definitions. It is not a complete list of bots. + There are hundreds of them so searching for each one would not be very efficient. If you find that some bots + that commonly visit your site are missing from the list you can add them to your + **application/config/user_agents.php** file. -$this->agent->browser() -======================= + .. method:: is_referral() -Returns a string containing the name of the web browser viewing your -site. + :returns: bool -$this->agent->version() -======================= + Returns TRUE/FALSE (boolean) if the user agent was referred from another site. -Returns a string containing the version number of the web browser -viewing your site. + .. method:: browser() -$this->agent->mobile() -====================== + :returns: string -Returns a string containing the name of the mobile device viewing your -site. + Returns a string containing the name of the web browser viewing your site. -$this->agent->robot() -===================== + .. method:: version() -Returns a string containing the name of the robot viewing your site. + :returns: string -$this->agent->platform() -======================== + Returns a string containing the version number of the web browser viewing your site. -Returns a string containing the platform viewing your site (Linux, -Windows, OS X, etc.). + .. method:: mobile() -$this->agent->referrer() -======================== + :returns: string -The referrer, if the user agent was referred from another site. -Typically you'll test for this as follows:: + Returns a string containing the name of the mobile device viewing your site. - if ($this->agent->is_referral()) - { - echo $this->agent->referrer(); - } + .. method:: robot() -$this->agent->agent_string() -============================= + :returns: string -Returns a string containing the full user agent string. Typically it -will be something like this:: + Returns a string containing the name of the robot viewing your site. - Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.0.4) Gecko/20060613 Camino/1.0.2 + .. method:: platform() -$this->agent->accept_lang() -============================ + :returns: string -Lets you determine if the user agent accepts a particular language. -Example:: + Returns a string containing the platform viewing your site (Linux, Windows, OS X, etc.). - if ($this->agent->accept_lang('en')) - { - echo 'You accept English!'; - } + .. method:: referrer() -.. note:: This function is not typically very reliable since some - browsers do not provide language info, and even among those that do, it - is not always accurate. + :returns: string -$this->agent->accept_charset() -=============================== + The referrer, if the user agent was referred from another site. Typically you'll test for this as follows:: -Lets you determine if the user agent accepts a particular character set. -Example:: + if ($this->agent->is_referral()) + { + echo $this->agent->referrer(); + } - if ($this->agent->accept_charset('utf-8')) - { - echo 'You browser supports UTF-8!'; - } + .. method:: agent_string() + + :returns: string + + Returns a string containing the full user agent string. Typically it will be something like this:: + + Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.0.4) Gecko/20060613 Camino/1.0.2 + + .. method:: accept_lang([$lang = 'en']) + + :param string $lang: language key + :returns: bool + + Lets you determine if the user agent accepts a particular language. Example:: + + if ($this->agent->accept_lang('en')) + { + echo 'You accept English!'; + } + + .. note:: This method is not typically very reliable since some browsers do not provide language info, + and even among those that do, it is not always accurate. + + .. method:: languages() + + :returns: array + + Returns an array of languages supported by the user agent. + + .. method:: accept_charset([$charset = 'utf-8']) + + :param string $charset: character set + :returns: bool + + Lets you determine if the user agent accepts a particular character set. Example:: + + if ($this->agent->accept_charset('utf-8')) + { + echo 'You browser supports UTF-8!'; + } + + .. note:: This method is not typically very reliable since some browsers do not provide character-set info, + and even among those that do, it is not always accurate. + + .. method:: charsets() + + :returns: array -.. note:: This function is not typically very reliable since some - browsers do not provide character-set info, and even among those that - do, it is not always accurate. + Returns an array of character sets accepted by the user agent. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From cc231fe7dc8d61e4d4f5d6a054e6131ea0659909 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 23 Sep 2013 16:46:52 +0300 Subject: [ci skip] Update the Typography library docs --- user_guide_src/source/libraries/typography.rst | 137 ++++++++++++------------- 1 file changed, 68 insertions(+), 69 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/typography.rst b/user_guide_src/source/libraries/typography.rst index db3f227be..8dab053ba 100644 --- a/user_guide_src/source/libraries/typography.rst +++ b/user_guide_src/source/libraries/typography.rst @@ -2,104 +2,103 @@ Typography Class ################ -The Typography Class provides functions that help you format text. +The Typography Class provides methods that help you format text. + +.. content:: + :local: + +.. raw:: html + +
+ +************************** +Using the Typography Class +************************** Initializing the Class ====================== Like most other classes in CodeIgniter, the Typography class is -initialized in your controller using the $this->load->library function:: +initialized in your controller using the ``$this->load->library()`` method:: $this->load->library('typography'); -Once loaded, the Typography library object will be available using: -$this->typography +Once loaded, the Typography library object will be available using:: -auto_typography() -================== + $this->typography -Formats text so that it is semantically and typographically correct -HTML. Takes a string as input and returns it with the following -formatting: +*************** +Class Reference +*************** -- Surrounds paragraphs within

(looks for double line breaks to - identify paragraphs). -- Single line breaks are converted to
, except those that appear - within
 tags.
--  Block level elements, like 
tags, are not wrapped within - paragraphs, but their contained text is if it contains paragraphs. -- Quotes are converted to correctly facing curly quote entities, except - those that appear within tags. -- Apostrophes are converted to curly apostrophe entities. -- Double dashes (either like -- this or like--this) are converted to - em—dashes. -- Three consecutive periods either preceding or following a word are - converted to ellipsis… -- Double spaces following sentences are converted to non-breaking - spaces to mimic double spacing. +.. class:: CI_Typography -Usage example:: + .. attribute:: $protect_braced_quotes = FALSE - $string = $this->typography->auto_typography($string); + When using the Typography library in conjunction with the :doc:`Template Parser library <../parser>` + it can often be desirable to protect single and double quotes within curly braces. + To enable this, set the ``protect_braced_quotes`` class property to TRUE. -Parameters ----------- + Usage example:: -There is one optional parameters that determines whether the parser -should reduce more then two consecutive line breaks down to two. Use -boolean TRUE or FALSE. + $this->load->library('typography'); + $this->typography->protect_braced_quotes = TRUE; -By default the parser does not reduce line breaks. In other words, if no -parameters are submitted, it is the same as doing this:: + .. method auto_typography($str[, $reduce_linebreaks = FALSE]) - $string = $this->typography->auto_typography($string, FALSE); + :param string $str: input string + :param bool $reduce_linebreaks: whether to reduce consequitive linebreaks + :returns: string -.. note:: Typographic formatting can be processor intensive, - particularly if you have a lot of content being formatted. If you choose - to use this function you may want to consider :doc:`caching <../general/caching>` - your pages. + Formats text so that it is semantically and typographically correct HTML. + Takes a string as input and returns it with the following formatting: -format_characters() -==================== + - Surrounds paragraphs within

(looks for double line breaks to identify paragraphs). + - Single line breaks are converted to
, except those that appear within
 tags.
+		 -  Block level elements, like 
tags, are not wrapped within paragraphs, but their contained text is if it contains paragraphs. + - Quotes are converted to correctly facing curly quote entities, except those that appear within tags. + - Apostrophes are converted to curly apostrophe entities. + - Double dashes (either like -- this or like--this) are converted to em—dashes. + - Three consecutive periods either preceding or following a word are converted to ellipsis (…). + - Double spaces following sentences are converted to non-breaking spaces to mimic double spacing. -This function is similar to the auto_typography function above, except -that it only does character conversion: + Usage example:: -- Quotes are converted to correctly facing curly quote entities, except - those that appear within tags. -- Apostrophes are converted to curly apostrophe entities. -- Double dashes (either like -- this or like--this) are converted to - em—dashes. -- Three consecutive periods either preceding or following a word are - converted to ellipsis… -- Double spaces following sentences are converted to non-breaking - spaces to mimic double spacing. + $string = $this->typography->auto_typography($string); -Usage example:: + There is one optional parameter that determines whether the parser should reduce more then two consecutive line breaks down to two. + Pass boolean TRUE to enable reducing line breaks:: - $string = $this->typography->format_characters($string); + $string = $this->typography->auto_typography($string, TRUE); -nl2br_except_pre() -==================== + .. note:: Typographic formatting can be processor intensive, particularly if you have a lot of content being formatted. + If you choose to use this method you may want to consider :doc:`caching <../general/caching>` your pages. -Converts newlines to
tags unless they appear within
 tags.
-This function is identical to the native PHP nl2br() function, except
-that it ignores 
 tags.
+	.. method:: format_characters($str)
 
-Usage example::
+		:param string $str: input string
+		:returns: string
 
-	$string = $this->typography->nl2br_except_pre($string);
+		This method is similar to ``auto_typography()`` above, except that it only does character conversion:
 
-protect_braced_quotes
-=======================
+		 -  Quotes are converted to correctly facing curly quote entities, except those that appear within tags.
+		 -  Apostrophes are converted to curly apostrophe entities.
+		 -  Double dashes (either like -- this or like--this) are converted to em—dashes.
+		 -  Three consecutive periods either preceding or following a word are converted to ellipsis (…).
+		 -  Double spaces following sentences are converted to non-breaking spaces to mimic double spacing.
 
-When using the Typography library in conjunction with the Template
-Parser library it can often be desirable to protect single and double
-quotes within curly braces. To enable this, set the
-protect_braced_quotes class property to TRUE.
+		Usage example::
 
-Usage example::
+			$string = $this->typography->format_characters($string);
 
-	$this->load->library('typography');
-	$this->typography->protect_braced_quotes = TRUE;
+	.. method:: nl2br_except_pre($str)
+
+		:param string $str: input string
+		:returns: string
+
+		Converts newlines to 
tags unless they appear within
 tags.
+		This method is identical to the native PHP :php:func:`nl2br()` function, except that it ignores 
 tags.
+
+		Usage example::
 
+			$string = $this->typography->nl2br_except_pre($string);
\ No newline at end of file
-- 
cgit v1.2.3-24-g4f1b


From 9ea31e823af8cfe73154d4e262331623a2f1ded5 Mon Sep 17 00:00:00 2001
From: Andrey Andreev 
Date: Mon, 23 Sep 2013 17:20:56 +0300
Subject: [ci skip] Update the Trackback library docs

---
 user_guide_src/source/libraries/trackback.rst | 215 ++++++++++++++++++++------
 1 file changed, 171 insertions(+), 44 deletions(-)

(limited to 'user_guide_src/source/libraries')

diff --git a/user_guide_src/source/libraries/trackback.rst b/user_guide_src/source/libraries/trackback.rst
index f9e0df882..72958934c 100644
--- a/user_guide_src/source/libraries/trackback.rst
+++ b/user_guide_src/source/libraries/trackback.rst
@@ -8,16 +8,28 @@ receive Trackback data.
 If you are not familiar with Trackbacks you'll find more information
 `here `_.
 
+.. content::
+	:local:
+
+.. raw:: html
+
+	
+ +************************* +Using the Trackback Class +************************* + Initializing the Class ====================== Like most other classes in CodeIgniter, the Trackback class is -initialized in your controller using the $this->load->library function:: +initialized in your controller using the ``$this->load->library()`` method:: $this->load->library('trackback'); -Once loaded, the Trackback library object will be available using: -$this->trackback +Once loaded, the Trackback library object will be available using:: + + $this->trackback Sending Trackbacks ================== @@ -28,38 +40,36 @@ similar to this example:: $this->load->library('trackback'); $tb_data = array( - 'ping_url' => 'http://example.com/trackback/456', - 'url' => 'http://www.my-example.com/blog/entry/123', - 'title' => 'The Title of My Entry', - 'excerpt' => 'The entry content.', - 'blog_name' => 'My Blog Name', - 'charset' => 'utf-8' - ); + 'ping_url' => 'http://example.com/trackback/456', + 'url' => 'http://www.my-example.com/blog/entry/123', + 'title' => 'The Title of My Entry', + 'excerpt' => 'The entry content.', + 'blog_name' => 'My Blog Name', + 'charset' => 'utf-8' + ); if ( ! $this->trackback->send($tb_data)) { - echo $this->trackback->display_errors(); + echo $this->trackback->display_errors(); } else { - echo 'Trackback was sent!'; + echo 'Trackback was sent!'; } Description of array data: - **ping_url** - The URL of the site you are sending the Trackback to. - You can send Trackbacks to multiple URLs by separating each URL with - a comma. + You can send Trackbacks to multiple URLs by separating each URL with a comma. - **url** - The URL to YOUR site where the weblog entry can be seen. - **title** - The title of your weblog entry. -- **excerpt** - The content of your weblog entry. Note: the Trackback - class will automatically send only the first 500 characters of your - entry. It will also strip all HTML. +- **excerpt** - The content of your weblog entry. + .. note:: the Trackback class will automatically send only the first 500 characters of your + entry. It will also strip all HTML. - **blog_name** - The name of your weblog. -- **charset** - The character encoding your weblog is written in. If - omitted, UTF-8 will be used. +- **charset** - The character encoding your weblog is written in. If omitted, UTF-8 will be used. -The Trackback sending function returns TRUE/FALSE (boolean) on success +The Trackback sending method returns TRUE/FALSE (boolean) on success or failure. If it fails, you can retrieve the error message using:: $this->trackback->display_errors(); @@ -107,16 +117,16 @@ Before you can receive Trackbacks you must create a table in which to store them. Here is a basic prototype for such a table:: CREATE TABLE trackbacks ( - tb_id int(10) unsigned NOT NULL auto_increment, - entry_id int(10) unsigned NOT NULL default 0, - url varchar(200) NOT NULL, - title varchar(100) NOT NULL, - excerpt text NOT NULL, - blog_name varchar(100) NOT NULL, - tb_date int(10) NOT NULL, - ip_address varchar(45) NOT NULL, - PRIMARY KEY `tb_id` (`tb_id`), - KEY `entry_id` (`entry_id`) + tb_id int(10) unsigned NOT NULL auto_increment, + entry_id int(10) unsigned NOT NULL default 0, + url varchar(200) NOT NULL, + title varchar(100) NOT NULL, + excerpt text NOT NULL, + blog_name varchar(100) NOT NULL, + tb_date int(10) NOT NULL, + ip_address varchar(45) NOT NULL, + PRIMARY KEY `tb_id` (`tb_id`), + KEY `entry_id` (`entry_id`) ); The Trackback specification only requires four pieces of information to @@ -129,33 +139,31 @@ Processing a Trackback Here is an example showing how you will receive and process a Trackback. The following code is intended for use within the controller function -where you expect to receive Trackbacks. - -:: +where you expect to receive Trackbacks.:: $this->load->library('trackback'); $this->load->database(); if ($this->uri->segment(3) == FALSE) { - $this->trackback->send_error("Unable to determine the entry ID"); + $this->trackback->send_error('Unable to determine the entry ID'); } if ( ! $this->trackback->receive()) { - $this->trackback->send_error("The Trackback did not contain valid data"); + $this->trackback->send_error('The Trackback did not contain valid data'); } $data = array( - 'tb_id' => '', - 'entry_id' => $this->uri->segment(3), - 'url' => $this->trackback->data('url'), - 'title' => $this->trackback->data('title'), - 'excerpt' => $this->trackback->data('excerpt'), - 'blog_name' => $this->trackback->data('blog_name'), - 'tb_date' => time(), - 'ip_address' => $this->input->ip_address() - ); + 'tb_id' => '', + 'entry_id' => $this->uri->segment(3), + 'url' => $this->trackback->data('url'), + 'title' => $this->trackback->data('title'), + 'excerpt' => $this->trackback->data('excerpt'), + 'blog_name' => $this->trackback->data('blog_name'), + 'tb_date' => time(), + 'ip_address' => $this->input->ip_address() + ); $sql = $this->db->insert_string('trackbacks', $data); $this->db->query($sql); @@ -199,3 +207,122 @@ message using:: .. note:: The above code contains no data validation, which you are encouraged to add. + +*************** +Class Reference +*************** + +.. class:: CI_Trackback + + .. attribute:: $data = array('url' => '', 'title' => '', 'excerpt' => '', 'blog_name' => '', 'charset' => '') + + Trackback data array. + + .. attribute:: $convert_ascii = TRUE + + Whether to convert high ASCII and MS Word characters to HTML entities. + + .. method:: send($tb_data) + + :param array $tb_data: trackback data + :returns: bool + + Send trackback. + + .. method:: receive() + + :returns: bool + + This method simply validates the incoming TB data, returning TRUE on success and FALSE on failure. + If the data is valid it is set to the ``$this->data`` array so that it can be inserted into a database. + + .. method:: send_error([$message = 'Incomplete information') + + :param string $message: error message + :returns: void + + Responses to a trackback request with an error message. + + .. note:: This method will terminate script execution. + + .. method:: send_success() + + :returns: void + + Responses to a trackback request with a success message. + + .. note:: This method will terminate script execution. + + .. method:: data($item) + + :param string $item: data key + :returns: string + + Returns a single item from the reponse data array. + + .. method:: process($url, $data) + + :param string $url: target url + :param string $data: raw post data + :returns: bool + + Opens a socket connection and passes the data to the server, returning TRUE on success and FALSE on failure. + + .. method:: extract_urls($urls) + + :param string $urls: comma-separated url list + :returns: string + + This method lets multiple trackbacks to be sent. It takes a string of URLs (separated by comma or space) and puts each URL into an array. + + .. method:: validate_url(&$url) + + :param string $url: trackback url + :returns: void + + Simply adds the *http://* prefix it it's not already present in the URL. + + .. method:: get_id($url) + + :param string $url: trackback url + :returns: string + + Find and return a trackback URL's ID or FALSE on failure. + + .. method:: convert_xml($str) + + :param string $str: input string + :returns: string + + Converts reserved XML characters to entities. + + .. method:: limit_characters($str[, $n = 500[, $end_char = '…']]) + + :param string $str: input string + :param int $n: max characters number + :param string $end_char: character to put at end of string + :returns: string + + Limits the string based on the character count. Will preserve complete words. + + .. method:: convert_ascii($str) + + :param string $str: input string + :returns: string + + Converts high ASCII text and MS Word special characterss to HTML entities. + + .. method:: set_error($msg) + + :param string $msg: error message + :returns: void + + Set an log an error message. + + .. method:: display_errors([$open = '

'[, $close = '

']]) + + :param string $open: open tag + :param string $close: close tag + :returns: string + + Returns error messages formatted in HTML or an empty string if there are no errors. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 0ee2a6333a8b987fd85c6bd6018fdd95906277ac Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 23 Sep 2013 18:55:38 +0300 Subject: [ci skip] Update the Table library docs --- user_guide_src/source/libraries/table.rst | 272 ++++++++++++++++-------------- 1 file changed, 143 insertions(+), 129 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/table.rst b/user_guide_src/source/libraries/table.rst index 6a808abc2..25927800e 100644 --- a/user_guide_src/source/libraries/table.rst +++ b/user_guide_src/source/libraries/table.rst @@ -5,48 +5,60 @@ HTML Table Class The Table Class provides functions that enable you to auto-generate HTML tables from arrays or database result sets. +.. content:: + :local: + +.. raw:: html + +
+ +********************* +Using the Table Class +********************* + Initializing the Class ====================== Like most other classes in CodeIgniter, the Table class is initialized -in your controller using the $this->load->library function:: +in your controller using the ``$this->load->library()`` method:: $this->load->library('table'); -Once loaded, the Table library object will be available using: -$this->table +Once loaded, the Table library object will be available using:: + + $this->table Examples ======== Here is an example showing how you can create a table from a multi-dimensional array. Note that the first array index will become the -table heading (or you can set your own headings using the set_heading() -function described in the function reference below). +table heading (or you can set your own headings using the ``set_heading()`` +method described in the function reference below). :: $this->load->library('table'); $data = array( - array('Name', 'Color', 'Size'), - array('Fred', 'Blue', 'Small'), - array('Mary', 'Red', 'Large'), - array('John', 'Green', 'Medium') - ); + array('Name', 'Color', 'Size'), + array('Fred', 'Blue', 'Small'), + array('Mary', 'Red', 'Large'), + array('John', 'Green', 'Medium') + ); echo $this->table->generate($data); Here is an example of a table created from a database query result. The table class will automatically generate the headings based on the table -names (or you can set your own headings using the set_heading() -function described in the function reference below). +names (or you can set your own headings using the ``set_heading()`` +method described in the class reference below). :: $this->load->library('table'); - $query = $this->db->query("SELECT * FROM my_table"); + $query = $this->db->query('SELECT * FROM my_table'); echo $this->table->generate($query); @@ -82,28 +94,28 @@ Changing the Look of Your Table The Table Class permits you to set a table template with which you can specify the design of your layout. Here is the template prototype:: - $tmpl = array ( - 'table_open' => '', + $template = array( + 'table_open' => '
', - 'heading_row_start' => '', - 'heading_row_end' => '', - 'heading_cell_start' => '', + 'heading_row_start' => '', + 'heading_row_end' => '', + 'heading_cell_start' => '', - 'row_start' => '', - 'row_end' => '', - 'cell_start' => '', + 'row_start' => '', + 'row_end' => '', + 'cell_start' => '', - 'row_alt_start' => '', - 'row_alt_end' => '', - 'cell_alt_start' => '', + 'row_alt_start' => '', + 'row_alt_end' => '', + 'cell_alt_start' => '', - 'table_close' => '
', - 'heading_cell_end' => '
', + 'heading_cell_end' => '
', - 'cell_end' => '
', + 'cell_end' => '
', - 'cell_alt_end' => '
', + 'cell_alt_end' => '
' - ); + 'table_close' => '' + ); - $this->table->set_template($tmpl); + $this->table->set_template($template); .. note:: You'll notice there are two sets of "row" blocks in the template. These permit you to create alternating row colors or design @@ -113,157 +125,159 @@ You are NOT required to submit a complete template. If you only need to change parts of the layout you can simply submit those elements. In this example, only the table opening tag is being changed:: - $tmpl = array ( 'table_open' => '' ); + $template = array( + 'table_open' => '
' + ); - $this->table->set_template($tmpl); + $this->table->set_template($template); You can also set defaults for these in a config file. -****************** -Function Reference -****************** +*************** +Class Reference +*************** -$this->table->generate() -======================== +.. class:: CI_Table -Returns a string containing the generated table. Accepts an optional -parameter which can be an array or a database result object. + .. attribute:: $function = FALSE -$this->table->set_caption() -============================ + Allows you to specify a native PHP function or a valid function array object to be applied to all cell data. + :: -Permits you to add a caption to the table. + $this->load->library('table'); -:: + $this->table->set_heading('Name', 'Color', 'Size'); + $this->table->add_row('Fred', 'Blue', 'Small'); - $this->table->set_caption('Colors'); + $this->table->function = 'htmlspecialchars'; + echo $this->table->generate(); -$this->table->set_heading() -============================ + In the above example, all cell data would be ran through PHP's :php:func:`htmlspecialchars()` function, resulting in:: -Permits you to set the table heading. You can submit an array or -discrete params:: + - $this->table->set_heading('Name', 'Color', 'Size'); + .. method:: generate([$table_data = NULL]) -:: + :param mixed $table_data: data to populate the table rows with + :returns: string - $this->table->set_heading(array('Name', 'Color', 'Size')); + Returns a string containing the generated table. Accepts an optional parameter which can be an array or a database result object. -$this->table->add_row() -======================== + .. method:: set_caption($caption) -Permits you to add a row to your table. You can submit an array or -discrete params:: + :param string $caption: table caption + :returns: void - $this->table->add_row('Blue', 'Red', 'Green'); + Permits you to add a caption to the table. + :: -:: + $this->table->set_caption('Colors'); - $this->table->add_row(array('Blue', 'Red', 'Green')); + .. method:: set_heading([$args = array()[, ...]]) -If you would like to set an individual cell's tag attributes, you can -use an associative array for that cell. The associative key 'data' -defines the cell's data. Any other key => val pairs are added as -key='val' attributes to the tag:: + :param mixed $args: an array or multiple strings containing the table column titles + :returns: void - $cell = array('data' => 'Blue', 'class' => 'highlight', 'colspan' => 2); - $this->table->add_row($cell, 'Red', 'Green'); + Permits you to set the table heading. You can submit an array or discrete params:: - // generates - // + $this->table->set_heading('Name', 'Color', 'Size'); -$this->table->make_columns() -============================= + $this->table->set_heading(array('Name', 'Color', 'Size')); -This function takes a one-dimensional array as input and creates a -multi-dimensional array with a depth equal to the number of columns -desired. This allows a single array with many elements to be displayed -in a table that has a fixed column count. Consider this example:: + .. method:: add_row([$args = array()[, ...]]) - $list = array('one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve'); + :param mixed $args: an array or multiple strings containing the row values + :returns: void - $new_list = $this->table->make_columns($list, 3); + Permits you to add a row to your table. You can submit an array or discrete params:: - $this->table->generate($new_list); + $this->table->add_row('Blue', 'Red', 'Green'); - // Generates a table with this prototype + $this->table->add_row(array('Blue', 'Red', 'Green')); -
Fred<strong>Blue</strong>SmallBlueRedGreen
- - - - - - - - -
onetwothree
fourfivesix
seveneightnine
teneleventwelve
+ If you would like to set an individual cell's tag attributes, you can use an associative array for that cell. + The associative key **data** defines the cell's data. Any other key => val pairs are added as key='val' attributes to the tag:: -$this->table->set_template() -============================= + $cell = array('data' => 'Blue', 'class' => 'highlight', 'colspan' => 2); + $this->table->add_row($cell, 'Red', 'Green'); -Permits you to set your template. You can submit a full or partial -template. + // generates + // BlueRedGreen -:: + .. method:: make_columns([$array = array()[, $col_limit = 0]]) - $tmpl = array ( 'table_open' => '' ); + :param array $array: an array containing multiple rows' data + :param int $col_limit: count of columns in the table + :returns: array - $this->table->set_template($tmpl); + This method takes a one-dimensional array as input and creates a multi-dimensional array with a depth equal to the number of columns desired. + This allows a single array with many elements to be displayed in a table that has a fixed column count. Consider this example:: -$this->table->set_empty() -========================== + $list = array('one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve'); -Let's you set a default value for use in any table cells that are empty. -You might, for example, set a non-breaking space:: + $new_list = $this->table->make_columns($list, 3); - $this->table->set_empty(" "); + $this->table->generate($new_list); -$this->table->clear() -===================== + // Generates a table with this prototype -Lets you clear the table heading and row data. If you need to show -multiple tables with different data you should to call this function -after each table has been generated to empty the previous table -information. Example:: +
+ + + + + + + + +
onetwothree
fourfivesix
seveneightnine
teneleventwelve
- $this->load->library('table'); - $this->table->set_heading('Name', 'Color', 'Size'); - $this->table->add_row('Fred', 'Blue', 'Small'); - $this->table->add_row('Mary', 'Red', 'Large'); - $this->table->add_row('John', 'Green', 'Medium'); + .. method:: set_template($template) - echo $this->table->generate(); + :param array $template: associative array containing template values + :returns: bool - $this->table->clear(); + Permits you to set your template. You can submit a full or partial template. + :: - $this->table->set_heading('Name', 'Day', 'Delivery'); - $this->table->add_row('Fred', 'Wednesday', 'Express'); - $this->table->add_row('Mary', 'Monday', 'Air'); - $this->table->add_row('John', 'Saturday', 'Overnight'); + $template = array( + 'table_open' => '' + ); - echo $this->table->generate(); + $this->table->set_template($template); -$this->table->function -====================== + .. method:: set_empty($value) -Allows you to specify a native PHP function or a valid function array -object to be applied to all cell data. + :param mixed $value: value to put in empty cells + :returns: void -:: + Lets you set a default value for use in any table cells that are empty. + You might, for example, set a non-breaking space:: - $this->load->library('table'); + $this->table->set_empty(" "); - $this->table->set_heading('Name', 'Color', 'Size'); - $this->table->add_row('Fred', 'Blue', 'Small'); + .. method:: clear() - $this->table->function = 'htmlspecialchars'; - echo $this->table->generate(); + :returns: void + + Lets you clear the table heading and row data. If you need to show multiple tables with different data you should to call this method + after each table has been generated to clear the previous table information. Example:: + + $this->load->library('table'); + + $this->table->set_heading('Name', 'Color', 'Size'); + $this->table->add_row('Fred', 'Blue', 'Small'); + $this->table->add_row('Mary', 'Red', 'Large'); + $this->table->add_row('John', 'Green', 'Medium'); + + echo $this->table->generate(); -In the above example, all cell data would be ran through PHP's -htmlspecialchars() function, resulting in:: + $this->table->clear(); - + $this->table->set_heading('Name', 'Day', 'Delivery'); + $this->table->add_row('Fred', 'Wednesday', 'Express'); + $this->table->add_row('Mary', 'Monday', 'Air'); + $this->table->add_row('John', 'Saturday', 'Overnight'); + echo $this->table->generate(); -- cgit v1.2.3-24-g4f1b From 5d4131b2d8a156e0793a185987292c35a898e332 Mon Sep 17 00:00:00 2001 From: Michael Date: Mon, 30 Sep 2013 12:22:29 +0300 Subject: Update the Session library docs Signed-off-by: Michael --- user_guide_src/source/libraries/sessions.rst | 65 +++++++++++++++------------- 1 file changed, 34 insertions(+), 31 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index 36c7c1d32..51bcc8022 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -21,11 +21,12 @@ initializing the class will cause it to read, create, and update sessions. To initialize the Session class manually in your controller constructor, -use the $this->load->driver function:: +use the ``$this->load->driver`` function:: $this->load->driver('session'); -Once loaded, the Sessions library object will be available using: +Once loaded, the Sessions library object will be available using:: + $this->session How do Sessions work? @@ -49,23 +50,23 @@ What is Session Data? A *session*, as far as CodeIgniter is concerned, is simply an array containing the following information: -- The user's unique Session ID (this is a statistically random string +* The user's unique Session ID (this is a statistically random string with very strong entropy, hashed with MD5 for portability, and regenerated (by default) every five minutes) -- The user's IP Address -- The user's User Agent data (the first 120 characters of the browser +* The user's IP Address +* The user's User Agent data (the first 120 characters of the browser data string) -- The "last activity" time stamp. +* The "last activity" time stamp. The above data is stored in a cookie as a serialized array with this prototype:: [array] ( - 'session_id' => random hash, - 'ip_address' => 'string - user IP address', - 'user_agent' => 'string - user agent data', - 'last_activity' => timestamp + 'session_id' => random hash, + 'ip_address' => 'string - user IP address', + 'user_agent' => 'string - user agent data', + 'last_activity' => timestamp ) .. note:: Sessions are only updated every five minutes by default to @@ -112,21 +113,21 @@ Where $array is an associative array containing your new data. Here's an example:: $newdata = array( - 'username' => 'johndoe', - 'email' => 'johndoe@some-site.com', - 'logged_in' => TRUE - ); + 'username' => 'johndoe', + 'email' => 'johndoe@some-site.com', + 'logged_in' => TRUE + ); $this->session->set_userdata($newdata); -If you want to add userdata one value at a time, set_userdata() also +If you want to add userdata one value at a time, ``set_userdata()`` also supports this syntax. :: $this->session->set_userdata('some_name', 'some_value'); -If you want to verify that a userdata value exists, call has_userdata(). +If you want to verify that a userdata value exists, call ``has_userdata()``. :: @@ -143,10 +144,10 @@ And returns an associative array like the following:: Array ( - [session_id] => 4a5a5dca22728fb0a84364eeb405b601 - [ip_address] => 127.0.0.1 - [user_agent] => Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_7; - [last_activity] => 1303142623 + [session_id] => 4a5a5dca22728fb0a84364eeb405b601 + [ip_address] => 127.0.0.1 + [user_agent] => Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_7; + [last_activity] => 1303142623 ) Removing Session Data @@ -185,8 +186,8 @@ To add flashdata:: $this->session->set_flashdata('item', 'value'); -You can also pass an array to set_flashdata(), in the same manner as -set_userdata(). +You can also pass an array to ``set_flashdata()``, in the same manner as +``set_userdata()``. To read a flashdata variable:: @@ -198,7 +199,7 @@ An array of all flashdata can be retrieved as follows:: If you find that you need to preserve a flashdata variable through an -additional request, you can do so using the keep_flashdata() function. +additional request, you can do so using the ``keep_flashdata()`` function. You can either pass a single item or an array of flashdata items to keep. :: @@ -206,6 +207,8 @@ You can either pass a single item or an array of flashdata items to keep. $this->session->keep_flashdata('item'); $this->session->keep_flashdata(array('item1', 'item2', 'item3')); +.. note:: The function will return NULL if the item cannot be found. + Tempdata ======== @@ -219,7 +222,7 @@ To add tempdata:: $this->session->set_tempdata('item', 'value', $expire); -You can also pass an array to set_tempdata():: +You can also pass an array to ``set_tempdata()``:: $tempdata = array('newuser' => TRUE, 'message' => 'Thanks for joining!'); @@ -233,7 +236,7 @@ To read a tempdata variable:: $this->session->tempdata('item'); If you need to remove a tempdata value before it expires, -use unset_tempdata():: +use ``unset_tempdata()``:: $this->session->unset_tempdata('item'); @@ -246,7 +249,7 @@ To clear the current session:: .. note:: This function should be the last one called, and even flash variables will no longer be available. If you only want some items - destroyed and not all, use unset_userdata(). + destroyed and not all, use ``unset_userdata()``. Session Preferences =================== @@ -303,7 +306,7 @@ installed, and `Custom Drivers`_ may also be installed by the user. Typically, only one driver will be used at a time, but CodeIgniter does support loading multiple drivers. If a specific valid driver is called, it will be automatically loaded. Or, an additional driver may be explicitly -loaded by calling load_driver():: +loaded by ``calling load_driver()``:: $this->session->load_driver('native'); @@ -328,7 +331,7 @@ the call to unset the *native* 'foo' value. The drivers maintain independent sets of values, regardless of key names. A specific driver may also be explicitly selected for use by pursuant -methods with the select_driver() call:: +methods with the ``select_driver()`` call:: $this->session->select_driver('native'); @@ -422,7 +425,7 @@ You may also :doc:`create your own <../general/creating_drivers>` custom session drivers. A session driver basically manages an array of name/value pairs with some sort of storage mechanism. -To make a new driver, extend CI_Session_driver. Overload the initialize() +To make a new driver, extend CI_Session_driver. Overload the ``initialize()`` method and read or create session data. Then implement a save handler to write changed data to storage (sess_save), a destroy handler to remove deleted data (sess_destroy), a regenerate handler to make a new session ID @@ -456,13 +459,13 @@ Your initial class might look like:: } } -Notice that get_userdata() returns a reference so the parent library is +Notice that ``get_userdata()`` returns a reference so the parent library is accessing the same array the driver object is using. This saves memory and avoids synchronization issues during usage. Put your driver in the libraries/Session/drivers folder anywhere in your package paths. This includes the application directory, the system directory, -or any path you add with $CI->load->add_package_path(). Your driver must be +or any path you add with ``$CI->load->add_package_path()``. Your driver must be named CI_Session_, and your filename must be Session_.php, preferably also capitalized, such as:: -- cgit v1.2.3-24-g4f1b From 1c7438f08bf289c08d5d1c466316850831b9b0ed Mon Sep 17 00:00:00 2001 From: Michael Date: Sun, 6 Oct 2013 15:21:21 +0300 Subject: Added class reference to the session docs Signed-off-by: Michael --- user_guide_src/source/libraries/sessions.rst | 193 ++++++++++++++++++++++++++- 1 file changed, 189 insertions(+), 4 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index 51bcc8022..3dc067a70 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -50,13 +50,13 @@ What is Session Data? A *session*, as far as CodeIgniter is concerned, is simply an array containing the following information: -* The user's unique Session ID (this is a statistically random string +- The user's unique Session ID (this is a statistically random string with very strong entropy, hashed with MD5 for portability, and regenerated (by default) every five minutes) -* The user's IP Address -* The user's User Agent data (the first 120 characters of the browser +- The user's IP Address +- The user's User Agent data (the first 120 characters of the browser data string) -* The "last activity" time stamp. +- The "last activity" time stamp. The above data is stored in a cookie as a serialized array with this prototype:: @@ -486,3 +486,188 @@ without making it the initially loaded driver, set 'sess_valid_drivers' in your config.php file to an array including your driver name:: $config['sess_valid_drivers'] = array('sess_driver'); + + + +*************** +Class Reference +*************** + +.. class:: CI_Session + +Userdata +-------- + + .. method:: set_userdata($newdata = array(), $newval) + + :param mixed $newdata: Item name or array of items + :param mixed $newval: Item value or empty string (not required if $newdata is array) + :returns: void + + Sets items into session example usages:: + + $this->session->set_userdata('user', 'example@example.com'); + // adds item user with value example@example.com to the session + + $this->session->set_userdata(array('user'=>'example@example.com')); + // does the same as the above example - adds item user with value example@example.com to the session + + .. method:: userdata($item) + + :param string $item: name of session item + :returns: string + + Returns a string containing the value of the passed item or NULL if the item is not found. Example:: + + $this->session->userdata('user'); + //returns example@example.com considering the set_userdata example. + + .. method:: unset_userdata($item) + + :param mixed $item: name of item or array of items + :returns: void + + Unsets previously setted items from the session. Example:: + + $this->session->unset_userdata('user'); + //unsets 'user' from session data. + + $this->session->unset_userdata(array('user', 'useremail')); + //unsets both 'user' nad 'useremail' from the session data. + + .. method:: has_userdata($item) + + :param string $item: name of item + :returns: bool + + Checks if an item exists in the session. + + .. method:: all_userdata() + + :returns: array + + Retruns array of userdata session items + + + +Flashdata +--------- +.. note:: the flashdata items are available only one server request + + .. method:: set_flashdata($newdata = array(), $newval) + + :param mixed $newdata: Item name or array of items + :param mixed $newval: Item value or empty string (not required if $newdata is array) + :returns: void + + Sets items into session flashdata example usages:: + + $this->session->set_flashdata('message', 'Test message.'); + // adds item 'message' with value 'Test message.' to the session flashdata + + $this->session->set_flashdata(array('message'=>'Test message.')); + // does the same as the above example - adds item 'message' with value 'Test message.' + to the session flashdata + + .. method:: flashdata($item) + + :param string $item: name of session item + :returns: string + + Returns a string containing the value of the passed item or NULL if the item is not found. Example:: + + $this->session->flashdata('message'); + //returns 'Test message.' considering the set_flashdata example. + + .. method:: has_flashdata($item) + + :param string $item: name of item + :returns: bool + + Checks if an item exists in the session flashdata. + + .. method:: all_flashdata() + + :returns: array + + Retruns array of flashdata session items + + .. method:: keep_flashdata($item) + + :param mixed $item: name of item or array of flashdata items + :returns: void + + Keeps items into flashdata for one more request + + +Tempdata +-------- + + .. method:: set_tempdata($newdata = array(), $newval, $expires) + + :param mixed $newdata: Item name or array of items + :param string $newval: Item value or empty string (not required if $newdata is array) + :param int $expires: lifetime in seconds (0 for default) + :returns: void + + Sets items into session tempdata example:: + + $this->session->set_tempdata('message', 'Test message.', '60'); + // adds item 'message' with value 'Test message.' to the session tempdata for 60 seconds + + $this->session->set_tempdata(array('message'=>'Test message.')); + // does the same as the above example - adds item 'message' with value 'Test message.' + to the session tempdata for the default value of + + .. method:: tempdata($item) + + :param string $item: name of tempdata item + :returns: string + + Returns a string containing the value of the passed item or NULL if the item is not found. Example:: + + $this->session->tempdata('message'); + //returns 'Test message.' considering the set_tempdata example. + + .. method:: unset_tempdata($item) + + :param mixed $item: name of item or array of items + :returns: void + + Unsets previously setted items from the tempdata. Example:: + + $this->session->unset_tempdata('user'); + //unsets 'user' from tempdata. + + $this->session->unset_tempdata(array('user', 'useremail')); + //unsets both 'user' nad 'useremail' from the tempdata. + +Session +------- + + .. method:: sess_destroy() + + Destroys current session + .. note:: This function should be the last one called, and even flash variables will no longer be available. + If you only want some items destroyed and not all, use ``unset_userdata()``. + + .. method:: sess_regenerate($destroy) + + :param bool $destroy: Destroy session data flag (default: false) + :returns: void + + Regenerate the current session data + + .. method:: load_driver($driver) + + :param string $driver: Driver name + :returns: object Loaded driver object + + Loads a session storage driver + + .. method:: select_driver($driver) + + :param string $driver: Driver name + :returns: void + + Selects default session storage driver. -- cgit v1.2.3-24-g4f1b From e0a631c3353ea26483e3958306fb2b53d7558a21 Mon Sep 17 00:00:00 2001 From: Michael Date: Sun, 20 Oct 2013 10:40:51 +0300 Subject: refactored the class reference in session.rst to properly reflect the session class Signed-off-by: Michael --- user_guide_src/source/libraries/sessions.rst | 145 +++++++++++---------------- 1 file changed, 61 insertions(+), 84 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index 3dc067a70..cab7669ae 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -495,22 +495,32 @@ Class Reference .. class:: CI_Session -Userdata --------- + .. method:: load_driver($driver) - .. method:: set_userdata($newdata = array(), $newval) + :param string $driver: Driver name + :returns: object Loaded driver object - :param mixed $newdata: Item name or array of items - :param mixed $newval: Item value or empty string (not required if $newdata is array) + Loads a session storage driver + + .. method:: select_driver($driver) + + :param string $driver: Driver name :returns: void - Sets items into session example usages:: + Selects default session storage driver. - $this->session->set_userdata('user', 'example@example.com'); - // adds item user with value example@example.com to the session + .. method:: sess_destroy() - $this->session->set_userdata(array('user'=>'example@example.com')); - // does the same as the above example - adds item user with value example@example.com to the session + Destroys current session + .. note:: This function should be the last one called, and even flash variables will no longer be available. + If you only want some items destroyed and not all, use ``unset_userdata()``. + + .. method:: sess_regenerate($destroy) + + :param bool $destroy: Destroy session data flag (default: false) + :returns: void + + Regenerate the current session data .. method:: userdata($item) @@ -522,6 +532,32 @@ Userdata $this->session->userdata('user'); //returns example@example.com considering the set_userdata example. + .. method:: all_userdata() + + :returns: array + + Retruns array of userdata session items + + .. method:: all_flashdata() + + :returns: array + + Retruns array of flashdata session items + + .. method:: set_userdata($newdata = array(), $newval) + + :param mixed $newdata: Item name or array of items + :param mixed $newval: Item value or empty string (not required if $newdata is array) + :returns: void + + Sets items into session example usages:: + + $this->session->set_userdata('user', 'example@example.com'); + // adds item user with value example@example.com to the session + + $this->session->set_userdata(array('user'=>'example@example.com')); + // does the same as the above example - adds item user with value example@example.com to the session + .. method:: unset_userdata($item) :param mixed $item: name of item or array of items @@ -533,7 +569,7 @@ Userdata //unsets 'user' from session data. $this->session->unset_userdata(array('user', 'useremail')); - //unsets both 'user' nad 'useremail' from the session data. + //unsets both 'user' and 'useremail' from the session data. .. method:: has_userdata($item) @@ -542,18 +578,6 @@ Userdata Checks if an item exists in the session. - .. method:: all_userdata() - - :returns: array - - Retruns array of userdata session items - - - -Flashdata ---------- -.. note:: the flashdata items are available only one server request - .. method:: set_flashdata($newdata = array(), $newval) :param mixed $newdata: Item name or array of items @@ -569,6 +593,13 @@ Flashdata // does the same as the above example - adds item 'message' with value 'Test message.' to the session flashdata + .. method:: keep_flashdata($item) + + :param mixed $item: name of item or array of flashdata items + :returns: void + + Keeps items into flashdata for one more request + .. method:: flashdata($item) :param string $item: name of session item @@ -579,30 +610,6 @@ Flashdata $this->session->flashdata('message'); //returns 'Test message.' considering the set_flashdata example. - .. method:: has_flashdata($item) - - :param string $item: name of item - :returns: bool - - Checks if an item exists in the session flashdata. - - .. method:: all_flashdata() - - :returns: array - - Retruns array of flashdata session items - - .. method:: keep_flashdata($item) - - :param mixed $item: name of item or array of flashdata items - :returns: void - - Keeps items into flashdata for one more request - - -Tempdata --------- - .. method:: set_tempdata($newdata = array(), $newval, $expires) :param mixed $newdata: Item name or array of items @@ -619,16 +626,6 @@ Tempdata // does the same as the above example - adds item 'message' with value 'Test message.' to the session tempdata for the default value of - .. method:: tempdata($item) - - :param string $item: name of tempdata item - :returns: string - - Returns a string containing the value of the passed item or NULL if the item is not found. Example:: - - $this->session->tempdata('message'); - //returns 'Test message.' considering the set_tempdata example. - .. method:: unset_tempdata($item) :param mixed $item: name of item or array of items @@ -640,34 +637,14 @@ Tempdata //unsets 'user' from tempdata. $this->session->unset_tempdata(array('user', 'useremail')); - //unsets both 'user' nad 'useremail' from the tempdata. - -Session -------- - - .. method:: sess_destroy() - - Destroys current session - .. note:: This function should be the last one called, and even flash variables will no longer be available. - If you only want some items destroyed and not all, use ``unset_userdata()``. - - .. method:: sess_regenerate($destroy) - - :param bool $destroy: Destroy session data flag (default: false) - :returns: void - - Regenerate the current session data + //unsets both 'user' and 'useremail' from the tempdata. - .. method:: load_driver($driver) - - :param string $driver: Driver name - :returns: object Loaded driver object - - Loads a session storage driver + .. method:: tempdata($item) - .. method:: select_driver($driver) + :param string $item: name of tempdata item + :returns: string - :param string $driver: Driver name - :returns: void + Returns a string containing the value of the passed item or NULL if the item is not found. Example:: - Selects default session storage driver. + $this->session->tempdata('message'); + //returns 'Test message.' considering the set_tempdata example. -- cgit v1.2.3-24-g4f1b From b57b2ade712990b9214ffaf80ae97829b91303db Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 12:02:08 +0200 Subject: [ci skip] Add/remove some newlines from the session docs --- user_guide_src/source/libraries/sessions.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index cab7669ae..b3de2252c 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -433,6 +433,7 @@ deleted data (sess_destroy), a regenerate handler to make a new session ID Your initial class might look like:: class CI_Session_custom extends CI_Session_driver { + protected function initialize() { // Read existing session data or create a new one @@ -457,6 +458,7 @@ Your initial class might look like:: { // Return a reference to your userdata array } + } Notice that ``get_userdata()`` returns a reference so the parent library is @@ -488,7 +490,6 @@ your config.php file to an array including your driver name:: $config['sess_valid_drivers'] = array('sess_driver'); - *************** Class Reference *************** @@ -647,4 +648,4 @@ Class Reference Returns a string containing the value of the passed item or NULL if the item is not found. Example:: $this->session->tempdata('message'); - //returns 'Test message.' considering the set_tempdata example. + //returns 'Test message.' considering the set_tempdata example. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 5363f4647b4fba3a0f7a52230cc33889096651ca Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 12:31:53 +0200 Subject: [ci skip] Update the Security class docs --- user_guide_src/source/libraries/security.rst | 103 ++++++++++++++++----------- 1 file changed, 60 insertions(+), 43 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/security.rst b/user_guide_src/source/libraries/security.rst index 05553142f..3d0697bbe 100644 --- a/user_guide_src/source/libraries/security.rst +++ b/user_guide_src/source/libraries/security.rst @@ -23,12 +23,7 @@ Note: This function should only be used to deal with data upon submission. It's not something that should be used for general runtime processing since it requires a fair amount of processing overhead. -To filter data through the XSS filter use this function: - -$this->security->xss_clean() -============================ - -Here is an usage example:: +To filter data through the XSS filter use the ``xss_clean()`` method:: $data = $this->security->xss_clean($data); @@ -38,10 +33,10 @@ application/config/config.php file and setting this:: $config['global_xss_filtering'] = TRUE; -Note: If you use the form validation class, it gives you the option of -XSS filtering as well. +.. note:: If you use the form validation class, it gives you the option of + XSS filtering as well. -An optional second parameter, is_image, allows this function to be used +An optional second parameter, *is_image*, allows this function to be used to test images for potential XSS attacks, useful for file upload security. When this second parameter is set to TRUE, instead of returning an altered string, the function returns TRUE if the image is @@ -52,40 +47,20 @@ browser may attempt to execute. if ($this->security->xss_clean($file, TRUE) === FALSE) { - // file failed the XSS test + // file failed the XSS test } -$this->security->sanitize_filename() -==================================== - -When accepting filenames from user input, it is best to sanitize them to -prevent directory traversal and other security related issues. To do so, -use the sanitize_filename() method of the Security class. Here is an -example:: - - $filename = $this->security->sanitize_filename($this->input->post('filename')); - -If it is acceptable for the user input to include relative paths, e.g. -file/in/some/approved/folder.txt, you can set the second optional -parameter, $relative_path to TRUE. - -:: - - $filename = $this->security->sanitize_filename($this->input->post('filename'), TRUE); - Cross-site request forgery (CSRF) ================================= -You can enable CSRF protection by opening your -application/config/config.php file and setting this:: +You can enable CSRF protection by altering your **application/config/config.php** +file in the following way:: $config['csrf_protection'] = TRUE; If you use the :doc:`form helper <../helpers/form_helper>`, then -``form_open()`` will automatically insert a hidden csrf field in -your forms. If not, then you can use ``csrf_get_token_name()`` -and ``csrf_get_hash()`` - +:func:`form_open()` will automatically insert a hidden csrf field in +your forms. If not, then you can use ``csrf_get_token_name()`` and ``csrf_get_hash()`` :: $csrf = array( @@ -114,15 +89,57 @@ by editing the 'csrf_exclude_uris' config parameter:: $config['csrf_exclude_uris'] = array('api/person/add'); -$this->security->get_csrf_token_name() -====================================== +*************** +Class Reference +*************** + +.. class:: CI_Security + + .. method:: xss_clean($str[, $is_image = FALSE]) + + :param string $str: Input string + :returns: mixed + + Tries to remove XSS exploits from the input data and returns the cleaned string. + If the optional second parameter is set to true, it will return boolean TRUE if the image is safe to use and FALSE if malicious data was detected in it. + + .. method:: sanitize_filename($str[, $relative_path = FALSE]) + + :param string $str: File name/path + :param bool $relative_path: Whether to preserve any directories in the file path + :returns: string + + Tries to sanitize filenames in order to prevent directory traversal attempts + and other security threats, which is particularly useful for files that were supplied via user input. + :: + + $filename = $this->security->sanitize_filename($this->input->post('filename')); + + If it is acceptable for the user input to include relative paths, e.g. + *file/in/some/approved/folder.txt*, you can set the second optional parameter, ``$relative_path`` to TRUE. + :: + + $filename = $this->security->sanitize_filename($this->input->post('filename'), TRUE); + + .. method:: get_csrf_token_name() + + :returns: string + + Returns the CSRF token name (the ``$config['csrf_token_name']`` value). + + .. method:: get_csrf_hash() + + :returns: string + + Returns the CSRF hash value. Useful in combination with ``get_csrf_token_name()`` + for manually building forms or sending valid AJAX POST requests. + + .. method:: entity_decode($str[, $charset = NULL]) -Returns the CSRF token name, which is set by -``$config['csrf_token_name']``. + :param string $str: Input string + :param string $charset: Character set of the input string -$this->security->get_csrf_hash() -================================ + This method acts a lot like PHP's own native ``html_entity_decode()`` function in ENT_COMPAT mode, only + it tries to detect HTML entities that don't end in a semicolon because some browsers allow that. -Returns the CSRF hash value. Useful in combination with -``get_csrf_token_name()`` for manually building forms or -sending valid AJAX POST requests. \ No newline at end of file + If the ``$charset`` parameter is left empty, then your configured ``$config['charset']`` value will be used. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 8da2e229362fc59329b3c3d8eea0dfcbf86759bb Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 12:47:37 +0200 Subject: [ci skip] Update the Parser library docs --- user_guide_src/source/libraries/parser.rst | 49 +++++++++++++++++++++--------- 1 file changed, 35 insertions(+), 14 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/parser.rst b/user_guide_src/source/libraries/parser.rst index 0b77ae4b9..5c184be58 100644 --- a/user_guide_src/source/libraries/parser.rst +++ b/user_guide_src/source/libraries/parser.rst @@ -46,15 +46,10 @@ in your controller using the $this->load->library function:: Once loaded, the Parser library object will be available using: $this->parser -The following functions are available in this library: +Parsing templates +================= -$this->parser->parse() -====================== - -This method accepts a template name and data array as input, and it -generates a parsed version. Example:: - - $this->load->library('parser'); +You can use the ``parse()`` method to parse (or render) simple templates, like this:: $data = array( 'blog_title' => 'My Blog Title', @@ -77,12 +72,6 @@ third parameter:: $string = $this->parser->parse('blog_template', $data, TRUE); -$this->parser->parse_string() -============================== - -This method works exactly like parse(), only accepts a string as the -first parameter in place of a view file. - Variable Pairs ============== @@ -147,3 +136,35 @@ function:: $this->parser->parse('blog_template', $data); +*************** +Class Reference +*************** + +.. class: CI_Parser + + .. method:: parse($template, $data[, $return = FALSE]) + + :param string $template: Path to view file + :param array $data: Variable data + :param bool $return: Whether to return the parsed template + :returns: mixed + + Parses a template from the provided path and variables. + + .. method:: parse_string($template, $data[, $return = FALSE]) + + :param string $template: Path to view file + :param array $data: Variable data + :param bool $return: Whether to return the parsed template + :returns: mixed + + 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 = '}']]) + + :param string $l: Left delimiter + :param string $r: Right delimiter + :returns: void + + Sets the delimiters (opening and closing) for a value "tag" in a template. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From f4bee9b68bf06f4161ddec05fe838af7b8fb561d Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 13:19:49 +0200 Subject: [ci skip] Update the Pagination library docs --- user_guide_src/source/libraries/pagination.rst | 105 ++++++++++++++----------- 1 file changed, 57 insertions(+), 48 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst index d9d3f5092..06627cfeb 100644 --- a/user_guide_src/source/libraries/pagination.rst +++ b/user_guide_src/source/libraries/pagination.rst @@ -15,7 +15,7 @@ Example ******* Here is a simple example showing how to create pagination in one of your -:doc:`controller <../general/controllers>` functions:: +:doc:`controller <../general/controllers>` methods:: $this->load->library('pagination'); @@ -30,8 +30,8 @@ Here is a simple example showing how to create pagination in one of your Notes ===== -The $config array contains your configuration variables. It is passed to -the $this->pagination->initialize function as shown above. Although +The ``$config`` array contains your configuration variables. It is passed to +the ``$this->pagination->initialize()`` method as shown above. Although there are some twenty items you can configure, at minimum you need the three shown. Here is a description of what those items represent: @@ -46,7 +46,7 @@ three shown. Here is a description of what those items represent: - **per_page** The number of items you intend to show per page. In the above example, you would be showing 20 items per page. -The create_links() function returns an empty string when there is no +The ``create_links()`` method returns an empty string when there is no pagination to show. Setting preferences in a config file @@ -54,9 +54,9 @@ Setting preferences in a config file If you prefer not to set preferences using the above method, you can instead put them into a config file. Simply create a new file called -pagination.php, add the $config array in that file. Then save the file -in: config/pagination.php and it will be used automatically. You will -NOT need to use the $this->pagination->initialize function if you save +pagination.php, add the ``$config`` array in that file. Then save the file +in *application/config/pagination.php* and it will be used automatically. +You will NOT need to use ``$this->pagination->initialize()`` if you save your preferences in a config file. ************************** @@ -67,14 +67,14 @@ The following is a list of all the preferences you can pass to the initialization function to tailor the display. $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; -========================== +========================= 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 @@ -92,25 +92,19 @@ $config['page_query_string'] = TRUE; By default, the pagination library assume you are using :doc:`URI Segments <../general/urls>`, and constructs your links something -like - -:: +like:: http://example.com/index.php/test/page/20 - -If you have $config['enable_query_strings'] set to TRUE your links +If you have ``$config['enable_query_strings']`` set to TRUE your links will automatically be re-written using Query Strings. This option can -also be explictly set. Using $config['page_query_string'] set to TRUE, -the pagination link will become. - -:: +also be explictly set. Using ``$config['page_query_string']`` set to TRUE, +the pagination link will become:: http://example.com/index.php?c=test&m=page&per_page=20 - Note that "per_page" is the default query string passed, however can be -configured using $config['query_string_segment'] = 'your_string' +configured using ``$config['query_string_segment'] = 'your_string'`` $config['reuse_query_string'] = FALSE; ====================================== @@ -118,9 +112,7 @@ $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 TRUE will add existing query string arguments back into the -URL after the URI segment and before the suffix - -:: +URL after the URI segment and before the suffix.:: http://example.com/index.php/test/page/20?query=search%term @@ -128,13 +120,13 @@ 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'] = ''; -================================== +======================= A custom prefix added to the path. The prefix value will be right before the offset segment. $config['suffix'] = ''; -================================== +======================= A custom suffix added to the path. The sufix value will be right after the offset segment. @@ -144,15 +136,15 @@ Adding Enclosing Markup *********************** If you would like to surround the entire pagination with some markup you -can do it with these two prefs: +can do it with these two preferences: $config['full_tag_open'] = '

'; -=================================== +================================= The opening tag placed on the left side of the entire result. $config['full_tag_close'] = '

'; -===================================== +=================================== The closing tag placed on the right side of the entire result. @@ -161,18 +153,18 @@ Customizing the First Link ************************** $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. $config['first_tag_open'] = '
'; -====================================== +==================================== The opening tag for the "first" link. $config['first_tag_close'] = '
'; -======================================== +====================================== The closing tag for the "first" link. @@ -181,18 +173,18 @@ Customizing the Last Link ************************* $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. $config['last_tag_open'] = '
'; -===================================== +=================================== The opening tag for the "last" link. $config['last_tag_close'] = '
'; -======================================= +===================================== The closing tag for the "last" link. @@ -201,18 +193,18 @@ Customizing the "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. $config['next_tag_open'] = '
'; -===================================== +=================================== The opening tag for the "next" link. $config['next_tag_close'] = '
'; -======================================= +===================================== The closing tag for the "next" link. @@ -221,18 +213,18 @@ Customizing the "Previous" 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. $config['prev_tag_open'] = '
'; -===================================== +=================================== The opening tag for the "previous" link. $config['prev_tag_close'] = '
'; -======================================= +===================================== The closing tag for the "previous" link. @@ -241,12 +233,12 @@ Customizing the "Current Page" Link *********************************** $config['cur_tag_open'] = ''; -================================== +================================ The opening tag for the "current" link. $config['cur_tag_close'] = ''; -==================================== +================================== The closing tag for the "current" link. @@ -255,12 +247,12 @@ Customizing the "Digit" Link **************************** $config['num_tag_open'] = '
'; -==================================== +================================== The opening tag for the "digit" link. $config['num_tag_close'] = '
'; -====================================== +==================================== The closing tag for the "digit" link. @@ -280,9 +272,7 @@ Adding attributes to anchors If you want to add an extra attribute to be added to every link rendered by the pagination class, you can set them as key/value pairs in the -"attributes" config - -:: +"attributes" config:: // Produces: class="myclass" $config['attributes'] = array('class' => 'myclass'); @@ -300,4 +290,23 @@ you can pass boolean FALSE as a regular attribute :: - $config['attributes']['rel'] = FALSE; \ No newline at end of file + $config['attributes']['rel'] = FALSE; + +*************** +Class Reference +*************** + +.. class:: CI_Pagination + + .. method:: initialize([$params = array()]) + + :param array $params: Configuration parameters + :returns: void + + Initializes the Pagination class with your preferred options. + + .. method:: create_links() + + :returns: string + + Returns a "pagination" bar, containing the generated links or an empty string if there's just a single page. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From c8f34854d6fe11f0b71aa6b1ebb30412937f062c Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 13:47:27 +0200 Subject: [ci skip] Update the Output library docs --- user_guide_src/source/libraries/output.rst | 224 +++++++++++++++-------------- 1 file changed, 120 insertions(+), 104 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/output.rst b/user_guide_src/source/libraries/output.rst index a3d67b847..a518f853d 100644 --- a/user_guide_src/source/libraries/output.rst +++ b/user_guide_src/source/libraries/output.rst @@ -2,7 +2,7 @@ Output Class ############ -The Output class is a small class with one main function: To send the +The Output class is a core class with one main function: To send the finalized web page to the requesting browser. It is also responsible for :doc:`caching <../general/caching>` your web pages, if you use that feature. @@ -16,159 +16,175 @@ use the :doc:`Loader <../libraries/loader>` class to load a view file, it's automatically passed to the Output class, which will be called automatically by CodeIgniter at the end of system execution. It is possible, however, for you to manually intervene with the output if you -need to, using either of the two following functions: +need to. -$this->output->set_output(); -============================= +*************** +Class Reference +*************** -Permits you to manually set the final output string. Usage example:: +.. class:: CI_Output - $this->output->set_output($data); + .. attribute:: $parse_exec_vars = TRUE; -.. important:: If you do set your output manually, it must be the last - thing done in the function you call it from. For example, if you build a - page in one of your controller functions, don't set the output until the - end. + Enables/disables parsing of the {elapsed_time} and {memory_usage} pseudo-variables. -$this->output->set_content_type(); -==================================== + CodeIgniter will parse those tokens in your output by default. To disable this, set + this property to FALSE in your controller. + :: -Permits you to set the mime-type of your page so you can serve JSON -data, JPEG's, XML, etc easily. + $this->output->parse_exec_vars = FALSE; -:: + .. method:: set_output($output) - $this->output - ->set_content_type('application/json') - ->set_output(json_encode(array('foo' => 'bar'))); + :param string $output: String to set the output to + :returns: object - $this->output - ->set_content_type('jpeg') // You could also use ".jpeg" which will have the full stop removed before looking in config/mimes.php - ->set_output(file_get_contents('files/something.jpg')); + Permits you to manually set the final output string. Usage example:: -.. important:: Make sure any non-mime string you pass to this method - exists in config/mimes.php or it will have no effect. + $this->output->set_output($data); -You can also set the character set of the document, by passing a second argument:: + .. important:: If you do set your output manually, it must be the last thing done + in the function you call it from. For example, if you build a page in one + of your controller functions, don't set the output until the end. - $this->output->set_content_type('css', 'utf-8'); + .. method:: set_content_type($mime_type[, $charset = NULL]) -$this->output->get_content_type() -================================= + :param string $mime_type: MIME Type idenitifer string + :param string $charset: Character set + :returns: object -Returns the Content-Type HTTP header that's currently in use, -excluding the character set value. + Permits you to set the mime-type of your page so you can serve JSON data, JPEG's, XML, etc easily. + :: - $mime = $this->output->get_content_type(); + $this->output + ->set_content_type('application/json') + ->set_output(json_encode(array('foo' => 'bar'))); -.. note:: If not set, the default return value is 'text/html'. + $this->output + ->set_content_type('jpeg') // You could also use ".jpeg" which will have the full stop removed before looking in config/mimes.php + ->set_output(file_get_contents('files/something.jpg')); -$this->output->get_header() -=========================== + .. important:: Make sure any non-mime string you pass to this method + exists in *application/config/mimes.php* or it will have no effect. -Gets the requested HTTP header value, if set. + You can also set the character set of the document, by passing a second argument:: -If the header is not set, NULL will be returned. -If an empty value is passed to the method, it will return FALSE. + $this->output->set_content_type('css', 'utf-8'); -Example:: + .. method:: get_content_type() - $this->output->set_content_type('text/plain', 'UTF-8'); - echo $this->output->get_header('content-type'); - // Outputs: text/plain; charset=utf-8 + :returns: string -.. note:: The header name is compared in a case-insensitive manner. + Returns the Content-Type HTTP header that's currently in use, excluding the character set value. + :: -.. note:: Raw headers sent via PHP's native ``header()`` function are - also detected. + $mime = $this->output->get_content_type(); -$this->output->get_output() -=========================== + .. note:: If not set, the default return value is 'text/html'. -Permits you to manually retrieve any output that has been sent for -storage in the output class. Usage example:: + .. method:: get_header($header) - $string = $this->output->get_output(); + :param string $header: HTTP header name + :returns: string -Note that data will only be retrievable from this function if it has -been previously sent to the output class by one of the CodeIgniter -functions like $this->load->view(). + Returns the requested HTTP header value, or NULL if the requested header is not set. + Example:: -$this->output->append_output(); -================================ + $this->output->set_content_type('text/plain', 'UTF-8'); + echo $this->output->get_header('content-type'); + // Outputs: text/plain; charset=utf-8 -Appends data onto the output string. Usage example:: + .. note:: The header name is compared in a case-insensitive manner. - $this->output->append_output($data); + .. note:: Raw headers sent via PHP's native ``header()`` function are also detected. -$this->output->set_header(); -============================= + .. method:: get_output() -Permits you to manually set server headers, which the output class will -send for you when outputting the final rendered display. Example:: + :returns: string - $this->output->set_header("HTTP/1.0 200 OK"); - $this->output->set_header("HTTP/1.1 200 OK"); - $this->output->set_header('Last-Modified: '.gmdate('D, d M Y H:i:s', $last_update).' GMT'); - $this->output->set_header("Cache-Control: no-store, no-cache, must-revalidate"); - $this->output->set_header("Cache-Control: post-check=0, pre-check=0"); - $this->output->set_header("Pragma: no-cache"); + Permits you to manually retrieve any output that has been sent for + storage in the output class. Usage example:: -$this->output->set_status_header(code, 'text'); -================================================= + $string = $this->output->get_output(); -Permits you to manually set a server status header. Example:: + Note that data will only be retrievable from this function if it has + been previously sent to the output class by one of the CodeIgniter + functions like ``$this->load->view()``. - $this->output->set_status_header('401'); - // Sets the header as: Unauthorized + .. method:: append_output($output) -`See here `_ for -a full list of headers. + :param string $output: Additional output data to append + :returns: object -.. note:: This method is an alias for :doc:`Common function <../general/common_functions>` - ``set_status_header()``. + Appends data onto the output string. + :: -$this->output->enable_profiler(); -================================== + $this->output->append_output($data); -Permits you to enable/disable the -:doc:`Profiler <../general/profiling>`, which will display benchmark -and other data at the bottom of your pages for debugging and -optimization purposes. + .. method:: set_header($header[, $replace = TRUE]) -To enable the profiler place the following function anywhere within your -:doc:`Controller <../general/controllers>` functions:: + :param string $header: HTTP Header + :param bool $replace: Whether to replace the old header value, if it is already set + :returns: object - $this->output->enable_profiler(TRUE); + Permits you to manually set server headers, which the output class will + send for you when outputting the final rendered display. Example:: -When enabled a report will be generated and inserted at the bottom of -your pages. + $this->output->set_header('HTTP/1.0 200 OK'); + $this->output->set_header('HTTP/1.1 200 OK'); + $this->output->set_header('Last-Modified: '.gmdate('D, d M Y H:i:s', $last_update).' GMT'); + $this->output->set_header('Cache-Control: no-store, no-cache, must-revalidate'); + $this->output->set_header('Cache-Control: post-check=0, pre-check=0'); + $this->output->set_header('Pragma: no-cache'); -To disable the profiler you will use:: + .. method:: set_status_header([$code = 200[, $text = '']]) - $this->output->enable_profiler(FALSE); + :param int $code: HTTP status code + :param string $text: Optional message + :returns: object -$this->output->set_profiler_sections(); -========================================= + Permits you to manually set a server status header. Example:: -Permits you to enable/disable specific sections of the Profiler when -enabled. Please refer to the :doc:`Profiler <../general/profiling>` -documentation for further information. + $this->output->set_status_header('401'); + // Sets the header as: Unauthorized -$this->output->cache(); -======================= + `See here `_ for a full list of headers. -The CodeIgniter output library also controls caching. For more -information, please see the :doc:`caching -documentation <../general/caching>`. + .. note:: This method is an alias for :doc:`Common function <../general/common_functions>` + :func:`set_status_header()`. -Parsing Execution Variables -=========================== + .. method:: enable_profiler([$val = TRUE]) -CodeIgniter will parse the pseudo-variables {elapsed_time} and -{memory_usage} in your output by default. To disable this, set the -$parse_exec_vars class property to FALSE in your controller. -:: + :param bool $val: Whether to enable or disable the Profiler + :returns: object - $this->output->parse_exec_vars = FALSE; + Permits you to enable/disable the :doc:`Profiler <../general/profiling>`, which will display benchmark + and other data at the bottom of your pages for debugging and optimization purposes. + To enable the profiler place the following line anywhere within your + :doc:`Controller <../general/controllers>` methods:: + + $this->output->enable_profiler(TRUE); + + When enabled a report will be generated and inserted at the bottom of your pages. + + To disable the profiler you would use:: + + $this->output->enable_profiler(FALSE); + + .. method:: set_profiler_sections($sections) + + :param array $sections: Profiler sections + :returns: object + + Permits you to enable/disable specific sections of the Profiler when it is enabled. + Please refer to the :doc:`Profiler <../general/profiling>` documentation for further information. + + .. method:: cache($time) + + :param int $time: Cache expiration time in seconds + :returns: object + + Caches the current page for the specified amount of seconds. + + For more information, please see the :doc:`caching documentation <../general/caching>`. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 11f58dcb887316f86e9e1f148355bf3a01ca1877 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 13:57:58 +0200 Subject: [ci skip] Update the Migration library docs --- user_guide_src/source/libraries/migration.rst | 116 ++++++++++++++------------ 1 file changed, 62 insertions(+), 54 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/migration.rst b/user_guide_src/source/libraries/migration.rst index b734f5c34..a007d5be7 100644 --- a/user_guide_src/source/libraries/migration.rst +++ b/user_guide_src/source/libraries/migration.rst @@ -10,8 +10,8 @@ need to be run against the production machines next time you deploy. The database table **migration** tracks which migrations have already been run so all you have to do is update your application files and -call **$this->migration->current()** to work out which migrations should be run. -The current version is found in **config/migration.php**. +call ``$this->migration->current()`` to work out which migrations should be run. +The current version is found in **application/config/migration.php**. ******************** Migration file names @@ -28,23 +28,24 @@ method taken. Two numbering styles are available: helps prevent numbering conflicts when working in a team environment, and is the preferred scheme in CodeIgniter 3.0 and later. -The desired style may be selected using the **$config['migration_type']** -setting in your **migration.php** config file. +The desired style may be selected using the ``$config['migration_type']`` +setting in your *application/config/migration.php* file. Regardless of which numbering style you choose to use, prefix your migration files with the migration number followed by an underscore and a descriptive name for the migration. For example: -* **001_add_blog.php** (sequential numbering) -* **20121031100537_add_blog.php** (timestamp numbering) +* 001_add_blog.php (sequential numbering) +* 20121031100537_add_blog.php (timestamp numbering) ****************** Create a Migration ****************** This will be the first migration for a new site which has a blog. All -migrations go in the folder **application/migrations/** and have names such -as **20121031100537_add_blog.php**.:: +migrations go in the **application/migrations/** directory and have names such +as *20121031100537_add_blog.php*. +:: load->library('migration'); - - if ($this->migration->current() === FALSE) - { - show_error($this->migration->error_string()); - } - } - } - -****************** -Function Reference -****************** - -$this->migration->current() -============================ - -The current migration is whatever is set for **$config['migration_version']** in -**application/config/migration.php**. - -$this->migration->error_string() -================================= - -This returns a string of errors while performing a migration. - -$this->migration->find_migrations() -==================================== -An array of migration filenames are returned that are found in the **migration_path** -property. - -$this->migration->latest() -=========================== - -This works much the same way as current() but instead of looking for -the **$config['migration_version']** the Migration class will use the very -newest migration found in the filesystem. - -$this->migration->version() -============================ - -Version can be used to roll back changes or step forwards programmatically to -specific versions. It works just like current but ignores **$config['migration_version']**.:: + public function index() + { + $this->load->library('migration'); - $this->load->library('migration'); + if ($this->migration->current() === FALSE) + { + show_error($this->migration->error_string()); + } + } - $this->migration->version(5); + } ********************* Migration Preferences @@ -161,3 +126,46 @@ Preference Default Options Des **migration_type** 'timestamp' 'timestamp' / 'sequential' The type of numeric identifier used to name migration files. ========================== ====================== ========================== ============================================= + +*************** +Class Reference +*************** + +.. class:: CI_Migration + + .. method:: current() + + :returns: mixed + + Migrates up to the current version (whatever is set for ``$config['migration_version']`` in *application/config/migration.php*). + + .. method:: error_string() + + :returns: string + + This returns a string of errors that were detected while performing a migration. + + .. method:: find_migrations() + + :returns: array + + An array of migration filenames are returned that are found in the **migration_path** property. + + .. method:: latest() + + :returns: mixed + + This works much the same way as ``current()`` but instead of looking for + the ``$config['migration_version']`` the Migration class will use the very + newest migration found in the filesystem. + + .. method:: version($target_version) + + :param mixed $target_version: Migration version to process + :returns: mixed + + Version can be used to roll back changes or step forwards programmatically to + specific versions. It works just like ``current()`` but ignores ``$config['migration_version']``. + :: + + $this->migration->version(5); \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 3a5638b51deb1921a149d416846e3078bc38163d Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 14:57:03 +0200 Subject: [ci skip] Update the URI library docs --- user_guide_src/source/libraries/uri.rst | 273 +++++++++++++++++--------------- 1 file changed, 149 insertions(+), 124 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/uri.rst b/user_guide_src/source/libraries/uri.rst index bb959b002..1256afdef 100644 --- a/user_guide_src/source/libraries/uri.rst +++ b/user_guide_src/source/libraries/uri.rst @@ -2,187 +2,212 @@ URI Class ######### -The URI Class provides functions that help you retrieve information from +The URI Class provides methods that help you retrieve information from your URI strings. If you use URI routing, you can also retrieve information about the re-routed segments. .. note:: This class is initialized automatically by the system so there is no need to do it manually. -$this->uri->segment(n) -====================== +*************** +Class Reference +*************** -Permits you to retrieve a specific segment. Where n is the segment -number you wish to retrieve. Segments are numbered from left to right. -For example, if your full URL is this:: +.. class:: CI_URI - http://example.com/index.php/news/local/metro/crime_is_up + .. method:: segment($n[, $no_result = NULL]) -The segment numbers would be this: + :param int $n: Segment index number + :param mixed $no_result: What to return if the searched segment is not found + :returns: mixed -#. news -#. local -#. metro -#. crime_is_up + Permits you to retrieve a specific segment. Where n is the segment + number you wish to retrieve. Segments are numbered from left to right. + For example, if your full URL is this:: -By default the function returns NULL if the segment does not -exist. There is an optional second parameter that permits you to set -your own default value if the segment is missing. For example, this -would tell the function to return the number zero in the event of -failure:: + http://example.com/index.php/news/local/metro/crime_is_up - $product_id = $this->uri->segment(3, 0); + The segment numbers would be this: -It helps avoid having to write code like this:: + #. news + #. local + #. metro + #. crime_is_up - if ($this->uri->segment(3) === FALSE) - { - $product_id = 0; - } - else - { - $product_id = $this->uri->segment(3); - } + The optional second parameter defaults to NULL and allows you to set the return value + of this method when the requested URI segment is missing. + For example, this would tell the method to return the number zero in the event of failure:: -$this->uri->rsegment(n) -======================= + $product_id = $this->uri->segment(3, 0); -This function is identical to the previous one, except that it lets you -retrieve a specific segment from your re-routed URI in the event you are -using CodeIgniter's :doc:`URI Routing <../general/routing>` feature. + It helps avoid having to write code like this:: -$this->uri->slash_segment(n) -============================= + if ($this->uri->segment(3) === FALSE) + { + $product_id = 0; + } + else + { + $product_id = $this->uri->segment(3); + } -This function is almost identical to $this->uri->segment(), except it -adds a trailing and/or leading slash based on the second parameter. If -the parameter is not used, a trailing slash added. Examples:: + .. method:: rsegment($n[, $no_result = NULL]) - $this->uri->slash_segment(3); - $this->uri->slash_segment(3, 'leading'); - $this->uri->slash_segment(3, 'both'); + :param int $n: Segment index number + :param mixed $no_result: What to return if the searched segment is not found + :returns: mixed -Returns: + This method is identical to ``segment()``, except that it lets you retrieve + a specific segment from your re-routed URI in the event you are + using CodeIgniter's :doc:`URI Routing <../general/routing>` feature. -#. segment/ -#. /segment -#. /segment/ + .. method:: slash_segment($n[, $where = 'trailing']) -$this->uri->slash_rsegment(n) -============================== + :param int $n: Segment index number + :param string $where: Where to add the slash ('trailing' or 'leading') + :returns: string -This function is identical to the previous one, except that it lets you -add slashes a specific segment from your re-routed URI in the event you -are using CodeIgniter's :doc:`URI Routing <../general/routing>` -feature. + This method is almost identical to ``segment()``, except it + adds a trailing and/or leading slash based on the second parameter. + If the parameter is not used, a trailing slash added. Examples:: -$this->uri->uri_to_assoc(n) -============================= + $this->uri->slash_segment(3); + $this->uri->slash_segment(3, 'leading'); + $this->uri->slash_segment(3, 'both'); -This function lets you turn URI segments into and associative array of -key/value pairs. Consider this URI:: + Returns: - index.php/user/search/name/joe/location/UK/gender/male + #. segment/ + #. /segment + #. /segment/ -Using this function you can turn the URI into an associative array with -this prototype:: + .. method:: slash_rsegment($n[, $where = 'trailing']) - [array] - ( - 'name' => 'joe' - 'location' => 'UK' - 'gender' => 'male' - ) + :param int $n: Segment index number + :param string $where: Where to add the slash ('trailing' or 'leading') + :returns: string -The first parameter of the function lets you set an offset. By default -it is set to 3 since your URI will normally contain a -controller/function in the first and second segments. Example:: + This method is identical to ``slash_segment()``, except that it lets you + add slashes a specific segment from your re-routed URI in the event you + are using CodeIgniter's :doc:`URI Routing <../general/routing>` + feature. - $array = $this->uri->uri_to_assoc(3); + .. method:: uri_to_assoc([$n = 3[, $default = array()]]) - echo $array['name']; + :param int $n: Segment index number + :param array $default: Default values + :returns: array -The second parameter lets you set default key names, so that the array -returned by the function will always contain expected indexes, even if -missing from the URI. Example:: + This method lets you turn URI segments into and associative array of + key/value pairs. Consider this URI:: - $default = array('name', 'gender', 'location', 'type', 'sort'); + index.php/user/search/name/joe/location/UK/gender/male - $array = $this->uri->uri_to_assoc(3, $default); + Using this method you can turn the URI into an associative array with + this prototype:: -If the URI does not contain a value in your default, an array index will -be set to that name, with a value of FALSE. + [array] + ( + 'name' => 'joe' + 'location' => 'UK' + 'gender' => 'male' + ) -Lastly, if a corresponding value is not found for a given key (if there -is an odd number of URI segments) the value will be set to FALSE -(boolean). + The first parameter lets you set an offset, which defaults to 3 since your + URI will normally contain a controller/method pair in the first and second segments. + Example:: -$this->uri->ruri_to_assoc(n) -============================== + $array = $this->uri->uri_to_assoc(3); + echo $array['name']; -This function is identical to the previous one, except that it creates -an associative array using the re-routed URI in the event you are using -CodeIgniter's :doc:`URI Routing <../general/routing>` feature. + The second parameter lets you set default key names, so that the array + returned will always contain expected indexes, even if missing from the URI. + Example:: -$this->uri->assoc_to_uri() -============================ + $default = array('name', 'gender', 'location', 'type', 'sort'); + $array = $this->uri->uri_to_assoc(3, $default); -Takes an associative array as input and generates a URI string from it. -The array keys will be included in the string. Example:: + If the URI does not contain a value in your default, an array index will + be set to that name, with a value of NULL. - $array = array('product' => 'shoes', 'size' => 'large', 'color' => 'red'); + Lastly, if a corresponding value is not found for a given key (if there + is an odd number of URI segments) the value will be set to NULL. - $str = $this->uri->assoc_to_uri($array); + .. method:: ruri_to_assoc([$n = 3[, $default = array()]]) - // Produces: product/shoes/size/large/color/red + :param int $n: Segment index number + :param array $default: Default values + :returns: array -$this->uri->uri_string() -========================= + This method is identical to ``uri_to_assoc()``, except that it creates + an associative array using the re-routed URI in the event you are using + CodeIgniter's :doc:`URI Routing <../general/routing>` feature. -Returns a string with the complete URI. For example, if this is your -full URL:: + .. method:: assoc_to_uri($array) - http://example.com/index.php/news/local/345 + :param array $array: Input array of key/value pairs + :returns: string -The function would return this:: + Takes an associative array as input and generates a URI string from it. + The array keys will be included in the string. Example:: - news/local/345 + $array = array('product' => 'shoes', 'size' => 'large', 'color' => 'red'); + $str = $this->uri->assoc_to_uri($array); -$this->uri->ruri_string() -========================== + // Produces: product/shoes/size/large/color/red -This function is identical to the previous one, except that it returns -the re-routed URI in the event you are using CodeIgniter's :doc:`URI -Routing <../general/routing>` feature. + .. method:: uri_string() -$this->uri->total_segments() -============================= + :returns: string -Returns the total number of segments. + Returns a string with the complete URI. For example, if this is your full URL:: -$this->uri->total_rsegments() -============================== + http://example.com/index.php/news/local/345 -This function is identical to the previous one, except that it returns -the total number of segments in your re-routed URI in the event you are -using CodeIgniter's :doc:`URI Routing <../general/routing>` feature. + The method would return this:: -$this->uri->segment_array() -============================ + news/local/345 -Returns an array containing the URI segments. For example:: + .. method:: ruri_string() - $segs = $this->uri->segment_array(); + :returns: string - foreach ($segs as $segment) - { - echo $segment; - echo '
'; - } + This method is identical to ``uri_string()``, except that it returns + the re-routed URI in the event you are using CodeIgniter's :doc:`URI + Routing <../general/routing>` feature. -$this->uri->rsegment_array() -============================= + .. method:: total_segments() -This function is identical to the previous one, except that it returns -the array of segments in your re-routed URI in the event you are using -CodeIgniter's :doc:`URI Routing <../general/routing>` feature. + :returns: int + + Returns the total number of segments. + + .. method:: total_rsegments() + + :returns: int + + This method is identical to ``total_segments()``, except that it returns + the total number of segments in your re-routed URI in the event you are + using CodeIgniter's :doc:`URI Routing <../general/routing>` feature. + + .. method:: segment_array() + + :returns: array + + Returns an array containing the URI segments. For example:: + + $segs = $this->uri->segment_array(); + + foreach ($segs as $segment) + { + echo $segment; + echo '
'; + } + + .. method:: rsegment_array() + + :returns: array + + This method is identical to ``segment_array()``, except that it returns + the array of segments in your re-routed URI in the event you are using + CodeIgniter's :doc:`URI Routing <../general/routing>` feature. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From cc042095bcce9856402cc04997f44310074716e0 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 17:08:27 +0200 Subject: [ci skip] Some more generic user guide cleanup --- user_guide_src/source/libraries/caching.rst | 38 ++++++-------------------- user_guide_src/source/libraries/migration.rst | 7 +++++ user_guide_src/source/libraries/output.rst | 7 +++++ user_guide_src/source/libraries/pagination.rst | 7 +++++ user_guide_src/source/libraries/parser.rst | 7 +++++ user_guide_src/source/libraries/security.rst | 7 +++++ user_guide_src/source/libraries/sessions.rst | 9 +++++- user_guide_src/source/libraries/table.rst | 8 +++--- user_guide_src/source/libraries/trackback.rst | 4 +-- user_guide_src/source/libraries/typography.rst | 4 +-- user_guide_src/source/libraries/uri.rst | 7 +++++ user_guide_src/source/libraries/user_agent.rst | 4 +-- user_guide_src/source/libraries/xmlrpc.rst | 4 +-- user_guide_src/source/libraries/zip.rst | 4 +-- 14 files changed, 73 insertions(+), 44 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/caching.rst b/user_guide_src/source/libraries/caching.rst index 55fdabca3..709171dd3 100644 --- a/user_guide_src/source/libraries/caching.rst +++ b/user_guide_src/source/libraries/caching.rst @@ -54,17 +54,15 @@ Class Reference .. class:: CI_Cache - .. method:: is_supported ( $driver ) + .. method:: is_supported($driver) :param string $driver: the name of the caching driver :returns: TRUE if supported, FALSE if not - :rtype: Boolean This method is automatically called when accessing drivers via - $this->cache->get(). However, if the individual drivers are used, make - sure to call this method to ensure the driver is supported in the + ``$this->cache->get()``. However, if the individual drivers are used, + make sure to call this method to ensure the driver is supported in the hosting environment. - :: if ($this->cache->apc->is_supported() @@ -75,71 +73,56 @@ Class Reference } } - - .. method:: get ( $id ) + .. method:: get($id) :param string $id: name of cached item :returns: The item if it exists, FALSE if it does not - :rtype: Mixed This method will attempt to fetch an item from the cache store. If the item does not exist, the method will return FALSE. - :: $foo = $this->cache->get('my_cached_item'); - - .. method:: save ( $id , $data [, $ttl = 60]) + .. method:: save($id, $data[, $ttl = 60]) :param string $id: name of the cached item :param mixed $data: the data to save :param int $ttl: Time To Live, in seconds (default 60) :returns: TRUE on success, FALSE on failure - :rtype: Boolean This method will save an item to the cache store. If saving fails, the method will return FALSE. - :: $this->cache->save('cache_item_id', 'data_to_cache'); - - .. method:: delete ( $id ) + .. method:: delete($id) :param string $id: name of cached item :returns: TRUE if deleted, FALSE if the deletion fails - :rtype: Boolean This method will delete a specific item from the cache store. If item deletion fails, the method will return FALSE. - :: $this->cache->delete('cache_item_id'); - - .. method:: clean ( ) + .. method:: clean() :returns: TRUE if deleted, FALSE if the deletion fails - :rtype: Boolean This method will 'clean' the entire cache. If the deletion of the cache files fails, the method will return FALSE. - :: $this->cache->clean(); - - .. method:: cache_info ( ) + .. method:: cache_info() :returns: information on the entire cache - :rtype: Mixed This method will return information on the entire cache. - :: var_dump($this->cache->cache_info()); @@ -147,16 +130,13 @@ Class Reference .. note:: The information returned and the structure of the data is dependent on which adapter is being used. - - .. method:: get_metadata ( $id ) + .. method:: get_metadata($id) :param string $id: name of cached item :returns: metadadta for the cached item - :rtype: Mixed This method will return detailed information on a specific item in the cache. - :: var_dump($this->cache->get_metadata('my_cached_item')); diff --git a/user_guide_src/source/libraries/migration.rst b/user_guide_src/source/libraries/migration.rst index a007d5be7..128796c4d 100644 --- a/user_guide_src/source/libraries/migration.rst +++ b/user_guide_src/source/libraries/migration.rst @@ -13,6 +13,13 @@ run so all you have to do is update your application files and call ``$this->migration->current()`` to work out which migrations should be run. The current version is found in **application/config/migration.php**. +.. contents:: + :local: + +.. raw:: html + +
+ ******************** Migration file names ******************** diff --git a/user_guide_src/source/libraries/output.rst b/user_guide_src/source/libraries/output.rst index a518f853d..76197bdc1 100644 --- a/user_guide_src/source/libraries/output.rst +++ b/user_guide_src/source/libraries/output.rst @@ -18,6 +18,13 @@ automatically by CodeIgniter at the end of system execution. It is possible, however, for you to manually intervene with the output if you need to. +.. contents:: + :local: + +.. raw:: html + +
+ *************** Class Reference *************** diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst index 06627cfeb..34ca22141 100644 --- a/user_guide_src/source/libraries/pagination.rst +++ b/user_guide_src/source/libraries/pagination.rst @@ -5,6 +5,13 @@ Pagination Class CodeIgniter's Pagination class is very easy to use, and it is 100% customizable, either dynamically or via stored preferences. +.. contents:: + :local: + +.. raw:: html + +
+ If you are not familiar with the term "pagination", it refers to links that allows you to navigate from page to page, like this:: diff --git a/user_guide_src/source/libraries/parser.rst b/user_guide_src/source/libraries/parser.rst index 5c184be58..50bde82c7 100644 --- a/user_guide_src/source/libraries/parser.rst +++ b/user_guide_src/source/libraries/parser.rst @@ -35,6 +35,13 @@ representations that allow you to eliminate PHP from your templates template parsing solution. We've kept it very lean on purpose in order to maintain maximum performance. +.. contents:: + :local: + +.. raw:: html + +
+ Initializing the Class ====================== diff --git a/user_guide_src/source/libraries/security.rst b/user_guide_src/source/libraries/security.rst index 3d0697bbe..8d7ccb1ab 100644 --- a/user_guide_src/source/libraries/security.rst +++ b/user_guide_src/source/libraries/security.rst @@ -5,6 +5,13 @@ Security Class The Security Class contains methods that help you create a secure application, processing input data for security. +.. contents:: + :local: + +.. raw:: html + +
+ XSS Filtering ============= diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index b3de2252c..8e117bee6 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -9,6 +9,13 @@ which supports usage of the native PHP Session mechanism. In addition, you may create your own `Custom Drivers`_ to store session data however you wish, while still taking advantage of the features of the Session class. +.. contents:: + :local: + +.. raw:: html + +
+ Initializing a Session ====================== @@ -27,7 +34,7 @@ use the ``$this->load->driver`` function:: Once loaded, the Sessions library object will be available using:: -$this->session + $this->session How do Sessions work? ===================== diff --git a/user_guide_src/source/libraries/table.rst b/user_guide_src/source/libraries/table.rst index 25927800e..bfe457993 100644 --- a/user_guide_src/source/libraries/table.rst +++ b/user_guide_src/source/libraries/table.rst @@ -5,12 +5,12 @@ HTML Table Class The Table Class provides functions that enable you to auto-generate HTML tables from arrays or database result sets. -.. content:: - :local: +.. contents:: + :local: .. raw:: html -
+
********************* Using the Table Class @@ -280,4 +280,4 @@ Class Reference $this->table->add_row('Mary', 'Monday', 'Air'); $this->table->add_row('John', 'Saturday', 'Overnight'); - echo $this->table->generate(); + echo $this->table->generate(); \ No newline at end of file diff --git a/user_guide_src/source/libraries/trackback.rst b/user_guide_src/source/libraries/trackback.rst index 72958934c..a1667c79c 100644 --- a/user_guide_src/source/libraries/trackback.rst +++ b/user_guide_src/source/libraries/trackback.rst @@ -9,11 +9,11 @@ If you are not familiar with Trackbacks you'll find more information `here `_. .. content:: - :local: + :local: .. raw:: html -
+
************************* Using the Trackback Class diff --git a/user_guide_src/source/libraries/typography.rst b/user_guide_src/source/libraries/typography.rst index 8dab053ba..006e77d56 100644 --- a/user_guide_src/source/libraries/typography.rst +++ b/user_guide_src/source/libraries/typography.rst @@ -5,11 +5,11 @@ Typography Class The Typography Class provides methods that help you format text. .. content:: - :local: + :local: .. raw:: html -
+
************************** Using the Typography Class diff --git a/user_guide_src/source/libraries/uri.rst b/user_guide_src/source/libraries/uri.rst index 1256afdef..f0fa04005 100644 --- a/user_guide_src/source/libraries/uri.rst +++ b/user_guide_src/source/libraries/uri.rst @@ -9,6 +9,13 @@ information about the re-routed segments. .. note:: This class is initialized automatically by the system so there is no need to do it manually. +.. contents:: + :local: + +.. raw:: html + +
+ *************** Class Reference *************** diff --git a/user_guide_src/source/libraries/user_agent.rst b/user_guide_src/source/libraries/user_agent.rst index 3662cf3ad..9f9676828 100644 --- a/user_guide_src/source/libraries/user_agent.rst +++ b/user_guide_src/source/libraries/user_agent.rst @@ -8,11 +8,11 @@ addition you can get referrer information as well as language and supported character-set information. .. contents:: - :local: + :local: .. raw:: html -
+
************************** Using the User Agent Class diff --git a/user_guide_src/source/libraries/xmlrpc.rst b/user_guide_src/source/libraries/xmlrpc.rst index c79f8bed9..c89c69c46 100644 --- a/user_guide_src/source/libraries/xmlrpc.rst +++ b/user_guide_src/source/libraries/xmlrpc.rst @@ -6,11 +6,11 @@ CodeIgniter's XML-RPC classes permit you to send requests to another server, or set up your own XML-RPC server to receive requests. .. contents:: - :local: + :local: .. raw:: html -
+
**************** What is XML-RPC? diff --git a/user_guide_src/source/libraries/zip.rst b/user_guide_src/source/libraries/zip.rst index e0955e3d6..ea5b46bac 100644 --- a/user_guide_src/source/libraries/zip.rst +++ b/user_guide_src/source/libraries/zip.rst @@ -7,11 +7,11 @@ archives. Archives can be downloaded to your desktop or saved to a directory. .. contents:: - :local: + :local: .. raw:: html -
+
**************************** Using the Zip Encoding Class -- cgit v1.2.3-24-g4f1b From eb21ac8e9b85b681bc03b935955b3fbfa9b0db1e Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 17:27:29 +0200 Subject: [ci skip] Finish updating the FTP class docs --- user_guide_src/source/libraries/ftp.rst | 201 ++++++++++++++++++-------------- 1 file changed, 111 insertions(+), 90 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/ftp.rst b/user_guide_src/source/libraries/ftp.rst index fd82590b9..1b1a45e36 100644 --- a/user_guide_src/source/libraries/ftp.rst +++ b/user_guide_src/source/libraries/ftp.rst @@ -37,7 +37,6 @@ Usage Examples In this example a connection is opened to the FTP server, and a local file is read and uploaded in ASCII mode. The file permissions are set to 755. - :: $this->load->library('ftp'); @@ -54,7 +53,6 @@ file is read and uploaded in ASCII mode. The file permissions are set to $this->ftp->close(); In this example a list of files is retrieved from the server. - :: $this->load->library('ftp'); @@ -73,7 +71,6 @@ In this example a list of files is retrieved from the server. $this->ftp->close(); In this example a local directory is mirrored on the server. - :: $this->load->library('ftp'); @@ -121,140 +118,164 @@ Class Reference If you prefer you can store your FTP preferences in a config file. Simply create a new file called the ftp.php, add the $config array in - that file. Then save the file at config/ftp.php and it will be used - automatically. + that file. Then save the file at *application/config/ftp.php* and it + will be used automatically. **Available connection options** ================== =================================== - Option Name Description + Option Name Description ================== =================================== - **hostname** the FTP hostname. Usually something like: ftp.example.com - **username** the FTP username - **password** the FTP password - **port** The port number. Set to 21 by default. - **debug** TRUE/FALSE (boolean). Whether to enable debugging to display error messages. - **passive** TRUE/FALSE (boolean). Whether to use passive mode. Passive is set automatically by default. + **hostname** the FTP hostname. Usually something like: ftp.example.com + **username** the FTP username + **password** the FTP password + **port** The port number. Set to 21 by default. + **debug** TRUE/FALSE (boolean). Whether to enable debugging to display error messages. + **passive** TRUE/FALSE (boolean). Whether to use passive mode. Passive is set automatically by default. ================== =================================== + .. method:: upload($locpath, $rempath[, $mode = 'auto'[, $permissions = NULL]]) -Uploads a file to your server. You must supply the local path and the -remote path, and you can optionally set the mode and permissions. -Example:: + :param string $locpath: Local file path + :param string $rempath: Remote file path + :param string $mode: FTP mode, defaults to 'auto' (options are: 'auto', 'binary', 'ascii') + :param int $permissions: File permissions (octal) + :returns: bool - $this->ftp->upload('/local/path/to/myfile.html', '/public_html/myfile.html', 'ascii', 0775); + Uploads a file to your server. You must supply the local path and the + remote path, and you can optionally set the mode and permissions. + Example:: -**Mode options are:** ascii, binary, and auto (the default). If auto is -used it will base the mode on the file extension of the source file. + $this->ftp->upload('/local/path/to/myfile.html', '/public_html/myfile.html', 'ascii', 0775); -If set, permissions have to be passed as an octal value. + If 'auto' mode is used it will base the mode on the file extension of the source file. -$this->ftp->download() -====================== + If set, permissions have to be passed as an octal value. -Downloads a file from your server. You must supply the remote path and -the local path, and you can optionally set the mode. Example:: + .. method:: download($rempath, $locpath[, $mode = 'auto']) - $this->ftp->download('/public_html/myfile.html', '/local/path/to/myfile.html', 'ascii'); + :param string $rempath: Remote file path + :param string $locpath: Local file path + :param string $mode: FTP mode, defaults to 'auto' (options are: 'auto', 'binary', 'ascii') + :returns: bool -**Mode options are:** ascii, binary, and auto (the default). If auto is -used it will base the mode on the file extension of the source file. + Downloads a file from your server. You must supply the remote path and + the local path, and you can optionally set the mode. Example:: -Returns FALSE if the download does not execute successfully (including -if PHP does not have permission to write the local file) + $this->ftp->download('/public_html/myfile.html', '/local/path/to/myfile.html', 'ascii'); -$this->ftp->rename() -==================== + If 'auto' mode is used it will base the mode on the file extension of the source file. -Permits you to rename a file. Supply the source file name/path and the -new file name/path. + Returns FALSE if the download does not execute successfully (including if PHP does not have permission to write the local file). -:: + .. method:: rename($old_file, $new_file, $move = FALSE) - // Renames green.html to blue.html - $this->ftp->rename('/public_html/foo/green.html', '/public_html/foo/blue.html'); + :param string $old_file: Old file name + :param string $new_file: New file name + :param bool $move: Whether a move is being performed + :returns: bool -$this->ftp->move() -================== + Permits you to rename a file. Supply the source file name/path and the new file name/path. + :: -Lets you move a file. Supply the source and destination paths:: + // Renames green.html to blue.html + $this->ftp->rename('/public_html/foo/green.html', '/public_html/foo/blue.html'); - // Moves blog.html from "joe" to "fred" - $this->ftp->move('/public_html/joe/blog.html', '/public_html/fred/blog.html'); + .. method:: move($old_file, $new_file) -Note: if the destination file name is different the file will be -renamed. + :param string $old_file: Old file name + :param string $new_file: New file name + :returns: bool -$this->ftp->delete_file() -========================== + Lets you move a file. Supply the source and destination paths:: -Lets you delete a file. Supply the source path with the file name. + // Moves blog.html from "joe" to "fred" + $this->ftp->move('/public_html/joe/blog.html', '/public_html/fred/blog.html'); -:: + .. note:: If the destination file name is different the file will be renamed. - $this->ftp->delete_file('/public_html/joe/blog.html'); + .. method:: delete_file($filepath) -$this->ftp->delete_dir() -========================= + :param string $filepath: Path to file to delete + :returns: bool -Lets you delete a directory and everything it contains. Supply the -source path to the directory with a trailing slash. + Lets you delete a file. Supply the source path with the file name. + :: -**Important** Be VERY careful with this function. It will recursively -delete **everything** within the supplied path, including sub-folders -and all files. Make absolutely sure your path is correct. Try using the -list_files() function first to verify that your path is correct. + $this->ftp->delete_file('/public_html/joe/blog.html'); -:: + .. method:: delete_dir($filepath) - $this->ftp->delete_dir('/public_html/path/to/folder/'); + :param string $filepath: Path to directory to delete + :returns: bool -$this->ftp->list_files() -========================= + Lets you delete a directory and everything it contains. Supply the + source path to the directory with a trailing slash. -Permits you to retrieve a list of files on your server returned as an -array. You must supply the path to the desired directory. + .. important:: Be VERY careful with this method! + It will recursively delete **everything** within the supplied path, + including sub-folders and all files. Make absolutely sure your path + is correct. Try using ``list_files()`` first to verify that your path is correct. -:: + :: - $list = $this->ftp->list_files('/public_html/'); + $this->ftp->delete_dir('/public_html/path/to/folder/'); - print_r($list); + .. method:: list_files([$path = '.']) -$this->ftp->mirror() -==================== + :param string $path: Directory path + :returns: array or FALSE on failure -Recursively reads a local folder and everything it contains (including -sub-folders) and creates a mirror via FTP based on it. Whatever the -directory structure of the original file path will be recreated on the -server. You must supply a source path and a destination path:: + Permits you to retrieve a list of files on your server returned as an + array. You must supply the path to the desired directory. + :: - $this->ftp->mirror('/path/to/myfolder/', '/public_html/myfolder/'); + $list = $this->ftp->list_files('/public_html/'); + print_r($list); -$this->ftp->mkdir() -=================== + .. method:: mirror($locpath, $rempath) -Lets you create a directory on your server. Supply the path ending in -the folder name you wish to create, with a trailing slash. Permissions -can be set by passed an octal value in the second parameter (if you are -running PHP 5). + :param string $locpath: Local path + :param string $rempath: Remote path + :returns: bool -:: + Recursively reads a local folder and everything it contains (including + sub-folders) and creates a mirror via FTP based on it. Whatever the + directory structure of the original file path will be recreated on the + server. You must supply a source path and a destination path:: + + $this->ftp->mirror('/path/to/myfolder/', '/public_html/myfolder/'); + + .. method:: mkdir($path[, $permissions = NULL]) + + :param string $path: Path to directory to create + :param int $permissions: Permissions (octal) + :returns: bool + + Lets you create a directory on your server. Supply the path ending in + the folder name you wish to create, with a trailing slash. - // Creates a folder named "bar" - $this->ftp->mkdir('/public_html/foo/bar/', DIR_WRITE_MODE); + Permissions can be set by passing an octal value in the second parameter. + :: -$this->ftp->chmod() -=================== + // Creates a folder named "bar" + $this->ftp->mkdir('/public_html/foo/bar/', DIR_WRITE_MODE); -Permits you to set file permissions. Supply the path to the file or -folder you wish to alter permissions on:: + .. method:: chmod($path, $perm) + + :param string $path: Path to alter permissions for + :param int $perm: Permissions (octal) + :returns: bool - // Chmod "bar" to 777 - $this->ftp->chmod('/public_html/foo/bar/', DIR_WRITE_MODE); + Permits you to set file permissions. Supply the path to the file or + directory you wish to alter permissions on:: -$this->ftp->close(); -==================== + // Chmod "bar" to 777 + $this->ftp->chmod('/public_html/foo/bar/', DIR_WRITE_MODE); + + .. method:: close() + + :returns: bool -Closes the connection to your server. It's recommended that you use this -when you are finished uploading. + Closes the connection to your server. It's recommended that you use this + when you are finished uploading. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From a322989d6e24f381df56dea2428c29d4d185d6b5 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 17:35:52 +0200 Subject: [ci skip] Add missing docs for CI_FTP::changedir() --- user_guide_src/source/libraries/ftp.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/ftp.rst b/user_guide_src/source/libraries/ftp.rst index 1b1a45e36..c587869db 100644 --- a/user_guide_src/source/libraries/ftp.rst +++ b/user_guide_src/source/libraries/ftp.rst @@ -273,6 +273,17 @@ Class Reference // Chmod "bar" to 777 $this->ftp->chmod('/public_html/foo/bar/', DIR_WRITE_MODE); + .. method:: changedir($path[, $suppress_debug = FALSE]) + + :param string $path: Directory path + :param bool $suppress_debug: Whether to turn off debug messages for this command + :returns: bool + + Changes the current working directory to the specified path. + + The ``$suppress_debug`` parameter is useful in case you want to use this method + as an ``is_dir()`` alternative for FTP. + .. method:: close() :returns: bool -- cgit v1.2.3-24-g4f1b From ae72dc60a833b60f9def05ff3c4bc68f5407d80d Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 18:15:24 +0200 Subject: [ci skip] Update the Language library docs --- user_guide_src/source/libraries/language.rst | 39 +++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/language.rst b/user_guide_src/source/libraries/language.rst index e772e8e27..3cee5d7f6 100644 --- a/user_guide_src/source/libraries/language.rst +++ b/user_guide_src/source/libraries/language.rst @@ -19,11 +19,18 @@ 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 +.. contents:: + :local: + +.. raw:: html + +
+ Creating Language Files ======================= -Language files must be named with **_lang.php** as the file extension. For -example, let's say you want to create a file containing error messages. +Language files must be named with **_lang.php** as the filename extension. +For example, let's say you want to create a file containing error messages. You might name it: error_lang.php Within the file you will assign each line of text to an array called @@ -89,4 +96,30 @@ If you find that you need a particular language globally throughout your application, you can tell CodeIgniter to :doc:`auto-load <../general/autoloader>` it during system initialization. This is done by opening the **application/config/autoload.php** file and adding the -language(s) to the autoload array. \ No newline at end of file +language(s) to the autoload array. + +*************** +Class Reference +*************** + +.. class:: CI_Lang + + .. method:: load($langfile[, $idiom = ''[, $return = FALSE[, $add_suffix = TRUE[, $alt_path = '']]]]) + + :param string $langfile: Language file to load + :param string $idiom: Language name (i.e. 'english') + :param bool $return: Whether to return the loaded array of translations + :param bool $add_suffix: Whether to add the '_lang' suffix to the language file name + :param string $alt_path: An alternative path to look in for the language file + :returns: void or array if the third parameter is set to TRUE + + Loads a language file. + + .. method:: line($line[, $log_errors = TRUE]) + + :param string $line: Language line key name + :param bool $log_errors: Whether to log an error if the line isn't found + :returns: string or FALSE on failure + + Fetches a single translation line from the already loaded language files, + based on the line's name. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From fd7d9caa71e960f2bec806da423eb8d93419e24c Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 18:44:23 +0200 Subject: [ci skip] Update the Unit testing library docs --- user_guide_src/source/libraries/unit_testing.rst | 97 +++++++++++++++++++++--- 1 file changed, 85 insertions(+), 12 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/unit_testing.rst b/user_guide_src/source/libraries/unit_testing.rst index 6bd91bf88..2d4a27a25 100644 --- a/user_guide_src/source/libraries/unit_testing.rst +++ b/user_guide_src/source/libraries/unit_testing.rst @@ -11,6 +11,13 @@ evaluation function and two result functions. It's not intended to be a full-blown test suite but rather a simple mechanism to evaluate your code to determine if it is producing the correct data type and result. +.. contents:: + :local: + +.. raw:: html + +
+ Initializing the Class ====================== @@ -19,16 +26,15 @@ initialized in your controller using the $this->load->library function:: $this->load->library('unit_test'); -Once loaded, the Unit Test object will be available using: $this->unit +Once loaded, the Unit Test object will be available using ``$this->unit`` Running Tests ============= -Running a test involves supplying a test and an expected result to the -following function: +Running a test involves supplying a test and an expected result in the +following way: -$this->unit->run( test, expected result, 'test name', 'notes'); -=============================================================== + $this->unit->run('test', 'expected result', 'test name', 'notes'); Where test is the result of the code you wish to test, expected result is the data type you expect, test name is an optional name you can give @@ -114,7 +120,7 @@ Enabling/Disabling Unit Testing If you would like to leave some testing in place in your scripts, but not have it run unless you need it, you can disable unit testing using:: - $this->unit->active(FALSE) + $this->unit->active(FALSE); Unit Test Display ================= @@ -150,15 +156,82 @@ template. Note the required pseudo-variables:: $str = '
Fred<strong>Blue</strong>Small
- {rows} - - - - - {/rows} + {rows} + + + + + {/rows}
{item}{result}
{item}{result}
'; $this->unit->set_template($str); .. note:: Your template must be declared **before** running the unit test process. + +*************** +Class Reference +*************** + +.. class:: CI_Unit_test + + .. method:: set_test_items($items) + + :param array $items: List of visible test items + :returns: void + + Sets a list of items that should be visible in tests. + Valid options are: + + - test_name + - test_datatype + - res_datatype + - result + - file + - line + - notes + + .. method:: run($test[, $expected = TRUE[, $test_name = 'undefined'[, $notes = '']]]) + + :param mixed $test: Test data + :param mixed $expected: Expected result + :param string $test_name: Test name + :param string $notes: Any notes to be attached to the test + :returns: string + + Runs unit tests. + + .. method:: report([$result = array()]) + + :param array $result: Array containing tests results + :returns: string + + Generates a report about already complete tests. + + .. method:: use_strict([$state = TRUE]) + + :param bool $state: Strict state flag + :returns: void + + Enables/disables strict type comparison in tests. + + .. method:: active([$state = TRUE]) + + :param bool $state: Whether to enable testing + :returns: void + + Enables/disables unit testing. + + .. method:: result([$results = array()]) + + :param array $results: Tests results list + :returns: array + + Returns raw tests results data. + + .. method:: set_template($template) + + :param string $template: Test result template + :returns: void + + Sets the template for displaying tests results. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 04535c7169aa9401a3cf09c256df8319a67b778e Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 6 Jan 2014 10:57:05 +0200 Subject: [ci skip] Update the Input library and Cookie helper docs --- user_guide_src/source/libraries/input.rst | 396 +++++++++++++++++------------- 1 file changed, 227 insertions(+), 169 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/input.rst b/user_guide_src/source/libraries/input.rst index 177f5cb64..39a0d0628 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -10,6 +10,13 @@ The Input Class serves two purposes: .. note:: This class is initialized automatically by the system so there is no need to do it manually. +.. contents:: + :local: + +.. raw:: html + +
+ Security Filtering ================== @@ -17,7 +24,7 @@ The security filtering method is called automatically when a new :doc:`controller <../general/controllers>` is invoked. It does the following: -- If $config['allow_get_array'] is FALSE (default is TRUE), destroys +- If ``$config['allow_get_array']`` is FALSE (default is TRUE), destroys the global GET array. - Destroys all global variables in the event register_globals is turned on. @@ -33,7 +40,7 @@ XSS Filtering The Input class has the ability to filter input automatically to prevent cross-site scripting attacks. If you want the filter to run automatically every time it encounters POST or COOKIE data you can -enable it by opening your application/config/config.php file and setting +enable it by opening your *application/config/config.php* file and setting this:: $config['global_xss_filtering'] = TRUE; @@ -44,7 +51,7 @@ information on using XSS Filtering in your application. Using POST, GET, COOKIE, or SERVER Data ======================================= -CodeIgniter comes with four helper methods that let you fetch POST, GET, +CodeIgniter comes with helper methods that let you fetch POST, GET, COOKIE or SERVER items. The main advantage of using the provided methods rather than fetching an item directly (``$_POST['something']``) is that the methods will check to see if the item is set and return @@ -58,262 +65,313 @@ With CodeIgniter's built in methods you can simply do this:: $something = $this->input->post('something'); -The four methods are: +The main methods are: - $this->input->post() - $this->input->get() - $this->input->cookie() - $this->input->server() -$this->input->post() -==================== +Using the php://input stream +============================ -The first parameter will contain the name of the POST item you are -looking for:: +If you want to utilize the PUT, DELETE, PATCH or other exotic request +methods, they can only be accessed via a special input stream, that +can only be read once. This isn't as easy as just reading from e.g. +the ``$_POST`` array, because it will always exist and you can try +and access multiple variables without caring that you might only have +one shot at all of the POST data. - $this->input->post('some_data'); +CodeIgniter will take care of that for you, and you can access data +from the **php://input** stream at any time, just by calling the +``input_stream()`` method:: -The method returns NULL if the item you are attempting to retrieve -does not exist. + $this->input->input_stream('key'); -The second optional parameter lets you run the data through the XSS -filter. It's enabled by setting the second parameter to boolean TRUE; +Similar to other methods such as ``get()`` and ``post()``, if the +requested data is not found, it will return NULL and you can also +decide whether to run the data through ``xss_clean()`` by passing +a boolean value as the second parameter:: -:: + $this->input->input_stream('key', TRUE); // XSS Clean + $this->input->input_stream('key', FALSE); // No XSS filter - $this->input->post('some_data', TRUE); +.. note:: You can utilize ``method()`` in order to know if you're reading + PUT, DELETE or PATCH data. -To return an array of all POST items call without any parameters. +*************** +Class Reference +*************** -To return all POST items and pass them through the XSS filter set the -first parameter NULL while setting the second parameter to boolean; +.. class:: CI_Input -The method returns NULL if there are no items in the POST. + .. method:: post([$index = NULL[, $xss_clean = FALSE]]) -:: + :param string $index: POST parameter name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: mixed - $this->input->post(NULL, TRUE); // returns all POST items with XSS filter - $this->input->post(); // returns all POST items without XSS filter + The first parameter will contain the name of the POST item you are + looking for:: -$this->input->get() -=================== + $this->input->post('some_data'); -This method is identical to the post method, only it fetches get data -:: + The method returns NULL if the item you are attempting to retrieve + does not exist. - $this->input->get('some_data', TRUE); + The second optional parameter lets you run the data through the XSS + filter. It's enabled by setting the second parameter to boolean TRUE. + :: -To return an array of all GET items call without any parameters. + $this->input->post('some_data', TRUE); -To return all GET items and pass them through the XSS filter set the -first parameter NULL while setting the second parameter to boolean; + To return an array of all POST items call without any parameters. -The method returns NULL if there are no items in the GET. + To return all POST items and pass them through the XSS filter set the + first parameter NULL while setting the second parameter to boolean TRUE. + :: -:: + $this->input->post(NULL, TRUE); // returns all POST items with XSS filter + $this->input->post(); // returns all POST items without XSS filter - $this->input->get(NULL, TRUE); // returns all GET items with XSS filter - $this->input->get(); // returns all GET items without XSS filtering + .. method:: get([$index = NULL[, $xss_clean = FALSE]]) + :param string $index: GET parameter name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: mixed -$this->input->get_post() -======================== + This method is identical to ``post()``, only it fetches GET data. + :: -This method will search through both the post and get streams for -data, looking first in post, and then in get:: + $this->input->get('some_data', TRUE); - $this->input->get_post('some_data', TRUE); + To return an array of all GET items call without any parameters. -$this->input->cookie() -====================== + To return all GET items and pass them through the XSS filter set the + first parameter NULL while setting the second parameter to boolean TRUE. + :: -This method is identical to the post method, only it fetches cookie data -:: + $this->input->get(NULL, TRUE); // returns all GET items with XSS filter + $this->input->get(); // returns all GET items without XSS filtering - $this->input->cookie('some_cookie'); - $this->input->cookie('some_cookie, TRUE); // with XSS filter + .. method:: get_post([$index = ''[, $xss_clean = FALSE]]) + :param string $index: GET/POST parameter name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: mixed -$this->input->server() -====================== + This method works the same way as ``post()`` and ``get()``, only combined. + It will search through both POST and GET streams for data, looking first + in POST, and then in GET:: -This method is identical to the above methods, only it fetches server -server data:: + $this->input->get_post('some_data', TRUE); - $this->input->server('some_data'); + .. method:: cookie([$index = ''[, $xss_clean = FALSE]]) -Using the php://input stream -============================ + :param string $index: COOKIE parameter name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: mixed -If you want to utilize the PUT, DELETE, PATCH or other exotic request -methods, they can only be accessed via a special input stream, that -can only be read once. This isn't as easy as just reading from e.g. -the ``$_POST`` array, because it will always exist and you can try -and access multiple variables without caring that you might only have -one shot at all of the POST data. + This method is identical to ``post()`` and ``get()``, only it fetches cookie + data:: -CodeIgniter will take care of that for you, and you can access data -from the **php://input** stream at any time, just by calling the -``input_stream()`` method:: + $this->input->cookie('some_cookie'); + $this->input->cookie('some_cookie, TRUE); // with XSS filter - $this->input->input_stream('key'); + .. method:: server([$index = ''[, $xss_clean = FALSE]]) -Similar to the methods above, if the requested data is not found, it -will return NULL and you can also decide whether to run the data -through ``xss_clean()`` by passing a boolean value as the second -parameter:: + :param string $index: Value name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: mixed - $this->input->input_stream('key', TRUE); // XSS Clean - $this->input->input_stream('key', FALSE); // No XSS filter + This method is identical to the ``post()``, ``get()`` and ``cookie()`` methods, + only it fetches server data (``$_SERVER``):: -.. note:: You can utilize method() in order to know if you're reading - PUT, DELETE or PATCH data. + $this->input->server('some_data'); + + .. method:: input_stream([$index = ''[, $xss_clean = FALSE]]) + + :param string $index: Key name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: mixed + + This method is identical to ``get()``, ``post()`` and ``cookie()``, + only it fetches the *php://input* stream data. + + .. method:: set_cookie($name = ''[, $value = ''[, $expire = ''[, $domain = ''[, $path = '/'[, $prefix = ''[, $secure = FALSE[, $httponly = FALSE]]]]]]]) + + :param mixed $name: Cookie name or an array of parameters + :param string $value: Cookie value + :param int $expire: Cookie expiration time in seconds + :param string $domain: Cookie domain + :param string $path: Cookie path + :param string $prefix: Cookie name prefix + :param bool $secure: Whether to only transfer the cookie through HTTPS + :param bool $httponly: Whether to only make the cookie accessible for HTTP requests (no JavaScript) + :returns: void + + Sets a cookie containing the values you specify. There are two ways to + pass information to this method so that a cookie can be set: Array + Method, and Discrete Parameters: + + Array Method + ^^^^^^^^^^^^ + + Using this method, an associative array is passed to the first + parameter:: + + $cookie = array( + 'name' => 'The Cookie Name', + 'value' => 'The Value', + 'expire' => '86500', + 'domain' => '.some-domain.com', + 'path' => '/', + 'prefix' => 'myprefix_', + 'secure' => TRUE + ); -$this->input->set_cookie() -========================== + $this->input->set_cookie($cookie); -Sets a cookie containing the values you specify. There are two ways to -pass information to this method so that a cookie can be set: Array -Method, and Discrete Parameters: + **Notes:** -Array Method -^^^^^^^^^^^^ + Only the name and value are required. To delete a cookie set it with the + expiration blank. -Using this method, an associative array is passed to the first -parameter:: + The expiration is set in **seconds**, which will be added to the current + time. Do not include the time, but rather only the number of seconds + from *now* that you wish the cookie to be valid. If the expiration is + set to zero the cookie will only last as long as the browser is open. - $cookie = array( - 'name' => 'The Cookie Name', - 'value' => 'The Value', - 'expire' => '86500', - 'domain' => '.some-domain.com', - 'path' => '/', - 'prefix' => 'myprefix_', - 'secure' => TRUE - ); + For site-wide cookies regardless of how your site is requested, add your + URL to the **domain** starting with a period, like this: + .your-domain.com - $this->input->set_cookie($cookie); + The path is usually not needed since the method sets a root path. -**Notes:** + The prefix is only needed if you need to avoid name collisions with + other identically named cookies for your server. -Only the name and value are required. To delete a cookie set it with the -expiration blank. + The secure boolean is only needed if you want to make it a secure cookie + by setting it to TRUE. -The expiration is set in **seconds**, which will be added to the current -time. Do not include the time, but rather only the number of seconds -from *now* that you wish the cookie to be valid. If the expiration is -set to zero the cookie will only last as long as the browser is open. + Discrete Parameters + ^^^^^^^^^^^^^^^^^^^ -For site-wide cookies regardless of how your site is requested, add your -URL to the **domain** starting with a period, like this: -.your-domain.com + If you prefer, you can set the cookie by passing data using individual + parameters:: -The path is usually not needed since the method sets a root path. + $this->input->set_cookie($name, $value, $expire, $domain, $path, $prefix, $secure); -The prefix is only needed if you need to avoid name collisions with -other identically named cookies for your server. -The secure boolean is only needed if you want to make it a secure cookie -by setting it to TRUE. + .. method:: ip_address() -Discrete Parameters -^^^^^^^^^^^^^^^^^^^ + :returns: string -If you prefer, you can set the cookie by passing data using individual -parameters:: + Returns the IP address for the current user. If the IP address is not + valid, the method will return '0.0.0.0':: - $this->input->set_cookie($name, $value, $expire, $domain, $path, $prefix, $secure); + echo $this->input->ip_address(); + .. important:: This method takes into account the ``$config['proxy_ips']`` + setting and will return the reported HTTP_X_FORWARDED_FOR, + HTTP_CLIENT_IP, HTTP_X_CLIENT_IP or HTTP_X_CLUSTER_CLIENT_IP + address for the allowed IP addresses. -$this->input->ip_address() -========================== + .. method:: valid_ip($ip[, $which = '']) -Returns the IP address for the current user. If the IP address is not -valid, the method will return an IP of: 0.0.0.0 + :param string $ip: IP address + :param string $which: IP protocol ('ipv4' or 'ipv6') + :returns: bool -:: + Takes an IP address as input and returns TRUE or FALSE (boolean) depending + on whether it is valid or not. - echo $this->input->ip_address(); + .. note:: The $this->input->ip_address() method above automatically + validates the IP address. -$this->input->valid_ip($ip) -=========================== + :: -Takes an IP address as input and returns TRUE or FALSE (boolean) if it -is valid or not. + if ( ! $this->input->valid_ip($ip)) + { + echo 'Not Valid'; + } + else + { + echo 'Valid'; + } -.. note:: The $this->input->ip_address() method above automatically - validates the IP address. + Accepts an optional second string parameter of 'ipv4' or 'ipv6' to specify + an IP format. The default checks for both formats. -:: + .. method:: user_agent() - if ( ! $this->input->valid_ip($ip)) - { - echo 'Not Valid'; - } - else - { - echo 'Valid'; - } + :returns: string -Accepts an optional second string parameter of 'ipv4' or 'ipv6' to specify -an IP format. The default checks for both formats. + Returns the user agent string (web browser) being used by the current user, + or NULL if it's not available. + :: -$this->input->user_agent() -========================== + echo $this->input->user_agent(); -Returns the user agent (web browser) being used by the current user. -Returns FALSE if it's not available. + See the :doc:`User Agent Class ` for methods which extract + information from the user agent string. -:: + .. method:: request_headers([$xss_clean = FALSE]) - echo $this->input->user_agent(); + :param bool $xss_clean: Whether to apply XSS filtering + :returns: array -See the :doc:`User Agent Class ` for methods which extract -information from the user agent string. + Returns an array of HTTP request headers. + Useful if running in a non-Apache environment where + `apache_request_headers() `_ + will not be supported. + :: -$this->input->request_headers() -=============================== + $headers = $this->input->request_headers(); -Useful if running in a non-Apache environment where -`apache_request_headers() `_ -will not be supported. Returns an array of headers. + .. method:: get_request_header($index[, $xss_clean = FALSE]) -:: + :param string $index: HTTP request header name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: string - $headers = $this->input->request_headers(); + Returns a single member of the request headers array or NULL + if the searched header is not found. + :: -$this->input->get_request_header() -================================== + $this->input->get_request_header('some-header', TRUE); -Returns a single member of the request headers array. + .. method:: is_ajax_request() -:: + :returns: bool - $this->input->get_request_header('some-header', TRUE); + Checks to see if the HTTP_X_REQUESTED_WITH server header has been + set, and returns boolean TRUE if it is or FALSE if not. -$this->input->is_ajax_request() -=============================== + .. method:: is_cli_request() -Checks to see if the HTTP_X_REQUESTED_WITH server header has been -set, and returns a boolean response. + :returns: bool -$this->input->is_cli_request() -============================== + Checks to see if the application was run from the command-line + interface. -Checks to see if the STDIN constant is set, which is a failsafe way to -see if PHP is being run on the command line. + .. note:: This method checks both the PHP SAPI name currently in use + and if the ``STDIN`` constant is defined, which is usually a + failsafe way to see if PHP is being run via the command line. -:: + :: - $this->input->is_cli_request() + $this->input->is_cli_request() -$this->input->method() -====================== + .. method:: method([$upper = FALSE]) -Returns the $_SERVER['REQUEST_METHOD'], optional set uppercase or lowercase (default lowercase). + :param bool $upper: Whether to return the request method name in upper or lower case + :returns: string -:: + Returns the ``$_SERVER['REQUEST_METHOD']``, with the option to set it + in uppercase or lowercase. + :: - echo $this->input->method(TRUE); // Outputs: POST - echo $this->input->method(FALSE); // Outputs: post - echo $this->input->method(); // Outputs: post \ No newline at end of file + echo $this->input->method(TRUE); // Outputs: POST + echo $this->input->method(FALSE); // Outputs: post + echo $this->input->method(); // Outputs: post \ No newline at end of file -- cgit v1.2.3-24-g4f1b From ecc7993a910bf8202ba022487288921a9c50e336 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 6 Jan 2014 11:22:31 +0200 Subject: [ci skip] Update the Form_validation library docs --- .../source/libraries/form_validation.rst | 168 ++++++++------------- 1 file changed, 61 insertions(+), 107 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/form_validation.rst b/user_guide_src/source/libraries/form_validation.rst index 5dffb1cd1..35f745fb7 100644 --- a/user_guide_src/source/libraries/form_validation.rst +++ b/user_guide_src/source/libraries/form_validation.rst @@ -340,10 +340,10 @@ commonly is:: set_value('field name') Open your myform.php view file and update the **value** in each field -using the ``set_value()`` function: +using the :func:`set_value()` function: -**Don't forget to include each field name in the ``set_value()`` -functions!** +**Don't forget to include each field name in the :func:`set_value()` +function calls!** :: @@ -380,11 +380,11 @@ Now reload your page and submit the form so that it triggers an error. Your form fields should now be re-populated .. note:: The :ref:`class-reference` section below - contains functions that permit you to re-populate menus, radio buttons, and checkboxes. -**Important Note:** If you use an array as the name of a form field, you -must supply it as an array to the function. Example:: +.. important:: If you use an array as the name of a form field, you + must supply it as an array to the function. Example:: @@ -559,7 +559,7 @@ Showing Errors Individually =========================== If you prefer to show an error message next to each form field, rather -than as a list, you can use the ``form_error()`` function. +than as a list, you can use the :func:`form_error()` function. Try it! Change your form so that it looks like this:: @@ -933,154 +933,108 @@ Name Parameter Description Class Reference *************** -.. class:: Form_validation - -The following methods are intended for use in your controller. +.. class:: CI_Form_validation -$this->form_validation->set_rules() -=================================== - - .. method:: set_rules ($field, $label = '', $rules = '') + .. method:: set_rules($field[, $label = ''[, $rules = '']]) :param string $field: The field name :param string $label: The field label :param mixed $rules: The rules, as a string with rules separated by a pipe "|", or an array or rules. - :rtype: Object + :returns: object Permits you to set validation rules, as described in the tutorial sections above: - - :ref:`setting-validation-rules` - - :ref:`saving-groups` + - :ref:`setting-validation-rules` + - :ref:`saving-groups` -$this->form_validation->run() -============================= - - .. method:: run ($group = '') + .. method:: run([$group = '']) :param string $group: The name of the validation group to run - :rtype: Boolean + :returns: bool Runs the validation routines. Returns boolean TRUE on success and FALSE on failure. You can optionally pass the name of the validation group via the method, as described in: :ref:`saving-groups` -$this->form_validation->set_message() -===================================== - - .. method:: set_message ($lang, $val = '') + .. method:: set_message($lang[, $val = '']) :param string $lang: The rule the message is for :param string $val: The message - :rtype: Object + :returns: object Permits you to set custom error messages. See :ref:`setting-error-messages` -$this->form_validation->set_data() -================================== + .. method:: set_error_delimiters([$prefix = '

'[, $suffix = '

']]) + + :param string $prefix: Error message prefix + :param string $suffix: Error message suffix + :returns: object + + Sets the default prefix and suffix for error messages. - .. method:: set_data ($data = '') + .. method:: set_data($data) :param array $data: The data to validate + :returns: void Permits you to set an array for validation, instead of using the default - $_POST array. + ``$_POST`` array. -$this->form_validation->reset_validation() -========================================== + .. method:: reset_validation() - .. method:: reset_validation () + :returns: void Permits you to reset the validation when you validate more than one array. This method should be called before validating each new array. -$this->form_validation->error_array() -===================================== + .. method:: error_array() - .. method:: error_array () - - :rtype: Array + :returns: array Returns the error messages as an array. -.. _helper-functions: - -**************** -Helper Reference -**************** - -The following helper functions are available for use in the view files -containing your forms. Note that these are procedural functions, so they -**do not** require you to prepend them with $this->form_validation. - -form_error() -============ - -Shows an individual error message associated with the field name -supplied to the function. Example:: + .. method:: error_string([$prefix = ''[, $suffix = '']]) - - -The error delimiters can be optionally specified. See the -:ref:`changing-delimiters` section above. - -validation_errors() -=================== - -Shows all error messages as a string: Example:: - - - -The error delimiters can be optionally specified. See the -:ref:`changing-delimiters` section above. - -set_value() -=========== + :param string $prefix: Error message prefix + :param string $suffix: Error message suffix + :returns: string -Permits you to set the value of an input form or textarea. You must -supply the field name via the first parameter of the function. The -second (optional) parameter allows you to set a default value for the -form. Example:: + Returns all error messages (as returned from error_array()) formatted as a + string and separated by a newline character. - + .. method:: error($field[, $prefix = ''[, $suffix = '']]) -The above form will show "0" when loaded for the first time. + :param string $field: Field name + :param string $prefix: Optional prefix + :param string $suffix: Optional suffix + :returns: string -set_select() -============ + Returns the error message for a specific field, optionally adding a + prefix and/or suffix to it (usually HTML tags). -If you use a - - - - + Checks to see if there is a rule set for the specified field. -set_checkbox() -============== - -Permits you to display a checkbox in the state it was submitted. The -first parameter must contain the name of the checkbox, the second -parameter must contain its value, and the third (optional) parameter -lets you set an item as the default (use boolean TRUE/FALSE). Example:: - - /> - /> +.. _helper-functions: -set_radio() -=========== +**************** +Helper Reference +**************** -Permits you to display radio buttons in the state they were submitted. -This function is identical to the **set_checkbox()** function above. +Please refer to the :doc:`Form Helper <../helpers/form_helper>` manual for +the following functions: -:: +- :func:`form_error()` +- :func:`validation_errors()` +- :func:`set_value()` +- :func:`set_select()` +- :func:`set_checkbox()` +- :func:`set_radio()` - /> - /> +Note that these are procedural functions, so they **do not** require you +to prepend them with ``$this->form_validation``. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 055639673a3640fb01820ab23a56697ad2d2ffff Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 6 Jan 2014 12:28:59 +0200 Subject: [ci skip] Update the Loader class docs --- user_guide_src/source/libraries/loader.rst | 531 ++++++++++++++++------------- 1 file changed, 298 insertions(+), 233 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/loader.rst b/user_guide_src/source/libraries/loader.rst index b048f4881..20e1c1d3c 100644 --- a/user_guide_src/source/libraries/loader.rst +++ b/user_guide_src/source/libraries/loader.rst @@ -11,337 +11,402 @@ can be libraries (classes) :doc:`View files <../general/views>`, .. note:: This class is initialized automatically by the system so there is no need to do it manually. -The following methods are available in this class: +.. contents:: + :local: -$this->load->library('class_name', $config, 'object name') -========================================================== +.. raw:: html -This method is used to load core classes. Where class_name is the -name of the class you want to load. +
-.. note:: We use the terms "class" and "library" interchangeably. +Application "Packages" +====================== -For example, if you would like to send email with CodeIgniter, the first -step is to load the email class within your controller:: +An application package allows for the easy distribution of complete sets +of resources in a single directory, complete with its own libraries, +models, helpers, config, and language files. It is recommended that +these packages be placed in the application/third_party directory. Below +is a sample map of an package directory. - $this->load->library('email'); +The following is an example of a directory for an application package +named "Foo Bar". -Once loaded, the library will be ready for use, using -$this->email->*some_method*(). +:: -Library files can be stored in subdirectories within the main -"libraries" directory, or within your personal application/libraries -directory. To load a file located in a subdirectory, simply include the -path, relative to the "libraries" directory. For example, if you have -file located at:: + /application/third_party/foo_bar - libraries/flavors/Chocolate.php + config/ + helpers/ + language/ + libraries/ + models/ -You will load it using:: +Whatever the purpose of the "Foo Bar" application package, it has its +own config files, helpers, language files, libraries, and models. To use +these resources in your controllers, you first need to tell the Loader +that you are going to be loading resources from a package, by adding the +package path via the ``add_package_path()`` method. - $this->load->library('flavors/chocolate'); +Package view files +------------------ -You may nest the file in as many subdirectories as you want. +By Default, package view files paths are set when ``add_package_path()`` +is called. View paths are looped through, and once a match is +encountered that view is loaded. -Additionally, multiple libraries can be loaded at the same time by -passing an array of libraries to the load method. +In this instance, it is possible for view naming collisions within +packages to occur, and possibly the incorrect package being loaded. To +ensure against this, set an optional second parameter of FALSE when +calling ``add_package_path()``. :: - $this->load->library(array('email', 'table')); + $this->load->add_package_path(APPPATH.'my_app', FALSE); + $this->load->view('my_app_index'); // Loads + $this->load->view('welcome_message'); // Will not load the default welcome_message b/c the second param to add_package_path is FALSE -Setting options ---------------- + // Reset things + $this->load->remove_package_path(APPPATH.'my_app'); -The second (optional) parameter allows you to optionally pass -configuration setting. You will typically pass these as an array:: + // Again without the second parameter: + $this->load->add_package_path(APPPATH.'my_app'); + $this->load->view('my_app_index'); // Loads + $this->load->view('welcome_message'); // Loads - $config = array ( - 'mailtype' => 'html', - 'charset' => 'utf-8, - 'priority' => '1' - ); +*************** +Class Reference +*************** - $this->load->library('email', $config); +.. class:: CI_Loader -Config options can usually also be set via a config file. Each library -is explained in detail in its own page, so please read the information -regarding each one you would like to use. + .. method:: library($library[, $params = NULL[, $object_name = NULL]]) -Please take note, when multiple libraries are supplied in an array for -the first parameter, each will receive the same parameter information. + :param mixed $library: Library name as a string or an array with multiple libraries + :param array $params: Optional array of parameters to pass to the loaded library's constructor + :param string $object_name: Optional object name to assign the library to + :returns: void -Assigning a Library to a different object name ----------------------------------------------- + This method is used to load core classes. -If the third (optional) parameter is blank, the library will usually be -assigned to an object with the same name as the library. For example, if -the library is named Calendar, it will be assigned to a variable named -$this->calendar. + .. note:: We use the terms "class" and "library" interchangeably. -If you prefer to set your own class names you can pass its value to the -third parameter:: + For example, if you would like to send email with CodeIgniter, the first + step is to load the email class within your controller:: - $this->load->library('calendar', '', 'my_calendar'); + $this->load->library('email'); - // Calendar class is now accessed using: - $this->my_calendar + Once loaded, the library will be ready for use, using ``$this->email``. -Please take note, when multiple libraries are supplied in an array for -the first parameter, this parameter is discarded. + Library files can be stored in subdirectories within the main + "libraries" directory, or within your personal *application/libraries* + directory. To load a file located in a subdirectory, simply include the + path, relative to the "libraries" directory. For example, if you have + file located at:: -$this->load->driver('parent_name', $config, 'object name') -========================================================== + libraries/flavors/Chocolate.php -This method is used to load driver libraries. Where parent_name is the -name of the parent class you want to load. + You will load it using:: -As an example, if you would like to use sessions with CodeIgniter, the first -step is to load the session driver within your controller:: + $this->load->library('flavors/chocolate'); - $this->load->driver('session'); + You may nest the file in as many subdirectories as you want. -Once loaded, the library will be ready for use, using -$this->session->*some_method*(). + Additionally, multiple libraries can be loaded at the same time by + passing an array of libraries to the load method. + :: -Driver files must be stored in a subdirectory within the main -"libraries" directory, or within your personal application/libraries -directory. The subdirectory must match the parent class name. Read the -:doc:`Drivers <../general/drivers>` description for details. + $this->load->library(array('email', 'table')); -Additionally, multiple driver libraries can be loaded at the same time by -passing an array of drivers to the load method. + Setting options + --------------- -:: + The second (optional) parameter allows you to optionally pass + configuration setting. You will typically pass these as an array:: - $this->load->driver(array('session', 'cache')); + $config = array ( + 'mailtype' => 'html', + 'charset' => 'utf-8, + 'priority' => '1' + ); -Setting options ---------------- + $this->load->library('email', $config); -The second (optional) parameter allows you to optionally pass -configuration settings. You will typically pass these as an array:: + Config options can usually also be set via a config file. Each library + is explained in detail in its own page, so please read the information + regarding each one you would like to use. - $config = array( - 'sess_driver' => 'cookie', - 'sess_encrypt_cookie' => true, - 'encryption_key' => 'mysecretkey' - ); + Please take note, when multiple libraries are supplied in an array for + the first parameter, each will receive the same parameter information. - $this->load->driver('session', $config); + Assigning a Library to a different object name + ---------------------------------------------- -Config options can usually also be set via a config file. Each library -is explained in detail in its own page, so please read the information -regarding each one you would like to use. + If the third (optional) parameter is blank, the library will usually be + assigned to an object with the same name as the library. For example, if + the library is named Calendar, it will be assigned to a variable named + ``$this->calendar``. -Assigning a Driver to a different object name ---------------------------------------------- + If you prefer to set your own class names you can pass its value to the + third parameter:: -If the third (optional) parameter is blank, the library will be assigned -to an object with the same name as the parent class. For example, if -the library is named Session, it will be assigned to a variable named -``$this->session``. + $this->load->library('calendar', NULL, 'my_calendar'); -If you prefer to set your own class names you can pass its value to the -third parameter:: + // Calendar class is now accessed using: + $this->my_calendar - $this->load->library('session', '', 'my_session'); + Please take note, when multiple libraries are supplied in an array for + the first parameter, this parameter is discarded. - // Session class is now accessed using: - $this->my_session + .. method:: driver($library[, $params = NULL[, $object_name]]) -.. note:: Driver libraries may also be loaded with the ``library()`` method, - but it is faster to use ``driver()``. + :param mixed $library: Library name as a string or an array with multiple libraries + :param array $params: Optional array of parameters to pass to the loaded library's constructor + :param string $object_name: Optional object name to assign the library to + :returns: void -$this->load->view('file_name', $data, TRUE/FALSE) -================================================= + This method is used to load driver libraries, acts very much like the + ``library()`` method. -This method is used to load your View files. If you haven't read the -:doc:`Views <../general/views>` section of the user guide it is -recommended that you do since it shows you how this method is -typically used. + As an example, if you would like to use sessions with CodeIgniter, the first + step is to load the session driver within your controller:: -The first parameter is required. It is the name of the view file you -would like to load. + $this->load->driver('session'); -.. note:: The .php file extension does not need to be specified unless - you use something other than .php. + Once loaded, the library will be ready for use, using ``$this->session``. -The second **optional** parameter can take an associative array or an -object as input, which it runs through the PHP -`extract() `_ function to convert to variables -that can be used in your view files. Again, read the -:doc:`Views <../general/views>` page to learn how this might be useful. + Driver files must be stored in a subdirectory within the main + "libraries" directory, or within your personal *application/libraries* + directory. The subdirectory must match the parent class name. Read the + :doc:`Drivers <../general/drivers>` description for details. -The third **optional** parameter lets you change the behavior of the -method so that it returns data as a string rather than sending it to -your browser. This can be useful if you want to process the data in some -way. If you set the parameter to true (boolean) it will return data. The -default behavior is false, which sends it to your browser. Remember to -assign it to a variable if you want the data returned:: + Additionally, multiple driver libraries can be loaded at the same time by + passing an array of drivers to the load method. + :: - $string = $this->load->view('myfile', '', true); + $this->load->driver(array('session', 'cache')); -$this->load->model('model_name'); -================================== + Setting options + --------------- -:: + The second (optional) parameter allows you to optionally pass + configuration settings. You will typically pass these as an array:: - $this->load->model('model_name'); + $config = array( + 'sess_driver' => 'cookie', + 'sess_encrypt_cookie' => true, + 'encryption_key' => 'mysecretkey' + ); + $this->load->driver('session', $config); -If your model is located in a subdirectory, include the relative path -from your models directory. For example, if you have a model located at -application/models/blog/queries.php you'll load it using:: + Config options can usually also be set via a config file. Each library + is explained in detail in its own page, so please read the information + regarding each one you would like to use. - $this->load->model('blog/queries'); + Assigning a Driver to a different object name + --------------------------------------------- -If you would like your model assigned to a different object name you can -specify it via the second parameter of the loading method:: + If the third (optional) parameter is blank, the library will be assigned + to an object with the same name as the parent class. For example, if + the library is named Session, it will be assigned to a variable named + ``$this->session``. - $this->load->model('model_name', 'fubar'); - $this->fubar->method(); + If you prefer to set your own class names you can pass its value to the + third parameter:: -$this->load->database('options', TRUE/FALSE) -============================================ + $this->load->library('session', '', 'my_session'); -This method lets you load the database class. The two parameters are -**optional**. Please see the :doc:`database <../database/index>` -section for more info. + // Session class is now accessed using: + $this->my_session -$this->load->vars($array) -========================= + .. method:: view($view[, $vars = array()[, return = FALSE]]) -This method takes an associative array as input and generates -variables using the PHP `extract `_ -method. This method produces the same result as using the second -parameter of the ``$this->load->view()`` method above. The reason you -might want to use this method independently is if you would like to -set some global variables in the constructor of your controller and have -them become available in any view file loaded from any method. You can -have multiple calls to this method. The data get cached and merged -into one array for conversion to variables. + :param string $view: View name + :param array $vars: An associative array of variables + :param bool $return: Whether to return the loaded view + :returns: mixed -$this->load->get_var($key) -========================== + This method is used to load your View files. If you haven't read the + :doc:`Views <../general/views>` section of the user guide it is + recommended that you do since it shows you how this method is + typically used. -This method checks the associative array of variables available to -your views. This is useful if for any reason a var is set in a library -or another controller method using ``$this->load->vars()``. + The first parameter is required. It is the name of the view file you + would like to load. -$this->load->get_vars() -======================= + .. note:: The .php file extension does not need to be specified unless + you use something other than .php. -This method retrieves all variables available to your views. + The second **optional** parameter can take an associative array or an + object as input, which it runs through the PHP + `extract() `_ function to convert to variables + that can be used in your view files. Again, read the + :doc:`Views <../general/views>` page to learn how this might be useful. -$this->load->helper('file_name') -================================ + The third **optional** parameter lets you change the behavior of the + method so that it returns data as a string rather than sending it to + your browser. This can be useful if you want to process the data in some + way. If you set the parameter to TRUE (boolean) it will return data. The + default behavior is FALSE, which sends it to your browser. Remember to + assign it to a variable if you want the data returned:: -This method loads helper files, where file_name is the name of the -file, without the _helper.php extension. + $string = $this->load->view('myfile', '', TRUE); -$this->load->file('filepath/filename', TRUE/FALSE) -================================================== + .. method:: vars($vars[, $val = '']) -This is a generic file loading method. Supply the filepath and name in -the first parameter and it will open and read the file. By default the -data is sent to your browser, just like a View file, but if you set the -second parameter to true (boolean) it will instead return the data as a -string. + :param mixed $vars: An array of variables or a single variable name + :param mixed $val: Optional variable value + :returns: void -$this->load->language('file_name') -================================== + This method takes an associative array as input and generates + variables using the PHP `extract() `_ + function. This method produces the same result as using the second + parameter of the ``$this->load->view()`` method above. The reason you + might want to use this method independently is if you would like to + set some global variables in the constructor of your controller and have + them become available in any view file loaded from any method. You can + have multiple calls to this method. The data get cached and merged + into one array for conversion to variables. -This method is an alias of the :doc:`language loading -method `: ``$this->lang->load()`` + .. method:: get_var($key) -$this->load->config('file_name') -================================ + :param string $key: Variable name key + :returns: mixed -This method is an alias of the :doc:`config file loading -method `: ``$this->config->load()`` + This method checks the associative array of variables available to + your views. This is useful if for any reason a var is set in a library + or another controller method using ``$this->load->vars()``. -Application "Packages" -====================== + .. method:: get_vars() -An application package allows for the easy distribution of complete sets -of resources in a single directory, complete with its own libraries, -models, helpers, config, and language files. It is recommended that -these packages be placed in the application/third_party directory. Below -is a sample map of an package directory + :returns: array -Sample Package "Foo Bar" Directory Map -====================================== + This method retrieves all variables available to your views. -The following is an example of a directory for an application package -named "Foo Bar". + .. method:: model($model[, $name = ''[, $db_conn = FALSE]]) -:: + :param mixed $model: Model name or an array containing multiple models + :param string $name: Optional object name to assign the model to + :param string $db_conn: Optional database configuration group to load + :returns: void - /application/third_party/foo_bar + :: - config/ - helpers/ - language/ - libraries/ - models/ + $this->load->model('model_name'); -Whatever the purpose of the "Foo Bar" application package, it has its -own config files, helpers, language files, libraries, and models. To use -these resources in your controllers, you first need to tell the Loader -that you are going to be loading resources from a package, by adding the -package path. -$this->load->add_package_path() ---------------------------------- + If your model is located in a subdirectory, include the relative path + from your models directory. For example, if you have a model located at + *application/models/blog/queries.php* you'll load it using:: -Adding a package path instructs the Loader class to prepend a given path -for subsequent requests for resources. As an example, the "Foo Bar" -application package above has a library named Foo_bar.php. In our -controller, we'd do the following:: + $this->load->model('blog/queries'); - $this->load->add_package_path(APPPATH.'third_party/foo_bar/'); - $this->load->library('foo_bar'); + If you would like your model assigned to a different object name you can + specify it via the second parameter of the loading method:: -$this->load->remove_package_path() ------------------------------------- + $this->load->model('model_name', 'fubar'); + $this->fubar->method(); -When your controller is finished using resources from an application -package, and particularly if you have other application packages you -want to work with, you may wish to remove the package path so the Loader -no longer looks in that directory for resources. To remove the last path -added, simply call the method with no parameters. + .. method:: database([$params = ''[, $return = FALSE[, $query_builder = NULL]]]) -$this->load->remove_package_path() ------------------------------------- + :param mixed $params: Database group name or configuration options + :param bool $return: Whether to return the loaded database object + :param bool $query_builder: Whether to load the Query Builder + :returns: mixed -Or to remove a specific package path, specify the same path previously -given to add_package_path() for a package.:: + This method lets you load the database class. The two parameters are + **optional**. Please see the :doc:`database <../database/index>` + section for more info. - $this->load->remove_package_path(APPPATH.'third_party/foo_bar/'); + .. method:: dbforge([$db = NULL[, $return = FALSE]]) -Package view files ------------------- + :param object $db: Database object + :param bool $return: Whether to return the Database Forge instance + :returns: mixed -By Default, package view files paths are set when add_package_path() -is called. View paths are looped through, and once a match is -encountered that view is loaded. + Loads the :doc:`Database Forge <../database/forge>` class, please refer + to that manual for more info. -In this instance, it is possible for view naming collisions within -packages to occur, and possibly the incorrect package being loaded. To -ensure against this, set an optional second parameter of FALSE when -calling add_package_path(). + .. method:: dbutil([$db = NULL[, $return = FALSE]]) -:: + :param object $db: Database object + :param bool $return: Whether to return the Database Utilities instance + :returns: mixed - $this->load->add_package_path(APPPATH.'my_app', FALSE); - $this->load->view('my_app_index'); // Loads - $this->load->view('welcome_message'); // Will not load the default welcome_message b/c the second param to add_package_path is FALSE + Loads the :doc:`Database Utilities <../database/utilities>` class, please + refer to that manual for more info. - // Reset things - $this->load->remove_package_path(APPPATH.'my_app'); + .. method:: helper($helpers) - // Again without the second parameter: - $this->load->add_package_path(APPPATH.'my_app'); - $this->load->view('my_app_index'); // Loads - $this->load->view('welcome_message'); // Loads \ No newline at end of file + :param mixed $helpers: Helper name as a string or an array containing multiple helpers + :returns: void + + This method loads helper files, where file_name is the name of the + file, without the _helper.php extension. + + .. method:: file($path[, $return = FALSE]) + + :param string $path: File path + :param bool $return: Whether to return the loaded file + :returns: mixed + + This is a generic file loading method. Supply the filepath and name in + the first parameter and it will open and read the file. By default the + data is sent to your browser, just like a View file, but if you set the + second parameter to boolean TRUE it will instead return the data as a + string. + + .. method:: language($files[, $lang = '']) + + :param mixed $files: Language file name or an array of multiple language files + :param string $lang: Language name + :returns: void + + This method is an alias of the :doc:`language loading + method `: ``$this->lang->load()``. + + .. method:: config($file[, $use_sections = FALSE[, $fail_gracefully = FALSE]]) + + :param string $file: Configuration file name + :param bool $use_sections: Whether configuration values should be loaded into their own section + :param bool $fail_gracefully: Whether to just return FALSE in case of failure + :returns: bool + + This method is an alias of the :doc:`config file loading + method `: ``$this->config->load()`` + + .. method:: add_package_path($path[, $view_cascade = TRUE]) + + :param string $path: Path to add + :param bool $view_cascade: Whether to use cascading views + :returns: void + + Adding a package path instructs the Loader class to prepend a given path + for subsequent requests for resources. As an example, the "Foo Bar" + application package above has a library named Foo_bar.php. In our + controller, we'd do the following:: + + $this->load->add_package_path(APPPATH.'third_party/foo_bar/'); + $this->load->library('foo_bar'); + + .. method:: remove_package_path([$path = '']) + + :param string $path: Path to remove + :returns: void + + When your controller is finished using resources from an application + package, and particularly if you have other application packages you + want to work with, you may wish to remove the package path so the Loader + no longer looks in that directory for resources. To remove the last path + added, simply call the method with no parameters. + + Or to remove a specific package path, specify the same path previously + given to ``add_package_path()`` for a package.:: + + $this->load->remove_package_path(APPPATH.'third_party/foo_bar/'); + + .. method:: get_package_paths([$include_base = TRUE]) + + :param bool $include_base: Whether to include BASEPATH + :returns: array + + Returns all currently available package paths. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 3a18df1337752c89952527d55fa7eb027ebd976e Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 6 Jan 2014 12:59:11 +0200 Subject: [ci skip] Update the Image_lib docs --- user_guide_src/source/libraries/image_lib.rst | 305 +++++++++++++++----------- 1 file changed, 171 insertions(+), 134 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/image_lib.rst b/user_guide_src/source/libraries/image_lib.rst index dcdccbd92..73dc1f20d 100644 --- a/user_guide_src/source/libraries/image_lib.rst +++ b/user_guide_src/source/libraries/image_lib.rst @@ -29,7 +29,7 @@ in your controller using the $this->load->library function:: $this->load->library('image_lib'); Once the library is loaded it will be ready for use. The image library -object you will use to call all functions is: $this->image_lib +object you will use to call all functions is: ``$this->image_lib`` Processing an Image =================== @@ -67,18 +67,17 @@ ratio. The thumbnail will be called *mypic_thumb.jpg* while processing images you may need to limit their maximum size, and/or adjust PHP memory limits. -Processing Functions -==================== +Processing Methods +================== -There are four available processing functions: +There are four available processing methods: - $this->image_lib->resize() - $this->image_lib->crop() - $this->image_lib->rotate() - $this->image_lib->watermark() -- $this->image_lib->clear() -These functions return boolean TRUE upon success and FALSE for failure. +These methods return boolean TRUE upon success and FALSE for failure. If they fail you can retrieve the error message using this function:: echo $this->image_lib->display_errors(); @@ -88,7 +87,7 @@ error upon failure, like this:: if ( ! $this->image_lib->resize()) { - echo $this->image_lib->display_errors(); + echo $this->image_lib->display_errors(); } .. note:: You can optionally specify the HTML formatting to be applied to @@ -97,6 +96,8 @@ error upon failure, like this:: $this->image_lib->display_errors('

', '

'); +.. _processing-preferences: + Preferences =========== @@ -162,134 +163,10 @@ Setting preferences in a config file If you prefer not to set preferences using the above method, you can instead put them into a config file. Simply create a new file called image_lib.php, add the $config array in that file. Then save the file -in: config/image_lib.php and it will be used automatically. You will -NOT need to use the $this->image_lib->initialize function if you save +in *config/image_lib.php* and it will be used automatically. You will +NOT need to use the ``$this->image_lib->initialize()``method if you save your preferences in a config file. -$this->image_lib->resize() -=========================== - -The image resizing function lets you resize the original image, create a -copy (with or without resizing), or create a thumbnail image. - -For practical purposes there is no difference between creating a copy -and creating a thumbnail except a thumb will have the thumbnail marker -as part of the name (ie, mypic_thumb.jpg). - -All preferences listed in the table above are available for this -function except these three: rotation_angle, x_axis, and y_axis. - -Creating a Thumbnail --------------------- - -The resizing function will create a thumbnail file (and preserve the -original) if you set this preference to TRUE:: - - $config['create_thumb'] = TRUE; - -This single preference determines whether a thumbnail is created or not. - -Creating a Copy ---------------- - -The resizing function will create a copy of the image file (and preserve -the original) if you set a path and/or a new filename using this -preference:: - - $config['new_image'] = '/path/to/new_image.jpg'; - -Notes regarding this preference: - -- If only the new image name is specified it will be placed in the same - folder as the original -- If only the path is specified, the new image will be placed in the - destination with the same name as the original. -- If both the path and image name are specified it will placed in its - own destination and given the new name. - -Resizing the Original Image ---------------------------- - -If neither of the two preferences listed above (create_thumb, and -new_image) are used, the resizing function will instead target the -original image for processing. - -$this->image_lib->crop() -========================= - -The cropping function works nearly identically to the resizing function -except it requires that you set preferences for the X and Y axis (in -pixels) specifying where to crop, like this:: - - $config['x_axis'] = '100'; - $config['y_axis'] = '40'; - -All preferences listed in the table above are available for this -function except these: rotation_angle, create_thumb, new_image. - -Here's an example showing how you might crop an image:: - - $config['image_library'] = 'imagemagick'; - $config['library_path'] = '/usr/X11R6/bin/'; - $config['source_image'] = '/path/to/image/mypic.jpg'; - $config['x_axis'] = '100'; - $config['y_axis'] = '60'; - - $this->image_lib->initialize($config); - - if ( ! $this->image_lib->crop()) - { - echo $this->image_lib->display_errors(); - } - -.. note:: Without a visual interface it is difficult to crop images, so this - function is not very useful unless you intend to build such an - interface. That's exactly what we did using for the photo gallery module - in ExpressionEngine, the CMS we develop. We added a JavaScript UI that - lets the cropping area be selected. - -$this->image_lib->rotate() -=========================== - -The image rotation function requires that the angle of rotation be set -via its preference:: - - $config['rotation_angle'] = '90'; - -There are 5 rotation options: - -#. 90 - rotates counter-clockwise by 90 degrees. -#. 180 - rotates counter-clockwise by 180 degrees. -#. 270 - rotates counter-clockwise by 270 degrees. -#. hor - flips the image horizontally. -#. vrt - flips the image vertically. - -Here's an example showing how you might rotate an image:: - - $config['image_library'] = 'netpbm'; - $config['library_path'] = '/usr/bin/'; - $config['source_image'] = '/path/to/image/mypic.jpg'; - $config['rotation_angle'] = 'hor'; - - $this->image_lib->initialize($config); - - if ( ! $this->image_lib->rotate()) - { - echo $this->image_lib->display_errors(); - } - -$this->image_lib->clear() -========================== - -The clear function resets all of the values used when processing an -image. You will want to call this if you are processing images in a -loop. - -:: - - $this->image_lib->clear(); - - ****************** Image Watermarking ****************** @@ -310,10 +187,12 @@ There are two types of watermarking that you can use: image (usually a transparent PNG or GIF) containing your watermark over the source image. +.. _watermarking: + Watermarking an Image ===================== -Just as with the other functions (resizing, cropping, and rotating) the +Just as with the other methods (resizing, cropping, and rotating) the general process for watermarking involves setting the preferences corresponding to the action you intend to perform, then calling the watermark function. Here is an example:: @@ -423,3 +302,161 @@ Preference Default Value Options Description coordinate to a pixel representative of the color you want to be transparent. ======================= =================== =================== ========================================================================== + +*************** +Class Reference +*************** + +.. class:: CI_Image_lib + + .. method:: initialize([$props = array()]) + + :param array $props: Image processing preferences + :returns: void + + Initializes the class for processing an image. + + .. method:: resize() + + :returns: bool + + The image resizing method lets you resize the original image, create a + copy (with or without resizing), or create a thumbnail image. + + For practical purposes there is no difference between creating a copy + and creating a thumbnail except a thumb will have the thumbnail marker + as part of the name (i.e. mypic_thumb.jpg). + + All preferences listed in the :ref:`processing-preferences` table are available for this + method except these three: *rotation_angle*, *x_axis* and *y_axis*. + + Creating a Thumbnail + -------------------- + + The resizing method will create a thumbnail file (and preserve the + original) if you set this preference to TRUE:: + + $config['create_thumb'] = TRUE; + + This single preference determines whether a thumbnail is created or not. + + Creating a Copy + --------------- + + The resizing method will create a copy of the image file (and preserve + the original) if you set a path and/or a new filename using this + preference:: + + $config['new_image'] = '/path/to/new_image.jpg'; + + Notes regarding this preference: + + - If only the new image name is specified it will be placed in the same + folder as the original + - If only the path is specified, the new image will be placed in the + destination with the same name as the original. + - If both the path and image name are specified it will placed in its + own destination and given the new name. + + Resizing the Original Image + --------------------------- + + If neither of the two preferences listed above (create_thumb, and + new_image) are used, the resizing method will instead target the + original image for processing. + + .. method:: crop() + + :returns: bool + + The cropping method works nearly identically to the resizing function + except it requires that you set preferences for the X and Y axis (in + pixels) specifying where to crop, like this:: + + $config['x_axis'] = '100'; + $config['y_axis'] = '40'; + + All preferences listed in the :ref:`processing-preferences` table are available for this + method except these: *rotation_angle*, *create_thumb* and *new_image*. + + Here's an example showing how you might crop an image:: + + $config['image_library'] = 'imagemagick'; + $config['library_path'] = '/usr/X11R6/bin/'; + $config['source_image'] = '/path/to/image/mypic.jpg'; + $config['x_axis'] = '100'; + $config['y_axis'] = '60'; + + $this->image_lib->initialize($config); + + if ( ! $this->image_lib->crop()) + { + echo $this->image_lib->display_errors(); + } + + .. note:: Without a visual interface it is difficult to crop images, so this + method is not very useful unless you intend to build such an + interface. That's exactly what we did using for the photo gallery module + in ExpressionEngine, the CMS we develop. We added a JavaScript UI that + lets the cropping area be selected. + + .. method:: rotate() + + :returns: bool + + The image rotation method requires that the angle of rotation be set + via its preference:: + + $config['rotation_angle'] = '90'; + + There are 5 rotation options: + + #. 90 - rotates counter-clockwise by 90 degrees. + #. 180 - rotates counter-clockwise by 180 degrees. + #. 270 - rotates counter-clockwise by 270 degrees. + #. hor - flips the image horizontally. + #. vrt - flips the image vertically. + + Here's an example showing how you might rotate an image:: + + $config['image_library'] = 'netpbm'; + $config['library_path'] = '/usr/bin/'; + $config['source_image'] = '/path/to/image/mypic.jpg'; + $config['rotation_angle'] = 'hor'; + + $this->image_lib->initialize($config); + + if ( ! $this->image_lib->rotate()) + { + echo $this->image_lib->display_errors(); + } + + .. method:: watermark() + + :returns: bool + + Creates a watermark over an image, please refer to the :ref:`watermarking` + section for more info. + + .. method:: clear() + + :returns: void + + The clear method resets all of the values used when processing an + image. You will want to call this if you are processing images in a + loop. + + :: + + $this->image_lib->clear(); + + .. method:: display_errors([$open = '

[, $close = '

']]) + + :param string $open: Error message opening tag + :param string $close: Error message closing tag + :returns: string + + Returns all detected errors formatted as a string. + :: + + echo $this->image_lib->diplay_errors(); \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 1ee5a997279e3f2c6fb20fb648d3620d8b1a14f5 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 6 Jan 2014 13:08:47 +0200 Subject: [ci skip] Update the Session library docs --- user_guide_src/source/libraries/sessions.rst | 60 +++++++++++++++------------- 1 file changed, 33 insertions(+), 27 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index 8e117bee6..4ce355606 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -506,7 +506,7 @@ Class Reference .. method:: load_driver($driver) :param string $driver: Driver name - :returns: object Loaded driver object + :returns: object Loads a session storage driver @@ -520,22 +520,26 @@ Class Reference .. method:: sess_destroy() Destroys current session - .. note:: This function should be the last one called, and even flash variables will no longer be available. - If you only want some items destroyed and not all, use ``unset_userdata()``. - .. method:: sess_regenerate($destroy) + .. note:: This method should be the last one called, and even flash + variables will no longer be available after it is used. + If you only want some items destroyed and not all, use + ``unset_userdata()``. - :param bool $destroy: Destroy session data flag (default: false) + .. method:: sess_regenerate([$destroy = FALSE]) + + :param bool $destroy: Whether to destroy session data :returns: void - Regenerate the current session data + Regenerate the current session data. .. method:: userdata($item) - :param string $item: name of session item + :param string $item: Session item name :returns: string - Returns a string containing the value of the passed item or NULL if the item is not found. Example:: + Returns a string containing the value of the passed item or NULL if the item is not found. + Example:: $this->session->userdata('user'); //returns example@example.com considering the set_userdata example. @@ -544,15 +548,15 @@ Class Reference :returns: array - Retruns array of userdata session items + Retruns an array with all of the session userdata items. .. method:: all_flashdata() :returns: array - Retruns array of flashdata session items + Retruns an array with all of the session flashdata items. - .. method:: set_userdata($newdata = array(), $newval) + .. method:: set_userdata($newdata[, $newval = '']) :param mixed $newdata: Item name or array of items :param mixed $newval: Item value or empty string (not required if $newdata is array) @@ -568,10 +572,10 @@ Class Reference .. method:: unset_userdata($item) - :param mixed $item: name of item or array of items + :param mixed $item: Item name or an array containing multiple items :returns: void - Unsets previously setted items from the session. Example:: + Unsets previously set items from the session. Example:: $this->session->unset_userdata('user'); //unsets 'user' from session data. @@ -581,14 +585,14 @@ Class Reference .. method:: has_userdata($item) - :param string $item: name of item + :param string $item: Item name :returns: bool Checks if an item exists in the session. - .. method:: set_flashdata($newdata = array(), $newval) + .. method:: set_flashdata($newdata[, $newval = '']) - :param mixed $newdata: Item name or array of items + :param mixed $newdata: Item name or an array of items :param mixed $newval: Item value or empty string (not required if $newdata is array) :returns: void @@ -603,26 +607,27 @@ Class Reference .. method:: keep_flashdata($item) - :param mixed $item: name of item or array of flashdata items + :param mixed $item: Item name or an array containing multiple flashdata items :returns: void - Keeps items into flashdata for one more request + Keeps items into flashdata for one more request. .. method:: flashdata($item) - :param string $item: name of session item + :param string $item: Flashdata item name :returns: string - Returns a string containing the value of the passed item or NULL if the item is not found. Example:: + Returns a string containing the value of the passed item or NULL if the item is not found. + Example:: $this->session->flashdata('message'); //returns 'Test message.' considering the set_flashdata example. - .. method:: set_tempdata($newdata = array(), $newval, $expires) + .. method:: set_tempdata($newdata[, $newval = ''[, $expire = 0]]) - :param mixed $newdata: Item name or array of items + :param mixed $newdata: Item name or array containing multiple items :param string $newval: Item value or empty string (not required if $newdata is array) - :param int $expires: lifetime in seconds (0 for default) + :param int $expire: Lifetime in seconds (0 for default) :returns: void Sets items into session tempdata example:: @@ -636,10 +641,10 @@ Class Reference .. method:: unset_tempdata($item) - :param mixed $item: name of item or array of items + :param mixed $item: Item name or an array containing multiple items :returns: void - Unsets previously setted items from the tempdata. Example:: + Unsets previously set items from tempdata. Example:: $this->session->unset_tempdata('user'); //unsets 'user' from tempdata. @@ -649,10 +654,11 @@ Class Reference .. method:: tempdata($item) - :param string $item: name of tempdata item + :param string $item: Tempdata item name :returns: string - Returns a string containing the value of the passed item or NULL if the item is not found. Example:: + Returns a string containing the value of the passed item or NULL if the item is not found. + Example:: $this->session->tempdata('message'); //returns 'Test message.' considering the set_tempdata example. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From d192953eb39845623811486a28b777b3dda93b5c Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Tue, 7 Jan 2014 12:16:16 +0200 Subject: Add basic HTTP auth info to the XML-RPC docs --- user_guide_src/source/libraries/xmlrpc.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/xmlrpc.rst b/user_guide_src/source/libraries/xmlrpc.rst index c89c69c46..91d832ff6 100644 --- a/user_guide_src/source/libraries/xmlrpc.rst +++ b/user_guide_src/source/libraries/xmlrpc.rst @@ -476,6 +476,10 @@ Class Reference $this->xmlrpc->server('http://www.sometimes.com/pings.php', 80); + Basic HTTP authentication is also supported, simply add it to the server URL:: + + $this->xmlrpc->server('http://user:pass@localhost/', 80); + .. method:: timeout($seconds = 5) :param int $seconds: timeout in seconds -- cgit v1.2.3-24-g4f1b From 0c9d08056e0816a1103b5b13b9c8e297f430d7bb Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Tue, 7 Jan 2014 13:39:23 +0200 Subject: [ci skip] Update Loader library docs for method chaining --- user_guide_src/source/libraries/loader.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/loader.rst b/user_guide_src/source/libraries/loader.rst index 20e1c1d3c..477639969 100644 --- a/user_guide_src/source/libraries/loader.rst +++ b/user_guide_src/source/libraries/loader.rst @@ -83,7 +83,7 @@ Class Reference :param mixed $library: Library name as a string or an array with multiple libraries :param array $params: Optional array of parameters to pass to the loaded library's constructor :param string $object_name: Optional object name to assign the library to - :returns: void + :returns: object This method is used to load core classes. @@ -161,7 +161,7 @@ Class Reference :param mixed $library: Library name as a string or an array with multiple libraries :param array $params: Optional array of parameters to pass to the loaded library's constructor :param string $object_name: Optional object name to assign the library to - :returns: void + :returns: object This method is used to load driver libraries, acts very much like the ``library()`` method. @@ -255,7 +255,7 @@ Class Reference :param mixed $vars: An array of variables or a single variable name :param mixed $val: Optional variable value - :returns: void + :returns: object This method takes an associative array as input and generates variables using the PHP `extract() `_ @@ -287,7 +287,7 @@ Class Reference :param mixed $model: Model name or an array containing multiple models :param string $name: Optional object name to assign the model to :param string $db_conn: Optional database configuration group to load - :returns: void + :returns: object :: @@ -338,7 +338,7 @@ Class Reference .. method:: helper($helpers) :param mixed $helpers: Helper name as a string or an array containing multiple helpers - :returns: void + :returns: object This method loads helper files, where file_name is the name of the file, without the _helper.php extension. @@ -359,7 +359,7 @@ Class Reference :param mixed $files: Language file name or an array of multiple language files :param string $lang: Language name - :returns: void + :returns: object This method is an alias of the :doc:`language loading method `: ``$this->lang->load()``. @@ -378,20 +378,20 @@ Class Reference :param string $path: Path to add :param bool $view_cascade: Whether to use cascading views - :returns: void + :returns: object Adding a package path instructs the Loader class to prepend a given path for subsequent requests for resources. As an example, the "Foo Bar" application package above has a library named Foo_bar.php. In our controller, we'd do the following:: - $this->load->add_package_path(APPPATH.'third_party/foo_bar/'); - $this->load->library('foo_bar'); + $this->load->add_package_path(APPPATH.'third_party/foo_bar/') + ->library('foo_bar'); .. method:: remove_package_path([$path = '']) :param string $path: Path to remove - :returns: void + :returns: object When your controller is finished using resources from an application package, and particularly if you have other application packages you -- cgit v1.2.3-24-g4f1b From 45082b6118a9b66e48c16582f72d4499d2c290c6 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Tue, 7 Jan 2014 15:28:17 +0200 Subject: [ci skip] Update CI_Zip::read_file() docs --- user_guide_src/source/libraries/zip.rst | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/zip.rst b/user_guide_src/source/libraries/zip.rst index ea5b46bac..535aa82d9 100644 --- a/user_guide_src/source/libraries/zip.rst +++ b/user_guide_src/source/libraries/zip.rst @@ -98,10 +98,10 @@ Class Reference $this->zip->add_dir('myfolder'); // Creates a directory called "myfolder" - .. method:: read_file($path[, $preserve_filepath = FALSE]) + .. method:: read_file($path[, $archive_filepath = FALSE]) - :param string $path: path to file - :param bool $preserve_filepath: whether to maintain the original filepath + :param string $path: Path to file + :param mixed $archive_filepath: New file name/path (string) or (boolean) whether to maintain the original filepath :returns: bool Permits you to compress a file that already exists somewhere on your server. @@ -126,6 +126,16 @@ Class Reference In the above example, photo.jpg will be placed into the *path/to/* directory. + You can also specify a new name (path included) for the added file on the fly:: + + $path = '/path/to/photo.jpg'; + $new_path = '/new/path/some_photo.jpg'; + + $this->zip->read_file($path, $new_path); + + // Download ZIP archive containing /new/path/some_photo.jpg + $this->zip->download('my_archive.zip'); + .. method:: read_dir($path[, $preserve_filepath = TRUE[, $root_path = NULL]]) :param string $path: path to directory -- cgit v1.2.3-24-g4f1b From 69e1b4f054521bc055af9e2b377a3a578fc6cadc Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Tue, 7 Jan 2014 17:29:25 +0200 Subject: [ci skip] Add a PostgreSQL CREATE TABLE sample to the Session docs From PR #2758 --- user_guide_src/source/libraries/sessions.rst | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index 4ce355606..c76bccb8c 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -400,11 +400,24 @@ session class:: KEY `last_activity_idx` (`last_activity`) ); +Or if you're using PostgreSQL:: + + CREATE TABLE ci_sessions ( + session_id varchar(40) DEFAULT '0' NOT NULL, + ip_address varchar(45) DEFAULT '0' NOT NULL, + user_agent varchar(120) NOT NULL, + last_activity bigint DEFAULT 0 NOT NULL, + user_data text NOT NULL, + PRIMARY KEY (session_id) + ); + + CREATE INDEX last_activity_idx ON ci_sessions(last_activity); + .. note:: By default the table is called ci_sessions, but you can name it anything you want as long as you update the - application/config/config.php file so that it contains the name you have - chosen. Once you have created your database table you can enable the - database option in your config.php file as follows:: + *application/config/config.php* file so that it contains the name + you have chosen. Once you have created your database table you + can enable the database option in your config.php file as follows:: $config['sess_use_database'] = TRUE; -- cgit v1.2.3-24-g4f1b From 88ebdf7ad98c2d24f9ba6b9839ab50c98cf0eb65 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Wed, 8 Jan 2014 17:28:02 +0200 Subject: [ci skip] Update the Input library and Cookie helper docs default value is now NULL --- user_guide_src/source/libraries/input.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/input.rst b/user_guide_src/source/libraries/input.rst index 39a0d0628..4d8fdaf15 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -105,7 +105,7 @@ Class Reference .. class:: CI_Input - .. method:: post([$index = NULL[, $xss_clean = FALSE]]) + .. method:: post([$index = NULL[, $xss_clean = NULL]]) :param string $index: POST parameter name :param bool $xss_clean: Whether to apply XSS filtering @@ -120,7 +120,8 @@ Class Reference does not exist. The second optional parameter lets you run the data through the XSS - filter. It's enabled by setting the second parameter to boolean TRUE. + filter. It's enabled by setting the second parameter to boolean TRUE + or by setting your ``$config['global_xss_filtering']`` to TRUE. :: $this->input->post('some_data', TRUE); @@ -132,9 +133,9 @@ Class Reference :: $this->input->post(NULL, TRUE); // returns all POST items with XSS filter - $this->input->post(); // returns all POST items without XSS filter + $this->input->post(NULL, FALSE); // returns all POST items without XSS filter - .. method:: get([$index = NULL[, $xss_clean = FALSE]]) + .. method:: get([$index = NULL[, $xss_clean = NULL]]) :param string $index: GET parameter name :param bool $xss_clean: Whether to apply XSS filtering @@ -152,9 +153,9 @@ Class Reference :: $this->input->get(NULL, TRUE); // returns all GET items with XSS filter - $this->input->get(); // returns all GET items without XSS filtering + $this->input->get(NULL, FALSE); // returns all GET items without XSS filtering - .. method:: get_post([$index = ''[, $xss_clean = FALSE]]) + .. method:: get_post([$index = ''[, $xss_clean = NULL]]) :param string $index: GET/POST parameter name :param bool $xss_clean: Whether to apply XSS filtering @@ -166,7 +167,7 @@ Class Reference $this->input->get_post('some_data', TRUE); - .. method:: cookie([$index = ''[, $xss_clean = FALSE]]) + .. method:: cookie([$index = ''[, $xss_clean = NULL]]) :param string $index: COOKIE parameter name :param bool $xss_clean: Whether to apply XSS filtering @@ -178,7 +179,7 @@ Class Reference $this->input->cookie('some_cookie'); $this->input->cookie('some_cookie, TRUE); // with XSS filter - .. method:: server([$index = ''[, $xss_clean = FALSE]]) + .. method:: server([$index = ''[, $xss_clean = NULL]]) :param string $index: Value name :param bool $xss_clean: Whether to apply XSS filtering @@ -189,7 +190,7 @@ Class Reference $this->input->server('some_data'); - .. method:: input_stream([$index = ''[, $xss_clean = FALSE]]) + .. method:: input_stream([$index = ''[, $xss_clean = NULL]]) :param string $index: Key name :param bool $xss_clean: Whether to apply XSS filtering -- cgit v1.2.3-24-g4f1b From 1f811c3b7e6bf43b329f0f2ccdbe700c6454eac9 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Thu, 9 Jan 2014 01:02:38 +0200 Subject: Add documentation for CI_User_agent::parse() --- user_guide_src/source/libraries/user_agent.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/user_agent.rst b/user_guide_src/source/libraries/user_agent.rst index 9f9676828..af76cfa6e 100644 --- a/user_guide_src/source/libraries/user_agent.rst +++ b/user_guide_src/source/libraries/user_agent.rst @@ -223,4 +223,11 @@ Class Reference :returns: array - Returns an array of character sets accepted by the user agent. \ No newline at end of file + Returns an array of character sets accepted by the user agent. + + .. method:: parse($string) + + :param string $string: A custom user-agent string + :returns: void + + Parses a custom user-agent string, different from the one reported by the current visitor. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From d0bc7eb366610ad2e68d5921b363c665ccda1ff3 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Thu, 9 Jan 2014 17:37:06 +0200 Subject: Add documentation for raw data, increment(), decrement() in Cache library Follows: 43d7fa73534c07d10a88ec120c0938d0d00a184e --- user_guide_src/source/libraries/caching.rst | 36 ++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/caching.rst b/user_guide_src/source/libraries/caching.rst index 709171dd3..5a9742378 100644 --- a/user_guide_src/source/libraries/caching.rst +++ b/user_guide_src/source/libraries/caching.rst @@ -84,11 +84,12 @@ Class Reference $foo = $this->cache->get('my_cached_item'); - .. method:: save($id, $data[, $ttl = 60]) + .. method:: save($id, $data[, $ttl = 60[, $raw = FALSE]]) :param string $id: name of the cached item :param mixed $data: the data to save :param int $ttl: Time To Live, in seconds (default 60) + :param bool $raw: Whether to store the raw value :returns: TRUE on success, FALSE on failure This method will save an item to the cache store. If saving fails, the @@ -97,6 +98,9 @@ Class Reference $this->cache->save('cache_item_id', 'data_to_cache'); + .. note:: The ``$raw`` parameter is only utilized by APC and Memcache, + in order to allow usage of ``increment()`` and ``decrement()``. + .. method:: delete($id) :param string $id: name of cached item @@ -108,6 +112,36 @@ Class Reference $this->cache->delete('cache_item_id'); + .. method:: increment($id[, $offset = 1]) + + :param string $id: Cache ID + :param int $offset: Step/value to add + :returns: New value on success, FALSE on failure + + Performs atomic incrementation of a raw stored value. + :: + + // 'iterator' has a value of 2 + + $this->cache->increment('iterator'); // 'iterator' is now 3 + + $this->cache->increment('iterator', 3); // 'iterator' is now 6 + + .. method:: decrement($id[, $offset = 1]) + + :param string $id: Cache ID + :param int $offset: Step/value to reduce by + :returns: New value on success, FALSE on failure + + Performs atomic decrementation of a raw stored value. + :: + + // 'iterator' has a value of 6 + + $this->cache->decrement('iterator'); // 'iterator' is now 5 + + $this->cache->decrement('iterator', 2); // 'iterator' is now 3 + .. method:: clean() :returns: TRUE if deleted, FALSE if the deletion fails -- cgit v1.2.3-24-g4f1b From 75b3fb26a324c71ff18fa19b2a3caa357f8133ec Mon Sep 17 00:00:00 2001 From: Connor Tumbleson Date: Sat, 11 Jan 2014 06:58:43 -0600 Subject: cleanup warnings Signed-off-by: Connor Tumbleson --- user_guide_src/source/libraries/image_lib.rst | 11 ++++------- user_guide_src/source/libraries/input.rst | 6 ++---- user_guide_src/source/libraries/loader.rst | 12 ++++-------- user_guide_src/source/libraries/sessions.rst | 3 +-- user_guide_src/source/libraries/table.rst | 10 +++++----- user_guide_src/source/libraries/trackback.rst | 7 ++++--- user_guide_src/source/libraries/typography.rst | 4 ++-- user_guide_src/source/libraries/xmlrpc.rst | 2 +- 8 files changed, 23 insertions(+), 32 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/image_lib.rst b/user_guide_src/source/libraries/image_lib.rst index 73dc1f20d..ebdeaa782 100644 --- a/user_guide_src/source/libraries/image_lib.rst +++ b/user_guide_src/source/libraries/image_lib.rst @@ -164,7 +164,7 @@ If you prefer not to set preferences using the above method, you can instead put them into a config file. Simply create a new file called image_lib.php, add the $config array in that file. Then save the file in *config/image_lib.php* and it will be used automatically. You will -NOT need to use the ``$this->image_lib->initialize()``method if you save +NOT need to use the ``$this->image_lib->initialize()`` method if you save your preferences in a config file. ****************** @@ -330,8 +330,7 @@ Class Reference All preferences listed in the :ref:`processing-preferences` table are available for this method except these three: *rotation_angle*, *x_axis* and *y_axis*. - Creating a Thumbnail - -------------------- + **Creating a Thumbnail** The resizing method will create a thumbnail file (and preserve the original) if you set this preference to TRUE:: @@ -340,8 +339,7 @@ Class Reference This single preference determines whether a thumbnail is created or not. - Creating a Copy - --------------- + **Creating a Copy** The resizing method will create a copy of the image file (and preserve the original) if you set a path and/or a new filename using this @@ -358,8 +356,7 @@ Class Reference - If both the path and image name are specified it will placed in its own destination and given the new name. - Resizing the Original Image - --------------------------- + **Resizing the Original Image** If neither of the two preferences listed above (create_thumb, and new_image) are used, the resizing method will instead target the diff --git a/user_guide_src/source/libraries/input.rst b/user_guide_src/source/libraries/input.rst index 4d8fdaf15..f5ab04883 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -215,8 +215,7 @@ Class Reference pass information to this method so that a cookie can be set: Array Method, and Discrete Parameters: - Array Method - ^^^^^^^^^^^^ + **Array Method** Using this method, an associative array is passed to the first parameter:: @@ -255,8 +254,7 @@ Class Reference The secure boolean is only needed if you want to make it a secure cookie by setting it to TRUE. - Discrete Parameters - ^^^^^^^^^^^^^^^^^^^ + **Discrete Parameters** If you prefer, you can set the cookie by passing data using individual parameters:: diff --git a/user_guide_src/source/libraries/loader.rst b/user_guide_src/source/libraries/loader.rst index 477639969..ec5a87bb4 100644 --- a/user_guide_src/source/libraries/loader.rst +++ b/user_guide_src/source/libraries/loader.rst @@ -116,8 +116,7 @@ Class Reference $this->load->library(array('email', 'table')); - Setting options - --------------- + **Setting options** The second (optional) parameter allows you to optionally pass configuration setting. You will typically pass these as an array:: @@ -137,8 +136,7 @@ Class Reference Please take note, when multiple libraries are supplied in an array for the first parameter, each will receive the same parameter information. - Assigning a Library to a different object name - ---------------------------------------------- + **Assigning a Library to a different object name** If the third (optional) parameter is blank, the library will usually be assigned to an object with the same name as the library. For example, if @@ -184,8 +182,7 @@ Class Reference $this->load->driver(array('session', 'cache')); - Setting options - --------------- + **Setting options** The second (optional) parameter allows you to optionally pass configuration settings. You will typically pass these as an array:: @@ -202,8 +199,7 @@ Class Reference is explained in detail in its own page, so please read the information regarding each one you would like to use. - Assigning a Driver to a different object name - --------------------------------------------- + **Assigning a Driver to a different object name** If the third (optional) parameter is blank, the library will be assigned to an object with the same name as the parent class. For example, if diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index c76bccb8c..010b464d3 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -509,7 +509,6 @@ your config.php file to an array including your driver name:: $config['sess_valid_drivers'] = array('sess_driver'); - *************** Class Reference *************** @@ -536,7 +535,7 @@ Class Reference .. note:: This method should be the last one called, and even flash variables will no longer be available after it is used. - If you only want some items destroyed and not all, use + If you only want some items destroyed and not all, use ``unset_userdata()``. .. method:: sess_regenerate([$destroy = FALSE]) diff --git a/user_guide_src/source/libraries/table.rst b/user_guide_src/source/libraries/table.rst index bfe457993..ed085f781 100644 --- a/user_guide_src/source/libraries/table.rst +++ b/user_guide_src/source/libraries/table.rst @@ -241,11 +241,11 @@ Class Reference Permits you to set your template. You can submit a full or partial template. :: - $template = array( - 'table_open' => '' - ); - - $this->table->set_template($template); + $template = array( + 'table_open' => '
' + ); + + $this->table->set_template($template); .. method:: set_empty($value) diff --git a/user_guide_src/source/libraries/trackback.rst b/user_guide_src/source/libraries/trackback.rst index a1667c79c..c5b01a2ee 100644 --- a/user_guide_src/source/libraries/trackback.rst +++ b/user_guide_src/source/libraries/trackback.rst @@ -8,7 +8,7 @@ receive Trackback data. If you are not familiar with Trackbacks you'll find more information `here `_. -.. content:: +.. contents:: :local: .. raw:: html @@ -64,11 +64,12 @@ Description of array data: - **url** - The URL to YOUR site where the weblog entry can be seen. - **title** - The title of your weblog entry. - **excerpt** - The content of your weblog entry. - .. note:: the Trackback class will automatically send only the first 500 characters of your - entry. It will also strip all HTML. - **blog_name** - The name of your weblog. - **charset** - The character encoding your weblog is written in. If omitted, UTF-8 will be used. +.. note:: the Trackback class will automatically send only the first 500 characters of your + entry. It will also strip all HTML. + The Trackback sending method returns TRUE/FALSE (boolean) on success or failure. If it fails, you can retrieve the error message using:: diff --git a/user_guide_src/source/libraries/typography.rst b/user_guide_src/source/libraries/typography.rst index 006e77d56..f1a825d3d 100644 --- a/user_guide_src/source/libraries/typography.rst +++ b/user_guide_src/source/libraries/typography.rst @@ -4,7 +4,7 @@ Typography Class The Typography Class provides methods that help you format text. -.. content:: +.. contents:: :local: .. raw:: html @@ -35,7 +35,7 @@ Class Reference .. attribute:: $protect_braced_quotes = FALSE - When using the Typography library in conjunction with the :doc:`Template Parser library <../parser>` + When using the Typography library in conjunction with the :doc:`Template Parser library ` it can often be desirable to protect single and double quotes within curly braces. To enable this, set the ``protect_braced_quotes`` class property to TRUE. diff --git a/user_guide_src/source/libraries/xmlrpc.rst b/user_guide_src/source/libraries/xmlrpc.rst index 91d832ff6..53fe965d7 100644 --- a/user_guide_src/source/libraries/xmlrpc.rst +++ b/user_guide_src/source/libraries/xmlrpc.rst @@ -551,7 +551,7 @@ Class Reference First parameter is the error number while the second parameter is the error message. :: - return $this->xmlrpc->send_error_message(123, 'Requested data not available'); + return $this->xmlrpc->send_error_message(123, 'Requested data not available'); .. method send_response($response) -- cgit v1.2.3-24-g4f1b From ba231aab2b26279f536a52bf4ccdb4af0d191570 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 20 Jan 2014 16:43:41 +0200 Subject: [ci skip] Replace incorrect usage of 'then', where it should be 'than' --- user_guide_src/source/libraries/cart.rst | 2 +- user_guide_src/source/libraries/image_lib.rst | 2 +- user_guide_src/source/libraries/typography.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/cart.rst b/user_guide_src/source/libraries/cart.rst index ad1955d27..0c8c0a601 100644 --- a/user_guide_src/source/libraries/cart.rst +++ b/user_guide_src/source/libraries/cart.rst @@ -245,7 +245,7 @@ the product ID and any options associated with it. In nearly all cases, updating the cart will be something the user does via the "view cart" page, so as a developer, it is unlikely that you -will ever have to concern yourself with the "row ID", other then making +will ever have to concern yourself with the "row ID", other than making sure your "view cart" page contains this information in a hidden form field, and making sure it gets passed to the update function when the update form is submitted. Please examine the construction of the "view diff --git a/user_guide_src/source/libraries/image_lib.rst b/user_guide_src/source/libraries/image_lib.rst index ebdeaa782..cde4e44dc 100644 --- a/user_guide_src/source/libraries/image_lib.rst +++ b/user_guide_src/source/libraries/image_lib.rst @@ -147,7 +147,7 @@ Preference Default Value Options pixels. If the source image size does not allow perfect resizing to those dimensions, this setting determines which axis should be used as the hard value. "auto" sets the axis automatically based on whether the - image is taller then wider, or vice versa. + image is taller than wider, or vice versa. **rotation_angle** None 90, 180, 270, vrt, hor Specifies the angle of rotation when rotating images. Note that PHP X rotates counter-clockwise, so a 90 degree rotation to the right must be specified as 270. diff --git a/user_guide_src/source/libraries/typography.rst b/user_guide_src/source/libraries/typography.rst index f1a825d3d..c1a864a3e 100644 --- a/user_guide_src/source/libraries/typography.rst +++ b/user_guide_src/source/libraries/typography.rst @@ -66,7 +66,7 @@ Class Reference $string = $this->typography->auto_typography($string); - There is one optional parameter that determines whether the parser should reduce more then two consecutive line breaks down to two. + There is one optional parameter that determines whether the parser should reduce more than two consecutive line breaks down to two. Pass boolean TRUE to enable reducing line breaks:: $string = $this->typography->auto_typography($string, TRUE); -- cgit v1.2.3-24-g4f1b From de1fe7d504898bc6a42e24b4c73da3887a9933d6 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 20 Jan 2014 17:06:16 +0200 Subject: [ci skip] Add 'Using the X class' headings to Session & Language lib docs Fixes 2 doc compile warnings --- user_guide_src/source/libraries/language.rst | 4 ++++ user_guide_src/source/libraries/sessions.rst | 4 ++++ 2 files changed, 8 insertions(+) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/language.rst b/user_guide_src/source/libraries/language.rst index 3cee5d7f6..10449b935 100644 --- a/user_guide_src/source/libraries/language.rst +++ b/user_guide_src/source/libraries/language.rst @@ -26,6 +26,10 @@ your **application/language/** directory.
+************************ +Using the Language Class +************************ + Creating Language Files ======================= diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index 3e6dcf28b..c4f861620 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -16,6 +16,10 @@ you wish, while still taking advantage of the features of the Session class.
+*********************** +Using the Session Class +*********************** + Initializing a Session ====================== -- cgit v1.2.3-24-g4f1b From 8b9dd229bc58e271cba9665d26882d8c8449ac36 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 24 Jan 2014 14:41:22 +0200 Subject: [ci skip] Update Session library docs --- user_guide_src/source/libraries/sessions.rst | 94 ++++++++++++++++------------ 1 file changed, 53 insertions(+), 41 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index f63f584a6..9e23e9b60 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -103,6 +103,23 @@ fetch. For example, to fetch the session ID you will do this:: .. note:: The function returns NULL if the item you are trying to access does not exist. +If you want to retrieve all of the existing userdata, you can simply +omit the item key parameter:: + + $this->session->userdata(); + + /** + * Produces something similar to: + * + * Array + * ( + * [session_id] => 4a5a5dca22728fb0a84364eeb405b601 + * [ip_address] => 127.0.0.1 + * [user_agent] => Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_7; + * [last_activity] => 1303142623 + * ) + */ + Adding Custom Session Data ========================== @@ -144,23 +161,6 @@ If you want to verify that a userdata value exists, call ``has_userdata()``. $this->session->has_userdata('some_name'); -Retrieving All Session Data -=========================== - -An array of all userdata can be retrieved as follows:: - - $this->session->userdata() - -And returns an associative array like the following:: - - Array - ( - [session_id] => 4a5a5dca22728fb0a84364eeb405b601 - [ip_address] => 127.0.0.1 - [user_agent] => Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_7; - [last_activity] => 1303142623 - ) - Removing Session Data ===================== @@ -246,6 +246,10 @@ To read a tempdata variable:: $this->session->tempdata('item'); +And of course, if you want to retrieve all existing tempdata:: + + $this->session->tempdata(); + If you need to remove a tempdata value before it expires, use ``unset_tempdata()``:: @@ -550,12 +554,14 @@ Class Reference Regenerate the current session data. - .. method:: userdata($item) + .. method:: userdata([$item = NULL]) :param string $item: Session item name - :returns: string + :returns: mixed + + If no parameter is passed, it will return an associative array of all existing userdata. - Returns a string containing the value of the passed item or NULL if the item is not found. + Otherwise returns a string containing the value of the passed item or NULL if the item is not found. Example:: $this->session->userdata('user'); @@ -565,13 +571,15 @@ Class Reference :returns: array - Retruns an array with all of the session userdata items. + Returns an array with all of the session userdata items. + + .. note:: This method is DEPRECATED. Use ``userdata()`` with no parameters instead. - .. method:: all_flashdata() + .. method:: &get_userdata() :returns: array - Retruns an array with all of the session flashdata items. + Returns a reference to the userdata array. .. method:: set_userdata($newdata[, $newval = '']) @@ -607,6 +615,19 @@ Class Reference Checks if an item exists in the session. + .. method:: flashdata([$item = NULL]) + + :param string $item: Flashdata item name + :returns: mixed + + If no parameter is passed, it will return an associative array of all existing flashdata. + + Otherwise returns a string containing the value of the passed item or NULL if the item is not found. + Example:: + + $this->session->flashdata('message'); + //returns 'Test message.' considering the set_flashdata example. + .. method:: set_flashdata($newdata[, $newval = '']) :param mixed $newdata: Item name or an array of items @@ -629,16 +650,18 @@ Class Reference Keeps items into flashdata for one more request. - .. method:: flashdata($item) + .. method:: tempdata([$item = NULL]) - :param string $item: Flashdata item name - :returns: string + :param string $item: Tempdata item name + :returns: mixed - Returns a string containing the value of the passed item or NULL if the item is not found. + If no parameter is passed, it will return an associative array of all existing tempdata. + + Otherwise returns a string containing the value of the passed item or NULL if the item is not found. Example:: - $this->session->flashdata('message'); - //returns 'Test message.' considering the set_flashdata example. + $this->session->tempdata('message'); + //returns 'Test message.' considering the set_tempdata example. .. method:: set_tempdata($newdata[, $newval = ''[, $expire = 0]]) @@ -667,15 +690,4 @@ Class Reference //unsets 'user' from tempdata. $this->session->unset_tempdata(array('user', 'useremail')); - //unsets both 'user' and 'useremail' from the tempdata. - - .. method:: tempdata($item) - - :param string $item: Tempdata item name - :returns: string - - Returns a string containing the value of the passed item or NULL if the item is not found. - Example:: - - $this->session->tempdata('message'); - //returns 'Test message.' considering the set_tempdata example. + //unsets both 'user' and 'useremail' from the tempdata. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 46145faeb1ba56417af53b0aa545ba8437717da6 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 7 Feb 2014 15:49:06 +0200 Subject: [ci skip] Some adjustments to the Javascript library docs --- user_guide_src/source/libraries/javascript.rst | 76 ++++++++++++++++---------- 1 file changed, 48 insertions(+), 28 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/javascript.rst b/user_guide_src/source/libraries/javascript.rst index 393d4e321..bb901ead9 100644 --- a/user_guide_src/source/libraries/javascript.rst +++ b/user_guide_src/source/libraries/javascript.rst @@ -1,31 +1,51 @@ -.. note:: This driver is experimental. Its feature set and - implementation may change in future releases. - ################ Javascript Class ################ +.. note:: This driver is experimental. Its feature set and + implementation may change in future releases. + 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. +.. contents:: + :local: + +.. raw:: html + +
+ +************************** +Using the Javascript Class +************************** + Initializing the Class ====================== To initialize the Javascript class manually in your controller -constructor, use the $this->load->library function. Currently, the only -available library is jQuery, which will automatically be loaded like -this:: +constructor, use the ``$this->load->library()`` method. Currently, +the only available library is jQuery, which will automatically be +loaded like this:: $this->load->library('javascript'); -The Javascript class also accepts parameters, js_library_driver -(string) default 'jquery' and autoload (bool) default TRUE. You may -override the defaults if you wish by sending an associative array:: +The Javascript class also accepts parameters: + +- js_library_driver (string) *default: 'jquery'* +- autoload (bool) *default: TRUE* - $this->load->library('javascript', array('js_library_driver' => 'scripto', 'autoload' => FALSE)); +You may override the defaults by sending an associative array:: + + $this->load->library( + 'javascript', + array( + 'js_library_driver' => 'scripto', + 'autoload' => FALSE + ) + ); Again, presently only 'jquery' is available. You may wish to set autoload to FALSE, though, if you do not want the jQuery library to @@ -34,7 +54,8 @@ is useful if you are loading it from a location outside of CodeIgniter, or already have the script tag in your markup. Once loaded, the jQuery library object will be available using: -$this->javascript + + $this->javascript Setup and Configuration ======================= @@ -47,8 +68,8 @@ application. As Javascript is a client side language, the library must be able to write content into your final output. This generally means a view. -You'll need to include the following variables in the sections of -your output. +You'll need to include the following variables in the ```` +sections of your output. :: @@ -56,17 +77,17 @@ your output. -$library_src, is where the actual library file will be loaded, as well -as any subsequent plugin script calls; $script_head is where specific -events, functions and other commands will be rendered. +``$library_src``, is where the actual library file will be loaded, as +well as any subsequent plugin script calls; $script_head is where +specific events, functions and other commands will be rendered. Set the path to the librarys with config items ---------------------------------------------- There are some configuration items in Javascript library. These can -either be set in application/config.php, within its own -config/javascript.php file, or within any controller usings the -set_item() function. +either be set in *application/config.php*, within its own +*config/javascript.php* file, or within any controller usings the +``set_item()`` function. An image to be used as an "ajax loader", or progress indicator. Without one, the simple text message of "loading" will appear when Ajax calls @@ -84,7 +105,7 @@ The jQuery Class ================ To initialize the jQuery class manually in your controller constructor, -use the $this->load->library function:: +use the ``$this->load->library()`` method:: $this->load->library('javascript/jquery'); @@ -96,30 +117,29 @@ library as follows:: $this->load->library('javascript/jquery', FALSE); Once loaded, the jQuery library object will be available using: -$this->jquery + + $this->jquery jQuery Events ============= Events are set using the following syntax. - :: $this->jquery->event('element_path', code_to_run()); - In the above example: - "event" is any of blur, change, click, dblclick, error, focus, hover, keydown, keyup, load, mousedown, mouseup, mouseover, mouseup, resize, scroll, or unload. -- "element_path" is any valid `jQuery - selector `_. Due to jQuery's unique +- "element_path" is any valid `jQuery selector + `_. Due to jQuery's unique selector syntax, this is usually an element id, or CSS selector. For - example "#notice_area" would effect
, and + example "#notice_area" would effect ``
``, and "#content a.notice" would effect all anchors with a class of "notice" in the div with id "content". -- "code_to_run()" is script your write yourself, or an action such as +- "``code_to_run()``" is script your write yourself, or an action such as an effect from the jQuery library below. Effects @@ -298,4 +318,4 @@ description to come calendar() ---------- -description to come +description to come \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 1e584208e420d1d864de2bc686d437ecdf0ce064 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 7 Feb 2014 21:50:36 +0200 Subject: [ci skip] Fix class reference sections of Image_lib, Parser and User agent docs --- user_guide_src/source/libraries/image_lib.rst | 7 +++++++ user_guide_src/source/libraries/parser.rst | 2 +- user_guide_src/source/libraries/user_agent.rst | 2 +- 3 files changed, 9 insertions(+), 2 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/image_lib.rst b/user_guide_src/source/libraries/image_lib.rst index cde4e44dc..cf23e397a 100644 --- a/user_guide_src/source/libraries/image_lib.rst +++ b/user_guide_src/source/libraries/image_lib.rst @@ -19,6 +19,13 @@ ImageMagick order for the script to calculate the image properties. The image processing, however, will be performed with the library you specify. +.. contents:: + :local: + +.. raw:: html + +
+ ********************** Initializing the Class ********************** diff --git a/user_guide_src/source/libraries/parser.rst b/user_guide_src/source/libraries/parser.rst index 50bde82c7..34ad65f2b 100644 --- a/user_guide_src/source/libraries/parser.rst +++ b/user_guide_src/source/libraries/parser.rst @@ -147,7 +147,7 @@ function:: Class Reference *************** -.. class: CI_Parser +.. class:: CI_Parser .. method:: parse($template, $data[, $return = FALSE]) diff --git a/user_guide_src/source/libraries/user_agent.rst b/user_guide_src/source/libraries/user_agent.rst index af76cfa6e..1b6a2988a 100644 --- a/user_guide_src/source/libraries/user_agent.rst +++ b/user_guide_src/source/libraries/user_agent.rst @@ -72,7 +72,7 @@ is available. Class Reference *************** -.. class: CI_User_agent +.. class:: CI_User_agent .. method:: is_browser([$key = NULL]) -- cgit v1.2.3-24-g4f1b From 28c2c975b118016d07212ed8e7c22ff280309f82 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Sat, 8 Feb 2014 04:27:48 +0200 Subject: [ci skip] Add return types to library docs --- user_guide_src/source/libraries/benchmark.rst | 17 +-- user_guide_src/source/libraries/caching.rst | 51 +++++---- user_guide_src/source/libraries/calendar.rst | 49 ++++---- user_guide_src/source/libraries/cart.rst | 53 +++++---- user_guide_src/source/libraries/config.rst | 49 ++++---- user_guide_src/source/libraries/email.rst | 121 ++++++++++---------- user_guide_src/source/libraries/encryption.rst | 53 +++++---- user_guide_src/source/libraries/file_uploading.rst | 60 +++++----- .../source/libraries/form_validation.rst | 58 ++++++---- user_guide_src/source/libraries/ftp.rst | 112 ++++++++++-------- user_guide_src/source/libraries/image_lib.rst | 34 +++--- user_guide_src/source/libraries/input.rst | 115 +++++++++++-------- user_guide_src/source/libraries/language.rst | 20 ++-- user_guide_src/source/libraries/loader.rst | 127 ++++++++++++--------- user_guide_src/source/libraries/migration.rst | 22 ++-- user_guide_src/source/libraries/output.rst | 59 ++++++---- user_guide_src/source/libraries/pagination.rst | 7 +- user_guide_src/source/libraries/parser.rst | 24 ++-- user_guide_src/source/libraries/security.rst | 26 +++-- user_guide_src/source/libraries/sessions.rst | 73 ++++++------ user_guide_src/source/libraries/table.rst | 35 +++--- user_guide_src/source/libraries/trackback.rst | 70 +++++++----- user_guide_src/source/libraries/typography.rst | 17 +-- user_guide_src/source/libraries/unit_testing.rst | 33 +++--- user_guide_src/source/libraries/uri.rst | 65 ++++++----- user_guide_src/source/libraries/user_agent.rst | 59 ++++++---- user_guide_src/source/libraries/xmlrpc.rst | 53 +++++---- user_guide_src/source/libraries/zip.rst | 40 ++++--- 28 files changed, 836 insertions(+), 666 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/benchmark.rst b/user_guide_src/source/libraries/benchmark.rst index 7a0313f43..ddbe04869 100644 --- a/user_guide_src/source/libraries/benchmark.rst +++ b/user_guide_src/source/libraries/benchmark.rst @@ -135,18 +135,18 @@ Class Reference .. method:: mark($name) - :param string $name: the name you wish to assign to your marker - :returns: void + :param string $name: the name you wish to assign to your marker + :rtype: void Sets a benchmark marker. - .. method:: elapsed_time([$point1 = ''[, $point2 = ''[, $decimals = 4]]]) - :param string $point1: a particular marked point - :param string $point2: a particular marked point - :param int $decimals: number of decimal places for precision - :returns: string + :param string $point1: a particular marked point + :param string $point2: a particular marked point + :param int $decimals: number of decimal places for precision + :returns: Elapsed time + :rtype: string Calculates and returns the time difference between two marked points. @@ -158,7 +158,8 @@ Class Reference .. method:: memory_usage() - :returns: string + :returns: Memory usage info + :rtype: string Simply returns the ``{memory_usage}`` marker. diff --git a/user_guide_src/source/libraries/caching.rst b/user_guide_src/source/libraries/caching.rst index 30a9fed2d..caece1aee 100644 --- a/user_guide_src/source/libraries/caching.rst +++ b/user_guide_src/source/libraries/caching.rst @@ -56,8 +56,9 @@ Class Reference .. method:: is_supported($driver) - :param string $driver: the name of the caching driver - :returns: TRUE if supported, FALSE if not + :param string $driver: the name of the caching driver + :returns: TRUE if supported, FALSE if not + :rtype: bool This method is automatically called when accessing drivers via ``$this->cache->get()``. However, if the individual drivers are used, @@ -75,8 +76,9 @@ Class Reference .. method:: get($id) - :param string $id: name of cached item - :returns: The item if it exists, FALSE if it does not + :param string $id: Cache item name + :returns: Item value or FALSE if not found + :rtype: mixed This method will attempt to fetch an item from the cache store. If the item does not exist, the method will return FALSE. @@ -86,11 +88,12 @@ Class Reference .. method:: save($id, $data[, $ttl = 60[, $raw = FALSE]]) - :param string $id: name of the cached item - :param mixed $data: the data to save - :param int $ttl: Time To Live, in seconds (default 60) - :param bool $raw: Whether to store the raw value - :returns: TRUE on success, FALSE on failure + :param string $id: Cache item name + :param mixed $data: the data to save + :param int $ttl: Time To Live, in seconds (default 60) + :param bool $raw: Whether to store the raw value + :returns: TRUE on success, FALSE on failure + :rtype: string This method will save an item to the cache store. If saving fails, the method will return FALSE. @@ -103,8 +106,9 @@ Class Reference .. method:: delete($id) - :param string $id: name of cached item - :returns: TRUE if deleted, FALSE if the deletion fails + :param string $id: name of cached item + :returns: TRUE on success, FALSE on failure + :rtype: bool This method will delete a specific item from the cache store. If item deletion fails, the method will return FALSE. @@ -114,9 +118,10 @@ Class Reference .. method:: increment($id[, $offset = 1]) - :param string $id: Cache ID - :param int $offset: Step/value to add - :returns: New value on success, FALSE on failure + :param string $id: Cache ID + :param int $offset: Step/value to add + :returns: New value on success, FALSE on failure + :rtype: mixed Performs atomic incrementation of a raw stored value. :: @@ -129,9 +134,10 @@ Class Reference .. method:: decrement($id[, $offset = 1]) - :param string $id: Cache ID - :param int $offset: Step/value to reduce by - :returns: New value on success, FALSE on failure + :param string $id: Cache ID + :param int $offset: Step/value to reduce by + :returns: New value on success, FALSE on failure + :rtype: mixed Performs atomic decrementation of a raw stored value. :: @@ -144,7 +150,8 @@ Class Reference .. method:: clean() - :returns: TRUE if deleted, FALSE if the deletion fails + :returns: TRUE on success, FALSE on failure + :rtype: bool This method will 'clean' the entire cache. If the deletion of the cache files fails, the method will return FALSE. @@ -154,7 +161,8 @@ Class Reference .. method:: cache_info() - :returns: information on the entire cache + :returns: Information on the entire cache database + :rtype: mixed This method will return information on the entire cache. :: @@ -166,8 +174,9 @@ Class Reference .. method:: get_metadata($id) - :param string $id: name of cached item - :returns: metadadta for the cached item + :param string $id: Cache item name + :returns: Metadata for the cached item + :rtype: mixed This method will return detailed information on a specific item in the cache. diff --git a/user_guide_src/source/libraries/calendar.rst b/user_guide_src/source/libraries/calendar.rst index 3879672ce..aa10e941d 100644 --- a/user_guide_src/source/libraries/calendar.rst +++ b/user_guide_src/source/libraries/calendar.rst @@ -201,48 +201,49 @@ Class Reference .. method:: initialize([$config = array()]) - :param array $config: config preferences - :returns: void + :param array $config: Configuration parameters + :rtype: void Initializes the Calendaring preferences. Accepts an associative array as input, containing display preferences. - .. method:: generate([$year = ''[, $month = ''[, $data = array()]]]) - :param int $year: the year - :param int $month: the month - :param array $data: the data to be shown in the calendar cells - :returns: string + :param int $year: Year + :param int $month: Month + :param array $data: Data to be shown in the calendar cells + :returns: HTML-formatted calendar + :rtype: string Generate the calendar. .. method:: get_month_name($month) - :param int $month: the numeric month - :returns: string + :param int $month: Month + :returns: Month name + :rtype: string Generates a textual month name based on the numeric month provided. - .. method:: get_day_names($day_type = '') - :param string $day_type: one of 'long', 'short', or 'abr' - :returns: array + :param string $day_type: 'long', 'short', or 'abr' + :returns: Array of day names + :rtype: array Returns an array of day names (Sunday, Monday, etc.) based on the type provided. Options: long, short, abr. If no ``$day_type`` is provided (or if an invalid type is provided) this method will return the "abbreviated" style. - .. method:: adjust_date($month, $year) - :param int $month: the month - :param int $year: the year - :returns: array + :param int $month: Month + :param int $year: Year + :returns: An associative array containing month and year + :rtype: array - This method makes usre that you have a valid month/year. For example, if + This method makes sure that you have a valid month/year. For example, if you submit 13 as the month, the year will increment and the month will become January:: @@ -256,22 +257,22 @@ Class Reference [year] => '2014' ) - .. method:: get_total_days($month, $year) - :param int $month: the month - :param int $year: the year - :returns: int + :param int $month: Month + :param int $year: Year + :returns: Count of days in the specified month + :rtype: int Total days in a given month:: echo $this->calendar->get_total_days(2, 2012); // 29 - .. method:: default_template() - :returns: array + :returns: An array of template values + :rtype: array Sets the default template. This method is used when you have not created your own template. @@ -279,7 +280,7 @@ Class Reference .. method:: parse_template() - :returns: void + :rtype: void Harvests the data within the template ``{pseudo-variables}`` used to display the calendar. \ No newline at end of file diff --git a/user_guide_src/source/libraries/cart.rst b/user_guide_src/source/libraries/cart.rst index 0c8c0a601..fb92c280a 100644 --- a/user_guide_src/source/libraries/cart.rst +++ b/user_guide_src/source/libraries/cart.rst @@ -275,8 +275,9 @@ Class Reference .. method:: insert([$items = array()]) - :param array $items: the items to insert into the cart - :returns: bool + :param array $items: Items to insert into the cart + :returns: TRUE on success, FALSE on failure + :rtype: bool Insert items into the cart and save it to the session table. Returns TRUE on success and FALSE on failure. @@ -284,83 +285,85 @@ Class Reference .. method:: update([$items = array()]) - :param array $items: the items to update in the cart - :returns: bool + :param array $items: Items to update in the cart + :returns: TRUE on success, FALSE on failure + :rtype: bool This method permits the quantity of a given item to be changed. Typically it is called from the "view cart" page if a user makes changes to the quantity before checkout. That array must contain the product ID and quantity for each item. - .. method:: remove($rowid) - :param int $rowid: the ID of the item to remove from the cart - :returns: bool + :param int $rowid: ID of the item to remove from the cart + :returns: TRUE on success, FALSE on failure + :rtype: bool Allows you to remove an item from the shopping cart by passing it the ``$rowid``. - .. method:: total() - :returns: int + :returns: Total amount + :rtype: int Displays the total amount in the cart. .. method:: total_items() - :returns: int + :returns: Total amount of items in the cart + :rtype: int Displays the total number of items in the cart. .. method:: contents([$newest_first = FALSE]) - :param bool $newest_first: order the array with newest first? - :returns: array + :param bool $newest_first: Whether to order the array with newest items first + :returns: An array of cart contents + :rtype: array Returns an array containing everything in the cart. You can sort the order by which the array is returned by passing it TRUE where the contents will be sorted from newest to oldest, otherwise it is sorted from oldest to newest. - .. method:: get_item($row_id) - :param int $row_id: the row ID to retrieve - :returns: array + :param int $row_id: Row ID to retrieve + :returns: Array of item data + :rtype: array Returns an array containing data for the item matching the specified row ID, or FALSE if no such item exists. - .. method:: has_options($row_id = '') - :param int $row_id: the row ID to inspect - :returns: bool + :param int $row_id: Row ID to inspect + :returns: TRUE if options exist, FALSE otherwise + :rtype: bool Returns TRUE (boolean) if a particular row in the cart contains options. - This method is designed to be used in a loop with :meth:contents:, since + This method is designed to be used in a loop with ``contents()``, since you must pass the rowid to this function, as shown in the Displaying the Cart example above. - .. method:: product_options([$row_id = '']) - :param int $row_id: the row ID - :returns: array + :param int $row_id: Row ID + :returns: Array of product options + :rtype: array Returns an array of options for a particular product. This method is - designed to be used in a loop with :meth:contents:, since you + designed to be used in a loop with ``contents()``, since you must pass the rowid to this method, as shown in the Displaying the Cart example above. - .. method:: destroy() - :returns: void + :rtype: void Permits you to destroy the cart. This method will likely be called when you are finished processing the customer's order. \ No newline at end of file diff --git a/user_guide_src/source/libraries/config.rst b/user_guide_src/source/libraries/config.rst index 8663324f2..b31815799 100644 --- a/user_guide_src/source/libraries/config.rst +++ b/user_guide_src/source/libraries/config.rst @@ -184,47 +184,44 @@ Class Reference .. method:: item($item[, $index='']) - :param string $item: config item name - :param string $index: index name, if the item is an element in a config - item that is itself an array. - :returns: mixed - the config item or FALSE if it does not exist + :param string $item: Config item name + :param string $index: Index name + :returns: Config item value or NULL if not found + :rtype: mixed Fetch a config file item. - .. method:: set_item($item, $value) - :param string $item: config item name - :param string $value: config item value - :returns: void + :param string $item: Config item name + :param string $value: Config item value + :rtype: void Sets a config file item to the specified value. - .. method:: slash_item($item) - :param string $item: config item name - :returns: moxied - the config item (slashed) or FALSE if it does not exist + :param string $item: config item name + :returns: Config item value with a trailing forward slash or NULL if not found + :rtype: mixed - This method is identical to :meth:item:, except it appends a forward + This method is identical to ``item()``, except it appends a forward slash to the end of the item, if it exists. - .. method:: load([$file = ''[, $use_sections = FALSE[, $fail_gracefully = FALSE]]]) - :param string $file: Configuration file name - :param bool $use_sections: Whether config values shoud be loaded into - their own section (index of the main config array) - :param bool $fail_gracefully: Whether to return FALSE or to display an - error message - :returns: bool + :param string $file: Configuration file name + :param bool $use_sections: Whether config values shoud be loaded into their own section (index of the main config array) + :param bool $fail_gracefully: Whether to return FALSE or to display an error message + :returns: TRUE on success, FALSE on failure + :rtype: bool Loads a configuration file. - .. method:: site_url() - :returns: string + :returns: Site URL + :rtype: string This method retrieves the URL to your site, along with the "index" value you've specified in the config file. @@ -232,10 +229,10 @@ Class Reference This method is normally accessed via the corresponding functions in the :doc:`URL Helper `. - .. method:: base_url() - :returns: string + :returns: Base URL + :rtype: string This method retrieves the URL to your site, plus an optional path such as to a stylesheet or image. @@ -243,9 +240,9 @@ Class Reference This method is normally accessed via the corresponding functions in the :doc:`URL Helper `. - .. method:: system_url() - :returns: string + :returns: URL pointing at your CI system/ directory + :rtype: string - This method retrieves the URL to your system folder. + This method retrieves the URL to your CodeIgniter system/ directory. \ No newline at end of file diff --git a/user_guide_src/source/libraries/email.rst b/user_guide_src/source/libraries/email.rst index ec639846f..3f990b628 100644 --- a/user_guide_src/source/libraries/email.rst +++ b/user_guide_src/source/libraries/email.rst @@ -145,10 +145,11 @@ Class Reference .. method:: from($from[, $name = ''[, $return_path = NULL]]) - :param string $from: "From" email address - :param string $name: "From" display name - :param string $return_path: optional email address to redirect undelivered email - :returns: CI_Email object for method chaining + :param string $from: "From" e-mail address + :param string $name: "From" display name + :param string $return_path: Optional email address to redirect undelivered e-mail to + :returns: CI_Email instance (method chaining) + :rtype: CI_Email Sets the email address and name of the person sending the email:: @@ -161,26 +162,26 @@ Class Reference .. note:: Return-Path can't be used if you've configured 'smtp' as your protocol. - .. method:: reply_to($replyto[, $name = '']) - :param string $replyto: email address for replies - :param string $name: display name for reply email address - :returns: CI_Email object for method chaining + :param string $replyto: E-mail address for replies + :param string $name: Display name for the reply-to e-mail address + :returns: CI_Email instance (method chaining) + :rtype: CI_Email Sets the reply-to address. If the information is not provided the information in the :meth:from method is used. Example:: $this->email->reply_to('you@example.com', 'Your Name'); - .. method:: to($to) - :param mixed $to: comma delimited string or array of email addresses - :returns: CI_Email object for method chaining + :param mixed $to: Comma-delimited string or an array of e-mail addresses + :returns: CI_Email instance (method chaining) + :rtype: CI_Email - Sets the email address(s) of the recipient(s). Can be a single email - , a comma-delimited list or an array:: + Sets the email address(s) of the recipient(s). Can be a single e-mail, + a comma-delimited list or an array:: $this->email->to('someone@example.com'); @@ -190,60 +191,60 @@ Class Reference :: - $list = array('one@example.com', 'two@example.com', 'three@example.com'); - - $this->email->to($list); - + $this->email->to( + array('one@example.com', 'two@example.com', 'three@example.com') + ); .. method:: cc($cc) - :param mixed $cc: comma delimited string or array of email addresses - :returns: CI_Email object for method chaining - - Sets the CC email address(s). Just like the "to", can be a single - email, a comma-delimited list or an array. + :param mixed $cc: Comma-delimited string or an array of e-mail addresses + :returns: CI_Email instance (method chaining) + :rtype: CI_Email + Sets the CC email address(s). Just like the "to", can be a single e-mail, + a comma-delimited list or an array. - .. method:: bcc($bcc, $limit = '') + .. method:: bcc($bcc[, $limit = '']) - :param mixed $bcc: comma delimited string or array of email addresses - :param int $limit: Maximum number of emails to send per batch - :returns: CI_Email object for method chaining + :param mixed $bcc: Comma-delimited string or an array of e-mail addresses + :param int $limit: Maximum number of e-mails to send per batch + :returns: CI_Email instance (method chaining) + :rtype: CI_Email - Sets the BCC email address(s). Just like the "to", can be a single - email, a comma-delimited list or an array. + Sets the BCC email address(s). Just like the ``to()`` method, can be a single + e-mail, a comma-delimited list or an array. If ``$limit`` is set, "batch mode" will be enabled, which will send the emails to batches, with each batch not exceeding the specified ``$limit``. - .. method:: subject($subject) - :param string $subject: email subject line - :returns: CI_Email object for method chaining + :param string $subject: E-mail subject line + :returns: CI_Email instance (method chaining) + :rtype: CI_Email Sets the email subject:: $this->email->subject('This is my subject'); - .. method:: message($body) - :param string $body: email body - :returns: CI_Email object for method chaining + :param string $body: E-mail message body + :returns: CI_Email instance (method chaining) + :rtype: CI_Email - Sets the email message body:: + Sets the e-mail message body:: $this->email->message('This is my message'); - .. method:: set_alt_message([$str = '']) - :param string $str: alternate email body - :returns: CI_Email object for method chaining + :param string $str: Alternative e-mail message body + :returns: CI_Email instance (method chaining) + :rtype: CI_Email - Sets the alternative email message body:: + Sets the alternative e-mail message body:: $this->email->set_alt_message('This is the alternative message'); @@ -256,19 +257,21 @@ Class Reference .. method:: set_header($header, $value) - :param string $header: header name - :param string $value: header value - :returns: void + :param string $header: Header name + :param string $value: Header value + :returns: CI_Email instance (method chaining) + :rtype: CI_Email Appends additional headers to the e-mail:: $this->email->set_header('Header1', 'Value1'); $this->email->set_header('Header2', 'Value2'); - .. method:: clear([$clear_attachments = FALSE]) - :param bool $clear_attachments: whether or not to clear attachments + :param bool $clear_attachments: Whether or not to clear attachments + :returns: CI_Email instance (method chaining) + :rtype: CI_Email Initializes all the email variables to an empty state. This method is intended for use if you run the email sending method in a loop, @@ -292,13 +295,13 @@ Class Reference $this->email->clear(TRUE); - .. method:: send([$auto_clear = TRUE]) - :param bool $auto_clear: Whether to :meth:clear automatically - :returns: bool + :param bool $auto_clear: Whether to clear message data automatically + :returns: TRUE on success, FALSE on failure + :rtype: bool - The Email sending method. Returns boolean TRUE or FALSE based on + The e-mail sending method. Returns boolean TRUE or FALSE based on success or failure, enabling it to be used conditionally:: if ( ! $this->email->send()) @@ -317,16 +320,16 @@ Class Reference .. note:: In order to use the ``print_debugger()`` method, you need to avoid clearing the email parameters. - .. method:: attach($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]]) - :param string $filename: name of the file - :param string $disposition: 'disposition' of the attachment. Most + :param string $filename: File name + :param string $disposition: 'disposition' of the attachment. Most email clients make their own decision regardless of the MIME specification used here. https://www.iana.org/assignments/cont-disp/cont-disp.xhtml - :param string $newname: custom name to use for the file in the email - :param string $mime: MIME type to use (useful for buffered data) - :returns: CI_Email object for method chaining + :param string $newname: Custom file name to use in the e-mail + :param string $mime: MIME type to use (useful for buffered data) + :returns: CI_Email instance (method chaining) + :rtype: CI_Email Enables you to send an attachment. Put the file path/name in the first parameter. For multiple attachments use the method multiple times. @@ -357,8 +360,9 @@ Class Reference .. method:: attachment_cid($filename) - :param string $filename: Existing attachment filename - :returns: string + :param string $filename: Existing attachment filename + :returns: Attachment Content-ID or FALSE if not found + :rtype: string Sets and returns an attachment's Content-ID, which enables your to embed an inline (picture) attachment into HTML. First parameter must be the already attached file name. @@ -378,8 +382,9 @@ Class Reference .. method:: print_debugger([$include = array('headers', 'subject', 'body')]) - :param array $include: Which parts of the message to print out - :returns: string + :param array $include: Which parts of the message to print out + :returns: Formatted debug data + :rtype: string Returns a string containing any server messages, the email headers, and the email messsage. Useful for debugging. diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst index f7235bfd2..567a1e990 100644 --- a/user_guide_src/source/libraries/encryption.rst +++ b/user_guide_src/source/libraries/encryption.rst @@ -81,11 +81,12 @@ Class Reference .. class:: CI_Encrypt - .. method:: encode($string, $key = '') + .. method:: encode($string[, $key = '']) - :param string $string: contents to be encrypted - :param string $key: encryption key - :returns: string + :param string $string: Data to encrypt + :param string $key: Encryption key + :returns: Encrypted string + :rtype: string Performs the data encryption and returns it as a string. Example:: @@ -101,12 +102,12 @@ Class Reference $encrypted_string = $this->encrypt->encode($msg, $key); + .. method:: decode($string[, $key = '']) - .. method:: decode($string, $key = '') - - :param string $string: contents to be decrypted - :param string $key: encryption key - :returns: string + :param string $string: String to decrypt + :param string $key: Encryption key + :returns: Plain-text string + :rtype: string Decrypts an encoded string. Example:: @@ -122,46 +123,44 @@ Class Reference $encrypted_string = $this->encrypt->decode($msg, $key); - .. method:: set_cipher($cipher) - :param int $cipher: valid PHP Mcrypt cypher constant - :returns: CI_Encrypt object for method chaining + :param int $cipher: Valid PHP MCrypt cypher constant + :returns: CI_Encrypt instance (method chaining) + :rtype: CI_Encrypt Permits you to set an Mcrypt cipher. By default it uses - **MCRYPT_RIJNDAEL_256**. Example:: + ``MCRYPT_RIJNDAEL_256``. Example:: $this->encrypt->set_cipher(MCRYPT_BLOWFISH); - Please visit php.net for a list of `available - ciphers `_. + Please visit php.net for a list of `available ciphers `_. - If you'd like to manually test whether your server supports Mcrypt you + If you'd like to manually test whether your server supports MCrypt you can use:: - echo ( ! function_exists('mcrypt_encrypt')) ? 'Nope' : 'Yup'; - + echo extension_loaded('mcrypt') ? 'Yup' : 'Nope'; .. method:: set_mode($mode) - :param int $mode: valid PHP Mcrypt mode constant - :returns: CI_Encrypt object for method chaining + :param int $mode: Valid PHP MCrypt mode constant + :returns: CI_Encrypt instance (method chaining) + :rtype: CI_Encrypt Permits you to set an Mcrypt mode. By default it uses **MCRYPT_MODE_CBC**. Example:: $this->encrypt->set_mode(MCRYPT_MODE_CFB); - Please visit php.net for a list of `available - modes `_. - + Please visit php.net for a list of `available modes `_. .. method:: encode_from_legacy($string[, $legacy_mode = MCRYPT_MODE_ECB[, $key = '']]) - :param string $string: contents to be encrypted - :param int $legacy_mode: valid PHP Mcrypt cypher constant - :param string $key: encryption key - :returns: string + :param string $string: String to encrypt + :param int $legacy_mode: Valid PHP MCrypt cipher constant + :param string $key: Encryption key + :returns: Newly encrypted string + :rtype: string Enables you to re-encode data that was originally encrypted with CodeIgniter 1.x to be compatible with the Encryption library in diff --git a/user_guide_src/source/libraries/file_uploading.rst b/user_guide_src/source/libraries/file_uploading.rst index d679d8aa2..d7ba3a6c1 100644 --- a/user_guide_src/source/libraries/file_uploading.rst +++ b/user_guide_src/source/libraries/file_uploading.rst @@ -256,8 +256,9 @@ Class Reference .. method:: do_upload([$field = 'userfile']) - :param string $field: name of the form field - :returns: bool + :param string $field: Name of the form field + :returns: TRUE on success, FALSE on failure + :rtype: bool Performs the upload based on the preferences you've set. @@ -275,12 +276,12 @@ Class Reference $field_name = "some_field_name"; $this->upload->do_upload($field_name); - .. method:: display_errors([$open = '

'[, $close = '

']]) - :param string $open: Opening markup - :param string $close: Closing markup - :returns: string + :param string $open: Opening markup + :param string $close: Closing markup + :returns: Formatted error message(s) + :rtype: string Retrieves any error messages if the ``do_upload()`` method returned false. The method does not echo automatically, it returns the data so @@ -296,8 +297,9 @@ Class Reference .. method:: data([$index = NULL]) - :param string $data: element to return instead of the full array - :returns: mixed + :param string $data: Element to return instead of the full array + :returns: Information about the uploaded file + :rtype: mixed This is a helper method that returns an array containing all of the data related to the file you uploaded. Here is the array prototype:: @@ -324,25 +326,23 @@ Class Reference $this->upload->data('file_name'); // Returns: mypic.jpg - **Explanation** - - Here is an explanation of the above array items. - - ================ ================================================ - Item Description - ================ ================================================ - file_name The name of the file that was uploaded including the file extension. - file_type The file's Mime type - file_path The absolute server path to the file - full_path The absolute server path including the file name - raw_name The file name without the extension - orig_name The original file name. This is only useful if you use the encrypted name option. - client_name The file name as supplied by the client user agent, prior to any file name preparation or incrementing. - file_ext The file extension with period - file_size The file size in kilobytes - is_image Whether the file is an image or not. 1 = image. 0 = not. - image_width Image width. - image_height Image height - image_type Image type. Typically the file extension without the period. - image_size_str A string containing the width and height. Useful to put into an image tag. - ================ ================================================ + Here's a table explaining the above-displayed array items: + + ================ ==================================================================================================== + Item Description + ================ ==================================================================================================== + file_name Name of the file that was uploaded, including the filename extension + file_type File MIME type identifier + file_path Absolute server path to the file + full_path Absolute server path, including the file name + raw_name File name, without the extension + orig_name Original file name. This is only useful if you use the encrypted name option. + client_name File name as supplied by the client user agent, prior to any file name preparation or incrementing + file_ext Filename extension, period included + file_size File size in kilobytes + is_image Whether the file is an image or not. 1 = image. 0 = not. + image_width Image width + image_height Image height + image_type Image type (usually the file name extension without the period) + image_size_str A string containing the width and height (useful to put into an image tag) + ================ ==================================================================================================== \ No newline at end of file diff --git a/user_guide_src/source/libraries/form_validation.rst b/user_guide_src/source/libraries/form_validation.rst index 42422f9d7..ae66cefb3 100644 --- a/user_guide_src/source/libraries/form_validation.rst +++ b/user_guide_src/source/libraries/form_validation.rst @@ -958,10 +958,11 @@ Class Reference .. method:: set_rules($field[, $label = ''[, $rules = '']]) - :param string $field: The field name - :param string $label: The field label - :param mixed $rules: The rules, as a string with rules separated by a pipe "|", or an array or rules. - :returns: object + :param string $field: Field name + :param string $label: Field label + :param mixed $rules: Validation rules, as a string list separated by a pipe "|", or as an array or rules + :returns: CI_Form_validation instance (method chaining) + :rtype: CI_Form_validation Permits you to set validation rules, as described in the tutorial sections above: @@ -971,8 +972,9 @@ Class Reference .. method:: run([$group = '']) - :param string $group: The name of the validation group to run - :returns: bool + :param string $group: The name of the validation group to run + :returns: TRUE on success, FALSE if validation failed + :rtype: bool Runs the validation routines. Returns boolean TRUE on success and FALSE on failure. You can optionally pass the name of the validation group via @@ -980,64 +982,70 @@ Class Reference .. method:: set_message($lang[, $val = '']) - :param string $lang: The rule the message is for - :param string $val: The message - :returns: object + :param string $lang: The rule the message is for + :param string $val: The message + :returns: CI_Form_validation instance (method chaining) + :rtype: CI_Form_validation Permits you to set custom error messages. See :ref:`setting-error-messages` .. method:: set_error_delimiters([$prefix = '

'[, $suffix = '

']]) - :param string $prefix: Error message prefix - :param string $suffix: Error message suffix - :returns: object + :param string $prefix: Error message prefix + :param string $suffix: Error message suffix + :returns: CI_Form_validation instance (method chaining) + :rtype: CI_Form_validation Sets the default prefix and suffix for error messages. .. method:: set_data($data) - :param array $data: The data to validate - :returns: void + :param array $data: Array of data validate + :rtype: void Permits you to set an array for validation, instead of using the default ``$_POST`` array. .. method:: reset_validation() - :returns: void + :rtype: void Permits you to reset the validation when you validate more than one array. This method should be called before validating each new array. .. method:: error_array() - :returns: array + :returns: Array of error messages + :rtype: array Returns the error messages as an array. .. method:: error_string([$prefix = ''[, $suffix = '']]) - :param string $prefix: Error message prefix - :param string $suffix: Error message suffix - :returns: string + :param string $prefix: Error message prefix + :param string $suffix: Error message suffix + :returns: Error messages as a string + :rtype: string Returns all error messages (as returned from error_array()) formatted as a string and separated by a newline character. .. method:: error($field[, $prefix = ''[, $suffix = '']]) - :param string $field: Field name - :param string $prefix: Optional prefix - :param string $suffix: Optional suffix - :returns: string + :param string $field: Field name + :param string $prefix: Optional prefix + :param string $suffix: Optional suffix + :returns: Error message string + :rtype: string Returns the error message for a specific field, optionally adding a prefix and/or suffix to it (usually HTML tags). .. method:: has_rule($field) - :param string $field: Field name - :returns: bool + :param string $field: Field name + :returns: TRUE if the field has rules set, FALSE if not + :rtype: bool Checks to see if there is a rule set for the specified field. diff --git a/user_guide_src/source/libraries/ftp.rst b/user_guide_src/source/libraries/ftp.rst index c587869db..dd9440443 100644 --- a/user_guide_src/source/libraries/ftp.rst +++ b/user_guide_src/source/libraries/ftp.rst @@ -94,8 +94,9 @@ Class Reference .. method:: connect([$config = array()]) - :param array $config: Connection values - :returns: bool + :param array $config: Connection values + :returns: TRUE on success, FALSE on failure + :rtype: bool Connects and logs into to the FTP server. Connection preferences are set by passing an array to the function, or you can store them in a config @@ -123,24 +124,25 @@ Class Reference **Available connection options** - ================== =================================== - Option Name Description - ================== =================================== - **hostname** the FTP hostname. Usually something like: ftp.example.com - **username** the FTP username - **password** the FTP password - **port** The port number. Set to 21 by default. - **debug** TRUE/FALSE (boolean). Whether to enable debugging to display error messages. - **passive** TRUE/FALSE (boolean). Whether to use passive mode. Passive is set automatically by default. - ================== =================================== + ============== =============== ============================================================================= + Option name Default value Description + ============== =============== ============================================================================= + **hostname** n/a FTP hostname (usually something like: ftp.example.com) + **username** n/a FTP username + **password** n/a FTP password + **port** 21 FTP server port number + **debug** FALSE TRUE/FALSE (boolean): Whether to enable debugging to display error messages + **passive** TRUE TRUE/FALSE (boolean): Whether to use passive mode + ============== =============== ============================================================================= .. method:: upload($locpath, $rempath[, $mode = 'auto'[, $permissions = NULL]]) - :param string $locpath: Local file path - :param string $rempath: Remote file path - :param string $mode: FTP mode, defaults to 'auto' (options are: 'auto', 'binary', 'ascii') - :param int $permissions: File permissions (octal) - :returns: bool + :param string $locpath: Local file path + :param string $rempath: Remote file path + :param string $mode: FTP mode, defaults to 'auto' (options are: 'auto', 'binary', 'ascii') + :param int $permissions: File permissions (octal) + :returns: TRUE on success, FALSE on failure + :rtype: bool Uploads a file to your server. You must supply the local path and the remote path, and you can optionally set the mode and permissions. @@ -154,10 +156,11 @@ Class Reference .. method:: download($rempath, $locpath[, $mode = 'auto']) - :param string $rempath: Remote file path - :param string $locpath: Local file path - :param string $mode: FTP mode, defaults to 'auto' (options are: 'auto', 'binary', 'ascii') - :returns: bool + :param string $rempath: Remote file path + :param string $locpath: Local file path + :param string $mode: FTP mode, defaults to 'auto' (options are: 'auto', 'binary', 'ascii') + :returns: TRUE on success, FALSE on failure + :rtype: bool Downloads a file from your server. You must supply the remote path and the local path, and you can optionally set the mode. Example:: @@ -166,14 +169,16 @@ Class Reference If 'auto' mode is used it will base the mode on the file extension of the source file. - Returns FALSE if the download does not execute successfully (including if PHP does not have permission to write the local file). + Returns FALSE if the download does not execute successfully + (including if PHP does not have permission to write the local file). - .. method:: rename($old_file, $new_file, $move = FALSE) + .. method:: rename($old_file, $new_file[, $move = FALSE]) - :param string $old_file: Old file name - :param string $new_file: New file name - :param bool $move: Whether a move is being performed - :returns: bool + :param string $old_file: Old file name + :param string $new_file: New file name + :param bool $move: Whether a move is being performed + :returns: TRUE on success, FALSE on failure + :rtype: bool Permits you to rename a file. Supply the source file name/path and the new file name/path. :: @@ -183,9 +188,10 @@ Class Reference .. method:: move($old_file, $new_file) - :param string $old_file: Old file name - :param string $new_file: New file name - :returns: bool + :param string $old_file: Old file name + :param string $new_file: New file name + :returns: TRUE on success, FALSE on failure + :rtype: bool Lets you move a file. Supply the source and destination paths:: @@ -196,8 +202,9 @@ Class Reference .. method:: delete_file($filepath) - :param string $filepath: Path to file to delete - :returns: bool + :param string $filepath: Path to file to delete + :returns: TRUE on success, FALSE on failure + :rtype: bool Lets you delete a file. Supply the source path with the file name. :: @@ -206,8 +213,9 @@ Class Reference .. method:: delete_dir($filepath) - :param string $filepath: Path to directory to delete - :returns: bool + :param string $filepath: Path to directory to delete + :returns: TRUE on success, FALSE on failure + :rtype: bool Lets you delete a directory and everything it contains. Supply the source path to the directory with a trailing slash. @@ -223,8 +231,9 @@ Class Reference .. method:: list_files([$path = '.']) - :param string $path: Directory path - :returns: array or FALSE on failure + :param string $path: Directory path + :returns: An array list of files or FALSE on failure + :rtype: array Permits you to retrieve a list of files on your server returned as an array. You must supply the path to the desired directory. @@ -235,9 +244,10 @@ Class Reference .. method:: mirror($locpath, $rempath) - :param string $locpath: Local path - :param string $rempath: Remote path - :returns: bool + :param string $locpath: Local path + :param string $rempath: Remote path + :returns: TRUE on success, FALSE on failure + :rtype: bool Recursively reads a local folder and everything it contains (including sub-folders) and creates a mirror via FTP based on it. Whatever the @@ -248,9 +258,10 @@ Class Reference .. method:: mkdir($path[, $permissions = NULL]) - :param string $path: Path to directory to create - :param int $permissions: Permissions (octal) - :returns: bool + :param string $path: Path to directory to create + :param int $permissions: Permissions (octal) + :returns: TRUE on success, FALSE on failure + :rtype: bool Lets you create a directory on your server. Supply the path ending in the folder name you wish to create, with a trailing slash. @@ -263,9 +274,10 @@ Class Reference .. method:: chmod($path, $perm) - :param string $path: Path to alter permissions for - :param int $perm: Permissions (octal) - :returns: bool + :param string $path: Path to alter permissions for + :param int $perm: Permissions (octal) + :returns: TRUE on success, FALSE on failure + :rtype: bool Permits you to set file permissions. Supply the path to the file or directory you wish to alter permissions on:: @@ -275,9 +287,10 @@ Class Reference .. method:: changedir($path[, $suppress_debug = FALSE]) - :param string $path: Directory path - :param bool $suppress_debug: Whether to turn off debug messages for this command - :returns: bool + :param string $path: Directory path + :param bool $suppress_debug: Whether to turn off debug messages for this command + :returns: TRUE on success, FALSE on failure + :rtype: bool Changes the current working directory to the specified path. @@ -286,7 +299,8 @@ Class Reference .. method:: close() - :returns: bool + :returns: TRUE on success, FALSE on failure + :rtype: bool Closes the connection to your server. It's recommended that you use this when you are finished uploading. \ No newline at end of file diff --git a/user_guide_src/source/libraries/image_lib.rst b/user_guide_src/source/libraries/image_lib.rst index cf23e397a..16acf090b 100644 --- a/user_guide_src/source/libraries/image_lib.rst +++ b/user_guide_src/source/libraries/image_lib.rst @@ -318,14 +318,16 @@ Class Reference .. method:: initialize([$props = array()]) - :param array $props: Image processing preferences - :returns: void + :param array $props: Image processing preferences + :returns: TRUE on success, FALSE in case of invalid settings + :rtype: bool Initializes the class for processing an image. .. method:: resize() - :returns: bool + :returns: TRUE on success, FALSE on failure + :rtype: bool The image resizing method lets you resize the original image, create a copy (with or without resizing), or create a thumbnail image. @@ -371,14 +373,15 @@ Class Reference .. method:: crop() - :returns: bool + :returns: TRUE on success, FALSE on failure + :rtype: bool The cropping method works nearly identically to the resizing function except it requires that you set preferences for the X and Y axis (in pixels) specifying where to crop, like this:: - $config['x_axis'] = '100'; - $config['y_axis'] = '40'; + $config['x_axis'] = 100; + $config['y_axis'] = 40; All preferences listed in the :ref:`processing-preferences` table are available for this method except these: *rotation_angle*, *create_thumb* and *new_image*. @@ -388,8 +391,8 @@ Class Reference $config['image_library'] = 'imagemagick'; $config['library_path'] = '/usr/X11R6/bin/'; $config['source_image'] = '/path/to/image/mypic.jpg'; - $config['x_axis'] = '100'; - $config['y_axis'] = '60'; + $config['x_axis'] = 100; + $config['y_axis'] = 60; $this->image_lib->initialize($config); @@ -406,7 +409,8 @@ Class Reference .. method:: rotate() - :returns: bool + :returns: TRUE on success, FALSE on failure + :rtype: bool The image rotation method requires that the angle of rotation be set via its preference:: @@ -437,14 +441,15 @@ Class Reference .. method:: watermark() - :returns: bool + :returns: TRUE on success, FALSE on failure + :rtype: bool Creates a watermark over an image, please refer to the :ref:`watermarking` section for more info. .. method:: clear() - :returns: void + :rtype: void The clear method resets all of the values used when processing an image. You will want to call this if you are processing images in a @@ -456,9 +461,10 @@ Class Reference .. method:: display_errors([$open = '

[, $close = '

']]) - :param string $open: Error message opening tag - :param string $close: Error message closing tag - :returns: string + :param string $open: Error message opening tag + :param string $close: Error message closing tag + :returns: Error messages + :rtype: string Returns all detected errors formatted as a string. :: diff --git a/user_guide_src/source/libraries/input.rst b/user_guide_src/source/libraries/input.rst index 8a83207af..7ebf0e1c7 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -68,10 +68,10 @@ With CodeIgniter's built in methods you can simply do this:: The main methods are: -- $this->input->post() -- $this->input->get() -- $this->input->cookie() -- $this->input->server() +- ``$this->input->post()`` +- ``$this->input->get()`` +- ``$this->input->cookie()`` +- ``$this->input->server()`` Using the php://input stream ============================ @@ -108,9 +108,10 @@ Class Reference .. method:: post([$index = NULL[, $xss_clean = NULL]]) - :param string $index: POST parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $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 The first parameter will contain the name of the POST item you are looking for:: @@ -138,9 +139,10 @@ Class Reference .. method:: get([$index = NULL[, $xss_clean = NULL]]) - :param string $index: GET parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $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 This method is identical to ``post()``, only it fetches GET data. :: @@ -158,9 +160,10 @@ Class Reference .. method:: post_get([$index = ''[, $xss_clean = NULL]]) - :param string $index: POST/GET parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $index: POST/GET parameter name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: POST/GET value if found, NULL if not + :rtype: mixed This method works the same way as ``post()`` and ``get()``, only combined. It will search through both POST and GET streams for data, looking in POST @@ -170,9 +173,10 @@ Class Reference .. method:: get_post([$index = ''[, $xss_clean = NULL]]) - :param string $index: GET/POST parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $index: GET/POST parameter name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: GET/POST value if found, NULL if not + :rtype: mixed This method works the same way as ``post_get()`` only it looks for GET data first. @@ -184,9 +188,10 @@ Class Reference .. method:: cookie([$index = ''[, $xss_clean = NULL]]) - :param string $index: COOKIE parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $index: COOKIE parameter 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 This method is identical to ``post()`` and ``get()``, only it fetches cookie data:: @@ -196,9 +201,10 @@ Class Reference .. method:: server([$index = ''[, $xss_clean = NULL]]) - :param string $index: Value name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $index: Value name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: $_SERVER item value if found, NULL if not + :rtype: mixed This method is identical to the ``post()``, ``get()`` and ``cookie()`` methods, only it fetches server data (``$_SERVER``):: @@ -207,24 +213,26 @@ Class Reference .. method:: input_stream([$index = ''[, $xss_clean = NULL]]) - :param string $index: Key name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $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 This method is identical to ``get()``, ``post()`` and ``cookie()``, only it fetches the *php://input* stream data. .. method:: set_cookie($name = ''[, $value = ''[, $expire = ''[, $domain = ''[, $path = '/'[, $prefix = ''[, $secure = FALSE[, $httponly = FALSE]]]]]]]) - :param mixed $name: Cookie name or an array of parameters - :param string $value: Cookie value - :param int $expire: Cookie expiration time in seconds - :param string $domain: Cookie domain - :param string $path: Cookie path - :param string $prefix: Cookie name prefix - :param bool $secure: Whether to only transfer the cookie through HTTPS - :param bool $httponly: Whether to only make the cookie accessible for HTTP requests (no JavaScript) - :returns: void + :param mixed $name: Cookie name or an array of parameters + :param string $value: Cookie value + :param int $expire: Cookie expiration time in seconds + :param string $domain: Cookie domain + :param string $path: Cookie path + :param string $prefix: Cookie name prefix + :param bool $secure: Whether to only transfer the cookie through HTTPS + :param bool $httponly: Whether to only make the cookie accessible for HTTP requests (no JavaScript) + :rtype: void + Sets a cookie containing the values you specify. There are two ways to pass information to this method so that a cookie can be set: Array @@ -247,7 +255,7 @@ Class Reference $this->input->set_cookie($cookie); - **Notes:** + **Notes** Only the name and value are required. To delete a cookie set it with the expiration blank. @@ -276,10 +284,10 @@ Class Reference $this->input->set_cookie($name, $value, $expire, $domain, $path, $prefix, $secure); - .. method:: ip_address() - :returns: string + :returns: Visitor's IP address or '0.0.0.0' if not valid + :rtype: string Returns the IP address for the current user. If the IP address is not valid, the method will return '0.0.0.0':: @@ -293,9 +301,10 @@ Class Reference .. method:: valid_ip($ip[, $which = '']) - :param string $ip: IP address - :param string $which: IP protocol ('ipv4' or 'ipv6') - :returns: bool + :param string $ip: IP address + :param string $which: IP protocol ('ipv4' or 'ipv6') + :returns: TRUE if the address is valid, FALSE if not + :rtype: bool Takes an IP address as input and returns TRUE or FALSE (boolean) depending on whether it is valid or not. @@ -319,7 +328,8 @@ Class Reference .. method:: user_agent() - :returns: string + :returns: User agent string or NULL if not set + :rtype: mixed Returns the user agent string (web browser) being used by the current user, or NULL if it's not available. @@ -332,8 +342,9 @@ Class Reference .. method:: request_headers([$xss_clean = FALSE]) - :param bool $xss_clean: Whether to apply XSS filtering - :returns: array + :param bool $xss_clean: Whether to apply XSS filtering + :returns: An array of HTTP request headers + :rtype: array Returns an array of HTTP request headers. Useful if running in a non-Apache environment where @@ -345,9 +356,10 @@ Class Reference .. method:: get_request_header($index[, $xss_clean = FALSE]) - :param string $index: HTTP request header name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: string + :param string $index: HTTP request header name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: An HTTP request header or NULL if not found + :rtype: string Returns a single member of the request headers array or NULL if the searched header is not found. @@ -357,14 +369,16 @@ Class Reference .. method:: is_ajax_request() - :returns: bool + :returns: TRUE if it is an Ajax request, FALSE if not + :rtype: bool Checks to see if the HTTP_X_REQUESTED_WITH server header has been set, and returns boolean TRUE if it is or FALSE if not. .. method:: is_cli_request() - :returns: bool + :returns: TRUE if it is a CLI request, FALSE if not + :rtype: bool Checks to see if the application was run from the command-line interface. @@ -382,8 +396,9 @@ Class Reference .. method:: method([$upper = FALSE]) - :param bool $upper: Whether to return the request method name in upper or lower case - :returns: string + :param bool $upper: Whether to return the request method name in upper or lower case + :returns: HTTP request method + :rtype: string Returns the ``$_SERVER['REQUEST_METHOD']``, with the option to set it in uppercase or lowercase. diff --git a/user_guide_src/source/libraries/language.rst b/user_guide_src/source/libraries/language.rst index 10449b935..3014d8f09 100644 --- a/user_guide_src/source/libraries/language.rst +++ b/user_guide_src/source/libraries/language.rst @@ -110,20 +110,22 @@ Class Reference .. method:: load($langfile[, $idiom = ''[, $return = FALSE[, $add_suffix = TRUE[, $alt_path = '']]]]) - :param string $langfile: Language file to load - :param string $idiom: Language name (i.e. 'english') - :param bool $return: Whether to return the loaded array of translations - :param bool $add_suffix: Whether to add the '_lang' suffix to the language file name - :param string $alt_path: An alternative path to look in for the language file - :returns: void or array if the third parameter is set to TRUE + :param string $langfile: Language file to load + :param string $idiom: Language name (i.e. 'english') + :param bool $return: Whether to return the loaded array of translations + :param bool $add_suffix: Whether to add the '_lang' suffix to the language file name + :param string $alt_path: An alternative path to look in for the language file + :returns: Array of language lines if $return is set to TRUE, otherwise void + :rtype: mixed Loads a language file. .. method:: line($line[, $log_errors = TRUE]) - :param string $line: Language line key name - :param bool $log_errors: Whether to log an error if the line isn't found - :returns: string or FALSE on failure + :param string $line: Language line key name + :param bool $log_errors: Whether to log an error if the line isn't found + :returns: Language line string or FALSE on failure + :rtype: string Fetches a single translation line from the already loaded language files, based on the line's name. \ No newline at end of file diff --git a/user_guide_src/source/libraries/loader.rst b/user_guide_src/source/libraries/loader.rst index 15d9d80fc..107b3ece3 100644 --- a/user_guide_src/source/libraries/loader.rst +++ b/user_guide_src/source/libraries/loader.rst @@ -80,10 +80,11 @@ Class Reference .. method:: library($library[, $params = NULL[, $object_name = NULL]]) - :param mixed $library: Library name as a string or an array with multiple libraries - :param array $params: Optional array of parameters to pass to the loaded library's constructor - :param string $object_name: Optional object name to assign the library to - :returns: object + :param mixed $library: Library name as a string or an array with multiple libraries + :param array $params: Optional array of parameters to pass to the loaded library's constructor + :param string $object_name: Optional object name to assign the library to + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader This method is used to load core classes. @@ -156,10 +157,11 @@ Class Reference .. method:: driver($library[, $params = NULL[, $object_name]]) - :param mixed $library: Library name as a string or an array with multiple libraries - :param array $params: Optional array of parameters to pass to the loaded library's constructor - :param string $object_name: Optional object name to assign the library to - :returns: object + :param mixed $library: Library name as a string or an array with multiple libraries + :param array $params: Optional array of parameters to pass to the loaded library's constructor + :param string $object_name: Optional object name to assign the library to + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader This method is used to load driver libraries, acts very much like the ``library()`` method. @@ -216,10 +218,11 @@ Class Reference .. method:: view($view[, $vars = array()[, return = FALSE]]) - :param string $view: View name - :param array $vars: An associative array of variables - :param bool $return: Whether to return the loaded view - :returns: mixed + :param string $view: View name + :param array $vars: An associative array of variables + :param bool $return: Whether to return the loaded view + :returns: View content string if $return is set to TRUE, otherwise CI_Loader instance (method chaining) + :rtype: mixed This method is used to load your View files. If you haven't read the :doc:`Views <../general/views>` section of the user guide it is @@ -249,9 +252,10 @@ Class Reference .. method:: vars($vars[, $val = '']) - :param mixed $vars: An array of variables or a single variable name - :param mixed $val: Optional variable value - :returns: object + :param mixed $vars: An array of variables or a single variable name + :param mixed $val: Optional variable value + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader This method takes an associative array as input and generates variables using the PHP `extract() `_ @@ -265,8 +269,9 @@ Class Reference .. method:: get_var($key) - :param string $key: Variable name key - :returns: mixed + :param string $key: Variable name key + :returns: Value if key is found, NULL if not + :rtype: mixed This method checks the associative array of variables available to your views. This is useful if for any reason a var is set in a library @@ -274,22 +279,25 @@ Class Reference .. method:: get_vars() - :returns: array + :returns: An array of all assigned view variables + :rtype: array This method retrieves all variables available to your views. .. method:: clear_vars() - :returns: object + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader Clears cached view variables. .. method:: model($model[, $name = ''[, $db_conn = FALSE]]) - :param mixed $model: Model name or an array containing multiple models - :param string $name: Optional object name to assign the model to - :param string $db_conn: Optional database configuration group to load - :returns: object + :param mixed $model: Model name or an array containing multiple models + :param string $name: Optional object name to assign the model to + :param string $db_conn: Optional database configuration group to load + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader :: @@ -310,10 +318,11 @@ Class Reference .. method:: database([$params = ''[, $return = FALSE[, $query_builder = NULL]]]) - :param mixed $params: Database group name or configuration options - :param bool $return: Whether to return the loaded database object - :param bool $query_builder: Whether to load the Query Builder - :returns: mixed + :param mixed $params: Database group name or configuration options + :param bool $return: Whether to return the loaded database object + :param bool $query_builder: Whether to load the Query Builder + :returns: Loaded CI_DB instance or FALSE on failure if $return is set to TRUE, otherwise CI_Loader instance (method chaining) + :rtype: mixed This method lets you load the database class. The two parameters are **optional**. Please see the :doc:`database <../database/index>` @@ -321,35 +330,39 @@ Class Reference .. method:: dbforge([$db = NULL[, $return = FALSE]]) - :param object $db: Database object - :param bool $return: Whether to return the Database Forge instance - :returns: mixed + :param object $db: Database object + :param bool $return: Whether to return the Database Forge instance + :returns: Loaded CI_DB_forge instance if $return is set to TRUE, otherwise CI_Loader instance (method chaining) + :rtype: mixed Loads the :doc:`Database Forge <../database/forge>` class, please refer to that manual for more info. .. method:: dbutil([$db = NULL[, $return = FALSE]]) - :param object $db: Database object - :param bool $return: Whether to return the Database Utilities instance - :returns: mixed + :param object $db: Database object + :param bool $return: Whether to return the Database Utilities instance + :returns: Loaded CI_DB_utility instance if $return is set to TRUE, otherwise CI_Loader instance (method chaining) + :rtype: mixed Loads the :doc:`Database Utilities <../database/utilities>` class, please refer to that manual for more info. .. method:: helper($helpers) - :param mixed $helpers: Helper name as a string or an array containing multiple helpers - :returns: object + :param mixed $helpers: Helper name as a string or an array containing multiple helpers + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader This method loads helper files, where file_name is the name of the file, without the _helper.php extension. .. method:: file($path[, $return = FALSE]) - :param string $path: File path - :param bool $return: Whether to return the loaded file - :returns: mixed + :param string $path: File path + :param bool $return: Whether to return the loaded file + :returns: File contents if $return is set to TRUE, otherwise CI_Loader instance (method chaining) + :rtype: mixed This is a generic file loading method. Supply the filepath and name in the first parameter and it will open and read the file. By default the @@ -359,27 +372,30 @@ Class Reference .. method:: language($files[, $lang = '']) - :param mixed $files: Language file name or an array of multiple language files - :param string $lang: Language name - :returns: object + :param mixed $files: Language file name or an array of multiple language files + :param string $lang: Language name + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader This method is an alias of the :doc:`language loading method `: ``$this->lang->load()``. .. method:: config($file[, $use_sections = FALSE[, $fail_gracefully = FALSE]]) - :param string $file: Configuration file name - :param bool $use_sections: Whether configuration values should be loaded into their own section - :param bool $fail_gracefully: Whether to just return FALSE in case of failure - :returns: bool + :param string $file: Configuration file name + :param bool $use_sections: Whether configuration values should be loaded into their own section + :param bool $fail_gracefully: Whether to just return FALSE in case of failure + :returns: TRUE on success, FALSE on failure + :rtype: bool This method is an alias of the :doc:`config file loading method `: ``$this->config->load()`` .. method:: is_loaded($class) - :param string $class: Class name - :returns: mixed + :param string $class: Class name + :returns: Singleton property name if found, FALSE if not + :rtype: mixed Allows you to check if a class has already been loaded or not. @@ -405,9 +421,10 @@ Class Reference .. method:: add_package_path($path[, $view_cascade = TRUE]) - :param string $path: Path to add - :param bool $view_cascade: Whether to use cascading views - :returns: object + :param string $path: Path to add + :param bool $view_cascade: Whether to use cascading views + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader Adding a package path instructs the Loader class to prepend a given path for subsequent requests for resources. As an example, the "Foo Bar" @@ -419,8 +436,9 @@ Class Reference .. method:: remove_package_path([$path = '']) - :param string $path: Path to remove - :returns: object + :param string $path: Path to remove + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader When your controller is finished using resources from an application package, and particularly if you have other application packages you @@ -435,7 +453,8 @@ Class Reference .. method:: get_package_paths([$include_base = TRUE]) - :param bool $include_base: Whether to include BASEPATH - :returns: array + :param bool $include_base: Whether to include BASEPATH + :returns: An array of package paths + :rtype: array Returns all currently available package paths. \ No newline at end of file diff --git a/user_guide_src/source/libraries/migration.rst b/user_guide_src/source/libraries/migration.rst index 4143609bb..e8ea1d977 100644 --- a/user_guide_src/source/libraries/migration.rst +++ b/user_guide_src/source/libraries/migration.rst @@ -142,25 +142,30 @@ Class Reference .. method:: current() - :returns: mixed + :returns: TRUE if no migrations are found, current version string on success, FALSE on failure + :rtype: mixed - Migrates up to the current version (whatever is set for ``$config['migration_version']`` in *application/config/migration.php*). + Migrates up to the current version (whatever is set for + ``$config['migration_version']`` in *application/config/migration.php*). .. method:: error_string() - :returns: string + :returns: Error messages + :rtype: string This returns a string of errors that were detected while performing a migration. .. method:: find_migrations() - :returns: array + :returns: An array of migration files + :rtype: array An array of migration filenames are returned that are found in the **migration_path** property. .. method:: latest() - :returns: mixed + :returns: TRUE if no migrations are found, current version string on success, FALSE on failure + :rtype: mixed This works much the same way as ``current()`` but instead of looking for the ``$config['migration_version']`` the Migration class will use the very @@ -168,11 +173,12 @@ Class Reference .. method:: version($target_version) - :param mixed $target_version: Migration version to process - :returns: mixed + :param mixed $target_version: Migration version to process + :returns: TRUE if no migrations are found, current version string on success, FALSE on failure + :rtype: mixed Version can be used to roll back changes or step forwards programmatically to specific versions. It works just like ``current()`` but ignores ``$config['migration_version']``. :: - $this->migration->version(5); + $this->migration->version(5); \ No newline at end of file diff --git a/user_guide_src/source/libraries/output.rst b/user_guide_src/source/libraries/output.rst index 76197bdc1..e49ea5366 100644 --- a/user_guide_src/source/libraries/output.rst +++ b/user_guide_src/source/libraries/output.rst @@ -43,8 +43,9 @@ Class Reference .. method:: set_output($output) - :param string $output: String to set the output to - :returns: object + :param string $output: String to set the output to + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to manually set the final output string. Usage example:: @@ -52,13 +53,14 @@ Class Reference .. important:: If you do set your output manually, it must be the last thing done in the function you call it from. For example, if you build a page in one - of your controller functions, don't set the output until the end. + of your controller methods, don't set the output until the end. .. method:: set_content_type($mime_type[, $charset = NULL]) - :param string $mime_type: MIME Type idenitifer string - :param string $charset: Character set - :returns: object + :param string $mime_type: MIME Type idenitifer string + :param string $charset: Character set + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to set the mime-type of your page so you can serve JSON data, JPEG's, XML, etc easily. :: @@ -80,7 +82,8 @@ Class Reference .. method:: get_content_type() - :returns: string + :returns: Content-Type string + :rtype: string Returns the Content-Type HTTP header that's currently in use, excluding the character set value. :: @@ -91,8 +94,9 @@ Class Reference .. method:: get_header($header) - :param string $header: HTTP header name - :returns: string + :param string $header: HTTP header name + :returns: HTTP response header or NULL if not found + :rtype: mixed Returns the requested HTTP header value, or NULL if the requested header is not set. Example:: @@ -107,7 +111,8 @@ Class Reference .. method:: get_output() - :returns: string + :returns: Output string + :rtype: string Permits you to manually retrieve any output that has been sent for storage in the output class. Usage example:: @@ -120,8 +125,9 @@ Class Reference .. method:: append_output($output) - :param string $output: Additional output data to append - :returns: object + :param string $output: Additional output data to append + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Appends data onto the output string. :: @@ -130,9 +136,10 @@ Class Reference .. method:: set_header($header[, $replace = TRUE]) - :param string $header: HTTP Header - :param bool $replace: Whether to replace the old header value, if it is already set - :returns: object + :param string $header: HTTP response header + :param bool $replace: Whether to replace the old header value, if it is already set + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to manually set server headers, which the output class will send for you when outputting the final rendered display. Example:: @@ -146,9 +153,10 @@ Class Reference .. method:: set_status_header([$code = 200[, $text = '']]) - :param int $code: HTTP status code - :param string $text: Optional message - :returns: object + :param int $code: HTTP status code + :param string $text: Optional message + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to manually set a server status header. Example:: @@ -162,8 +170,9 @@ Class Reference .. method:: enable_profiler([$val = TRUE]) - :param bool $val: Whether to enable or disable the Profiler - :returns: object + :param bool $val: Whether to enable or disable the Profiler + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to enable/disable the :doc:`Profiler <../general/profiling>`, which will display benchmark and other data at the bottom of your pages for debugging and optimization purposes. @@ -181,16 +190,18 @@ Class Reference .. method:: set_profiler_sections($sections) - :param array $sections: Profiler sections - :returns: object + :param array $sections: Profiler sections + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to enable/disable specific sections of the Profiler when it is enabled. Please refer to the :doc:`Profiler <../general/profiling>` documentation for further information. .. method:: cache($time) - :param int $time: Cache expiration time in seconds - :returns: object + :param int $time: Cache expiration time in seconds + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Caches the current page for the specified amount of seconds. diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst index 34ca22141..222436f46 100644 --- a/user_guide_src/source/libraries/pagination.rst +++ b/user_guide_src/source/libraries/pagination.rst @@ -307,13 +307,14 @@ Class Reference .. method:: initialize([$params = array()]) - :param array $params: Configuration parameters - :returns: void + :param array $params: Configuration parameters + :rtype: void Initializes the Pagination class with your preferred options. .. method:: create_links() - :returns: string + :returns: HTML-formatted pagination + :rtype: string Returns a "pagination" bar, containing the generated links or an empty string if there's just a single page. \ No newline at end of file diff --git a/user_guide_src/source/libraries/parser.rst b/user_guide_src/source/libraries/parser.rst index 34ad65f2b..5af504a03 100644 --- a/user_guide_src/source/libraries/parser.rst +++ b/user_guide_src/source/libraries/parser.rst @@ -151,27 +151,29 @@ Class Reference .. method:: parse($template, $data[, $return = FALSE]) - :param string $template: Path to view file - :param array $data: Variable data - :param bool $return: Whether to return the parsed template - :returns: mixed + :param string $template: Path to view file + :param array $data: Variable data + :param bool $return: Whether to only return the parsed template + :returns: Parsed template string + :rtype: string Parses a template from the provided path and variables. .. method:: parse_string($template, $data[, $return = FALSE]) - :param string $template: Path to view file - :param array $data: Variable data - :param bool $return: Whether to return the parsed template - :returns: mixed + :param string $template: Path to view file + :param array $data: Variable data + :param bool $return: Whether to only return the parsed template + :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. .. method:: set_delimiters([$l = '{'[, $r = '}']]) - :param string $l: Left delimiter - :param string $r: Right delimiter - :returns: void + :param string $l: Left delimiter + :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 diff --git a/user_guide_src/source/libraries/security.rst b/user_guide_src/source/libraries/security.rst index 451fadf93..fb875a0d9 100644 --- a/user_guide_src/source/libraries/security.rst +++ b/user_guide_src/source/libraries/security.rst @@ -105,17 +105,19 @@ Class Reference .. method:: xss_clean($str[, $is_image = FALSE]) - :param string $str: Input string - :returns: mixed + :param mixed $str: Input string or an array of strings + :returns: XSS-clean data + :rtype: mixed Tries to remove XSS exploits from the input data and returns the cleaned string. If the optional second parameter is set to true, it will return boolean TRUE if the image is safe to use and FALSE if malicious data was detected in it. .. method:: sanitize_filename($str[, $relative_path = FALSE]) - :param string $str: File name/path - :param bool $relative_path: Whether to preserve any directories in the file path - :returns: string + :param string $str: File name/path + :param bool $relative_path: Whether to preserve any directories in the file path + :returns: Sanitized file name/path + :rtype: string Tries to sanitize filenames in order to prevent directory traversal attempts and other security threats, which is particularly useful for files that were supplied via user input. @@ -131,23 +133,27 @@ Class Reference .. method:: get_csrf_token_name() - :returns: string + :returns: CSRF token name + :rtype: string Returns the CSRF token name (the ``$config['csrf_token_name']`` value). .. method:: get_csrf_hash() - :returns: string + :returns: CSRF hash + :rtype: string Returns the CSRF hash value. Useful in combination with ``get_csrf_token_name()`` for manually building forms or sending valid AJAX POST requests. .. method:: entity_decode($str[, $charset = NULL]) - :param string $str: Input string - :param string $charset: Character set of the input string + :param string $str: Input string + :param string $charset: Character set of the input string + :returns: Entity-decoded string + :rtype: string This method acts a lot like PHP's own native ``html_entity_decode()`` function in ENT_COMPAT mode, only it tries to detect HTML entities that don't end in a semicolon because some browsers allow that. - If the ``$charset`` parameter is left empty, then your configured ``$config['charset']`` value will be used. + If the ``$charset`` parameter is left empty, then your configured ``$config['charset']`` value will be used. \ No newline at end of file diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index 9e23e9b60..f05f86af1 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -526,20 +526,23 @@ Class Reference .. method:: load_driver($driver) - :param string $driver: Driver name - :returns: object + :param string $driver: Driver name + :returns: Instance of currently loaded session driver + :rtype: mixed Loads a session storage driver .. method:: select_driver($driver) - :param string $driver: Driver name - :returns: void + :param string $driver: Driver name + :rtype: void Selects default session storage driver. .. method:: sess_destroy() + :rtype: void + Destroys current session .. note:: This method should be the last one called, and even flash @@ -549,15 +552,16 @@ Class Reference .. method:: sess_regenerate([$destroy = FALSE]) - :param bool $destroy: Whether to destroy session data - :returns: void + :param bool $destroy: Whether to destroy session data + :rtype: void Regenerate the current session data. .. method:: userdata([$item = NULL]) - :param string $item: Session item name - :returns: mixed + :param string $item: Session item name + :returns: Item value if found, NULL if not or an array of all userdata if $item parameter is not used + :rtype: mixed If no parameter is passed, it will return an associative array of all existing userdata. @@ -569,7 +573,8 @@ Class Reference .. method:: all_userdata() - :returns: array + :returns: An array of all userdata + :rtype: array Returns an array with all of the session userdata items. @@ -577,15 +582,16 @@ Class Reference .. method:: &get_userdata() - :returns: array + :returns: A reference to the userdata array + :rtype: &array Returns a reference to the userdata array. .. method:: set_userdata($newdata[, $newval = '']) - :param mixed $newdata: Item name or array of items - :param mixed $newval: Item value or empty string (not required if $newdata is array) - :returns: void + :param mixed $newdata: Item name or array of items + :param mixed $newval: Item value or empty string (not required if $newdata is array) + :rtype: void Sets items into session example usages:: @@ -597,8 +603,8 @@ Class Reference .. method:: unset_userdata($item) - :param mixed $item: Item name or an array containing multiple items - :returns: void + :param mixed $item: Item name or an array containing multiple items + :rtype: void Unsets previously set items from the session. Example:: @@ -610,15 +616,17 @@ Class Reference .. method:: has_userdata($item) - :param string $item: Item name - :returns: bool + :param string $item: Item name + :returns: TRUE if item exists, FALSE if not + :rtype: bool Checks if an item exists in the session. .. method:: flashdata([$item = NULL]) - :param string $item: Flashdata item name - :returns: mixed + :param string $item: Flashdata item name + :returns: Item value if found, NULL if not or an array of all flashdata if $item parameter is not used + :rtype: mixed If no parameter is passed, it will return an associative array of all existing flashdata. @@ -630,9 +638,9 @@ Class Reference .. method:: set_flashdata($newdata[, $newval = '']) - :param mixed $newdata: Item name or an array of items - :param mixed $newval: Item value or empty string (not required if $newdata is array) - :returns: void + :param mixed $newdata: Item name or an array of items + :param mixed $newval: Item value or empty string (not required if $newdata is array) + :rtype: void Sets items into session flashdata example usages:: @@ -645,15 +653,16 @@ Class Reference .. method:: keep_flashdata($item) - :param mixed $item: Item name or an array containing multiple flashdata items - :returns: void + :param mixed $item: Item name or an array containing multiple flashdata items + :rtype: void Keeps items into flashdata for one more request. .. method:: tempdata([$item = NULL]) - :param string $item: Tempdata item name - :returns: mixed + :param string $item: Tempdata item name + :returns: Item value if found, NULL if not or an array of all tempdata if $item parameter is not used + :rtype: mixed If no parameter is passed, it will return an associative array of all existing tempdata. @@ -665,10 +674,10 @@ Class Reference .. method:: set_tempdata($newdata[, $newval = ''[, $expire = 0]]) - :param mixed $newdata: Item name or array containing multiple items - :param string $newval: Item value or empty string (not required if $newdata is array) - :param int $expire: Lifetime in seconds (0 for default) - :returns: void + :param mixed $newdata: Item name or array containing multiple items + :param string $newval: Item value or empty string (not required if $newdata is array) + :param int $expire: Lifetime in seconds (0 for default) + :rtype: void Sets items into session tempdata example:: @@ -681,8 +690,8 @@ Class Reference .. method:: unset_tempdata($item) - :param mixed $item: Item name or an array containing multiple items - :returns: void + :param mixed $item: Item name or an array containing multiple items + :rtype: void Unsets previously set items from tempdata. Example:: diff --git a/user_guide_src/source/libraries/table.rst b/user_guide_src/source/libraries/table.rst index ed085f781..ea0c417c4 100644 --- a/user_guide_src/source/libraries/table.rst +++ b/user_guide_src/source/libraries/table.rst @@ -158,15 +158,16 @@ Class Reference .. method:: generate([$table_data = NULL]) - :param mixed $table_data: data to populate the table rows with - :returns: string + :param mixed $table_data: Data to populate the table rows with + :returns: HTML table + :rtype: string Returns a string containing the generated table. Accepts an optional parameter which can be an array or a database result object. .. method:: set_caption($caption) - :param string $caption: table caption - :returns: void + :param string $caption: Table caption + :rtype: void Permits you to add a caption to the table. :: @@ -175,8 +176,8 @@ Class Reference .. method:: set_heading([$args = array()[, ...]]) - :param mixed $args: an array or multiple strings containing the table column titles - :returns: void + :param mixed $args: An array or multiple strings containing the table column titles + :rtype: void Permits you to set the table heading. You can submit an array or discrete params:: @@ -186,8 +187,8 @@ Class Reference .. method:: add_row([$args = array()[, ...]]) - :param mixed $args: an array or multiple strings containing the row values - :returns: void + :param mixed $args: An array or multiple strings containing the row values + :rtype: void Permits you to add a row to your table. You can submit an array or discrete params:: @@ -206,9 +207,10 @@ Class Reference .. method:: make_columns([$array = array()[, $col_limit = 0]]) - :param array $array: an array containing multiple rows' data - :param int $col_limit: count of columns in the table - :returns: array + :param array $array: An array containing multiple rows' data + :param int $col_limit: Count of columns in the table + :returns: An array of HTML table columns + :rtype: array This method takes a one-dimensional array as input and creates a multi-dimensional array with a depth equal to the number of columns desired. This allows a single array with many elements to be displayed in a table that has a fixed column count. Consider this example:: @@ -235,8 +237,9 @@ Class Reference .. method:: set_template($template) - :param array $template: associative array containing template values - :returns: bool + :param array $template: An associative array containing template values + :returns: TRUE on success, FALSE on failure + :rtype: bool Permits you to set your template. You can submit a full or partial template. :: @@ -249,8 +252,8 @@ Class Reference .. method:: set_empty($value) - :param mixed $value: value to put in empty cells - :returns: void + :param mixed $value: Value to put in empty cells + :rtype: void Lets you set a default value for use in any table cells that are empty. You might, for example, set a non-breaking space:: @@ -259,7 +262,7 @@ Class Reference .. method:: clear() - :returns: void + :rtype: void Lets you clear the table heading and row data. If you need to show multiple tables with different data you should to call this method after each table has been generated to clear the previous table information. Example:: diff --git a/user_guide_src/source/libraries/trackback.rst b/user_guide_src/source/libraries/trackback.rst index c5b01a2ee..22859a13d 100644 --- a/user_guide_src/source/libraries/trackback.rst +++ b/user_guide_src/source/libraries/trackback.rst @@ -225,22 +225,24 @@ Class Reference .. method:: send($tb_data) - :param array $tb_data: trackback data - :returns: bool + :param array $tb_data: Trackback data + :returns: TRUE on success, FALSE on failure + :rtype: bool Send trackback. .. method:: receive() - :returns: bool + :returns: TRUE on success, FALSE on failure + :rtype: bool This method simply validates the incoming TB data, returning TRUE on success and FALSE on failure. If the data is valid it is set to the ``$this->data`` array so that it can be inserted into a database. .. method:: send_error([$message = 'Incomplete information') - :param string $message: error message - :returns: void + :param string $message: Error message + :rtype: void Responses to a trackback request with an error message. @@ -248,7 +250,7 @@ Class Reference .. method:: send_success() - :returns: void + :rtype: void Responses to a trackback request with a success message. @@ -256,74 +258,82 @@ Class Reference .. method:: data($item) - :param string $item: data key - :returns: string + :param string $item: Data key + :returns: Data value or empty string if not found + :rtype: string Returns a single item from the reponse data array. .. method:: process($url, $data) - :param string $url: target url - :param string $data: raw post data - :returns: bool + :param string $url: Target url + :param string $data: Raw POST data + :returns: TRUE on success, FALSE on failure + :rtype: bool Opens a socket connection and passes the data to the server, returning TRUE on success and FALSE on failure. .. method:: extract_urls($urls) - :param string $urls: comma-separated url list - :returns: string + :param string $urls: Comma-separated URL list + :returns: Array of URLs + :rtype: array This method lets multiple trackbacks to be sent. It takes a string of URLs (separated by comma or space) and puts each URL into an array. .. method:: validate_url(&$url) - :param string $url: trackback url - :returns: void + :param string $url: Trackback URL + :rtype: void Simply adds the *http://* prefix it it's not already present in the URL. .. method:: get_id($url) - :param string $url: trackback url - :returns: string + :param string $url: Trackback URL + :returns: URL ID or FALSE on failure + :rtype: string Find and return a trackback URL's ID or FALSE on failure. .. method:: convert_xml($str) - :param string $str: input string - :returns: string + :param string $str: Input string + :returns: Converted string + :rtype: string Converts reserved XML characters to entities. .. method:: limit_characters($str[, $n = 500[, $end_char = '…']]) - :param string $str: input string - :param int $n: max characters number - :param string $end_char: character to put at end of string - :returns: string + :param string $str: Input string + :param int $n: Max characters number + :param string $end_char: Character to put at end of string + :returns: Shortened string + :rtype: string Limits the string based on the character count. Will preserve complete words. .. method:: convert_ascii($str) - :param string $str: input string - :returns: string + :param string $str: Input string + :returns: Converted string + :rtype: string Converts high ASCII text and MS Word special characterss to HTML entities. .. method:: set_error($msg) - :param string $msg: error message - :returns: void + :param string $msg: Error message + :rtype: void Set an log an error message. .. method:: display_errors([$open = '

'[, $close = '

']]) - :param string $open: open tag - :param string $close: close tag - :returns: string + :param string $open: Open tag + :param string $close: Close tag + :returns: HTML formatted error messages + :rtype: string Returns error messages formatted in HTML or an empty string if there are no errors. \ No newline at end of file diff --git a/user_guide_src/source/libraries/typography.rst b/user_guide_src/source/libraries/typography.rst index c1a864a3e..65fea9d8e 100644 --- a/user_guide_src/source/libraries/typography.rst +++ b/user_guide_src/source/libraries/typography.rst @@ -46,9 +46,10 @@ Class Reference .. method auto_typography($str[, $reduce_linebreaks = FALSE]) - :param string $str: input string - :param bool $reduce_linebreaks: whether to reduce consequitive linebreaks - :returns: string + :param string $str: Input string + :param bool $reduce_linebreaks: Whether to reduce consequitive linebreaks + :returns: HTML typography-safe string + :rtype: string Formats text so that it is semantically and typographically correct HTML. Takes a string as input and returns it with the following formatting: @@ -76,8 +77,9 @@ Class Reference .. method:: format_characters($str) - :param string $str: input string - :returns: string + :param string $str: Input string + :returns: Formatted string + :rtype: string This method is similar to ``auto_typography()`` above, except that it only does character conversion: @@ -93,8 +95,9 @@ Class Reference .. method:: nl2br_except_pre($str) - :param string $str: input string - :returns: string + :param string $str: Input string + :returns: Formatted string + :rtype: string Converts newlines to
tags unless they appear within
 tags.
 		This method is identical to the native PHP :php:func:`nl2br()` function, except that it ignores 
 tags.
diff --git a/user_guide_src/source/libraries/unit_testing.rst b/user_guide_src/source/libraries/unit_testing.rst
index 2d4a27a25..0bc860f61 100644
--- a/user_guide_src/source/libraries/unit_testing.rst
+++ b/user_guide_src/source/libraries/unit_testing.rst
@@ -193,45 +193,48 @@ Class Reference
 
 	.. method:: run($test[, $expected = TRUE[, $test_name = 'undefined'[, $notes = '']]])
 
-		:param mixed $test: Test data
-		:param mixed $expected: Expected result
-		:param string $test_name: Test name
-		:param string $notes: Any notes to be attached to the test
-		:returns: string
+		:param	mixed	$test: Test data
+		:param	mixed	$expected: Expected result
+		:param	string	$test_name: Test name
+		:param	string	$notes: Any notes to be attached to the test
+		:returns:	Test report
+		:rtype:	string
 
 		Runs unit tests.
 
 	.. method:: report([$result = array()])
 
-		:param array $result: Array containing tests results
-		:returns: string
+		:param	array	$result: Array containing tests results
+		:returns:	Test report
+		:rtype:	string
 
 		Generates a report about already complete tests.
 
 	.. method:: use_strict([$state = TRUE])
 
-		:param bool $state: Strict state flag
-		:returns: void
+		:param	bool	$state: Strict state flag
+		:rtype:	void
 
 		Enables/disables strict type comparison in tests.
 
 	.. method:: active([$state = TRUE])
 
-		:param bool $state: Whether to enable testing
-		:returns: void
+		:param	bool	$state: Whether to enable testing
+		:rtype:	void
 
 		Enables/disables unit testing.
 
 	.. method:: result([$results = array()])
 
-		:param array $results: Tests results list
-		:returns: array
+		:param	array	$results: Tests results list
+		:returns:	Array of raw result data
+		:rtype:	array
 
 		Returns raw tests results data.
 
 	.. method:: set_template($template)
 
-		:param string $template: Test result template
-		:returns: void
+		:param	string	$template: Test result template
+		:rtype:	void
 
 		Sets the template for displaying tests results.
\ No newline at end of file
diff --git a/user_guide_src/source/libraries/uri.rst b/user_guide_src/source/libraries/uri.rst
index f0fa04005..7db758ce7 100644
--- a/user_guide_src/source/libraries/uri.rst
+++ b/user_guide_src/source/libraries/uri.rst
@@ -24,9 +24,10 @@ Class Reference
 
 	.. method:: segment($n[, $no_result = NULL])
 
-		:param int $n: Segment index number
-		:param mixed $no_result: What to return if the searched segment is not found
-		:returns: mixed
+		:param	int	$n: Segment index number
+		:param	mixed	$no_result: What to return if the searched segment is not found
+		:returns:	Segment value or $no_result value if not found
+		:rtype:	mixed
 
 		Permits you to retrieve a specific segment. Where n is the segment
 		number you wish to retrieve. Segments are numbered from left to right.
@@ -60,9 +61,10 @@ Class Reference
 
 	.. method:: rsegment($n[, $no_result = NULL])
 
-		:param int $n: Segment index number
-		:param mixed $no_result: What to return if the searched segment is not found
-		:returns: mixed
+		:param	int	$n: Segment index number
+		:param	mixed	$no_result: What to return if the searched segment is not found
+		:returns:	Routed segment value or $no_result value if not found
+		:rtype:	mixed
 
 		This method is identical to ``segment()``, except that it lets you retrieve
 		a specific segment from your re-routed URI in the event you are
@@ -70,9 +72,10 @@ Class Reference
 
 	.. method:: slash_segment($n[, $where = 'trailing'])
 
-		:param int $n: Segment index number
-		:param string $where: Where to add the slash ('trailing' or 'leading')
-		:returns: string
+		:param	int	$n: Segment index number
+		:param	string	$where: Where to add the slash ('trailing' or 'leading')
+		:returns:	Segment value, prepended/suffixed with a forward slash, or a slash if not found
+		:rtype:	string
 
 		This method is almost identical to ``segment()``, except it
 		adds a trailing and/or leading slash based on the second parameter.
@@ -90,9 +93,10 @@ Class Reference
 
 	.. method:: slash_rsegment($n[, $where = 'trailing'])
 
-		:param int $n: Segment index number
-		:param string $where: Where to add the slash ('trailing' or 'leading')
-		:returns: string
+		:param	int	$n: Segment index number
+		:param	string	$where: Where to add the slash ('trailing' or 'leading')
+		:returns:	Routed segment value, prepended/suffixed with a forward slash, or a slash if not found
+		:rtype:	string
 
 		This method is identical to ``slash_segment()``, except that it lets you
 		add slashes a specific segment from your re-routed URI in the event you
@@ -101,9 +105,10 @@ Class Reference
 
 	.. method:: uri_to_assoc([$n = 3[, $default = array()]])
 
-		:param int $n: Segment index number
-		:param array $default: Default values
-		:returns: array
+		:param	int	$n: Segment index number
+		:param	array	$default: Default values
+		:returns:	Associative URI segments array
+		:rtype:	array
 
 		This method lets you turn URI segments into and associative array of
 		key/value pairs. Consider this URI::
@@ -142,9 +147,10 @@ Class Reference
 
 	.. method:: ruri_to_assoc([$n = 3[, $default = array()]])
 
-		:param int $n: Segment index number
-		:param array $default: Default values
-		:returns: array
+		:param	int	$n: Segment index number
+		:param	array	$default: Default values
+		:returns:	Associative routed URI segments array
+		:rtype:	array
 
 		This method is identical to ``uri_to_assoc()``, except that it creates
 		an associative array using the re-routed URI in the event you are using
@@ -152,8 +158,9 @@ Class Reference
 
 	.. method:: assoc_to_uri($array)
 
-		:param array $array: Input array of key/value pairs
-		:returns: string
+		:param	array	$array: Input array of key/value pairs
+		:returns:	URI string
+		:rtype:	string
 
 		Takes an associative array as input and generates a URI string from it.
 		The array keys will be included in the string. Example::
@@ -165,7 +172,8 @@ Class Reference
 
 	.. method:: uri_string()
 
-		:returns: string
+		:returns:	URI string
+		:rtype:	string
 
 		Returns a string with the complete URI. For example, if this is your full URL::
 
@@ -177,7 +185,8 @@ Class Reference
 
 	.. method:: ruri_string()
 
-		:returns: string
+		:returns:	Routed URI string
+		:rtype:	string
 
 		This method is identical to ``uri_string()``, except that it returns
 		the re-routed URI in the event you are using CodeIgniter's :doc:`URI
@@ -185,13 +194,15 @@ Class Reference
 
 	.. method:: total_segments()
 
-		:returns: int
+		:returns:	Count of URI segments
+		:rtype:	int
 
 		Returns the total number of segments.
 
 	.. method:: total_rsegments()
 
-		:returns: int
+		:returns:	Count of routed URI segments
+		:rtype:	int
 
 		This method is identical to ``total_segments()``, except that it returns
 		the total number of segments in your re-routed URI in the event you are
@@ -199,7 +210,8 @@ Class Reference
 
 	.. method:: segment_array()
 
-		:returns: array
+		:returns:	URI segments array
+		:rtype:	array
 
 		Returns an array containing the URI segments. For example::
 
@@ -213,7 +225,8 @@ Class Reference
 
 	.. method:: rsegment_array()
 
-		:returns: array
+		:returns:	Routed URI segments array
+		:rtype:	array
 
 		This method is identical to ``segment_array()``, except that it returns
 		the array of segments in your re-routed URI in the event you are using
diff --git a/user_guide_src/source/libraries/user_agent.rst b/user_guide_src/source/libraries/user_agent.rst
index 1b6a2988a..517382a65 100644
--- a/user_guide_src/source/libraries/user_agent.rst
+++ b/user_guide_src/source/libraries/user_agent.rst
@@ -76,8 +76,9 @@ Class Reference
 
 	.. method:: is_browser([$key = NULL])
 
-		:param string $key: optional browser name
-		:returns: bool
+		:param	string	$key: Optional browser name
+		:returns:	TRUE if the user agent is a (specified) browser, FALSE if not
+		:rtype:	bool
 
 		Returns TRUE/FALSE (boolean) if the user agent is a known web browser.
 		::
@@ -97,8 +98,9 @@ Class Reference
 
 	.. method:: is_mobile([$key = NULL])
 
-		:param string $key: optional mobile device name
-		:returns: bool
+		:param	string	$key: Optional mobile device name
+		:returns:	TRUE if the user agent is a (specified) mobile device, FALSE if not
+		:rtype:	bool
 
 		Returns TRUE/FALSE (boolean) if the user agent is a known mobile device.
 		::
@@ -118,8 +120,9 @@ Class Reference
 
 	.. method:: is_robot([$key = NULL])
 
-		:param string $key: optional robot name
-		:returns: bool
+		:param	string	$key: Optional robot name
+		:returns:	TRUE if the user agent is a (specified) robot, FALSE if not
+		:rtype:	bool
 
 		Returns TRUE/FALSE (boolean) if the user agent is a known robot.
 
@@ -130,43 +133,50 @@ Class Reference
 
 	.. method:: is_referral()
 
-		:returns: bool
+		:returns:	TRUE if the user agent is a referral, FALSE if not
+		:rtype:	bool
 
 		Returns TRUE/FALSE (boolean) if the user agent was referred from another site.
 
 	.. method:: browser()
 
-		:returns: string
+		:returns:	Detected browser or an empty string
+		:rtype:	string
 
 		Returns a string containing the name of the web browser viewing your site.
 
 	.. method:: version()
 
-		:returns: string
+		:returns:	Detected browser version or an empty string
+		:rtype:	string
 
 		Returns a string containing the version number of the web browser viewing your site.
 
 	.. method:: mobile()
 
-		:returns: string
+		:returns:	Detected mobile device brand or an empty string
+		:rtype:	string
 
 		Returns a string containing the name of the mobile device viewing your site.
 
 	.. method:: robot()
 
-		:returns: string
+		:returns:	Detected robot name or an empty string
+		:rtype:	string
 
 		Returns a string containing the name of the robot viewing your site.
 
 	.. method:: platform()
 
-		:returns: string
+		:returns:	Detected operating system or an empty string
+		:rtype:	string
 
 		Returns a string containing the platform viewing your site (Linux, Windows, OS X, etc.).
 
 	.. method:: referrer()
 
-		:returns: string
+		:returns:	Detected referrer or an empty string
+		:rtype:	string
 
 		The referrer, if the user agent was referred from another site. Typically you'll test for this as follows::
 
@@ -177,7 +187,8 @@ Class Reference
 
 	.. method:: agent_string()
 
-		:returns: string
+		:returns:	Full user agent string or an empty string
+		:rtype:	string
 
 		Returns a string containing the full user agent string. Typically it will be something like this::
 
@@ -185,8 +196,9 @@ Class Reference
 
 	.. method:: accept_lang([$lang = 'en'])
 
-		:param string $lang: language key
-		:returns: bool
+		:param	string	$lang: Language key
+		:returns:	TRUE if provided language is accepted, FALSE if not
+		:rtype:	bool
 
 		Lets you determine if the user agent accepts a particular language. Example::
 
@@ -200,14 +212,16 @@ Class Reference
 
 	.. method:: languages()
 
-		:returns: array
+		:returns:	An array list of accepted languages
+		:rtype:	array
 
 		Returns an array of languages supported by the user agent.
 
 	.. method:: accept_charset([$charset = 'utf-8'])
 
-		:param string $charset: character set
-		:returns: bool
+		:param	string	$charset: Character set
+		:returns:	TRUE if the character set is accepted, FALSE if not
+		:rtype:	bool
 
 		Lets you determine if the user agent accepts a particular character set. Example::
 
@@ -221,13 +235,14 @@ Class Reference
 
 	.. method:: charsets()
 
-		:returns: array
+		:returns:	An array list of accepted character sets
+		:rtype:	array
 
 		Returns an array of character sets accepted by the user agent.
 
 	.. method:: parse($string)
 
-		:param string $string: A custom user-agent string
-		:returns: void
+		:param	string	$string: A custom user-agent string
+		:rtype:	void
 
 		Parses a custom user-agent string, different from the one reported by the current visitor.
\ No newline at end of file
diff --git a/user_guide_src/source/libraries/xmlrpc.rst b/user_guide_src/source/libraries/xmlrpc.rst
index d9b2dfb1a..2cf548750 100644
--- a/user_guide_src/source/libraries/xmlrpc.rst
+++ b/user_guide_src/source/libraries/xmlrpc.rst
@@ -459,18 +459,18 @@ Class Reference
 
 	.. method:: initialize([$config = array()])
 
-		:param array $config: configuration data
-		:returns: void
+		:param	array	$config: Configuration data
+		:rtype:	void
 
 		Initializes the XML-RPC library. Accepts an associative array containing your settings.
 
 	.. method:: server($url[, $port = 80[, $proxy = FALSE[, $proxy_port = 8080]]])
 
-		:param string $url: XML-RPC server URL
-		:param int $port: server port
-		:param string $proxy: optional proxy
-		:param int $proxy_port: proxy listening port
-		:returns: void
+		:param	string	$url: XML-RPC server URL
+		:param	int	$port: Server port
+		:param	string	$proxy: Optional proxy
+		:param	int	$proxy_port: Proxy listening port
+		:rtype:	void
 
 		Sets the URL and port number of the server to which a request is to be sent::
 
@@ -482,8 +482,8 @@ Class Reference
 
 	.. method:: timeout($seconds = 5)
 
-		:param int $seconds: timeout in seconds
-		:returns: void
+		:param	int	$seconds: Timeout in seconds
+		:rtype:	void
 
 		Set a time out period (in seconds) after which the request will be canceled::
 
@@ -491,8 +491,8 @@ Class Reference
 
 	.. method:: method($function)
 
-		:param string $function: method name
-		:returns: void
+		:param	string	$function: Method name
+		:rtype:	void
 
 		Sets the method that will be requested from the XML-RPC server::
 
@@ -502,8 +502,8 @@ Class Reference
 
 	.. method:: request($incoming)
 
-		:param array $incoming: request data
-		:returns: void
+		:param	array	$incoming: Request data
+		:rtype:	void
 
 		Takes an array of data and builds request to be sent to XML-RPC server::
 
@@ -512,20 +512,22 @@ Class Reference
 
 	.. method:: send_request()
 
-		:returns: bool
+		:returns:	TRUE on success, FALSE on failure
+		:rtype:	bool
 
 		The request sending method. Returns boolean TRUE or FALSE based on success for failure, enabling it to be used conditionally.
 
 	.. method set_debug($flag = TRUE)
 
-		:param bool $flag: debug status flag
-		:returns: void
+		:param	bool	$flag: Debug status flag
+		:rtype:	void
 
 	Enables or disables debugging, which will display a variety of information and error data helpful during development.
 
 	.. method:: display_error()
 
-		:returns: string
+		:returns:	Error message string
+		:rtype:	string
 
 		Returns an error message as a string if your request failed for some reason.
 		::
@@ -534,7 +536,8 @@ Class Reference
 
 	.. method:: display_response()
 
-		:returns: mixed
+		:returns:	Response
+		:rtype:	mixed
 
 		Returns the response from the remote server once request is received. The response will typically be an associative array.
 		::
@@ -543,9 +546,10 @@ Class Reference
 
 	.. method:: send_error_message($number, $message)
 
-		:param int $number: error number
-		:param string $message: error message
-		:returns: object
+		:param	int	$number: Error number
+		:param	string	$message: Error message
+		:returns:	XML_RPC_Response instance
+		:rtype:	XML_RPC_Response
 
 		This method lets you send an error message from your server to the client.
 		First parameter is the error number while the second parameter is the error message.
@@ -555,8 +559,9 @@ Class Reference
 
 	.. method send_response($response)
 
-		:param array $response: response data
-		:returns: object
+		:param	array	$response: Response data
+		:returns:	XML_RPC_Response instance
+		:rtype:	XML_RPC_Response
 
 		Lets you send the response from your server to the client. An array of valid data values must be sent with this method.
 		::
@@ -569,4 +574,4 @@ Class Reference
 				'struct'
 			);
 
-		return $this->xmlrpc->send_response($response);
+		return $this->xmlrpc->send_response($response);
\ 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 535aa82d9..5ff7d07d6 100644
--- a/user_guide_src/source/libraries/zip.rst
+++ b/user_guide_src/source/libraries/zip.rst
@@ -54,9 +54,9 @@ Class Reference
 
 	.. method:: add_data($filepath[, $data = NULL])
 
-		:param mixed $filepath: a single file path or an array of file => data pairs
-		:param array $data: single file contents
-		:returns: void
+		:param	mixed	$filepath: A single file path or an array of file => data pairs
+		:param	array	$data: File contents (ignored if $filepath is an array)
+		:rtype:	void
 
 		Adds data to the Zip archive. Can work both in single and multiple files mode.
 
@@ -90,8 +90,8 @@ Class Reference
 
 	.. method:: add_dir($directory)
 
-		:param mixed $directory: string directory name or an array of multiple directories
-		:returns: void
+		: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::
@@ -100,9 +100,10 @@ Class Reference
 
 	.. method:: read_file($path[, $archive_filepath = FALSE])
 
-		:param string $path: Path to file
-		:param mixed $archive_filepath: New file name/path (string) or (boolean) whether to maintain the original filepath
-		:returns: bool
+		:param	string	$path: Path to file
+		:param	mixed	$archive_filepath: New file name/path (string) or (boolean) whether to maintain the original filepath
+		:returns:	TRUE on success, FALSE on failure
+		:rtype:	bool
 
 		Permits you to compress a file that already exists somewhere on your server.
 		Supply a file path and the zip class will read it and add it to the archive::
@@ -138,10 +139,11 @@ Class Reference
 
 	.. method:: read_dir($path[, $preserve_filepath = TRUE[, $root_path = NULL]])
 
-		:param string $path: path to directory
-		:param bool $preserve_filepath: whether to maintain the original path
-		:param string $root_path: part of the path to exclude from the archive directory
-		:returns: bool
+		:param	string	$path: Path to directory
+		:param	bool	$preserve_filepath: Whether to maintain the original path
+		:param	string	$root_path: Part of the path to exclude from the archive directory
+		:returns:	TRUE on success, FALSE on failure
+		:rtype:	bool
 
 		Permits you to compress a directory (and its contents) that already exists somewhere on your server.
 		Supply a path to the directory and the zip class will recursively read and recreate it as a Zip archive.
@@ -166,8 +168,9 @@ Class Reference
 
 	.. method:: archive($filepath)
 
-		:param string $filepath: path to target zip archive
-		:returns: bool
+		:param	string	$filepath: Path to target zip archive
+		: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 (660 or 666 is usually OK). Example::
@@ -176,8 +179,8 @@ Class Reference
 
 	.. method:: download($filename = 'backup.zip')
 
-		:param string $filename: the archive file name
-		:returns: void
+		: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::
 
@@ -189,7 +192,8 @@ Class Reference
 
 	.. method:: get_zip()
 
-		:returns: string
+		: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::
 
@@ -202,7 +206,7 @@ Class Reference
 
 	.. method:: clear_data()
 
-		:returns: void
+		: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::
-- 
cgit v1.2.3-24-g4f1b