diff options
| author | Andrey Andreev <narf@devilix.net> | 2019-09-19 14:08:45 +0200 |
|---|---|---|
| committer | Andrey Andreev <narf@devilix.net> | 2019-09-19 14:08:45 +0200 |
| commit | b73eb19aed66190c10c9cad476da7c36c271d6dc (patch) | |
| tree | b3d5d4f960569c30701934416d6d51628bde81a7 /user_guide_src/source/libraries | |
| parent | 6e052d80b95b9332ed592cdc3431b5f9dc8dd250 (diff) | |
[ci skip] 3.1.11 release
Diffstat (limited to 'user_guide_src/source/libraries')
31 files changed, 0 insertions, 10915 deletions
diff --git a/user_guide_src/source/libraries/benchmark.rst b/user_guide_src/source/libraries/benchmark.rst deleted file mode 100644 index 8fc06be12..000000000 --- a/user_guide_src/source/libraries/benchmark.rst +++ /dev/null @@ -1,168 +0,0 @@ -################## -Benchmarking Class -################## - -CodeIgniter has a Benchmarking class that is always active, enabling the -time difference between any two marked points to be calculated. - -.. note:: This class is initialized automatically by the system so there - is no need to do it manually. - -In addition, the benchmark is always started the moment the framework is -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:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -************************* -Using the Benchmark Class -************************* - -The Benchmark class can be used within your -:doc:`controllers </general/controllers>`, -:doc:`views </general/views>`, or your :doc:`models </general/models>`. -The process for usage is this: - -#. Mark a start point -#. Mark an end point -#. Run the "elapsed time" function to view the results - -Here's an example using real code:: - - $this->benchmark->mark('code_start'); - - // Some code happens here - - $this->benchmark->mark('code_end'); - - echo $this->benchmark->elapsed_time('code_start', 'code_end'); - -.. note:: The words "code_start" and "code_end" are arbitrary. They - are simply words used to set two markers. You can use any words you - want, and you can set multiple sets of markers. Consider this example:: - - $this->benchmark->mark('dog'); - - // Some code happens here - - $this->benchmark->mark('cat'); - - // More code happens here - - $this->benchmark->mark('bird'); - - echo $this->benchmark->elapsed_time('dog', 'cat'); - echo $this->benchmark->elapsed_time('cat', 'bird'); - echo $this->benchmark->elapsed_time('dog', 'bird'); - - -Profiling Your Benchmark Points -=============================== - -If you want your benchmark data to be available to the -:doc:`Profiler </general/profiling>` all of your marked points must -be set up in pairs, and each mark point name must end with _start and -_end. Each pair of points must otherwise be named identically. Example:: - - $this->benchmark->mark('my_mark_start'); - - // Some code happens here... - - $this->benchmark->mark('my_mark_end'); - - $this->benchmark->mark('another_mark_start'); - - // Some more code happens here... - - $this->benchmark->mark('another_mark_end'); - -Please read the :doc:`Profiler page </general/profiling>` for more -information. - -Displaying Total Execution Time -=============================== - -If you would like to display the total elapsed time from the moment -CodeIgniter starts to the moment the final output is sent to the -browser, simply place this in one of your view templates:: - - <?php echo $this->benchmark->elapsed_time();?> - -You'll notice that it's the same function used in the examples above to -calculate the time between two point, except you are **not** using any -parameters. When the parameters are absent, CodeIgniter does not stop -the benchmark until right before the final output is sent to the -browser. It doesn't matter where you use the function call, the timer -will continue to run until the very end. - -An alternate way to show your elapsed time in your view files is to use -this pseudo-variable, if you prefer not to use the pure PHP:: - - {elapsed_time} - -.. note:: If you want to benchmark anything within your controller - functions you must set your own start/end points. - -Displaying Memory Consumption -============================= - -If your PHP installation is configured with --enable-memory-limit, you -can display the amount of memory consumed by the entire system using the -following code in one of your view file:: - - <?php echo $this->benchmark->memory_usage();?> - -.. note:: This function can only be used in your view files. The consumption - will reflect the total memory used by the entire app. - -An alternate way to show your memory usage in your view files is to use -this pseudo-variable, if you prefer not to use the pure PHP:: - - {memory_usage} - - -*************** -Class Reference -*************** - -.. php:class:: CI_Benchmark - - .. php:method:: mark($name) - - :param string $name: the name you wish to assign to your marker - :rtype: void - - Sets a benchmark marker. - - .. php: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: Elapsed time - :rtype: 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. - - - .. php:method:: memory_usage() - - :returns: Memory usage info - :rtype: 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 <output>` will - swap the real value for this variable.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/caching.rst b/user_guide_src/source/libraries/caching.rst deleted file mode 100644 index a7081ec6b..000000000 --- a/user_guide_src/source/libraries/caching.rst +++ /dev/null @@ -1,279 +0,0 @@ -############## -Caching Driver -############## - -CodeIgniter features wrappers around some of the most popular forms of -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:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -************* -Example Usage -************* - -The following example will load the cache driver, specify `APC <#alternative-php-cache-apc-caching>`_ -as the driver to use, and fall back to file-based caching if APC is not -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!<br />'; - $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 -to avoid collisions when you're running multiple applications on the same environment. - -:: - - $this->load->driver('cache', - array('adapter' => 'apc', 'backup' => 'file', 'key_prefix' => 'my_') - ); - - $this->cache->get('foo'); // Will get the cache entry named 'my_foo' - -*************** -Class Reference -*************** - -.. php:class:: CI_Cache - - .. php:method:: is_supported($driver) - - :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, - make sure to call this method to ensure the driver is supported in the - hosting environment. - :: - - if ($this->cache->apc->is_supported()) - { - if ($data = $this->cache->apc->get('my_cache')) - { - // do things. - } - } - - .. php:method:: get($id) - - :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. - :: - - $foo = $this->cache->get('my_cached_item'); - - .. php:method:: save($id, $data[, $ttl = 60[, $raw = FALSE]]) - - :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. - :: - - $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()``. - - .. php:method:: delete($id) - - :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. - :: - - $this->cache->delete('cache_item_id'); - - .. php: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 - :rtype: mixed - - 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 - - .. php: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 - :rtype: mixed - - 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 - - .. php:method:: clean() - - :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. - :: - - $this->cache->clean(); - - .. php:method:: cache_info() - - :returns: Information on the entire cache database - :rtype: mixed - - This method will return information on the entire cache. - :: - - var_dump($this->cache->cache_info()); - - .. note:: The information returned and the structure of the data is dependent - on which adapter is being used. - - .. php:method:: get_metadata($id) - - :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. - :: - - var_dump($this->cache->get_metadata('my_cached_item')); - - .. note:: The information returned and the structure of the data is dependent - on which adapter is being used. - -******* -Drivers -******* - -Alternative PHP Cache (APC) Caching -=================================== - -All of the methods listed above can be accessed without passing a -specific adapter to the driver loader as follows:: - - $this->load->driver('cache'); - $this->cache->apc->save('foo', 'bar', 10); - -For more information on APC, please see -`http://php.net/apc <http://php.net/apc>`_. - -File-based Caching -================== - -Unlike caching from the Output Class, the driver file-based caching -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 methods listed above can be accessed without passing a -specific adapter to the driver loader as follows:: - - $this->load->driver('cache'); - $this->cache->file->save('foo', 'bar', 10); - -Memcached Caching -================= - -Multiple Memcached servers can be specified in the memcached.php -configuration file, located in the _application/config/* directory. - -All of the methods listed above can be accessed without passing a -specific adapter to the driver loader as follows:: - - $this->load->driver('cache'); - $this->cache->memcached->save('foo', 'bar', 10); - -For more information on Memcached, please see -`http://php.net/memcached <http://php.net/memcached>`_. - -WinCache Caching -================ - -Under Windows, you can also utilize the WinCache driver. - -All of the methods listed above can be accessed without passing a -specific adapter to the driver loader as follows:: - - $this->load->driver('cache'); - $this->cache->wincache->save('foo', 'bar', 10); - -For more information on WinCache, please see -`http://php.net/wincache <http://php.net/wincache>`_. - -Redis Caching -============= - -Redis is an in-memory key-value store which can operate in LRU cache mode. -To use it, you need `Redis server and phpredis PHP extension <https://github.com/phpredis/phpredis>`_. - -Config options to connect to redis server must be stored in the application/config/redis.php file. -Available options are:: - - $config['socket_type'] = 'tcp'; //`tcp` or `unix` - $config['socket'] = '/var/run/redis.sock'; // in case of `unix` socket type - $config['host'] = '127.0.0.1'; - $config['password'] = NULL; - $config['port'] = 6379; - $config['timeout'] = 0; - -All of the methods listed above can be accessed without passing a -specific adapter to the driver loader as follows:: - - $this->load->driver('cache'); - $this->cache->redis->save('foo', 'bar', 10); - -For more information on Redis, please see -`http://redis.io <http://redis.io>`_. - -Dummy Cache -=========== - -This is a caching backend that will always 'miss.' It stores no data, -but lets you keep your caching code in place in environments that don't -support your chosen cache.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/calendar.rst b/user_guide_src/source/libraries/calendar.rst deleted file mode 100644 index 8fdacf1d7..000000000 --- a/user_guide_src/source/libraries/calendar.rst +++ /dev/null @@ -1,307 +0,0 @@ -################# -Calendaring Class -################# - -The Calendar class enables you to dynamically create calendars. Your -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 - - <div class="custom-index container"></div> - -*************************** -Using the Calendaring Class -*************************** - -Initializing the Class -====================== - -Like most other classes in CodeIgniter, the Calendar class is -initialized in your controller using the $this->load->library function:: - - $this->load->library('calendar'); - -Once loaded, the Calendar object will be available using:: - - $this->calendar - -Displaying a Calendar -===================== - -Here is a very simple example showing how you can display a calendar:: - - $this->load->library('calendar'); - echo $this->calendar->generate(); - -The above code will generate a calendar for the current month/year based -on your server time. To show a calendar for a specific month and year -you will pass this information to the calendar generating function:: - - $this->load->library('calendar'); - echo $this->calendar->generate(2006, 6); - -The above code will generate a calendar showing the month of June in -2006. The first parameter specifies the year, the second parameter -specifies the month. - -Passing Data to your Calendar Cells -=================================== - -To add data to your calendar cells involves creating an associative -array in which the keys correspond to the days you wish to populate and -the array value contains the data. The array is passed to the third -parameter of the calendar generating function. Consider this example:: - - $this->load->library('calendar'); - - $data = array( - 3 => 'http://example.com/news/article/2006/06/03/', - 7 => 'http://example.com/news/article/2006/06/07/', - 13 => 'http://example.com/news/article/2006/06/13/', - 26 => 'http://example.com/news/article/2006/06/26/' - ); - - echo $this->calendar->generate(2006, 6, $data); - -Using the above example, day numbers 3, 7, 13, and 26 will become links -pointing to the URLs you've provided. - -.. note:: By default it is assumed that your array will contain links. - In the section that explains the calendar template below you'll see how - you can customize how data passed to your cells is handled so you can - pass different types of information. - -Setting Display Preferences -=========================== - -There are seven preferences you can set to control various aspects of -the calendar. Preferences are set by passing an array of preferences in -the second parameter of the loading function. Here is an example:: - - $prefs = array( - 'start_day' => 'saturday', - 'month_type' => 'long', - 'day_type' => 'short' - ); - - $this->load->library('calendar', $prefs); - - echo $this->calendar->generate(); - -The above code would start the calendar on saturday, use the "long" -month heading, and the "short" day names. More information regarding -preferences below. - -====================== ================= ============================================ =================================================================== -Preference Default Options Description -====================== ================= ============================================ =================================================================== -**template** None None A string or array containing your calendar template. - See the template section below. -**local_time** time() None A Unix timestamp corresponding to the current time. -**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 - 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. -**next_prev_url** controller/method A URL Sets the basepath used in the next/previous calendar links. -**show_other_days** FALSE TRUE/FALSE (boolean) Determines whether to display days of other months that share the - first or last week of the calendar month. -====================== ================= ============================================ =================================================================== - - -Showing Next/Previous Month Links -================================= - -To allow your calendar to dynamically increment/decrement via the -next/previous links requires that you set up your calendar code similar -to this example:: - - $prefs = array( - 'show_next_prev' => TRUE, - 'next_prev_url' => 'http://example.com/index.php/calendar/show/' - ); - - $this->load->library('calendar', $prefs); - - echo $this->calendar->generate($this->uri->segment(3), $this->uri->segment(4)); - -You'll notice a few things about the above example: - -- You must set the "show_next_prev" to TRUE. -- You must supply the URL to the controller containing your calendar in - the "next_prev_url" preference. If you don't, it will be set to the current - *controller/method*. -- You must supply the "year" and "month" to the calendar generating - function via the URI segments where they appear (Note: The calendar - class automatically adds the year/month to the base URL you - provide.). - -Creating a Calendar Template -============================ - -By creating a calendar template you have 100% control over the design of -your calendar. Using the string method, each component of your calendar -will be placed within a pair of pseudo-variables as shown here:: - - $prefs['template'] = ' - - {table_open}<table border="0" cellpadding="0" cellspacing="0">{/table_open} - - {heading_row_start}<tr>{/heading_row_start} - - {heading_previous_cell}<th><a href="{previous_url}"><<</a></th>{/heading_previous_cell} - {heading_title_cell}<th colspan="{colspan}">{heading}</th>{/heading_title_cell} - {heading_next_cell}<th><a href="{next_url}">>></a></th>{/heading_next_cell} - - {heading_row_end}</tr>{/heading_row_end} - - {week_row_start}<tr>{/week_row_start} - {week_day_cell}<td>{week_day}</td>{/week_day_cell} - {week_row_end}</tr>{/week_row_end} - - {cal_row_start}<tr>{/cal_row_start} - {cal_cell_start}<td>{/cal_cell_start} - {cal_cell_start_today}<td>{/cal_cell_start_today} - {cal_cell_start_other}<td class="other-month">{/cal_cell_start_other} - - {cal_cell_content}<a href="{content}">{day}</a>{/cal_cell_content} - {cal_cell_content_today}<div class="highlight"><a href="{content}">{day}</a></div>{/cal_cell_content_today} - - {cal_cell_no_content}{day}{/cal_cell_no_content} - {cal_cell_no_content_today}<div class="highlight">{day}</div>{/cal_cell_no_content_today} - - {cal_cell_blank} {/cal_cell_blank} - - {cal_cell_other}{day}{/cal_cel_other} - - {cal_cell_end}</td>{/cal_cell_end} - {cal_cell_end_today}</td>{/cal_cell_end_today} - {cal_cell_end_other}</td>{/cal_cell_end_other} - {cal_row_end}</tr>{/cal_row_end} - - {table_close}</table>{/table_close} - '; - - $this->load->library('calendar', $prefs); - - echo $this->calendar->generate(); - -Using the array method, you will pass `key => value` pairs. You can pass as -many or as few values as you'd like. Omitted keys will use the default values -inherited in the calendar class. - -Example:: - - $prefs['template'] = array( - 'table_open' => '<table class="calendar">', - 'cal_cell_start' => '<td class="day">', - 'cal_cell_start_today' => '<td class="today">' - ); - - $this->load->library('calendar', $prefs); - - echo $this->calendar->generate(); - -*************** -Class Reference -*************** - -.. php:class:: CI_Calendar - - .. php:method:: initialize([$config = array()]) - - :param array $config: Configuration parameters - :returns: CI_Calendar instance (method chaining) - :rtype: CI_Calendar - - Initializes the Calendaring preferences. Accepts an associative array as input, containing display preferences. - - .. php:method:: generate([$year = ''[, $month = ''[, $data = array()]]]) - - :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. - - - .. php:method:: get_month_name($month) - - :param int $month: Month - :returns: Month name - :rtype: string - - Generates a textual month name based on the numeric month provided. - - .. php:method:: get_day_names($day_type = '') - - :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. - - .. php:method:: adjust_date($month, $year) - - :param int $month: Month - :param int $year: Year - :returns: An associative array containing month and year - :rtype: array - - 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:: - - print_r($this->calendar->adjust_date(13, 2014)); - - outputs:: - - Array - ( - [month] => '01' - [year] => '2015' - ) - - .. php:method:: get_total_days($month, $year) - - :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 - - .. note:: This method is an alias for :doc:`Date Helper - <../helpers/date_helper>` function :php:func:`days_in_month()`. - - .. php:method:: default_template() - - :returns: An array of template values - :rtype: array - - Sets the default template. This method is used when you have not created - your own template. - - - .. php:method:: parse_template() - - :returns: CI_Calendar instance (method chaining) - :rtype: CI_Calendar - - Harvests the data within the template ``{pseudo-variables}`` used to - display the calendar. diff --git a/user_guide_src/source/libraries/cart.rst b/user_guide_src/source/libraries/cart.rst deleted file mode 100644 index be343320d..000000000 --- a/user_guide_src/source/libraries/cart.rst +++ /dev/null @@ -1,398 +0,0 @@ -################### -Shopping Cart Class -################### - -The Cart Class permits items to be added to a session that stays active -while a user is browsing your site. These items can be retrieved and -displayed in a standard "shopping cart" format, allowing the user to -update the quantity or remove items from the cart. - -.. important:: The Cart library is DEPRECATED and should not be used. - It is currently only kept for backwards compatibility. - -Please note that the Cart Class ONLY provides the core "cart" -functionality. It does not provide shipping, credit card authorization, -or other processing components. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -******************** -Using the Cart Class -******************** - -Initializing the Shopping Cart Class -==================================== - -.. important:: The Cart class utilizes CodeIgniter's :doc:`Session - Class <sessions>` to save the cart information to a database, so - before using the Cart class you must set up a database table as - indicated in the :doc:`Session Documentation <sessions>`, and set the - session preferences in your application/config/config.php file to - utilize a database. - -To initialize the Shopping Cart Class in your controller constructor, -use the ``$this->load->library()`` method:: - - $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 - automatically, so unless you are using sessions elsewhere in your - application, you do not need to load the Session class. - -Adding an Item to The Cart -========================== - -To add an item to the shopping cart, simply pass an array with the -product information to the ``$this->cart->insert()`` method, as shown -below:: - - $data = array( - 'id' => 'sku_123ABC', - 'qty' => 1, - 'price' => 39.95, - 'name' => 'T-Shirt', - 'options' => array('Size' => 'L', 'Color' => 'Red') - ); - - $this->cart->insert($data); - -.. important:: The first four array indexes above (id, qty, price, and - name) are **required**. If you omit any of them the data will not be - saved to the cart. The fifth index (options) is optional. It is intended - to be used in cases where your product has options associated with it. - Use an array for options, as shown above. - -The five reserved indexes are: - -- **id** - Each product in your store must have a unique identifier. - Typically this will be an "sku" or other such identifier. -- **qty** - The quantity being purchased. -- **price** - The price of the item. -- **name** - The name of the item. -- **options** - Any additional attributes that are needed to identify - the product. These must be passed via an array. - -In addition to the five indexes above, there are two reserved words: -rowid and subtotal. These are used internally by the Cart class, so -please do NOT use those words as index names when inserting data into -the cart. - -Your array may contain additional data. Anything you include in your -array will be stored in the session. However, it is best to standardize -your data among all your products in order to make displaying the -information in a table easier. - -:: - - $data = array( - 'id' => 'sku_123ABC', - 'qty' => 1, - 'price' => 39.95, - 'name' => 'T-Shirt', - 'coupon' => 'XMAS-50OFF' - ); - - $this->cart->insert($data); - -The ``insert()`` method will return the $rowid if you successfully insert a -single item. - -Adding Multiple Items to The Cart -================================= - -By using a multi-dimensional array, as shown below, it is possible to -add multiple products to the cart in one action. This is useful in cases -where you wish to allow people to select from among several items on the -same page. - -:: - - $data = array( - array( - 'id' => 'sku_123ABC', - 'qty' => 1, - 'price' => 39.95, - 'name' => 'T-Shirt', - 'options' => array('Size' => 'L', 'Color' => 'Red') - ), - array( - 'id' => 'sku_567ZYX', - 'qty' => 1, - 'price' => 9.95, - 'name' => 'Coffee Mug' - ), - array( - 'id' => 'sku_965QRS', - 'qty' => 1, - 'price' => 29.95, - 'name' => 'Shot Glass' - ) - ); - - $this->cart->insert($data); - -Displaying the Cart -=================== - -To display the cart you will create a :doc:`view -file </general/views>` with code similar to the one shown below. - -Please note that this example uses the :doc:`form -helper </helpers/form_helper>`. - -:: - - <?php echo form_open('path/to/controller/update/method'); ?> - - <table cellpadding="6" cellspacing="1" style="width:100%" border="0"> - - <tr> - <th>QTY</th> - <th>Item Description</th> - <th style="text-align:right">Item Price</th> - <th style="text-align:right">Sub-Total</th> - </tr> - - <?php $i = 1; ?> - - <?php foreach ($this->cart->contents() as $items): ?> - - <?php echo form_hidden($i.'[rowid]', $items['rowid']); ?> - - <tr> - <td><?php echo form_input(array('name' => $i.'[qty]', 'value' => $items['qty'], 'maxlength' => '3', 'size' => '5')); ?></td> - <td> - <?php echo $items['name']; ?> - - <?php if ($this->cart->has_options($items['rowid']) == TRUE): ?> - - <p> - <?php foreach ($this->cart->product_options($items['rowid']) as $option_name => $option_value): ?> - - <strong><?php echo $option_name; ?>:</strong> <?php echo $option_value; ?><br /> - - <?php endforeach; ?> - </p> - - <?php endif; ?> - - </td> - <td style="text-align:right"><?php echo $this->cart->format_number($items['price']); ?></td> - <td style="text-align:right">$<?php echo $this->cart->format_number($items['subtotal']); ?></td> - </tr> - - <?php $i++; ?> - - <?php endforeach; ?> - - <tr> - <td colspan="2"> </td> - <td class="right"><strong>Total</strong></td> - <td class="right">$<?php echo $this->cart->format_number($this->cart->total()); ?></td> - </tr> - - </table> - - <p><?php echo form_submit('', 'Update your Cart'); ?></p> - -Updating The Cart -================= - -To update the information in your cart, you must pass an array -containing the Row ID and one or more pre-defined properties to the -``$this->cart->update()`` method. - -.. note:: If the quantity is set to zero, the item will be removed from - the cart. - -:: - - $data = array( - 'rowid' => 'b99ccdf16028f015540f341130b6d8ec', - 'qty' => 3 - ); - - $this->cart->update($data); - - // Or a multi-dimensional array - - $data = array( - array( - 'rowid' => 'b99ccdf16028f015540f341130b6d8ec', - 'qty' => 3 - ), - array( - 'rowid' => 'xw82g9q3r495893iajdh473990rikw23', - 'qty' => 4 - ), - array( - 'rowid' => 'fh4kdkkkaoe30njgoe92rkdkkobec333', - 'qty' => 2 - ) - ); - - $this->cart->update($data); - -You may also update any property you have previously defined when -inserting the item such as options, price or other custom fields. - -:: - - $data = array( - 'rowid' => 'b99ccdf16028f015540f341130b6d8ec', - 'qty' => 1, - 'price' => 49.95, - 'coupon' => NULL - ); - - $this->cart->update($data); - -What is a Row ID? -***************** - -The row ID is a unique identifier that is generated by the cart code -when an item is added to the cart. The reason a unique ID is created -is so that identical products with different options can be managed -by the cart. - -For example, let's say someone buys two identical t-shirts (same product -ID), but in different sizes. The product ID (and other attributes) will -be identical for both sizes because it's the same shirt. The only -difference will be the size. The cart must therefore have a means of -identifying this difference so that the two sizes of shirts can be -managed independently. It does so by creating a unique "row ID" based on -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 than making -sure your "view cart" page contains this information in a hidden form -field, and making sure it gets passed to the ``update()`` method when -the update form is submitted. Please examine the construction of the -"view cart" page above for more information. - - -*************** -Class Reference -*************** - -.. php: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. - - - .. php:method:: insert([$items = array()]) - - :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. - - - .. php:method:: update([$items = array()]) - - :param array $items: Items to update in the cart - :returns: TRUE on success, FALSE on failure - :rtype: bool - - This method permits changing the properties of a given item. - Typically it is called from the "view cart" page if a user makes changes - to the quantity before checkout. That array must contain the rowid - for each item. - - .. php:method:: remove($rowid) - - :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``. - - .. php:method:: total() - - :returns: Total amount - :rtype: int - - Displays the total amount in the cart. - - - .. php:method:: total_items() - - :returns: Total amount of items in the cart - :rtype: int - - Displays the total number of items in the cart. - - - .. php:method:: contents([$newest_first = FALSE]) - - :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. - - .. php:method:: get_item($row_id) - - :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. - - .. php:method:: has_options($row_id = '') - - :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 ``contents()``, since - you must pass the rowid to this method, as shown in the Displaying - the Cart example above. - - .. php:method:: product_options([$row_id = '']) - - :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 ``contents()``, since you - must pass the rowid to this method, as shown in the Displaying the - Cart example above. - - .. php:method:: destroy() - - :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 deleted file mode 100644 index fe2e0a99d..000000000 --- a/user_guide_src/source/libraries/config.rst +++ /dev/null @@ -1,252 +0,0 @@ -############ -Config Class -############ - -The Config class provides a means to retrieve configuration preferences. -These preferences can come from the default config file -(application/config/config.php) or from your own custom config files. - -.. note:: This class is initialized automatically by the system so there - is no need to do it manually. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -***************************** -Working with the Config Class -***************************** - -Anatomy of a Config File -======================== - -By default, CodeIgniter has one primary config file, located at -application/config/config.php. If you open the file using your text -editor you'll see that config items are stored in an array called -$config. - -You can add your own config items to this file, or if you prefer to keep -your configuration items separate (assuming you even need config items), -simply create your own file and save it in config folder. - -.. note:: If you do create your own config files use the same format as - the primary one, storing your items in an array called $config. - CodeIgniter will intelligently manage these files so there will be no - conflict even though the array has the same name (assuming an array - index is not named the same as another). - -Loading a Config File -===================== - -.. note:: - CodeIgniter automatically loads the primary config file - (application/config/config.php), so you will only need to load a config - file if you have created your own. - -There are two ways to load a config file: - -Manual Loading -************** - -To load one of your custom config files you will use the following -function within the :doc:`controller </general/controllers>` that -needs it:: - - $this->config->load('filename'); - -Where filename is the name of your config file, without the .php file -extension. - -If you need to load multiple config files normally they will be -merged into one master config array. Name collisions can occur, -however, if you have identically named array indexes in different -config files. To avoid collisions you can set the second parameter to -TRUE and each config file will be stored in an array index -corresponding to the name of the config file. Example:: - - // Stored in an array with this prototype: $this->config['blog_settings'] = $config - $this->config->load('blog_settings', TRUE); - -Please see the section entitled Fetching Config Items below to learn -how to retrieve config items set this way. - -The third parameter allows you to suppress errors in the event that a -config file does not exist:: - - $this->config->load('blog_settings', FALSE, TRUE); - -Auto-loading -************ - -If you find that you need a particular config file globally, you can -have it loaded automatically by the system. To do this, open the -**autoload.php** file, located at application/config/autoload.php, -and add your config file as indicated in the file. - - -Fetching Config Items -===================== - -To retrieve an item from your config file, use the following function:: - - $this->config->item('item_name'); - -Where item_name is the $config array index you want to retrieve. For -example, to fetch your language choice you'll do this:: - - $lang = $this->config->item('language'); - -The function returns NULL if the item you are trying to fetch -does not exist. - -If you are using the second parameter of the $this->config->load -function in order to assign your config items to a specific index you -can retrieve it by specifying the index name in the second parameter of -the $this->config->item() function. Example:: - - // Loads a config file named blog_settings.php and assigns it to an index named "blog_settings" - $this->config->load('blog_settings', TRUE); - - // Retrieve a config item named site_name contained within the blog_settings array - $site_name = $this->config->item('site_name', 'blog_settings'); - - // An alternate way to specify the same item: - $blog_config = $this->config->item('blog_settings'); - $site_name = $blog_config['site_name']; - -Setting a Config Item -===================== - -If you would like to dynamically set a config item or change an existing -one, you can do so using:: - - $this->config->set_item('item_name', 'item_value'); - -Where item_name is the $config array index you want to change, and -item_value is its value. - -.. _config-environments: - -Environments -============ - -You may load different configuration files depending on the current -environment. The ENVIRONMENT constant is defined in index.php, and is -described in detail in the :doc:`Handling -Environments </general/environments>` section. - -To create an environment-specific configuration file, create or copy a -configuration file in application/config/{ENVIRONMENT}/{FILENAME}.php - -For example, to create a production-only config.php, you would: - -#. Create the directory application/config/production/ -#. Copy your existing config.php into the above directory -#. Edit application/config/production/config.php so it contains your - production settings - -When you set the ENVIRONMENT constant to 'production', the settings for -your new production-only config.php will be loaded. - -You can place the following configuration files in environment-specific -folders: - -- Default CodeIgniter configuration files -- Your own custom configuration files - -.. note:: - CodeIgniter always loads the global config file first (i.e., the one in application/config/), - then tries to load the configuration files for the current environment. - This means you are not obligated to place **all** of your configuration files in an - environment folder. Only the files that change per environment. Additionally you don't - have to copy **all** the config items in the environment config file. Only the config items - that you wish to change for your environment. The config items declared in your environment - folders always overwrite those in your global config files. - - -*************** -Class Reference -*************** - -.. php:class:: CI_Config - - .. attribute:: $config - - Array of all loaded config values - - .. attribute:: $is_loaded - - Array of all loaded config files - - - .. php:method:: item($item[, $index='']) - - :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. - - .. php:method:: set_item($item, $value) - - :param string $item: Config item name - :param string $value: Config item value - :rtype: void - - Sets a config file item to the specified value. - - .. php:method:: slash_item($item) - - :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 ``item()``, except it appends a forward - slash to the end of the item, if it exists. - - .. php:method:: load([$file = ''[, $use_sections = FALSE[, $fail_gracefully = FALSE]]]) - - :param string $file: Configuration file name - :param bool $use_sections: Whether config values should 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. - - .. php:method:: site_url() - - :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. - - This method is normally accessed via the corresponding functions in the - :doc:`URL Helper </helpers/url_helper>`. - - .. php:method:: base_url() - - :returns: Base URL - :rtype: 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 </helpers/url_helper>`. - - .. php:method:: system_url() - - :returns: URL pointing at your CI system/ directory - :rtype: string - - This method retrieves the URL to your CodeIgniter system/ directory. - - .. note:: This method is DEPRECATED because it encourages usage of - insecure coding practices. Your *system/* directory shouldn't - be publicly accessible.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/email.rst b/user_guide_src/source/libraries/email.rst deleted file mode 100644 index 1be6e2adb..000000000 --- a/user_guide_src/source/libraries/email.rst +++ /dev/null @@ -1,405 +0,0 @@ -########### -Email Class -########### - -CodeIgniter's robust Email Class supports the following features: - -- Multiple Protocols: Mail, Sendmail, and SMTP -- TLS and SSL Encryption for SMTP -- Multiple recipients -- CC and BCCs -- HTML or Plaintext email -- Attachments -- Word wrapping -- Priorities -- BCC Batch Mode, enabling large email lists to be broken into small - BCC batches. -- Email Debugging tools - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -*********************** -Using the Email Library -*********************** - -Sending Email -============= - -Sending email is not only simple, but you can configure it on the fly or -set your preferences in a config file. - -Here is a basic example demonstrating how you might send email. Note: -This example assumes you are sending the email from one of your -:doc:`controllers <../general/controllers>`. - -:: - - $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->subject('Email Test'); - $this->email->message('Testing the email class.'); - - $this->email->send(); - -Setting Email Preferences -========================= - -There are 21 different preferences available to tailor how your email -messages are sent. You can either set them manually as described here, -or automatically via preferences stored in your config file, described -below: - -Preferences are set by passing an array of preference values to the -email initialize method. Here is an example of how you might set some -preferences:: - - $config['protocol'] = 'sendmail'; - $config['mailpath'] = '/usr/sbin/sendmail'; - $config['charset'] = 'iso-8859-1'; - $config['wordwrap'] = TRUE; - - $this->email->initialize($config); - -.. note:: Most of the preferences have default values that will be used - if you do not set them. - -Setting Email 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 the -email.php, add the $config array in that file. Then save the file at -config/email.php and it will be used automatically. You will NOT need to -use the ``$this->email->initialize()`` method if you save your -preferences in a config file. - -Email Preferences -================= - -The following is a list of all the preferences that can be set when -sending email. - -=================== ====================== ============================ ======================================================================= -Preference Default Value Options Description -=================== ====================== ============================ ======================================================================= -**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. -**smtp_host** No Default None SMTP Server Address. -**smtp_user** No Default None SMTP Username. -**smtp_pass** No Default None SMTP Password. -**smtp_port** 25 None SMTP Port. -**smtp_timeout** 5 None SMTP Timeout (in seconds). -**smtp_keepalive** FALSE TRUE or FALSE (boolean) Enable persistent SMTP connections. -**smtp_crypto** No Default tls or ssl SMTP Encryption -**wordwrap** TRUE TRUE or FALSE (boolean) Enable word-wrap. -**wrapchars** 76 Character count to wrap at. -**mailtype** text text or html Type of mail. If you send HTML email you must send it as a complete web - page. Make sure you don't have any relative links or relative image - paths otherwise they will not work. -**charset** ``$config['charset']`` Character set (utf-8, iso-8859-1, etc.). -**validate** FALSE TRUE or FALSE (boolean) Whether to validate the email address. -**priority** 3 1, 2, 3, 4, 5 Email Priority. 1 = highest. 5 = lowest. 3 = normal. -**crlf** \\n "\\r\\n" or "\\n" or "\\r" Newline character. (Use "\\r\\n" to comply with RFC 822). -**newline** \\n "\\r\\n" or "\\n" or "\\r" Newline character. (Use "\\r\\n" to comply with RFC 822). -**bcc_batch_mode** FALSE TRUE or FALSE (boolean) Enable BCC Batch Mode. -**bcc_batch_size** 200 None Number of emails in each BCC batch. -**dsn** FALSE TRUE or FALSE (boolean) Enable notify message from server -=================== ====================== ============================ ======================================================================= - -Overriding Word Wrapping -======================== - -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:: - - The text of your email that - gets wrapped normally. - - {unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap} - - More text that will be - wrapped normally. - - -Place the item you do not want word-wrapped between: {unwrap} {/unwrap} - -*************** -Class Reference -*************** - -.. php:class:: CI_Email - - .. php:method:: from($from[, $name = ''[, $return_path = NULL]]) - - :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:: - - $this->email->from('you@example.com', 'Your Name'); - - You can also set a Return-Path, to help redirect undelivered mail:: - - $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. - - .. php:method:: reply_to($replyto[, $name = '']) - - :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'); - - .. php:method:: to($to) - - :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 e-mail, - a comma-delimited list or an array:: - - $this->email->to('someone@example.com'); - - :: - - $this->email->to('one@example.com, two@example.com, three@example.com'); - - :: - - $this->email->to( - array('one@example.com', 'two@example.com', 'three@example.com') - ); - - .. php:method:: cc($cc) - - :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. - - .. php:method:: bcc($bcc[, $limit = '']) - - :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()`` 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``. - - .. php:method:: subject($subject) - - :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'); - - .. php:method:: message($body) - - :param string $body: E-mail message body - :returns: CI_Email instance (method chaining) - :rtype: CI_Email - - Sets the e-mail message body:: - - $this->email->message('This is my message'); - - .. php:method:: set_alt_message($str) - - :param string $str: Alternative e-mail message body - :returns: CI_Email instance (method chaining) - :rtype: CI_Email - - Sets the alternative e-mail message body:: - - $this->email->set_alt_message('This is the alternative message'); - - 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. - - .. php:method:: set_header($header, $value) - - :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'); - - .. php:method:: clear([$clear_attachments = FALSE]) - - :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, - permitting the data to be reset between cycles. - - :: - - foreach ($list as $name => $address) - { - $this->email->clear(); - - $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); - - .. php:method:: send([$auto_clear = TRUE]) - - :param bool $auto_clear: Whether to clear message data automatically - :returns: TRUE on success, FALSE on failure - :rtype: bool - - 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()) - { - // 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. - - .. php:method:: attach($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]]) - - :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 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. - 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'); - - You can also use a URL:: - - $this->email->attach('http://example.com/filename.pdf'); - - If you'd like to use a custom file name, you can use the third parameter:: - - $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'); - - .. php:method:: attachment_cid($filename) - - :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. - :: - - $filename = '/img/photo1.jpg'; - $this->email->attach($filename); - foreach ($list as $address) - { - $this->email->to($address); - $cid = $this->email->attachment_cid($filename); - $this->email->message('<img src="cid:'. $cid .'" alt="photo1" />'); - $this->email->send(); - } - - .. note:: Content-ID for each e-mail must be re-created for it to be unique. - - .. php:method:: print_debugger([$include = array('headers', 'subject', 'body')]) - - :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 message. 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')); - - .. note:: By default, all of the raw data will be printed.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/encrypt.rst b/user_guide_src/source/libraries/encrypt.rst deleted file mode 100644 index 67e2a0190..000000000 --- a/user_guide_src/source/libraries/encrypt.rst +++ /dev/null @@ -1,198 +0,0 @@ -############# -Encrypt Class -############# - -The Encrypt Class provides two-way data encryption. It encrypted using -the Mcrypt PHP extension, which is required for the Encrypt Class to run. - -.. important:: This library has been DEPRECATED and is only kept for - backwards compatibility. Please use the new :doc:`Encryption Library - <encryption>`. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -************************* -Using the Encrypt Library -************************* - -Setting your Key -================ - -A *key* is a piece of information that controls the cryptographic -process and permits an encrypted string to be decoded. In fact, the key -you chose will provide the **only** means to decode data that was -encrypted with that key, so not only must you choose the key carefully, -you must never change it if you intend use it for persistent data. - -It goes without saying that you should guard your key carefully. Should -someone gain access to your key, the data will be easily decoded. If -your server is not totally under your control it's impossible to ensure -key security so you may want to think carefully before using it for -anything that requires high security, like storing credit card numbers. - -To take maximum advantage of the encryption algorithm, your key should -be 32 characters in length (256 bits). The key should be as random a -string as you can concoct, with numbers and uppercase and lowercase -letters. Your key should **not** be a simple text string. In order to be -cryptographically secure it needs to be as random as possible. - -Your key can be either stored in your **application/config/config.php**, or -you can design your own storage mechanism and pass the key dynamically -when encoding/decoding. - -To save your key to your **application/config/config.php**, open the file -and set:: - - $config['encryption_key'] = "YOUR KEY"; - -Message Length -============== - -It's important for you to know that the encoded messages the encryption -function generates will be approximately 2.6 times longer than the -original message. For example, if you encrypt the string "my super -secret data", which is 21 characters in length, you'll end up with an -encoded string that is roughly 55 characters (we say "roughly" because -the encoded string length increments in 64 bit clusters, so it's not -exactly linear). Keep this information in mind when selecting your data -storage mechanism. Cookies, for example, can only hold 4K of -information. - -Initializing the Class -====================== - -Like most other classes in CodeIgniter, the Encrypt class is -initialized in your controller using the ``$this->load->library()`` -method:: - - $this->load->library('encrypt'); - -Once loaded, the Encrypt library object will be available using:: - - $this->encrypt - -*************** -Class Reference -*************** - -.. php:class:: CI_Encrypt - - .. php:method:: encode($string[, $key = '']) - - :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:: - - $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); - - .. php:method:: decode($string[, $key = '']) - - :param string $string: String to decrypt - :param string $key: Encryption key - :returns: Plain-text string - :rtype: string - - Decrypts an encoded string. Example:: - - $encrypted_string = 'APANtByIGI1BpVXZTJgcsAG8GZl8pdwwa84'; - - $plaintext_string = $this->encrypt->decode($encrypted_string); - - 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->decode($msg, $key); - - .. php:method:: set_cipher($cipher) - - :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:: - - $this->encrypt->set_cipher(MCRYPT_BLOWFISH); - - Please visit php.net for a list of `available ciphers <http://php.net/mcrypt>`_. - - If you'd like to manually test whether your server supports MCrypt you - can use:: - - echo extension_loaded('mcrypt') ? 'Yup' : 'Nope'; - - .. php:method:: set_mode($mode) - - :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 <http://php.net/mcrypt>`_. - - .. php:method:: encode_from_legacy($string[, $legacy_mode = MCRYPT_MODE_ECB[, $key = '']]) - - :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 Encrypt 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 - Encrypt 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); - - ====================== =============== ======================================================================= - 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 diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst deleted file mode 100644 index b16511d4d..000000000 --- a/user_guide_src/source/libraries/encryption.rst +++ /dev/null @@ -1,585 +0,0 @@ -################## -Encryption Library -################## - -.. important:: DO NOT use this or any other *encryption* library for - user password storage! Passwords must be *hashed* instead, and you - should do that via PHP's own `Password Hashing extension - <http://php.net/password>`_. - -The Encryption Library provides two-way data encryption. To do so in -a cryptographically secure way, it utilizes PHP extensions that are -unfortunately not always available on all systems. -You must meet one of the following dependencies in order to use this -library: - -- `OpenSSL <http://php.net/openssl>`_ -- `MCrypt <http://php.net/mcrypt>`_ (and `MCRYPT_DEV_URANDOM` availability) - -If neither of the above dependencies is met, we simply cannot offer -you a good enough implementation to meet the high standards required -for proper cryptography. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -**************************** -Using the Encryption Library -**************************** - -Initializing the Class -====================== - -Like most other classes in CodeIgniter, the Encryption library is -initialized in your controller using the ``$this->load->library()`` -method:: - - $this->load->library('encryption'); - -Once loaded, the Encryption library object will be available using:: - - $this->encryption - -Default behavior -================ - -By default, the Encryption Library will use the AES-128 cipher in CBC -mode, using your configured *encryption_key* and SHA512 HMAC authentication. - -.. note:: AES-128 is chosen both because it is proven to be strong and - because of its wide availability across different cryptographic - software and programming languages' APIs. - -However, the *encryption_key* is not used as is. - -If you are somewhat familiar with cryptography, you should already know -that a HMAC also requires a secret key and using the same key for both -encryption and authentication is a bad practice. - -Because of that, two separate keys are derived from your already configured -*encryption_key*: one for encryption and one for authentication. This is -done via a technique called `HMAC-based Key Derivation Function -<http://en.wikipedia.org/wiki/HKDF>`_ (HKDF). - -Setting your encryption_key -=========================== - -An *encryption key* is a piece of information that controls the -cryptographic process and permits a plain-text string to be encrypted, -and afterwards - decrypted. It is the secret "ingredient" in the whole -process that allows you to be the only one who is able to decrypt data -that you've decided to hide from the eyes of the public. -After one key is used to encrypt data, that same key provides the **only** -means to decrypt it, so not only must you chose one carefully, but you -must not lose it or you will also lose access to the data. - -It must be noted that to ensure maximum security, such key *should* not -only be as strong as possible, but also often changed. Such behavior -however is rarely practical or possible to implement, and that is why -CodeIgniter gives you the ability to configure a single key that is to be -used (almost) every time. - -It goes without saying that you should guard your key carefully. Should -someone gain access to your key, the data will be easily decrypted. If -your server is not totally under your control it's impossible to ensure -key security so you may want to think carefully before using it for -anything that requires high security, like storing credit card numbers. - -Your encryption key **must** be as long as the encyption algorithm in use -allows. For AES-128, that's 128 bits or 16 bytes (charcters) long. -You will find a table below that shows the supported key lengths of -different ciphers. - -The key should be as random as possible and it **must not** be a regular -text string, nor the output of a hashing function, etc. In order to create -a proper key, you must use the Encryption library's ``create_key()`` method -:: - - // $key will be assigned a 16-byte (128-bit) random key - $key = $this->encryption->create_key(16); - -The key can be either stored in your *application/config/config.php*, or -you can design your own storage mechanism and pass the key dynamically -when encrypting/decrypting. - -To save your key to your *application/config/config.php*, open the file -and set:: - - $config['encryption_key'] = 'YOUR KEY'; - -You'll notice that the ``create_key()`` method outputs binary data, which -is hard to deal with (i.e. a copy-paste may damage it), so you may use -``bin2hex()``, ``hex2bin()`` or Base64-encoding to work with the key in -a more friendly manner. For example:: - - // Get a hex-encoded representation of the key: - $key = bin2hex($this->encryption->create_key(16)); - - // Put the same value in your config with hex2bin(), - // so that it is still passed as binary to the library: - $config['encryption_key'] = hex2bin(<your hex-encoded key>); - -.. _ciphers-and-modes: - -Supported encryption ciphers and modes -====================================== - -.. note:: The terms 'cipher' and 'encryption algorithm' are interchangeable. - -Portable ciphers ----------------- - -Because MCrypt and OpenSSL (also called drivers throughout this document) -each support different sets of encryption algorithms and often implement -them in different ways, our Encryption library is designed to use them in -a portable fashion, or in other words - it enables you to use them -interchangeably, at least for the ciphers supported by both drivers. - -It is also implemented in a way that aims to match the standard -implementations in other programming languages and libraries. - -Here's a list of the so called "portable" ciphers, where -"CodeIgniter name" is the string value that you'd have to pass to the -Encryption library to use that cipher: - -======================== ================== ============================ =============================== -Cipher name CodeIgniter name Key lengths (bits / bytes) Supported modes -======================== ================== ============================ =============================== -AES-128 / Rijndael-128 aes-128 128 / 16 CBC, CTR, CFB, CFB8, OFB, ECB -AES-192 aes-192 192 / 24 CBC, CTR, CFB, CFB8, OFB, ECB -AES-256 aes-256 256 / 32 CBC, CTR, CFB, CFB8, OFB, ECB -DES des 56 / 7 CBC, CFB, CFB8, OFB, ECB -TripleDES tripledes 56 / 7, 112 / 14, 168 / 21 CBC, CFB, CFB8, OFB -Blowfish blowfish 128-448 / 16-56 CBC, CFB, OFB, ECB -CAST5 / CAST-128 cast5 88-128 / 11-16 CBC, CFB, OFB, ECB -RC4 / ARCFour rc4 40-2048 / 5-256 Stream -======================== ================== ============================ =============================== - -.. important:: Because of how MCrypt works, if you fail to provide a key - with the appropriate length, you might end up using a different - algorithm than the one configured, so be really careful with that! - -.. note:: In case it isn't clear from the above table, Blowfish, CAST5 - and RC4 support variable length keys. That is, any number in the - shown ranges is valid, although in bit terms that only happens - in 8-bit increments. - -.. note:: Even though CAST5 supports key lengths lower than 128 bits - (16 bytes), in fact they will just be zero-padded to the - maximum length, as specified in `RFC 2144 - <http://tools.ietf.org/rfc/rfc2144.txt>`_. - -.. note:: Blowfish supports key lengths as small as 32 bits (4 bytes), but - our tests have shown that only lengths of 128 bits (16 bytes) or - higher are properly supported by both MCrypt and OpenSSL. It is - also a bad practice to use such low-length keys anyway. - -Driver-specific ciphers ------------------------ - -As noted above, MCrypt and OpenSSL support different sets of encryption -ciphers. For portability reasons and because we haven't tested them -properly, we do not advise you to use the ones that are driver-specific, -but regardless, here's a list of most of them: - - -============== ========= ============================== ========================================= -Cipher name Driver Key lengths (bits / bytes) Supported modes -============== ========= ============================== ========================================= -AES-128 OpenSSL 128 / 16 CBC, CTR, CFB, CFB8, OFB, ECB, XTS -AES-192 OpenSSL 192 / 24 CBC, CTR, CFB, CFB8, OFB, ECB, XTS -AES-256 OpenSSL 256 / 32 CBC, CTR, CFB, CFB8, OFB, ECB, XTS -Rijndael-128 MCrypt 128 / 16, 192 / 24, 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB -Rijndael-192 MCrypt 128 / 16, 192 / 24, 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB -Rijndael-256 MCrypt 128 / 16, 192 / 24, 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB -GOST MCrypt 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB -Twofish MCrypt 128 / 16, 192 / 24, 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB -CAST-128 MCrypt 40-128 / 5-16 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB -CAST-256 MCrypt 128 / 16, 192 / 24, 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB -Loki97 MCrypt 128 / 16, 192 / 24, 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB -SaferPlus MCrypt 128 / 16, 192 / 24, 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB -Serpent MCrypt 128 / 16, 192 / 24, 256 / 32 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB -XTEA MCrypt 128 / 16 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB -RC2 MCrypt 8-1024 / 1-128 CBC, CTR, CFB, CFB8, OFB, OFB8, ECB -RC2 OpenSSL 8-1024 / 1-128 CBC, CFB, OFB, ECB -Camellia-128 OpenSSL 128 / 16 CBC, CFB, CFB8, OFB, ECB -Camellia-192 OpenSSL 192 / 24 CBC, CFB, CFB8, OFB, ECB -Camellia-256 OpenSSL 256 / 32 CBC, CFB, CFB8, OFB, ECB -Seed OpenSSL 128 / 16 CBC, CFB, OFB, ECB -============== ========= ============================== ========================================= - -.. note:: If you wish to use one of those ciphers, you'd have to pass - its name in lower-case to the Encryption library. - -.. note:: You've probably noticed that all AES cipers (and Rijndael-128) - are also listed in the portable ciphers list. This is because - drivers support different modes for these ciphers. Also, it is - important to note that AES-128 and Rijndael-128 are actually - the same cipher, but **only** when used with a 128-bit key. - -.. note:: CAST-128 / CAST-5 is also listed in both the portable and - driver-specific ciphers list. This is because OpenSSL's - implementation doesn't appear to be working correctly with - key sizes of 80 bits and lower. - -.. note:: RC2 is listed as supported by both MCrypt and OpenSSL. - However, both drivers implement them differently and they - are not portable. It is probably worth noting that we only - found one obscure source confirming that it is MCrypt that - is not properly implementing it. - -.. _encryption-modes: - -Encryption modes ----------------- - -Different modes of encryption have different characteristics and serve -for different purposes. Some are stronger than others, some are faster -and some offer extra features. -We are not going in depth into that here, we'll leave that to the -cryptography experts. The table below is to provide brief informational -reference to our more experienced users. If you are a beginner, just -stick to the CBC mode - it is widely accepted as strong and secure for -general purposes. - -=========== ================== ================= =================================================================================================================================================== -Mode name CodeIgniter name Driver support Additional info -=========== ================== ================= =================================================================================================================================================== -CBC cbc MCrypt, OpenSSL A safe default choice -CTR ctr MCrypt, OpenSSL Considered as theoretically better than CBC, but not as widely available -CFB cfb MCrypt, OpenSSL N/A -CFB8 cfb8 MCrypt, OpenSSL Same as CFB, but operates in 8-bit mode (not recommended). -OFB ofb MCrypt, OpenSSL N/A -OFB8 ofb8 MCrypt Same as OFB, but operates in 8-bit mode (not recommended). -ECB ecb MCrypt, OpenSSL Ignores IV (not recommended). -XTS xts OpenSSL Usually used for encrypting random access data such as RAM or hard-disk storage. -Stream stream MCrypt, OpenSSL This is not actually a mode, it just says that a stream cipher is being used. Required because of the general cipher+mode initialization process. -=========== ================== ================= =================================================================================================================================================== - -Message Length -============== - -It's probably important for you to know that an encrypted string is usually -longer than the original, plain-text string (depending on the cipher). - -This is influenced by the cipher algorithm itself, the IV prepended to the -cipher-text and the HMAC authentication message that is also prepended. -Furthermore, the encrypted message is also Base64-encoded so that it is safe -for storage and transmission, regardless of a possible character set in use. - -Keep this information in mind when selecting your data storage mechanism. -Cookies, for example, can only hold 4K of information. - -.. _configuration: - -Configuring the library -======================= - -For usability, performance, but also historical reasons tied to our old -:doc:`Encrypt Class <encrypt>`, the Encryption library is designed to -use repeatedly the same driver, encryption cipher, mode and key. - -As noted in the "Default behavior" section above, this means using an -auto-detected driver (OpenSSL has a higher priority), the AES-128 ciper -in CBC mode, and your ``$config['encryption_key']`` value. - -If you wish to change that however, you need to use the ``initialize()`` -method. It accepts an associative array of parameters, all of which are -optional: - -======== =============================================== -Option Possible values -======== =============================================== -driver 'mcrypt', 'openssl' -cipher Cipher name (see :ref:`ciphers-and-modes`) -mode Encryption mode (see :ref:`encryption-modes`) -key Encryption key -======== =============================================== - -For example, if you were to change the encryption algorithm and -mode to AES-256 in CTR mode, this is what you should do:: - - $this->encryption->initialize( - array( - 'cipher' => 'aes-256', - 'mode' => 'ctr', - 'key' => '<a 32-character random string>' - ) - ); - -Note that we only mentioned that you want to change the ciper and mode, -but we also included a key in the example. As previously noted, it is -important that you choose a key with a proper size for the used algorithm. - -There's also the ability to change the driver, if for some reason you -have both, but want to use MCrypt instead of OpenSSL:: - - // Switch to the MCrypt driver - $this->encryption->initialize(array('driver' => 'mcrypt')); - - // Switch back to the OpenSSL driver - $this->encryption->initialize(array('driver' => 'openssl')); - -Encrypting and decrypting data -============================== - -Encrypting and decrypting data with the already configured library -settings is simple. As simple as just passing the string to the -``encrypt()`` and/or ``decrypt()`` methods:: - - $plain_text = 'This is a plain-text message!'; - $ciphertext = $this->encryption->encrypt($plain_text); - - // Outputs: This is a plain-text message! - echo $this->encryption->decrypt($ciphertext); - -And that's it! The Encryption library will do everything necessary -for the whole process to be cryptographically secure out-of-the-box. -You don't need to worry about it. - -.. important:: Both methods will return FALSE in case of an error. - While for ``encrypt()`` this can only mean incorrect - configuration, you should always check the return value - of ``decrypt()`` in production code. - -How it works ------------- - -If you must know how the process works, here's what happens under -the hood: - -- ``$this->encryption->encrypt($plain_text)`` - - #. Derive an encryption key and a HMAC key from your configured - *encryption_key* via HKDF, using the SHA-512 digest algorithm. - - #. Generate a random initialization vector (IV). - - #. Encrypt the data via AES-128 in CBC mode (or another previously - configured cipher and mode), using the above-mentioned derived - encryption key and IV. - - #. Prepend said IV to the resulting cipher-text. - - #. Base64-encode the resulting string, so that it can be safely - stored or transferred without worrying about character sets. - - #. Create a SHA-512 HMAC authentication message using the derived - HMAC key to ensure data integrity and prepend it to the Base64 - string. - -- ``$this->encryption->decrypt($ciphertext)`` - - #. Derive an encryption key and a HMAC key from your configured - *encryption_key* via HKDF, using the SHA-512 digest algorithm. - Because your configured *encryption_key* is the same, this - will produce the same result as in the ``encrypt()`` method - above - otherwise you won't be able to decrypt it. - - #. Check if the string is long enough, separate the HMAC out of - it and validate if it is correct (this is done in a way that - prevents timing attacks against it). Return FALSE if either of - the checks fails. - - #. Base64-decode the string. - - #. Separate the IV out of the cipher-text and decrypt the said - cipher-text using that IV and the derived encryption key. - -.. _custom-parameters: - -Using custom parameters ------------------------ - -Let's say you have to interact with another system that is out -of your control and uses another method to encrypt data. A -method that will most certainly not match the above-described -sequence and probably not use all of the steps either. - -The Encryption library allows you to change how its encryption -and decryption processes work, so that you can easily tailor a -custom solution for such situations. - -.. note:: It is possible to use the library in this way, without - setting an *encryption_key* in your configuration file. - -All you have to do is to pass an associative array with a few -parameters to either the ``encrypt()`` or ``decrypt()`` method. -Here's an example:: - - // Assume that we have $ciphertext, $key and $hmac_key - // from on outside source - - $message = $this->encryption->decrypt( - $ciphertext, - array( - 'cipher' => 'blowfish', - 'mode' => 'cbc', - 'key' => $key, - 'hmac_digest' => 'sha256', - 'hmac_key' => $hmac_key - ) - ); - -In the above example, we are decrypting a message that was encrypted -using the Blowfish cipher in CBC mode and authenticated via a SHA-256 -HMAC. - -.. important:: Note that both 'key' and 'hmac_key' are used in this - example. When using custom parameters, encryption and HMAC keys - are not derived like the default behavior of the library is. - -Below is a list of the available options. - -However, unless you really need to and you know what you are doing, -we advise you to not change the encryption process as this could -impact security, so please do so with caution. - -============= =============== ============================= ====================================================== -Option Default value Mandatory / Optional Description -============= =============== ============================= ====================================================== -cipher N/A Yes Encryption algorithm (see :ref:`ciphers-and-modes`). -mode N/A Yes Encryption mode (see :ref:`encryption-modes`). -key N/A Yes Encryption key. -hmac TRUE No Whether to use a HMAC. - Boolean. If set to FALSE, then *hmac_digest* and - *hmac_key* will be ignored. -hmac_digest sha512 No HMAC message digest algorithm (see :ref:`digests`). -hmac_key N/A Yes, unless *hmac* is FALSE HMAC key. -raw_data FALSE No Whether the cipher-text should be raw. - Boolean. If set to TRUE, then Base64 encoding and - decoding will not be performed and HMAC will not - be a hexadecimal string. -============= =============== ============================= ====================================================== - -.. important:: ``encrypt()`` and ``decrypt()`` will return FALSE if - a mandatory parameter is not provided or if a provided - value is incorrect. This includes *hmac_key*, unless *hmac* - is set to FALSE. - -.. _digests: - -Supported HMAC authentication algorithms ----------------------------------------- - -For HMAC message authentication, the Encryption library supports -usage of the SHA-2 family of algorithms: - -=========== ==================== ============================ -Algorithm Raw length (bytes) Hex-encoded length (bytes) -=========== ==================== ============================ -sha512 64 128 -sha384 48 96 -sha256 32 64 -sha224 28 56 -=========== ==================== ============================ - -The reason for not including other popular algorithms, such as -MD5 or SHA1 is that they are no longer considered secure enough -and as such, we don't want to encourage their usage. -If you absolutely need to use them, it is easy to do so via PHP's -native `hash_hmac() <http://php.net/manual/en/function.hash-hmac.php>`_ function. - -Stronger algorithms of course will be added in the future as they -appear and become widely available. - -*************** -Class Reference -*************** - -.. php:class:: CI_Encryption - - .. php:method:: initialize($params) - - :param array $params: Configuration parameters - :returns: CI_Encryption instance (method chaining) - :rtype: CI_Encryption - - Initializes (configures) the library to use a different - driver, cipher, mode or key. - - Example:: - - $this->encryption->initialize( - array('mode' => 'ctr') - ); - - Please refer to the :ref:`configuration` section for detailed info. - - .. php:method:: encrypt($data[, $params = NULL]) - - :param string $data: Data to encrypt - :param array $params: Optional parameters - :returns: Encrypted data or FALSE on failure - :rtype: string - - Encrypts the input data and returns its ciphertext. - - Example:: - - $ciphertext = $this->encryption->encrypt('My secret message'); - - Please refer to the :ref:`custom-parameters` section for information - on the optional parameters. - - .. php:method:: decrypt($data[, $params = NULL]) - - :param string $data: Data to decrypt - :param array $params: Optional parameters - :returns: Decrypted data or FALSE on failure - :rtype: string - - Decrypts the input data and returns it in plain-text. - - Example:: - - echo $this->encryption->decrypt($ciphertext); - - Please refer to the :ref:`custom-parameters` secrion for information - on the optional parameters. - - .. php:method:: create_key($length) - - :param int $length: Output length - :returns: A pseudo-random cryptographic key with the specified length, or FALSE on failure - :rtype: string - - Creates a cryptographic key by fetching random data from - the operating system's sources (i.e. /dev/urandom). - - .. php:method:: hkdf($key[, $digest = 'sha512'[, $salt = NULL[, $length = NULL[, $info = '']]]]) - - :param string $key: Input key material - :param string $digest: A SHA-2 family digest algorithm - :param string $salt: Optional salt - :param int $length: Optional output length - :param string $info: Optional context/application-specific info - :returns: A pseudo-random key or FALSE on failure - :rtype: string - - Derives a key from another, presumably weaker key. - - This method is used internally to derive an encryption and HMAC key - from your configured *encryption_key*. - - It is publicly available due to its otherwise general purpose. It is - described in `RFC 5869 <https://tools.ietf.org/rfc/rfc5869.txt>`_. - - However, as opposed to the description in RFC 5869, this implementation - doesn't support SHA1. - - Example:: - - $hmac_key = $this->encryption->hkdf( - $key, - 'sha512', - NULL, - NULL, - 'authentication' - ); - - // $hmac_key is a pseudo-random key with a length of 64 bytes
\ No newline at end of file diff --git a/user_guide_src/source/libraries/file_uploading.rst b/user_guide_src/source/libraries/file_uploading.rst deleted file mode 100644 index babdc04f9..000000000 --- a/user_guide_src/source/libraries/file_uploading.rst +++ /dev/null @@ -1,355 +0,0 @@ -#################### -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 - - <div class="custom-index container"></div> - -*********** -The Process -*********** - -Uploading a file involves the following general process: - -- An upload form is displayed, allowing a user to select a file and - upload it. -- When the form is submitted, the file is uploaded to the destination - you specify. -- Along the way, the file is validated to make sure it is allowed to be - uploaded based on the preferences you set. -- Once uploaded, the user will be shown a success message. - -To demonstrate this process here is brief tutorial. Afterward you'll -find reference information. - -Creating the Upload Form -======================== - -Using a text editor, create a form called upload_form.php. In it, place -this code and save it to your **application/views/** directory:: - - <html> - <head> - <title>Upload Form</title> - </head> - <body> - - <?php echo $error;?> - - <?php echo form_open_multipart('upload/do_upload');?> - - <input type="file" name="userfile" size="20" /> - - <br /><br /> - - <input type="submit" value="upload" /> - - </form> - - </body> - </html> - -You'll notice we are using a form helper to create the opening form tag. -File uploads require a multipart form, so the helper creates the proper -syntax for you. You'll also notice we have an $error variable. This is -so we can show error messages in the event the user does something -wrong. - -The Success Page -================ - -Using a text editor, create a form called upload_success.php. In it, -place this code and save it to your **application/views/** directory:: - - <html> - <head> - <title>Upload Form</title> - </head> - <body> - - <h3>Your file was successfully uploaded!</h3> - - <ul> - <?php foreach ($upload_data as $item => $value):?> - <li><?php echo $item;?>: <?php echo $value;?></li> - <?php endforeach; ?> - </ul> - - <p><?php echo anchor('upload', 'Upload Another File!'); ?></p> - - </body> - </html> - -The Controller -============== - -Using a text editor, create a controller called Upload.php. In it, place -this code and save it to your **application/controllers/** directory:: - - <?php - - class Upload extends CI_Controller { - - public function __construct() - { - parent::__construct(); - $this->load->helper(array('form', 'url')); - } - - public function index() - { - $this->load->view('upload_form', array('error' => ' ' )); - } - - public function do_upload() - { - $config['upload_path'] = './uploads/'; - $config['allowed_types'] = 'gif|jpg|png'; - $config['max_size'] = 100; - $config['max_width'] = 1024; - $config['max_height'] = 768; - - $this->load->library('upload', $config); - - if ( ! $this->upload->do_upload('userfile')) - { - $error = array('error' => $this->upload->display_errors()); - - $this->load->view('upload_form', $error); - } - else - { - $data = array('upload_data' => $this->upload->data()); - - $this->load->view('upload_success', $data); - } - } - } - ?> - -The Upload Directory -==================== - -You'll need a destination directory for your uploaded images. Create a -directory at the root of your CodeIgniter installation called uploads -and set its file permissions to 777. - -Try it! -======= - -To try your form, visit your site using a URL similar to this one:: - - example.com/index.php/upload/ - -You should see an upload form. Try uploading an image file (either a -jpg, gif, or png). If the path in your controller is correct it should -work. - -*************** -Reference Guide -*************** - -Initializing the Upload Class -============================= - -Like most other classes in CodeIgniter, the Upload class is initialized -in your controller using the ``$this->load->library()`` method:: - - $this->load->library('upload'); - -Once the Upload class is loaded, the object will be available using: -$this->upload - -Setting Preferences -=================== - -Similar to other libraries, you'll control what is allowed to be upload -based on your preferences. In the controller you built above you set the -following preferences:: - - $config['upload_path'] = './uploads/'; - $config['allowed_types'] = 'gif|jpg|png'; - $config['max_size'] = '100'; - $config['max_width'] = '1024'; - $config['max_height'] = '768'; - - $this->load->library('upload', $config); - - // Alternately you can set preferences by calling the ``initialize()`` method. Useful if you auto-load the class: - $this->upload->initialize($config); - -The above preferences should be fairly self-explanatory. Below is a -table describing all available preferences. - -Preferences -=========== - -The following preferences are available. The default value indicates -what will be used if you do not specify that preference. - -============================ ================= ======================= ====================================================================== -Preference Default Value Options Description -============================ ================= ======================= ====================================================================== -**upload_path** None None The path to the directory where the upload should be placed. The - directory must be writable and the path can be absolute or relative. -**allowed_types** None None The mime types corresponding to the types of files you allow to be - uploaded. Usually the file extension can be used as the mime type. - Can be either an array or a pipe-separated string. -**file_name** None Desired file name If set CodeIgniter will rename the uploaded file to this name. The - extension provided in the file name must also be an allowed file type. - If no extension is provided in the original file_name will be used. -**file_ext_tolower** FALSE TRUE/FALSE (boolean) If set to TRUE, the file extension will be forced to lower case -**overwrite** FALSE TRUE/FALSE (boolean) If set to true, if a file with the same name as the one you are - uploading exists, it will be overwritten. If set to false, a number will - be appended to the filename if another with the same name exists. -**max_size** 0 None The maximum size (in kilobytes) that the file can be. Set to zero for no - limit. Note: Most PHP installations have their own limit, as specified - in the php.ini file. Usually 2 MB (or 2048 KB) by default. -**max_width** 0 None The maximum width (in pixels) that the image can be. Set to zero for no - limit. -**max_height** 0 None The maximum height (in pixels) that the image can be. Set to zero for no - limit. -**min_width** 0 None The minimum width (in pixels) that the image can be. Set to zero for no - limit. -**min_height** 0 None The minimum height (in pixels) that the image can be. Set to zero for no - limit. -**max_filename** 0 None The maximum length that a file name can be. Set to zero for no limit. -**max_filename_increment** 100 None When overwrite is set to FALSE, use this to set the maximum filename - increment for CodeIgniter to append to the filename. -**encrypt_name** FALSE TRUE/FALSE (boolean) If set to TRUE the file name will be converted to a random encrypted - string. This can be useful if you would like the file saved with a name - that can not be discerned by the person uploading it. -**remove_spaces** TRUE TRUE/FALSE (boolean) If set to TRUE, any spaces in the file name will be converted to - underscores. This is recommended. -**detect_mime** TRUE TRUE/FALSE (boolean) If set to TRUE, a server side detection of the file type will be - performed to avoid code injection attacks. DO NOT disable this option - unless you have no other option as that would cause a security risk. -**mod_mime_fix** TRUE TRUE/FALSE (boolean) If set to TRUE, multiple filename extensions will be suffixed with an - underscore in order to avoid triggering `Apache mod_mime - <http://httpd.apache.org/docs/2.0/mod/mod_mime.html#multipleext>`_. - DO NOT turn off this option if your upload directory is public, as this - is a security risk. -============================ ================= ======================= ====================================================================== - -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 the -upload.php, add the $config array in that file. Then save the file in: -**config/upload.php** and it will be used automatically. You will NOT -need to use the ``$this->upload->initialize()`` method if you save your -preferences in a config file. - -*************** -Class Reference -*************** - -.. php:class:: CI_Upload - - .. php:method:: initialize([array $config = array()[, $reset = TRUE]]) - - :param array $config: Preferences - :param bool $reset: Whether to reset preferences (that are not provided in $config) to their defaults - :returns: CI_Upload instance (method chaining) - :rtype: CI_Upload - - .. php:method:: do_upload([$field = 'userfile']) - - :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. - - .. 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". - - :: - - <form method="post" action="some_action" enctype="multipart/form-data" /> - - 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); - - .. php:method:: display_errors([$open = '<p>'[, $close = '</p>']]) - - :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 - you can assign it however you need. - - **Formatting Errors** - - By default the above method wraps any errors within <p> tags. You can - set your own delimiters like this:: - - $this->upload->display_errors('<p>', '</p>'); - - - .. php:method:: data([$index = NULL]) - - :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:: - - 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 - - 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 supplied by the client user agent, but possibly sanitized - 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) - ================ ==================================================================================================== diff --git a/user_guide_src/source/libraries/form_validation.rst b/user_guide_src/source/libraries/form_validation.rst deleted file mode 100644 index 16de42338..000000000 --- a/user_guide_src/source/libraries/form_validation.rst +++ /dev/null @@ -1,1143 +0,0 @@ -############### -Form Validation -############### - -CodeIgniter provides a comprehensive form validation and data prepping -class that helps minimize the amount of code you'll write. - -.. contents:: Page Contents - -******** -Overview -******** - -Before explaining CodeIgniter's approach to data validation, let's -describe the ideal scenario: - -#. A form is displayed. -#. You fill it in and submit it. -#. If you submitted something invalid, or perhaps missed a required - item, the form is redisplayed containing your data along with an - error message describing the problem. -#. This process continues until you have submitted a valid form. - -On the receiving end, the script must: - -#. Check for required data. -#. Verify that the data is of the correct type, and meets the correct - criteria. For example, if a username is submitted it must be - validated to contain only permitted characters. It must be of a - minimum length, and not exceed a maximum length. The username can't - be someone else's existing username, or perhaps even a reserved word. - Etc. -#. Sanitize the data for security. -#. Pre-format the data if needed (Does the data need to be trimmed? HTML - encoded? Etc.) -#. Prep the data for insertion in the database. - -Although there is nothing terribly complex about the above process, it -usually requires a significant amount of code, and to display error -messages, various control structures are usually placed within the form -HTML. Form validation, while simple to create, is generally very messy -and tedious to implement. - -************************ -Form Validation Tutorial -************************ - -What follows is a "hands on" tutorial for implementing CodeIgniter's Form -Validation. - -In order to implement form validation you'll need three things: - -#. A :doc:`View <../general/views>` file containing a form. -#. A View file containing a "success" message to be displayed upon - successful submission. -#. A :doc:`controller <../general/controllers>` method to receive and - process the submitted data. - -Let's create those three things, using a member sign-up form as the -example. - -The Form -======== - -Using a text editor, create a form called myform.php. In it, place this -code and save it to your application/views/ folder:: - - <html> - <head> - <title>My Form</title> - </head> - <body> - - <?php echo validation_errors(); ?> - - <?php echo form_open('form'); ?> - - <h5>Username</h5> - <input type="text" name="username" value="" size="50" /> - - <h5>Password</h5> - <input type="text" name="password" value="" size="50" /> - - <h5>Password Confirm</h5> - <input type="text" name="passconf" value="" size="50" /> - - <h5>Email Address</h5> - <input type="text" name="email" value="" size="50" /> - - <div><input type="submit" value="Submit" /></div> - - </form> - - </body> - </html> - -The Success Page -================ - -Using a text editor, create a form called formsuccess.php. In it, place -this code and save it to your application/views/ folder:: - - <html> - <head> - <title>My Form</title> - </head> - <body> - - <h3>Your form was successfully submitted!</h3> - - <p><?php echo anchor('form', 'Try it again!'); ?></p> - - </body> - </html> - -The Controller -============== - -Using a text editor, create a controller called Form.php. In it, place -this code and save it to your application/controllers/ folder:: - - <?php - - class Form extends CI_Controller { - - public function index() - { - $this->load->helper(array('form', 'url')); - - $this->load->library('form_validation'); - - if ($this->form_validation->run() == FALSE) - { - $this->load->view('myform'); - } - else - { - $this->load->view('formsuccess'); - } - } - } - -Try it! -======= - -To try your form, visit your site using a URL similar to this one:: - - example.com/index.php/form/ - -If you submit the form you should simply see the form reload. That's -because you haven't set up any validation rules yet. - -**Since you haven't told the Form Validation class to validate anything -yet, it returns FALSE (boolean false) by default. ``The run()`` method -only returns TRUE if it has successfully applied your rules without any -of them failing.** - -Explanation -=========== - -You'll notice several things about the above pages: - -The form (myform.php) is a standard web form with a couple exceptions: - -#. It uses a form helper to create the form opening. Technically, this - isn't necessary. You could create the form using standard HTML. - However, the benefit of using the helper is that it generates the - action URL for you, based on the URL in your config file. This makes - your application more portable in the event your URLs change. -#. At the top of the form you'll notice the following function call: - :: - - <?php echo validation_errors(); ?> - - This function will return any error messages sent back by the - validator. If there are no messages it returns an empty string. - -The controller (Form.php) has one method: ``index()``. This method -initializes the validation class and loads the form helper and URL -helper used by your view files. It also runs the validation routine. -Based on whether the validation was successful it either presents the -form or the success page. - -.. _setting-validation-rules: - -Setting Validation Rules -======================== - -CodeIgniter lets you set as many validation rules as you need for a -given field, cascading them in order, and it even lets you prep and -pre-process the field data at the same time. To set validation rules you -will use the ``set_rules()`` method:: - - $this->form_validation->set_rules(); - -The above method takes **three** parameters as input: - -#. The field name - the exact name you've given the form field. -#. A "human" name for this field, which will be inserted into the error - message. For example, if your field is named "user" you might give it - a human name of "Username". -#. The validation rules for this form field. -#. (optional) Set custom error messages on any rules given for current field. If not provided will use the default one. - -.. note:: If you would like the field name to be stored in a language - file, please see :ref:`translating-field-names`. - -Here is an example. In your controller (Form.php), add this code just -below the validation initialization method:: - - $this->form_validation->set_rules('username', 'Username', 'required'); - $this->form_validation->set_rules('password', 'Password', 'required'); - $this->form_validation->set_rules('passconf', 'Password Confirmation', 'required'); - $this->form_validation->set_rules('email', 'Email', 'required'); - -Your controller should now look like this:: - - <?php - - class Form extends CI_Controller { - - public function index() - { - $this->load->helper(array('form', 'url')); - - $this->load->library('form_validation'); - - $this->form_validation->set_rules('username', 'Username', 'required'); - $this->form_validation->set_rules('password', 'Password', 'required', - array('required' => 'You must provide a %s.') - ); - $this->form_validation->set_rules('passconf', 'Password Confirmation', 'required'); - $this->form_validation->set_rules('email', 'Email', 'required'); - - if ($this->form_validation->run() == FALSE) - { - $this->load->view('myform'); - } - else - { - $this->load->view('formsuccess'); - } - } - } - -Now submit the form with the fields blank and you should see the error -messages. If you submit the form with all the fields populated you'll -see your success page. - -.. note:: The form fields are not yet being re-populated with the data - when there is an error. We'll get to that shortly. - -Setting Rules Using an Array -============================ - -Before moving on it should be noted that the rule setting method can -be passed an array if you prefer to set all your rules in one action. If -you use this approach, you must name your array keys as indicated:: - - $config = array( - array( - 'field' => 'username', - 'label' => 'Username', - 'rules' => 'required' - ), - array( - 'field' => 'password', - 'label' => 'Password', - 'rules' => 'required', - 'errors' => array( - 'required' => 'You must provide a %s.', - ), - ), - array( - 'field' => 'passconf', - 'label' => 'Password Confirmation', - 'rules' => 'required' - ), - array( - 'field' => 'email', - 'label' => 'Email', - 'rules' => 'required' - ) - ); - - $this->form_validation->set_rules($config); - -Cascading Rules -=============== - -CodeIgniter lets you pipe multiple rules together. Let's try it. Change -your rules in the third parameter of rule setting method, like this:: - - $this->form_validation->set_rules( - 'username', 'Username', - 'required|min_length[5]|max_length[12]|is_unique[users.username]', - array( - 'required' => 'You have not provided %s.', - 'is_unique' => 'This %s already exists.' - ) - ); - $this->form_validation->set_rules('password', 'Password', 'required'); - $this->form_validation->set_rules('passconf', 'Password Confirmation', 'required|matches[password]'); - $this->form_validation->set_rules('email', 'Email', 'required|valid_email|is_unique[users.email]'); - -The above code sets the following rules: - -#. The username field be no shorter than 5 characters and no longer than - 12. -#. The password field must match the password confirmation field. -#. The email field must contain a valid email address. - -Give it a try! Submit your form without the proper data and you'll see -new error messages that correspond to your new rules. There are numerous -rules available which you can read about in the validation reference. - -.. note:: You can also pass an array of rules to ``set_rules()``, - instead of a string. Example:: - - $this->form_validation->set_rules('username', 'Username', array('required', 'min_length[5]')); - -Prepping Data -============= - -In addition to the validation method like the ones we used above, you -can also prep your data in various ways. For example, you can set up -rules like this:: - - $this->form_validation->set_rules('username', 'Username', 'trim|required|min_length[5]|max_length[12]'); - $this->form_validation->set_rules('password', 'Password', 'trim|required|min_length[8]'); - $this->form_validation->set_rules('passconf', 'Password Confirmation', 'trim|required|matches[password]'); - $this->form_validation->set_rules('email', 'Email', 'trim|required|valid_email'); - -In the above example, we are "trimming" the fields, checking for length -where necessary and making sure that both password fields match. - -**Any native PHP function that accepts one parameter can be used as a -rule, like ``htmlspecialchars()``, ``trim()``, etc.** - -.. note:: You will generally want to use the prepping functions - **after** the validation rules so if there is an error, the - original data will be shown in the form. - -Re-populating the form -====================== - -Thus far we have only been dealing with errors. It's time to repopulate -the form field with the submitted data. CodeIgniter offers several -helper functions that permit you to do this. The one you will use most -commonly is:: - - set_value('field name') - -Open your myform.php view file and update the **value** in each field -using the :php:func:`set_value()` function: - -**Don't forget to include each field name in the :php:func:`set_value()` -function calls!** - -:: - - <html> - <head> - <title>My Form</title> - </head> - <body> - - <?php echo validation_errors(); ?> - - <?php echo form_open('form'); ?> - - <h5>Username</h5> - <input type="text" name="username" value="<?php echo set_value('username'); ?>" size="50" /> - - <h5>Password</h5> - <input type="text" name="password" value="<?php echo set_value('password'); ?>" size="50" /> - - <h5>Password Confirm</h5> - <input type="text" name="passconf" value="<?php echo set_value('passconf'); ?>" size="50" /> - - <h5>Email Address</h5> - <input type="text" name="email" value="<?php echo set_value('email'); ?>" size="50" /> - - <div><input type="submit" value="Submit" /></div> - - </form> - - </body> - </html> - -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 methods that permit you to re-populate <select> menus, - radio buttons, and checkboxes. - -.. important:: If you use an array as the name of a form field, you - must supply it as an array to the function. Example:: - - <input type="text" name="colors[]" value="<?php echo set_value('colors[]'); ?>" size="50" /> - -For more info please see the :ref:`using-arrays-as-field-names` section below. - -Callbacks: Your own Validation Methods -====================================== - -The validation system supports callbacks to your own validation -methods. This permits you to extend the validation class to meet your -needs. For example, if you need to run a database query to see if the -user is choosing a unique username, you can create a callback method -that does that. Let's create an example of this. - -In your controller, change the "username" rule to this:: - - $this->form_validation->set_rules('username', 'Username', 'callback_username_check'); - -Then add a new method called ``username_check()`` to your controller. -Here's how your controller should now look:: - - <?php - - class Form extends CI_Controller { - - public function index() - { - $this->load->helper(array('form', 'url')); - - $this->load->library('form_validation'); - - $this->form_validation->set_rules('username', 'Username', 'callback_username_check'); - $this->form_validation->set_rules('password', 'Password', 'required'); - $this->form_validation->set_rules('passconf', 'Password Confirmation', 'required'); - $this->form_validation->set_rules('email', 'Email', 'required|is_unique[users.email]'); - - if ($this->form_validation->run() == FALSE) - { - $this->load->view('myform'); - } - else - { - $this->load->view('formsuccess'); - } - } - - public function username_check($str) - { - if ($str == 'test') - { - $this->form_validation->set_message('username_check', 'The {field} field can not be the word "test"'); - return FALSE; - } - else - { - return TRUE; - } - } - - } - -Reload your form and submit it with the word "test" as the username. You -can see that the form field data was passed to your callback method -for you to process. - -To invoke a callback just put the method name in a rule, with -"callback\_" as the rule **prefix**. If you need to receive an extra -parameter in your callback method, just add it normally after the -method name between square brackets, as in: ``callback_foo[bar]``, -then it will be passed as the second argument of your callback method. - -.. note:: You can also process the form data that is passed to your - callback and return it. If your callback returns anything other than a - boolean TRUE/FALSE it is assumed that the data is your newly processed - form data. - -Callable: Use anything as a rule -================================ - -If callback rules aren't good enough for you (for example, because they are -limited to your controller), don't get disappointed, there's one more way -to create custom rules: anything that ``is_callable()`` would return TRUE for. - -Consider the following example:: - - $this->form_validation->set_rules( - 'username', 'Username', - array( - 'required', - array($this->users_model, 'valid_username') - ) - ); - -The above code would use the ``valid_username()`` method from your -``Users_model`` object. - -This is just an example of course, and callbacks aren't limited to models. -You can use any object/method that accepts the field value as its' first -parameter. You can also use an anonymous function:: - - $this->form_validation->set_rules( - 'username', 'Username', - array( - 'required', - function($value) - { - // Check $value - } - ) - ); - -Of course, since a Callable rule by itself is not a string, it isn't -a rule name either. That is a problem when you want to set error messages -for them. In order to get around that problem, you can put such rules as -the second element of an array, with the first one being the rule name:: - - $this->form_validation->set_rules( - 'username', 'Username', - array( - 'required', - array('username_callable', array($this->users_model, 'valid_username')) - ) - ); - -Anonymous function version:: - - $this->form_validation->set_rules( - 'username', 'Username', - array( - 'required', - array( - 'username_callable', - function($str) - { - // Check validity of $str and return TRUE or FALSE - } - ) - ) - ); - -.. _setting-error-messages: - -Setting Error Messages -====================== - -All of the native error messages are located in the following language -file: **system/language/english/form_validation_lang.php** - -To set your own global custom message for a rule, you can either -extend/override the language file by creating your own in -**application/language/english/form_validation_lang.php** (read more -about this in the :doc:`Language Class <language>` documentation), -or use the following method:: - - $this->form_validation->set_message('rule', 'Error Message'); - -If you need to set a custom error message for a particular field on -some particular rule, use the set_rules() method:: - - $this->form_validation->set_rules('field_name', 'Field Label', 'rule1|rule2|rule3', - array('rule2' => 'Error Message on rule2 for this field_name') - ); - -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 -**{field}** and **{param}** tags to your message, respectively:: - - $this->form_validation->set_message('min_length', '{field} must have at least {param} characters.'); - -On a field with the human name Username and a rule of min_length[5], an -error would display: "Username must have at least 5 characters." - -.. note:: The old `sprintf()` method of using **%s** in your error messages - will still work, however it will override the tags above. You should - use one or the other. - -In the callback rule example above, the error message was set by passing -the name of the method (without the "callback\_" prefix):: - - $this->form_validation->set_message('username_check') - -.. _translating-field-names: - -Translating Field Names -======================= - -If you would like to store the "human" name you passed to the -``set_rules()`` method in a language file, and therefore make the name -able to be translated, here's how: - -First, prefix your "human" name with **lang:**, as in this example:: - - $this->form_validation->set_rules('first_name', 'lang:first_name', 'required'); - -Then, store the name in one of your language file arrays (without the -prefix):: - - $lang['first_name'] = 'First Name'; - -.. note:: If you store your array item in a language file that is not - loaded automatically by CI, you'll need to remember to load it in your - controller using:: - - $this->lang->load('file_name'); - -See the :doc:`Language Class <language>` page for more info regarding -language files. - -.. _changing-delimiters: - -Changing the Error Delimiters -============================= - -By default, the Form Validation class adds a paragraph tag (<p>) around -each error message shown. You can either change these delimiters -globally, individually, or change the defaults in a config file. - -#. **Changing delimiters Globally** - To globally change the error delimiters, in your controller method, - just after loading the Form Validation class, add this:: - - $this->form_validation->set_error_delimiters('<div class="error">', '</div>'); - - In this example, we've switched to using div tags. - -#. **Changing delimiters Individually** - Each of the two error generating functions shown in this tutorial can - be supplied their own delimiters as follows:: - - <?php echo form_error('field name', '<div class="error">', '</div>'); ?> - - Or:: - - <?php echo validation_errors('<div class="error">', '</div>'); ?> - -#. **Set delimiters in a config file** - You can add your error delimiters in application/config/form_validation.php as follows:: - - $config['error_prefix'] = '<div class="error_prefix">'; - $config['error_suffix'] = '</div>'; - -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 :php:func:`form_error()` function. - -Try it! Change your form so that it looks like this:: - - <h5>Username</h5> - <?php echo form_error('username'); ?> - <input type="text" name="username" value="<?php echo set_value('username'); ?>" size="50" /> - - <h5>Password</h5> - <?php echo form_error('password'); ?> - <input type="text" name="password" value="<?php echo set_value('password'); ?>" size="50" /> - - <h5>Password Confirm</h5> - <?php echo form_error('passconf'); ?> - <input type="text" name="passconf" value="<?php echo set_value('passconf'); ?>" size="50" /> - - <h5>Email Address</h5> - <?php echo form_error('email'); ?> - <input type="text" name="email" value="<?php echo set_value('email'); ?>" size="50" /> - -If there are no errors, nothing will be shown. If there is an error, the -message will appear. - -.. important:: If you use an array as the name of a form field, you - must supply it as an array to the function. Example:: - - <?php echo form_error('options[size]'); ?> - <input type="text" name="options[size]" value="<?php echo set_value("options[size]"); ?>" size="50" /> - -For more info please see the :ref:`using-arrays-as-field-names` section below. - -Validating an Array (other than $_POST) -======================================= - -Sometimes you may want to validate an array that does not originate from ``$_POST`` data. - -In this case, you can specify the array to be validated:: - - $data = array( - 'username' => 'johndoe', - 'password' => 'mypassword', - 'passconf' => 'mypassword' - ); - - $this->form_validation->set_data($data); - -Creating validation rules, running the validation, and retrieving error -messages works the same whether you are validating ``$_POST`` data or -another array of your choice. - -.. important:: You have to call the ``set_data()`` method *before* defining - any validation rules. - -.. important:: If you want to validate more than one array during a single - execution, then you should call the ``reset_validation()`` method - before setting up rules and validating the new array. - -For more info please see the :ref:`class-reference` section below. - -.. _saving-groups: - -************************************************ -Saving Sets of Validation Rules to a Config File -************************************************ - -A nice feature of the Form Validation class is that it permits you to -store all your validation rules for your entire application in a config -file. You can organize these rules into "groups". These groups can -either be loaded automatically when a matching controller/method is -called, or you can manually call each set as needed. - -How to save your rules -====================== - -To store your validation rules, simply create a file named -form_validation.php in your application/config/ folder. In that file -you will place an array named $config with your rules. As shown earlier, -the validation array will have this prototype:: - - $config = array( - array( - 'field' => 'username', - 'label' => 'Username', - 'rules' => 'required' - ), - array( - 'field' => 'password', - 'label' => 'Password', - 'rules' => 'required' - ), - array( - 'field' => 'passconf', - 'label' => 'Password Confirmation', - 'rules' => 'required' - ), - array( - 'field' => 'email', - 'label' => 'Email', - 'rules' => 'required' - ) - ); - -Your validation rule file will be loaded automatically and used when you -call the ``run()`` method. - -Please note that you MUST name your ``$config`` array. - -Creating Sets of Rules -====================== - -In order to organize your rules into "sets" requires that you place them -into "sub arrays". Consider the following example, showing two sets of -rules. We've arbitrarily called these two rules "signup" and "email". -You can name your rules anything you want:: - - $config = array( - 'signup' => array( - array( - 'field' => 'username', - 'label' => 'Username', - 'rules' => 'required' - ), - array( - 'field' => 'password', - 'label' => 'Password', - 'rules' => 'required' - ), - array( - 'field' => 'passconf', - 'label' => 'Password Confirmation', - 'rules' => 'required' - ), - array( - 'field' => 'email', - 'label' => 'Email', - 'rules' => 'required' - ) - ), - 'email' => array( - array( - 'field' => 'emailaddress', - 'label' => 'EmailAddress', - 'rules' => 'required|valid_email' - ), - array( - 'field' => 'name', - 'label' => 'Name', - 'rules' => 'required|alpha' - ), - array( - 'field' => 'title', - 'label' => 'Title', - 'rules' => 'required' - ), - array( - 'field' => 'message', - 'label' => 'MessageBody', - 'rules' => 'required' - ) - ) - ); - -Calling a Specific Rule Group -============================= - -In order to call a specific group, you will pass its name to the ``run()`` -method. For example, to call the signup rule you will do this:: - - if ($this->form_validation->run('signup') == FALSE) - { - $this->load->view('myform'); - } - else - { - $this->load->view('formsuccess'); - } - -Associating a Controller Method with a Rule Group -================================================= - -An alternate (and more automatic) method of calling a rule group is to -name it according to the controller class/method you intend to use it -with. For example, let's say you have a controller named Member and a -method named signup. Here's what your class might look like:: - - <?php - - class Member extends CI_Controller { - - public function signup() - { - $this->load->library('form_validation'); - - if ($this->form_validation->run() == FALSE) - { - $this->load->view('myform'); - } - else - { - $this->load->view('formsuccess'); - } - } - } - -In your validation config file, you will name your rule group -member/signup:: - - $config = array( - 'member/signup' => array( - array( - 'field' => 'username', - 'label' => 'Username', - 'rules' => 'required' - ), - array( - 'field' => 'password', - 'label' => 'Password', - 'rules' => 'required' - ), - array( - 'field' => 'passconf', - 'label' => 'PasswordConfirmation', - 'rules' => 'required' - ), - array( - 'field' => 'email', - 'label' => 'Email', - 'rules' => 'required' - ) - ) - ); - -When a rule group is named identically to a controller class/method it -will be used automatically when the ``run()`` method is invoked from that -class/method. - -.. _using-arrays-as-field-names: - -*************************** -Using Arrays as Field Names -*************************** - -The Form Validation class supports the use of arrays as field names. -Consider this example:: - - <input type="text" name="options[]" value="" size="50" /> - -If you do use an array as a field name, you must use the EXACT array -name in the :ref:`Helper Functions <helper-functions>` that require the -field name, and as your Validation Rule field name. - -For example, to set a rule for the above field you would use:: - - $this->form_validation->set_rules('options[]', 'Options', 'required'); - -Or, to show an error for the above field you would use:: - - <?php echo form_error('options[]'); ?> - -Or to re-populate the field you would use:: - - <input type="text" name="options[]" value="<?php echo set_value('options[]'); ?>" size="50" /> - -You can use multidimensional arrays as field names as well. For example:: - - <input type="text" name="options[size]" value="" size="50" /> - -Or even:: - - <input type="text" name="sports[nba][basketball]" value="" size="50" /> - -As with our first example, you must use the exact array name in the -helper functions:: - - <?php echo form_error('sports[nba][basketball]'); ?> - -If you are using checkboxes (or other fields) that have multiple -options, don't forget to leave an empty bracket after each option, so -that all selections will be added to the POST array:: - - <input type="checkbox" name="options[]" value="red" /> - <input type="checkbox" name="options[]" value="blue" /> - <input type="checkbox" name="options[]" value="green" /> - -Or if you use a multidimensional array:: - - <input type="checkbox" name="options[color][]" value="red" /> - <input type="checkbox" name="options[color][]" value="blue" /> - <input type="checkbox" name="options[color][]" value="green" /> - -When you use a helper function you'll include the bracket as well:: - - <?php echo form_error('options[color][]'); ?> - - -************** -Rule Reference -************** - -The following is a list of all the native rules that are available to -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] -**regex_match** Yes Returns FALSE if the form element does not match the regular expression. regex_match[/regex/] -**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. -**min_length** Yes Returns FALSE if the form element is shorter than the parameter value. min_length[3] -**max_length** Yes Returns FALSE if the form element is longer than 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] - or not numeric. -**less_than** Yes Returns FALSE if the form element is greater than or equal to the parameter value or less_than[8] - 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. -**in_list** Yes Returns FALSE if the form element is not within a predetermined list. in_list[red,blue,green] -**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. -**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 - number, but not zero: 1, 2, 3, etc. -**valid_url** No Returns FALSE if the form element does not contain a valid URL. -**valid_email** No Returns FALSE if the form element does not contain a valid email address. -**valid_emails** No Returns FALSE if any value provided in a comma separated list is not a valid email. -**valid_ip** Yes Returns FALSE if the supplied IP address is not valid. - Accepts an optional parameter of 'ipv4' or 'ipv6' to specify an IP format. -**valid_base64** No Returns FALSE if the supplied string contains anything other than valid Base64 characters. -========================= ========== ============================================================================================= ======================= - -.. note:: These rules can also be called as discrete methods. For - example:: - - $this->form_validation->required($string); - -.. note:: You can also use any native PHP functions that permit up - to two parameters, where at least one is required (to pass - the field data). - -****************** -Prepping Reference -****************** - -The following is a list of all the prepping methods that are available -to use: - -==================== ========= ============================================================================================================== -Name Parameter Description -==================== ========= ============================================================================================================== -**prep_for_form** No DEPRECATED: Converts special characters so that HTML data can be shown in a form field without breaking it. -**prep_url** No Adds "\http://" to URLs if missing. -**strip_image_tags** No Strips the HTML from image tags leaving the raw URL. -**encode_php_tags** No Converts PHP tags to entities. -==================== ========= ============================================================================================================== - -.. note:: You can also use any native PHP functions that permits one - parameter, like ``trim()``, ``htmlspecialchars()``, ``urldecode()``, - etc. - -.. _class-reference: - -*************** -Class Reference -*************** - -.. php:class:: CI_Form_validation - - .. php:method:: set_rules($field[, $label = ''[, $rules = ''[, $errors = array()]]]) - - :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 - :param array $errors: A list of custom error messages - :returns: CI_Form_validation instance (method chaining) - :rtype: CI_Form_validation - - Permits you to set validation rules, as described in the tutorial - sections above: - - - :ref:`setting-validation-rules` - - :ref:`saving-groups` - - .. php:method:: run([$group = '']) - - :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 - the method, as described in: :ref:`saving-groups` - - .. php:method:: set_message($lang[, $val = '']) - - :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` - - .. php:method:: set_error_delimiters([$prefix = '<p>'[, $suffix = '</p>']]) - - :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. - - .. php:method:: set_data($data) - - :param array $data: Array of data validate - :returns: CI_Form_validation instance (method chaining) - :rtype: CI_Form_validation - - Permits you to set an array for validation, instead of using the default - ``$_POST`` array. - - .. php:method:: reset_validation() - - :returns: CI_Form_validation instance (method chaining) - :rtype: CI_Form_validation - - Permits you to reset the validation when you validate more than one array. - This method should be called before validating each new array. - - .. php:method:: error_array() - - :returns: Array of error messages - :rtype: array - - Returns the error messages as an array. - - .. php:method:: error_string([$prefix = ''[, $suffix = '']]) - - :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. - - .. php:method:: error($field[, $prefix = ''[, $suffix = '']]) - - :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). - - .. php:method:: has_rule($field) - - :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. - -.. _helper-functions: - -**************** -Helper Reference -**************** - -Please refer to the :doc:`Form Helper <../helpers/form_helper>` manual for -the following functions: - -- :php:func:`form_error()` -- :php:func:`validation_errors()` -- :php:func:`set_value()` -- :php:func:`set_select()` -- :php:func:`set_checkbox()` -- :php:func:`set_radio()` - -Note that these are procedural functions, so they **do not** require you -to prepend them with ``$this->form_validation``. diff --git a/user_guide_src/source/libraries/ftp.rst b/user_guide_src/source/libraries/ftp.rst deleted file mode 100644 index 2a015256d..000000000 --- a/user_guide_src/source/libraries/ftp.rst +++ /dev/null @@ -1,306 +0,0 @@ -######### -FTP Class -######### - -CodeIgniter's FTP Class permits files to be transferred to a remote -server. Remote files can also be moved, renamed, and deleted. The FTP -class also includes a "mirroring" function that permits an entire local -directory to be recreated remotely via FTP. - -.. note:: SFTP and SSL FTP protocols are not supported, only standard - FTP. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -************************** -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:: - - $this->load->library('ftp'); - -Once loaded, the FTP object will be available using: $this->ftp - -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'); - - $config['hostname'] = 'ftp.example.com'; - $config['username'] = 'your-username'; - $config['password'] = 'your-password'; - $config['debug'] = TRUE; - - $this->ftp->connect($config); - - $this->ftp->upload('/local/path/to/myfile.html', '/public_html/myfile.html', 'ascii', 0775); - - $this->ftp->close(); - -In this example a list of files is retrieved from the server. -:: - - $this->load->library('ftp'); - - $config['hostname'] = 'ftp.example.com'; - $config['username'] = 'your-username'; - $config['password'] = 'your-password'; - $config['debug'] = TRUE; - - $this->ftp->connect($config); - - $list = $this->ftp->list_files('/public_html/'); - - print_r($list); - - $this->ftp->close(); - -In this example a local directory is mirrored on the server. -:: - - $this->load->library('ftp'); - - $config['hostname'] = 'ftp.example.com'; - $config['username'] = 'your-username'; - $config['password'] = 'your-password'; - $config['debug'] = TRUE; - - $this->ftp->connect($config); - - $this->ftp->mirror('/path/to/myfolder/', '/public_html/myfolder/'); - - $this->ftp->close(); - -*************** -Class Reference -*************** - -.. php:class:: CI_FTP - - .. php:method:: connect([$config = array()]) - - :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 - file. - - Here is an example showing how you set preferences manually:: - - $this->load->library('ftp'); - - $config['hostname'] = 'ftp.example.com'; - $config['username'] = 'your-username'; - $config['password'] = 'your-password'; - $config['port'] = 21; - $config['passive'] = FALSE; - $config['debug'] = TRUE; - - $this->ftp->connect($config); - - **Setting FTP Preferences in a Config File** - - 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 *application/config/ftp.php* and it - will be used automatically. - - **Available connection options** - - ============== =============== ============================================================================= - 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 - ============== =============== ============================================================================= - - .. php: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: 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. - Example:: - - $this->ftp->upload('/local/path/to/myfile.html', '/public_html/myfile.html', 'ascii', 0775); - - If 'auto' mode is used it will base the mode on the file extension of the source file. - - If set, permissions have to be passed as an octal value. - - .. php: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: 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:: - - $this->ftp->download('/public_html/myfile.html', '/local/path/to/myfile.html', 'ascii'); - - 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). - - .. php: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: 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. - :: - - // Renames green.html to blue.html - $this->ftp->rename('/public_html/foo/green.html', '/public_html/foo/blue.html'); - - .. php:method:: move($old_file, $new_file) - - :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:: - - // 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. - - .. php:method:: delete_file($filepath) - - :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. - :: - - $this->ftp->delete_file('/public_html/joe/blog.html'); - - .. php:method:: delete_dir($filepath) - - :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. - - .. 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. - - :: - - $this->ftp->delete_dir('/public_html/path/to/folder/'); - - .. php:method:: list_files([$path = '.']) - - :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. - :: - - $list = $this->ftp->list_files('/public_html/'); - print_r($list); - - .. php:method:: mirror($locpath, $rempath) - - :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 - 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/'); - - .. php:method:: mkdir($path[, $permissions = NULL]) - - :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. - - Permissions can be set by passing an octal value in the second parameter. - :: - - // Creates a folder named "bar" - $this->ftp->mkdir('/public_html/foo/bar/', 0755); - - .. php:method:: chmod($path, $perm) - - :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:: - - // Chmod "bar" to 755 - $this->ftp->chmod('/public_html/foo/bar/', 0755); - - .. php: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: TRUE on success, FALSE on failure - :rtype: 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. - - .. php:method:: close() - - :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 deleted file mode 100644 index 22407962f..000000000 --- a/user_guide_src/source/libraries/image_lib.rst +++ /dev/null @@ -1,475 +0,0 @@ -######################## -Image Manipulation Class -######################## - -CodeIgniter's Image Manipulation class lets you perform the following -actions: - -- Image Resizing -- Thumbnail Creation -- Image Cropping -- Image Rotating -- Image Watermarking - -All three major image libraries are supported: GD/GD2, NetPBM, and -ImageMagick - -.. note:: Watermarking is only available using the GD/GD2 library. In - addition, even though other libraries are supported, GD is required in - 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 - - <div class="custom-index container"></div> - -********************** -Initializing the Class -********************** - -Like most other classes in CodeIgniter, the image class is initialized -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`` - -Processing an Image -=================== - -Regardless of the type of processing you would like to perform -(resizing, cropping, rotation, or watermarking), the general process is -identical. You will set some preferences corresponding to the action you -intend to perform, then call one of four available processing functions. -For example, to create an image thumbnail you'll do this:: - - $config['image_library'] = 'gd2'; - $config['source_image'] = '/path/to/image/mypic.jpg'; - $config['create_thumb'] = TRUE; - $config['maintain_ratio'] = TRUE; - $config['width'] = 75; - $config['height'] = 50; - - $this->load->library('image_lib', $config); - - $this->image_lib->resize(); - -The above code tells the image_resize function to look for an image -called *mypic.jpg* located in the source_image folder, then create a -thumbnail that is 75 X 50 pixels using the GD2 image_library. Since the -maintain_ratio option is enabled, the thumb will be as close to the -target width and height as possible while preserving the original aspect -ratio. The thumbnail will be called *mypic_thumb.jpg* and located at -the same level as *source_image*. - -.. note:: In order for the image class to be allowed to do any - processing, the folder containing the image files must have write - permissions. - -.. note:: Image processing can require a considerable amount of server - memory for some operations. If you are experiencing out of memory errors - while processing images you may need to limit their maximum size, and/or - adjust PHP memory limits. - -Processing Methods -================== - -There are four available processing methods: - -- $this->image_lib->resize() -- $this->image_lib->crop() -- $this->image_lib->rotate() -- $this->image_lib->watermark() - -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(); - -A good practice is to use the processing function conditionally, showing an -error upon failure, like this:: - - if ( ! $this->image_lib->resize()) - { - echo $this->image_lib->display_errors(); - } - -.. note:: You can optionally specify the HTML formatting to be applied to - the errors, by submitting the opening/closing tags in the function, - like this:: - - $this->image_lib->display_errors('<p>', '</p>'); - -.. _processing-preferences: - -Preferences -=========== - -The preferences described below allow you to tailor the image processing -to suit your needs. - -Note that not all preferences are available for every function. For -example, the x/y axis preferences are only available for image cropping. -Likewise, the width and height preferences have no effect on cropping. -The "availability" column indicates which functions support a given -preference. - -Availability Legend: - -- R - Image Resizing -- C - Image Cropping -- X - Image Rotation -- W - Image Watermarking - -======================= ======================= =============================== =========================================================================== ============= -Preference Default Value Options Description Availability -======================= ======================= =============================== =========================================================================== ============= -**image_library** GD2 GD, GD2, ImageMagick, NetPBM Sets the image library to be used. R, C, X, W -**library_path** None None Sets the server path to your ImageMagick or NetPBM library. If you use R, C, X - either of those libraries you must supply the path. R, C, S, W -**source_image** None None Sets the source image name/path. The path must be a relative or absolute - server path, not a URL. -**dynamic_output** FALSE TRUE/FALSE (boolean) Determines whether the new image file should be written to disk or R, C, X, W - generated dynamically. Note: If you choose the dynamic setting, only one - image can be shown at a time, and it can't be positioned on the page. It - simply outputs the raw image dynamically to your browser, along with - image headers. -**file_permissions** 0644 (integer) File system permissions to apply on the resulting image file, R, C, X, W - writing it to the disk. WARNING: Use octal integer notation! -**quality** 90% 1 - 100% Sets the quality of the image. The higher the quality the larger the R, C, X, W - file size. -**new_image** None None Sets the destination image name/path. You'll use this preference when R, C, X, W - creating an image copy. The path must be a relative or absolute server - path, not a URL. -**width** None None Sets the width you would like the image set to. R, C -**height** None None Sets the height you would like the image set to. R, C -**create_thumb** FALSE TRUE/FALSE (boolean) Tells the image processing function to create a thumb. R -**thumb_marker** _thumb None Specifies the thumbnail indicator. It will be inserted just before the R - file extension, so mypic.jpg would become mypic_thumb.jpg -**maintain_ratio** TRUE TRUE/FALSE (boolean) Specifies whether to maintain the original aspect ratio when resizing or R, C - use hard values. -**master_dim** auto auto, width, height Specifies what to use as the master axis when resizing or creating R - thumbs. For example, let's say you want to resize an image to 100 X 75 - 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 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. -**x_axis** None None Sets the X coordinate in pixels for image cropping. For example, a C - setting of 30 will crop an image 30 pixels from the left. -**y_axis** None None Sets the Y coordinate in pixels for image cropping. For example, a C - setting of 30 will crop an image 30 pixels from the top. -======================= ======================= =============================== =========================================================================== ============= - -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()`` method if you save -your preferences in a config file. - -****************** -Image Watermarking -****************** - -The Watermarking feature requires the GD/GD2 library. - -Two Types of Watermarking -========================= - -There are two types of watermarking that you can use: - -- **Text**: The watermark message will be generated using text, either - with a True Type font that you specify, or using the native text - output that the GD library supports. If you use the True Type version - your GD installation must be compiled with True Type support (most - are, but not all). -- **Overlay**: The watermark message will be generated by overlaying an - image (usually a transparent PNG or GIF) containing your watermark - over the source image. - -.. _watermarking: - -Watermarking an Image -===================== - -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:: - - $config['source_image'] = '/path/to/image/mypic.jpg'; - $config['wm_text'] = 'Copyright 2006 - John Doe'; - $config['wm_type'] = 'text'; - $config['wm_font_path'] = './system/fonts/texb.ttf'; - $config['wm_font_size'] = '16'; - $config['wm_font_color'] = 'ffffff'; - $config['wm_vrt_alignment'] = 'bottom'; - $config['wm_hor_alignment'] = 'center'; - $config['wm_padding'] = '20'; - - $this->image_lib->initialize($config); - - $this->image_lib->watermark(); - -The above example will use a 16 pixel True Type font to create the text -"Copyright 2006 - John Doe". The watermark will be positioned at the -bottom/center of the image, 20 pixels from the bottom of the image. - -.. note:: In order for the image class to be allowed to do any - processing, the image file must have "write" file permissions - For example, 777. - -Watermarking Preferences -======================== - -This table shows the preferences that are available for both types of -watermarking (text or overlay) - -======================= =================== ======================= ========================================================================== -Preference Default Value Options Description -======================= =================== ======================= ========================================================================== -**wm_type** text text, overlay Sets the type of watermarking that should be used. -**source_image** None None Sets the source image name/path. The path must be a relative or absolute - server path, not a URL. -**dynamic_output** FALSE TRUE/FALSE (boolean) Determines whether the new image file should be written to disk or - generated dynamically. Note: If you choose the dynamic setting, only one - image can be shown at a time, and it can't be positioned on the page. It - simply outputs the raw image dynamically to your browser, along with - image headers. -**quality** 90% 1 - 100% Sets the quality of the image. The higher the quality the larger the - file size. -**wm_padding** None A number The amount of padding, set in pixels, that will be applied to the - watermark to set it away from the edge of your images. -**wm_vrt_alignment** bottom top, middle, bottom Sets the vertical alignment for the watermark image. -**wm_hor_alignment** center left, center, right Sets the horizontal alignment for the watermark image. -**wm_hor_offset** None None You may specify a horizontal offset (in pixels) to apply to the - watermark position. The offset normally moves the watermark to the - right, except if you have your alignment set to "right" then your offset - value will move the watermark toward the left of the image. -**wm_vrt_offset** None None You may specify a vertical offset (in pixels) to apply to the watermark - position. The offset normally moves the watermark down, except if you - have your alignment set to "bottom" then your offset value will move the - watermark toward the top of the image. -======================= =================== ======================= ========================================================================== - -Text Preferences ----------------- - -This table shows the preferences that are available for the text type of -watermarking. - -======================= =================== =================== ========================================================================== -Preference Default Value Options Description -======================= =================== =================== ========================================================================== -**wm_text** None None The text you would like shown as the watermark. Typically this will be a - copyright notice. -**wm_font_path** None None The server path to the True Type Font you would like to use. If you do - not use this option, the native GD font will be used. -**wm_font_size** 16 None The size of the text. Note: If you are not using the True Type option - above, the number is set using a range of 1 - 5. Otherwise, you can use - any valid pixel size for the font you're using. -**wm_font_color** ffffff None The font color, specified in hex. Both the full 6-length (ie, 993300) and - the short three character abbreviated version (ie, fff) are supported. -**wm_shadow_color** None None The color of the drop shadow, specified in hex. If you leave this blank - a drop shadow will not be used. Both the full 6-length (ie, 993300) and - the short three character abbreviated version (ie, fff) are supported. -**wm_shadow_distance** 3 None The distance (in pixels) from the font that the drop shadow should - appear. -======================= =================== =================== ========================================================================== - -Overlay Preferences -------------------- - -This table shows the preferences that are available for the overlay type -of watermarking. - -======================= =================== =================== ========================================================================== -Preference Default Value Options Description -======================= =================== =================== ========================================================================== -**wm_overlay_path** None None The server path to the image you wish to use as your watermark. Required - only if you are using the overlay method. -**wm_opacity** 50 1 - 100 Image opacity. You may specify the opacity (i.e. transparency) of your - watermark image. This allows the watermark to be faint and not - completely obscure the details from the original image behind it. A 50% - opacity is typical. -**wm_x_transp** 4 A number If your watermark image is a PNG or GIF image, you may specify a color - on the image to be "transparent". This setting (along with the next) - will allow you to specify that color. This works by specifying the "X" - and "Y" coordinate pixel (measured from the upper left) within the image - that corresponds to a pixel representative of the color you want to be - transparent. -**wm_y_transp** 4 A number Along with the previous setting, this allows you to specify the - coordinate to a pixel representative of the color you want to be - transparent. -======================= =================== =================== ========================================================================== - -*************** -Class Reference -*************** - -.. php:class:: CI_Image_lib - - .. php:method:: initialize([$props = array()]) - - :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. - - .. php:method:: resize() - - :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. - - 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. - - .. php:method:: crop() - - :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; - - 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. - - .. php:method:: rotate() - - :returns: TRUE on success, FALSE on failure - :rtype: 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(); - } - - .. php:method:: watermark() - - :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. - - .. php:method:: clear() - - :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 - loop. - - :: - - $this->image_lib->clear(); - - .. php:method:: display_errors([$open = '<p>[, $close = '</p>']]) - - :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. - :: - - echo $this->image_lib->display_errors(); diff --git a/user_guide_src/source/libraries/index.rst b/user_guide_src/source/libraries/index.rst deleted file mode 100644 index 678b633dd..000000000 --- a/user_guide_src/source/libraries/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -######### -Libraries -######### - -.. toctree:: - :glob: - :titlesonly: - - *
\ No newline at end of file diff --git a/user_guide_src/source/libraries/input.rst b/user_guide_src/source/libraries/input.rst deleted file mode 100644 index 300f47112..000000000 --- a/user_guide_src/source/libraries/input.rst +++ /dev/null @@ -1,474 +0,0 @@ -########### -Input Class -########### - -The Input Class serves two purposes: - -#. It pre-processes global input data for security. -#. It provides some helper methods for fetching input data and pre-processing it. - -.. note:: This class is initialized automatically by the system so there - is no need to do it manually. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -*************** -Input Filtering -*************** - -Security Filtering -================== - -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 - the global GET array. -- Destroys all global variables in the event register_globals is - turned on. -- Filters the GET/POST/COOKIE array keys, permitting only alpha-numeric - (and a few other) characters. -- Provides XSS (Cross-site Scripting Hacks) filtering. This can be - enabled globally, or upon request. -- Standardizes newline characters to ``PHP_EOL`` (\\n in UNIX-based OSes, - \\r\\n under Windows). This is configurable. - -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 -this:: - - $config['global_xss_filtering'] = TRUE; - -Please refer to the :doc:`Security class <security>` documentation for -information on using XSS Filtering in your application. - -.. important:: The 'global_xss_filtering' setting is DEPRECATED and kept - solely for backwards-compatibility purposes. XSS escaping should - be performed on *output*, not *input*! - -******************* -Accessing form data -******************* - -Using POST, GET, COOKIE, or SERVER Data -======================================= - -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 -NULL if not. This lets you conveniently use data without -having to test whether an item exists first. In other words, normally -you might do something like this:: - - $something = isset($_POST['something']) ? $_POST['something'] : NULL; - -With CodeIgniter's built in methods you can simply do this:: - - $something = $this->input->post('something'); - -The main methods are: - -- ``$this->input->post()`` -- ``$this->input->get()`` -- ``$this->input->cookie()`` -- ``$this->input->server()`` - -Using the php://input stream -============================ - -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. - -CodeIgniter will take care of that for you, and you can read the data -from the **php://input** stream at any time, just by using the -``$raw_input_stream`` property:: - - $this->input->raw_input_stream; - -Additionally if the input stream is form-encoded like $_POST you can -access its values by calling the -``input_stream()`` method:: - - $this->input->input_stream('key'); - -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 - -.. note:: You can utilize ``method()`` in order to know if you're reading - PUT, DELETE or PATCH data. - -*************** -Class Reference -*************** - -.. php:class:: CI_Input - - .. attribute:: $raw_input_stream - - Read only property that will return php://input data as is. - - The property can be read multiple times. - - .. php:method:: post([$index = NULL[, $xss_clean = NULL]]) - - :param mixed $index: POST parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: $_POST if no parameters supplied, otherwise the POST value if found or NULL if not - :rtype: mixed - - The first parameter will contain the name of the POST item you are - looking for:: - - $this->input->post('some_data'); - - The method returns NULL if the item you are attempting to retrieve - 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 - or by setting your ``$config['global_xss_filtering']`` to TRUE. - :: - - $this->input->post('some_data', TRUE); - - To return an array of all POST items call without any parameters. - - 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(NULL, FALSE); // returns all POST items without XSS filter - - To return an array of multiple POST parameters, pass all the required keys - as an array. - :: - - $this->input->post(array('field1', 'field2')); - - Same rule applied here, to retrieve the parameters with XSS filtering enabled, set the - second parameter to boolean TRUE. - :: - - $this->input->post(array('field1', 'field2'), TRUE); - - .. php:method:: get([$index = NULL[, $xss_clean = NULL]]) - - :param mixed $index: GET parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: $_GET if no parameters supplied, otherwise the GET value if found or NULL if not - :rtype: mixed - - This method is identical to ``post()``, only it fetches GET data. - :: - - $this->input->get('some_data', TRUE); - - To return an array of all GET items call without any parameters. - - 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->input->get(NULL, TRUE); // returns all GET items with XSS filter - $this->input->get(NULL, FALSE); // returns all GET items without XSS filtering - - To return an array of multiple GET parameters, pass all the required keys - as an array. - :: - - $this->input->get(array('field1', 'field2')); - - Same rule applied here, to retrieve the parameters with XSS filtering enabled, set the - second parameter to boolean TRUE. - :: - - $this->input->get(array('field1', 'field2'), TRUE); - - .. php:method:: post_get($index[, $xss_clean = NULL]) - - :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 pretty much the same way as ``post()`` and ``get()``, - only combined. It will search through both POST and GET streams for data, - looking in POST first, and then in GET:: - - $this->input->post_get('some_data', TRUE); - - .. php:method:: get_post($index[, $xss_clean = NULL]) - - :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. - - $this->input->get_post('some_data', TRUE); - - .. note:: This method used to act EXACTLY like ``post_get()``, but it's - behavior has changed in CodeIgniter 3.0. - - .. php:method:: cookie([$index = NULL[, $xss_clean = NULL]]) - - :param mixed $index: COOKIE name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: $_COOKIE if no parameters supplied, otherwise the COOKIE value if found or NULL if not - :rtype: mixed - - This method is identical to ``post()`` and ``get()``, only it fetches cookie - data:: - - $this->input->cookie('some_cookie'); - $this->input->cookie('some_cookie', TRUE); // with XSS filter - - To return an array of multiple cookie values, pass all the required keys - as an array. - :: - - $this->input->cookie(array('some_cookie', 'some_cookie2')); - - .. note:: Unlike the :doc:`Cookie Helper <../helpers/cookie_helper>` - function :php:func:`get_cookie()`, this method does NOT prepend - your configured ``$config['cookie_prefix']`` value. - - .. php:method:: server($index[, $xss_clean = NULL]) - - :param mixed $index: Value name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: $_SERVER item value if found, NULL if not - :rtype: mixed - - This method is identical to the ``post()``, ``get()`` and ``cookie()`` - methods, only it fetches server data (``$_SERVER``):: - - $this->input->server('some_data'); - - To return an array of multiple ``$_SERVER`` values, pass all the required keys - as an array. - :: - - $this->input->server(array('SERVER_PROTOCOL', 'REQUEST_URI')); - - .. php:method:: input_stream([$index = NULL[, $xss_clean = NULL]]) - - :param mixed $index: Key name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: Input stream array if no parameters supplied, otherwise the specified value if found or NULL if not - :rtype: mixed - - This method is identical to ``get()``, ``post()`` and ``cookie()``, - only it fetches the *php://input* stream data. - - .. php:method:: set_cookie($name = ''[, $value = ''[, $expire = ''[, $domain = ''[, $path = '/'[, $prefix = ''[, $secure = NULL[, $httponly = NULL]]]]]]]) - - :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 - 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($cookie); - - **Notes** - - Only the name and value are required. To delete a cookie set it with the - expiration blank. - - 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. - - 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 - - The path is usually not needed since the method sets a root path. - - The prefix is only needed if you need to avoid name collisions with - other identically named cookies for your server. - - The *httponly* and *secure* flags, when omitted, will default to your - ``$config['cookie_httponly']`` and ``$config['cookie_secure']`` settings. - - **Discrete Parameters** - - If you prefer, you can set the cookie by passing data using individual - parameters:: - - $this->input->set_cookie($name, $value, $expire, $domain, $path, $prefix, $secure); - - .. php:method:: ip_address() - - :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':: - - 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. - - .. php:method:: valid_ip($ip[, $which = '']) - - :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. - - .. note:: The $this->input->ip_address() method above automatically - validates the IP address. - - :: - - if ( ! $this->input->valid_ip($ip)) - { - echo 'Not Valid'; - } - else - { - echo 'Valid'; - } - - Accepts an optional second string parameter of 'ipv4' or 'ipv6' to specify - an IP format. The default checks for both formats. - - .. php:method:: user_agent([$xss_clean = NULL]) - - :returns: User agent string or NULL if not set - :param bool $xss_clean: Whether to apply XSS filtering - :rtype: mixed - - Returns the user agent string (web browser) being used by the current user, - or NULL if it's not available. - :: - - echo $this->input->user_agent(); - - See the :doc:`User Agent Class <user_agent>` for methods which extract - information from the user agent string. - - .. php:method:: request_headers([$xss_clean = FALSE]) - - :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 - `apache_request_headers() <http://php.net/apache_request_headers>`_ - will not be supported. - :: - - $headers = $this->input->request_headers(); - - .. php: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: 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. - :: - - $this->input->get_request_header('some-header', TRUE); - - .. php:method:: is_ajax_request() - - :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. - - .. php:method:: is_cli_request() - - :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. - - .. 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() - - .. note:: This method is DEPRECATED and is now just an alias for the - :func:`is_cli()` function. - - .. php:method:: method([$upper = FALSE]) - - :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. - :: - - echo $this->input->method(TRUE); // Outputs: POST - echo $this->input->method(FALSE); // Outputs: post - echo $this->input->method(); // Outputs: post diff --git a/user_guide_src/source/libraries/javascript.rst b/user_guide_src/source/libraries/javascript.rst deleted file mode 100644 index e91b9ad78..000000000 --- a/user_guide_src/source/libraries/javascript.rst +++ /dev/null @@ -1,322 +0,0 @@ -################ -Javascript Class -################ - -CodeIgniter provides a library to help you with certain common functions -that you may want to use with Javascript. Please note that CodeIgniter -does not require the jQuery library to run, and that any scripting -library will work equally well. The jQuery library is simply presented -as a convenience if you choose to use it. - -.. important:: This library is DEPRECATED and should not be used. It has always - been with an 'experimental' status and is now no longer supported. - Currently only kept for backwards compatibility. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -************************** -Using the Javascript Class -************************** - -Initializing the Class -====================== - -To initialize the Javascript class manually in your controller -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'* -- autoload (bool) *default: TRUE* - -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 -automatically include a script tag for the main jQuery script file. This -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 - -Setup and Configuration -======================= - -Set these variables in your view --------------------------------- - -As a Javascript library, your files must be available to your -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 ``<head>`` -sections of your output. - -:: - - <?php echo $library_src;?> - <?php echo $script_head;?> - - -``$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. - -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 -need to be made. - -:: - - $config['javascript_location'] = 'http://localhost/codeigniter/themes/js/jquery/'; - $config['javascript_ajax_img'] = 'images/ajax-loader.gif'; - -If you keep your files in the same directories they were downloaded -from, then you need not set this configuration items. - -The jQuery Class -================ - -To initialize the jQuery class manually in your controller constructor, -use the ``$this->load->library()`` method:: - - $this->load->library('javascript/jquery'); - -You may send an optional parameter to determine whether or not a script -tag for the main jQuery file will be automatically included when loading -the library. It will be created by default. To prevent this, load the -library as follows:: - - $this->load->library('javascript/jquery', FALSE); - -Once loaded, the jQuery library object will be available using: - - $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 - <http://api.jquery.com/category/selectors/>`_. Due to jQuery's unique - selector syntax, this is usually an element id, or CSS selector. For - example "#notice_area" would effect ``<div id="notice_area">``, 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 - an effect from the jQuery library below. - -Effects -======= - -The query library supports a powerful -`Effects <http://api.jquery.com/category/effects/>`_ repertoire. Before an effect -can be used, it must be loaded:: - - $this->jquery->effect([optional path] plugin name); // for example $this->jquery->effect('bounce'); - - -hide() / show() ---------------- - -Each of this functions will affect the visibility of an item on your -page. hide() will set an item invisible, show() will reveal it. - -:: - - $this->jquery->hide(target, optional speed, optional extra information); - $this->jquery->show(target, optional speed, optional extra information); - - -- "target" will be any valid jQuery selector or selectors. -- "speed" is optional, and is set to either slow, normal, fast, or - alternatively a number of milliseconds. -- "extra information" is optional, and could include a callback, or - other additional information. - -toggle() --------- - -toggle() will change the visibility of an item to the opposite of its -current state, hiding visible elements, and revealing hidden ones. - -:: - - $this->jquery->toggle(target); - - -- "target" will be any valid jQuery selector or selectors. - -animate() ---------- - -:: - - $this->jquery->animate(target, parameters, optional speed, optional extra information); - - -- "target" will be any valid jQuery selector or selectors. -- "parameters" in jQuery would generally include a series of CSS - properties that you wish to change. -- "speed" is optional, and is set to either slow, normal, fast, or - alternatively a number of milliseconds. -- "extra information" is optional, and could include a callback, or - other additional information. - -For a full summary, see -`http://api.jquery.com/animate/ <http://api.jquery.com/animate/>`_ - -Here is an example of an animate() called on a div with an id of "note", -and triggered by a click using the jQuery library's click() event. - -:: - - $params = array( - 'height' => 80, - 'width' => '50%', - 'marginLeft' => 125 - ); - $this->jquery->click('#trigger', $this->jquery->animate('#note', $params, 'normal')); - -fadeIn() / fadeOut() --------------------- - -:: - - $this->jquery->fadeIn(target, optional speed, optional extra information); - $this->jquery->fadeOut(target, optional speed, optional extra information); - - -- "target" will be any valid jQuery selector or selectors. -- "speed" is optional, and is set to either slow, normal, fast, or - alternatively a number of milliseconds. -- "extra information" is optional, and could include a callback, or - other additional information. - -toggleClass() -------------- - -This function will add or remove a CSS class to its target. - -:: - - $this->jquery->toggleClass(target, class) - - -- "target" will be any valid jQuery selector or selectors. -- "class" is any CSS classname. Note that this class must be defined - and available in a CSS that is already loaded. - -fadeIn() / fadeOut() --------------------- - -These effects cause an element(s) to disappear or reappear over time. - -:: - - $this->jquery->fadeIn(target, optional speed, optional extra information); - $this->jquery->fadeOut(target, optional speed, optional extra information); - - -- "target" will be any valid jQuery selector or selectors. -- "speed" is optional, and is set to either slow, normal, fast, or - alternatively a number of milliseconds. -- "extra information" is optional, and could include a callback, or - other additional information. - -slideUp() / slideDown() / slideToggle() ---------------------------------------- - -These effects cause an element(s) to slide. - -:: - - $this->jquery->slideUp(target, optional speed, optional extra information); - $this->jquery->slideDown(target, optional speed, optional extra information); - $this->jquery->slideToggle(target, optional speed, optional extra information); - - -- "target" will be any valid jQuery selector or selectors. -- "speed" is optional, and is set to either slow, normal, fast, or - alternatively a number of milliseconds. -- "extra information" is optional, and could include a callback, or - other additional information. - -Plugins -======= - -Some select jQuery plugins are made available using this library. - -corner() --------- - -Used to add distinct corners to page elements. For full details see -`http://malsup.com/jquery/corner/ <http://malsup.com/jquery/corner/>`_ - -:: - - $this->jquery->corner(target, corner_style); - - -- "target" will be any valid jQuery selector or selectors. -- "corner_style" is optional, and can be set to any valid style such - as round, sharp, bevel, bite, dog, etc. Individual corners can be set - by following the style with a space and using "tl" (top left), "tr" - (top right), "bl" (bottom left), or "br" (bottom right). - -:: - - $this->jquery->corner("#note", "cool tl br"); - - -tablesorter() -------------- - -description to come - -modal() -------- - -description to come - -calendar() ----------- - -description to come
\ No newline at end of file diff --git a/user_guide_src/source/libraries/language.rst b/user_guide_src/source/libraries/language.rst deleted file mode 100644 index de17c8288..000000000 --- a/user_guide_src/source/libraries/language.rst +++ /dev/null @@ -1,210 +0,0 @@ -############## -Language Class -############## - -The Language Class provides functions to retrieve language files and -lines of text for purposes of internationalization. - -In your CodeIgniter **system** folder, you will find a **language** sub-directory -containing a set of language files for the **english** idiom. -The files in this directory (**system/language/english/**) define the regular messages, -error messages, and other generally output terms or expressions, for the different parts -of the CodeIgniter framework. - -You can create or incorporate your own language files, as needed, in order to provide -application-specific error and other messages, or to provide translations of the core -messages into other languages. These translations or additional messages would go inside -your **application/language/** directory, with separate sub-directories for each idiom -(for instance, 'french' or 'german'). - -The CodeIgniter framework comes with a set of language files for the "english" idiom. -Additional approved translations for different idioms may be found in the -`CodeIgniter 3 Translations repositories <https://github.com/bcit-ci/codeigniter3-translations>`_. -Each repository deals with a single idiom. - -When CodeIgniter loads language files, it will load the one in **system/language/** -first and will then look for an override in your **application/language/** directory. - -.. note:: Each language should be stored in its own folder. For example, - the English files are located at: system/language/english - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -*************************** -Handling Multiple Languages -*************************** - -If you want to support multiple languages in your application, you would provide folders inside -your **application/language/** directory for each of them, and you would specify the default -language in your **application/config/config.php**. - -The **application/language/english/** directory would contain any additional language files -needed by your application, for instance for error messages. - -Each of the other idiom-specific directories would contain the core language files that you -obtained from the translations repositories, or that you translated yourself, as well as -any additional ones needed by your application. - -You would store the language you are currently using, for instance in a session variable. - -Sample Language Files -===================== - -:: - - system/ - language/ - english/ - ... - email_lang.php - form_validation_lang.php - ... - - application/ - language/ - english/ - error_messages_lang.php - french/ - ... - email_lang.php - error_messages_lang.php - form_validation_lang.php - ... - -Example of switching languages -============================== - -:: - - $idiom = $this->session->get_userdata('language'); - $this->lang->load('error_messages', $idiom); - $oops = $this->lang->line('message_key'); - -******************** -Internationalization -******************** - -The Language class in CodeIgniter is meant to provide an easy and lightweight -way to support multiplelanguages in your application. It is not meant to be a -full implementation of what is commonly called `internationalization and localization -<http://en.wikipedia.org/wiki/Internationalization_and_localization>`_. - -We use the term "idiom" to refer to a language using its common name, -rather than using any of the international standards, such as "en", "en-US", -or "en-CA-x-ca" for English and some of its variants. - -.. note:: There is nothing to prevent you from using those abbreviations in your application! - -************************ -Using the Language Class -************************ - -Creating Language Files -======================= - -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 -``$lang`` with this prototype:: - - $lang['language_key'] = 'The actual message to be shown'; - -.. note:: It's a good practice to use a common prefix for all messages - in a given file to avoid collisions with similarly named items in other - files. For example, if you are creating error messages you might prefix - them with error\_ - -:: - - $lang['error_email_missing'] = 'You must submit an email address'; - $lang['error_url_missing'] = 'You must submit a URL'; - $lang['error_username_missing'] = 'You must submit a username'; - -Loading A Language File -======================= - -In order to fetch a line from a particular file you must load the file -first. Loading a language file is done with the following code:: - - $this->lang->load('filename', 'language'); - -Where filename is the name of the file you wish to load (without the -file extension), and language is the language set containing it (ie, -english). If the second parameter is missing, the default language set -in your **application/config/config.php** file will be used. - -You can also load multiple language files at the same time by passing an array of language files as first parameter. -:: - - $this->lang->load(array('filename1', 'filename2')); - -.. note:: The *language* parameter can only consist of letters. - -Fetching a Line of Text -======================= - -Once your desired language file is loaded you can access any line of -text using this function:: - - $this->lang->line('language_key'); - -Where *language_key* is the array key corresponding to the line you wish -to show. - -You can optionally pass FALSE as the second argument of that method to -disable error logging, in case you're not sure if the line exists:: - - $this->lang->line('misc_key', FALSE); - -.. note:: This method simply returns the line. It does not echo it. - -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 -<../helpers/language_helper>`. - -Auto-loading Languages -====================== - -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. - -*************** -Class Reference -*************** - -.. php:class:: CI_Lang - - .. php:method:: load($langfile[, $idiom = ''[, $return = FALSE[, $add_suffix = TRUE[, $alt_path = '']]]]) - - :param mixed $langfile: Language file to load or array with multiple files - :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. - - .. php: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: 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 deleted file mode 100644 index 22abb4586..000000000 --- a/user_guide_src/source/libraries/loader.rst +++ /dev/null @@ -1,461 +0,0 @@ -############ -Loader Class -############ - -Loader, as the name suggests, is used to load elements. These elements -can be libraries (classes) :doc:`View files <../general/views>`, -:doc:`Drivers <../general/drivers>`, -:doc:`Helpers <../general/helpers>`, -:doc:`Models <../general/models>`, or your own files. - -.. note:: This class is initialized automatically by the system so there - is no need to do it manually. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -********************** -Application "Packages" -********************** - -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. - -The following is an example of a directory for an application package -named "Foo Bar". - -:: - - /application/third_party/foo_bar - - config/ - helpers/ - language/ - libraries/ - models/ - -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. - -Package view files ------------------- - -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. - -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->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 - - // Reset things - $this->load->remove_package_path(APPPATH.'my_app'); - - // 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 - -*************** -Class Reference -*************** - -.. php:class:: CI_Loader - - .. php: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: CI_Loader instance (method chaining) - :rtype: CI_Loader - - This method is used to load core classes. - - .. note:: We use the terms "class" and "library" interchangeably. - - 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('email'); - - Once loaded, the library will be ready for use, using ``$this->email``. - - 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:: - - libraries/flavors/Chocolate.php - - You will load it using:: - - $this->load->library('flavors/chocolate'); - - You may nest the file in as many subdirectories as you want. - - Additionally, multiple libraries can be loaded at the same time by - passing an array of libraries to the load method. - :: - - $this->load->library(array('email', 'table')); - - **Setting options** - - The second (optional) parameter allows you to optionally pass - configuration setting. You will typically pass these as an array:: - - $config = array ( - 'mailtype' => 'html', - 'charset' => 'utf-8', - 'priority' => '1' - ); - - $this->load->library('email', $config); - - 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. - - 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** - - 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``. - - If you prefer to set your own class names you can pass its value to the - third parameter:: - - $this->load->library('calendar', NULL, 'my_calendar'); - - // Calendar class is now accessed using: - $this->my_calendar - - Please take note, when multiple libraries are supplied in an array for - the first parameter, this parameter is discarded. - - .. php: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: CI_Loader instance (method chaining) - :rtype: CI_Loader - - This method is used to load driver libraries, acts very much like the - ``library()`` method. - - 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->driver('session'); - - Once loaded, the library will be ready for use, using ``$this->session``. - - 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. - - Additionally, multiple driver libraries can be loaded at the same time by - passing an array of drivers to the load method. - :: - - $this->load->driver(array('session', 'cache')); - - **Setting options** - - The second (optional) parameter allows you to optionally pass - configuration settings. You will typically pass these as an array:: - - $config = array( - 'sess_driver' => 'cookie', - 'sess_encrypt_cookie' => true, - 'encryption_key' => 'mysecretkey' - ); - - $this->load->driver('session', $config); - - 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. - - **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 - the library is named Session, it will be assigned to a variable named - ``$this->session``. - - If you prefer to set your own class names you can pass its value to the - third parameter:: - - $this->load->library('session', '', 'my_session'); - - // Session class is now accessed using: - $this->my_session - - .. php: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: 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 - recommended that you do since it shows you how this method is - typically used. - - The first parameter is required. It is the name of the view file you - would like to load. - - .. note:: The .php file extension does not need to be specified unless - you use something other than .php. - - The second **optional** parameter can take an associative array or an - object as input, which it runs through the PHP - `extract() <http://php.net/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. - - 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:: - - $string = $this->load->view('myfile', '', TRUE); - - .. php:method:: vars($vars[, $val = '']) - - :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() <http://php.net/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. - - .. php:method:: get_var($key) - - :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 - or another controller method using ``$this->load->vars()``. - - .. php:method:: get_vars() - - :returns: An array of all assigned view variables - :rtype: array - - This method retrieves all variables available to your views. - - .. php:method:: clear_vars() - - :returns: CI_Loader instance (method chaining) - :rtype: CI_Loader - - Clears cached view variables. - - .. php: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: CI_Loader instance (method chaining) - :rtype: CI_Loader - - :: - - $this->load->model('model_name'); - - - 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:: - - $this->load->model('blog/queries'); - - 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->model('model_name', 'fubar'); - $this->fubar->method(); - - .. php: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: 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>` - section for more info. - - .. php:method:: dbforge([$db = NULL[, $return = FALSE]]) - - :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. - - .. php:method:: dbutil([$db = NULL[, $return = FALSE]]) - - :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. - - .. php:method:: helper($helpers) - - :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. - - .. php:method:: file($path[, $return = FALSE]) - - :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 - 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. - - .. php:method:: language($files[, $lang = '']) - - :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 <language>`: ``$this->lang->load()``. - - .. php: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: TRUE on success, FALSE on failure - :rtype: bool - - This method is an alias of the :doc:`config file loading - method <config>`: ``$this->config->load()`` - - .. php:method:: is_loaded($class) - - :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. - - .. note:: The word "class" here refers to libraries and drivers. - - If the requested class has been loaded, the method returns its assigned - name in the CI Super-object and FALSE if it's not:: - - $this->load->library('form_validation'); - $this->load->is_loaded('Form_validation'); // returns 'form_validation' - - $this->load->is_loaded('Nonexistent_library'); // returns FALSE - - .. important:: If you have more than one instance of a class (assigned to - different properties), then the first one will be returned. - - :: - - $this->load->library('form_validation', $config, 'fv'); - $this->load->library('form_validation'); - - $this->load->is_loaded('Form_validation'); // returns 'fv' - - .. php:method:: add_package_path($path[, $view_cascade = TRUE]) - - :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" - 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/') - ->library('foo_bar'); - - .. php:method:: remove_package_path([$path = '']) - - :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 - 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/'); - - .. php:method:: get_package_paths([$include_base = TRUE]) - - :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 deleted file mode 100644 index 97c72303c..000000000 --- a/user_guide_src/source/libraries/migration.rst +++ /dev/null @@ -1,184 +0,0 @@ -################ -Migrations Class -################ - -Migrations are a convenient way for you to alter your database in a -structured and organized manner. You could edit fragments of SQL by hand -but you would then be responsible for telling other developers that they -need to go and run them. You would also have to keep track of which changes -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 **application/config/migration.php**. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -******************** -Migration file names -******************** - -Each Migration is run in numeric order forward or backwards depending on the -method taken. Two numbering styles are available: - -* **Sequential:** each migration is numbered in sequence, starting with **001**. - Each number must be three digits, and there must not be any gaps in the - sequence. (This was the numbering scheme prior to CodeIgniter 3.0.) -* **Timestamp:** each migration is numbered using the timestamp when the migration - was created, in **YYYYMMDDHHIISS** format (e.g. **20121031100537**). This - 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 *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) - -****************** -Create a Migration -****************** - -This will be the first migration for a new site which has a blog. All -migrations go in the **application/migrations/** directory and have names such -as *20121031100537_add_blog.php*. -:: - - <?php - - defined('BASEPATH') OR exit('No direct script access allowed'); - - class Migration_Add_blog extends CI_Migration { - - public function up() - { - $this->dbforge->add_field(array( - 'blog_id' => array( - 'type' => 'INT', - 'constraint' => 5, - 'unsigned' => TRUE, - 'auto_increment' => TRUE - ), - 'blog_title' => array( - 'type' => 'VARCHAR', - 'constraint' => '100', - ), - 'blog_description' => array( - 'type' => 'TEXT', - 'null' => TRUE, - ), - )); - $this->dbforge->add_key('blog_id', TRUE); - $this->dbforge->create_table('blog'); - } - - public function down() - { - $this->dbforge->drop_table('blog'); - } - } - -Then in **application/config/migration.php** set ``$config['migration_version'] = 20121031100537;``. - -************* -Usage Example -************* - -In this example some simple code is placed in **application/controllers/Migrate.php** -to update the schema.:: - - <?php - - class Migrate extends CI_Controller - { - - public function index() - { - $this->load->library('migration'); - - if ($this->migration->current() === FALSE) - { - show_error($this->migration->error_string()); - } - } - - } - -********************* -Migration Preferences -********************* - -The following is a table of all the config options for migrations. - -========================== ====================== ========================== ============================================= -Preference Default Options Description -========================== ====================== ========================== ============================================= -**migration_enabled** FALSE TRUE / FALSE Enable or disable migrations. -**migration_path** APPPATH.'migrations/' None The path to your migrations folder. -**migration_version** 0 None The current version your database should use. -**migration_table** migrations None The table name for storing the schema - version number. -**migration_auto_latest** FALSE TRUE / FALSE Enable or disable automatically - running migrations. -**migration_type** 'timestamp' 'timestamp' / 'sequential' The type of numeric identifier used to name - migration files. -========================== ====================== ========================== ============================================= - -*************** -Class Reference -*************** - -.. php:class:: CI_Migration - - .. php:method:: current() - - :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*). - - .. php:method:: error_string() - - :returns: Error messages - :rtype: string - - This returns a string of errors that were detected while performing a migration. - - .. php:method:: find_migrations() - - :returns: An array of migration files - :rtype: array - - An array of migration filenames are returned that are found in the **migration_path** property. - - .. php:method:: latest() - - :returns: 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 - newest migration found in the filesystem. - - .. php:method:: version($target_version) - - :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); diff --git a/user_guide_src/source/libraries/output.rst b/user_guide_src/source/libraries/output.rst deleted file mode 100644 index 92060f66a..000000000 --- a/user_guide_src/source/libraries/output.rst +++ /dev/null @@ -1,233 +0,0 @@ -############ -Output Class -############ - -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. - -.. note:: This class is initialized automatically by the system so there - is no need to do it manually. - -Under normal circumstances you won't even notice the Output class since -it works transparently without your intervention. For example, when you -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. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -*************** -Class Reference -*************** - -.. php:class:: CI_Output - - .. attribute:: $parse_exec_vars = TRUE; - - Enables/disables parsing of the {elapsed_time} and {memory_usage} pseudo-variables. - - CodeIgniter will parse those tokens in your output by default. To disable this, set - this property to FALSE in your controller. - :: - - $this->output->parse_exec_vars = FALSE; - - .. php:method:: set_output($output) - - :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:: - - $this->output->set_output($data); - - .. 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 methods, don't set the output until the end. - - .. php:method:: set_content_type($mime_type[, $charset = NULL]) - - :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. - :: - - $this->output - ->set_content_type('application/json') - ->set_output(json_encode(array('foo' => 'bar'))); - - $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')); - - .. important:: Make sure any non-mime string you pass to this method - exists in *application/config/mimes.php* or it will have no effect. - - You can also set the character set of the document, by passing a second argument:: - - $this->output->set_content_type('css', 'utf-8'); - - .. php:method:: get_content_type() - - :returns: Content-Type string - :rtype: string - - Returns the Content-Type HTTP header that's currently in use, excluding the character set value. - :: - - $mime = $this->output->get_content_type(); - - .. note:: If not set, the default return value is 'text/html'. - - .. php:method:: get_header($header) - - :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:: - - $this->output->set_content_type('text/plain', 'UTF-8'); - echo $this->output->get_header('content-type'); - // Outputs: text/plain; charset=utf-8 - - .. note:: The header name is compared in a case-insensitive manner. - - .. note:: Raw headers sent via PHP's native ``header()`` function are also detected. - - .. php:method:: get_output() - - :returns: Output string - :rtype: string - - Permits you to manually retrieve any output that has been sent for - storage in the output class. Usage example:: - - $string = $this->output->get_output(); - - 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()``. - - .. php:method:: append_output($output) - - :param string $output: Additional output data to append - :returns: CI_Output instance (method chaining) - :rtype: CI_Output - - Appends data onto the output string. - :: - - $this->output->append_output($data); - - .. php:method:: set_header($header[, $replace = TRUE]) - - :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:: - - $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'); - - .. php:method:: set_status_header([$code = 200[, $text = '']]) - - :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:: - - $this->output->set_status_header(401); - // Sets the header as: Unauthorized - - `See here <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>`_ for a full list of headers. - - .. note:: This method is an alias for :doc:`Common function <../general/common_functions>` - :func:`set_status_header()`. - - .. php:method:: enable_profiler([$val = TRUE]) - - :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. - - 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); - - .. php:method:: set_profiler_sections($sections) - - :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. - - .. php:method:: cache($time) - - :param int $time: Cache expiration time in minutes - :returns: CI_Output instance (method chaining) - :rtype: CI_Output - - Caches the current page for the specified amount of minutes. - - For more information, please see the :doc:`caching documentation <../general/caching>`. - - .. php:method:: _display([$output = '']) - - :param string $output: Output data override - :returns: void - :rtype: void - - Sends finalized output data to the browser along with any server headers. It also stops benchmark - timers. - - .. note:: This method is called automatically at the end of script execution, you won't need to - call it manually unless you are aborting script execution using ``exit()`` or ``die()`` in your code. - - Example:: - - $response = array('status' => 'OK'); - - $this->output - ->set_status_header(200) - ->set_content_type('application/json', 'utf-8') - ->set_output(json_encode($response, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)) - ->_display(); - exit; - - .. note:: Calling this method manually without aborting script execution will result in duplicated output. diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst deleted file mode 100644 index fbc75ea56..000000000 --- a/user_guide_src/source/libraries/pagination.rst +++ /dev/null @@ -1,314 +0,0 @@ -################ -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 - - <div class="custom-index container"></div> - -If you are not familiar with the term "pagination", it refers to links -that allows you to navigate from page to page, like this:: - - « First < 1 2 3 4 5 > Last » - -******* -Example -******* - -Here is a simple example showing how to create pagination in one of your -:doc:`controller <../general/controllers>` methods:: - - $this->load->library('pagination'); - - $config['base_url'] = 'http://example.com/index.php/test/page/'; - $config['total_rows'] = 200; - $config['per_page'] = 20; - - $this->pagination->initialize($config); - - echo $this->pagination->create_links(); - -Notes -===== - -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: - -- **base_url** This is the full URL to the controller class/function - containing your pagination. In the example above, it is pointing to a - controller called "Test" and a function called "page". Keep in mind - that you can :doc:`re-route your URI <../general/routing>` if you - need a different structure. -- **total_rows** This number represents the total rows in the result - set you are creating pagination for. Typically this number will be - the total rows that your database query returned. -- **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()`` method returns an empty string when there is no -pagination to show. - -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 *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. - -************************** -Customizing the Pagination -************************** - -The following is a list of all the preferences you can pass to the -initialization function to tailor the display. - -**$config['uri_segment'] = 3;** - -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 -side, as in the example links at the very top of this page. - -**$config['use_page_numbers'] = TRUE;** - -By default, the URI segment will use the starting index for the items -you are paginating. If you prefer to show the the actual page number, -set this to TRUE. - -**$config['page_query_string'] = TRUE;** - -By default, the pagination library assume you are using :doc:`URI -Segments <../general/urls>`, and constructs your links something -like:: - - http://example.com/index.php/test/page/20 - -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 explicitly 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'`` - -**$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.:: - - http://example.com/index.php/test/page/20?query=search%term - -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 suffix value will be right after -the offset segment. - -**$config['use_global_url_suffix'] = FALSE;** - -When set to TRUE, it will **override** the ``$config['suffix']`` value and -instead set it to the one that you have in ``$config['url_suffix']`` in -your **application/config/config.php** file. - -*********************** -Adding Enclosing Markup -*********************** - -If you would like to surround the entire pagination with some markup you -can do it with these two preferences: - -**$config['full_tag_open'] = '<p>';** - -The opening tag placed on the left side of the entire result. - -**$config['full_tag_close'] = '</p>';** - -The closing tag placed on the right side of the entire result. - -************************** -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. - -.. note:: This value can also be translated via a language file. - -**$config['first_tag_open'] = '<div>';** - -The opening tag for the "first" link. - -**$config['first_tag_close'] = '</div>';** - -The closing tag for the "first" link. - -**$config['first_url'] = '';** - -An alternative URL to use for the "first page" link. - -************************* -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. - -.. note:: This value can also be translated via a language file. - -**$config['last_tag_open'] = '<div>';** - -The opening tag for the "last" link. - -**$config['last_tag_close'] = '</div>';** - -The closing tag for the "last" link. - -*************************** -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. - -.. note:: This value can also be translated via a language file. - -**$config['next_tag_open'] = '<div>';** - -The opening tag for the "next" link. - -**$config['next_tag_close'] = '</div>';** - -The closing tag for the "next" link. - -******************************* -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. - -.. note:: This value can also be translated via a language file. - -**$config['prev_tag_open'] = '<div>';** - -The opening tag for the "previous" link. - -**$config['prev_tag_close'] = '</div>';** - -The closing tag for the "previous" link. - -*********************************** -Customizing the "Current Page" Link -*********************************** - -**$config['cur_tag_open'] = '<b>';** - -The opening tag for the "current" link. - -**$config['cur_tag_close'] = '</b>';** - -The closing tag for the "current" link. - -**************************** -Customizing the "Digit" Link -**************************** - -**$config['num_tag_open'] = '<div>';** - -The opening tag for the "digit" link. - -**$config['num_tag_close'] = '</div>';** - -The closing tag for the "digit" link. - -**************** -Hiding the Pages -**************** - -If you wanted to not list the specific pages (for example, you only want -"next" and "previous" links), you can suppress their rendering by -adding:: - - $config['display_pages'] = FALSE; - -**************************** -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:: - - // Produces: class="myclass" - $config['attributes'] = array('class' => 'myclass'); - -.. note:: Usage of the old method of setting classes via "anchor_class" - is deprecated. - -***************************** -Disabling the "rel" attribute -***************************** - -By default the rel attribute is dynamically generated and appended to -the appropriate anchors. If for some reason you want to turn it off, -you can pass boolean FALSE as a regular attribute - -:: - - $config['attributes']['rel'] = FALSE; - -*************** -Class Reference -*************** - -.. php:class:: CI_Pagination - - .. php:method:: initialize([$params = array()]) - - :param array $params: Configuration parameters - :returns: CI_Pagination instance (method chaining) - :rtype: CI_Pagination - - Initializes the Pagination class with your preferred options. - - .. php:method:: create_links() - - :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. diff --git a/user_guide_src/source/libraries/parser.rst b/user_guide_src/source/libraries/parser.rst deleted file mode 100644 index 6c9d28959..000000000 --- a/user_guide_src/source/libraries/parser.rst +++ /dev/null @@ -1,309 +0,0 @@ -##################### -Template Parser Class -##################### - -The Template Parser Class can perform simple text substitution for -pseudo-variables contained within your view files. -It can parse simple variables or variable tag pairs. - -If you've never used a template engine, -pseudo-variable names are enclosed in braces, like this:: - - <html> - <head> - <title>{blog_title}</title> - </head> - <body> - <h3>{blog_heading}</h3> - - {blog_entries} - <h5>{title}</h5> - <p>{body}</p> - {/blog_entries} - - </body> - </html> - -These variables are not actual PHP variables, but rather plain text -representations that allow you to eliminate PHP from your templates -(view files). - -.. note:: CodeIgniter does **not** require you to use this class since - using pure PHP in your view pages lets them run a little faster. - However, some developers prefer to use a template engine if - they work with designers who they feel would find some - confusion working with PHP. - -.. important:: The Template Parser Class is **not** a full-blown - template parsing solution. We've kept it very lean on purpose in order - to maintain maximum performance. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -******************************* -Using the Template Parser Class -******************************* - -Initializing the Class -====================== - -Like most other classes in CodeIgniter, the Parser class is initialized -in your controller using the ``$this->load->library()`` method:: - - $this->load->library('parser'); - -Once loaded, the Parser library object will be available using: -$this->parser - -Parsing templates -================= - -You can use the ``parse()`` method to parse (or render) simple templates, -like this:: - - $data = array( - 'blog_title' => 'My Blog Title', - 'blog_heading' => 'My Blog Heading' - ); - - $this->parser->parse('blog_template', $data); - -The first parameter contains the name of the :doc:`view -file <../general/views>` (in this example the file would be called -blog_template.php), and the second parameter contains an associative -array of data to be replaced in the template. In the above example, the -template would contain two variables: {blog_title} and {blog_heading} - -There is no need to "echo" or do something with the data returned by -$this->parser->parse(). It is automatically passed to the output class -to be sent to the browser. However, if you do want the data returned -instead of sent to the output class you can pass TRUE (boolean) as the -third parameter:: - - $string = $this->parser->parse('blog_template', $data, TRUE); - -Variable Pairs -============== - -The above example code allows simple variables to be replaced. What if -you would like an entire block of variables to be repeated, with each -iteration containing new values? Consider the template example we showed -at the top of the page:: - - <html> - <head> - <title>{blog_title}</title> - </head> - <body> - <h3>{blog_heading}</h3> - - {blog_entries} - <h5>{title}</h5> - <p>{body}</p> - {/blog_entries} - - </body> - </html> - -In the above code you'll notice a pair of variables: {blog_entries} -data... {/blog_entries}. In a case like this, the entire chunk of data -between these pairs would be repeated multiple times, corresponding to -the number of rows in the "blog_entries" element of the parameters array. - -Parsing variable pairs is done using the identical code shown above to -parse single variables, except, you will add a multi-dimensional array -corresponding to your variable pair data. Consider this example:: - - $this->load->library('parser'); - - $data = array( - 'blog_title' => 'My Blog Title', - 'blog_heading' => 'My Blog Heading', - 'blog_entries' => array( - array('title' => 'Title 1', 'body' => 'Body 1'), - array('title' => 'Title 2', 'body' => 'Body 2'), - array('title' => 'Title 3', 'body' => 'Body 3'), - array('title' => 'Title 4', 'body' => 'Body 4'), - array('title' => 'Title 5', 'body' => 'Body 5') - ) - ); - - $this->parser->parse('blog_template', $data); - -If your "pair" data is coming from a database result, which is already a -multi-dimensional array, you can simply use the database ``result_array()`` -method:: - - $query = $this->db->query("SELECT * FROM blog"); - - $this->load->library('parser'); - - $data = array( - 'blog_title' => 'My Blog Title', - 'blog_heading' => 'My Blog Heading', - 'blog_entries' => $query->result_array() - ); - - $this->parser->parse('blog_template', $data); - -Usage Notes -=========== - -If you include substitution parameters that are not referenced in your -template, they are ignored:: - - $template = 'Hello, {firstname} {lastname}'; - $data = array( - 'title' => 'Mr', - 'firstname' => 'John', - 'lastname' => 'Doe' - ); - $this->parser->parse_string($template, $data); - - // Result: Hello, John Doe - -If you do not include a substitution parameter that is referenced in your -template, the original pseudo-variable is shown in the result:: - - $template = 'Hello, {firstname} {initials} {lastname}'; - $data = array( - 'title' => 'Mr', - 'firstname' => 'John', - 'lastname' => 'Doe' - ); - $this->parser->parse_string($template, $data); - - // Result: Hello, John {initials} Doe - -If you provide a string substitution parameter when an array is expected, -i.e. for a variable pair, the substitution is done for the opening variable -pair tag, but the closing variable pair tag is not rendered properly:: - - $template = 'Hello, {firstname} {lastname} ({degrees}{degree} {/degrees})'; - $data = array( - 'degrees' => 'Mr', - 'firstname' => 'John', - 'lastname' => 'Doe', - 'titles' => array( - array('degree' => 'BSc'), - array('degree' => 'PhD') - ) - ); - $this->parser->parse_string($template, $data); - - // Result: Hello, John Doe (Mr{degree} {/degrees}) - -If you name one of your individual substitution parameters the same as one -used inside a variable pair, the results may not be as expected:: - - $template = 'Hello, {firstname} {lastname} ({degrees}{degree} {/degrees})'; - $data = array( - 'degree' => 'Mr', - 'firstname' => 'John', - 'lastname' => 'Doe', - 'degrees' => array( - array('degree' => 'BSc'), - array('degree' => 'PhD') - ) - ); - $this->parser->parse_string($template, $data); - - // Result: Hello, John Doe (Mr Mr ) - -View Fragments -============== - -You do not have to use variable pairs to get the effect of iteration in -your views. It is possible to use a view fragment for what would be inside -a variable pair, and to control the iteration in your controller instead -of in the view. - -An example with the iteration controlled in the view:: - - $template = '<ul>{menuitems} - <li><a href="{link}">{title}</a></li> - {/menuitems}</ul>'; - - $data = array( - 'menuitems' => array( - array('title' => 'First Link', 'link' => '/first'), - array('title' => 'Second Link', 'link' => '/second'), - ) - ); - $this->parser->parse_string($template, $data); - -Result:: - - <ul> - <li><a href="/first">First Link</a></li> - <li><a href="/second">Second Link</a></li> - </ul> - -An example with the iteration controlled in the controller, -using a view fragment:: - - $temp = ''; - $template1 = '<li><a href="{link}">{title}</a></li>'; - $data1 = array( - array('title' => 'First Link', 'link' => '/first'), - array('title' => 'Second Link', 'link' => '/second'), - ); - - foreach ($data1 as $menuitem) - { - $temp .= $this->parser->parse_string($template1, $menuitem, TRUE); - } - - $template = '<ul>{menuitems}</ul>'; - $data = array( - 'menuitems' => $temp - ); - $this->parser->parse_string($template, $data); - -Result:: - - <ul> - <li><a href="/first">First Link</a></li> - <li><a href="/second">Second Link</a></li> - </ul> - -*************** -Class Reference -*************** - -.. php:class:: CI_Parser - - .. php:method:: parse($template, $data[, $return = FALSE]) - - :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. - - .. php:method:: parse_string($template, $data[, $return = FALSE]) - - :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. - - .. php:method:: set_delimiters([$l = '{'[, $r = '}']]) - - :param string $l: Left delimiter - :param string $r: Right delimiter - :rtype: void - - Sets the delimiters (opening and closing) for a - pseudo-variable "tag" in a template.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/security.rst b/user_guide_src/source/libraries/security.rst deleted file mode 100644 index 868112684..000000000 --- a/user_guide_src/source/libraries/security.rst +++ /dev/null @@ -1,172 +0,0 @@ -############## -Security Class -############## - -The Security Class contains methods that help you create a secure -application, processing input data for security. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -************* -XSS Filtering -************* - -CodeIgniter comes with a Cross Site Scripting prevention filter, which -looks for commonly used techniques to trigger JavaScript or other types -of code that attempt to hijack cookies or do other malicious things. -If anything disallowed is encountered it is rendered safe by converting -the data to character entities. - -To filter data through the XSS filter use the ``xss_clean()`` method:: - - $data = $this->security->xss_clean($data); - -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 -safe, and FALSE if it contained potentially malicious information that a -browser may attempt to execute. - -:: - - if ($this->security->xss_clean($file, TRUE) === FALSE) - { - // file failed the XSS test - } - -.. important:: If you want to filter HTML attribute values, use - :php:func:`html_escape()` instead! - -********************************* -Cross-site request forgery (CSRF) -********************************* - -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 -:func:`form_open()` will automatically insert a hidden csrf field in -your forms. If not, then you can use ``get_csrf_token_name()`` -and ``get_csrf_hash()`` -:: - - $csrf = array( - 'name' => $this->security->get_csrf_token_name(), - 'hash' => $this->security->get_csrf_hash() - ); - - ... - - <input type="hidden" name="<?=$csrf['name'];?>" value="<?=$csrf['hash'];?>" /> - -Tokens may be either regenerated on every submission (default) or -kept the same throughout the life of the CSRF cookie. The default -regeneration of tokens provides stricter security, but may result -in usability concerns as other tokens become invalid (back/forward -navigation, multiple tabs/windows, asynchronous actions, etc). You -may alter this behavior by editing the following config parameter - -:: - - $config['csrf_regenerate'] = TRUE; - -Select URIs can be whitelisted from csrf protection (for example API -endpoints expecting externally POSTed content). You can add these URIs -by editing the 'csrf_exclude_uris' config parameter:: - - $config['csrf_exclude_uris'] = array('api/person/add'); - -Regular expressions are also supported (case-insensitive):: - - $config['csrf_exclude_uris'] = array( - 'api/record/[0-9]+', - 'api/title/[a-z]+' - ); - -*************** -Class Reference -*************** - -.. php:class:: CI_Security - - .. php:method:: xss_clean($str[, $is_image = FALSE]) - - :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. - - .. important:: This method is not suitable for filtering HTML attribute values! - Use :php:func:`html_escape()` for that instead. - - .. php: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: 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. - :: - - $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); - - .. php:method:: get_csrf_token_name() - - :returns: CSRF token name - :rtype: string - - Returns the CSRF token name (the ``$config['csrf_token_name']`` value). - - .. php:method:: get_csrf_hash() - - :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. - - .. php:method:: entity_decode($str[, $charset = NULL]) - - :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. - - .. php:method:: get_random_bytes($length) - - :param int $length: Output length - :returns: A binary stream of random bytes or FALSE on failure - :rtype: string - - A convenience method for getting proper random bytes via ``mcrypt_create_iv()``, - ``/dev/urandom`` or ``openssl_random_pseudo_bytes()`` (in that order), if one - of them is available. - - Used for generating CSRF and XSS tokens. - - .. note:: The output is NOT guaranteed to be cryptographically secure, - just the best attempt at that. diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst deleted file mode 100644 index 994dc2e08..000000000 --- a/user_guide_src/source/libraries/sessions.rst +++ /dev/null @@ -1,1062 +0,0 @@ -############### -Session Library -############### - -The Session class permits you maintain a user's "state" and track their -activity while they browse your site. - -CodeIgniter comes with a few session storage drivers: - - - files (default; file-system based) - - database - - redis - - memcached - -In addition, you may create your own, custom session drivers based on other -kinds of storage, while still taking advantage of the features of the -Session class. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -*********************** -Using the Session Class -*********************** - -Initializing a Session -====================== - -Sessions will typically run globally with each page load, so the Session -class should either be initialized in your :doc:`controller -<../general/controllers>` constructors, or it can be :doc:`auto-loaded -<../general/autoloader>` by the system. -For the most part the session class will run unattended in the background, -so simply initializing the class will cause it to read, create, and update -sessions when necessary. - -To initialize the Session class manually in your controller constructor, -use the ``$this->load->library()`` method:: - - $this->load->library('session'); - -Once loaded, the Sessions library object will be available using:: - - $this->session - -.. important:: Because the :doc:`Loader Class </libraries/loader>` is instantiated - by CodeIgniter's base controller, make sure to call - ``parent::__construct()`` before trying to load a library from - inside a controller constructor. - -How do Sessions work? -===================== - -When a page is loaded, the session class will check to see if valid -session cookie is sent by the user's browser. If a sessions cookie does -**not** exist (or if it doesn't match one stored on the server or has -expired) a new session will be created and saved. - -If a valid session does exist, its information will be updated. With each -update, the session ID may be regenerated if configured to do so. - -It's important for you to understand that once initialized, the Session -class runs automatically. There is nothing you need to do to cause the -above behavior to happen. You can, as you'll see below, work with session -data, but the process of reading, writing, and updating a session is -automatic. - -.. note:: Under CLI, the Session library will automatically halt itself, - as this is a concept based entirely on the HTTP protocol. - -A note about concurrency ------------------------- - -Unless you're developing a website with heavy AJAX usage, you can skip this -section. If you are, however, and if you're experiencing performance -issues, then this note is exactly what you're looking for. - -Sessions in previous versions of CodeIgniter didn't implement locking, -which meant that two HTTP requests using the same session could run exactly -at the same time. To use a more appropriate technical term - requests were -non-blocking. - -However, non-blocking requests in the context of sessions also means -unsafe, because modifications to session data (or session ID regeneration) -in one request can interfere with the execution of a second, concurrent -request. This detail was at the root of many issues and the main reason why -CodeIgniter 3.0 has a completely re-written Session library. - -Why are we telling you this? Because it is likely that after trying to -find the reason for your performance issues, you may conclude that locking -is the issue and therefore look into how to remove the locks ... - -DO NOT DO THAT! Removing locks would be **wrong** and it will cause you -more problems! - -Locking is not the issue, it is a solution. Your issue is that you still -have the session open, while you've already processed it and therefore no -longer need it. So, what you need is to close the session for the -current request after you no longer need it. - -Long story short - call ``session_write_close()`` once you no longer need -anything to do with session variables. - -What is Session Data? -===================== - -Session data is simply an array associated with a particular session ID -(cookie). - -If you've used sessions in PHP before, you should be familiar with PHP's -`$_SESSION superglobal <http://php.net/manual/en/reserved.variables.session.php>`_ -(if not, please read the content on that link). - -CodeIgniter gives access to its session data through the same means, as it -uses the session handlers' mechanism provided by PHP. Using session data is -as simple as manipulating (read, set and unset values) the ``$_SESSION`` -array. - -In addition, CodeIgniter also provides 2 special types of session data -that are further explained below: flashdata and tempdata. - -.. note:: In previous versions, regular session data in CodeIgniter was - referred to as 'userdata'. Have this in mind if that term is used - elsewhere in the manual. Most of it is written to explain how - the custom 'userdata' methods work. - -Retrieving Session Data -======================= - -Any piece of information from the session array is available through the -``$_SESSION`` superglobal:: - - $_SESSION['item'] - -Or through the magic getter:: - - $this->session->item - -And for backwards compatibility, through the ``userdata()`` method:: - - $this->session->userdata('item'); - -Where item is the array key corresponding to the item you wish to fetch. -For example, to assign a previously stored 'name' item to the ``$name`` -variable, you will do this:: - - $name = $_SESSION['name']; - - // or: - - $name = $this->session->name - - // or: - - $name = $this->session->userdata('name'); - -.. note:: The ``userdata()`` method 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 (magic getter only works for properties):: - - $_SESSION - - // or: - - $this->session->userdata(); - -Adding Session Data -=================== - -Let's say a particular user logs into your site. Once authenticated, you -could add their username and e-mail address to the session, making that -data globally available to you without having to run a database query when -you need it. - -You can simply assign data to the ``$_SESSION`` array, as with any other -variable. Or as a property of ``$this->session``. - -Alternatively, the old method of assigning it as "userdata" is also -available. That however passing an array containing your new data to the -``set_userdata()`` method:: - - $this->session->set_userdata($array); - -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 - ); - - $this->session->set_userdata($newdata); - -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 session value exists, simply check with -``isset()``:: - - // returns FALSE if the 'some_name' item doesn't exist or is NULL, - // TRUE otherwise: - isset($_SESSION['some_name']) - -Or you can call ``has_userdata()``:: - - $this->session->has_userdata('some_name'); - -Removing Session Data -===================== - -Just as with any other variable, unsetting a value in ``$_SESSION`` can be -done through ``unset()``:: - - unset($_SESSION['some_name']); - - // or multiple values: - - unset( - $_SESSION['some_name'], - $_SESSION['another_name'] - ); - -Also, just as ``set_userdata()`` can be used to add information to a -session, ``unset_userdata()`` can be used to remove it, by passing the -session key. For example, if you wanted to remove 'some_name' from your -session data array:: - - $this->session->unset_userdata('some_name'); - -This method also accepts an array of item keys to unset:: - - $array_items = array('username', 'email'); - - $this->session->unset_userdata($array_items); - -.. note:: In previous versions, the ``unset_userdata()`` method used - to accept an associative array of ``key => 'dummy value'`` - pairs. This is no longer supported. - -Flashdata -========= - -CodeIgniter supports "flashdata", or session data that will only be -available for the next request, and is then automatically cleared. - -This can be very useful, especially for one-time informational, error or -status messages (for example: "Record 2 deleted"). - -It should be noted that flashdata variables are regular session vars, -only marked in a specific way under the '__ci_vars' key (please don't touch -that one, you've been warned). - -To mark an existing item as "flashdata":: - - $this->session->mark_as_flash('item'); - -If you want to mark multiple items as flashdata, simply pass the keys as an -array:: - - $this->session->mark_as_flash(array('item', 'item2')); - -To add flashdata:: - - $_SESSION['item'] = 'value'; - $this->session->mark_as_flash('item'); - -Or alternatively, using the ``set_flashdata()`` method:: - - $this->session->set_flashdata('item', 'value'); - -You can also pass an array to ``set_flashdata()``, in the same manner as -``set_userdata()``. - -Reading flashdata variables is the same as reading regular session data -through ``$_SESSION``:: - - $_SESSION['item'] - -.. important:: The ``userdata()`` method will NOT return flashdata items. - -However, if you want to be sure that you're reading "flashdata" (and not -any other kind), you can also use the ``flashdata()`` method:: - - $this->session->flashdata('item'); - -Or to get an array with all flashdata, simply omit the key parameter:: - - $this->session->flashdata(); - -.. note:: The ``flashdata()`` method returns NULL if the item cannot be - found. - -If you find that you need to preserve a flashdata variable through an -additional request, you can do so using the ``keep_flashdata()`` method. -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')); - -Tempdata -======== - -CodeIgniter also supports "tempdata", or session data with a specific -expiration time. After the value expires, or the session expires or is -deleted, the value is automatically removed. - -Similarly to flashdata, tempdata variables are regular session vars that -are marked in a specific way under the '__ci_vars' key (again, don't touch -that one). - -To mark an existing item as "tempdata", simply pass its key and expiry time -(in seconds!) to the ``mark_as_temp()`` method:: - - // 'item' will be erased after 300 seconds - $this->session->mark_as_temp('item', 300); - -You can mark multiple items as tempdata in two ways, depending on whether -you want them all to have the same expiry time or not:: - - // Both 'item' and 'item2' will expire after 300 seconds - $this->session->mark_as_temp(array('item', 'item2'), 300); - - // 'item' will be erased after 300 seconds, while 'item2' - // will do so after only 240 seconds - $this->session->mark_as_temp(array( - 'item' => 300, - 'item2' => 240 - )); - -To add tempdata:: - - $_SESSION['item'] = 'value'; - $this->session->mark_as_temp('item', 300); // Expire in 5 minutes - -Or alternatively, using the ``set_tempdata()`` method:: - - $this->session->set_tempdata('item', 'value', 300); - -You can also pass an array to ``set_tempdata()``:: - - $tempdata = array('newuser' => TRUE, 'message' => 'Thanks for joining!'); - - $this->session->set_tempdata($tempdata, NULL, $expire); - -.. note:: If the expiration is omitted or set to 0, the default - time-to-live value of 300 seconds (or 5 minutes) will be used. - -To read a tempdata variable, again you can just access it through the -``$_SESSION`` superglobal array:: - - $_SESSION['item'] - -.. important:: The ``userdata()`` method will NOT return tempdata items. - -Or if you want to be sure that you're reading "tempdata" (and not any -other kind), you can also use the ``tempdata()`` method:: - - $this->session->tempdata('item'); - -And of course, if you want to retrieve all existing tempdata:: - - $this->session->tempdata(); - -.. note:: The ``tempdata()`` method returns NULL if the item cannot be - found. - -If you need to remove a tempdata value before it expires, you can directly -unset it from the ``$_SESSION`` array:: - - unset($_SESSION['item']); - -However, this won't remove the marker that makes this specific item to be -tempdata (it will be invalidated on the next HTTP request), so if you -intend to reuse that same key in the same request, you'd want to use -``unset_tempdata()``:: - - $this->session->unset_tempdata('item'); - -Destroying a Session -==================== - -To clear the current session (for example, during a logout), you may -simply use either PHP's `session_destroy() <http://php.net/session_destroy>`_ -function, or the ``sess_destroy()`` method. Both will work in exactly the -same way:: - - session_destroy(); - - // or - - $this->session->sess_destroy(); - -.. note:: This must be the last session-related operation that you do - during the same request. All session data (including flashdata and - tempdata) will be destroyed permanently and functions will be - unusable during the same request after you destroy the session. - -Accessing session metadata -========================== - -In previous CodeIgniter versions, the session data array included 4 items -by default: 'session_id', 'ip_address', 'user_agent', 'last_activity'. - -This was due to the specifics of how sessions worked, but is now no longer -necessary with our new implementation. However, it may happen that your -application relied on these values, so here are alternative methods of -accessing them: - - - session_id: ``session_id()`` - - ip_address: ``$_SERVER['REMOTE_ADDR']`` - - user_agent: ``$this->input->user_agent()`` (unused by sessions) - - last_activity: Depends on the storage, no straightforward way. Sorry! - -Session Preferences -=================== - -CodeIgniter will usually make everything work out of the box. However, -Sessions are a very sensitive component of any application, so some -careful configuration must be done. Please take your time to consider -all of the options and their effects. - -You'll find the following Session related preferences in your -**application/config/config.php** file: - -============================ =============== ======================================== ============================================================================================ -Preference Default Options Description -============================ =============== ======================================== ============================================================================================ -**sess_driver** files files/database/redis/memcached/*custom* The session storage driver to use. -**sess_cookie_name** ci_session [A-Za-z\_-] characters only The name used for the session cookie. -**sess_expiration** 7200 (2 hours) Time in seconds (integer) The number of seconds you would like the session to last. - If you would like a non-expiring session (until browser is closed) set the value to zero: 0 -**sess_save_path** NULL None Specifies the storage location, depends on the driver being used. -**sess_match_ip** FALSE TRUE/FALSE (boolean) Whether to validate the user's IP address when reading the session cookie. - Note that some ISPs dynamically changes the IP, so if you want a non-expiring session you - will likely set this to FALSE. -**sess_time_to_update** 300 Time in seconds (integer) This option controls how often the session class will regenerate itself and create a new - session ID. Setting it to 0 will disable session ID regeneration. -**sess_regenerate_destroy** FALSE TRUE/FALSE (boolean) Whether to destroy session data associated with the old session ID when auto-regenerating - the session ID. When set to FALSE, the data will be later deleted by the garbage collector. -============================ =============== ======================================== ============================================================================================ - -.. note:: As a last resort, the Session library will try to fetch PHP's - session related INI settings, as well as legacy CI settings such as - 'sess_expire_on_close' when any of the above is not configured. - However, you should never rely on this behavior as it can cause - unexpected results or be changed in the future. Please configure - everything properly. - -In addition to the values above, the cookie and native drivers apply the -following configuration values shared by the :doc:`Input <input>` and -:doc:`Security <security>` classes: - -================== =============== =========================================================================== -Preference Default Description -================== =============== =========================================================================== -**cookie_domain** '' The domain for which the session is applicable -**cookie_path** / The path to which the session is applicable -**cookie_secure** FALSE Whether to create the session cookie only on encrypted (HTTPS) connections -================== =============== =========================================================================== - -.. note:: The 'cookie_httponly' setting doesn't have an effect on sessions. - Instead the HttpOnly parameter is always enabled, for security - reasons. Additionally, the 'cookie_prefix' setting is completely - ignored. - -Session Drivers -=============== - -As already mentioned, the Session library comes with 4 drivers, or storage -engines, that you can use: - - - files - - database - - redis - - memcached - -By default, the `Files Driver`_ will be used when a session is initialized, -because it is the most safe choice and is expected to work everywhere -(virtually every environment has a file system). - -However, any other driver may be selected via the ``$config['sess_driver']`` -line in your **application/config/config.php** file, if you chose to do so. -Have it in mind though, every driver has different caveats, so be sure to -get yourself familiar with them (below) before you make that choice. - -In addition, you may also create and use `Custom Drivers`_, if the ones -provided by default don't satisfy your use case. - -.. note:: In previous CodeIgniter versions, a different, "cookie driver" - was the only option and we have received negative feedback on not - providing that option. While we do listen to feedback from the - community, we want to warn you that it was dropped because it is - **unsafe** and we advise you NOT to try to replicate it via a - custom driver. - -Files Driver ------------- - -The 'files' driver uses your file system for storing session data. - -It can safely be said that it works exactly like PHP's own default session -implementation, but in case this is an important detail for you, have it -mind that it is in fact not the same code and it has some limitations -(and advantages). - -To be more specific, it doesn't support PHP's `directory level and mode -formats used in session.save_path -<http://php.net/manual/en/session.configuration.php#ini.session.save-path>`_, -and it has most of the options hard-coded for safety. Instead, only -absolute paths are supported for ``$config['sess_save_path']``. - -Another important thing that you should know, is to make sure that you -don't use a publicly-readable or shared directory for storing your session -files. Make sure that *only you* have access to see the contents of your -chosen *sess_save_path* directory. Otherwise, anybody who can do that, can -also steal any of the current sessions (also known as "session fixation" -attack). - -On UNIX-like operating systems, this is usually achieved by setting the -0700 mode permissions on that directory via the `chmod` command, which -allows only the directory's owner to perform read and write operations on -it. But be careful because the system user *running* the script is usually -not your own, but something like 'www-data' instead, so only setting those -permissions will probable break your application. - -Instead, you should do something like this, depending on your environment -:: - - mkdir /<path to your application directory>/sessions/ - chmod 0700 /<path to your application directory>/sessions/ - chown www-data /<path to your application directory>/sessions/ - -Bonus Tip -^^^^^^^^^ - -Some of you will probably opt to choose another session driver because -file storage is usually slower. This is only half true. - -A very basic test will probably trick you into believing that an SQL -database is faster, but in 99% of the cases, this is only true while you -only have a few current sessions. As the sessions count and server loads -increase - which is the time when it matters - the file system will -consistently outperform almost all relational database setups. - -In addition, if performance is your only concern, you may want to look -into using `tmpfs <http://eddmann.com/posts/storing-php-sessions-file-caches-in-memory-using-tmpfs/>`_, -(warning: external resource), which can make your sessions blazing fast. - -Database Driver ---------------- - -The 'database' driver uses a relational database such as MySQL or -PostgreSQL to store sessions. This is a popular choice among many users, -because it allows the developer easy access to the session data within -an application - it is just another table in your database. - -However, there are some conditions that must be met: - - - Only your **default** database connection (or the one that you access - as ``$this->db`` from your controllers) can be used. - - You must have the :doc:`Query Builder </database/query_builder>` - enabled. - - You can NOT use a persistent connection. - - You can NOT use a connection with the *cache_on* setting enabled. - -In order to use the 'database' session driver, you must also create this -table that we already mentioned and then set it as your -``$config['sess_save_path']`` value. -For example, if you would like to use 'ci_sessions' as your table name, -you would do this:: - - $config['sess_driver'] = 'database'; - $config['sess_save_path'] = 'ci_sessions'; - -.. note:: If you've upgraded from a previous version of CodeIgniter and - you don't have 'sess_save_path' configured, then the Session - library will look for the old 'sess_table_name' setting and use - it instead. Please don't rely on this behavior as it will get - removed in the future. - -And then of course, create the database table ... - -For MySQL:: - - CREATE TABLE IF NOT EXISTS `ci_sessions` ( - `id` varchar(128) NOT NULL, - `ip_address` varchar(45) NOT NULL, - `timestamp` int(10) unsigned DEFAULT 0 NOT NULL, - `data` blob NOT NULL, - KEY `ci_sessions_timestamp` (`timestamp`) - ); - -For PostgreSQL:: - - CREATE TABLE "ci_sessions" ( - "id" varchar(128) NOT NULL, - "ip_address" varchar(45) NOT NULL, - "timestamp" bigint DEFAULT 0 NOT NULL, - "data" text DEFAULT '' NOT NULL - ); - - CREATE INDEX "ci_sessions_timestamp" ON "ci_sessions" ("timestamp"); - -You will also need to add a PRIMARY KEY **depending on your 'sess_match_ip' -setting**. The examples below work both on MySQL and PostgreSQL:: - - // When sess_match_ip = TRUE - ALTER TABLE ci_sessions ADD PRIMARY KEY (id, ip_address); - - // When sess_match_ip = FALSE - ALTER TABLE ci_sessions ADD PRIMARY KEY (id); - - // To drop a previously created primary key (use when changing the setting) - ALTER TABLE ci_sessions DROP PRIMARY KEY; - - -.. important:: Only MySQL and PostgreSQL databases are officially - supported, due to lack of advisory locking mechanisms on other - platforms. Using sessions without locks can cause all sorts of - problems, especially with heavy usage of AJAX, and we will not - support such cases. Use ``session_write_close()`` after you've - done processing session data if you're having performance - issues. - -Redis Driver ------------- - -.. note:: Since Redis doesn't have a locking mechanism exposed, locks for - this driver are emulated by a separate value that is kept for up - to 300 seconds. - -Redis is a storage engine typically used for caching and popular because -of its high performance, which is also probably your reason to use the -'redis' session driver. - -The downside is that it is not as ubiquitous as relational databases and -requires the `phpredis <https://github.com/phpredis/phpredis>`_ PHP -extension to be installed on your system, and that one doesn't come -bundled with PHP. -Chances are, you're only be using the 'redis' driver only if you're already -both familiar with Redis and using it for other purposes. - -Just as with the 'files' and 'database' drivers, you must also configure -the storage location for your sessions via the -``$config['sess_save_path']`` setting. -The format here is a bit different and complicated at the same time. It is -best explained by the *phpredis* extension's README file, so we'll simply -link you to it: - - https://github.com/phpredis/phpredis#php-session-handler - -.. warning:: CodeIgniter's Session library does NOT use the actual 'redis' - ``session.save_handler``. Take note **only** of the path format in - the link above. - -For the most common case however, a simple ``host:port`` pair should be -sufficient:: - - $config['sess_driver'] = 'redis'; - $config['sess_save_path'] = 'tcp://localhost:6379'; - -Memcached Driver ----------------- - -.. note:: Since Memcache doesn't have a locking mechanism exposed, locks - for this driver are emulated by a separate value that is kept for - up to 300 seconds. - -The 'memcached' driver is very similar to the 'redis' one in all of its -properties, except perhaps for availability, because PHP's `Memcached -<http://php.net/memcached>`_ extension is distributed via PECL and some -Linux distrubutions make it available as an easy to install package. - -Other than that, and without any intentional bias towards Redis, there's -not much different to be said about Memcached - it is also a popular -product that is usually used for caching and famed for its speed. - -However, it is worth noting that the only guarantee given by Memcached -is that setting value X to expire after Y seconds will result in it being -deleted after Y seconds have passed (but not necessarily that it won't -expire earlier than that time). This happens very rarely, but should be -considered as it may result in loss of sessions. - -The ``$config['sess_save_path']`` format is fairly straightforward here, -being just a ``host:port`` pair:: - - $config['sess_driver'] = 'memcached'; - $config['sess_save_path'] = 'localhost:11211'; - -Bonus Tip -^^^^^^^^^ - -Multi-server configuration with an optional *weight* parameter as the -third colon-separated (``:weight``) value is also supported, but we have -to note that we haven't tested if that is reliable. - -If you want to experiment with this feature (on your own risk), simply -separate the multiple server paths with commas:: - - // localhost will be given higher priority (5) here, - // compared to 192.0.2.1 with a weight of 1. - $config['sess_save_path'] = 'localhost:11211:5,192.0.2.1:11211:1'; - -Custom Drivers --------------- - -You may also create your own, custom session drivers. However, have it in -mind that this is typically not an easy task, as it takes a lot of -knowledge to do it properly. - -You need to know not only how sessions work in general, but also how they -work specifically in PHP, how the underlying storage mechanism works, how -to handle concurrency, avoid deadlocks (but NOT through lack of locks) and -last but not least - how to handle the potential security issues, which -is far from trivial. - -Long story short - if you don't know how to do that already in raw PHP, -you shouldn't be trying to do it within CodeIgniter either. You've been -warned. - -If you only want to add some extra functionality to your sessions, just -extend the base Session class, which is a lot more easier. Read the -:doc:`Creating Libraries <../general/creating_libraries>` article to -learn how to do that. - -Now, to the point - there are three general rules that you must follow -when creating a session driver for CodeIgniter: - - - Put your driver's file under **application/libraries/Session/drivers/** - and follow the naming conventions used by the Session class. - - For example, if you were to create a 'dummy' driver, you would have - a ``Session_dummy_driver`` class name, that is declared in - *application/libraries/Session/drivers/Session_dummy_driver.php*. - - - Extend the ``CI_Session_driver`` class. - - This is just a basic class with a few internal helper methods. It is - also extendable like any other library, if you really need to do that, - but we are not going to explain how ... if you're familiar with how - class extensions/overrides work in CI, then you already know how to do - it. If not, well, you shouldn't be doing it in the first place. - - - - Implement the `SessionHandlerInterface - <http://php.net/sessionhandlerinterface>`_ interface. - - .. note:: You may notice that ``SessionHandlerInterface`` is provided - by PHP since version 5.4.0. CodeIgniter will automatically declare - the same interface if you're running an older PHP version. - - The link will explain why and how. - -So, based on our 'dummy' driver example above, you'd end up with something -like this:: - - // application/libraries/Session/drivers/Session_dummy_driver.php: - - class CI_Session_dummy_driver extends CI_Session_driver implements SessionHandlerInterface - { - - public function __construct(&$params) - { - // DO NOT forget this - parent::__construct($params); - - // Configuration & other initializations - } - - public function open($save_path, $name) - { - // Initialize storage mechanism (connection) - } - - public function read($session_id) - { - // Read session data (if exists), acquire locks - } - - public function write($session_id, $session_data) - { - // Create / update session data (it might not exist!) - } - - public function close() - { - // Free locks, close connections / streams / etc. - } - - public function destroy($session_id) - { - // Call close() method & destroy data for current session (order may differ) - } - - public function gc($maxlifetime) - { - // Erase data for expired sessions - } - - } - -If you've done everything properly, you can now set your *sess_driver* -configuration value to 'dummy' and use your own driver. Congratulations! - -*************** -Class Reference -*************** - -.. php:class:: CI_Session - - .. php:method:: userdata([$key = NULL]) - - :param mixed $key: Session item key or NULL - :returns: Value of the specified item key, or an array of all userdata - :rtype: mixed - - Gets the value for a specific ``$_SESSION`` item, or an - array of all "userdata" items if not key was specified. - - .. note:: This is a legacy method kept only for backwards - compatibility with older applications. You should - directly access ``$_SESSION`` instead. - - .. php:method:: all_userdata() - - :returns: An array of all userdata - :rtype: array - - Returns an array containing all "userdata" items. - - .. note:: This method is DEPRECATED. Use ``userdata()`` - with no parameters instead. - - .. php:method:: &get_userdata() - - :returns: A reference to ``$_SESSION`` - :rtype: array - - Returns a reference to the ``$_SESSION`` array. - - .. note:: This is a legacy method kept only for backwards - compatibility with older applications. - - .. php:method:: has_userdata($key) - - :param string $key: Session item key - :returns: TRUE if the specified key exists, FALSE if not - :rtype: bool - - Checks if an item exists in ``$_SESSION``. - - .. note:: This is a legacy method kept only for backwards - compatibility with older applications. It is just - an alias for ``isset($_SESSION[$key])`` - please - use that instead. - - .. php:method:: set_userdata($data[, $value = NULL]) - - :param mixed $data: An array of key/value pairs to set as session data, or the key for a single item - :param mixed $value: The value to set for a specific session item, if $data is a key - :rtype: void - - Assigns data to the ``$_SESSION`` superglobal. - - .. note:: This is a legacy method kept only for backwards - compatibility with older applications. - - .. php:method:: unset_userdata($key) - - :param mixed $key: Key for the session data item to unset, or an array of multiple keys - :rtype: void - - Unsets the specified key(s) from the ``$_SESSION`` - superglobal. - - .. note:: This is a legacy method kept only for backwards - compatibility with older applications. It is just - an alias for ``unset($_SESSION[$key])`` - please - use that instead. - - .. php:method:: mark_as_flash($key) - - :param mixed $key: Key to mark as flashdata, or an array of multiple keys - :returns: TRUE on success, FALSE on failure - :rtype: bool - - Marks a ``$_SESSION`` item key (or multiple ones) as - "flashdata". - - .. php:method:: get_flash_keys() - - :returns: Array containing the keys of all "flashdata" items. - :rtype: array - - Gets a list of all ``$_SESSION`` that have been marked as - "flashdata". - - .. php:method:: unmark_flash($key) - - :param mixed $key: Key to be un-marked as flashdata, or an array of multiple keys - :rtype: void - - Unmarks a ``$_SESSION`` item key (or multiple ones) as - "flashdata". - - .. php:method:: flashdata([$key = NULL]) - - :param mixed $key: Flashdata item key or NULL - :returns: Value of the specified item key, or an array of all flashdata - :rtype: mixed - - Gets the value for a specific ``$_SESSION`` item that has - been marked as "flashdata", or an array of all "flashdata" - items if no key was specified. - - .. note:: This is a legacy method kept only for backwards - compatibility with older applications. You should - directly access ``$_SESSION`` instead. - - .. php:method:: keep_flashdata($key) - - :param mixed $key: Flashdata key to keep, or an array of multiple keys - :returns: TRUE on success, FALSE on failure - :rtype: bool - - Retains the specified session data key(s) as "flashdata" - through the next request. - - .. note:: This is a legacy method kept only for backwards - compatibility with older applications. It is just - an alias for the ``mark_as_flash()`` method. - - .. php:method:: set_flashdata($data[, $value = NULL]) - - :param mixed $data: An array of key/value pairs to set as flashdata, or the key for a single item - :param mixed $value: The value to set for a specific session item, if $data is a key - :rtype: void - - Assigns data to the ``$_SESSION`` superglobal and marks it - as "flashdata". - - .. note:: This is a legacy method kept only for backwards - compatibility with older applications. - - .. php:method:: mark_as_temp($key[, $ttl = 300]) - - :param mixed $key: Key to mark as tempdata, or an array of multiple keys - :param int $ttl: Time-to-live value for the tempdata, in seconds - :returns: TRUE on success, FALSE on failure - :rtype: bool - - Marks a ``$_SESSION`` item key (or multiple ones) as - "tempdata". - - .. php:method:: get_temp_keys() - - :returns: Array containing the keys of all "tempdata" items. - :rtype: array - - Gets a list of all ``$_SESSION`` that have been marked as - "tempdata". - - .. php:method:: unmark_temp($key) - - :param mixed $key: Key to be un-marked as tempdata, or an array of multiple keys - :rtype: void - - Unmarks a ``$_SESSION`` item key (or multiple ones) as - "tempdata". - - .. php:method:: tempdata([$key = NULL]) - - :param mixed $key: Tempdata item key or NULL - :returns: Value of the specified item key, or an array of all tempdata - :rtype: mixed - - Gets the value for a specific ``$_SESSION`` item that has - been marked as "tempdata", or an array of all "tempdata" - items if no key was specified. - - .. note:: This is a legacy method kept only for backwards - compatibility with older applications. You should - directly access ``$_SESSION`` instead. - - .. php:method:: set_tempdata($data[, $value = NULL]) - - :param mixed $data: An array of key/value pairs to set as tempdata, or the key for a single item - :param mixed $value: The value to set for a specific session item, if $data is a key - :param int $ttl: Time-to-live value for the tempdata item(s), in seconds - :rtype: void - - Assigns data to the ``$_SESSION`` superglobal and marks it - as "tempdata". - - .. note:: This is a legacy method kept only for backwards - compatibility with older applications. - - .. php:method:: sess_regenerate([$destroy = FALSE]) - - :param bool $destroy: Whether to destroy session data - :rtype: void - - Regenerate session ID, optionally destroying the current - session's data. - - .. note:: This method is just an alias for PHP's native - `session_regenerate_id() - <http://php.net/session_regenerate_id>`_ function. - - .. php:method:: sess_destroy() - - :rtype: void - - Destroys the current session. - - .. note:: This must be the *last* session-related function - that you call. All session data will be lost after - you do that. - - .. note:: This method is just an alias for PHP's native - `session_destroy() - <http://php.net/session_destroy>`_ function. - - .. php:method:: __get($key) - - :param string $key: Session item key - :returns: The requested session data item, or NULL if it doesn't exist - :rtype: mixed - - A magic method that allows you to use - ``$this->session->item`` instead of ``$_SESSION['item']``, - if that's what you prefer. - - It will also return the session ID by calling - ``session_id()`` if you try to access - ``$this->session->session_id``. - - .. php:method:: __set($key, $value) - - :param string $key: Session item key - :param mixed $value: Value to assign to the session item key - :returns: void - - A magic method that allows you to assign items to - ``$_SESSION`` by accessing them as ``$this->session`` - properties:: - - $this->session->foo = 'bar'; - - // Results in: - // $_SESSION['foo'] = 'bar'; diff --git a/user_guide_src/source/libraries/table.rst b/user_guide_src/source/libraries/table.rst deleted file mode 100644 index 91ae1ae8d..000000000 --- a/user_guide_src/source/libraries/table.rst +++ /dev/null @@ -1,297 +0,0 @@ -################ -HTML Table Class -################ - -The Table Class provides functions that enable you to auto-generate HTML -tables from arrays or database result sets. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -********************* -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()`` method:: - - $this->load->library('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()`` -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') - ); - - 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()`` -method described in the class reference below). - -:: - - $this->load->library('table'); - - $query = $this->db->query('SELECT * FROM my_table'); - - echo $this->table->generate($query); - -Here is an example showing how you might create a table using discrete -parameters:: - - $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(); - -Here is the same example, except instead of individual parameters, -arrays are used:: - - $this->load->library('table'); - - $this->table->set_heading(array('Name', 'Color', 'Size')); - - $this->table->add_row(array('Fred', 'Blue', 'Small')); - $this->table->add_row(array('Mary', 'Red', 'Large')); - $this->table->add_row(array('John', 'Green', 'Medium')); - - echo $this->table->generate(); - -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:: - - $template = array( - 'table_open' => '<table border="0" cellpadding="4" cellspacing="0">', - - 'thead_open' => '<thead>', - 'thead_close' => '</thead>', - - 'heading_row_start' => '<tr>', - 'heading_row_end' => '</tr>', - 'heading_cell_start' => '<th>', - 'heading_cell_end' => '</th>', - - 'tbody_open' => '<tbody>', - 'tbody_close' => '</tbody>', - - 'row_start' => '<tr>', - 'row_end' => '</tr>', - 'cell_start' => '<td>', - 'cell_end' => '</td>', - - 'row_alt_start' => '<tr>', - 'row_alt_end' => '</tr>', - 'cell_alt_start' => '<td>', - 'cell_alt_end' => '</td>', - - 'table_close' => '</table>' - ); - - $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 - elements that alternate with each iteration of the row data. - -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:: - - $template = array( - 'table_open' => '<table border="1" cellpadding="2" cellspacing="1" class="mytable">' - ); - - $this->table->set_template($template); - -You can also set defaults for these in a config file. - -*************** -Class Reference -*************** - -.. php:class:: CI_Table - - .. attribute:: $function = NULL - - Allows you to specify a native PHP function or a valid function array object to be applied to all cell data. - :: - - $this->load->library('table'); - - $this->table->set_heading('Name', 'Color', 'Size'); - $this->table->add_row('Fred', '<strong>Blue</strong>', 'Small'); - - $this->table->function = 'htmlspecialchars'; - echo $this->table->generate(); - - In the above example, all cell data would be ran through PHP's :php:func:`htmlspecialchars()` function, resulting in:: - - <td>Fred</td><td><strong>Blue</strong></td><td>Small</td> - - .. php:method:: generate([$table_data = NULL]) - - :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. - - .. php:method:: set_caption($caption) - - :param string $caption: Table caption - :returns: CI_Table instance (method chaining) - :rtype: CI_Table - - Permits you to add a caption to the table. - :: - - $this->table->set_caption('Colors'); - - .. php:method:: set_heading([$args = array()[, ...]]) - - :param mixed $args: An array or multiple strings containing the table column titles - :returns: CI_Table instance (method chaining) - :rtype: CI_Table - - Permits you to set the table heading. You can submit an array or discrete params:: - - $this->table->set_heading('Name', 'Color', 'Size'); - - $this->table->set_heading(array('Name', 'Color', 'Size')); - - .. php:method:: add_row([$args = array()[, ...]]) - - :param mixed $args: An array or multiple strings containing the row values - :returns: CI_Table instance (method chaining) - :rtype: CI_Table - - Permits you to add a row to your table. You can submit an array or discrete params:: - - $this->table->add_row('Blue', 'Red', 'Green'); - - $this->table->add_row(array('Blue', 'Red', 'Green')); - - 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:: - - $cell = array('data' => 'Blue', 'class' => 'highlight', 'colspan' => 2); - $this->table->add_row($cell, 'Red', 'Green'); - - // generates - // <td class='highlight' colspan='2'>Blue</td><td>Red</td><td>Green</td> - - .. php: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: 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:: - - $list = array('one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve'); - - $new_list = $this->table->make_columns($list, 3); - - $this->table->generate($new_list); - - // Generates a table with this prototype - - <table border="0" cellpadding="4" cellspacing="0"> - <tr> - <td>one</td><td>two</td><td>three</td> - </tr><tr> - <td>four</td><td>five</td><td>six</td> - </tr><tr> - <td>seven</td><td>eight</td><td>nine</td> - </tr><tr> - <td>ten</td><td>eleven</td><td>twelve</td></tr> - </table> - - - .. php:method:: set_template($template) - - :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. - :: - - $template = array( - 'table_open' => '<table border="1" cellpadding="2" cellspacing="1" class="mytable">' - ); - - $this->table->set_template($template); - - .. php:method:: set_empty($value) - - :param mixed $value: Value to put in empty cells - :returns: CI_Table instance (method chaining) - :rtype: CI_Table - - 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->table->set_empty(" "); - - .. php:method:: clear() - - :returns: CI_Table instance (method chaining) - :rtype: CI_Table - - 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(); - - $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(); diff --git a/user_guide_src/source/libraries/trackback.rst b/user_guide_src/source/libraries/trackback.rst deleted file mode 100644 index dc4477e9f..000000000 --- a/user_guide_src/source/libraries/trackback.rst +++ /dev/null @@ -1,339 +0,0 @@ -############### -Trackback Class -############### - -The Trackback Class provides functions that enable you to send and -receive Trackback data. - -If you are not familiar with Trackbacks you'll find more information -`here <http://en.wikipedia.org/wiki/Trackback>`_. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -************************* -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()`` method:: - - $this->load->library('trackback'); - -Once loaded, the Trackback library object will be available using:: - - $this->trackback - -Sending Trackbacks -================== - -A Trackback can be sent from any of your controller functions using code -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' - ); - - if ( ! $this->trackback->send($tb_data)) - { - echo $this->trackback->display_errors(); - } - else - { - 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. -- **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. -- **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:: - - $this->trackback->display_errors(); - -Receiving Trackbacks -==================== - -Before you can receive Trackbacks you must create a weblog. If you don't -have a blog yet there's no point in continuing. - -Receiving Trackbacks is a little more complex than sending them, only -because you will need a database table in which to store them, and you -will need to validate the incoming trackback data. You are encouraged to -implement a thorough validation process to guard against spam and -duplicate data. You may also want to limit the number of Trackbacks you -allow from a particular IP within a given span of time to further -curtail spam. The process of receiving a Trackback is quite simple; the -validation is what takes most of the effort. - -Your Ping URL -============= - -In order to accept Trackbacks you must display a Trackback URL next to -each one of your weblog entries. This will be the URL that people will -use to send you Trackbacks (we will refer to this as your "Ping URL"). - -Your Ping URL must point to a controller function where your Trackback -receiving code is located, and the URL must contain the ID number for -each particular entry, so that when the Trackback is received you'll be -able to associate it with a particular entry. - -For example, if your controller class is called Trackback, and the -receiving function is called receive, your Ping URLs will look something -like this:: - - http://example.com/index.php/trackback/receive/entry_id - -Where entry_id represents the individual ID number for each of your -entries. - -Creating a Trackback Table -========================== - -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`) - ); - -The Trackback specification only requires four pieces of information to -be sent in a Trackback (url, title, excerpt, blog_name), but to make -the data more useful we've added a few more fields in the above table -schema (date, IP address, etc.). - -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.:: - - $this->load->library('trackback'); - $this->load->database(); - - if ($this->uri->segment(3) == FALSE) - { - $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'); - } - - $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() - ); - - $sql = $this->db->insert_string('trackbacks', $data); - $this->db->query($sql); - - $this->trackback->send_success(); - -Notes: -^^^^^^ - -The entry ID number is expected in the third segment of your URL. This -is based on the URI example we gave earlier:: - - http://example.com/index.php/trackback/receive/entry_id - -Notice the entry_id is in the third URI segment, which you can retrieve -using:: - - $this->uri->segment(3); - -In our Trackback receiving code above, if the third segment is missing, -we will issue an error. Without a valid entry ID, there's no reason to -continue. - -The $this->trackback->receive() function is simply a validation function -that looks at the incoming data and makes sure it contains the four -pieces of data that are required (url, title, excerpt, blog_name). It -returns TRUE on success and FALSE on failure. If it fails you will issue -an error message. - -The incoming Trackback data can be retrieved using this function:: - - $this->trackback->data('item') - -Where item represents one of these four pieces of info: url, title, -excerpt, or blog_name - -If the Trackback data is successfully received, you will issue a success -message using:: - - $this->trackback->send_success(); - -.. note:: The above code contains no data validation, which you are - encouraged to add. - -*************** -Class Reference -*************** - -.. php: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. - - .. php:method:: send($tb_data) - - :param array $tb_data: Trackback data - :returns: TRUE on success, FALSE on failure - :rtype: bool - - Send trackback. - - .. php:method:: receive() - - :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. - - .. php:method:: send_error([$message = 'Incomplete information']) - - :param string $message: Error message - :rtype: void - - Responses to a trackback request with an error message. - - .. note:: This method will terminate script execution. - - .. php:method:: send_success() - - :rtype: void - - Responses to a trackback request with a success message. - - .. note:: This method will terminate script execution. - - .. php:method:: data($item) - - :param string $item: Data key - :returns: Data value or empty string if not found - :rtype: string - - Returns a single item from the response data array. - - .. php:method:: process($url, $data) - - :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. - - .. php:method:: extract_urls($urls) - - :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. - - .. php:method:: validate_url(&$url) - - :param string $url: Trackback URL - :rtype: void - - Simply adds the *http://* prefix it it's not already present in the URL. - - .. php:method:: get_id($url) - - :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. - - .. php:method:: convert_xml($str) - - :param string $str: Input string - :returns: Converted string - :rtype: string - - Converts reserved XML characters to entities. - - .. php: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: Shortened string - :rtype: string - - Limits the string based on the character count. Will preserve complete words. - - .. php:method:: convert_ascii($str) - - :param string $str: Input string - :returns: Converted string - :rtype: string - - Converts high ASCII text and MS Word special characterss to HTML entities. - - .. php:method:: set_error($msg) - - :param string $msg: Error message - :rtype: void - - Set an log an error message. - - .. php:method:: display_errors([$open = '<p>'[, $close = '</p>']]) - - :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 deleted file mode 100644 index 321b064ba..000000000 --- a/user_guide_src/source/libraries/typography.rst +++ /dev/null @@ -1,107 +0,0 @@ -################ -Typography Class -################ - -The Typography Class provides methods that help you format text. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -************************** -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()`` method:: - - $this->load->library('typography'); - -Once loaded, the Typography library object will be available using:: - - $this->typography - -*************** -Class Reference -*************** - -.. php:class:: CI_Typography - - .. attribute:: $protect_braced_quotes = FALSE - - 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. - - Usage example:: - - $this->load->library('typography'); - $this->typography->protect_braced_quotes = TRUE; - - .. php:method:: auto_typography($str[, $reduce_linebreaks = FALSE]) - - :param string $str: Input string - :param bool $reduce_linebreaks: Whether to reduce consecutive 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: - - - Surrounds paragraphs within <p></p> (looks for double line breaks to identify paragraphs). - - Single line breaks are converted to <br />, except those that appear within <pre> tags. - - Block level elements, like <div> 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. - - Usage example:: - - $string = $this->typography->auto_typography($string); - - 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); - - .. 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. - - .. php:method:: format_characters($str) - - :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: - - - 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. - - Usage example:: - - $string = $this->typography->format_characters($string); - - .. php:method:: nl2br_except_pre($str) - - :param string $str: Input string - :returns: Formatted string - :rtype: string - - Converts newlines to <br /> tags unless they appear within <pre> tags. - This method is identical to the native PHP :php:func:`nl2br()` function, except that it ignores <pre> tags. - - Usage example:: - - $string = $this->typography->nl2br_except_pre($string); diff --git a/user_guide_src/source/libraries/unit_testing.rst b/user_guide_src/source/libraries/unit_testing.rst deleted file mode 100644 index 57934cba3..000000000 --- a/user_guide_src/source/libraries/unit_testing.rst +++ /dev/null @@ -1,245 +0,0 @@ -################## -Unit Testing Class -################## - -Unit testing is an approach to software development in which tests are -written for each function in your application. If you are not familiar -with the concept you might do a little googling on the subject. - -CodeIgniter's Unit Test class is quite simple, consisting of an -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 - - <div class="custom-index container"></div> - -****************************** -Using the Unit Testing Library -****************************** - -Initializing the Class -====================== - -Like most other classes in CodeIgniter, the Unit Test class is -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`` - -Running Tests -============= - -Running a test involves supplying a test and an expected result in the -following way: - - $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 -your test, and notes are optional notes. Example:: - - $test = 1 + 1; - - $expected_result = 2; - - $test_name = 'Adds one plus one'; - - $this->unit->run($test, $expected_result, $test_name); - -The expected result you supply can either be a literal match, or a data -type match. Here's an example of a literal:: - - $this->unit->run('Foo', 'Foo'); - -Here is an example of a data type match:: - - $this->unit->run('Foo', 'is_string'); - -Notice the use of "is_string" in the second parameter? This tells the -function to evaluate whether your test is producing a string as the -result. Here is a list of allowed comparison types: - -- is_object -- is_string -- is_bool -- is_true -- is_false -- is_int -- is_numeric -- is_float -- is_double -- is_array -- is_null -- is_resource - -Generating Reports -================== - -You can either display results after each test, or your can run several -tests and generate a report at the end. To show a report directly simply -echo or return the run function:: - - echo $this->unit->run($test, $expected_result); - -To run a full report of all tests, use this:: - - echo $this->unit->report(); - -The report will be formatted in an HTML table for viewing. If you prefer -the raw data you can retrieve an array using:: - - echo $this->unit->result(); - -Strict Mode -=========== - -By default the unit test class evaluates literal matches loosely. -Consider this example:: - - $this->unit->run(1, TRUE); - -The test is evaluating an integer, but the expected result is a boolean. -PHP, however, due to it's loose data-typing will evaluate the above code -as TRUE using a normal equality test:: - - if (1 == TRUE) echo 'This evaluates as true'; - -If you prefer, you can put the unit test class in to strict mode, which -will compare the data type as well as the value:: - - if (1 === TRUE) echo 'This evaluates as FALSE'; - -To enable strict mode use this:: - - $this->unit->use_strict(TRUE); - -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); - -Unit Test Display -================= - -When your unit test results display, the following items show by -default: - -- Test Name (test_name) -- Test Datatype (test_datatype) -- Expected Datatype (res_datatype) -- Result (result) -- File Name (file) -- Line Number (line) -- Any notes you entered for the test (notes) - -You can customize which of these items get displayed by using -$this->unit->set_test_items(). For example, if you only wanted the test name -and the result displayed: - -Customizing displayed tests ---------------------------- - -:: - - $this->unit->set_test_items(array('test_name', 'result')); - -Creating a Template -------------------- - -If you would like your test results formatted differently then the -default you can set your own template. Here is an example of a simple -template. Note the required pseudo-variables:: - - $str = ' - <table border="0" cellpadding="4" cellspacing="1"> - {rows} - <tr> - <td>{item}</td> - <td>{result}</td> - </tr> - {/rows} - </table>'; - - $this->unit->set_template($str); - -.. note:: Your template must be declared **before** running the unit - test process. - -*************** -Class Reference -*************** - -.. php:class:: CI_Unit_test - - .. php: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 - - .. php: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: Test report - :rtype: string - - Runs unit tests. - - .. php:method:: report([$result = array()]) - - :param array $result: Array containing tests results - :returns: Test report - :rtype: string - - Generates a report about already complete tests. - - .. php:method:: use_strict([$state = TRUE]) - - :param bool $state: Strict state flag - :rtype: void - - Enables/disables strict type comparison in tests. - - .. php:method:: active([$state = TRUE]) - - :param bool $state: Whether to enable testing - :rtype: void - - Enables/disables unit testing. - - .. php:method:: result([$results = array()]) - - :param array $results: Tests results list - :returns: Array of raw result data - :rtype: array - - Returns raw tests results data. - - .. php:method:: set_template($template) - - :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 deleted file mode 100644 index 4d38c1d22..000000000 --- a/user_guide_src/source/libraries/uri.rst +++ /dev/null @@ -1,233 +0,0 @@ -######### -URI Class -######### - -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. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -*************** -Class Reference -*************** - -.. php:class:: CI_URI - - .. php: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: 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. - For example, if your full URL is this:: - - http://example.com/index.php/news/local/metro/crime_is_up - - The segment numbers would be this: - - #. news - #. local - #. metro - #. crime_is_up - - 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:: - - $product_id = $this->uri->segment(3, 0); - - It helps avoid having to write code like this:: - - if ($this->uri->segment(3) === FALSE) - { - $product_id = 0; - } - else - { - $product_id = $this->uri->segment(3); - } - - .. php: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: 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 - using CodeIgniter's :doc:`URI Routing <../general/routing>` feature. - - .. php:method:: slash_segment($n[, $where = 'trailing']) - - :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. - If the parameter is not used, a trailing slash added. Examples:: - - $this->uri->slash_segment(3); - $this->uri->slash_segment(3, 'leading'); - $this->uri->slash_segment(3, 'both'); - - Returns: - - #. segment/ - #. /segment - #. /segment/ - - .. php:method:: slash_rsegment($n[, $where = 'trailing']) - - :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 - are using CodeIgniter's :doc:`URI Routing <../general/routing>` - feature. - - .. php:method:: uri_to_assoc([$n = 3[, $default = 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 an associative array of - key/value pairs. Consider this URI:: - - index.php/user/search/name/joe/location/UK/gender/male - - Using this method you can turn the URI into an associative array with - this prototype:: - - [array] - ( - 'name' => 'joe' - 'location' => 'UK' - 'gender' => 'male' - ) - - 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:: - - $array = $this->uri->uri_to_assoc(3); - echo $array['name']; - - 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:: - - $default = array('name', 'gender', 'location', 'type', 'sort'); - $array = $this->uri->uri_to_assoc(3, $default); - - 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. - - 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. - - .. php:method:: ruri_to_assoc([$n = 3[, $default = 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 - CodeIgniter's :doc:`URI Routing <../general/routing>` feature. - - .. php:method:: assoc_to_uri($array) - - :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:: - - $array = array('product' => 'shoes', 'size' => 'large', 'color' => 'red'); - $str = $this->uri->assoc_to_uri($array); - - // Produces: product/shoes/size/large/color/red - - .. php:method:: uri_string() - - :returns: URI string - :rtype: string - - Returns a string with the complete URI. For example, if this is your full URL:: - - http://example.com/index.php/news/local/345 - - The method would return this:: - - news/local/345 - - .. php:method:: ruri_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 - Routing <../general/routing>` feature. - - .. php:method:: total_segments() - - :returns: Count of URI segments - :rtype: int - - Returns the total number of segments. - - .. php:method:: total_rsegments() - - :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 - using CodeIgniter's :doc:`URI Routing <../general/routing>` feature. - - .. php:method:: segment_array() - - :returns: URI segments array - :rtype: array - - Returns an array containing the URI segments. For example:: - - $segs = $this->uri->segment_array(); - - foreach ($segs as $segment) - { - echo $segment; - echo '<br />'; - } - - .. php:method:: rsegment_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 - CodeIgniter's :doc:`URI Routing <../general/routing>` feature. diff --git a/user_guide_src/source/libraries/user_agent.rst b/user_guide_src/source/libraries/user_agent.rst deleted file mode 100644 index a1d969abf..000000000 --- a/user_guide_src/source/libraries/user_agent.rst +++ /dev/null @@ -1,248 +0,0 @@ -################ -User Agent Class -################ - -The User Agent Class provides functions that help identify information -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 - - <div class="custom-index container"></div> - -************************** -Using the User Agent Class -************************** - -Initializing the Class -====================== - -Like most other classes in CodeIgniter, the User Agent class is -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`` - -User Agent Definitions -====================== - -The user agent name definitions are located in a config file located at: -application/config/user_agents.php. You may add items to the various -user agent arrays if needed. - -Example -======= - -When the User Agent class is initialized it will attempt to determine -whether the user agent browsing your site is a web browser, a mobile -device, or a robot. It will also gather the platform information if it -is available. - -:: - - $this->load->library('user_agent'); - - if ($this->agent->is_browser()) - { - $agent = $this->agent->browser().' '.$this->agent->version(); - } - elseif ($this->agent->is_robot()) - { - $agent = $this->agent->robot(); - } - elseif ($this->agent->is_mobile()) - { - $agent = $this->agent->mobile(); - } - else - { - $agent = 'Unidentified User Agent'; - } - - echo $agent; - - echo $this->agent->platform(); // Platform info (Windows, Linux, Mac, etc.) - -*************** -Class Reference -*************** - -.. php:class:: CI_User_agent - - .. php:method:: is_browser([$key = NULL]) - - :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. - :: - - if ($this->agent->is_browser('Safari')) - { - echo 'You are using Safari.'; - } - elseif ($this->agent->is_browser()) - { - echo 'You are using a 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. - - .. php:method:: is_mobile([$key = NULL]) - - :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. - :: - - 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'); - } - - .. php:method:: is_robot([$key = NULL]) - - :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. - - .. 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. - - .. php:method:: is_referral() - - :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. - - .. php:method:: browser() - - :returns: Detected browser or an empty string - :rtype: string - - Returns a string containing the name of the web browser viewing your site. - - .. php:method:: version() - - :returns: Detected browser version or an empty string - :rtype: string - - Returns a string containing the version number of the web browser viewing your site. - - .. php:method:: mobile() - - :returns: Detected mobile device brand or an empty string - :rtype: string - - Returns a string containing the name of the mobile device viewing your site. - - .. php:method:: robot() - - :returns: Detected robot name or an empty string - :rtype: string - - Returns a string containing the name of the robot viewing your site. - - .. php:method:: platform() - - :returns: Detected operating system or an empty string - :rtype: string - - Returns a string containing the platform viewing your site (Linux, Windows, OS X, etc.). - - .. php:method:: referrer() - - :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:: - - if ($this->agent->is_referral()) - { - echo $this->agent->referrer(); - } - - .. php:method:: agent_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:: - - Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.0.4) Gecko/20060613 Camino/1.0.2 - - .. php:method:: accept_lang([$lang = 'en']) - - :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:: - - 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. - - .. php:method:: languages() - - :returns: An array list of accepted languages - :rtype: array - - Returns an array of languages supported by the user agent. - - .. php:method:: accept_charset([$charset = 'utf-8']) - - :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:: - - 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. - - .. php:method:: charsets() - - :returns: An array list of accepted character sets - :rtype: array - - Returns an array of character sets accepted by the user agent. - - .. php:method:: parse($string) - - :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 deleted file mode 100644 index 2fe07c49d..000000000 --- a/user_guide_src/source/libraries/xmlrpc.rst +++ /dev/null @@ -1,582 +0,0 @@ -################################## -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 - - <div class="custom-index container"></div> - -**************** -What is XML-RPC? -**************** - -Quite simply it is a way for two computers to communicate over the -internet using XML. One computer, which we will call the client, sends -an XML-RPC **request** to another computer, which we will call the -server. Once the server receives and processes the request it will send -back a **response** to the client. - -For example, using the MetaWeblog API, an XML-RPC Client (usually a -desktop publishing tool) will send a request to an XML-RPC Server -running on your site. This request might be a new weblog entry being -sent for publication, or it could be a request for an existing entry for -editing. When the XML-RPC Server receives this request it will examine -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 <http://www.xmlrpc.com/>`_ site. - -*********************** -Using the XML-RPC Class -*********************** - -Initializing the Class -====================== - -Like most other classes in CodeIgniter, the XML-RPC and XML-RPCS classes -are initialized in your controller using the $this->load->library -function: - -To load the XML-RPC class you will use:: - - $this->load->library('xmlrpc'); - -Once loaded, the xml-rpc library object will be available using: -$this->xmlrpc - -To load the XML-RPC Server class you will use:: - - $this->load->library('xmlrpc'); - $this->load->library('xmlrpcs'); - -Once loaded, the xml-rpcs library object will be available using: -$this->xmlrpcs - -.. note:: When using the XML-RPC Server class you must load BOTH the - XML-RPC class and the XML-RPC Server class. - -Sending XML-RPC Requests -======================== - -To send a request to an XML-RPC server you must specify the following -information: - -- The URL of the server -- The method on the server you wish to call -- The *request* data (explained below). - -Here is a basic example that sends a simple Weblogs.com ping to the -`Ping-o-Matic <http://pingomatic.com/>`_ - -:: - - $this->load->library('xmlrpc'); - - $this->xmlrpc->server('http://rpc.pingomatic.com/', 80); - $this->xmlrpc->method('weblogUpdates.ping'); - - $request = array('My Photoblog', 'http://www.my-site.com/photoblog/'); - $this->xmlrpc->request($request); - - if ( ! $this->xmlrpc->send_request()) - { - echo $this->xmlrpc->display_error(); - } - -Explanation ------------ - -The above code initializes the XML-RPC class, sets the server URL and -method to be called (weblogUpdates.ping). The request (in this case, the -title and URL of your site) is placed into an array for transportation, -and compiled using the request() function. Lastly, the full request is -sent. If the send_request() method returns false we will display the -error message sent back from the XML-RPC Server. - -Anatomy of a Request -==================== - -An XML-RPC request is simply the data you are sending to the XML-RPC -server. Each piece of data in a request is referred to as a request -parameter. The above example has two parameters: The URL and title of -your site. When the XML-RPC server receives your request, it will look -for parameters it requires. - -Request parameters must be placed into an array for transportation, and -each parameter can be one of seven data types (strings, numbers, dates, -etc.). If your parameters are something other than strings you will have -to include the data type in the request array. - -Here is an example of a simple array with three parameters:: - - $request = array('John', 'Doe', 'www.some-site.com'); - $this->xmlrpc->request($request); - -If you use data types other than strings, or if you have several -different data types, you will place each parameter into its own array, -with the data type in the second position:: - - $request = array( - array('John', 'string'), - array('Doe', 'string'), - array(FALSE, 'boolean'), - array(12345, 'int') - ); - $this->xmlrpc->request($request); - -The `Data Types <#datatypes>`_ section below has a full list of data -types. - -Creating an XML-RPC Server -========================== - -An XML-RPC Server acts as a traffic cop of sorts, waiting for incoming -requests and redirecting them to the appropriate functions for -processing. - -To create your own XML-RPC server involves initializing the XML-RPC -Server class in your controller where you expect the incoming request to -appear, then setting up an array with mapping instructions so that -incoming requests can be sent to the appropriate class and method for -processing. - -Here is an example to illustrate:: - - $this->load->library('xmlrpc'); - $this->load->library('xmlrpcs'); - - $config['functions']['new_post'] = array('function' => 'My_blog.new_entry'); - $config['functions']['update_post'] = array('function' => 'My_blog.update_entry'); - $config['object'] = $this; - - $this->xmlrpcs->initialize($config); - $this->xmlrpcs->serve(); - -The above example contains an array specifying two method requests that -the Server allows. The allowed methods are on the left side of the -array. When either of those are received, they will be mapped to the -class and method on the right. - -The 'object' key is a special key that you pass an instantiated class -object with, which is necessary when the method you are mapping to is -not part of the CodeIgniter super object. - -In other words, if an XML-RPC Client sends a request for the new_post -method, your server will load the My_blog class and call the new_entry -function. If the request is for the update_post method, your server -will load the My_blog class and call the ``update_entry()`` method. - -The function names in the above example are arbitrary. You'll decide -what they should be called on your server, or if you are using -standardized APIs, like the Blogger or MetaWeblog API, you'll use their -function names. - -There are two additional configuration keys you may make use of when -initializing the server class: debug can be set to TRUE in order to -enable debugging, and xss_clean may be set to FALSE to prevent sending -data through the Security library's ``xss_clean()`` method. - -Processing Server Requests -========================== - -When the XML-RPC Server receives a request and loads the class/method -for processing, it will pass an object to that method containing the -data sent by the client. - -Using the above example, if the new_post method is requested, the -server will expect a class to exist with this prototype:: - - class My_blog extends CI_Controller { - - public function new_post($request) - { - - } - } - -The $request variable is an object compiled by the Server, which -contains the data sent by the XML-RPC Client. Using this object you will -have access to the *request parameters* enabling you to process the -request. When you are done you will send a Response back to the Client. - -Below is a real-world example, using the Blogger API. One of the methods -in the Blogger API is ``getUserInfo()``. Using this method, an XML-RPC -Client can send the Server a username and password, in return the Server -sends back information about that particular user (nickname, user ID, -email address, etc.). Here is how the processing function might look:: - - class My_blog extends CI_Controller { - - public function getUserInfo($request) - { - $username = 'smitty'; - $password = 'secretsmittypass'; - - $this->load->library('xmlrpc'); - - $parameters = $request->output_parameters(); - - if ($parameters[1] != $username && $parameters[2] != $password) - { - return $this->xmlrpc->send_error_message('100', 'Invalid Access'); - } - - $response = array( - array( - 'nickname' => array('Smitty', 'string'), - 'userid' => array('99', 'string'), - 'url' => array('http://yoursite.com', 'string'), - 'email' => array('jsmith@yoursite.com', 'string'), - 'lastname' => array('Smith', 'string'), - 'firstname' => array('John', 'string') - ), - 'struct' - ); - - return $this->xmlrpc->send_response($response); - } - } - -Notes: ------- - -The ``output_parameters()`` method retrieves an indexed array -corresponding to the request parameters sent by the client. In the above -example, the output parameters will be the username and password. - -If the username and password sent by the client were not valid, and -error message is returned using ``send_error_message()``. - -If the operation was successful, the client will be sent back a response -array containing the user's info. - -Formatting a Response -===================== - -Similar to *Requests*, *Responses* must be formatted as an array. -However, unlike requests, a response is an array **that contains a -single item**. This item can be an array with several additional arrays, -but there can be only one primary array index. In other words, the basic -prototype is this:: - - $response = array('Response data', 'array'); - -Responses, however, usually contain multiple pieces of information. In -order to accomplish this we must put the response into its own array so -that the primary array continues to contain a single piece of data. -Here's an example showing how this might be accomplished:: - - $response = array( - array( - 'first_name' => array('John', 'string'), - 'last_name' => array('Doe', 'string'), - 'member_id' => array(123435, 'int'), - 'todo_list' => array(array('clean house', 'call mom', 'water plants'), 'array'), - ), - 'struct' - ); - -Notice that the above array is formatted as a struct. This is the most -common data type for responses. - -As with Requests, a response can be one of the seven data types listed -in the `Data Types <#datatypes>`_ section. - -Sending an Error Response -========================= - -If you need to send the client an error response you will use the -following:: - - return $this->xmlrpc->send_error_message('123', 'Requested data not available'); - -The first parameter is the error number while the second parameter is -the error message. - -Creating Your Own Client and Server -=================================== - -To help you understand everything we've covered thus far, let's create a -couple controllers that act as XML-RPC Client and Server. You'll use the -Client to send a request to the Server and receive a response. - -The Client ----------- - -Using a text editor, create a controller called Xmlrpc_client.php. In -it, place this code and save it to your application/controllers/ -folder:: - - <?php - - class Xmlrpc_client extends CI_Controller { - - public function index() - { - $this->load->helper('url'); - $server_url = site_url('xmlrpc_server'); - - $this->load->library('xmlrpc'); - - $this->xmlrpc->server($server_url, 80); - $this->xmlrpc->method('Greetings'); - - $request = array('How is it going?'); - $this->xmlrpc->request($request); - - if ( ! $this->xmlrpc->send_request()) - { - echo $this->xmlrpc->display_error(); - } - else - { - echo '<pre>'; - print_r($this->xmlrpc->display_response()); - echo '</pre>'; - } - } - } - ?> - -.. note:: In the above code we are using a "url helper". You can find more - information in the :doc:`Helpers Functions <../general/helpers>` page. - -The Server ----------- - -Using a text editor, create a controller called Xmlrpc_server.php. In -it, place this code and save it to your application/controllers/ -folder:: - - <?php - - class Xmlrpc_server extends CI_Controller { - - public function index() - { - $this->load->library('xmlrpc'); - $this->load->library('xmlrpcs'); - - $config['functions']['Greetings'] = array('function' => 'Xmlrpc_server.process'); - - $this->xmlrpcs->initialize($config); - $this->xmlrpcs->serve(); - } - - - public function process($request) - { - $parameters = $request->output_parameters(); - - $response = array( - array( - 'you_said' => $parameters[0], - 'i_respond' => 'Not bad at all.' - ), - 'struct' - ); - - return $this->xmlrpc->send_response($response); - } - } - - -Try it! -------- - -Now visit the your site using a URL similar to this:: - - example.com/index.php/xmlrpc_client/ - -You should now see the message you sent to the server, and its response -back to you. - -The client you created sends a message ("How's is going?") to the -server, along with a request for the "Greetings" method. The Server -receives the request and maps it to the ``process()`` method, where a -response is sent back. - -Using Associative Arrays In a Request Parameter -=============================================== - -If you wish to use an associative array in your method parameters you -will need to use a struct datatype:: - - $request = array( - array( - // Param 0 - array('name' => 'John'), - 'struct' - ), - array( - // Param 1 - array( - 'size' => 'large', - 'shape'=>'round' - ), - 'struct' - ) - ); - - $this->xmlrpc->request($request); - -You can retrieve the associative array when processing the request in -the Server. - -:: - - $parameters = $request->output_parameters(); - $name = $parameters[0]['name']; - $size = $parameters[1]['size']; - $shape = $parameters[1]['shape']; - -Data Types -========== - -According to the `XML-RPC spec <http://www.xmlrpc.com/spec>`_ there are -seven types of values that you can send via XML-RPC: - -- *int* or *i4* -- *boolean* -- *string* -- *double* -- *dateTime.iso8601* -- *base64* -- *struct* (contains array of values) -- *array* (contains array of values) - -*************** -Class Reference -*************** - -.. php:class:: CI_Xmlrpc - - .. php:method:: initialize([$config = array()]) - - :param array $config: Configuration data - :rtype: void - - Initializes the XML-RPC library. Accepts an associative array containing your settings. - - .. php: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 - :rtype: void - - Sets the URL and port number of the server to which a request is to be sent:: - - $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); - - .. php:method:: timeout($seconds = 5) - - :param int $seconds: Timeout in seconds - :rtype: void - - Set a time out period (in seconds) after which the request will be canceled:: - - $this->xmlrpc->timeout(6); - - This timeout period will be used both for an initial connection to - the remote server, as well as for getting a response from it. - Make sure you set the timeout before calling ``send_request()``. - - .. php:method:: method($function) - - :param string $function: Method name - :rtype: void - - Sets the method that will be requested from the XML-RPC server:: - - $this->xmlrpc->method('method'); - - Where method is the name of the method. - - .. php:method:: request($incoming) - - :param array $incoming: Request data - :rtype: void - - 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); - - .. php:method:: send_request() - - :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 - :rtype: void - - Enables or disables debugging, which will display a variety of information and error data helpful during development. - - .. php:method:: display_error() - - :returns: Error message string - :rtype: string - - Returns an error message as a string if your request failed for some reason. - :: - - echo $this->xmlrpc->display_error(); - - .. php:method:: display_response() - - :returns: Response - :rtype: mixed - - Returns the response from the remote server once request is received. The response will typically be an associative array. - :: - - $this->xmlrpc->display_response(); - - .. php:method:: send_error_message($number, $message) - - :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. - :: - - return $this->xmlrpc->send_error_message(123, 'Requested data not available'); - - .. method send_response($response) - - :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. - :: - - $response = array( - array( - 'flerror' => array(FALSE, 'boolean'), - 'message' => "Thanks for the ping!" - ), - 'struct' - ); - - return $this->xmlrpc->send_response($response); diff --git a/user_guide_src/source/libraries/zip.rst b/user_guide_src/source/libraries/zip.rst deleted file mode 100644 index 9704d5b1d..000000000 --- a/user_guide_src/source/libraries/zip.rst +++ /dev/null @@ -1,243 +0,0 @@ -################## -Zip Encoding Class -################## - -CodeIgniter's Zip Encoding Class permits you to create Zip archives. -Archives can be downloaded to your desktop or saved to a directory. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -**************************** -Using the Zip Encoding Class -**************************** - -Initializing the Class -====================== - -Like most other classes in CodeIgniter, the Zip class is initialized in -your controller using the $this->load->library function:: - - $this->load->library('zip'); - -Once loaded, the Zip library object will be available using:: - - $this->zip - -Usage Example -============= - -This example demonstrates how to compress a file, save it to a folder on -your server, and download it to your desktop. - -:: - - $name = 'mydata1.txt'; - $data = 'A Data String!'; - - $this->zip->add_data($name, $data); - - // Write the zip file to a folder on your server. Name it "my_backup.zip" - $this->zip->archive('/path/to/directory/my_backup.zip'); - - // Download the file to your desktop. Name it "my_backup.zip" - $this->zip->download('my_backup.zip'); - -*************** -Class Reference -*************** - -.. php:class:: CI_Zip - - .. attribute:: $compression_level = 2 - - The compression level to use. - - It can range from 0 to 9, with 9 being the highest and 0 effectively disabling compression:: - - $this->zip->compression_level = 0; - - .. php:method:: add_data($filepath[, $data = NULL]) - - :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. - - 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 = '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:: - - $data = array( - 'mydata1.txt' => 'A Data String!', - 'mydata2.txt' => 'Another Data String!' - ); - - $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):: - - $name = 'personal/my_bio.txt'; - $data = 'I was born in an elevator...'; - - $this->zip->add_data($name, $data); - - The above example will place my_bio.txt inside a folder called personal. - - .. php:method:: add_dir($directory) - - :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:: - - $this->zip->add_dir('myfolder'); // Creates a directory called "myfolder" - - .. php: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: 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:: - - $path = '/path/to/photo.jpg'; - - $this->zip->read_file($path); - - // 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:: - - $path = '/path/to/photo.jpg'; - - $this->zip->read_file($path, TRUE); - - // 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 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'); - - .. php: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: 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. - All files contained within the supplied path will be encoded, as will any sub-directories contained within it. Example:: - - $path = '/path/to/your/directory/'; - - $this->zip->read_dir($path); - - // Download the file to your desktop. Name it "my_backup.zip" - $this->zip->download('my_backup.zip'); - - By default the Zip archive will place all directories listed in the first parameter - inside the zip. If you want the tree preceding the target directory to be ignored, - you can pass FALSE (boolean) in the second parameter. Example:: - - $path = '/path/to/your/directory/'; - - $this->zip->read_dir($path, FALSE); - - This will create a ZIP with a directory named "directory" inside, then all sub-directories - stored correctly inside that, but will not include the */path/to/your* part of the path. - - .. php:method:: archive($filepath) - - :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 (755 is usually OK). - Example:: - - $this->zip->archive('/path/to/folder/myarchive.zip'); // Creates a file named myarchive.zip - - .. php:method:: download($filename = 'backup.zip') - - :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:: - - $this->zip->download('latest_stuff.zip'); // File will be named "latest_stuff.zip" - - .. 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. - - .. php:method:: get_zip() - - :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:: - - $name = 'my_bio.txt'; - $data = 'I was born in an elevator...'; - - $this->zip->add_data($name, $data); - - $zip_file = $this->zip->get_zip(); - - .. php:method:: clear_data() - - :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:: - - $name = 'my_bio.txt'; - $data = 'I was born in an elevator...'; - - $this->zip->add_data($name, $data); - $zip_file = $this->zip->get_zip(); - - $this->zip->clear_data(); - - $name = 'photo.jpg'; - $this->zip->read_file("/path/to/photo.jpg"); // Read the file's contents - - $this->zip->download('myphotos.zip'); |