diff options
Diffstat (limited to 'user_guide_src/source')
64 files changed, 6417 insertions, 4958 deletions
diff --git a/user_guide_src/source/_themes/eldocs/layout.html b/user_guide_src/source/_themes/eldocs/layout.html index 7f2fe1a34..535c2f194 100644 --- a/user_guide_src/source/_themes/eldocs/layout.html +++ b/user_guide_src/source/_themes/eldocs/layout.html @@ -31,7 +31,7 @@ {%- for cssfile in css_files %} <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" /> {%- endfor %} - + {%- if not embedded %} <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { @@ -46,11 +46,13 @@ <script type="text/javascript" src="{{ pathto(scriptfile, 1) }}"></script> {%- endfor %} + <script type="text/javascript" src="{{ pathto('_static/asset/js/method-toc.js', 1) }}"></script> + {%- if favicon %} <link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1) }}"/> {%- endif %} {%- endif %} - + {%- block linktags %} {%- if hasdoc('about') %} <link rel="author" title="{{ _('About these documents') }}" href="{{ pathto('about') }}" /> @@ -96,7 +98,7 @@ {%- block rootrellink %} <li><a href="{{ pathto(master_doc) }}">User Guide Home</a>{%- if pagename != 'index' %} {{ reldelim1 }}{%- endif %}</li> {%- endblock %} - + {%- for parent in parents %} <li><a href="{{ parent.link|e }}" {% if loop.last %}{{ accesskey("U") }}{% endif %}>{{ parent.title }}</a> {{ reldelim1 }}</li> {%- endfor %} @@ -117,8 +119,8 @@ {% if pagename not in exclude_comments -%} <!-- {user_guide_comments} --> {% endif %} - - {%- block footer %} + + {%- block footer %} <div id="footer"> <p class="top"><a href="#header" title="Return to top">Return to top</a></p> <p><a href="http://{{ project_domain }}/">{{ project }}</a> – Copyright © {{ copyright }}</a></p> diff --git a/user_guide_src/source/_themes/eldocs/static/asset/css/common.css b/user_guide_src/source/_themes/eldocs/static/asset/css/common.css index 5cbb37f94..962380b50 100644 --- a/user_guide_src/source/_themes/eldocs/static/asset/css/common.css +++ b/user_guide_src/source/_themes/eldocs/static/asset/css/common.css @@ -22,7 +22,7 @@ http://opensource.org/licenses/OSL-3.0 Open Software License (OSL 3.0) html, body, h1, h2, h3, h4, h5, h6, -p, ul, ol, li, dl, dd, dt, pre, form, fieldset{ margin: 0; padding: 0; } +p, ul, ol, li, dl, dd, dt, pre, form, fieldset{ margin: 0; padding: 0; } body{ background-color: #F9F9F9; color: #444444; font: normal normal 14px "Helvetica", "Arial", Sans-Serif; } @@ -34,10 +34,10 @@ pre, #table-contents .toctree-wrapper{ font-size: 12px; } dfn, var, -em.dfn, em.var{ - background-color: #FFFDED; - color: #578236; - font-style: italic; +em.dfn, em.var{ + background-color: #FFFDED; + color: #578236; + font-style: italic; padding: 3px; } @@ -53,7 +53,7 @@ h2{ font-size: 24px; font-weight: normal; } h1, h2, h3, h4, h5, h6{ margin-bottom: 20px; } -h2, h3{ border-bottom: 2px solid #EEEEEE; padding: 0 0 3px; } +h2, h3{ border-bottom: 2px solid #EEEEEE; padding: 0 0 3px; } h3{ border-color: #E5E5E5; border-width: 1px; } @@ -62,7 +62,7 @@ h4{ background-color: #FFFDED; display: inline-block; font-size: 18px; margin: 0 h1 a, h2 a{ font-weight: normal; } h1 a, h2 a, h3 a{ text-decoration: none; } - + h3, h5, h6{ font-size: 18px; margin: 20px 0; } h4, h5, h6{ font-size: 14px; } @@ -75,57 +75,67 @@ p, dl, ul, ol{ margin: 20px 0; } li > ol{ margin: 0; margin-left: 40px; } dl > dd{ margin-left: 20px; } - + li > p { margin: 0; } #expressionengine-user-guide li em { font-style: normal; } p, li, dd, dt, pre{ line-height: 1.5; } -table{ +table{ background-color: #F5FBFF; border: 1px solid #C8DEF0; border-collapse: collapse; margin-bottom: 20px; } - th, td{ - border: 0; + th, td{ + border: 0; border-bottom: 1px solid #C8DEF0; - padding: 8px; + padding: 8px; } - - th{ - background-color: #326B95; + + th{ + background-color: #326B95; color: #FFFFFF; - text-align: left; + text-align: left; } - + td{ font-size: 12px; } .descname{ color: #000080; font-weight: bold; } .descclassname{ color: #094776; } - + .class .descname{ font-size: 18px; font-style: italic; } .method .descname{ font-style: normal; } - + .class .property{ color: #094776; } - + .method big, - .method .optional{ color: #094776; padding: 0 4px 0 6px; } - + .method .optional + .function big, + .function .optional{ color: #094776; padding: 0 4px 0 6px; } + .class em, - .method em{ color: #008080; } - - .method dt{ margin: 20px 0; } - - .method table{ margin-bottom: 0; margin-left: 20px; } - + .method em, + .function em{ color: #008080; } + + .method dt, + .function dt{ margin: 20px 0; } + + .method table, + .function table{ margin-bottom: 0; margin-left: 20px; } + .method th, - .method td{ padding: 10px; } - - .method td > ul{ margin: 0; margin-left: 20px; } - .method td.field-body > p { margin: 0; margin-left: 20px; } + .method td, + .function th, + .function td{ padding: 10px; } + + .method td > ul, + .function td > ul{ margin: 0; margin-left: 20px; } + + .method td.field-body > p, + .function td.field-body > p { margin: 0; margin-left: 20px; } a:link, a:visited{ color: #1A5B8D; } @@ -137,7 +147,7 @@ a.headerlink{ visibility: hidden; margin-left: 0.4em; } :hover > a.headerlink { visibility: visible; } -a img{ +a img{ border: 0; outline: 0; } @@ -157,37 +167,38 @@ fieldset{ border: 0; } .highlight-bash, .highlight-perl, .highlight-php, +.highlight-html, .cp-path, -.codeblock{ - background-color: #F9FEFF; - border: 1px solid #C8DEF0; +.codeblock{ + background-color: #F9FEFF; + border: 1px solid #C8DEF0; -moz-box-shadow: 4px 4px 0 rgba(0,0,0,0.03); -webkit-box-shadow: 4px 4px 0 rgba(0,0,0,0.03); box-shadow: 4px 4px 0 rgba(0,0,0,0.03); - margin: 20px 0; - padding: 10px 10px 8px; + margin: 20px 0; + padding: 10px 10px 8px; } .highlight-ci{ background-color: #FEFEFE; border-color: #E5E5E5; } .admonition p{ margin: 0; } - + .codeblock{ margin: 10px 0; } - + .cp-path{ background-color: #FAFFF6; border-color: #D1CDB0; } .important, .note{ background-color: #FFFFF2; border-color: #C8C8A5; } - -.admonition-title{ + +.admonition-title{ float: left; - font-weight: bold; - padding-right: 4px; - text-transform: uppercase; + font-weight: bold; + padding-right: 4px; + text-transform: uppercase; } .admonition-title:after{ content: ': '; } .highlighted{ background-color: #FFF09B; } - + #table-contents{ bottom: 0; left: -520px; @@ -195,7 +206,7 @@ fieldset{ border: 0; } top: 0; } -#table-contents .toctree-wrapper{ +#table-contents .toctree-wrapper{ background-color: #444444; background-color: rgba(0,0,0,0.9); *+background-color: #444444; @@ -209,16 +220,16 @@ fieldset{ border: 0; } } #table-contents .toctree-wrapper ul{margin-bottom: 0; margin-top: 0; } - + #table-contents .toctree-wrapper li{ color: #999999; line-height: 1.7; padding: 1px 0; } - + #table-contents .toctree-l1{ list-style-type: none; } - - #table-contents .toctree-l1 > a{ - background: transparent url(../../asset/img/paper-ico.gif) no-repeat 0 0; - font-size: 14px; + + #table-contents .toctree-l1 > a{ + background: transparent url(../../asset/img/paper-ico.gif) no-repeat 0 0; + font-size: 14px; font-weight: bold; - padding-left: 20px; + padding-left: 20px; } #header a:link, @@ -233,15 +244,15 @@ fieldset{ border: 0; } #content{ background-color: #FFFFFF; padding: 40px 40px 20px; } -#brand{ - background-color: #F5F5F5; - color: #FFFFFF; +#brand{ + background-color: #F5F5F5; + color: #FFFFFF; overflow: hidden; - padding: 10px 20px 13px; + padding: 10px 20px 13px; } #brand > *{ float: left; } - + #brand p{ font-size: 14px; margin: 2px 0 0 5px; } #brand.ci p{ margin-top: 8px; } @@ -250,16 +261,16 @@ fieldset{ border: 0; } #brand.mm{ background-color: #222627; } #brand.el{ background-color: #4A0202; } -#header{ +#header{ background-color: #3B7EB0; border-top: 2px solid #539ECC; - color: #FFFFFF; - overflow: hidden; - padding: 15px 15px 16px 20px; + color: #FFFFFF; + overflow: hidden; + padding: 15px 15px 16px 20px; } #header form{ float: right; overflow: hidden; } - + #header input{ float: left; } #header input[type="text"]{ @@ -271,9 +282,9 @@ fieldset{ border: 0; } padding: 5px; width: 175px; } - + #header input[type="text"]:focus{ background-color: #FFFDED; outline: 0; } - + #header input[type="submit"]{ background: #F0F9FF url(../../asset/img/grades.gif) repeat-x 0 -58px; border: 1px solid #033861; @@ -284,18 +295,18 @@ fieldset{ border: 0; } padding: 5px 10px; text-transform: uppercase; } - + #header input[type="submit"]:hover{ background-position: 0 -83px; } - - #header ul{ + + #header ul{ float: left; list-style-type: none; - margin: 0; + margin: 0; overflow: hidden; } - + #header li{ float: left; margin: 4px 5px 0 0; } - + #footer{ background-color: #F9F9F9; border-top: 1px solid #CCCCCC; padding: 20px; } #footer p{ margin: 0; } @@ -323,8 +334,8 @@ fieldset{ border: 0; } -webkit-box-sizing: border-box; box-sizing: border-box; margin-bottom: 10px; - resize: none; - width: 100%; + resize: none; + width: 100%; } #comment_form input[type="submit"]{ margin-top: 10px; } @@ -350,4 +361,4 @@ fieldset{ border: 0; } h3,h4,h5,h6{ font-size: 14px; } } -#header input[type="submit"], x:-moz-any-link{ padding: 4px 10px; }
\ No newline at end of file +#header input[type="submit"], x:-moz-any-link{ padding: 4px 10px; } diff --git a/user_guide_src/source/_themes/eldocs/static/asset/js/method-toc.js b/user_guide_src/source/_themes/eldocs/static/asset/js/method-toc.js new file mode 100644 index 000000000..a926b3da9 --- /dev/null +++ b/user_guide_src/source/_themes/eldocs/static/asset/js/method-toc.js @@ -0,0 +1,44 @@ +/* modified from http://stackoverflow.com/a/12459801 */ +$(function (){ + var createList = function(selector){ + + var ul = $('<ul>'); + var selected = $(selector); + + if (selected.length === 0){ + return; + } + + selected.clone().each(function (i,e){ + + var p = $(e).children('.descclassname'); + var n = $(e).children('.descname'); + var l = $(e).children('.headerlink'); + + var a = $('<a>'); + a.attr('href',l.attr('href')).attr('title', 'jump to ' + n + '()'); + + a.append(p).append(n); + + var entry = $('<li>').append(a); + ul.append(entry); + }); + return ul; + } + + var c = $('<div>'); + + var ul0 = c.clone().append($('.submodule-index')) + + customIndex = $('.custom-index'); + customIndex.empty(); + customIndex.append(ul0); + + var l = createList('dl.method > dt, dl.function > dt'); + if (l) { + var ul = c.clone() + .append('<h3>Methods / Functions</h3>') + .append(l); + } + customIndex.append(ul); +});
\ No newline at end of file diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst index a5839a2e6..4a54593f0 100644 --- a/user_guide_src/source/changelog.rst +++ b/user_guide_src/source/changelog.rst @@ -65,21 +65,21 @@ Release Date: Not Released - :doc:`Date Helper <helpers/date_helper>` changes include: - - :php:func:`now()` now works with all timezone strings supported by PHP. - - Added an optional third parameter to :php:func:`timespan()` that constrains the number of time units displayed. - - Added an optional parameter to :php:func:`timezone_menu()` that allows more attributes to be added to the generated select tag. + - :func:`now()` now works with all timezone strings supported by PHP. + - Added an optional third parameter to :func:`timespan()` that constrains the number of time units displayed. + - Added an optional parameter to :func:`timezone_menu()` that allows more attributes to be added to the generated select tag. - Deprecated ``standard_date()``, which now just uses the native ``date()`` with `DateTime constants <http://www.php.net/manual/en/class.datetime.php#datetime.constants.types>`_. - - Added function :php:func:`date_range()` that generates a list of dates between a specified period. + - Added function :func:`date_range()` that generates a list of dates between a specified period. - :doc:`URL Helper <helpers/url_helper>` changes include: - - Deprecated *separator* options **dash** and **underscore** for function :php:func:`url_title()` (they are only aliases for '-' and '_' respectively). - - :php:func:`url_title()` will now trim extra dashes from beginning and end. - - :php:func:`anchor_popup()` will now fill the *href* attribute with the URL and its JS code will return FALSE instead. - - Added JS window name support to the :php:func:`anchor_popup()` function. - - Added support (auto-detection) for HTTP/1.1 response codes 303, 307 in :php:func:`redirect()`. - - Changed :php:func:`redirect()` to choose the **refresh** method only on IIS servers, instead of all servers on Windows (when **auto** is used). - - Changed :php:func:`anchor()`, :php:func:`anchor_popup()`, and :php:func:`redirect()` to support protocol-relative URLs (e.g. *//ellislab.com/codeigniter*). + - Deprecated *separator* options **dash** and **underscore** for function :func:`url_title()` (they are only aliases for '-' and '_' respectively). + - :func:`url_title()` will now trim extra dashes from beginning and end. + - :func:`anchor_popup()` will now fill the *href* attribute with the URL and its JS code will return FALSE instead. + - Added JS window name support to the :func:`anchor_popup()` function. + - Added support (auto-detection) for HTTP/1.1 response codes 303, 307 in :func:`redirect()`. + - Changed :func:`redirect()` to choose the **refresh** method only on IIS servers, instead of all servers on Windows (when **auto** is used). + - Changed :func:`anchor()`, :func:`anchor_popup()`, and :func:`redirect()` to support protocol-relative URLs (e.g. *//ellislab.com/codeigniter*). - :doc:`HTML Helper <helpers/html_helper>` changes include: @@ -89,24 +89,24 @@ Release Date: Not Released - :doc:`Inflector Helper <helpers/inflector_helper>` changes include: - - Changed :php:func:`humanize()` to allow passing an input separator as its second parameter. - - Refactored :php:func:`plural()` and :php:func:`singular()` to avoid double pluralization and support more words. + - Changed :func:`humanize()` to allow passing an input separator as its second parameter. + - Refactored :func:`plural()` and :func:`singular()` to avoid double pluralization and support more words. - :doc:`Download Helper <helpers/download_helper>` changes include: - - Added an optional third parameter to :php:func:`force_download()` that enables/disables sending the actual file MIME type in the Content-Type header (disabled by default). - - Added a work-around in :php:func:`force_download()` for a bug Android <= 2.1, where the filename extension needs to be in uppercase. - - Added support for reading from an existing file path by passing NULL as the second parameter to :php:func:`force_download()` (useful for large files and/or safely transmitting binary data). + - Added an optional third parameter to :func:`force_download()` that enables/disables sending the actual file MIME type in the Content-Type header (disabled by default). + - Added a work-around in :func:`force_download()` for a bug Android <= 2.1, where the filename extension needs to be in uppercase. + - Added support for reading from an existing file path by passing NULL as the second parameter to :func:`force_download()` (useful for large files and/or safely transmitting binary data). - :doc:`Form Helper <helpers/form_helper>` changes include: - - :php:func:`form_dropdown()` will now also take an array for unity with other form helpers. - - :php:func:`form_prep()`'s second argument now only accepts a boolean value, which determines whether the value is escaped for a <textarea> or a regular <input> element. + - :func:`form_dropdown()` will now also take an array for unity with other form helpers. + - :func:`form_prep()`'s second argument now only accepts a boolean value, which determines whether the value is escaped for a <textarea> or a regular <input> element. - :doc:`Security Helper <helpers/security_helper>` changes include: - - :php:func:`do_hash()` now uses PHP's native ``hash()`` function (supporting more algorithms) and is deprecated. - - :php:func:`strip_image_tags()` is now an alias for the same method in the :doc:`Security Library <libraries/security>`. + - :func:`do_hash()` now uses PHP's native ``hash()`` function (supporting more algorithms) and is deprecated. + - :func:`strip_image_tags()` is now an alias for the same method in the :doc:`Security Library <libraries/security>`. - :doc:`Smiley Helper <helpers/smiley_helper>` changes include: @@ -116,15 +116,15 @@ Release Date: Not Released - :doc:`File Helper <helpers/file_helper>` changes include: - - :php:func:`set_realpath()` can now also handle file paths as opposed to just directories. - - Added an optional paramater to :php:func:`delete_files()` to enable it to skip deleting files such as *.htaccess* and *index.html*. + - :func:`set_realpath()` can now also handle file paths as opposed to just directories. + - Added an optional paramater to :func:`delete_files()` to enable it to skip deleting files such as *.htaccess* and *index.html*. - Deprecated function ``read_file()`` - it's just an alias for PHP's native ``file_get_contents()``. - :doc:`String Helper <helpers/string_helper>` changes include: - Deprecated function ``repeater()`` - it's just an alias for PHP's native ``str_repeat()``. - Deprecated function ``trim_slashes()`` - it's just an alias for PHP's native ``trim()`` (with a slash as its second argument). - - Deprecated randomization type options **unique** and **encrypt** for funcion :php:func:`random_string()` (they are only aliases for **md5** and **sha1** respectively). + - Deprecated randomization type options **unique** and **encrypt** for funcion :func:`random_string()` (they are only aliases for **md5** and **sha1** respectively). - :doc:`CAPTCHA Helper <helpers/captcha_helper>` changes include: @@ -133,7 +133,7 @@ Release Date: Not Released - Added *filename* to the returned array elements. - :doc:`Directory Helper <helpers/directory_helper>` :func:`directory_map()` will now append ``DIRECTORY_SEPARATOR`` to directory names in the returned array. - - :doc:`Array Helper <helpers/array_helper>` :func:`element()` and :php:func:`elements()` now return NULL instead of FALSE when the required elements don't exist. + - :doc:`Array Helper <helpers/array_helper>` :func:`element()` and :func:`elements()` now return NULL instead of FALSE when the required elements don't exist. - :doc:`Language Helper <helpers/language_helper>` :func:`lang()` now accepts an optional list of additional HTML attributes. - Changed the default tag for use in :doc:`Text Helper <helpers/text_helper>` :func:`highlight_phrase()` to ``<mark>`` (formerly ``<strong>``). - Deprecated the :doc:`Email Helper <helpers/email_helper>` as its ``valid_email()``, ``send_email()`` functions are now only aliases for PHP native functions ``filter_var()`` and ``mail()`` respectively. @@ -284,6 +284,7 @@ Release Date: Not Released - :doc:`Calendar Library <libraries/calendar>` changes include: + - Added method chaining support. - Added configuration to generate days of other months instead of blank cells. - Auto set *next_prev_url* if it is empty and *show_prev_next* is set to TRUE. @@ -331,7 +332,7 @@ Release Date: Not Released - Added option to store raw values instead of CI-formatted ones (APC, Memcache). - Added atomic increment/decrement feature via ``increment()``, ``decrement()``. - - :doc:`Email Library <libraries/email>` changes include: + - :doc:`E-mail Library <libraries/email>` changes include: - Added a custom filename parameter to ``attach()`` as ``$this->email->attach($filename, $disposition, $newname)``. - Added possibility to send attachment as buffer string in ``attach()`` as ``$this->email->attach($buffer, $disposition, $newname, $mime)``. @@ -352,6 +353,7 @@ Release Date: Not Released - :doc:`Pagination Library <libraries/pagination>` changes include: + - Added method chaining support to ``initialize()`` method. - Added support for the anchor "rel" attribute. - Added support for setting custom attributes. - Deprecated usage of the "anchor_class" setting (use the new "attributes" setting instead). @@ -385,7 +387,11 @@ Release Date: Not Released - Added check to detect if robots are pretending to be mobile clients (helps with e.g. Google indexing mobile website versions). - Added method ``parse()`` to allow parsing a custom user-agent string, different from the current visitor's. - - Added support for setting :doc:`Table <libraries/table>` class defaults in a config file. + - :doc:`HTML Table Library <libraries/table>` changes include: + + - Added method chaining support. + - Added support for setting table class defaults in a config file. + - :doc:`Zip Library <libraries/zip>` method ``read_file()`` can now also alter the original file path/name while adding files to an archive. - Core @@ -439,18 +445,18 @@ Release Date: Not Released - Added method ``post_get()`` and changed ``get_post()`` to search in GET data first. Both methods' names now properly match their GET/POST data search priorities. - Changed method ``_fetch_from_array()`` to parse array notation in field name. - Added an option for ``_clean_input_keys()`` to return FALSE instead of terminating the whole script. - - Deprecated the ``is_cli_request()`` method, it is now an alias for the new :php:func:`is_cli()` common function. + - Deprecated the ``is_cli_request()`` method, it is now an alias for the new :func:`is_cli()` common function. - :doc:`Common functions <general/common_functions>` changes include: - - Added function :php:func:`get_mimes()` to return the *application/config/mimes.php* array. - - Added support for HTTP code 303 ("See Other") in :php:func:`set_status_header()`. - - Removed redundant conditional to determine HTTP server protocol in :php:func:`set_status_header()`. + - Added function :func:`get_mimes()` to return the *application/config/mimes.php* array. + - Added support for HTTP code 303 ("See Other") in :func:`set_status_header()`. + - Removed redundant conditional to determine HTTP server protocol in :func:`set_status_header()`. - Changed ``_exception_handler()`` to respect php.ini *display_errors* setting. - - Added function :php:func:`is_https()` to check if a secure connection is used. - - Added function :php:func:`is_cli()` to replace the ``CI_Input::is_cli_request()`` method. - - Added function :php:func:`function_usable()` to work around a bug in `Suhosin <http://www.hardened-php.net/suhosin/>`. - - Removed the third (`$php_error`) from function :php:func:`log_message()`. + - Added function :func:`is_https()` to check if a secure connection is used. + - Added function :func:`is_cli()` to replace the ``CI_Input::is_cli_request()`` method. + - Added function :func:`function_usable()` to work around a bug in `Suhosin <http://www.hardened-php.net/suhosin/>`. + - Removed the third (`$php_error`) argument from function :func:`log_message()`. - :doc:`Output Library <libraries/output>` changes include: @@ -494,134 +500,133 @@ Bug fixes for 3.0 ------------------ - Fixed a bug where ``unlink()`` raised an error if cache file did not exist when you try to delete it. -- Fixed a bug (#181) where a mis-spelling was in the form validation language file. -- Fixed a bug (#159, #163) - :doc:`Query Builder <database/query_builder>` nested transactions didn't work properly due to ``_trans_depth`` not being incremented. +- Fixed a bug (#181) - a typo in the form validation language file. +- Fixed a bug (#159, #163) - :doc:`Query Builder <database/query_builder>` nested transactions didn't work properly due to ``$_trans_depth`` not being incremented. - Fixed a bug (#737, #75) - :doc:`Pagination <libraries/pagination>` anchor class was not set properly when using initialize method. -- Fixed a bug (#419) - :php:func:`auto_link()` didn't recognize URLs that come after a word boundary. +- Fixed a bug (#419) - :doc:`URL Helper <helpers/url_helper>` :func:`auto_link()` didn't recognize URLs that come after a word boundary. - Fixed a bug (#724) - :doc:`Form Validation Library <libraries/form_validation>` rule **is_unique** didn't check if a database connection exists. - Fixed a bug (#647) - :doc:`Zip Library <libraries/zip>` internal method ``_get_mod_time()`` didn't suppress possible "stat failed" errors generated by ``filemtime()``. - Fixed a bug (#157, #174) - :doc:`Image Manipulation Library <libraries/image_lib>` method ``clear()`` didn't completely clear properties. - Fixed a bug where :doc:`Database Forge <database/forge>` method ``create_table()`` with PostgreSQL database could lead to fetching the whole table. -- Fixed a bug (#795) - :doc:`Form Helper <helpers/form_helper>` :php:func:`form_open()` didn't add the default form *method* and *accept-charset* when an empty array is passed to it. -- Fixed a bug (#797) - :php:func:`timespan()` was using incorrect seconds for year and month. -- Fixed a bug in CI_Cart::contents() where if called without a TRUE (or equal) parameter, it would fail due to a typo. -- Fixed a bug (#696) - make oci_execute() calls inside num_rows() non-committing, since they are only there to reset which row is next in line for oci_fetch calls and thus don't need to be committed. +- Fixed a bug (#795) - :doc:`Form Helper <helpers/form_helper>` :func:`form_open()` didn't add the default form *method* and *accept-charset* when an empty array is passed to it. +- Fixed a bug (#797) - :doc:`Date Helper <helpers/date_helper>` :func:`timespan()` was using incorrect seconds for year and month. +- Fixed a bug in :doc:`Cart Library <libraries/cart>` method ``contents()`` where if called without a TRUE (or equal) parameter, it would fail due to a typo. +- Fixed a bug (#696) - make ``oci_execute()`` calls inside ``num_rows()`` non-committing, since they are only there to reset which row is next in line for oci_fetch calls and thus don't need to be committed. - Fixed a bug (#406) - SQLSRV DB driver not returning resource on ``db_pconnect()``. -- Fixed a bug in CI_Image_lib::gd_loaded() where it was possible for the script execution to end or a PHP E_WARNING message to be emitted. +- Fixed a bug in :doc:`Image Manipulation Library <libraries/image_lib>` method ``gd_loaded()`` where it was possible for the script execution to end or a PHP E_WARNING message to be emitted. - Fixed a bug in the :doc:`Pagination library <libraries/pagination>` where when use_page_numbers=TRUE previous link and page 1 link did not have the same url. -- Fixed a bug (#561) - Errors in :doc:`XML-RPC Library <libraries/xmlrpc>` were not properly escaped. -- Fixed a bug (#904) - ``CI_Loader::initialize()`` caused a PHP Fatal error to be triggered if error level E_STRICT is used. -- Fixed a hosting edge case where an empty $_SERVER['HTTPS'] variable would evaluate to 'on'. -- Fixed a bug (#154) - ``CI_Session::sess_update()`` caused the session to be destroyed on pages where multiple AJAX requests were executed at once. -- Fixed a possible bug in ``CI_Input::is_ajax_request()`` where some clients might not send the X-Requested-With HTTP header value exactly as 'XmlHttpRequest'. -- Fixed a bug (#1039) - MySQL's _backup() method failed due to a table name not being escaped. -- Fixed a bug (#1070) - CI_DB_driver::initialize() didn't set a character set if a database is not selected. -- Fixed a bug (#177) - ``CI_Form_validation::set_value()`` didn't set the default value if POST data is NULL. -- Fixed a bug (#68, #414) - Oracle's escape_str() didn't properly escape LIKE wild characters. -- Fixed a bug (#81) - ODBC's list_fields() and field_data() methods skipped the first column due to odbc_field_*() functions' index starting at 1 instead of 0. +- Fixed a bug (#561) - errors in :doc:`XML-RPC Library <libraries/xmlrpc>` were not properly escaped. +- Fixed a bug (#904) - :doc:`Loader Library <libraries/loader>` method ``initialize()`` caused a PHP Fatal error to be triggered if error level E_STRICT is used. +- Fixed a hosting edge case where an empty ``$_SERVER['HTTPS']`` variable would evaluate to 'on'. +- Fixed a bug (#154) - :doc:`Session Library <libraries/sessions>` method ``sess_update()`` caused the session to be destroyed on pages where multiple AJAX requests were executed at once. +- Fixed a possible bug in :doc:`Input Libary <libraries/input>` method ``is_ajax_request()`` where some clients might not send the X-Requested-With HTTP header value exactly as 'XmlHttpRequest'. +- Fixed a bug (#1039) - :doc:`Database Utilities <database/utilities>` internal method ``_backup()`` method failed for the 'mysql' driver due to a table name not being escaped. +- Fixed a bug (#1070) - ``CI_DB_driver::initialize()`` didn't set a character set if a database is not selected. +- Fixed a bug (#177) - :doc:`Form Validation Library <libraries/form_validation>` method ``set_value()`` didn't set the default value if POST data is NULL. +- Fixed a bug (#68, #414) - :Oracle's ``escape_str()`` didn't properly escape LIKE wild characters. +- Fixed a bug (#81) - ODBC's ``list_fields()`` and ``field_data()`` methods skipped the first column due to ``odbc_field_*()`` functions' index starting at 1 instead of 0. - Fixed a bug (#129) - ODBC's ``num_rows()`` method returned -1 in some cases, due to not all subdrivers supporting the ``odbc_num_rows()`` function. -- Fixed a bug (#153) - E_NOTICE being generated by getimagesize() in the :doc:`File Uploading Library <libraries/file_uploading>`. +- Fixed a bug (#153) - E_NOTICE being generated by ``getimagesize()`` in the :doc:`File Uploading Library <libraries/file_uploading>`. - Fixed a bug (#611) - SQLSRV's error handling methods used to issue warnings when there's no actual error. - Fixed a bug (#1036) - ``is_write_type()`` method in the :doc:`Database Library <database/index>` didn't return TRUE for RENAME queries. -- Fixed a bug in PDO's _version() method where it used to return the client version as opposed to the server one. -- Fixed a bug in PDO's insert_id() method where it could've failed if it's used with Postgre versions prior to 8.1. -- Fixed a bug in CUBRID's affected_rows() method where a connection resource was passed to cubrid_affected_rows() instead of a result. -- Fixed a bug (#638) - db_set_charset() ignored its arguments and always used the configured charset instead. +- Fixed a bug in PDO's ``_version()`` method where it used to return the client version as opposed to the server one. +- Fixed a bug in PDO's ``insert_id()`` method where it could've failed if it's used with Postgre versions prior to 8.1. +- Fixed a bug in CUBRID's ``affected_rows()`` method where a connection resource was passed to ``cubrid_affected_rows()`` instead of a result. +- Fixed a bug (#638) - ``db_set_charset()`` ignored its arguments and always used the configured charset instead. - Fixed a bug (#413) - Oracle's error handling methods used to only return connection-related errors. -- Fixed a bug (#1101) - MySQL/MySQLi result method field_data() was implemented as if it was handling a DESCRIBE result instead of the actual result set. -- Fixed a bug in Oracle's :doc:`Database Forge Class <database/forge>` method _create_table() where it failed with AUTO_INCREMENT as it's not supported. -- Fixed a bug (#1080) - When using the SMTP protocol, the :doc:`Email Library <libraries/email>` send() method was returning TRUE even if the connection/authentication against the server failed. -- Fixed a bug (#306) - ODBC's insert_id() method was calling non-existent function odbc_insert_id(), which resulted in a fatal error. -- Fixed a bug in Oracle's DB_result class where the cursor id passed to it was always NULL. -- Fixed a bug (#64) - Regular expression in DB_query_builder.php failed to handle queries containing SQL bracket delimiters in the join condition. -- Fixed a bug in the :doc:`Session Library <libraries/sessions>` where a PHP E_NOTICE error was triggered by _unserialize() due to results from databases such as MSSQL and Oracle being space-padded on the right. -- Fixed a bug (#501) - set_rules() to check if the request method is not 'POST' before aborting, instead of depending on count($_POST) in the :doc:`Form Validation Library <libraries/form_validation>`. -- Fixed a bug (#136) - PostgreSQL, MySQL and MySQLi's escape_str() method didn't properly escape LIKE wild characters. -- Fixed a bug in the library loader where some PHP versions wouldn't execute the class constructor. +- Fixed a bug (#1101) - :doc:`Database Result <database/results>` method ``field_data()`` for 'mysql', 'mysqli' drivers was implemented as if it was handling a DESCRIBE result instead of the actual result set. +- Fixed a bug in Oracle's :doc:`Database Forge <database/forge>` method ``_create_table()`` where it failed with AUTO_INCREMENT as it's not supported. +- Fixed a bug (#1080) - when using the SMTP protocol, :doc:`Email Library <libraries/email>` method ``send()`` was returning TRUE even if the connection/authentication against the server failed. +- Fixed a bug (#306) - ODBC's ``insert_id()`` method was calling non-existent function ``odbc_insert_id()``, which resulted in a fatal error. +- Fixed a bug in Oracle's :doc:`Database Result <database/results>` implementation where the cursor ID passed to it was always NULL. +- Fixed a bug (#64) - Regular expression in *DB_query_builder.php* failed to handle queries containing SQL bracket delimiters in the JOIN condition. +- Fixed a bug in the :doc:`Session Library <libraries/sessions>` where a PHP E_NOTICE error was triggered by ``_unserialize()`` due to results from databases such as MSSQL and Oracle being space-padded on the right. +- Fixed a bug (#501) - :doc:`Form Validation Library <libraries/form_validation>` method ``set_rules()`` depended on ``count($_POST)`` instead of actually checking if the request method 'POST' before aborting. +- Fixed a bug (#136) - PostgreSQL and MySQL's ``escape_str()`` method didn't properly escape LIKE wild characters. +- Fixed a bug in :doc:`Loader Library <libraries/loader>` method ``library()`` where some PHP versions wouldn't execute the class constructor. - Fixed a bug (#88) - An unexisting property was used for configuration of the Memcache cache driver. -- Fixed a bug (#14) - create_database() method in the :doc:`Database Forge Library <database/forge>` didn't utilize the configured database character set. -- Fixed a bug (#23, #1238) - delete_all() in the `Database Caching Library <database/caching>` used to delete .htaccess and index.html files, which is a potential security risk. -- Fixed a bug in :doc:`Trackback Library <libraries/trackback>` method validate_url() where it didn't actually do anything, due to input not being passed by reference. -- Fixed a bug (#11, #183, #863) - CI_Form_validation::_execute() silently continued to the next rule, if a rule method/function is not found. +- Fixed a bug (#14) - :doc:`Database Forge <database/forge>` method ``create_database()`` didn't utilize the configured database character set. +- Fixed a bug (#23, #1238) - :doc:`Database Caching <database/caching>` method ``delete_all()`` used to delete .htaccess and index.html files, which is a potential security risk. +- Fixed a bug in :doc:`Trackback Library <libraries/trackback>` method ``validate_url()`` where it didn't actually do anything, due to input not being passed by reference. +- Fixed a bug (#11, #183, #863) - :doc:`Form Validation Library <libraries/form_validation>` method ``_execute()`` silently continued to the next rule, if a rule method/function is not found. - Fixed a bug (#122) - routed URI string was being reported incorrectly in sub-directories. -- Fixed a bug (#1242) - read_dir() in the :doc:`Zip Library <libraries/zip>` wasn't compatible with Windows. -- Fixed a bug (#306) - ODBC driver didn't have an _insert_batch() method, which resulted in fatal error being triggered when insert_batch() is used with it. -- Fixed a bug in MSSQL and SQLSrv's _truncate() where the TABLE keyword was missing. -- Fixed a bug in PDO's trans_commit() method where it failed due to an erroneous property name. -- Fixed a bug (#798) - update() used to ignore LIKE conditions that were set with like(). -- Fixed a bug in Oracle's and MSSQL's delete() methods where an erroneous SQL statement was generated when used with limit(). -- Fixed a bug in SQLSRV's delete() method where like() and limit() conditions were ignored. +- Fixed a bug (#1241) - :doc:`Zip Library <libraries/zip>` method ``read_dir()`` wasn't compatible with Windows. +- Fixed a bug (#306) - ODBC driver didn't have an ``_insert_batch()`` method, which resulted in fatal error being triggered when ``insert_batch()`` is used with it. +- Fixed a bug in MSSQL and SQLSrv's ``_truncate()`` where the TABLE keyword was missing. +- Fixed a bug in PDO's ``trans_commit()`` method where it failed due to an erroneous property name. +- Fixed a bug (#798) - :doc:`Query Builder <database/query_builder>` method ``update()`` used to ignore LIKE conditions that were set with ``like()``. +- Fixed a bug in Oracle's and MSSQL's ``delete()`` methods where an erroneous SQL statement was generated when used with ``limit()``. +- Fixed a bug in SQLSRV's ``delete()`` method where ``like()`` and ``limit()`` conditions were ignored. - Fixed a bug (#1265) - Database connections were always closed, regardless of the 'pconnect' option value. - Fixed a bug (#128) - :doc:`Language Library <libraries/language>` did not correctly keep track of loaded language files. -- Fixed a bug (#1242) - Added Windows path compatibility to function read_dir of ZIP library. -- Fixed a bug (#1349) - get_extension() in the :doc:`File Uploading Library <libraries/file_uploading>` returned the original filename when it didn't have an actual extension. -- Fixed a bug (#1273) - E_NOTICE being generated by :doc:`Query Builder <database/query_builder>`'s set_update_batch() method. -- Fixed a bug (#44, #110) - :doc:`Upload library <libraries/file_uploading>`'s clean_file_name() method didn't clear '!' and '#' characters. -- Fixed a bug (#121) - ``CI_DB_result::row()`` returned an array when there's no actual result to be returned. -- Fixed a bug (#319) - SQLSRV's affected_rows() method failed due to a scrollable cursor being created for write-type queries. -- Fixed a bug (#356) - PostgreSQL driver didn't have an _update_batch() method, which resulted in fatal error being triggered when update_batch() is used with it. +- Fixed a bug (#1349) - :doc:`File Uploading Library <libraries/file_uploading>` method ``get_extension()`` returned the original filename when it didn't have an actual extension. +- Fixed a bug (#1273) - :doc:`Query Builder <database/query_builder>` method ``set_update_batch()`` generated an E_NOTICE message. +- Fixed a bug (#44, #110) - :doc:`File Uploading Library <libraries/file_uploading>` method ``clean_file_name()`` didn't clear '!' and '#' characters. +- Fixed a bug (#121) - :doc:`Database Results <database/results>` method ``row()`` returned an array when there's no actual result to be returned. +- Fixed a bug (#319) - SQLSRV's ``affected_rows()`` method failed due to a scrollable cursor being created for write-type queries. +- Fixed a bug (#356) - :doc:`Database <database/index>` driver 'postgre' didn't have an ``_update_batch()`` method, which resulted in fatal error being triggered when ``update_batch()`` is used with it. - Fixed a bug (#784, #862) - :doc:`Database Forge <database/forge>` method ``create_table()`` failed on SQLSRV/MSSQL when used with 'IF NOT EXISTS'. -- Fixed a bug (#1419) - libraries/Driver.php had a static variable that was causing an error. -- Fixed a bug (#1411) - the :doc:`Email library <libraries/email>` used its own short list of MIMEs instead the one from config/mimes.php. -- Fixed a bug where the magic_quotes_runtime setting wasn't turned off for PHP 5.3 (where it is indeed deprecated, but not non-existent). -- Fixed a bug (#666) - :doc:`Output library <libraries/output>`'s set_content_type() method didn't set the document charset. +- Fixed a bug (#1419) - :doc:`Driver Library <general/creating_drivers>` had a static variable that was causing an error. +- Fixed a bug (#1411) - the :doc:`Email Library <libraries/email>` used its own short list of MIMEs instead the one from *config/mimes.php*. +- Fixed a bug where php.ini setting *magic_quotes_runtime* wasn't turned off for PHP 5.3 (where it is indeed deprecated, but not non-existent). +- Fixed a bug (#666) - :doc:`Output Library <libraries/output>` method ``set_content_type()`` didn't set the document charset. - Fixed a bug (#784, #861) - :doc:`Database Forge <database/forge>` method ``create_table()`` used to accept constraints for MSSQL/SQLSRV integer-type columns. -- Fixed a bug (#706) - SQLSRV/MSSSQL didn't escape field names. -- Fixed a bug (#1452) - ``protect_identifiers()`` didn't properly detect identifiers with spaces in their names. -- Fixed a bug where ``protect_identifiers()`` ignored its extra arguments when the value passed to it is an array. -- Fixed a bug where ``_has_operator()`` didn't detect BETWEEN. -- Fixed a bug in :doc:`Query Builder <database/query_builder>`'s ``join()`` method where it failed with identifiers containing dashes. +- Fixed a bug (#706) - SQLSRV/MSSSQL :doc:`Database <database/index>` drivers didn't escape field names. +- Fixed a bug (#1452) - :doc:`Query Builder <database/query_builder>` method ``protect_identifiers()`` didn't properly detect identifiers with spaces in their names. +- Fixed a bug where :doc:`Query Builder <database/query_builder>` method ``protect_identifiers()`` ignored its extra arguments when the value passed to it is an array. +- Fixed a bug where :doc:`Query Builder <database/query_builder>` internal method ``_has_operator()`` didn't detect BETWEEN. +- Fixed a bug where :doc:`Query Builder <database/query_builder>` method ``join()`` failed with identifiers containing dashes. - Fixed a bug (#1264) - :doc:`Database Forge <database/forge>` and :doc:`Database Utilities <database/utilities>` didn't update/reset the databases and tables list cache when a table or a database is created, dropped or renamed. -- Fixed a bug (#7) - :doc:`Query Builder <database/query_builder>`'s ``join()`` method only escaped one set of conditions. -- Fixed a bug (#1321) - Core Exceptions class couldn't find the errors/ folder in some cases. -- Fixed a bug (#1202) - :doc:`Encryption Library <libraries/encryption>` encode_from_legacy() didn't set back the encrypt mode on failure. -- Fixed a bug (#145) - compile_binds() failed when the bind marker was present in a literal string within the query. -- Fixed a bug in protect_identifiers() where if passed along with the field names, operators got escaped as well. -- Fixed a bug (#10) - :doc:`URI Library <libraries/uri>` internal method _detect_uri() failed with paths containing a colon. -- Fixed a bug (#1387) - :doc:`Query Builder <database/query_builder>`'s from() method didn't escape table aliases. -- Fixed a bug (#520) - :doc:`Date Helper <helpers/date_helper>` function nice_date() failed when the optional second parameter is not passed. +- Fixed a bug (#7) - :doc:`Query Builder <database/query_builder>` method ``join()`` only escaped one set of conditions. +- Fixed a bug (#1321) - ``CI_Exceptions`` couldn't find the *errors/* directory in some cases. +- Fixed a bug (#1202) - :doc:`Encryption Library <libraries/encryption>` ``encode_from_legacy()`` didn't set back the encrypt mode on failure. +- Fixed a bug (#145) - :doc:`Database Class <database/index>` method ``compile_binds()`` failed when the bind marker was present in a literal string within the query. +- Fixed a bug in :doc:`Query Builder <database/query_builder>` method ``protect_identifiers()`` where if passed along with the field names, operators got escaped as well. +- Fixed a bug (#10) - :doc:`URI Library <libraries/uri>` internal method ``_detect_uri()`` failed with paths containing a colon. +- Fixed a bug (#1387) - :doc:`Query Builder <database/query_builder>` method ``from()`` didn't escape table aliases. +- Fixed a bug (#520) - :doc:`Date Helper <helpers/date_helper>` function :func:``nice_date()`` failed when the optional second parameter is not passed. - Fixed a bug (#167) - ``$config['permitted_uri_chars']`` didn't affect URL-encoded characters. -- Fixed a bug (#318) - :doc:`Profiling <general/profiling>` setting *query_toggle_count* was not settable as described in the manual. +- Fixed a bug (#318) - :doc:`Profiling Library <general/profiling>` setting *query_toggle_count* was not settable as described in the manual. - Fixed a bug (#938) - :doc:`Config Library <libraries/config>` method ``site_url()`` added a question mark to the URL string when query strings are enabled even if it already existed. - Fixed a bug (#999) - :doc:`Config Library <libraries/config>` method ``site_url()`` always appended ``$config['url_suffix']`` to the end of the URL string, regardless of whether a query string exists in it. -- Fixed a bug where :doc:`URL Helper <helpers/url_helper>` function ``anchor_popup()`` ignored the attributes argument if it is not an array. +- Fixed a bug where :doc:`URL Helper <helpers/url_helper>` function :func:`anchor_popup()` ignored the attributes argument if it is not an array. - Fixed a bug (#1328) - :doc:`Form Validation Library <libraries/form_validation>` didn't properly check the type of the form fields before processing them. - Fixed a bug (#79) - :doc:`Form Validation Library <libraries/form_validation>` didn't properly validate array fields that use associative keys or have custom indexes. - Fixed a bug (#427) - :doc:`Form Validation Library <libraries/form_validation>` method ``strip_image_tags()`` was an alias to a non-existent method. - Fixed a bug (#1545) - :doc:`Query Builder <database/query_builder>` method ``limit()`` wasn't executed properly under Oracle. -- Fixed a bug (#1551) - :doc:`Date Helper <helpers/date_helper>` function ``standard_date()`` didn't properly format *W3C* and *ATOM* standard dates. -- Fixed a bug in :doc:`Query Builder <database/query_builder>` method join() where literal values were escaped as if they were fields. +- Fixed a bug (#1551) - :doc:`Date Helper <helpers/date_helper>` function :func:`standard_date()` didn't properly format *W3C* and *ATOM* standard dates. +- Fixed a bug where :doc:`Query Builder <database/query_builder>` method ``join()`` escaped literal values as if they were fields. - Fixed a bug (#135) - PHP Error logging was impossible without the errors being displayed. -- Fixed a bug (#1613) - :doc:`Form Helper <helpers/form_helper>` functions ``form_multiselect()``, ``form_dropdown()`` didn't properly handle empty array option groups. +- Fixed a bug (#1613) - :doc:`Form Helper <helpers/form_helper>` functions :func:`form_multiselect()`, :func:`form_dropdown()` didn't properly handle empty array option groups. - Fixed a bug (#1605) - :doc:`Pagination Library <libraries/pagination>` produced incorrect *previous* and *next* link values. - Fixed a bug in SQLSRV's ``affected_rows()`` method where an erroneous function name was used. - Fixed a bug (#1000) - Change syntax of ``$view_file`` to ``$_ci_view_file`` to prevent being overwritten by application. -- Fixed a bug (#1757) - :doc:`Directory Helper <helpers/directory_helper>` function ``directory_map()`` was skipping files and directories named *0*. +- Fixed a bug (#1757) - :doc:`Directory Helper <helpers/directory_helper>` function :func:`directory_map()` was skipping files and directories named '0'. - Fixed a bug (#1789) - :doc:`Database Library <database/index>` method ``escape_str()`` escaped quote characters in LIKE conditions twice under MySQL. - Fixed a bug (#395) - :doc:`Unit Testing Library <libraries/unit_testing>` method ``result()`` didn't properly check array result columns when called from ``report()``. -- Fixed a bug (#1692) - :doc:`Database Library <database/index>` method ``display_error()`` didn't properly trace the possible error source on Windows systems. -- Fixed a bug (#1745) - ``is_write_type()`` method in the :doc:`Database Library <database/index>` didn't return TRUE for LOAD queries. -- Fixed a bug (#1765) - :doc:`Database Library <database/index>` didn't properly detect connection errors for MySQLi. +- Fixed a bug (#1692) - :doc:`Database Class <database/index>` method ``display_error()`` didn't properly trace the possible error source on Windows systems. +- Fixed a bug (#1745) - :doc:`Database Class <database/index>` method ``is_write_type()`` didn't return TRUE for LOAD queries. +- Fixed a bug (#1765) - :doc:`Database Class <database/index>` didn't properly detect connection errors for the 'mysqli' driver. - Fixed a bug (#1257) - :doc:`Query Builder <database/query_builder>` used to (unnecessarily) group FROM clause contents, which breaks certain queries and is invalid for some databases. - Fixed a bug (#1709) - :doc:`Email <libraries/email>` headers were broken when using long email subjects and \r\n as CRLF. -- Fixed a bug where ``MB_ENABLED`` was only declared if ``UTF8_ENABLED`` was set to TRUE. +- Fixed a bug where ``MB_ENABLED`` constant was only declared if ``UTF8_ENABLED`` was set to TRUE. - Fixed a bug where the :doc:`Session Library <libraries/sessions>` accepted cookies with *last_activity* values being in the future. - Fixed a bug (#1897) - :doc:`Email Library <libraries/email>` triggered PHP E_WARNING errors when *mail* protocol used and ``to()`` is never called. - Fixed a bug (#1409) - :doc:`Email Library <libraries/email>` didn't properly handle multibyte characters when applying Q-encoding to headers. -- Fixed a bug where :doc:`Email Library <libraries/email>` didn't honor its *wordwrap* setting while handling alternative messages. +- Fixed a bug where :doc:`Email Library <libraries/email>` ignored its *wordwrap* setting while handling alternative messages. - Fixed a bug (#1476, #1909) - :doc:`Pagination Library <libraries/pagination>` didn't take into account actual routing when determining the current page. - Fixed a bug (#1766) - :doc:`Query Builder <database/query_builder>` didn't always take into account the *dbprefix* setting. - Fixed a bug (#779) - :doc:`URI Class <libraries/uri>` didn't always trim slashes from the *uri_string* as shown in the documentation. - Fixed a bug (#134) - :doc:`Database Caching <database/caching>` method ``delete_cache()`` didn't work in some cases due to *cachedir* not being initialized properly. - Fixed a bug (#191) - :doc:`Loader Library <libraries/loader>` ignored attempts for (re)loading databases to ``get_instance()->db`` even when the old database connection is dead. - Fixed a bug (#1255) - :doc:`User Agent Library <libraries/user_agent>` method ``is_referral()`` only checked if ``$_SERVER['HTTP_REFERER']`` exists. -- Fixed a bug (#1146) - :doc:`Download Helper <helpers/download_helper>` function ``force_download()`` incorrectly sent *Cache-Control* directives *pre-check* and *post-check* to Internet Explorer. +- Fixed a bug (#1146) - :doc:`Download Helper <helpers/download_helper>` function :func:`force_download()` incorrectly sent *Cache-Control* directives *pre-check* and *post-check* to Internet Explorer. - Fixed a bug (#1811) - :doc:`URI Library <libraries/uri>` didn't properly cache segments for ``uri_to_assoc()`` and ``ruri_to_assoc()``. - Fixed a bug (#1506) - :doc:`Form Helpers <helpers/form_helper>` set empty *name* attributes. - Fixed a bug (#59) - :doc:`Query Builder <database/query_builder>` method ``count_all_results()`` ignored the DISTINCT clause. - Fixed a bug (#1624) - :doc:`Form Validation Library <libraries/form_validation>` rule **matches** didn't property handle array field names. -- Fixed a bug (#1630) - :doc:`Form Helper <helpers/form_helper>` function ``set_value()`` didn't escape HTML entities. -- Fixed a bug (#142) - :doc:`Form Helper <helpers/form_helper>` function ``form_dropdown()`` didn't escape HTML entities in option values. +- Fixed a bug (#1630) - :doc:`Form Helper <helpers/form_helper>` function :func:`set_value()` didn't escape HTML entities. +- Fixed a bug (#142) - :doc:`Form Helper <helpers/form_helper>` function :func:`form_dropdown()` didn't escape HTML entities in option values. - Fixed a bug (#50) - :doc:`Session Library <libraries/sessions>` unnecessarily stripped slashed from serialized data, making it impossible to read objects in a namespace. - Fixed a bug (#658) - :doc:`Routing <general/routing>` wildcard **:any** didn't work as advertised and matched multiple URI segments instead of all characters within a single segment. - Fixed a bug (#1938) - :doc:`Email Library <libraries/email>` removed multiple spaces inside a pre-formatted plain text message. @@ -630,18 +635,18 @@ Bug fixes for 3.0 - Fixed a bug - :doc:`Routing Library <general/routing>` didn't properly handle *default_controller* in a subdirectory when a method is also specified. - Fixed a bug (#953) - :doc:`post_controller_constructor hook <general/hooks>` wasn't called with a *404_override*. - Fixed a bug (#1220) - :doc:`Profiler Library <general/profiling>` didn't display information for database objects that are instantiated inside models. -- Fixed a bug (#1978) - :doc:`Directory Helper <helpers/directory_helper>` function :php:func:`directory_map()`'s return array didn't make a distinction between directories and file indexes when a directory with a numeric name is present. +- Fixed a bug (#1978) - :doc:`Directory Helper <helpers/directory_helper>` function :func:`directory_map()`'s return array didn't make a distinction between directories and file indexes when a directory with a numeric name is present. - Fixed a bug (#777) - :doc:`Loader Library <libraries/loader>` didn't look for helper extensions in added package paths. - Fixed a bug (#18) - :doc:`APC Cache <libraries/caching>` driver didn't (un)serialize data, resulting in failure to store objects. - Fixed a bug (#188) - :doc:`Unit Testing Library <libraries/unit_testing>` filled up logs with error messages for non-existing language keys. - Fixed a bug (#113) - :doc:`Form Validation Library <libraries/form_validation>` didn't properly handle empty fields that were specified as an array. - Fixed a bug (#2061) - :doc:`Routing Class <general/routing>` didn't properly sanitize directory, controller and function triggers with **enable_query_strings** set to TRUE. - Fixed a bug - SQLSRV didn't support ``escape_like_str()`` or escaping an array of values. -- Fixed a bug - :doc:`Database Results <database/results>` method ``list_fields()`` didn't reset its field pointer for the *mysql*, *mysqli* and *mssql* drivers. +- Fixed a bug - :doc:`Database Results <database/results>` method ``list_fields()`` didn't reset its field pointer for the 'mysql', 'mysqli' and 'mssql' drivers. - Fixed a bug (#73) - :doc:`Security Library <libraries/security>` method ``sanitize_filename()`` could be tricked by an XSS attack. - Fixed a bug (#2211) - :doc:`Migration Library <libraries/migration>` extensions couldn't execute ``CI_Migration::__construct()``. -- Fixed a bug (#2255) - :doc:`Email Library <libraries/email>` didn't apply ``smtp_timeout`` to socket reads and writes. -- Fixed a bug (#2239) - :doc:`Email Library <libraries/email>` improperly handled the Subject when used with ``bcc_batch_mode`` resulting in E_WARNING messages and an empty Subject. +- Fixed a bug (#2255) - :doc:`Email Library <libraries/email>` didn't apply *smtp_timeout* to socket reads and writes. +- Fixed a bug (#2239) - :doc:`Email Library <libraries/email>` improperly handled the Subject when used with *bcc_batch_mode* resulting in E_WARNING messages and an empty Subject. - Fixed a bug (#2234) - :doc:`Query Builder <database/query_builder>` didn't reset JOIN cache for write-type queries. - Fixed a bug (#2298) - :doc:`Database Results <database/results>` method ``next_row()`` kept returning the last row, allowing for infinite loops. - Fixed a bug (#2236, #2639) - :doc:`Form Helper <helpers/form_helper>` functions :func:`set_value()`, :func:`set_select()`, :func:`set_radio()`, :func:`set_checkbox()` didn't parse array notation for keys if the rule was not present in the :doc:`Form Validation Library <libraries/form_validation>`. @@ -651,20 +656,20 @@ Bug fixes for 3.0 - Fixed a bug (#2380) - :doc:`URI Routing <general/routing>` method ``fetch_method()`` returned 'index' if the requested method name matches its controller name. - Fixed a bug (#2388) - :doc:`Email Library <libraries/email>` used to ignore attachment errors, resulting in broken emails being sent. - Fixed a bug (#2498) - :doc:`Form Validation Library <libraries/form_validation>` rule **valid_base64** only checked characters instead of actual validity. -- Fixed a bug (#2425) - OCI8 :doc:`database <database/index>` driver's method ``stored_procedure()`` didn't log an error unless **db_debug** was set to TRUE. -- Fixed a bug (#2490) - :doc:`Database Class <database/queries>` method ``query()`` returning boolean instead of a result object when the PostgreSQL-specific *RETURNING* clause is used. +- Fixed a bug (#2425) - OCI8 :doc:`database <database/index>` driver method ``stored_procedure()`` didn't log an error unless **db_debug** was set to TRUE. +- Fixed a bug (#2490) - :doc:`Database Class <database/queries>` method ``query()`` returning boolean instead of a result object for PostgreSQL-specific *INSERT INTO ... RETURNING* statements. - Fixed a bug (#249) - :doc:`Cache Library <libraries/caching>` didn't properly handle Memcache(d) configurations with missing options. -- Fixed a bug (#180) - :php:func:`config_item()` didn't take into account run-time configuration changes. +- Fixed a bug (#180) - :func:`config_item()` didn't take into account run-time configuration changes. - Fixed a bug (#2551) - :doc:`Loader Library <libraries/loader>` method ``library()`` didn't properly check if a class that is being loaded already exists. -- Fixed a bug (#2560) - :doc:`Form Helper <helpers/form_helper>` function :php:func:`form_open()` set the 'method="post"' attribute only if the passed attributes equaled an empty string. +- Fixed a bug (#2560) - :doc:`Form Helper <helpers/form_helper>` function :func:`form_open()` set the 'method="post"' attribute only if the passed attributes equaled an empty string. - Fixed a bug (#2585) - :doc:`Query Builder <database/query_builder>` methods ``min()``, ``max()``, ``avg()``, ``sum()`` didn't escape field names. - Fixed an edge case (#2583) in the :doc:`Email Library <libraries/email>` where `Suhosin <http://www.hardened-php.net/suhosin/>` blocked messages sent via ``mail()`` due to trailing newspaces in headers. -- Fixed a bug (#2590) - :php:func:`log_message()` didn't actually cache the ``CI_Log`` class instance. -- Fixed a bug (#2609) - :php:func:`get_config()` optional argument was only effective on first function call. Also, it can now add items, in addition to updating existing items. +- Fixed a bug (#2590) - :doc:`Common function <general/common_functions>` :func:`log_message()` didn't actually cache the ``CI_Log`` class instance. +- Fixed a bug (#2609) - :doc:`Common function <general/common_functions>` :func:`get_config()` optional argument was only effective on first function call. Also, it can now add items, in addition to updating existing items. - Fixed a bug in the 'postgre' :doc:`database <database/index>` driver where the connection ID wasn't passed to ``pg_escape_string()``. - Fixed a bug (#33) - Script execution was terminated when an invalid cookie key was encountered. -- Fixed a bug (#2681) - ``CI_Security::entity_decode()`` used the `PREG_REPLACE_EVAL` flag, which is deprecated since PHP 5.5. -- Fixed a bug (#2691) - nested transactions could end in a deadlock when an error is encountered with *db_debug* set to TRUE. +- Fixed a bug (#2681) - :doc:`Security Library <libraries/security>` method ``entity_decode()`` used the `PREG_REPLACE_EVAL` flag, which is deprecated since PHP 5.5. +- Fixed a bug (#2691) - nested :doc:`database <database/index>` transactions could end in a deadlock when an error is encountered with *db_debug* set to TRUE. - Fixed a bug (#2515) - ``_exception_handler()`` used to send the 200 "OK" HTTP status code and didn't stop script exection even on fatal errors. - Fixed a bug - Redis :doc:`Caching <libraries/caching>` driver didn't handle connection failures properly. - Fixed a bug (#2756) - :doc:`Database Class <database/index>` executed the MySQL-specific `SET SESSION sql_mode` query for all drivers when the 'stricton' option is set. @@ -673,16 +678,16 @@ Bug fixes for 3.0 - Fixed a bug (#2268) - :doc:`Security Library <libraries/security>` didn't properly match JavaScript events. - Fixed a bug (#2143) - :doc:`Form Validation Library <libraries/form_validation>` didn't check for rule groups named in a *controller/method* manner when trying to load from a config file. - Fixed a bug (#2762) - :doc:`Hooks Class <general/hooks>` didn't properly check if the called class/function exists. -- Fixed a bug (#148) - while sanitizing input data, ``CI_Input::_clean_input_data()`` assumed that it is URL-encoded, stripping certain character sequences from it. +- Fixed a bug (#148) - :doc:`Input Library <libraries/input>` internal method ``_clean_input_data()`` assumed that it data is URL-encoded, stripping certain character sequences from it. - Fixed a bug (#346) - with ``$config['global_xss_filtering']`` turned on, the ``$_GET``, ``$_POST``, ``$_COOKIE`` and ``$_SERVER`` superglobals were overwritten during initialization time, resulting in XSS filtering being either performed twice or there was no possible way to get the original data, even though options for this do exist. -- Fixed an edge case (#555) - incorrect browser version was reported for Opera 10+ due to a non-standard user-agent string. +- Fixed an edge case (#555) - :doc:`User Agent Library <libraries/user_agent>` reported an incorrect version Opera 10+ due to a non-standard user-agent string. - Fixed a bug (#133) - :doc:`Text Helper <helpers/text_helper>` :func:`ascii_to_entities()` stripped the last character if it happens to be in the extended ASCII group. - Fixed a bug (#2822) - ``fwrite()`` was used incorrectly throughout the whole framework, allowing incomplete writes when writing to a network stream and possibly a few other edge cases. - Fixed a bug where :doc:`User Agent Library <libraries/user_agent>` methods ``accept_charset()`` and ``accept_lang()`` didn't properly parse HTTP headers that contain spaces. - Fixed a bug where *default_controller* was called instad of triggering a 404 error if the current route is in a controller directory. - Fixed a bug (#2737) - :doc:`XML-RPC Library <libraries/xmlrpc>` used objects as array keys, which triggered E_NOTICE messages. -- Fixed a bug (#2729) - ``CI_Security::_validate_entities()`` used overly-intrusive ``preg_replace()`` patterns that produced false-positives. -- Fixed a bug (#2771) - ``CI_Security::xss_clean()`` didn't take into account HTML5 entities. +- Fixed a bug (#2729) - :doc:`Security Library <libraries/security>` internal method ``_validate_entities()`` used overly-intrusive ``preg_replace()`` patterns that produced false-positives. +- Fixed a bug (#2771) - :doc:`Security Library <libraries/security>` method ``xss_clean()`` didn't take into account HTML5 entities. - Fixed a bug in the :doc:`Session Library <libraries/sessions>` 'cookie' driver where authentication was not performed for encrypted cookies. - Fixed a bug (#2856) - ODBC method ``affected_rows()`` passed an incorrect value to ``odbc_num_rows()``. @@ -2255,7 +2260,7 @@ Bug fixes for Version 1.6.0 - Fixed a bug (#3003) in the Encryption Library to support modes other than MCRYPT_MODE_ECB - Fixed a bug (#3015) in the :doc:`User Agent - library <./libraries/user_agent>` where more then 2 languages + library <./libraries/user_agent>` where more than 2 languages where not reported with languages(). - Fixed a bug (#3017) in the :doc:`Email <./libraries/email>` library where some timezones were calculated incorrectly. diff --git a/user_guide_src/source/documentation/index.rst b/user_guide_src/source/documentation/index.rst index e977566d2..b080c0efa 100644 --- a/user_guide_src/source/documentation/index.rst +++ b/user_guide_src/source/documentation/index.rst @@ -8,12 +8,28 @@ Markdown or Textile, you will quickly grasp reStructuredText. The focus is on readability, user friendliness, and an "I've got your hand, baby" feel. While they can be quite technical, we always write for humans! -A table of contents should always be included like the one below. -It is created automatically by inserting the ``.. contents::`` -directive on a line by itself. +A local table of contents should always be included like the one below. +It is created automatically by inserting the the following: -.. contents:: Page Contents +:: + .. contents:: + :local: + + .. raw:: html + + <div class="custom-index container"></div> + +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + +The <div> that is inserted as raw HTML is a hook for the documentation's +JavaScript to dynamically add links to any function and method definitions +contained in the current page. ************** Tools Required @@ -50,39 +66,39 @@ overlines. Other headings just use underlines, with the following hierarchy:: - for subsubsections ^ for subsubsubsections " for subsubsubsubsections (!) - + The :download:`TextMate ELDocs Bundle <./ELDocs.tmbundle.zip>` can help you create these with the following tab triggers:: title-> - + ########## Page Title ########## sec-> - + ************* Major Section ************* - + sub-> - + Subsection ========== - + sss-> - + SubSubSection ------------- - + ssss-> - + SubSubSubSection ^^^^^^^^^^^^^^^^ - + sssss-> - + SubSubSubSubSection (!) """"""""""""""""""""""" @@ -99,12 +115,9 @@ ReST: .. code-block:: rst - .. php:class:: Some_class - - some_method() - ============= + .. class:: Some_class - .. php:method:: some_method ( $foo [, $bar [, $bat]]) + .. method:: some_method ( $foo [, $bar [, $bat]]) This function will perform some action. The ``$bar`` array must contain a something and something else, and along with ``$bat`` is an optional @@ -114,8 +127,8 @@ ReST: :param mixed $bar: A data array that must contain aa something and something else :param bool $bat: whether or not to do something :returns: FALSE on failure, TRUE if successful - :rtype: Boolean - + :rtype: bool + :: $this->load->library('some_class'); @@ -131,29 +144,25 @@ ReST: { show_error('An Error Occurred Doing Some Method'); } - + .. note:: Here is something that you should be aware of when using some_method(). For real. - - See also :php:meth:`Some_class::should_do_something` - should_do_something() - ===================== + See also :meth:`Some_class::should_do_something` + - .. php:method:: should_do_something() + .. method:: should_do_something() - :returns: whether or something should be done or not - :rtype: Boolean + :returns: Whether or something should be done or not + :rtype: bool It creates the following display: -.. php:class:: Some_class +.. class:: Some_class -some_method() -============= - .. php:method:: some_method ( $foo [, $bar [, $bat]]) + .. method:: some_method ( $foo [, $bar [, $bat]]) This function will perform some action. The ``$bar`` array must contain a something and something else, and along with ``$bat`` is an optional @@ -163,8 +172,8 @@ some_method() :param mixed $bar: A data array that must contain aa something and something else :param bool $bat: whether or not to do something :returns: FALSE on failure, TRUE if successful - :rtype: Boolean - + :rtype: bool + :: $this->load->library('some_class'); @@ -180,16 +189,14 @@ some_method() { show_error('An Error Occurred Doing Some Method'); } - + .. note:: Here is something that you should be aware of when using some_method(). For real. - - See also :php:meth:`Some_class::should_do_something` -should_do_something() -===================== + See also :meth:`Some_class::should_do_something` + - .. php:method:: should_do_something() + .. method:: should_do_something() - :returns: whether or something should be done or not - :rtype: Boolean + :returns: Whether or something should be done or not + :rtype: bool
\ No newline at end of file diff --git a/user_guide_src/source/general/ancillary_classes.rst b/user_guide_src/source/general/ancillary_classes.rst index 5dc058ad4..edb3a14fb 100644 --- a/user_guide_src/source/general/ancillary_classes.rst +++ b/user_guide_src/source/general/ancillary_classes.rst @@ -9,7 +9,7 @@ resources. This is easily possible as you'll see. get_instance() ============== -.. php:function:: get_instance() +.. function:: get_instance() :returns: object of class CI_Controller @@ -48,7 +48,7 @@ Once you've assigned the object to a variable, you'll use that variable passed by reference:: $CI =& get_instance(); - + This is very important. Assigning by reference allows you to use the original CodeIgniter object rather than creating a copy of it. diff --git a/user_guide_src/source/general/common_functions.rst b/user_guide_src/source/general/common_functions.rst index 1babe5a83..2ca7478ec 100644 --- a/user_guide_src/source/general/common_functions.rst +++ b/user_guide_src/source/general/common_functions.rst @@ -6,205 +6,183 @@ CodeIgniter uses a few functions for its operation that are globally defined, and are available to you at any point. These do not require loading any libraries or helpers. -is_php() -======== +.. contents:: + :local: -.. php:function:: is_php($version = '5.3.0') +.. raw:: html - :param string $version: Version number - :returns: bool + <div class="custom-index container"></div> + +.. function:: is_php([$version = '5.3.0']) -Determines of the PHP version being used is greater than the -supplied version number. + :param string $version: Version number + :returns: TRUE if the running PHP version is at least the one specified or FALSE if not + :rtype: bool -Example:: + Determines of the PHP version being used is greater than the + supplied version number. - if (is_php('5.3')) - { - $str = quoted_printable_encode($str); - } + Example:: -Returns boolean TRUE if the installed version of PHP is equal to or -greater than the supplied version number. Returns FALSE if the installed -version of PHP is lower than the supplied version number. + if (is_php('5.3')) + { + $str = quoted_printable_encode($str); + } -is_really_writable() -==================== + Returns boolean TRUE if the installed version of PHP is equal to or + greater than the supplied version number. Returns FALSE if the installed + version of PHP is lower than the supplied version number. -.. php:function:: is_really_writable($file) +.. function:: is_really_writable($file) :param string $file: File path - :returns: bool + :returns: TRUE if the path is writable, FALSE if not + :rtype: bool -``is_writable()`` returns TRUE on Windows servers when you really can't -write to the file as the OS reports to PHP as FALSE only if the -read-only attribute is marked. + ``is_writable()`` returns TRUE on Windows servers when you really can't + write to the file as the OS reports to PHP as FALSE only if the + read-only attribute is marked. -This function determines if a file is actually writable by attempting -to write to it first. Generally only recommended on platforms where -this information may be unreliable. + This function determines if a file is actually writable by attempting + to write to it first. Generally only recommended on platforms where + this information may be unreliable. -Example:: + Example:: - if (is_really_writable('file.txt')) - { - echo "I could write to this if I wanted to"; - } - else - { - echo "File is not writable"; - } + if (is_really_writable('file.txt')) + { + echo "I could write to this if I wanted to"; + } + else + { + echo "File is not writable"; + } -config_item() -============= + .. note:: See also `PHP bug #54709 <https://bugs.php.net/bug.php?id=54709>`_ for more info. -.. php:function:: config_item($key) +.. function:: config_item($key) :param string $key: Config item key - :returns: mixed - -The :doc:`Config Library <../libraries/config>` is the preferred way of -accessing configuration information, however ``config_item()`` can be used -to retrieve single keys. See :doc:`Config Library <../libraries/config>` -documentation for more information. + :returns: Configuration key value or FALSE if not found + :rtype: mixed -show_error() -============ + The :doc:`Config Library <../libraries/config>` is the preferred way of + accessing configuration information, however ``config_item()`` can be used + to retrieve single keys. See :doc:`Config Library <../libraries/config>` + documentation for more information. -.. :noindex: php:function:: show_error($message, $status_code, $heading = 'An Error Was Encountered') +.. :noindex: function:: show_error($message, $status_code[, $heading = 'An Error Was Encountered']) :param mixed $message: Error message :param int $status_code: HTTP Response status code :param string $heading: Error page heading - :returns: void + :rtype: void -This function calls ``CI_Exception::show_error()``. For more info, -please see the :doc:`Error Handling <errors>` documentation. + This function calls ``CI_Exception::show_error()``. For more info, + please see the :doc:`Error Handling <errors>` documentation. -show_404() -========== - -.. :noindex: php:function:: show_404($page = '', $log_error = TRUE) +.. :noindex: function:: show_404([$page = ''[, $log_error = TRUE]]) :param string $page: URI string :param bool $log_error: Whether to log the error - :returns: void - -This function calls ``CI_Exception::show_404()``. For more info, -please see the :doc:`Error Handling <errors>` documentation. + :rtype: void -log_message() -============= + This function calls ``CI_Exception::show_404()``. For more info, + please see the :doc:`Error Handling <errors>` documentation. -.. :noindex: php:function:: log_message($level, $message) +.. :noindex: function:: log_message($level, $message) :param string $level: Log level: 'error', 'debug' or 'info' :param string $message: Message to log - :returns: void - -This function is an alias for ``CI_Log::write_log()``. For more info, -please see the :doc:`Error Handling <errors>` documentation. + :rtype: void -set_status_header() -=============================== + This function is an alias for ``CI_Log::write_log()``. For more info, + please see the :doc:`Error Handling <errors>` documentation. -.. php:function:: set_status_header($code, $text = '') +.. function:: set_status_header($code[, $text = '']) :param int $code: HTTP Reponse status code :param string $text: A custom message to set with the status code - :returns: void + :rtype: void -Permits you to manually set a server status header. Example:: + Permits you to manually set a server status header. Example:: - set_status_header(401); - // Sets the header as: Unauthorized + 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. + `See here <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>`_ for + a full list of headers. -remove_invisible_characters() -============================= - -.. php:function:: remove_invisible_characters($str, $url_encoded = TRUE) +.. function:: remove_invisible_characters($str[, $url_encoded = TRUE]) :param string $str: Input string :param bool $url_encoded: Whether to remove URL-encoded characters as well - :returns: string - -This function prevents inserting NULL characters between ASCII -characters, like Java\\0script. - -Example:: - - remove_invisible_characters('Java\\0script'); - // Returns: 'Javascript' - -html_escape() -============= - -.. php:function:: html_escape($var) + :returns: Sanitized string + :rtype: string - :param mixed $var: Variable to escape - (string or array) - :returns: mixed + This function prevents inserting NULL characters between ASCII + characters, like Java\\0script. -This function acts as an alias for PHP's native ``htmlspecialchars()`` -function, with the advantage of being able to accept an array of strings. + Example:: -It is useful in preventing Cross Site Scripting (XSS). + remove_invisible_characters('Java\\0script'); + // Returns: 'Javascript' -get_mimes() -=========== +.. function:: html_escape($var) -.. php:function:: get_mimes() + :param mixed $var: Variable to escape (string or array) + :returns: HTML escaped string(s) + :rtype: mixed - :returns: array + This function acts as an alias for PHP's native ``htmlspecialchars()`` + function, with the advantage of being able to accept an array of strings. -This function returns a *reference* to the MIMEs array from -*application/config/mimes.php*. + It is useful in preventing Cross Site Scripting (XSS). -is_https() -========== +.. function:: get_mimes() -.. php:function:: is_https() + :returns: An associative array of file types + :rtype: array - :returns: bool + This function returns a *reference* to the MIMEs array from + *application/config/mimes.php*. -Returns TRUE if a secure (HTTPS) connection is used and FALSE -in any other case (including non-HTTP requests). +.. function:: is_https() -is_cli() -======== + :returns: TRUE if currently using HTTP-over-SSL, FALSE if not + :rtype: bool -.. php:function:: is_cli() + Returns TRUE if a secure (HTTPS) connection is used and FALSE + in any other case (including non-HTTP requests). - :returns: bool +.. function:: is_cli() -Returns TRUE if the application is run through the command line -and FALSE if not. + :returns: TRUE if currently running under CLI, FALSE otherwise + :rtype: bool -.. note:: This function checks both if the ``PHP_SAPI`` value is 'cli' - or if the ``STDIN`` constant is defined. + Returns TRUE if the application is run through the command line + and FALSE if not. -function_usable() -================= + .. note:: This function checks both if the ``PHP_SAPI`` value is 'cli' + or if the ``STDIN`` constant is defined. -.. php:function:: function_usable($function_name) +.. function:: function_usable($function_name) :param string $function_name: Function name - :returns: bool + :returns: TRUE if the function can be used, FALSE if not + :rtype: bool -Returns TRUE if a function exists and is usable, FALSE otherwise. + Returns TRUE if a function exists and is usable, FALSE otherwise. -This function runs a ``function_exists()`` check and if the -`Suhosin extension <http://www.hardened-php.net/suhosin/>` is loaded, -checks if it doesn't disable the function being checked. + This function runs a ``function_exists()`` check and if the + `Suhosin extension <http://www.hardened-php.net/suhosin/>` is loaded, + checks if it doesn't disable the function being checked. -It is useful if you want to check for the availability of functions -such as ``eval()`` and ``exec()``, which are dangerous and might be -disabled on servers with highly restrictive security policies. + It is useful if you want to check for the availability of functions + such as ``eval()`` and ``exec()``, which are dangerous and might be + disabled on servers with highly restrictive security policies. -.. note:: This function was introduced because Suhosin terminated - script execution, but this turned out to be a bug. A fix - has been available for some time (version 0.9.34), but is - unfortunately not released yet.
\ No newline at end of file + .. note:: This function was introduced because Suhosin terminated + script execution, but this turned out to be a bug. A fix + has been available for some time (version 0.9.34), but is + unfortunately not released yet.
\ No newline at end of file diff --git a/user_guide_src/source/general/controllers.rst b/user_guide_src/source/general/controllers.rst index d8ef824fb..bc8319dd8 100644 --- a/user_guide_src/source/general/controllers.rst +++ b/user_guide_src/source/general/controllers.rst @@ -107,7 +107,7 @@ You should see your new message. Passing URI Segments to your methods ==================================== -If your URI contains more then two segments they will be passed to your +If your URI contains more than two segments they will be passed to your method as parameters. For example, let's say you have a URI like this:: diff --git a/user_guide_src/source/general/errors.rst b/user_guide_src/source/general/errors.rst index f12d992f8..26c26bea1 100644 --- a/user_guide_src/source/general/errors.rst +++ b/user_guide_src/source/general/errors.rst @@ -21,23 +21,20 @@ without having to worry about class/function scoping. CodeIgniter also returns a status code whenever a portion of the core calls ``exit()``. This exit status code is separate from the HTTP status code, and serves as a notice to other processes that may be watching of -whether the script completed successfully, or if not, what kind of -problem it encountered that caused it to abort. These values are +whether the script completed successfully, or if not, what kind of +problem it encountered that caused it to abort. These values are defined in *application/config/constants.php*. While exit status codes are most useful in CLI settings, returning the proper code helps server software keep track of your scripts and the health of your application. The following functions let you generate errors: -show_error() -============ - -.. php:function:: show_error($message, $status_code, $heading = 'An Error Was Encountered') +.. function:: show_error($message, $status_code, $heading = 'An Error Was Encountered') :param mixed $message: Error message :param int $status_code: HTTP Response status code :param string $heading: Error page heading - :returns: void + :rtype: void This function will display the error message supplied to it using the following error template:: @@ -49,17 +46,14 @@ code should be sent with the error. If ``$status_code`` is less than 100, the HTTP status code will be set to 500, and the exit status code will be set to ``$status_code + EXIT__AUTO_MIN``. If that value is larger than ``EXIT__AUTO_MAX``, or if ``$status_code`` is 100 or higher, the exit -status code will be set to ``EXIT_ERROR``. You can check in +status code will be set to ``EXIT_ERROR``. You can check in *application/config/constants.php* for more detail. -show_404() -========== - -.. php:function:: show_404($page = '', $log_error = TRUE) +.. function:: show_404($page = '', $log_error = TRUE) :param string $page: URI string :param bool $log_error: Whether to log the error - :returns: void + :rtype: void This function will display the 404 error message supplied to it using the following error template:: @@ -74,15 +68,12 @@ not found. CodeIgniter automatically logs any ``show_404()`` calls. Setting the optional second parameter to FALSE will skip logging. -log_message() -============= - -.. php:function:: log_message($level, $message, $php_error = FALSE) +.. function:: log_message($level, $message, $php_error = FALSE) :param string $level: Log level: 'error', 'debug' or 'info' :param string $message: Message to log :param bool $php_error: Whether we're logging a native PHP error message - :returns: void + :rtype: void This function lets you write messages to your log files. You must supply one of three "levels" in the first parameter, indicating what type of diff --git a/user_guide_src/source/general/hooks.rst b/user_guide_src/source/general/hooks.rst index fc5da5b80..1046c48ae 100644 --- a/user_guide_src/source/general/hooks.rst +++ b/user_guide_src/source/general/hooks.rst @@ -59,7 +59,7 @@ defined in your associative hook array: Multiple Calls to the Same Hook =============================== -If want to use the same hook point with more then one script, simply +If want to use the same hook point with more than one script, simply make your array declaration multi-dimensional, like this:: $hook['pre_controller'][] = array( diff --git a/user_guide_src/source/general/requirements.rst b/user_guide_src/source/general/requirements.rst index 104923625..0b67e8e3a 100644 --- a/user_guide_src/source/general/requirements.rst +++ b/user_guide_src/source/general/requirements.rst @@ -2,14 +2,15 @@ Server Requirements ################### -- `PHP <http://www.php.net/>`_ version 5.2.4 or newer. -- A Database is required for most web application programming. - Currently supported databases are: - - MySQL (5.1+) via the *mysql* (deprecated), *mysqli* and *pdo* drivers - - Oracle via the *oci8* and *pdo* drivers - - PostgreSQL via the *postgre* and *pdo* drivers - - MS SQL via the *mssql*, *sqlsrv* (version 2005 and above only) and *pdo* drivers - - SQLite via the *sqlite* (version 2), *sqlite3* (version 3) and *pdo* drivers - - CUBRID via the *cubrid* and *pdo* drivers - - Interbase/Firebird via the *ibase* and *pdo* drivers - - ODBC via the *odbc* and *pdo* drivers (you should know that ODBC is actually an abstraction layer)
\ No newline at end of file +- `PHP <http://www.php.net/>`_ version 5.2.4 or newer. +- A Database is required for most web application programming. + + Currently supported databases are: + - MySQL (5.1+) via the *mysql* (deprecated), *mysqli* and *pdo* drivers + - Oracle via the *oci8* and *pdo* drivers + - PostgreSQL via the *postgre* and *pdo* drivers + - MS SQL via the *mssql*, *sqlsrv* (version 2005 and above only) and *pdo* drivers + - SQLite via the *sqlite* (version 2), *sqlite3* (version 3) and *pdo* drivers + - CUBRID via the *cubrid* and *pdo* drivers + - Interbase/Firebird via the *ibase* and *pdo* drivers + - ODBC via the *odbc* and *pdo* drivers (you should know that ODBC is actually an abstraction layer)
\ No newline at end of file diff --git a/user_guide_src/source/general/reserved_names.rst b/user_guide_src/source/general/reserved_names.rst index ccc17d61b..a767651fb 100644 --- a/user_guide_src/source/general/reserved_names.rst +++ b/user_guide_src/source/general/reserved_names.rst @@ -25,22 +25,22 @@ your controller any of these: Functions --------- -- :php:func:`is_php()` -- :php:func:`is_really_writable()` +- :func:`is_php()` +- :func:`is_really_writable()` - ``load_class()`` - ``is_loaded()`` - ``get_config()`` -- :php:func:`config_item()` -- :php:func:`show_error()` -- :php:func:`show_404()` -- :php:func:`log_message()` -- :php:func:`set_status_header()` -- :php:func:`get_mimes()` -- :php:func:`html_escape()` -- :php:func:`remove_invisible_characters()` -- :php:func:`is_https()` -- :php:func:`function_usable()` -- :php:func:`get_instance()` +- :func:`config_item()` +- :func:`show_error()` +- :func:`show_404()` +- :func:`log_message()` +- :func:`set_status_header()` +- :func:`get_mimes()` +- :func:`html_escape()` +- :func:`remove_invisible_characters()` +- :func:`is_https()` +- :func:`function_usable()` +- :func:`get_instance()` - ``_exception_handler()`` - ``_stringify_attributes()`` diff --git a/user_guide_src/source/general/styleguide.rst b/user_guide_src/source/general/styleguide.rst index 5613eabec..6718bc342 100644 --- a/user_guide_src/source/general/styleguide.rst +++ b/user_guide_src/source/general/styleguide.rst @@ -565,7 +565,7 @@ the ability to change this in the php.ini, you can often enable it with:: ini_set('display_errors', 1); .. note:: Setting the `display_errors - <http://php.net/manual/en/ref.errorfunc.php#ini.display-errors>`_ + <http://php.net/manual/en/errorfunc.configuration.php#ini.display-errors>`_ setting with ``ini_set()`` at runtime is not identical to having it enabled in the PHP environment. Namely, it will not have any effect if the script has fatal errors. diff --git a/user_guide_src/source/helpers/array_helper.rst b/user_guide_src/source/helpers/array_helper.rst index 9435b3ac7..4805f581a 100644 --- a/user_guide_src/source/helpers/array_helper.rst +++ b/user_guide_src/source/helpers/array_helper.rst @@ -5,7 +5,12 @@ Array Helper The Array Helper file contains functions that assist in working with arrays. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,114 +19,115 @@ This helper is loaded using the following code:: $this->load->helper('array'); + +Available Functions +=================== + The following functions are available: -element() -========= -.. php:function:: element($item, $array, $default = NULL) +.. function:: element($item, $array[, $default = NULL]) :param string $item: Item to fetch from the array :param array $array: Input array :param bool $default: What to return if the array isn't valid :returns: NULL on failure or the array item. + :rtype: mixed -Lets you fetch an item from an array. The function tests whether the -array index is set and whether it has a value. If a value exists it is -returned. If a value does not exist it returns NULL, or whatever you've -specified as the default value via the third parameter. + Lets you fetch an item from an array. The function tests whether the + array index is set and whether it has a value. If a value exists it is + returned. If a value does not exist it returns NULL, or whatever you've + specified as the default value via the third parameter. -Example:: + Example:: - $array = array( - 'color' => 'red', - 'shape' => 'round', - 'size' => '' - ); + $array = array( + 'color' => 'red', + 'shape' => 'round', + 'size' => '' + ); - echo element('color', $array); // returns "red" - echo element('size', $array, 'foobar'); // returns "foobar" + echo element('color', $array); // returns "red" + echo element('size', $array, 'foobar'); // returns "foobar" -elements() -========== -.. php:function:: elements($items, $array, $default = NULL) +.. function:: elements($items, $array[, $default = NULL]) :param string $item: Item to fetch from the array :param array $array: Input array :param bool $default: What to return if the array isn't valid :returns: NULL on failure or the array item. + :rtype: mixed -Lets you fetch a number of items from an array. The function tests -whether each of the array indices is set. If an index does not exist it -is set to NULL, or whatever you've specified as the default value via -the third parameter. + Lets you fetch a number of items from an array. The function tests + whether each of the array indices is set. If an index does not exist it + is set to NULL, or whatever you've specified as the default value via + the third parameter. -Example:: + Example:: - $array = array( - 'color' => 'red', - 'shape' => 'round', - 'radius' => '10', - 'diameter' => '20' - ); + $array = array( + 'color' => 'red', + 'shape' => 'round', + 'radius' => '10', + 'diameter' => '20' + ); - $my_shape = elements(array('color', 'shape', 'height'), $array); + $my_shape = elements(array('color', 'shape', 'height'), $array); -The above will return the following array:: + The above will return the following array:: - array( - 'color' => 'red', - 'shape' => 'round', - 'height' => NULL - ); + array( + 'color' => 'red', + 'shape' => 'round', + 'height' => NULL + ); -You can set the third parameter to any default value you like. -:: + You can set the third parameter to any default value you like. + :: - $my_shape = elements(array('color', 'shape', 'height'), $array, 'foobar'); + $my_shape = elements(array('color', 'shape', 'height'), $array, 'foobar'); -The above will return the following array:: + The above will return the following array:: - array( Â Â Â Â - 'color' => 'red', - 'shape' => 'round', - 'height' => 'foobar' - ); + array( Â Â Â Â + 'color' => 'red', + 'shape' => 'round', + 'height' => 'foobar' + ); -This is useful when sending the ``$_POST`` array to one of your Models. -This prevents users from sending additional POST data to be entered into -your tables. + This is useful when sending the ``$_POST`` array to one of your Models. + This prevents users from sending additional POST data to be entered into + your tables. -:: + :: - $this->load->model('post_model'); - $this->post_model->update( - elements(array('id', 'title', 'content'), $_POST) - ); + $this->load->model('post_model'); + $this->post_model->update( + elements(array('id', 'title', 'content'), $_POST) + ); -This ensures that only the id, title and content fields are sent to be -updated. + This ensures that only the id, title and content fields are sent to be + updated. -random_element() -================ -.. php:function:: random_element($array) +.. function:: random_element($array) :param array $array: Input array - :returns: string (a random element from the array) + :returns: A random element from the array + :rtype: mixed -Takes an array as input and returns a random element from it. + Takes an array as input and returns a random element from it. -Usage example:: + Usage example:: - $quotes = array( - "I find that the harder I work, the more luck I seem to have. - Thomas Jefferson", - "Don't stay in bed, unless you can make money in bed. - George Burns", - "We didn't lose the game; we just ran out of time. - Vince Lombardi", - "If everything seems under control, you're not going fast enough. - Mario Andretti", - "Reality is merely an illusion, albeit a very persistent one. - Albert Einstein", - "Chance favors the prepared mind - Louis Pasteur" - ); + $quotes = array( + "I find that the harder I work, the more luck I seem to have. - Thomas Jefferson", + "Don't stay in bed, unless you can make money in bed. - George Burns", + "We didn't lose the game; we just ran out of time. - Vince Lombardi", + "If everything seems under control, you're not going fast enough. - Mario Andretti", + "Reality is merely an illusion, albeit a very persistent one. - Albert Einstein", + "Chance favors the prepared mind - Louis Pasteur" + ); - echo random_element($quotes);
\ No newline at end of file + echo random_element($quotes);
\ No newline at end of file diff --git a/user_guide_src/source/helpers/captcha_helper.rst b/user_guide_src/source/helpers/captcha_helper.rst index f47173453..d83490b8e 100644 --- a/user_guide_src/source/helpers/captcha_helper.rst +++ b/user_guide_src/source/helpers/captcha_helper.rst @@ -5,56 +5,24 @@ CAPTCHA Helper The CAPTCHA Helper file contains functions that assist in creating CAPTCHA images. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== -This helper is loaded using the following code -:: +This helper is loaded using the following code:: $this->load->helper('captcha'); -The following functions are available: - -create_captcha() -================ - -.. php:function:: function create_captcha($data = '', $img_path = '', $img_url = '', $font_path = '') - - :param array $data: Array of data for the CAPTCHA - :param string $img_path: Path to create the image in - :param string $img_url: URL to the CAPTCHA image folder - :param string $font_path: Server path to font - :returns: array - -Takes an array of information to generate the CAPTCHA as input and -creates the image to your specifications, returning an array of -associative data about the image. - -:: - - array( - 'word' => CAPTCHA WORD, - 'time' => TIMESTAMP (in microtime), - 'image' => IMAGE TAG, - 'filename' => IMAGE FILE NAME - ) - -The **image** is the actual image tag:: - - <img src="http://example.com/captcha/12345.jpg" width="140" height="50" /> - -The **time** is the micro timestamp used as the image name without the -file extension. It will be a number like this: 1139612155.3422 - -The **word** is the word that appears in the captcha image, which if not -supplied to the function, will be a random string. - Using the CAPTCHA helper ------------------------- +======================== -Once loaded you can generate a captcha like this:: +Once loaded you can generate a CAPTCHA like this:: $vals = array( 'word' => 'Random word', @@ -133,7 +101,7 @@ CAPTCHA will be shown you'll have something like this:: $this->db->query($query); echo 'Submit the word you see below:'; - echo $cap['image']; + echo $cap['image']; echo '<input type="text" name="captcha" value="" />'; Then, on the page that accepts the submission you'll have something like @@ -153,4 +121,40 @@ this:: if ($row->count == 0) { Â Â Â Â echo 'You must submit the word that appears in the image.'; - }
\ No newline at end of file + } + +Available Functions +=================== + +The following functions are available: + +.. function:: create_captcha([$data = ''[, $img_path = ''[, $img_url = ''[, $font_path = '']]]]) + + :param array $data: Array of data for the CAPTCHA + :param string $img_path: Path to create the image in + :param string $img_url: URL to the CAPTCHA image folder + :param string $font_path: Server path to font + :returns: array('word' => $word, 'time' => $now, 'image' => $img) + :rtype: array + + Takes an array of information to generate the CAPTCHA as input and + creates the image to your specifications, returning an array of + associative data about the image. + + :: + + array( + 'image' => IMAGE TAG + 'time' => TIMESTAMP (in microtime) + 'word' => CAPTCHA WORD + ) + + The **image** is the actual image tag:: + + <img src="http://example.com/captcha/12345.jpg" width="140" height="50" /> + + The **time** is the micro timestamp used as the image name without the + file extension. It will be a number like this: 1139612155.3422 + + The **word** is the word that appears in the captcha image, which if not + supplied to the function, will be a random string.
\ No newline at end of file diff --git a/user_guide_src/source/helpers/cookie_helper.rst b/user_guide_src/source/helpers/cookie_helper.rst index c41193c3c..22fd0f77f 100644 --- a/user_guide_src/source/helpers/cookie_helper.rst +++ b/user_guide_src/source/helpers/cookie_helper.rst @@ -5,7 +5,12 @@ Cookie Helper The Cookie Helper file contains functions that assist in working with cookies. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,14 +19,15 @@ This helper is loaded using the following code:: $this->load->helper('cookie'); +Available Functions +=================== + The following functions are available: -set_cookie() -============ -.. php:function:: set_cookie($name = '', $value = '', $expire = '', $domain = '', $path = '/', $prefix = '', $secure = FALSE, $httponly = FALSE) +.. function:: set_cookie($name[, $value = ''[, $expire = ''[, $domain = ''[, $path = '/'[, $prefix = ''[, $secure = FALSE[, $httponly = FALSE]]]]]]]]) - :param string $name: Cookie name + :param mixed $name: Cookie name *or* associative array of all of the parameters available to this function :param string $value: Cookie value :param int $expire: Number of seconds until expiration :param string $domain: Cookie domain (usually: .yourdomain.com) @@ -29,49 +35,44 @@ set_cookie() :param string $prefix: Cookie name prefix :param bool $secure: Whether to only send the cookie through HTTPS :param bool $httponly: Whether to hide the cookie from JavaScript - :returns: void + :rtype: void -This helper function gives you view file friendly syntax to set browser -cookies. Refer to the :doc:`Input Library <../libraries/input>` for a -description of its use, as this function is an alias for -``CI_Input::set_cookie()``. + This helper function gives you view file friendly syntax to set browser + cookies. Refer to the :doc:`Input Library <../libraries/input>` for a + description of its use, as this function is an alias for + ``CI_Input::set_cookie()``. -get_cookie() -============ -.. php:function:: get_cookie($index = '', $xss_clean = FALSE) +.. function:: get_cookie($index[, $xss_clean = NULL]]) :param string $index: Cookie name :param bool $xss_clean: Whether to apply XSS filtering to the returned value - :returns: mixed + :returns: The cookie value or NULL if not found + :rtype: mixed -This helper function gives you view file friendly syntax to get browser -cookies. Refer to the :doc:`Input Library <../libraries/input>` for a -description of itsuse, as this function is an alias for ``CI_Input::cookie()``. + This helper function gives you view file friendly syntax to get browser + cookies. Refer to the :doc:`Input Library <../libraries/input>` for a + description of its use, as this function is an alias for ``CI_Input::cookie()``. -delete_cookie() -=============== -.. php:function:: delete_cookie($name = '', $domain = '', $path = '/', $prefix = '') +.. function:: delete_cookie($name[, $domain = ''[, $path = '/'[, $prefix = '']]]]) :param string $name: Cookie name :param string $domain: Cookie domain (usually: .yourdomain.com) :param string $path: Cookie path :param string $prefix: Cookie name prefix - :returns: void - -Lets you delete a cookie. Unless you've set a custom path or other -values, only the name of the cookie is needed. - -:: + :rtype: void - delete_cookie('name'); + Lets you delete a cookie. Unless you've set a custom path or other + values, only the name of the cookie is needed. + :: -This function is otherwise identical to ``set_cookie()``, except that it -does not have the value and expiration parameters. You can submit an -array of values in the first parameter or you can set discrete -parameters. + delete_cookie('name'); -:: + This function is otherwise identical to ``set_cookie()``, except that it + does not have the value and expiration parameters. You can submit an + array of values in the first parameter or you can set discrete + parameters. + :: - delete_cookie($name, $domain, $path, $prefix)
\ No newline at end of file + delete_cookie($name, $domain, $path, $prefix)
\ No newline at end of file diff --git a/user_guide_src/source/helpers/date_helper.rst b/user_guide_src/source/helpers/date_helper.rst index 8126eba6c..39a9cb325 100644 --- a/user_guide_src/source/helpers/date_helper.rst +++ b/user_guide_src/source/helpers/date_helper.rst @@ -4,7 +4,12 @@ Date Helper The Date Helper file contains functions that help you work with dates. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -13,396 +18,368 @@ This helper is loaded using the following code:: $this->load->helper('date'); +Available Functions +=================== + The following functions are available: -now() -===== -.. php:function:: now($timezone = NULL) +.. function:: now([$timezone = NULL]) :param string $timezone: Timezone - :returns: int - -Returns the current time as a UNIX timestamp, referenced either to your server's -local time or any PHP suported timezone, based on the "time reference" setting -in your config file. If you do not intend to set your master time reference to -any other PHP supported timezone (which you'll typically do if you run a site -that lets each user set their own timezone settings) there is no benefit to using -this function over PHP's ``time()`` function. - -:: + :returns: UNIX timestamp + :rtype: int - echo now('Australia/Victoria'); + Returns the current time as a UNIX timestamp, referenced either to your server's + local time or any PHP suported timezone, based on the "time reference" setting + in your config file. If you do not intend to set your master time reference to + any other PHP supported timezone (which you'll typically do if you run a site + that lets each user set their own timezone settings) there is no benefit to using + this function over PHP's ``time()`` function. + :: -If a timezone is not provided, it will return ``time()`` based on the -**time_reference** setting. + echo now('Australia/Victoria'); -mdate() -======= + If a timezone is not provided, it will return ``time()`` based on the + **time_reference** setting. -.. php:function:: mdate($datestr = '', $time = '') +.. function:: mdate([$datestr = ''[, $time = '']]) - :param string $datestr: Date string - :param int $time: UNIX timestamp - :returns: int - -This function is identical to PHP's `date() <http://www.php.net/date>`_ -function, except that it lets you use MySQL style date codes, where each -code letter is preceded with a percent sign, e.g. `%Y %m %d` + :param string $datestr: Date string + :param int $time: UNIX timestamp + :returns: MySQL-formatted date + :rtype: string -The benefit of doing dates this way is that you don't have to worry -about escaping any characters that are not date codes, as you would -normally have to do with the ``date()`` function. + This function is identical to PHP's `date() <http://www.php.net/date>`_ + function, except that it lets you use MySQL style date codes, where each + code letter is preceded with a percent sign, e.g. `%Y %m %d` -Example:: + The benefit of doing dates this way is that you don't have to worry + about escaping any characters that are not date codes, as you would + normally have to do with the ``date()`` function. - $datestring = 'Year: %Y Month: %m Day: %d - %h:%i %a'; - $time = time(); - echo mdate($datestring, $time); + Example:: -If a timestamp is not included in the second parameter the current time -will be used. + $datestring = 'Year: %Y Month: %m Day: %d - %h:%i %a'; + $time = time(); + echo mdate($datestring, $time); -standard_date() -=============== + If a timestamp is not included in the second parameter the current time + will be used. -.. php:function:: standard_date($fmt = 'DATE_RFC822', $time = NULL) +.. function:: standard_date([$fmt = 'DATE_RFC822'[, $time = NULL]]) :param string $fmt: Date format - :param int $time: UNIX timestamp - :returns: string - -Lets you generate a date string in one of several standardized formats. + :param int $time: UNIX timestamp + :returns: Formatted date or FALSE on invalid format + :rtype: string -Example:: + Lets you generate a date string in one of several standardized formats. - $format = 'DATE_RFC822'; - $time = time(); - echo standard_date($format, $time); + Example:: -.. note:: This function is DEPRECATED. Use the native ``date()`` combined with - `DateTime's format constants - <http://www.php.net/manual/en/class.datetime.php#datetime.constants.types>`_ - instead: + $format = 'DATE_RFC822'; + $time = time(); + echo standard_date($format, $time); - | - | echo date(DATE_RFC822, time()); + .. note:: This function is DEPRECATED. Use the native ``date()`` combined with + `DateTime's format constants + <http://www.php.net/manual/en/class.datetime.php#datetime.constants.types>`_ + instead:: -Supported formats ------------------ + echo date(DATE_RFC822, time()); -=============== ======================= ====================================== -Constant Description Example -=============== ======================= ====================================== -DATE_ATOM Atom 2005-08-15T16:13:03+0000 -DATE_COOKIE HTTP Cookies Sun, 14 Aug 2005 16:13:03 UTC -DATE_ISO8601 ISO-8601 2005-08-14T16:13:03+00:00 -DATE_RFC822 RFC 822 Sun, 14 Aug 05 16:13:03 UTC -DATE_RFC850 RFC 850 Sunday, 14-Aug-05 16:13:03 UTC -DATE_RFC1036 RFC 1036 Sunday, 14-Aug-05 16:13:03 UTC -DATE_RFC1123 RFC 1123 Sun, 14 Aug 2005 16:13:03 UTC -DATE_RFC2822 RFC 2822 Sun, 14 Aug 2005 16:13:03 +0000 -DATE_RSS RSS Sun, 14 Aug 2005 16:13:03 UTC -DATE_W3C W3C 2005-08-14T16:13:03+0000 -=============== ======================= ====================================== + **Supported formats:** -local_to_gmt() -============== + =============== ======================= ====================================== + Constant Description Example + =============== ======================= ====================================== + DATE_ATOM Atom 2005-08-15T16:13:03+0000 + DATE_COOKIE HTTP Cookies Sun, 14 Aug 2005 16:13:03 UTC + DATE_ISO8601 ISO-8601 2005-08-14T16:13:03+00:00 + DATE_RFC822 RFC 822 Sun, 14 Aug 05 16:13:03 UTC + DATE_RFC850 RFC 850 Sunday, 14-Aug-05 16:13:03 UTC + DATE_RFC1036 RFC 1036 Sunday, 14-Aug-05 16:13:03 UTC + DATE_RFC1123 RFC 1123 Sun, 14 Aug 2005 16:13:03 UTC + DATE_RFC2822 RFC 2822 Sun, 14 Aug 2005 16:13:03 +0000 + DATE_RSS RSS Sun, 14 Aug 2005 16:13:03 UTC + DATE_W3C W3C 2005-08-14T16:13:03+0000 + =============== ======================= ====================================== -.. php:function:: local_to_gmt($time = '') +.. function:: local_to_gmt([$time = '']) :param int $time: UNIX timestamp - :returns: string + :returns: UNIX timestamp + :rtype: int -Takes a UNIX timestamp as input and returns it as GMT. + Takes a UNIX timestamp as input and returns it as GMT. -Example:: + Example:: - $gmt = local_to_gmt(time()); + $gmt = local_to_gmt(time()); -gmt_to_local() -============== +.. function:: gmt_to_local([$time = ''[, $timezone = 'UTC'[, $dst = FALSE]]]) -.. php:function:: gmt_to_local($time = '', $timezone = 'UTC', $dst = FALSE) - - :param int $time: UNIX timestamp + :param int $time: UNIX timestamp :param string $timezone: Timezone - :param bool $dst: Whether DST is active - :returns: int - -Takes a UNIX timestamp (referenced to GMT) as input, and converts it to -a localized timestamp based on the timezone and Daylight Saving Time -submitted. + :param bool $dst: Whether DST is active + :returns: UNIX timestamp + :rtype: int -Example:: + Takes a UNIX timestamp (referenced to GMT) as input, and converts it to + a localized timestamp based on the timezone and Daylight Saving Time + submitted. - $timestamp = 1140153693; - $timezone = 'UM8'; - $daylight_saving = TRUE; - echo gmt_to_local($timestamp, $timezone, $daylight_saving); + Example:: + $timestamp = 1140153693; + $timezone = 'UM8'; + $daylight_saving = TRUE; + echo gmt_to_local($timestamp, $timezone, $daylight_saving); -.. note:: For a list of timezones see the reference at the bottom of this page. -mysql_to_unix() -=============== + .. note:: For a list of timezones see the reference at the bottom of this page. -.. php:function:: mysql_to_unix($time = '') +.. function:: mysql_to_unix([$time = '']) - :param int $time: UNIX timestamp - :returns: int + :param string $time: MySQL timestamp + :returns: UNIX timestamp + :rtype: int -Takes a MySQL Timestamp as input and returns it as a UNIX timestamp. + Takes a MySQL Timestamp as input and returns it as a UNIX timestamp. -Example:: + Example:: - $unix = mysql_to_unix('20061124092345'); + $unix = mysql_to_unix('20061124092345'); -unix_to_human() -=============== - -.. php:function:: unix_to_human($time = '', $seconds = FALSE, $fmt = 'us') +.. function:: unix_to_human([$time = ''[, $seconds = FALSE[, $fmt = 'us']]]) :param int $time: UNIX timestamp :param bool $seconds: Whether to show seconds :param string $fmt: format (us or euro) - :returns: integer - -Takes a UNIX timestamp as input and returns it in a human readable -format with this prototype:: + :returns: Formatted date + :rtype: string - YYYY-MM-DD HH:MM:SS AM/PM + Takes a UNIX timestamp as input and returns it in a human readable + format with this prototype:: -This can be useful if you need to display a date in a form field for -submission. + YYYY-MM-DD HH:MM:SS AM/PM -The time can be formatted with or without seconds, and it can be set to -European or US format. If only the timestamp is submitted it will return -the time without seconds formatted for the U.S. + This can be useful if you need to display a date in a form field for + submission. -Examples:: + The time can be formatted with or without seconds, and it can be set to + European or US format. If only the timestamp is submitted it will return + the time without seconds formatted for the U.S. - $now = time(); - echo unix_to_human($now); // U.S. time, no seconds - echo unix_to_human($now, TRUE, 'us'); // U.S. time with seconds - echo unix_to_human($now, TRUE, 'eu'); // Euro time with seconds + Examples:: -human_to_unix() -=============== + $now = time(); + echo unix_to_human($now); // U.S. time, no seconds + echo unix_to_human($now, TRUE, 'us'); // U.S. time with seconds + echo unix_to_human($now, TRUE, 'eu'); // Euro time with seconds -.. php:function:: human_to_unix($datestr = '') +.. function:: human_to_unix([$datestr = '']) - :param int $datestr: Date string - :returns: int UNIX timestamp or FALSE on failure + :param int $datestr: Date string + :returns: UNIX timestamp or FALSE on failure + :rtype: int -The opposite of the :php:func:`unix_to_time()` function. Takes a "human" -time as input and returns it as a UNIX timestamp. This is useful if you -accept "human" formatted dates submitted via a form. Returns boolean FALSE -date string passed to it is not formatted as indicated above. + The opposite of the :func:`unix_to_time()` function. Takes a "human" + time as input and returns it as a UNIX timestamp. This is useful if you + accept "human" formatted dates submitted via a form. Returns boolean FALSE + date string passed to it is not formatted as indicated above. -Example:: + Example:: - $now = time(); - $human = unix_to_human($now); - $unix = human_to_unix($human); + $now = time(); + $human = unix_to_human($now); + $unix = human_to_unix($human); -nice_date() -=========== - -.. php:function:: nice_date($bad_date = '', $format = FALSE) +.. function:: nice_date([$bad_date = ''[, $format = FALSE]]) :param int $bad_date: The terribly formatted date-like string :param string $format: Date format to return (same as PHP's ``date()`` function) - :returns: string - -This function can take a number poorly-formed date formats and convert -them into something useful. It also accepts well-formed dates. + :returns: Formatted date + :rtype: string -The function will return a UNIX timestamp by default. You can, optionally, -pass a format string (the same type as the PHP ``date()`` function accepts) -as the second parameter. + This function can take a number poorly-formed date formats and convert + them into something useful. It also accepts well-formed dates. -Example:: + The function will return a UNIX timestamp by default. You can, optionally, + pass a format string (the same type as the PHP ``date()`` function accepts) + as the second parameter. - $bad_date = '199605'; - // Should Produce: 1996-05-01 - $better_date = nice_date($bad_date, 'Y-m-d'); + Example:: - $bad_date = '9-11-2001'; - // Should Produce: 2001-09-11 - $better_date = nice_date($bad_date, 'Y-m-d'); + $bad_date = '199605'; + // Should Produce: 1996-05-01 + $better_date = nice_date($bad_date, 'Y-m-d'); -timespan() -========== + $bad_date = '9-11-2001'; + // Should Produce: 2001-09-11 + $better_date = nice_date($bad_date, 'Y-m-d'); -.. php:function:: timespan($seconds = 1, $time = '', $units = '') +.. function:: timespan([$seconds = 1[, $time = ''[, $units = '']]]) :param int $seconds: Number of seconds :param string $time: UNIX timestamp :param int $units: Number of time units to display - :returns: string + :returns: Formatted time difference + :rtype: string -Formats a UNIX timestamp so that is appears similar to this:: + Formats a UNIX timestamp so that is appears similar to this:: - 1 Year, 10 Months, 2 Weeks, 5 Days, 10 Hours, 16 Minutes + 1 Year, 10 Months, 2 Weeks, 5 Days, 10 Hours, 16 Minutes -The first parameter must contain a UNIX timestamp. -The second parameter must contain a timestamp that is greater that the -first timestamp. -The thirdparameter is optional and limits the number of time units to display. + The first parameter must contain a UNIX timestamp. + The second parameter must contain a timestamp that is greater that the + first timestamp. + The thirdparameter is optional and limits the number of time units to display. -If the second parameter empty, the current time will be used. + If the second parameter empty, the current time will be used. -The most common purpose for this function is to show how much time has -elapsed from some point in time in the past to now. + The most common purpose for this function is to show how much time has + elapsed from some point in time in the past to now. -Example:: + Example:: - $post_date = '1079621429'; - $now = time(); - $units = 2; - echo timespan($post_date, $now, $units); + $post_date = '1079621429'; + $now = time(); + $units = 2; + echo timespan($post_date, $now, $units); -.. note:: The text generated by this function is found in the following language - file: `language/<your_lang>/date_lang.php` + .. note:: The text generated by this function is found in the following language + file: `language/<your_lang>/date_lang.php` -days_in_month() -=============== - -.. php:function:: days_in_month($month = 0, $year = '') +.. function:: days_in_month([$month = 0[, $year = '']]) :param int $month: a numeric month :param int $year: a numeric year - :returns: int - -Returns the number of days in a given month/year. Takes leap years into -account. + :returns: Count of days in the specified month + :rtype: int -Example:: + Returns the number of days in a given month/year. Takes leap years into + account. - echo days_in_month(06, 2005); + Example:: -If the second parameter is empty, the current year will be used. + echo days_in_month(06, 2005); -date_range() -============ + If the second parameter is empty, the current year will be used. -.. php:function:: date_range($unix_start = '', $mixed = '', $is_unix = TRUE, $format = 'Y-m-d') +.. function:: date_range([$unix_start = ''[, $mixed = ''[, $is_unix = TRUE[, $format = 'Y-m-d']]]]) :param int $unix_start: UNIX timestamp of the range start date :param int $mixed: UNIX timestamp of the range end date or interval in days :param bool $is_unix: set to FALSE if $mixed is not a timestamp :param string $format: Output date format, same as in ``date()`` - :returns: array - -Returns a list of dates within a specified period. + :returns: An array of dates + :rtype: array -Example:: + Returns a list of dates within a specified period. - $range = date_range('2012-01-01', '2012-01-15'); - echo "First 15 days of 2012:"; - foreach ($range as $date) - { - echo $date."\n"; - } + Example:: -timezones() -=========== + $range = date_range('2012-01-01', '2012-01-15'); + echo "First 15 days of 2012:"; + foreach ($range as $date) + { + echo $date."\n"; + } -.. php:function:: timezones($tz = '') +.. function:: timezones([$tz = '']) - :param string $tz: a numeric timezone - :returns: string + :param string $tz: A numeric timezone + :returns: Hour difference from UTC + :rtype: int -Takes a timezone reference (for a list of valid timezones, see the -"Timezone Reference" below) and returns the number of hours offset from -UTC. + Takes a timezone reference (for a list of valid timezones, see the + "Timezone Reference" below) and returns the number of hours offset from + UTC. -Example:: + Example:: - echo timezones('UM5'); + echo timezones('UM5'); -This function is useful when used with :php:func:`timezone_menu()`. + This function is useful when used with :func:`timezone_menu()`. -timezone_menu() -=============== - -.. php:function:: timezone_menu($default = 'UTC', $class = '', $name = 'timezones', $attributes = '') +.. function:: timezone_menu([$default = 'UTC'[, $class = ''[, $name = 'timezones'[, $attributes = '']]]]) :param string $default: Timezone :param string $class: Class name :param string $name: Menu name :param mixed $attributes: HTML attributes - :returns: string - -Generates a pull-down menu of timezones, like this one: - -.. raw:: html - - <form action="#"> - <select name="timezones"> - <option value='UM12'>(UTC -12:00) Baker/Howland Island</option> - <option value='UM11'>(UTC -11:00) Samoa Time Zone, Niue</option> - <option value='UM10'>(UTC -10:00) Hawaii-Aleutian Standard Time, Cook Islands, Tahiti</option> - <option value='UM95'>(UTC -9:30) Marquesas Islands</option> - <option value='UM9'>(UTC -9:00) Alaska Standard Time, Gambier Islands</option> - <option value='UM8'>(UTC -8:00) Pacific Standard Time, Clipperton Island</option> - <option value='UM7'>(UTC -7:00) Mountain Standard Time</option> - <option value='UM6'>(UTC -6:00) Central Standard Time</option> - <option value='UM5'>(UTC -5:00) Eastern Standard Time, Western Caribbean Standard Time</option> - <option value='UM45'>(UTC -4:30) Venezuelan Standard Time</option> - <option value='UM4'>(UTC -4:00) Atlantic Standard Time, Eastern Caribbean Standard Time</option> - <option value='UM35'>(UTC -3:30) Newfoundland Standard Time</option> - <option value='UM3'>(UTC -3:00) Argentina, Brazil, French Guiana, Uruguay</option> - <option value='UM2'>(UTC -2:00) South Georgia/South Sandwich Islands</option> - <option value='UM1'>(UTC -1:00) Azores, Cape Verde Islands</option> - <option value='UTC' selected='selected'>(UTC) Greenwich Mean Time, Western European Time</option> - <option value='UP1'>(UTC +1:00) Central European Time, West Africa Time</option> - <option value='UP2'>(UTC +2:00) Central Africa Time, Eastern European Time, Kaliningrad Time</option> - <option value='UP3'>(UTC +3:00) Moscow Time, East Africa Time</option> - <option value='UP35'>(UTC +3:30) Iran Standard Time</option> - <option value='UP4'>(UTC +4:00) Azerbaijan Standard Time, Samara Time</option> - <option value='UP45'>(UTC +4:30) Afghanistan</option> - <option value='UP5'>(UTC +5:00) Pakistan Standard Time, Yekaterinburg Time</option> - <option value='UP55'>(UTC +5:30) Indian Standard Time, Sri Lanka Time</option> - <option value='UP575'>(UTC +5:45) Nepal Time</option> - <option value='UP6'>(UTC +6:00) Bangladesh Standard Time, Bhutan Time, Omsk Time</option> - <option value='UP65'>(UTC +6:30) Cocos Islands, Myanmar</option> - <option value='UP7'>(UTC +7:00) Krasnoyarsk Time, Cambodia, Laos, Thailand, Vietnam</option> - <option value='UP8'>(UTC +8:00) Australian Western Standard Time, Beijing Time, Irkutsk Time</option> - <option value='UP875'>(UTC +8:45) Australian Central Western Standard Time</option> - <option value='UP9'>(UTC +9:00) Japan Standard Time, Korea Standard Time, Yakutsk Time</option> - <option value='UP95'>(UTC +9:30) Australian Central Standard Time</option> - <option value='UP10'>(UTC +10:00) Australian Eastern Standard Time, Vladivostok Time</option> - <option value='UP105'>(UTC +10:30) Lord Howe Island</option> - <option value='UP11'>(UTC +11:00) Magadan Time, Solomon Islands, Vanuatu</option> - <option value='UP115'>(UTC +11:30) Norfolk Island</option> - <option value='UP12'>(UTC +12:00) Fiji, Gilbert Islands, Kamchatka Time, New Zealand Standard Time</option> - <option value='UP1275'>(UTC +12:45) Chatham Islands Standard Time</option> - <option value='UP13'>(UTC +13:00) Phoenix Islands Time, Tonga</option> - <option value='UP14'>(UTC +14:00) Line Islands</option> - </select> - </form> - - -This menu is useful if you run a membership site in which your users are -allowed to set their local timezone value. - -The first parameter lets you set the "selected" state of the menu. For -example, to set Pacific time as the default you will do this:: - - echo timezone_menu('UM8'); - -Please see the timezone reference below to see the values of this menu. - -The second parameter lets you set a CSS class name for the menu. - -The fourth parameter lets you set one or more attributes on the generated select tag. - -.. note:: The text contained in the menu is found in the following - language file: `language/<your_lang>/date_lang.php` - + :returns: HTML drop down menu with time zones + :rtype: string + + Generates a pull-down menu of timezones, like this one: + + .. raw:: html + + <form action="#"> + <select name="timezones"> + <option value='UM12'>(UTC -12:00) Baker/Howland Island</option> + <option value='UM11'>(UTC -11:00) Samoa Time Zone, Niue</option> + <option value='UM10'>(UTC -10:00) Hawaii-Aleutian Standard Time, Cook Islands, Tahiti</option> + <option value='UM95'>(UTC -9:30) Marquesas Islands</option> + <option value='UM9'>(UTC -9:00) Alaska Standard Time, Gambier Islands</option> + <option value='UM8'>(UTC -8:00) Pacific Standard Time, Clipperton Island</option> + <option value='UM7'>(UTC -7:00) Mountain Standard Time</option> + <option value='UM6'>(UTC -6:00) Central Standard Time</option> + <option value='UM5'>(UTC -5:00) Eastern Standard Time, Western Caribbean Standard Time</option> + <option value='UM45'>(UTC -4:30) Venezuelan Standard Time</option> + <option value='UM4'>(UTC -4:00) Atlantic Standard Time, Eastern Caribbean Standard Time</option> + <option value='UM35'>(UTC -3:30) Newfoundland Standard Time</option> + <option value='UM3'>(UTC -3:00) Argentina, Brazil, French Guiana, Uruguay</option> + <option value='UM2'>(UTC -2:00) South Georgia/South Sandwich Islands</option> + <option value='UM1'>(UTC -1:00) Azores, Cape Verde Islands</option> + <option value='UTC' selected='selected'>(UTC) Greenwich Mean Time, Western European Time</option> + <option value='UP1'>(UTC +1:00) Central European Time, West Africa Time</option> + <option value='UP2'>(UTC +2:00) Central Africa Time, Eastern European Time, Kaliningrad Time</option> + <option value='UP3'>(UTC +3:00) Moscow Time, East Africa Time</option> + <option value='UP35'>(UTC +3:30) Iran Standard Time</option> + <option value='UP4'>(UTC +4:00) Azerbaijan Standard Time, Samara Time</option> + <option value='UP45'>(UTC +4:30) Afghanistan</option> + <option value='UP5'>(UTC +5:00) Pakistan Standard Time, Yekaterinburg Time</option> + <option value='UP55'>(UTC +5:30) Indian Standard Time, Sri Lanka Time</option> + <option value='UP575'>(UTC +5:45) Nepal Time</option> + <option value='UP6'>(UTC +6:00) Bangladesh Standard Time, Bhutan Time, Omsk Time</option> + <option value='UP65'>(UTC +6:30) Cocos Islands, Myanmar</option> + <option value='UP7'>(UTC +7:00) Krasnoyarsk Time, Cambodia, Laos, Thailand, Vietnam</option> + <option value='UP8'>(UTC +8:00) Australian Western Standard Time, Beijing Time, Irkutsk Time</option> + <option value='UP875'>(UTC +8:45) Australian Central Western Standard Time</option> + <option value='UP9'>(UTC +9:00) Japan Standard Time, Korea Standard Time, Yakutsk Time</option> + <option value='UP95'>(UTC +9:30) Australian Central Standard Time</option> + <option value='UP10'>(UTC +10:00) Australian Eastern Standard Time, Vladivostok Time</option> + <option value='UP105'>(UTC +10:30) Lord Howe Island</option> + <option value='UP11'>(UTC +11:00) Magadan Time, Solomon Islands, Vanuatu</option> + <option value='UP115'>(UTC +11:30) Norfolk Island</option> + <option value='UP12'>(UTC +12:00) Fiji, Gilbert Islands, Kamchatka Time, New Zealand Standard Time</option> + <option value='UP1275'>(UTC +12:45) Chatham Islands Standard Time</option> + <option value='UP13'>(UTC +13:00) Phoenix Islands Time, Tonga</option> + <option value='UP14'>(UTC +14:00) Line Islands</option> + </select> + </form> + + + This menu is useful if you run a membership site in which your users are + allowed to set their local timezone value. + + The first parameter lets you set the "selected" state of the menu. For + example, to set Pacific time as the default you will do this:: + + echo timezone_menu('UM8'); + + Please see the timezone reference below to see the values of this menu. + + The second parameter lets you set a CSS class name for the menu. + + The fourth parameter lets you set one or more attributes on the generated select tag. + + .. note:: The text contained in the menu is found in the following + language file: `language/<your_lang>/date_lang.php` Timezone Reference ================== @@ -411,47 +388,47 @@ The following table indicates each timezone and its location. Note some of the location lists have been abridged for clarity and formatting. -=========== ===================================================================== -Time Zone Location -=========== ===================================================================== -UM12 (UTC - 12:00) Baker/Howland Island -UM11 (UTC - 11:00) Samoa Time Zone, Niue -UM10 (UTC - 10:00) Hawaii-Aleutian Standard Time, Cook Islands -UM95 (UTC - 09:30) Marquesas Islands -UM9 (UTC - 09:00) Alaska Standard Time, Gambier Islands -UM8 (UTC - 08:00) Pacific Standard Time, Clipperton Island -UM7 (UTC - 11:00) Mountain Standard Time -UM6 (UTC - 06:00) Central Standard Time -UM5 (UTC - 05:00) Eastern Standard Time, Western Caribbean -UM45 (UTC - 04:30) Venezuelan Standard Time -UM4 (UTC - 04:00) Atlantic Standard Time, Eastern Caribbean -UM35 (UTC - 03:30) Newfoundland Standard Time -UM3 (UTC - 03:00) Argentina, Brazil, French Guiana, Uruguay -UM2 (UTC - 02:00) South Georgia/South Sandwich Islands -UM1 (UTC -1:00) Azores, Cape Verde Islands -UTC (UTC) Greenwich Mean Time, Western European Time -UP1 (UTC +1:00) Central European Time, West Africa Time -UP2 (UTC +2:00) Central Africa Time, Eastern European Time -UP3 (UTC +3:00) Moscow Time, East Africa Time -UP35 (UTC +3:30) Iran Standard Time -UP4 (UTC +4:00) Azerbaijan Standard Time, Samara Time -UP45 (UTC +4:30) Afghanistan -UP5 (UTC +5:00) Pakistan Standard Time, Yekaterinburg Time -UP55 (UTC +5:30) Indian Standard Time, Sri Lanka Time -UP575 (UTC +5:45) Nepal Time -UP6 (UTC +6:00) Bangladesh Standard Time, Bhutan Time, Omsk Time -UP65 (UTC +6:30) Cocos Islands, Myanmar -UP7 (UTC +7:00) Krasnoyarsk Time, Cambodia, Laos, Thailand, Vietnam -UP8 (UTC +8:00) Australian Western Standard Time, Beijing Time -UP875 (UTC +8:45) Australian Central Western Standard Time -UP9 (UTC +9:00) Japan Standard Time, Korea Standard Time, Yakutsk -UP95 (UTC +9:30) Australian Central Standard Time -UP10 (UTC +10:00) Australian Eastern Standard Time, Vladivostok Time -UP105 (UTC +10:30) Lord Howe Island -UP11 (UTC +11:00) Magadan Time, Solomon Islands, Vanuatu -UP115 (UTC +11:30) Norfolk Island -UP12 (UTC +12:00) Fiji, Gilbert Islands, Kamchatka, New Zealand -UP1275 (UTC +12:45) Chatham Islands Standard Time -UP13 (UTC +13:00) Phoenix Islands Time, Tonga -UP14 (UTC +14:00) Line Islands +=========== ===================================================================== +Time Zone Location +=========== ===================================================================== +UM12 (UTC - 12:00) Baker/Howland Island +UM11 (UTC - 11:00) Samoa Time Zone, Niue +UM10 (UTC - 10:00) Hawaii-Aleutian Standard Time, Cook Islands +UM95 (UTC - 09:30) Marquesas Islands +UM9 (UTC - 09:00) Alaska Standard Time, Gambier Islands +UM8 (UTC - 08:00) Pacific Standard Time, Clipperton Island +UM7 (UTC - 11:00) Mountain Standard Time +UM6 (UTC - 06:00) Central Standard Time +UM5 (UTC - 05:00) Eastern Standard Time, Western Caribbean +UM45 (UTC - 04:30) Venezuelan Standard Time +UM4 (UTC - 04:00) Atlantic Standard Time, Eastern Caribbean +UM35 (UTC - 03:30) Newfoundland Standard Time +UM3 (UTC - 03:00) Argentina, Brazil, French Guiana, Uruguay +UM2 (UTC - 02:00) South Georgia/South Sandwich Islands +UM1 (UTC -1:00) Azores, Cape Verde Islands +UTC (UTC) Greenwich Mean Time, Western European Time +UP1 (UTC +1:00) Central European Time, West Africa Time +UP2 (UTC +2:00) Central Africa Time, Eastern European Time +UP3 (UTC +3:00) Moscow Time, East Africa Time +UP35 (UTC +3:30) Iran Standard Time +UP4 (UTC +4:00) Azerbaijan Standard Time, Samara Time +UP45 (UTC +4:30) Afghanistan +UP5 (UTC +5:00) Pakistan Standard Time, Yekaterinburg Time +UP55 (UTC +5:30) Indian Standard Time, Sri Lanka Time +UP575 (UTC +5:45) Nepal Time +UP6 (UTC +6:00) Bangladesh Standard Time, Bhutan Time, Omsk Time +UP65 (UTC +6:30) Cocos Islands, Myanmar +UP7 (UTC +7:00) Krasnoyarsk Time, Cambodia, Laos, Thailand, Vietnam +UP8 (UTC +8:00) Australian Western Standard Time, Beijing Time +UP875 (UTC +8:45) Australian Central Western Standard Time +UP9 (UTC +9:00) Japan Standard Time, Korea Standard Time, Yakutsk +UP95 (UTC +9:30) Australian Central Standard Time +UP10 (UTC +10:00) Australian Eastern Standard Time, Vladivostok Time +UP105 (UTC +10:30) Lord Howe Island +UP11 (UTC +11:00) Magadan Time, Solomon Islands, Vanuatu +UP115 (UTC +11:30) Norfolk Island +UP12 (UTC +12:00) Fiji, Gilbert Islands, Kamchatka, New Zealand +UP1275 (UTC +12:45) Chatham Islands Standard Time +UP13 (UTC +13:00) Phoenix Islands Time, Tonga +UP14 (UTC +14:00) Line Islands =========== =====================================================================
\ No newline at end of file diff --git a/user_guide_src/source/helpers/directory_helper.rst b/user_guide_src/source/helpers/directory_helper.rst index a785ebc8c..3004316a8 100644 --- a/user_guide_src/source/helpers/directory_helper.rst +++ b/user_guide_src/source/helpers/directory_helper.rst @@ -5,7 +5,12 @@ Directory Helper The Directory Helper file contains functions that assist in working with directories. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -16,64 +21,63 @@ This helper is loaded using the following code $this->load->helper('directory'); +Available Functions +=================== + The following functions are available: -directory_map() -=============== - -This function reads the directory path specified in the first parameter -and builds an array representation of it and all its contained files. - -.. php:method:: directory_map($source_dir[, $directory_depth = 0[, $hidden = FALSE]]) - - :param string $source_dir: path to the ource directory - :param integer $directory_depth: depth of directories to traverse (0 = - fully recursive, 1 = current dir, etc) - :param boolean $hidden: whether to include hidden directories - -Examples:: - - $map = directory_map('./mydirectory/'); - -.. note:: Paths are almost always relative to your main index.php file. - - -Sub-folders contained within the directory will be mapped as well. If -you wish to control the recursion depth, you can do so using the second -parameter (integer). A depth of 1 will only map the top level directory:: - - $map = directory_map('./mydirectory/', 1); - -By default, hidden files will not be included in the returned array. To -override this behavior, you may set a third parameter to true (boolean):: - - $map = directory_map('./mydirectory/', FALSE, TRUE); - -Each folder name will be an array index, while its contained files will -be numerically indexed. Here is an example of a typical array:: - - Array (    - [libraries] => Array    - (        - [0] => benchmark.html        - [1] => config.html        - ["database/"] => Array - (              - [0] => query_builder.html              - [1] => binds.html              - [2] => configuration.html - [3] => connecting.html              - [4] => examples.html              - [5] => fields.html              - [6] => index.html - [7] => queries.html - )        - [2] => email.html        - [3] => file_uploading.html        - [4] => image_lib.html        - [5] => input.html        - [6] => language.html        - [7] => loader.html        - [8] => pagination.html        - [9] => uri.html - )
\ No newline at end of file + +.. function:: directory_map($source_dir[, $directory_depth = 0[, $hidden = FALSE]]) + + :param string $source_dir: Path to the ource directory + :param int $directory_depth: Depth of directories to traverse (0 = fully recursive, 1 = current dir, etc) + :param bool $hidden: Whether to include hidden directories + :returns: An array of files + :rtype: array + + Examples:: + + $map = directory_map('./mydirectory/'); + + .. note:: Paths are almost always relative to your main index.php file. + + + Sub-folders contained within the directory will be mapped as well. If + you wish to control the recursion depth, you can do so using the second + parameter (integer). A depth of 1 will only map the top level directory:: + + $map = directory_map('./mydirectory/', 1); + + By default, hidden files will not be included in the returned array. To + override this behavior, you may set a third parameter to true (boolean):: + + $map = directory_map('./mydirectory/', FALSE, TRUE); + + Each folder name will be an array index, while its contained files will + be numerically indexed. Here is an example of a typical array:: + + Array (    + [libraries] => Array    + (        + [0] => benchmark.html        + [1] => config.html        + ["database/"] => Array + (              + [0] => query_builder.html              + [1] => binds.html              + [2] => configuration.html + [3] => connecting.html              + [4] => examples.html              + [5] => fields.html              + [6] => index.html + [7] => queries.html + )        + [2] => email.html        + [3] => file_uploading.html        + [4] => image_lib.html        + [5] => input.html        + [6] => language.html        + [7] => loader.html        + [8] => pagination.html        + [9] => uri.html + )
\ No newline at end of file diff --git a/user_guide_src/source/helpers/download_helper.rst b/user_guide_src/source/helpers/download_helper.rst index 860c568b9..f374d491f 100644 --- a/user_guide_src/source/helpers/download_helper.rst +++ b/user_guide_src/source/helpers/download_helper.rst @@ -4,7 +4,12 @@ Download Helper The Download Helper lets you download data to your desktop. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -13,38 +18,39 @@ This helper is loaded using the following code:: $this->load->helper('download'); +Available Functions +=================== + The following functions are available: -force_download() -================ -.. php:function:: force_download($filename = '', $data = '', $set_mime = FALSE) +.. function:: force_download([$filename = ''[, $data = ''[, $set_mime = FALSE]]]) :param string $filename: Filename :param mixed $data: File contents :param bool $set_mime: Whether to try to send the actual MIME type - :returns: void + :rtype: void -Generates server headers which force data to be downloaded to your -desktop. Useful with file downloads. The first parameter is the **name -you want the downloaded file to be named**, the second parameter is the -file data. + Generates server headers which force data to be downloaded to your + desktop. Useful with file downloads. The first parameter is the **name + you want the downloaded file to be named**, the second parameter is the + file data. -If you set the second parameter to NULL and ``$filename`` is an existing, readable -file path, then its content will be read instead. + If you set the second parameter to NULL and ``$filename`` is an existing, readable + file path, then its content will be read instead. -If you set the third parameter to boolean TRUE, then the actual file MIME type -(based on the filename extension) will be sent, so that if your browser has a -handler for that type - it can use it. + If you set the third parameter to boolean TRUE, then the actual file MIME type + (based on the filename extension) will be sent, so that if your browser has a + handler for that type - it can use it. -Example:: + Example:: - $data = 'Here is some text!'; - $name = 'mytext.txt'; - force_download($name, $data); + $data = 'Here is some text!'; + $name = 'mytext.txt'; + force_download($name, $data); -If you want to download an existing file from your server you'll need to -do the following:: + If you want to download an existing file from your server you'll need to + do the following:: - // Contents of photo.jpg will be automatically read - force_download('/path/to/photo.jpg', NULL);
\ No newline at end of file + // Contents of photo.jpg will be automatically read + force_download('/path/to/photo.jpg', NULL);
\ No newline at end of file diff --git a/user_guide_src/source/helpers/email_helper.rst b/user_guide_src/source/helpers/email_helper.rst index 10adf1d0e..b665ce548 100644 --- a/user_guide_src/source/helpers/email_helper.rst +++ b/user_guide_src/source/helpers/email_helper.rst @@ -6,9 +6,14 @@ The Email Helper provides some assistive functions for working with Email. For a more robust email solution, see CodeIgniter's :doc:`Email Class <../libraries/email>`. -.. contents:: Page Contents +.. important:: The Email helper is **deprecated**. -.. important:: The Email helper is DEPRECATED. +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -17,51 +22,53 @@ This helper is loaded using the following code:: $this->load->helper('email'); +Available Functions +=================== + The following functions are available: -valid_email() -============= -.. php:function:: valid_email($email) +.. function:: valid_email($email) - :param string $email: Email address - :returns: bool + :param string $email: E-mail address + :returns: TRUE if a valid email is supplied, FALSE otherwise + :rtype: bool -Checks if the input is a correctly formatted e-mail address. Note that is -doesn't actually prove that the address will be able recieve mail, but -simply that it is a validly formed address. + Checks if the input is a correctly formatted e-mail address. Note that is + doesn't actually prove that the address will be able recieve mail, but + simply that it is a validly formed address. -Example:: + Example:: - if (valid_email('email@somesite.com')) - { - echo 'email is valid'; - } - else - { - echo 'email is not valid'; - } + if (valid_email('email@somesite.com')) + { + echo 'email is valid'; + } + else + { + echo 'email is not valid'; + } -.. note:: All that this function does is to use PHP's native ``filter_var()``: - | - | (bool) filter_var($email, FILTER_VALIDATE_EMAIL); + .. note:: All that this function does is to use PHP's native ``filter_var()``:: -send_email() -============ + (bool) filter_var($email, FILTER_VALIDATE_EMAIL); -.. php:function:: send_email($recipient, $subject, $message) +.. function:: send_email($recipient, $subject, $message) :param string $recipient: E-mail address :param string $subject: Mail subject :param string $message: Message body - :returns: bool + :returns: TRUE if the mail was successfully sent, FALSE in case of an error + :rtype: bool + + Sends an email using PHP's native `mail() <http://www.php.net/function.mail>`_ + function. + + .. note:: All that this function does is to use PHP's native ``mail`` -Sends an email using PHP's native `mail() <http://www.php.net/function.mail>`_ -function. + :: -.. note:: All that this function does is to use PHP's native ``mail``: - | - | mail($recipient, $subject, $message); + mail($recipient, $subject, $message); -For a more robust email solution, see CodeIgniter's :doc:`Email Library -<../libraries/email>`. + For a more robust email solution, see CodeIgniter's :doc:`Email Library + <../libraries/email>`.
\ No newline at end of file diff --git a/user_guide_src/source/helpers/file_helper.rst b/user_guide_src/source/helpers/file_helper.rst index 194d4348f..59cabcce2 100644 --- a/user_guide_src/source/helpers/file_helper.rst +++ b/user_guide_src/source/helpers/file_helper.rst @@ -4,7 +4,12 @@ File Helper The File Helper file contains functions that assist in working with files. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -13,204 +18,185 @@ This helper is loaded using the following code:: $this->load->helper('file'); +Available Functions +=================== + The following functions are available: -read_file() -=========== -.. php:function:: read_file($file) +.. function:: read_file($file) :param string $file: File path - :returns: string or FALSE on failure + :returns: File contents or FALSE on failure + :rtype: string -Returns the data contained in the file specified in the path. + Returns the data contained in the file specified in the path. -Example:: + Example:: - $string = read_file('./path/to/file.php'); + $string = read_file('./path/to/file.php'); -The path can be a relative or full server path. Returns FALSE (boolean) on failure. + The path can be a relative or full server path. Returns FALSE (boolean) on failure. -.. note:: The path is relative to your main site index.php file, NOT your - controller or view files. CodeIgniter uses a front controller so paths - are always relative to the main site index. + .. note:: The path is relative to your main site index.php file, NOT your + controller or view files. CodeIgniter uses a front controller so paths + are always relative to the main site index. -.. note:: This function is DEPRECATED. Use the native ``file_get_contents()`` - instead. + .. note:: This function is DEPRECATED. Use the native ``file_get_contents()`` + instead. -.. important:: If your server is running an **open_basedir** restriction this - function might not work if you are trying to access a file above the - calling script. + .. important:: If your server is running an **open_basedir** restriction this + function might not work if you are trying to access a file above the + calling script. -write_file() -============ - -.. php:function:: write_file($path, $data, $mode = 'wb') +.. function:: write_file($path, $data[, $mode = 'wb']) :param string $path: File path :param string $data: Data to write to file :param string $mode: ``fopen()`` mode - :returns: bool - -Writes data to the file specified in the path. If the file does not exist then the -function will create it. + :returns: TRUE if the write was successful, FALSE in case of an error + :rtype: bool -Example:: + Writes data to the file specified in the path. If the file does not exist then the + function will create it. - $data = 'Some file data'; - if ( ! write_file('./path/to/file.php', $data)) - { Â Â Â Â - echo 'Unable to write the file'; - } - else - { Â Â Â Â - echo 'File written!'; - } + Example:: -You can optionally set the write mode via the third parameter:: + $data = 'Some file data'; + if ( ! write_file('./path/to/file.php', $data)) + { Â Â Â Â + echo 'Unable to write the file'; + } + else + { Â Â Â Â + echo 'File written!'; + } - write_file('./path/to/file.php', $data, 'r+'); + You can optionally set the write mode via the third parameter:: -The default mode is 'wb'. Please see the `PHP user guide <http://php.net/fopen>`_ -for mode options. + write_file('./path/to/file.php', $data, 'r+'); -.. note: In order for this function to write data to a file, its permissions must - be set such that it is writable (666, 777, etc.). If the file does not - already exist, the directory containing it must be writable. + The default mode is 'wb'. Please see the `PHP user guide <http://php.net/fopen>`_ + for mode options. -.. note:: The path is relative to your main site index.php file, NOT your - controller or view files. CodeIgniter uses a front controller so paths - are always relative to the main site index. + .. note: In order for this function to write data to a file, its permissions must + be set such that it is writable (666, 777, etc.). If the file does not + already exist, the directory containing it must be writable. -.. note:: This function acquires an exclusive lock on the file while writing to it. + .. note:: The path is relative to your main site index.php file, NOT your + controller or view files. CodeIgniter uses a front controller so paths + are always relative to the main site index. -delete_files() -============== + .. note:: This function acquires an exclusive lock on the file while writing to it. -.. php:function:: delete_files($path, $del_dir = FALSE, $htdocs = FALSE) +.. function:: delete_files($path[, $del_dir = FALSE[, $htdocs = FALSE]]) :param string $path: Directory path :param bool $del_dir: Whether to also delete directories :param bool $htdocs: Whether to skip deleting .htaccess and index page files - :returns: bool + :returns: TRUE on success, FALSE in case of an error + :rtype: bool -Deletes ALL files contained in the supplied path. + Deletes ALL files contained in the supplied path. -Example:: + Example:: - delete_files('./path/to/directory/'); + delete_files('./path/to/directory/'); -If the second parameter is set to TRUE, any directories contained within the supplied -root path will be deleted as well. + If the second parameter is set to TRUE, any directories contained within the supplied + root path will be deleted as well. -Example:: + Example:: - delete_files('./path/to/directory/', TRUE); + delete_files('./path/to/directory/', TRUE); -.. note:: The files must be writable or owned by the system in order to be deleted. + .. note:: The files must be writable or owned by the system in order to be deleted. -get_filenames() -=============== - -.. php:function:: get_filenames($source_dir, $include_path = FALSE) +.. function:: get_filenames($source_dir[, $include_path = FALSE]) :param string $source_dir: Directory path :param bool $include_path: Whether to include the path as part of the filenames - :returns: array + :returns: An array of file names + :rtype: array -Takes a server path as input and returns an array containing the names of all files -contained within it. The file path can optionally be added to the file names by setting -the second parameter to TRUE. + Takes a server path as input and returns an array containing the names of all files + contained within it. The file path can optionally be added to the file names by setting + the second parameter to TRUE. -Example:: + Example:: - $controllers = get_filenames(APPPATH.'controllers/'); + $controllers = get_filenames(APPPATH.'controllers/'); -get_dir_file_info() -=================== - -.. php:function:: get_dir_file_info($source_dir, $top_level_only) +.. function:: get_dir_file_info($source_dir, $top_level_only) :param string $source_dir: Directory path - :param bool $top_level_only: Whether to look only at the specified directory - (excluding sub-directories) - :returns: array - -Reads the specified directory and builds an array containing the filenames, filesize, -dates, and permissions. Sub-folders contained within the specified path are only read -if forced by sending the second parameter to FALSE, as this can be an intensive -operation. + :param bool $top_level_only: Whether to look only at the specified directory (excluding sub-directories) + :returns: An array containing info on the supplied directory's contents + :rtype: array -Example:: + Reads the specified directory and builds an array containing the filenames, filesize, + dates, and permissions. Sub-folders contained within the specified path are only read + if forced by sending the second parameter to FALSE, as this can be an intensive + operation. - $models_info = get_dir_file_info(APPPATH.'models/'); + Example:: -get_file_info() -=============== + $models_info = get_dir_file_info(APPPATH.'models/'); -.. php:function: get_file_info($file, $returned_values = array('name', 'server_path', 'size', 'date')) +.. function:: get_file_info($file[, $returned_values = array('name', 'server_path', 'size', 'date')]) :param string $file: File path :param array $returned_values: What type of info to return - :returns: array or FALSE on failure - -Given a file and path, returns (optionally) the *name*, *path*, *size* and *date modified* -information attributes for a file. Second parameter allows you to explicitly declare what -information you want returned. - -Valid ``$returned_values`` options are: `name`, `size`, `date`, `readable`, `writeable`, -`executable` and `fileperms`. + :returns: An array containing info on the specified file or FALSE on failure + :rtype: array -.. note:: The *writable* attribute is checked via PHP's ``is_writeable()`` function, which - known to have issues on the IIS webserver. Consider using *fileperms* instead, - which returns information from PHP's ``fileperms()`` function. + Given a file and path, returns (optionally) the *name*, *path*, *size* and *date modified* + information attributes for a file. Second parameter allows you to explicitly declare what + information you want returned. -get_mime_by_extension() -======================= + Valid ``$returned_values`` options are: `name`, `size`, `date`, `readable`, `writeable`, + `executable` and `fileperms`. -.. php:function:: get_mime_by_extension($filename) +.. function:: get_mime_by_extension($filename) :param string $filename: File name - :returns: string or FALSE on failure + :returns: MIME type string or FALSE on failure + :rtype: string -Translates a filename extension into a MIME type based on *config/mimes.php*. -Returns FALSE if it can't determine the type, or read the MIME config file. + Translates a filename extension into a MIME type based on *config/mimes.php*. + Returns FALSE if it can't determine the type, or read the MIME config file. -:: + :: - $file = 'somefile.png'; - echo $file.' is has a mime type of '.get_mime_by_extension($file); + $file = 'somefile.png'; + echo $file.' is has a mime type of '.get_mime_by_extension($file); -.. note:: This is not an accurate way of determining file MIME types, and - is here strictly for convenience. It should not be used for security - purposes. + .. note:: This is not an accurate way of determining file MIME types, and + is here strictly for convenience. It should not be used for security + purposes. -symbolic_permissions() -====================== - -.. php:function:: symbolic_permissions($perms) +.. function:: symbolic_permissions($perms) :param int $perms: Permissions - :returns: string - -Takes numeric permissions (such as is returned by ``fileperms()``) and returns -standard symbolic notation of file permissions. + :returns: Symbolic permissions string + :rtype: string -:: + Takes numeric permissions (such as is returned by ``fileperms()``) and returns + standard symbolic notation of file permissions. - echo symbolic_permissions(fileperms('./index.php')); // -rw-r--r-- + :: -octal_permissions() -=================== + echo symbolic_permissions(fileperms('./index.php')); // -rw-r--r-- -.. php:function:: octal_permissions($perms) +.. function:: octal_permissions($perms) :param int $perms: Permissions - :returns: string + :returns: Octal permissions string + :rtype: string -Takes numeric permissions (such as is returned by ``fileperms()``) and returns -a three character octal notation of file permissions. + Takes numeric permissions (such as is returned by ``fileperms()``) and returns + a three character octal notation of file permissions. -:: + :: - echo octal_permissions(fileperms('./index.php')); // 644
\ No newline at end of file + echo octal_permissions(fileperms('./index.php')); // 644
\ No newline at end of file diff --git a/user_guide_src/source/helpers/form_helper.rst b/user_guide_src/source/helpers/form_helper.rst index f49027baa..4fa5f246b 100644 --- a/user_guide_src/source/helpers/form_helper.rst +++ b/user_guide_src/source/helpers/form_helper.rst @@ -5,7 +5,12 @@ Form Helper The Form Helper file contains functions that assist in working with forms. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,713 +19,684 @@ This helper is loaded using the following code:: $this->load->helper('form'); +Available Functions +=================== + The following functions are available: -form_open() -=========== -.. php:function:: form_open($action = '', $attributes = '', $hidden = array()) +.. function:: form_open([$action = ''[, $attributes = ''[, $hidden = array()]]]) :param string $action: Form action/target URI string :param array $attributes: HTML attributes :param array $hidden: An array of hidden fields' definitions - :returns: string + :returns: An HTML form opening tag + :rtype: string -Creates an opening form tag with a base URL **built from your config preferences**. -It will optionally let you add form attributes and hidden input fields, and -will always add the `accept-charset` attribute based on the charset value in your -config file. + Creates an opening form tag with a base URL **built from your config preferences**. + It will optionally let you add form attributes and hidden input fields, and + will always add the `accept-charset` attribute based on the charset value in your + config file. -The main benefit of using this tag rather than hard coding your own HTML is that -it permits your site to be more portable in the event your URLs ever change. + The main benefit of using this tag rather than hard coding your own HTML is that + it permits your site to be more portable in the event your URLs ever change. -Here's a simple example:: + Here's a simple example:: - echo form_open('email/send'); + echo form_open('email/send'); -The above example would create a form that points to your base URL plus the -"email/send" URI segments, like this:: + The above example would create a form that points to your base URL plus the + "email/send" URI segments, like this:: - <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send"> + <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send"> -Adding Attributes -^^^^^^^^^^^^^^^^^ + **Adding Attributes** -Attributes can be added by passing an associative array to the second -parameter, like this:: + Attributes can be added by passing an associative array to the second + parameter, like this:: - $attributes = array('class' => 'email', 'id' => 'myform'); - echo form_open('email/send', $attributes); + $attributes = array('class' => 'email', 'id' => 'myform'); + echo form_open('email/send', $attributes); -Alternatively, you can specify the second parameter as a string:: + Alternatively, you can specify the second parameter as a string:: - echo form_open('email/send', 'class="email" id="myform"'); + echo form_open('email/send', 'class="email" id="myform"'); -The above examples would create a form similar to this:: + The above examples would create a form similar to this:: - <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send" class="email" id="myform"> + <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send" class="email" id="myform"> -Adding Hidden Input Fields -^^^^^^^^^^^^^^^^^^^^^^^^^^ + **Adding Hidden Input Fields** -Hidden fields can be added by passing an associative array to the -third parameter, like this:: + Hidden fields can be added by passing an associative array to the + third parameter, like this:: - $hidden = array('username' => 'Joe', 'member_id' => '234'); - echo form_open('email/send', '', $hidden); + $hidden = array('username' => 'Joe', 'member_id' => '234'); + echo form_open('email/send', '', $hidden); -You can skip the second parameter by passing any falsy value to it. + You can skip the second parameter by passing any falsy value to it. -The above example would create a form similar to this:: + The above example would create a form similar to this:: - <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send"> - <input type="hidden" name="username" value="Joe" /> - <input type="hidden" name="member_id" value="234" /> + <form method="post" accept-charset="utf-8" action="http://example.com/index.php/email/send"> + <input type="hidden" name="username" value="Joe" /> + <input type="hidden" name="member_id" value="234" /> -form_open_multipart() -===================== -.. php:function:: form_open_multipart($action = '', $attributes = array(), $hidden = array()) +.. function:: form_open_multipart([$action = ''[, $attributes = array()[, $hidden = array()]]) :param string $action: Form action/target URI string :param array $attributes: HTML attributes :param array $hidden: An array of hidden fields' definitions - :returns: string + :returns: An HTML multipart form opening tag + :rtype: string -This function is absolutely identical to :php:func:`form_open()` above, -except that it adds a *multipart* attribute, which is necessary if you -would like to use the form to upload files with. + This function is absolutely identical to :func:`form_open()` above, + except that it adds a *multipart* attribute, which is necessary if you + would like to use the form to upload files with. -form_hidden() -============= -.. php:function:: form_hidden($name, $value = '') +.. function:: form_hidden($name[, $value = '']) :param string $name: Field name :param string $value: Field value - :returns: string - -Lets you generate hidden input fields. You can either submit a -name/value string to create one field:: + :returns: An HTML hidden input field tag + :rtype: string - form_hidden('username', 'johndoe'); - // Would produce: <input type="hidden" name="username" value="johndoe" /> + Lets you generate hidden input fields. You can either submit a + name/value string to create one field:: -... or you can submit an associative array to create multiple fields:: + form_hidden('username', 'johndoe'); + // Would produce: <input type="hidden" name="username" value="johndoe" /> - $data = array( - 'name' => 'John Doe', - 'email' => 'john@example.com', - 'url' => 'http://example.com' - ); + ... or you can submit an associative array to create multiple fields:: - echo form_hidden($data); + $data = array( + 'name' => 'John Doe', + 'email' => 'john@example.com', + 'url' => 'http://example.com' + ); - /* - Would produce: - <input type="hidden" name="name" value="John Doe" /> - <input type="hidden" name="email" value="john@example.com" /> - <input type="hidden" name="url" value="http://example.com" /> - */ + echo form_hidden($data); -You can also pass an associative array to the value field:: + /* + Would produce: + <input type="hidden" name="name" value="John Doe" /> + <input type="hidden" name="email" value="john@example.com" /> + <input type="hidden" name="url" value="http://example.com" /> + */ - $data = array( - 'name' => 'John Doe', - 'email' => 'john@example.com', - 'url' => 'http://example.com' - ); + You can also pass an associative array to the value field:: - echo form_hidden('my_array', $data); + $data = array( + 'name' => 'John Doe', + 'email' => 'john@example.com', + 'url' => 'http://example.com' + ); - /* - Would produce: + echo form_hidden('my_array', $data); - <input type="hidden" name="my_array[name]" value="John Doe" /> - <input type="hidden" name="my_array[email]" value="john@example.com" /> - <input type="hidden" name="my_array[url]" value="http://example.com" /> - */ + /* + Would produce: -If you want to create hidden input fields with extra attributes:: + <input type="hidden" name="my_array[name]" value="John Doe" /> + <input type="hidden" name="my_array[email]" value="john@example.com" /> + <input type="hidden" name="my_array[url]" value="http://example.com" /> + */ - $data = array( - 'type' => 'hidden', - 'name' => 'email', - 'id' => 'hiddenemail', - 'value' => 'john@example.com', - 'class' => 'hiddenemail' - ); + If you want to create hidden input fields with extra attributes:: - echo form_input($data); + $data = array( + 'type' => 'hidden', + 'name' => 'email', + 'id' => 'hiddenemail', + 'value' => 'john@example.com', + 'class' => 'hiddenemail' + ); - /* - Would produce: + echo form_input($data); - <input type="hidden" name="email" value="john@example.com" id="hiddenemail" class="hiddenemail" /> - */ + /* + Would produce: -form_input() -============ + <input type="hidden" name="email" value="john@example.com" id="hiddenemail" class="hiddenemail" /> + */ -.. php:function:: form_input($data = '', $value = '', $extra = '') +.. function:: form_input([$data = ''[, $value = ''[, $extra = '']]) :param array $data: Field attributes data :param string $value: Field value :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string - -Lets you generate a standard text input field. You can minimally pass -the field name and value in the first and second parameter:: + :returns: An HTML text input field tag + :rtype: string - echo form_input('username', 'johndoe'); + Lets you generate a standard text input field. You can minimally pass + the field name and value in the first and second parameter:: -Or you can pass an associative array containing any data you wish your -form to contain:: + echo form_input('username', 'johndoe'); - $data = array( - 'name' => 'username', - 'id' => 'username', - 'value' => 'johndoe', - 'maxlength' => '100', - 'size' => '50', - 'style' => 'width:50%' - ); + Or you can pass an associative array containing any data you wish your + form to contain:: - echo form_input($data); + $data = array( + 'name' => 'username', + 'id' => 'username', + 'value' => 'johndoe', + 'maxlength' => '100', + 'size' => '50', + 'style' => 'width:50%' + ); - /* - Would produce: + echo form_input($data); - <input type="text" name="username" value="johndoe" id="username" maxlength="100" size="50" style="width:50%" /> - */ + /* + Would produce: -If you would like your form to contain some additional data, like -JavaScript, you can pass it as a string in the third parameter:: + <input type="text" name="username" value="johndoe" id="username" maxlength="100" size="50" style="width:50%" /> + */ - $js = 'onClick="some_function()"'; - echo form_input('username', 'johndoe', $js); + If you would like your form to contain some additional data, like + JavaScript, you can pass it as a string in the third parameter:: -form_password() -=============== + $js = 'onClick="some_function()"'; + echo form_input('username', 'johndoe', $js); -.. php:function:: form_password($data = '', $value = '', $extra = '') +.. function:: form_password([$data = ''[, $value = ''[, $extra = '']]]) :param array $data: Field attributes data :param string $value: Field value :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML password input field tag + :rtype: string -This function is identical in all respects to the :php:func:`form_input()` -function above except that it uses the "password" input type. + This function is identical in all respects to the :func:`form_input()` + function above except that it uses the "password" input type. -form_upload() -============= -.. php:function:: form_upload($data = '', $value = '', $extra = '') +.. function:: form_upload([$data = ''[, $value = ''[, $extra = '']]]) :param array $data: Field attributes data :param string $value: Field value :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML file upload input field tag + :rtype: string -This function is identical in all respects to the :php:func:`form_input()` -function above except that it uses the "file" input type, allowing it to -be used to upload files. + This function is identical in all respects to the :func:`form_input()` + function above except that it uses the "file" input type, allowing it to + be used to upload files. -form_textarea() -=============== -.. php:function:: form_textarea($data = '', $value = '', $extra = '') +.. function:: form_textarea([$data = ''[, $value = ''[, $extra = '']]]) :param array $data: Field attributes data :param string $value: Field value :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML textarea tag + :rtype: string -This function is identical in all respects to the :php:func:`form_input()` -function above except that it generates a "textarea" type. + This function is identical in all respects to the :func:`form_input()` + function above except that it generates a "textarea" type. -.. note: Instead of the *maxlength* and *size* attributes in the above example, - you will instead specify *rows* and *cols*. + .. note:: Instead of the *maxlength* and *size* attributes in the above example, + you will instead specify *rows* and *cols*. -form_dropdown() -=============== - -.. php:function:: form_dropdown($name = '', $options = array(), $selected = array(), $extra = '') +.. function:: form_dropdown([$name = ''[, $options = array()[, $selected = array()[, $extra = '']]]]) :param string $name: Field name :param array $options: An associative array of options to be listed :param array $selected: List of fields to mark with the *selected* attribute :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string - -Lets you create a standard drop-down field. The first parameter will -contain the name of the field, the second parameter will contain an -associative array of options, and the third parameter will contain the -value you wish to be selected. You can also pass an array of multiple -items through the third parameter, and CodeIgniter will create a -multiple select for you. - -Example:: - - $options = array( - 'small' => 'Small Shirt', - 'med' => 'Medium Shirt', - 'large' => 'Large Shirt', - 'xlarge' => 'Extra Large Shirt', - ); - - $shirts_on_sale = array('small', 'large'); - echo form_dropdown('shirts', $options, 'large'); - - /* - Would produce: - - <select name="shirts"> - <option value="small">Small Shirt</option> - <option value="med">Medium Shirt</option> - <option value="large" selected="selected">Large Shirt</option> - <option value="xlarge">Extra Large Shirt</option> - </select> - */ + :returns: An HTML dropdown select field tag + :rtype: string - echo form_dropdown('shirts', $options, $shirts_on_sale); + Lets you create a standard drop-down field. The first parameter will + contain the name of the field, the second parameter will contain an + associative array of options, and the third parameter will contain the + value you wish to be selected. You can also pass an array of multiple + items through the third parameter, and CodeIgniter will create a + multiple select for you. - /* - Would produce: + Example:: - <select name="shirts" multiple="multiple"> - <option value="small" selected="selected">Small Shirt</option> - <option value="med">Medium Shirt</option> - <option value="large" selected="selected">Large Shirt</option> - <option value="xlarge">Extra Large Shirt</option> - </select> - */ + $options = array( + 'small' => 'Small Shirt', + 'med' => 'Medium Shirt', + 'large' => 'Large Shirt', + 'xlarge' => 'Extra Large Shirt', + ); + + $shirts_on_sale = array('small', 'large'); + echo form_dropdown('shirts', $options, 'large'); + + /* + Would produce: + + <select name="shirts"> + <option value="small">Small Shirt</option> + <option value="med">Medium Shirt</option> + <option value="large" selected="selected">Large Shirt</option> + <option value="xlarge">Extra Large Shirt</option> + </select> + */ -If you would like the opening <select> to contain additional data, like -an id attribute or JavaScript, you can pass it as a string in the fourth -parameter:: + echo form_dropdown('shirts', $options, $shirts_on_sale); - $js = 'id="shirts" onChange="some_function();"'; - echo form_dropdown('shirts', $options, 'large', $js); + /* + Would produce: -If the array passed as ``$options`` is a multidimensional array, then -``form_dropdown()`` will produce an <optgroup> with the array key as the -label. + <select name="shirts" multiple="multiple"> + <option value="small" selected="selected">Small Shirt</option> + <option value="med">Medium Shirt</option> + <option value="large" selected="selected">Large Shirt</option> + <option value="xlarge">Extra Large Shirt</option> + </select> + */ -form_multiselect() -================== + If you would like the opening <select> to contain additional data, like + an id attribute or JavaScript, you can pass it as a string in the fourth + parameter:: -.. php:function:: form_multiselect($name = '', $options = array(), $selected = array(), $extra = '') + $js = 'id="shirts" onChange="some_function();"'; + echo form_dropdown('shirts', $options, 'large', $js); + + If the array passed as ``$options`` is a multidimensional array, then + ``form_dropdown()`` will produce an <optgroup> with the array key as the + label. + + +.. function:: form_multiselect([$name = ''[, $options = array()[, $selected = array()[, $extra = '']]]]) :param string $name: Field name :param array $options: An associative array of options to be listed :param array $selected: List of fields to mark with the *selected* attribute :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML dropdown multiselect field tag + :rtype: string -Lets you create a standard multiselect field. The first parameter will -contain the name of the field, the second parameter will contain an -associative array of options, and the third parameter will contain the -value or values you wish to be selected. + Lets you create a standard multiselect field. The first parameter will + contain the name of the field, the second parameter will contain an + associative array of options, and the third parameter will contain the + value or values you wish to be selected. -The parameter usage is identical to using :php:func:`form_dropdown()` above, -except of course that the name of the field will need to use POST array -syntax, e.g. foo[]. + The parameter usage is identical to using :func:`form_dropdown()` above, + except of course that the name of the field will need to use POST array + syntax, e.g. foo[]. -form_fieldset() -=============== -.. php:function:: form_fieldset($legend_text = '', $attributes = array()) +.. function:: form_fieldset([$legend_text = ''[, $attributes = array()]]) :param string $legend_text: Text to put in the <legend> tag :param array $attributes: Attributes to be set on the <fieldset> tag - :returns: string + :returns: An HTML fieldset opening tag + :rtype: string -Lets you generate fieldset/legend fields. + Lets you generate fieldset/legend fields. -Example:: + Example:: - echo form_fieldset('Address Information'); - echo "<p>fieldset content here</p>\n"; - echo form_fieldset_close(); + echo form_fieldset('Address Information'); + echo "<p>fieldset content here</p>\n"; + echo form_fieldset_close(); - /* - Produces: + /* + Produces: - <fieldset> - <legend>Address Information</legend> - <p>form content here</p> - </fieldset> - */ + <fieldset> + <legend>Address Information</legend> + <p>form content here</p> + </fieldset> + */ -Similar to other functions, you can submit an associative array in the -second parameter if you prefer to set additional attributes:: + Similar to other functions, you can submit an associative array in the + second parameter if you prefer to set additional attributes:: - $attributes = array( - 'id' => 'address_info', - 'class' => 'address_info' - ); + $attributes = array( + 'id' => 'address_info', + 'class' => 'address_info' + ); - echo form_fieldset('Address Information', $attributes); - echo "<p>fieldset content here</p>\n"; - echo form_fieldset_close(); + echo form_fieldset('Address Information', $attributes); + echo "<p>fieldset content here</p>\n"; + echo form_fieldset_close(); - /* - Produces: + /* + Produces: - <fieldset id="address_info" class="address_info"> - <legend>Address Information</legend> - <p>form content here</p> - </fieldset> - */ + <fieldset id="address_info" class="address_info"> + <legend>Address Information</legend> + <p>form content here</p> + </fieldset> + */ -form_fieldset_close() -===================== -.. php:function:: form_fieldset_close($extra = '') +.. function:: form_fieldset_close([$extra = '']) :param string $extra: Anything to append after the closing tag, *as is* - :returns: string + :returns: An HTML fieldset closing tag + :rtype: string + -Produces a closing </fieldset> tag. The only advantage to using this -function is it permits you to pass data to it which will be added below -the tag. For example + Produces a closing </fieldset> tag. The only advantage to using this + function is it permits you to pass data to it which will be added below + the tag. For example -:: + :: - $string = '</div></div>'; - echo form_fieldset_close($string); - // Would produce: </fieldset></div></div> + $string = '</div></div>'; + echo form_fieldset_close($string); + // Would produce: </fieldset></div></div> -form_checkbox() -=============== -.. php:function:: form_checkbox($data = '', $value = '', $checked = FALSE, $extra = '') +.. function:: form_checkbox([$data = ''[, $value = ''[, $checked = FALSE[, $extra = '']]]]) :param array $data: Field attributes data :param string $value: Field value :param bool $checked: Whether to mark the checkbox as being *checked* :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML checkbox input tag + :rtype: string -Lets you generate a checkbox field. Simple example:: + Lets you generate a checkbox field. Simple example:: - echo form_checkbox('newsletter', 'accept', TRUE); - // Would produce: <input type="checkbox" name="newsletter" value="accept" checked="checked" /> + echo form_checkbox('newsletter', 'accept', TRUE); + // Would produce: <input type="checkbox" name="newsletter" value="accept" checked="checked" /> -The third parameter contains a boolean TRUE/FALSE to determine whether -the box should be checked or not. + The third parameter contains a boolean TRUE/FALSE to determine whether + the box should be checked or not. -Similar to the other form functions in this helper, you can also pass an -array of attributes to the function:: + Similar to the other form functions in this helper, you can also pass an + array of attributes to the function:: - $data = array( - 'name' => 'newsletter', - 'id' => 'newsletter', - 'value' => 'accept', - 'checked' => TRUE, - 'style' => 'margin:10px' - ); + $data = array( + 'name' => 'newsletter', + 'id' => 'newsletter', + 'value' => 'accept', + 'checked' => TRUE, + 'style' => 'margin:10px' + ); - echo form_checkbox($data); - // Would produce: <input type="checkbox" name="newsletter" id="newsletter" value="accept" checked="checked" style="margin:10px" /> + echo form_checkbox($data); + // Would produce: <input type="checkbox" name="newsletter" id="newsletter" value="accept" checked="checked" style="margin:10px" /> -Also as with other functions, if you would like the tag to contain -additional data like JavaScript, you can pass it as a string in the -fourth parameter:: + Also as with other functions, if you would like the tag to contain + additional data like JavaScript, you can pass it as a string in the + fourth parameter:: - $js = 'onClick="some_function()"'; - echo form_checkbox('newsletter', 'accept', TRUE, $js) + $js = 'onClick="some_function()"'; + echo form_checkbox('newsletter', 'accept', TRUE, $js) -form_radio() -============ -.. php:function:: form_radio($data = '', $value = '', $checked = FALSE, $extra = '') +.. function:: form_radio([$data = ''[, $value = ''[, $checked = FALSE[, $extra = '']]]]) :param array $data: Field attributes data :param string $value: Field value :param bool $checked: Whether to mark the radio button as being *checked* :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML radio input tag + :rtype: string -This function is identical in all respects to the :php:func:`form_checkbox()` -function above except that it uses the "radio" input type. + This function is identical in all respects to the :func:`form_checkbox()` + function above except that it uses the "radio" input type. -form_label() -============ -.. php:function:: form_label($label_text = '', $id = '', $attributes = array()) +.. function:: form_label([$label_text = ''[, $id = ''[, $attributes = array()]]]) :param string $label_text: Text to put in the <label> tag :param string $id: ID of the form element that we're making a label for :param string $attributes: HTML attributes - :returns: string + :returns: An HTML field label tag + :rtype: string -Lets you generate a <label>. Simple example:: + Lets you generate a <label>. Simple example:: - echo form_label('What is your Name', 'username'); - // Would produce: <label for="username">What is your Name</label> + echo form_label('What is your Name', 'username'); + // Would produce: <label for="username">What is your Name</label> -Similar to other functions, you can submit an associative array in the -third parameter if you prefer to set additional attributes. + Similar to other functions, you can submit an associative array in the + third parameter if you prefer to set additional attributes. -Example:: + Example:: - $attributes = array( - 'class' => 'mycustomclass', - 'style' => 'color: #000;' - ); + $attributes = array( + 'class' => 'mycustomclass', + 'style' => 'color: #000;' + ); - echo form_label('What is your Name', 'username', $attributes); - // Would produce: <label for="username" class="mycustomclass" style="color: #000;">What is your Name</label> + echo form_label('What is your Name', 'username', $attributes); + // Would produce: <label for="username" class="mycustomclass" style="color: #000;">What is your Name</label> -form_submit() -============= -.. php:function:: form_submit($data = '', $value = '', $extra = '') +.. function:: form_submit([$data = ''[, $value = ''[, $extra = '']]]) :param string $data: Button name :param string $value: Button value :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML input submit tag + :rtype: string -Lets you generate a standard submit button. Simple example:: + Lets you generate a standard submit button. Simple example:: - echo form_submit('mysubmit', 'Submit Post!'); - // Would produce: <input type="submit" name="mysubmit" value="Submit Post!" /> + echo form_submit('mysubmit', 'Submit Post!'); + // Would produce: <input type="submit" name="mysubmit" value="Submit Post!" /> -Similar to other functions, you can submit an associative array in the -first parameter if you prefer to set your own attributes. The third -parameter lets you add extra data to your form, like JavaScript. + Similar to other functions, you can submit an associative array in the + first parameter if you prefer to set your own attributes. The third + parameter lets you add extra data to your form, like JavaScript. -form_reset() -============ -.. php:function:: form_reset($data = '', $value = '', $extra = '') +.. function:: form_reset([$data = ''[, $value = ''[, $extra = '']]]) :param string $data: Button name :param string $value: Button value :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML input reset button tag + :rtype: string -Lets you generate a standard reset button. Use is identical to -:php:func:`form_submit()`. + Lets you generate a standard reset button. Use is identical to + :func:`form_submit()`. -form_button() -============= -.. php:function:: form_button($data = '', $content = '', $extra = '') +.. function:: form_button([$data = ''[, $content = ''[, $extra = '']]]) :param string $data: Button name :param string $content: Button label :param string $extra: Extra attributes to be added to the tag *as is* - :returns: string + :returns: An HTML button tag + :rtype: string -Lets you generate a standard button element. You can minimally pass the -button name and content in the first and second parameter:: + Lets you generate a standard button element. You can minimally pass the + button name and content in the first and second parameter:: - echo form_button('name','content'); - // Would produce: <button name="name" type="button">Content</button> + echo form_button('name','content'); + // Would produce: <button name="name" type="button">Content</button> -Or you can pass an associative array containing any data you wish your -form to contain:: + Or you can pass an associative array containing any data you wish your + form to contain:: - $data = array( - 'name' => 'button', - 'id' => 'button', - 'value' => 'true', - 'type' => 'reset', - 'content' => 'Reset' - ); + $data = array( + 'name' => 'button', + 'id' => 'button', + 'value' => 'true', + 'type' => 'reset', + 'content' => 'Reset' + ); - echo form_button($data); - // Would produce: <button name="button" id="button" value="true" type="reset">Reset</button> + echo form_button($data); + // Would produce: <button name="button" id="button" value="true" type="reset">Reset</button> -If you would like your form to contain some additional data, like -JavaScript, you can pass it as a string in the third parameter:: + If you would like your form to contain some additional data, like + JavaScript, you can pass it as a string in the third parameter:: - $js = 'onClick="some_function()"'; - echo form_button('mybutton', 'Click Me', $js); + $js = 'onClick="some_function()"'; + echo form_button('mybutton', 'Click Me', $js); -form_close() -============ -.. php:function:: form_close($extra = '') +.. function:: form_close([$extra = '']) :param string $extra: Anything to append after the closing tag, *as is* - :returns: string + :returns: An HTML form closing tag + :rtype: string -Produces a closing </form> tag. The only advantage to using this -function is it permits you to pass data to it which will be added below -the tag. For example:: + Produces a closing </form> tag. The only advantage to using this + function is it permits you to pass data to it which will be added below + the tag. For example:: - $string = '</div></div>'; - echo form_close($string); - // Would produce: </form> </div></div> + $string = '</div></div>'; + echo form_close($string); + // Would produce: </form> </div></div> -form_prep() -=========== -.. php:function:: form_prep($str = '', $is_textarea = FALSE) +.. function:: form_prep([$str = ''[, $is_textarea = FALSE]]) :param string $str: Value to escape :param bool $is_textarea: Whether we're preparing for <textarea> or a regular input tag - :returns: string + :returns: Escaped value + :rtype: string -Allows you to safely use HTML and characters such as quotes within form -elements without breaking out of the form. + Allows you to safely use HTML and characters such as quotes within form + elements without breaking out of the form. -Consider this example:: + Consider this example:: - $string = 'Here is a string containing "quoted" text.'; - <input type="text" name="myform" value="$string" /> + $string = 'Here is a string containing "quoted" text.'; + <input type="text" name="myform" value="$string" /> -Since the above string contains a set of quotes it will cause the form -to break. The ``form_prep()`` function converts HTML so that it can be used -safely:: + Since the above string contains a set of quotes it will cause the form + to break. The ``form_prep()`` function converts HTML so that it can be used + safely:: - <input type="text" name="myform" value="<?php echo form_prep($string); ?>" /> + <input type="text" name="myform" value="<?php echo form_prep($string); ?>" /> -.. note:: If you use any of the form helper functions listed in this page the form - values will be prepped automatically, so there is no need to call this - function. Use it only if you are creating your own form elements. + .. note:: If you use any of the form helper functions listed in this page the form + values will be prepped automatically, so there is no need to call this + function. Use it only if you are creating your own form elements. -set_value() -=========== -.. php:function:: set_value($field = '', $default = '', $is_textarea = FALSE) +.. function:: set_value([$field = ''[, $default = ''[, $is_textarea = FALSE]]]) :param string $field: Field name :param string $default: Default value :param bool $is_textarea: Whether we're setting <textarea> content - :returns: string + :returns: Field value + :rtype: string -Permits you to set the value of an input form or textarea. You must -supply the field name via the first parameter of the function. The -second (optional) parameter allows you to set a default value for the -form. + Permits you to set the value of an input form or textarea. You must + supply the field name via the first parameter of the function. The + second (optional) parameter allows you to set a default value for the + form. -Example:: + Example:: - <input type="text" name="quantity" value="<?=set_value('quantity', '0');?>" size="50" /> + <input type="text" name="quantity" value="<?=set_value('quantity', '0');?>" size="50" /> -The above form will show "0" when loaded for the first time. + The above form will show "0" when loaded for the first time. -set_select() -============ -.. php:function:: set_select($field = '', $value = '', $default = FALSE) +.. function:: set_select([$field = ''[, $value = ''[, $default = FALSE]]]) :param string $field: Field name :param string $value: Value to check for :param string $default: Whether the value is also a default one - :returns: string - -If you use a <select> menu, this function permits you to display the -menu item that was selected. + :returns: 'selected' attribute or an empty string + :rtype: string -The first parameter must contain the name of the select menu, the second -parameter must contain the value of each item, and the third (optional) -parameter lets you set an item as the default (use boolean TRUE/FALSE). + If you use a <select> menu, this function permits you to display the + menu item that was selected. -Example:: + The first parameter must contain the name of the select menu, the second + parameter must contain the value of each item, and the third (optional) + parameter lets you set an item as the default (use boolean TRUE/FALSE). - <select name="myselect"> - <option value="one" <?php echo set_select('myselect', 'one', TRUE); ?> >One</option> - <option value="two" <?php echo set_select('myselect', 'two'); ?> >Two</option> - <option value="three" <?php echo set_select('myselect', 'three'); ?> >Three</option> - </select> + Example:: -set_checkbox() -============== + <select name="myselect"> + <option value="one" <?php echo set_select('myselect', 'one', TRUE); ?> >One</option> + <option value="two" <?php echo set_select('myselect', 'two'); ?> >Two</option> + <option value="three" <?php echo set_select('myselect', 'three'); ?> >Three</option> + </select> -.. php:function:: set_checkbox($field = '', $value = '', $default = FALSE) +.. function:: set_checkbox([$field = ''[, $value = ''[, $default = FALSE]]]) :param string $field: Field name :param string $value: Value to check for :param string $default: Whether the value is also a default one - :returns: string + :returns: 'checked' attribute or an empty string + :rtype: string -Permits you to display a checkbox in the state it was submitted. + Permits you to display a checkbox in the state it was submitted. -The first parameter must contain the name of the checkbox, the second -parameter must contain its value, and the third (optional) parameter -lets you set an item as the default (use boolean TRUE/FALSE). + The first parameter must contain the name of the checkbox, the second + parameter must contain its value, and the third (optional) parameter + lets you set an item as the default (use boolean TRUE/FALSE). -Example:: + Example:: - <input type="checkbox" name="mycheck" value="1" <?php echo set_checkbox('mycheck', '1'); ?> /> - <input type="checkbox" name="mycheck" value="2" <?php echo set_checkbox('mycheck', '2'); ?> /> + <input type="checkbox" name="mycheck" value="1" <?php echo set_checkbox('mycheck', '1'); ?> /> + <input type="checkbox" name="mycheck" value="2" <?php echo set_checkbox('mycheck', '2'); ?> /> -set_radio() -=========== - -.. php:function:: set_radio($field = '', $value = '', $default = FALSE) +.. function:: set_radio([$field = ''[, $value = ''[, $default = FALSE]]]) :param string $field: Field name :param string $value: Value to check for :param string $default: Whether the value is also a default one - :returns: string - -Permits you to display radio buttons in the state they were submitted. -This function is identical to the :php:func:`set_checkbox()` function above. + :returns: 'checked' attribute or an empty string + :rtype: string -Example:: + Permits you to display radio buttons in the state they were submitted. + This function is identical to the :func:`set_checkbox()` function above. - <input type="radio" name="myradio" value="1" <?php echo set_radio('myradio', '1', TRUE); ?> /> - <input type="radio" name="myradio" value="2" <?php echo set_radio('myradio', '2'); ?> /> + Example:: -.. note:: If you are using the Form Validation class, you must always specify - a rule for your field, even if empty, in order for the ``set_*()`` - functions to work. This is because if a Form Validation object is - defined, the control for ``set_*()`` is handed over to a method of the - class instead of the generic helper function. + <input type="radio" name="myradio" value="1" <?php echo set_radio('myradio', '1', TRUE); ?> /> + <input type="radio" name="myradio" value="2" <?php echo set_radio('myradio', '2'); ?> /> -form_error() -============ + .. note:: If you are using the Form Validation class, you must always specify + a rule for your field, even if empty, in order for the ``set_*()`` + functions to work. This is because if a Form Validation object is + defined, the control for ``set_*()`` is handed over to a method of the + class instead of the generic helper function. -.. php:function:: form_error($field = '', $prefix = '', $suffix = '') +.. function:: form_error([$field = ''[, $prefix = ''[, $suffix = '']]]) :param string $field: Field name :param string $prefix: Error opening tag :param string $suffix: Error closing tag - :returns: string + :returns: HTML-formatted form validation error message(s) + :rtype: string -Returns a validation error message from the :doc:`Form Validation Library -<../libraries/form_validation>`, associated with the specified field name. -You can optionally specify opening and closing tag(s) to put around the error -message. + Returns a validation error message from the :doc:`Form Validation Library + <../libraries/form_validation>`, associated with the specified field name. + You can optionally specify opening and closing tag(s) to put around the error + message. -Example:: + Example:: - // Assuming that the 'username' field value was incorrect: - echo form_error('myfield', '<div class="error">', '</div>'); + // Assuming that the 'username' field value was incorrect: + echo form_error('myfield', '<div class="error">', '</div>'); - // Would produce: <div class="error">Error message associated with the "username" field.</div> + // Would produce: <div class="error">Error message associated with the "username" field.</div> -validation_errors() -=================== -.. php:function:: validation_errors($prefix = '', $suffix = '') +.. function:: validation_errors([$prefix = ''[, $suffix = '']]) :param string $prefix: Error opening tag :param string $suffix: Error closing tag - :returns: string + :returns: HTML-formatted form validation error message(s) + :rtype: string -Similarly to the :php:func:`form_error()` function, returns all validation -error messages produced by the :doc:`Form Validation Library -<../libraries/form_validation>`, with optional opening and closing tags -around each of the messages. + Similarly to the :func:`form_error()` function, returns all validation + error messages produced by the :doc:`Form Validation Library + <../libraries/form_validation>`, with optional opening and closing tags + around each of the messages. -Example:: + Example:: - echo validation_errors('<span class="error">', '</span>'); + echo validation_errors('<span class="error">', '</span>'); - /* - Would produce, e.g.: + /* + Would produce, e.g.: - <span class="error">The "email" field doesn't contain a valid e-mail address!</span> - <span class="error">The "password" field doesn't match the "repeat_password" field!</span> + <span class="error">The "email" field doesn't contain a valid e-mail address!</span> + <span class="error">The "password" field doesn't match the "repeat_password" field!</span> - */
\ No newline at end of file + */
\ No newline at end of file diff --git a/user_guide_src/source/helpers/html_helper.rst b/user_guide_src/source/helpers/html_helper.rst index df53ebd2f..3324da8c0 100644 --- a/user_guide_src/source/helpers/html_helper.rst +++ b/user_guide_src/source/helpers/html_helper.rst @@ -5,7 +5,12 @@ HTML Helper The HTML Helper file contains functions that assist in working with HTML. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,94 +19,95 @@ This helper is loaded using the following code:: $this->load->helper('html'); +Available Functions +=================== + The following functions are available: -br() -==== -.. php:function:: br($count = 1) +.. function:: br([$count = 1]) :param int $count: Number of times to repeat the tag - :returns: string + :returns: HTML line break tag + :rtype: string -Generates line break tags (<br />) based on the number you submit. -Example:: + Generates line break tags (<br />) based on the number you submit. + Example:: - echo br(3); + echo br(3); -The above would produce: <br /><br /><br /> + The above would produce: -heading() -========= + .. code-block:: html -.. php:function:: heading($data = '', $h = '1', $attributes = '') + <br /><br /><br /> + +.. function:: heading([$data = ''[, $h = '1'[, $attributes = '']]]) :param string $data: Content :param string $h: Heading level :param array $attributes: HTML attributes - :returns: string + :returns: HTML heading tag + :rtype: string + + Lets you create HTML heading tags. The first parameter will contain the + data, the second the size of the heading. Example:: -Lets you create HTML heading tags. The first parameter will contain the -data, the second the size of the heading. Example:: + echo heading('Welcome!', 3); - echo heading('Welcome!', 3); + The above would produce: <h3>Welcome!</h3> -The above would produce: <h3>Welcome!</h3> + Additionally, in order to add attributes to the heading tag such as HTML + classes, ids or inline styles, a third parameter is available:: -Additionally, in order to add attributes to the heading tag such as HTML -classes, ids or inline styles, a third parameter is available:: + echo heading('Welcome!', 3, 'class="pink"') - echo heading('Welcome!', 3, 'class="pink"') + The above code produces: -The above code produces: <h3 class="pink">Welcome!<<h3> + .. code-block:: html -img() -===== + <h3 class="pink">Welcome!<h3> -.. php:function:: img($src = '', $index_page = FALSE, $attributes = '') +.. function:: img([$src = ''[, $index_page = FALSE[, $attributes = '']]]) :param string $src: Image source data :param bool $index_page: Whether to treat $src as a routed URI string :param array $attributes: HTML attributes - :returns: string - -Lets you create HTML <img /> tags. The first parameter contains the -image source. Example:: + :returns: HTML image tag + :rtype: string - echo img('images/picture.jpg'); // gives <img src="http://site.com/images/picture.jpg" /> + Lets you create HTML <img /> tags. The first parameter contains the + image source. Example:: -There is an optional second parameter that is a TRUE/FALSE value that -specifics if the *src* should have the page specified by -``$config['index_page']`` added to the address it creates. -Presumably, this would be if you were using a media controller:: + echo img('images/picture.jpg'); // gives <img src="http://site.com/images/picture.jpg" /> - echo img('images/picture.jpg', TRUE); // gives <img src="http://site.com/index.php/images/picture.jpg" alt="" /> + There is an optional second parameter that is a TRUE/FALSE value that + specifics if the *src* should have the page specified by + ``$config['index_page']`` added to the address it creates. + Presumably, this would be if you were using a media controller:: + echo img('images/picture.jpg', TRUE); // gives <img src="http://site.com/index.php/images/picture.jpg" alt="" /> -Additionally, an associative array can be passed to the ``img()`` function -for complete control over all attributes and values. If an *alt* attribute -is not provided, CodeIgniter will generate an empty string. + Additionally, an associative array can be passed to the ``img()`` function + for complete control over all attributes and values. If an *alt* attribute + is not provided, CodeIgniter will generate an empty string. -Example:: + Example:: - $image_properties = array(           - 'src' => 'images/picture.jpg',           - 'alt' => 'Me, demonstrating how to eat 4 slices of pizza at one time',  - 'class' => 'post_images',           - 'width' => '200',           - 'height'=> '200',           - 'title' => 'That was quite a night',           - 'rel' => 'lightbox' - ); + $image_properties = array( + 'src' => 'images/picture.jpg', + 'alt' => 'Me, demonstrating how to eat 4 slices of pizza at one time', + 'class' => 'post_images', + 'width' => '200', + 'height'=> '200', + 'title' => 'That was quite a night', + 'rel' => 'lightbox' + ); - img($image_properties); - // <img src="http://site.com/index.php/images/picture.jpg" alt="Me, demonstrating how to eat 4 slices of pizza at one time" class="post_images" width="200" height="200" title="That was quite a night" rel="lightbox" /> + img($image_properties); + // <img src="http://site.com/index.php/images/picture.jpg" alt="Me, demonstrating how to eat 4 slices of pizza at one time" class="post_images" width="200" height="200" title="That was quite a night" rel="lightbox" /> - -link_tag() -========== - -.. php:function:: ling_tag($href = '', $rel = 'stylesheet', $type = 'text/css', $title = '', $media = '', $index_page = FALSE) +.. function:: link_tag([$href = ''[, $rel = 'stylesheet'[, $type = 'text/css'[, $title = ''[, $media = ''[, $index_page = FALSE]]]]]]) :param string $href: What are we linking to :param string $rel: Relation type @@ -109,300 +115,284 @@ link_tag() :param string $title: Link title :param string $media: Media type :param bool $index_page: Whether to treat $src as a routed URI string - :returns: string - -Lets you create HTML <link /> tags. This is useful for stylesheet links, -as well as other links. The parameters are *href*, with optional *rel*, -*type*, *title*, *media* and *index_page*. + :returns: HTML link tag + :rtype: string -*index_page* is a boolean value that specifies if the *href* should have -the page specified by ``$config['index_page']`` added to the address it creates. + Lets you create HTML <link /> tags. This is useful for stylesheet links, + as well as other links. The parameters are *href*, with optional *rel*, + *type*, *title*, *media* and *index_page*. -Example:: + *index_page* is a boolean value that specifies if the *href* should have + the page specified by ``$config['index_page']`` added to the address it creates. - echo link_tag('css/mystyles.css'); - // gives <link href="http://site.com/css/mystyles.css" rel="stylesheet" type="text/css" /> + Example:: + echo link_tag('css/mystyles.css'); + // gives <link href="http://site.com/css/mystyles.css" rel="stylesheet" type="text/css" /> -Further examples:: + Further examples:: - echo link_tag('favicon.ico', 'shortcut icon', 'image/ico'); - // <link href="http://site.com/favicon.ico" rel="shortcut icon" type="image/ico" /> + echo link_tag('favicon.ico', 'shortcut icon', 'image/ico'); + // <link href="http://site.com/favicon.ico" rel="shortcut icon" type="image/ico" /> - echo link_tag('feed', 'alternate', 'application/rss+xml', 'My RSS Feed'); - // <link href="http://site.com/feed" rel="alternate" type="application/rss+xml" title="My RSS Feed" /> + echo link_tag('feed', 'alternate', 'application/rss+xml', 'My RSS Feed'); + // <link href="http://site.com/feed" rel="alternate" type="application/rss+xml" title="My RSS Feed" /> -Additionally, an associative array can be passed to the ``link()`` function -for complete control over all attributes and values:: + Additionally, an associative array can be passed to the ``link()`` function + for complete control over all attributes and values:: - $link = array(           - 'href' => 'css/printer.css', - 'rel' => 'stylesheet', - 'type' => 'text/css', - 'media' => 'print' - ); + $link = array( + 'href' => 'css/printer.css', + 'rel' => 'stylesheet', + 'type' => 'text/css', + 'media' => 'print' + ); - echo link_tag($link); - // <link href="http://site.com/css/printer.css" rel="stylesheet" type="text/css" media="print" /> + echo link_tag($link); + // <link href="http://site.com/css/printer.css" rel="stylesheet" type="text/css" media="print" /> -nbs() -===== - -.. php:function:: nbs($num = 1) +.. function:: nbs([$num = 1]) :param int $num: Number of space entities to produce - :returns: string + :returns: A sequence of non-breaking space HTML entities + :rtype: string + + Generates non-breaking spaces ( ) based on the number you submit. + Example:: -Generates non-breaking spaces ( ) based on the number you submit. -Example:: + echo nbs(3); - echo nbs(3); + The above would produce: -The above would produce:: + .. code-block:: html - + -ul() and ol() -============= -.. php:function:: ul($list, $attributes = '') +.. function:: ul($list[, $attributes = '']) :param array $list: List entries :param array $attributes: HTML attributes - :returns: string - -Permits you to generate ordered or unordered HTML lists from simple or -multi-dimensional arrays. Example:: + :returns: HTML-formatted unordered list + :rtype: string - $list = array( - 'red', - 'blue', - 'green', - 'yellow' - ); + Permits you to generate ordered or unordered HTML lists from simple or + multi-dimensional arrays. Example:: - $attributes = array( - 'class' => 'boldlist', - 'id' => 'mylist' - ); - - echo ul($list, $attributes); - -The above code will produce this:: - - <ul class="boldlist" id="mylist"> - <li>red</li> - <li>blue</li> - <li>green</li> - <li>yellow</li> - </ul> - -Here is a more complex example, using a multi-dimensional array:: - - $attributes = array( - 'class' => 'boldlist', - 'id' => 'mylist' - ); - - $list = array( - 'colors' => array( + $list = array( 'red', 'blue', - 'green' - ), - 'shapes' => array( - 'round', - 'square', - 'circles' => array( - 'ellipse', - 'oval', - 'sphere' - ) - ), - 'moods' => array( - 'happy', - 'upset' => array( - 'defeated' => array( - 'dejected', - 'disheartened', - 'depressed' - ), - 'annoyed', - 'cross', - 'angry' + 'green', + 'yellow' + ); + + $attributes = array( + 'class' => 'boldlist', + 'id' => 'mylist' + ); + + echo ul($list, $attributes); + + The above code will produce this: + + .. code-block:: html + + <ul class="boldlist" id="mylist"> + <li>red</li> + <li>blue</li> + <li>green</li> + <li>yellow</li> + </ul> + + Here is a more complex example, using a multi-dimensional array:: + + $attributes = array( + 'class' => 'boldlist', + 'id' => 'mylist' + ); + + $list = array( + 'colors' => array( + 'red', + 'blue', + 'green' + ), + 'shapes' => array( + 'round', + 'square', + 'circles' => array( + 'ellipse', + 'oval', + 'sphere' + ) + ), + 'moods' => array( + 'happy', + 'upset' => array( + 'defeated' => array( + 'dejected', + 'disheartened', + 'depressed' + ), + 'annoyed', + 'cross', + 'angry' + ) ) - ) - ); - - echo ul($list, $attributes); - -The above code will produce this:: - - <ul class="boldlist" id="mylist"> - <li>colors - <ul> - <li>red</li> - <li>blue</li> - <li>green</li> - </ul> - </li> - <li>shapes - <ul> - <li>round</li> - <li>suare</li> - <li>circles - <ul> - <li>elipse</li> - <li>oval</li> - <li>sphere</li> - </ul> - </li> - </ul> - </li> - <li>moods - <ul> - <li>happy</li> - <li>upset - <ul> - <li>defeated - <ul> - <li>dejected</li> - <li>disheartened</li> - <li>depressed</li> - </ul> - </li> - <li>annoyed</li> - <li>cross</li> - <li>angry</li> - </ul> - </li> - </ul> - </li> - </ul> - -.. php:function:: ol($list, $attributes = '') + ); + + echo ul($list, $attributes); + + The above code will produce this: + + .. code-block:: html + + <ul class="boldlist" id="mylist"> + <li>colors + <ul> + <li>red</li> + <li>blue</li> + <li>green</li> + </ul> + </li> + <li>shapes + <ul> + <li>round</li> + <li>suare</li> + <li>circles + <ul> + <li>elipse</li> + <li>oval</li> + <li>sphere</li> + </ul> + </li> + </ul> + </li> + <li>moods + <ul> + <li>happy</li> + <li>upset + <ul> + <li>defeated + <ul> + <li>dejected</li> + <li>disheartened</li> + <li>depressed</li> + </ul> + </li> + <li>annoyed</li> + <li>cross</li> + <li>angry</li> + </ul> + </li> + </ul> + </li> + </ul> + +.. function:: ol($list, $attributes = '') :param array $list: List entries :param array $attributes: HTML attributes - :returns: string + :returns: HTML-formatted ordered list + :rtype: string -Identical to :php:func:`ul()`, only it produces the <ol> tag for -ordered lists instead of <ul>. + Identical to :func:`ul()`, only it produces the <ol> tag for + ordered lists instead of <ul>. -meta() -====== - -.. php:function:: meta($name = '', $content = '', $type = 'name', $newline = "\n") +.. function:: meta([$name = ''[, $content = ''[, $type = 'name'[, $newline = "\n"]]]]) :param string $name: Meta name :param string $content: Meta content :param string $type: Meta type :param string $newline: Newline character - :returns: string - -Helps you generate meta tags. You can pass strings to the function, or -simple arrays, or multidimensional ones. - -Examples:: - - echo meta('description', 'My Great site'); - // Generates: <meta name="description" content="My Great Site" /> - - echo meta('Content-type', 'text/html; charset=utf-8', 'equiv'); - // Note the third parameter. Can be "equiv" or "name" - // Generates: <meta http-equiv="Content-type" content="text/html; charset=utf-8" /> - - echo meta(array('name' => 'robots', 'content' => 'no-cache')); - // Generates: <meta name="robots" content="no-cache" /> - - $meta = array( - array( - 'name' => 'robots', - 'content' => 'no-cache' - ), - array( - 'name' => 'description', - 'content' => 'My Great Site' - ), - array( - 'name' => 'keywords', - 'content' => 'love, passion, intrigue, deception' - ), - array( - 'name' => 'robots', - 'content' => 'no-cache' - ), - array( - 'name' => 'Content-type', - 'content' => 'text/html; charset=utf-8', 'type' => 'equiv' - ) - ); - - echo meta($meta); - // Generates: - // <meta name="robots" content="no-cache" /> - // <meta name="description" content="My Great Site" /> - // <meta name="keywords" content="love, passion, intrigue, deception" /> - // <meta name="robots" content="no-cache" /> - // <meta http-equiv="Content-type" content="text/html; charset=utf-8" /> - -doctype() -========= - -.. php:function:: doctype($type = 'xhtml1-strict') + :returns: HTML meta tag + :rtype: string + + Helps you generate meta tags. You can pass strings to the function, or + simple arrays, or multidimensional ones. + + Examples:: + + echo meta('description', 'My Great site'); + // Generates: <meta name="description" content="My Great Site" /> + + echo meta('Content-type', 'text/html; charset=utf-8', 'equiv'); + // Note the third parameter. Can be "equiv" or "name" + // Generates: <meta http-equiv="Content-type" content="text/html; charset=utf-8" /> + + echo meta(array('name' => 'robots', 'content' => 'no-cache')); + // Generates: <meta name="robots" content="no-cache" /> + + $meta = array( + array( + 'name' => 'robots', + 'content' => 'no-cache' + ), + array( + 'name' => 'description', + 'content' => 'My Great Site' + ), + array( + 'name' => 'keywords', + 'content' => 'love, passion, intrigue, deception' + ), + array( + 'name' => 'robots', + 'content' => 'no-cache' + ), + array( + 'name' => 'Content-type', + 'content' => 'text/html; charset=utf-8', 'type' => 'equiv' + ) + ); - :param string $type: Doctype name + echo meta($meta); + // Generates: + // <meta name="robots" content="no-cache" /> + // <meta name="description" content="My Great Site" /> + // <meta name="keywords" content="love, passion, intrigue, deception" /> + // <meta name="robots" content="no-cache" /> + // <meta http-equiv="Content-type" content="text/html; charset=utf-8" /> -Helps you generate document type declarations, or DTD's. XHTML 1.0 -Strict is used by default, but many doctypes are available. - -Example:: - - echo doctype(); // <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - - echo doctype('html4-trans'); // <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> - -The following is a list of doctype choices. These are configurable, and -pulled from application/config/doctypes.php - -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| Doctype | Option | Result | -+===============================+==============================+==================================================================================================================================================+ -| XHTML 1.1 | doctype('xhtml11') | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| XHTML 1.0 Strict | doctype('xhtml1-strict') | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| XHTML 1.0 Transitional | doctype('xhtml1-trans') | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| XHTML 1.0 Frameset | doctype('xhtml1-frame') | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| XHTML Basic 1.1 | doctype('xhtml-basic11') | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| HTML 5 | doctype('html5') | <!DOCTYPE html> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| HTML 4 Strict | doctype('html4-strict') | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| HTML 4 Transitional | doctype('html4-trans') | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| HTML 4 Frameset | doctype('html4-frame') | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| MathML 1.01 | doctype('mathml1') | <!DOCTYPE math SYSTEM "http://www.w3.org/Math/DTD/mathml1/mathml.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| MathML 2.0 | doctype('mathml2') | <!DOCTYPE math PUBLIC "-//W3C//DTD MathML 2.0//EN" "http://www.w3.org/Math/DTD/mathml2/mathml2.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| SVG 1.0 | doctype('svg10') | <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| SVG 1.1 Full | doctype('svg11') | <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| SVG 1.1 Basic | doctype('svg11-basic') | <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1 Basic//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-basic.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| SVG 1.1 Tiny | doctype('svg11-tiny') | <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1 Tiny//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-tiny.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| XHTML+MathML+SVG (XHTML host) | doctype('xhtml-math-svg-xh') | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN" "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| XHTML+MathML+SVG (SVG host) | doctype('xhtml-math-svg-sh') | <!DOCTYPE svg:svg PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN" "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| XHTML+RDFa 1.0 | doctype('xhtml-rdfa-1') | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ -| XHTML+RDFa 1.1 | doctype('xhtml-rdfa-2') | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.1//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-2.dtd"> | -+-------------------------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
\ No newline at end of file + +.. function:: doctype([$type = 'xhtml1-strict']) + + :param string $type: Doctype name + :returns: HTML DocType tag + :rtype: string + + Helps you generate document type declarations, or DTD's. XHTML 1.0 + Strict is used by default, but many doctypes are available. + + Example:: + + echo doctype(); // <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> + + echo doctype('html4-trans'); // <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> + + The following is a list of doctype choices. These are configurable, and + pulled from application/config/doctypes.php + + =============================== =================== ================================================================================================================================================== + Document type Option Result + =============================== =================== ================================================================================================================================================== + XHTML 1.1 xhtml11 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> + XHTML 1.0 Strict xhtml1-strict <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> + XHTML 1.0 Transitional xhtml1-trans <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + XHTML 1.0 Frameset xhtml1-frame <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd"> + XHTML Basic 1.1 xhtml-basic11 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"> + HTML 5 html5 <!DOCTYPE html> + HTML 4 Strict html4-strict <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> + HTML 4 Transitional html4-trans <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> + HTML 4 Frameset html4-frame <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd"> + MathML 1.01 mathml1 <!DOCTYPE math SYSTEM "http://www.w3.org/Math/DTD/mathml1/mathml.dtd"> + MathML 2.0 mathml2 <!DOCTYPE math PUBLIC "-//W3C//DTD MathML 2.0//EN" "http://www.w3.org/Math/DTD/mathml2/mathml2.dtd"> + SVG 1.0 svg10 <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd"> + SVG 1.1 Full svg11 <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> + SVG 1.1 Basic svg11-basic <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1 Basic//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-basic.dtd"> + SVG 1.1 Tiny svg11-tiny <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1 Tiny//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-tiny.dtd"> + XHTML+MathML+SVG (XHTML host) xhtml-math-svg-xh <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN" "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd"> + XHTML+MathML+SVG (SVG host) xhtml-math-svg-sh <!DOCTYPE svg:svg PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN" "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd"> + XHTML+RDFa 1.0 xhtml-rdfa-1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd"> + XHTML+RDFa 1.1 xhtml-rdfa-2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.1//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-2.dtd"> + =============================== =================== ==================================================================================================================================================
\ No newline at end of file diff --git a/user_guide_src/source/helpers/inflector_helper.rst b/user_guide_src/source/helpers/inflector_helper.rst index 1f54b76c0..d0cb17c18 100644 --- a/user_guide_src/source/helpers/inflector_helper.rst +++ b/user_guide_src/source/helpers/inflector_helper.rst @@ -5,7 +5,12 @@ Inflector Helper The Inflector Helper file contains functions that permits you to change words to plural, singular, camel case, etc. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,86 +19,78 @@ This helper is loaded using the following code:: $this->load->helper('inflector'); +Available Functions +=================== + The following functions are available: -singular() -========== -.. php:function:: singular($str) +.. function:: singular($str) :param string $str: Input string - :returns: string - -Changes a plural word to singular. Example:: + :returns: A singular word + :rtype: string - echo singular('dogs'); // Prints 'dog' + Changes a plural word to singular. Example:: -plural() -======== + echo singular('dogs'); // Prints 'dog' -.. php:function:: plural($str) +.. function:: plural($str) :param string $str: Input string - :returns: string + :returns: A plular word + :rtype: string -Changes a singular word to plural. Example:: + Changes a singular word to plural. Example:: - echo plural('dog'); // Prints 'dogs' + echo plural('dog'); // Prints 'dogs' -camelize() -========== - -.. php:function:: camelize($str) +.. function:: camelize($str) :param string $str: Input string - :returns: string - -Changes a string of words separated by spaces or underscores to camel -case. Example:: + :returns: Camelized string + :rtype: string - echo camelize('my_dog_spot'); // Prints 'myDogSpot' + Changes a string of words separated by spaces or underscores to camel + case. Example:: -underscore() -============ + echo camelize('my_dog_spot'); // Prints 'myDogSpot' -.. php:function:: camelize($str) +.. function:: underscore($str) :param string $str: Input string - :returns: string + :returns: String containing underscores instead of spaces + :rtype: string -Takes multiple words separated by spaces and underscores them. -Example:: + Takes multiple words separated by spaces and underscores them. + Example:: - echo underscore('my dog spot'); // Prints 'my_dog_spot' + echo underscore('my dog spot'); // Prints 'my_dog_spot' -humanize() -========== - -.. php:function:: camelize($str) +.. function:: humanize($str[, $separator = '_']) :param string $str: Input string :param string $separator: Input separator - :returns: string - -Takes multiple words separated by underscores and adds spaces between -them. Each word is capitalized. + :returns: Humanized string + :rtype: string -Example:: + Takes multiple words separated by underscores and adds spaces between + them. Each word is capitalized. - echo humanize('my_dog_spot'); // Prints 'My Dog Spot' + Example:: -To use dashes instead of underscores:: + echo humanize('my_dog_spot'); // Prints 'My Dog Spot' - echo humanize('my-dog-spot', '-'); // Prints 'My Dog Spot' + To use dashes instead of underscores:: -is_countable() -============== + echo humanize('my-dog-spot', '-'); // Prints 'My Dog Spot' -.. php:function:: is_countable($word) +.. function:: is_countable($word) :param string $word: Input string - :returns: bool + :returns: TRUE if the word is countable or FALSE if not + :rtype: bool -Checks if the given word has a plural version. Example:: + Checks if the given word has a plural version. Example:: - is_countable('equipment'); // Returns FALSE
\ No newline at end of file + is_countable('equipment'); // Returns FALSE
\ No newline at end of file diff --git a/user_guide_src/source/helpers/language_helper.rst b/user_guide_src/source/helpers/language_helper.rst index 1911e3bfd..e4d093725 100644 --- a/user_guide_src/source/helpers/language_helper.rst +++ b/user_guide_src/source/helpers/language_helper.rst @@ -5,7 +5,12 @@ Language Helper The Language Helper file contains functions that assist in working with language files. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,23 +19,25 @@ This helper is loaded using the following code:: $this->load->helper('language'); +Available Functions +=================== + The following functions are available: -lang() -====== -.. php:function:: lang($line, $for = '', $attributes = array()) +.. function:: lang($line[, $for = ''[, $attributes = array()]]) - :param string $line: Language line key - :param string $for: HTML "for" attribute (ID of the element we're creating a label for) - :param array $attributes: Any additional HTML attributes - :returns: string + :param string $line: Language line key + :param string $for: HTML "for" attribute (ID of the element we're creating a label for) + :param array $attributes: Any additional HTML attributes + :returns: HTML-formatted language line label + :rtype: string -This function returns a line of text from a loaded language file with -simplified syntax that may be more desirable for view files than -``CI_Lang::line()``. + This function returns a line of text from a loaded language file with + simplified syntax that may be more desirable for view files than + ``CI_Lang::line()``. -Example:: + Example:: - echo lang('language_key', 'form_item_id', array('class' => 'myClass'); - // Outputs: <label for="form_item_id" class="myClass">Language line</label>
\ No newline at end of file + echo lang('language_key', 'form_item_id', array('class' => 'myClass')); + // Outputs: <label for="form_item_id" class="myClass">Language line</label>
\ No newline at end of file diff --git a/user_guide_src/source/helpers/number_helper.rst b/user_guide_src/source/helpers/number_helper.rst index 8e0ebda5e..2de4457d9 100644 --- a/user_guide_src/source/helpers/number_helper.rst +++ b/user_guide_src/source/helpers/number_helper.rst @@ -5,7 +5,12 @@ Number Helper The Number Helper file contains functions that help you work with numeric data. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,32 +19,34 @@ This helper is loaded using the following code:: $this->load->helper('number'); +Available Functions +=================== + The following functions are available: -byte_format() -============= -.. php:function:: byte_format($num, $precision = 1) +.. function:: byte_format($num[, $precision = 1]) :param mixed $num: Number of bytes :param int $precision: Floating point precision - :returns: string - -Formats numbers as bytes, based on size, and adds the appropriate -suffix. Examples:: - - echo byte_format(456); // Returns 456 Bytes - echo byte_format(4567); // Returns 4.5 KB - echo byte_format(45678); // Returns 44.6 KB - echo byte_format(456789); // Returns 447.8 KB - echo byte_format(3456789); // Returns 3.3 MB - echo byte_format(12345678912345); // Returns 1.8 GB - echo byte_format(123456789123456789); // Returns 11,228.3 TB - -An optional second parameter allows you to set the precision of the -result:: - - echo byte_format(45678, 2); // Returns 44.61 KB - -.. note:: The text generated by this function is found in the following - language file: `language/<your_lang>/number_lang.php`
\ No newline at end of file + :returns: Formatted data size string + :rtype: string + + Formats numbers as bytes, based on size, and adds the appropriate + suffix. Examples:: + + echo byte_format(456); // Returns 456 Bytes + echo byte_format(4567); // Returns 4.5 KB + echo byte_format(45678); // Returns 44.6 KB + echo byte_format(456789); // Returns 447.8 KB + echo byte_format(3456789); // Returns 3.3 MB + echo byte_format(12345678912345); // Returns 1.8 GB + echo byte_format(123456789123456789); // Returns 11,228.3 TB + + An optional second parameter allows you to set the precision of the + result:: + + echo byte_format(45678, 2); // Returns 44.61 KB + + .. note:: The text generated by this function is found in the following + language file: *language/<your_lang>/number_lang.php*
\ No newline at end of file diff --git a/user_guide_src/source/helpers/path_helper.rst b/user_guide_src/source/helpers/path_helper.rst index 3a271b28f..705ca23b9 100644 --- a/user_guide_src/source/helpers/path_helper.rst +++ b/user_guide_src/source/helpers/path_helper.rst @@ -5,7 +5,12 @@ Path Helper The Path Helper file contains functions that permits you to work with file paths on the server. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,33 +19,35 @@ This helper is loaded using the following code:: $this->load->helper('path'); +Available Functions +=================== + The following functions are available: -set_realpath() -============== -.. php:function:: set_realpath($path, $check_existance = FALSE) +.. function:: set_realpath($path[, $check_existance = FALSE]) :param string $path: Path :param bool $check_existance: Whether to check if the path actually exists - :returns: string + :returns: An absolute path + :rtype: string + + This function will return a server path without symbolic links or + relative directory structures. An optional second argument will + cause an error to be triggered if the path cannot be resolved. -This function will return a server path without symbolic links or -relative directory structures. An optional second argument will -cause an error to be triggered if the path cannot be resolved. + Examples:: -Examples:: + $file = '/etc/php5/apache2/php.ini'; + echo set_realpath($file); // Prints '/etc/php5/apache2/php.ini' - $file = '/etc/php5/apache2/php.ini'; - echo set_realpath($file); // Prints '/etc/php5/apache2/php.ini' + $non_existent_file = '/path/to/non-exist-file.txt'; + echo set_realpath($non_existent_file, TRUE); // Shows an error, as the path cannot be resolved + echo set_realpath($non_existent_file, FALSE); // Prints '/path/to/non-exist-file.txt' - $non_existent_file = '/path/to/non-exist-file.txt'; - echo set_realpath($non_existent_file, TRUE); // Shows an error, as the path cannot be resolved - echo set_realpath($non_existent_file, FALSE); // Prints '/path/to/non-exist-file.txt' + $directory = '/etc/php5'; + echo set_realpath($directory); // Prints '/etc/php5/' - $directory = '/etc/php5'; - echo set_realpath($directory); // Prints '/etc/php5/' - - $non_existent_directory = '/path/to/nowhere'; - echo set_realpath($non_existent_directory, TRUE); // Shows an error, as the path cannot be resolved - echo set_realpath($non_existent_directory, FALSE); // Prints '/path/to/nowhere'
\ No newline at end of file + $non_existent_directory = '/path/to/nowhere'; + echo set_realpath($non_existent_directory, TRUE); // Shows an error, as the path cannot be resolved + echo set_realpath($non_existent_directory, FALSE); // Prints '/path/to/nowhere'
\ No newline at end of file diff --git a/user_guide_src/source/helpers/security_helper.rst b/user_guide_src/source/helpers/security_helper.rst index 21bf53490..2e26890b0 100644 --- a/user_guide_src/source/helpers/security_helper.rst +++ b/user_guide_src/source/helpers/security_helper.rst @@ -4,7 +4,12 @@ Security Helper The Security Helper file contains security related functions. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -13,92 +18,89 @@ This helper is loaded using the following code:: $this->load->helper('security'); +Available Functions +=================== + The following functions are available: -xss_clean() -=========== -.. php:function:: xss_clean($str, $is_image = FALSE) +.. function:: xss_clean($str[, $is_image = FALSE]) :param string $str: Input data :param bool $is_image: Whether we're dealing with an image - :returns: string + :returns: XSS-clean string + :rtype: string -Provides Cross Site Script Hack filtering. + Provides Cross Site Script Hack filtering. -This function is an alias for ``CI_Input::xss_clean()``. For more info, -please see the :doc:`Input Library <../libraries/input>` documentation. + This function is an alias for ``CI_Input::xss_clean()``. For more info, + please see the :doc:`Input Library <../libraries/input>` documentation. -sanitize_filename() -=================== - -.. php:function:: sanitize_filename($filename) +.. function:: sanitize_filename($filename) :param string $filename: Filename - :returns: string + :returns: Sanitized file name + :rtype: string -Provides protection against directory traversal. + Provides protection against directory traversal. -This function is an alias for ``CI_Security::sanitize_filename()``. -For more info, please see the :doc:`Security Library <../libraries/security>` -documentation. + This function is an alias for ``CI_Security::sanitize_filename()``. + For more info, please see the :doc:`Security Library <../libraries/security>` + documentation. -do_hash() -========= -.. php:function:: do_hash($str, $type = 'sha1') +.. function:: do_hash($str[, $type = 'sha1']) :param string $str: Input :param string $type: Algorithm - :returns: string + :returns: Hex-formatted hash + :rtype: string -Permits you to create one way hashes suitable for encrypting -passwords. Will use SHA1 by default. + Permits you to create one way hashes suitable for encrypting + passwords. Will use SHA1 by default. -See `hash_algos() <http://php.net/function.hash_algos>`_ -for a full list of supported algorithms. + See `hash_algos() <http://php.net/function.hash_algos>`_ + for a full list of supported algorithms. -Examples:: + Examples:: - $str = do_hash($str); // SHA1 - $str = do_hash($str, 'md5'); // MD5 + $str = do_hash($str); // SHA1 + $str = do_hash($str, 'md5'); // MD5 -.. note:: This function was formerly named ``dohash()``, which has been - removed in favor of ``do_hash()``. + .. note:: This function was formerly named ``dohash()``, which has been + removed in favor of ``do_hash()``. -.. note:: This function is DEPRECATED. Use the native ``hash()`` instead. + .. note:: This function is DEPRECATED. Use the native ``hash()`` instead. -strip_image_tags() -================== -.. php:function:: strip_image_tags($str) +.. function:: strip_image_tags($str) - :param string $str: Input - :returns: string + :param string $str: Input string + :returns: The input string with no image tags + :rtype: string -This is a security function that will strip image tags from a string. -It leaves the image URL as plain text. + This is a security function that will strip image tags from a string. + It leaves the image URL as plain text. -Example:: + Example:: - $string = strip_image_tags($string); + $string = strip_image_tags($string); -This function is an alias for ``CI_Security::strip_image_tags()``. For -more info, please see the :doc:`Security Library <../libraries/security>` -documentation. + This function is an alias for ``CI_Security::strip_image_tags()``. For + more info, please see the :doc:`Security Library <../libraries/security>` + documentation. -encode_php_tags() -================= -.. php:function:: encode_php_tags($str) +.. function:: encode_php_tags($str) - :param string $str: Input - :returns: string + :param string $str: Input string + :returns: Safely formatted string + :rtype: string -This is a security function that converts PHP tags to entities. + This is a security function that converts PHP tags to entities. -.. note: :php:func:`xss_clean()` does this automatically, if you use it. + .. note:: :func:`xss_clean()` does this automatically, if you use it. -Example:: + Example:: - $string = encode_php_tags($string);
\ No newline at end of file + $string = encode_php_tags($string);
\ No newline at end of file diff --git a/user_guide_src/source/helpers/smiley_helper.rst b/user_guide_src/source/helpers/smiley_helper.rst index cfd52ffbc..b98084089 100644 --- a/user_guide_src/source/helpers/smiley_helper.rst +++ b/user_guide_src/source/helpers/smiley_helper.rst @@ -5,7 +5,12 @@ Smiley Helper The Smiley Helper file contains functions that let you manage smileys (emoticons). -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -46,7 +51,7 @@ The Controller In your **application/controllers/** directory, create a file called Smileys.php and place the code below in it. -.. important:: Change the URL in the :php:func:`get_clickable_smileys()` +.. important:: Change the URL in the :func:`get_clickable_smileys()` function below so that it points to your smiley folder. You'll notice that in addition to the smiley helper, we are also using @@ -100,65 +105,62 @@ links a generic name that will be tied to a specific id in your view. $image_array = get_smiley_links("http://example.com/images/smileys/", "comment_textarea_alias"); To map the alias to the field id, pass them both into the -:php:func:`smiley_js()` function:: +:func:`smiley_js()` function:: $image_array = smiley_js("comment_textarea_alias", "comments"); -get_clickable_smileys() -======================= +Available Functions +=================== -.. php:function:: get_clickable_smileys($image_url, $alias = '', $smileys = NULL) +.. function:: get_clickable_smileys($image_url[, $alias = ''[, $smileys = NULL]]) :param string $image_url: URL path to the smileys directory :param string $alias: Field alias - :returns: array + :returns: An array of ready to use smileys + :rtype: array -Returns an array containing your smiley images wrapped in a clickable -link. You must supply the URL to your smiley folder and a field id or -field alias. + Returns an array containing your smiley images wrapped in a clickable + link. You must supply the URL to your smiley folder and a field id or + field alias. -Example:: + Example:: - $image_array = get_smiley_links("http://example.com/images/smileys/", "comment"); + $image_array = get_clickable_smileys('http://example.com/images/smileys/', 'comment'); -smiley_js() -=========== - -.. php:function:: smiley_js($alias = '', $field_id = '', $inline = TRUE) +.. function:: smiley_js([$alias = ''[, $field_id = ''[, $inline = TRUE]]]) :param string $alias: Field alias :param string $field_id: Field ID :param bool $inline: Whether we're inserting an inline smiley + :returns: Smiley-enabling JavaScript code + :rtype: string -Generates the JavaScript that allows the images to be clicked and -inserted into a form field. If you supplied an alias instead of an id -when generating your smiley links, you need to pass the alias and -corresponding form id into the function. This function is designed to be -placed into the <head> area of your web page. - -Example:: + Generates the JavaScript that allows the images to be clicked and + inserted into a form field. If you supplied an alias instead of an id + when generating your smiley links, you need to pass the alias and + corresponding form id into the function. This function is designed to be + placed into the <head> area of your web page. - <?php echo smiley_js(); ?> + Example:: -parse_smileys() -=============== + <?php echo smiley_js(); ?> -.. php:function:: parse_smileys($str = '', $image_url = '', $smileys = NULL) +.. function:: parse_smileys([$str = ''[, $image_url = ''[, $smileys = NULL]]]) :param string $str: Text containing smiley codes :param string $image_url: URL path to the smileys directory :param array $smileys: An array of smileys - :returns: string - -Takes a string of text as input and replaces any contained plain text -smileys into the image equivalent. The first parameter must contain your -string, the second must contain the URL to your smiley folder + :returns: Parsed smileys + :rtype: string -Example:: + Takes a string of text as input and replaces any contained plain text + smileys into the image equivalent. The first parameter must contain your + string, the second must contain the URL to your smiley folder - $str = 'Here are some smileys: :-) ;-)'; - $str = parse_smileys($str, "http://example.com/images/smileys/"); - echo $str; + Example:: + $str = 'Here are some smileys: :-) ;-)'; + $str = parse_smileys($str, 'http://example.com/images/smileys/'); + echo $str; .. |smile!| image:: ../images/smile.gif
\ No newline at end of file diff --git a/user_guide_src/source/helpers/string_helper.rst b/user_guide_src/source/helpers/string_helper.rst index d0d302476..922bc6b8d 100644 --- a/user_guide_src/source/helpers/string_helper.rst +++ b/user_guide_src/source/helpers/string_helper.rst @@ -5,7 +5,12 @@ String Helper The String Helper file contains functions that assist in working with strings. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,214 +19,202 @@ This helper is loaded using the following code:: $this->load->helper('string'); +Available Functions +=================== + The following functions are available: -random_string() -=============== -.. php:function:: random_string($type = 'alnum', $len = 8) +.. function:: random_string([$type = 'alnum'[, $len = 8]]) :param string $type: Randomization type :param int $len: Output string length - :returns: string - -Generates a random string based on the type and length you specify. -Useful for creating passwords or generating random hashes. + :returns: A random string + :rtype: string -The first parameter specifies the type of string, the second parameter -specifies the length. The following choices are available: + Generates a random string based on the type and length you specify. + Useful for creating passwords or generating random hashes. -- **alpha**: A string with lower and uppercase letters only. -- **alnum**: Alpha-numeric string with lower and uppercase characters. -- **basic**: A random number based on ``mt_rand()``. -- **numeric**: Numeric string. -- **nozero**: Numeric string with no zeros. -- **md5**: An encrypted random number based on ``md5()`` (fixed length of 32). -- **sha1**: An encrypted random number based on ``sha1()`` (fixed length of 40). + The first parameter specifies the type of string, the second parameter + specifies the length. The following choices are available: -Usage example:: + - **alpha**: A string with lower and uppercase letters only. + - **alnum**: Alpha-numeric string with lower and uppercase characters. + - **basic**: A random number based on ``mt_rand()``. + - **numeric**: Numeric string. + - **nozero**: Numeric string with no zeros. + - **md5**: An encrypted random number based on ``md5()`` (fixed length of 32). + - **sha1**: An encrypted random number based on ``sha1()`` (fixed length of 40). - echo random_string('alnum', 16); + Usage example:: -.. note:: Usage of the *unique* and *encrypt* types is DEPRECATED. They - are just aliases for *md5* and *sha1* respectively. + echo random_string('alnum', 16); -increment_string() -================== + .. note:: Usage of the *unique* and *encrypt* types is DEPRECATED. They + are just aliases for *md5* and *sha1* respectively. -.. php:function:: increment_string($str, $separator = '_', $first = 1) +.. function:: increment_string($str[, $separator = '_'[, $first = 1]]) :param string $str: Input string :param string $separator: Separator to append a duplicate number with :param int $first: Starting number - :returns: string + :returns: An incremented string + :rtype: string -Increments a string by appending a number to it or increasing the -number. Useful for creating "copies" or a file or duplicating database -content which has unique titles or slugs. + Increments a string by appending a number to it or increasing the + number. Useful for creating "copies" or a file or duplicating database + content which has unique titles or slugs. -Usage example:: + Usage example:: - echo increment_string('file', '_'); // "file_1" - echo increment_string('file', '-', 2); // "file-2" - echo increment_string('file_4'); // "file_5" + echo increment_string('file', '_'); // "file_1" + echo increment_string('file', '-', 2); // "file-2" + echo increment_string('file_4'); // "file_5" -alternator() -============ -.. php:function:: alternator($args) +.. function:: alternator($args) :param mixed $args: A variable number of arguments - :returns: mixed + :returns: Alternated string(s) + :rtype: mixed -Allows two or more items to be alternated between, when cycling through -a loop. Example:: + Allows two or more items to be alternated between, when cycling through + a loop. Example:: - for ($i = 0; $i < 10; $i++) - { Â Â Â Â - echo alternator('string one', 'string two'); - } + for ($i = 0; $i < 10; $i++) + { Â Â Â Â + echo alternator('string one', 'string two'); + } -You can add as many parameters as you want, and with each iteration of -your loop the next item will be returned. + You can add as many parameters as you want, and with each iteration of + your loop the next item will be returned. -:: + :: - for ($i = 0; $i < 10; $i++) - { Â Â Â Â - echo alternator('one', 'two', 'three', 'four', 'five'); - } + for ($i = 0; $i < 10; $i++) + { Â Â Â Â + echo alternator('one', 'two', 'three', 'four', 'five'); + } -.. note:: To use multiple separate calls to this function simply call the - function with no arguments to re-initialize. + .. note:: To use multiple separate calls to this function simply call the + function with no arguments to re-initialize. -repeater() -========== - -.. php:function:: repeater($data, $num = 1) +.. function:: repeater($data[, $num = 1]) :param string $data: Input :param int $num: Number of times to repeat - :returns: string + :returns: Repeated string + :rtype: string -Generates repeating copies of the data you submit. Example:: + Generates repeating copies of the data you submit. Example:: - $string = "\n"; - echo repeater($string, 30); + $string = "\n"; + echo repeater($string, 30); -The above would generate 30 newlines. + The above would generate 30 newlines. -.. note:: This function is DEPRECATED. Use the native ``str_repeat()`` - instead. + .. note:: This function is DEPRECATED. Use the native ``str_repeat()`` + instead. -reduce_double_slashes() -======================= -.. php:function:: reduce_double_slashes($str) +.. function:: reduce_double_slashes($str) :param string $str: Input string - :returns: string + :returns: A string with normalized slashes + :rtype: string -Converts double slashes in a string to a single slash, except those -found in URL protocol prefixes (e.g. http://). + Converts double slashes in a string to a single slash, except those + found in URL protocol prefixes (e.g. http://). -Example:: + Example:: - $string = "http://example.com//index.php"; - echo reduce_double_slashes($string); // results in "http://example.com/index.php" + $string = "http://example.com//index.php"; + echo reduce_double_slashes($string); // results in "http://example.com/index.php" -strip_slashes() -=============== -.. php:function:: strip_slashes($data) +.. function:: strip_slashes($data) - :param array $data: Input - :returns: array + :param mixed $data: Input string or an array of strings + :returns: String(s) with stripped slashes + :rtype: mixed -Removes any slashes from an array of strings. + Removes any slashes from an array of strings. -Example:: - - $str = array( - 'question'Â Â => 'Is your name O\'reilly?', - 'answer' => 'No, my name is O\'connor.' - ); - - $str = strip_slashes($str); - -The above will return the following array:: + Example:: - array( - 'question'Â Â => "Is your name O'reilly?", - 'answer' => "No, my name is O'connor." - ); + $str = array( + 'question'Â Â => 'Is your name O\'reilly?', + 'answer' => 'No, my name is O\'connor.' + ); -.. note:: For historical reasons, this function will also accept - and handle string inputs. This however makes it just an - alias for ``stripslashes()``. + $str = strip_slashes($str); -trim_slashes() -============== + The above will return the following array:: -.. php:function:: trim_slashes($str) + array( + 'question'Â Â => "Is your name O'reilly?", + 'answer' => "No, my name is O'connor." + ); - :param string $str: Input string - :returns: string + .. note:: For historical reasons, this function will also accept + and handle string inputs. This however makes it just an + alias for ``stripslashes()``. -Removes any leading/trailing slashes from a string. Example:: +.. function:: trim_slashes($str) - $string = "/this/that/theother/"; - echo trim_slashes($string); // results in this/that/theother + :param string $str: Input string + :returns: Slash-trimmed string + :rtype: string -.. note:: This function is DEPRECATED. Use the native ``trim()`` instead: - | - | trim($str, '/'); + Removes any leading/trailing slashes from a string. Example:: -reduce_multiples() -================== + $string = "/this/that/theother/"; + echo trim_slashes($string); // results in this/that/theother -.. php:function:: reduce_multiples($str, $character = '', $trim = FALSE) + .. note:: This function is DEPRECATED. Use the native ``trim()`` instead: + | + | trim($str, '/'); + +.. function:: reduce_multiples($str[, $character = ''[, $trim = FALSE]]) :param string $str: Text to search in :param string $character: Character to reduce :param bool $trim: Whether to also trim the specified character - :returns: string - -Reduces multiple instances of a particular character occuring directly -after each other. Example:: + :returns: Reduced string + :rtype: string - $string = "Fred, Bill,, Joe, Jimmy"; - $string = reduce_multiples($string,","); //results in "Fred, Bill, Joe, Jimmy" + Reduces multiple instances of a particular character occuring directly + after each other. Example:: -If the third parameter is set to TRUE it will remove occurences of the -character at the beginning and the end of the string. Example:: + $string = "Fred, Bill,, Joe, Jimmy"; + $string = reduce_multiples($string,","); //results in "Fred, Bill, Joe, Jimmy" - $string = ",Fred, Bill,, Joe, Jimmy,"; - $string = reduce_multiples($string, ", ", TRUE); //results in "Fred, Bill, Joe, Jimmy" + If the third parameter is set to TRUE it will remove occurrences of the + character at the beginning and the end of the string. Example:: -quotes_to_entities() -==================== + $string = ",Fred, Bill,, Joe, Jimmy,"; + $string = reduce_multiples($string, ", ", TRUE); //results in "Fred, Bill, Joe, Jimmy" -.. php:function:: quotes_to_entities($str) +.. function:: quotes_to_entities($str) :param string $str: Input string - :returns: string + :returns: String with quotes converted to HTML entities + :rtype: string -Converts single and double quotes in a string to the corresponding HTML -entities. Example:: + Converts single and double quotes in a string to the corresponding HTML + entities. Example:: - $string = "Joe's \"dinner\""; - $string = quotes_to_entities($string); //results in "Joe's "dinner"" + $string = "Joe's \"dinner\""; + $string = quotes_to_entities($string); //results in "Joe's "dinner"" -strip_quotes() -============== -.. php:function:: strip_quotes($str) +.. function:: strip_quotes($str) :param string $str: Input string - :returns: string + :returns: String with quotes stripped + :rtype: string -Removes single and double quotes from a string. Example:: + Removes single and double quotes from a string. Example:: - $string = "Joe's \"dinner\""; - $string = strip_quotes($string); //results in "Joes dinner"
\ No newline at end of file + $string = "Joe's \"dinner\""; + $string = strip_quotes($string); //results in "Joes dinner"
\ No newline at end of file diff --git a/user_guide_src/source/helpers/text_helper.rst b/user_guide_src/source/helpers/text_helper.rst index aec36c9a7..88a6d0658 100644 --- a/user_guide_src/source/helpers/text_helper.rst +++ b/user_guide_src/source/helpers/text_helper.rst @@ -5,7 +5,12 @@ Text Helper The Text Helper file contains functions that assist in working with text. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,216 +19,208 @@ This helper is loaded using the following code:: $this->load->helper('text'); -The following functions are available: +Available Functions +=================== -word_limiter() -============== +The following functions are available: -.. php:function:: word_limiter($str, $limit = 100, $end_char = '…') +.. function:: word_limiter($str[, $limit = 100[, $end_char = '…']]) :param string $str: Input string :param int $limit: Limit :param string $end_char: End character (usually an ellipsis) - :returns: string + :returns: Word-limited string + :rtype: string -Truncates a string to the number of *words* specified. Example:: + Truncates a string to the number of *words* specified. Example:: - $string = "Here is a nice text string consisting of eleven words."; - $string = word_limiter($string, 4); - // Returns: Here is a nice… + $string = "Here is a nice text string consisting of eleven words."; + $string = word_limiter($string, 4); + // Returns: Here is a nice -The third parameter is an optional suffix added to the string. By -default it adds an ellipsis. + The third parameter is an optional suffix added to the string. By + default it adds an ellipsis. -character_limiter() -=================== -.. php:function:: character_limiter($str, $n = 500, $end_char = '…') +.. function:: character_limiter($str[, $n = 500[, $end_char = '…']]) :param string $str: Input string :param int $n: Number of characters :param string $end_char: End character (usually an ellipsis) - :returns: string + :returns: Character-limited string + :rtype: string -Truncates a string to the number of *characters* specified. It -maintains the integrity of words so the character count may be slightly -more or less then what you specify. + Truncates a string to the number of *characters* specified. It + maintains the integrity of words so the character count may be slightly + more or less than what you specify. -Example:: + Example:: - $string = "Here is a nice text string consisting of eleven words."; - $string = character_limiter($string, 20); - // Returns: Here is a nice text string… + $string = "Here is a nice text string consisting of eleven words."; + $string = character_limiter($string, 20); + // Returns: Here is a nice text string -The third parameter is an optional suffix added to the string, if -undeclared this helper uses an ellipsis. + The third parameter is an optional suffix added to the string, if + undeclared this helper uses an ellipsis. -.. note:: If you need to truncate to an exact number of characters please - see the :ref:`ellipsize()` function below. - -ascii_to_entities() -=================== + .. note:: If you need to truncate to an exact number of characters please + see the :func:`ellipsize()` function below. -.. php:function:: ascii_to_entities($str) +.. function:: ascii_to_entities($str) :param string $str: Input string - :returns: string + :returns: A string with ASCII values converted to entities + :rtype: string -Converts ASCII values to character entities, including high ASCII and MS -Word characters that can cause problems when used in a web page, so that -they can be shown consistently regardless of browser settings or stored -reliably in a database. There is some dependence on your server's -supported character sets, so it may not be 100% reliable in all cases, -but for the most part it should correctly identify characters outside -the normal range (like accented characters). + Converts ASCII values to character entities, including high ASCII and MS + Word characters that can cause problems when used in a web page, so that + they can be shown consistently regardless of browser settings or stored + reliably in a database. There is some dependence on your server's + supported character sets, so it may not be 100% reliable in all cases, + but for the most part it should correctly identify characters outside + the normal range (like accented characters). -Example:: + Example:: - $string = ascii_to_entities($string); + $string = ascii_to_entities($string); -entities_to_ascii() -=================== - -.. php:function::entities_to_ascii($str, $all = TRUE) +.. function::entities_to_ascii($str[, $all = TRUE]) :param string $str: Input string :param bool $all: Whether to convert unsafe entities as well - :returns: string + :returns: A string with HTML entities converted to ASCII characters + :rtype: string -This function does the opposite of :php:func:`ascii_to_entities()`. -It turns character entities back into ASCII. + This function does the opposite of :func:`ascii_to_entities()`. + It turns character entities back into ASCII. -convert_accented_characters() -============================= - -.. php:function:: convert_accented_characters($str) +.. function:: convert_accented_characters($str) :param string $str: Input string - :returns: string - -Transliterates high ASCII characters to low ASCII equivalents. Useful -when non-English characters need to be used where only standard ASCII -characters are safely used, for instance, in URLs. + :returns: A string with accented characters converted + :rtype: string -Example:: + Transliterates high ASCII characters to low ASCII equivalents. Useful + when non-English characters need to be used where only standard ASCII + characters are safely used, for instance, in URLs. - $string = convert_accented_characters($string); + Example:: -.. note:: This function uses a companion config file - `application/config/foreign_chars.php` to define the to and - from array for transliteration. + $string = convert_accented_characters($string); -word_censor() -============= + .. note:: This function uses a companion config file + `application/config/foreign_chars.php` to define the to and + from array for transliteration. -.. php:function:: word_censor($str, $censored, $replacement = '') +.. function:: word_censor($str, $censored[, $replacement = '']) :param string $str: Input string :param array $censored: List of bad words to censor :param string $replacement: What to replace bad words with - :returns: string + :returns: Censored string + :rtype: string -Enables you to censor words within a text string. The first parameter -will contain the original string. The second will contain an array of -words which you disallow. The third (optional) parameter can contain -a replacement value for the words. If not specified they are replaced -with pound signs: ####. + Enables you to censor words within a text string. The first parameter + will contain the original string. The second will contain an array of + words which you disallow. The third (optional) parameter can contain + a replacement value for the words. If not specified they are replaced + with pound signs: ####. -Example:: + Example:: - $disallowed = array('darn', 'shucks', 'golly', 'phooey'); - $string = word_censor($string, $disallowed, 'Beep!'); + $disallowed = array('darn', 'shucks', 'golly', 'phooey'); + $string = word_censor($string, $disallowed, 'Beep!'); -highlight_code() -================ - -.. php:function:: highlight_code($str) +.. function:: highlight_code($str) :param string $str: Input string - :returns: string + :returns: String with code highlighted via HTML + :rtype: string -Colorizes a string of code (PHP, HTML, etc.). Example:: + Colorizes a string of code (PHP, HTML, etc.). Example:: - $string = highlight_code($string); + $string = highlight_code($string); -The function uses PHP's ``highlight_string()`` function, so the -colors used are the ones specified in your php.ini file. + The function uses PHP's ``highlight_string()`` function, so the + colors used are the ones specified in your php.ini file. -highlight_phrase() -================== -.. php:function:: highlight_phrase($str, $phrase, $tag_open = '<strong>', $tag_close = '</strong>') +.. function:: highlight_phrase($str, $phrase[, $tag_open = '<mark>'[, $tag_close = '</mark>']]) :param string $str: Input string :param string $phrase: Phrase to highlight :param string $tag_open: Opening tag used for the highlight :param string $tag_close: Closing tag for the highlight - :returns: string + :returns: String with a phrase highlighted via HTML + :rtype: string + + Will highlight a phrase within a text string. The first parameter will + contain the original string, the second will contain the phrase you wish + to highlight. The third and fourth parameters will contain the + opening/closing HTML tags you would like the phrase wrapped in. -Will highlight a phrase within a text string. The first parameter will -contain the original string, the second will contain the phrase you wish -to highlight. The third and fourth parameters will contain the -opening/closing HTML tags you would like the phrase wrapped in. + Example:: -Example:: + $string = "Here is a nice text string about nothing in particular."; + echo highlight_phrase($string, "nice text", '<span style="color:#990000;">', '</span>'); - $string = "Here is a nice text string about nothing in particular."; - echo highlight_phrase($string, "nice text", '<span style="color:#990000;">', '</span>'); + The above code prints:: -The above code prints:: + Here is a <span style="color:#990000;">nice text</span> string about nothing in particular. - Here is a <span style="color:#990000;">nice text</span> string about nothing in particular. + .. note:: This function used to use the ``<strong>`` tag by default. Older browsers + might not support the new HTML5 mark tag, so it is recommended that you + insert the following CSS code into your stylesheet if you need to support + such browsers:: -word_wrap() -=========== + mark { + background: #ff0; + color: #000; + }; -.. php:function:: word_wrap($str, $charlim = 76) +.. function:: word_wrap($str[, $charlim = 76]) :param string $str: Input string :param int $charlim: Character limit - :returns: string - -Wraps text at the specified *character* count while maintaining -complete words. - -Example:: + :returns: Word-wrapped string + :rtype: string - $string = "Here is a simple string of text that will help us demonstrate this function."; - echo word_wrap($string, 25); + Wraps text at the specified *character* count while maintaining + complete words. - // Would produce: Here is a simple string of text that will help us demonstrate this function + Example:: -.. _ellipsize(): + $string = "Here is a simple string of text that will help us demonstrate this function."; + echo word_wrap($string, 25); -ellipsize() -=========== + // Would produce: Here is a simple string of text that will help us demonstrate this function -.. php:function:: ellipsize($str, $max_length, $position = 1, $ellipsis = '…') +.. function:: ellipsize($str, $max_length[, $position = 1[, $ellipsis = '…']]) :param string $str: Input string :param int $max_length: String length limit - :param mixed $position: Position to split at - (int or float) + :param mixed $position: Position to split at (int or float) :param string $ellipsis: What to use as the ellipsis character - :returns: string + :returns: Ellipsized string + :rtype: string -This function will strip tags from a string, split it at a defined -maximum length, and insert an ellipsis. + This function will strip tags from a string, split it at a defined + maximum length, and insert an ellipsis. -The first parameter is the string to ellipsize, the second is the number -of characters in the final string. The third parameter is where in the -string the ellipsis should appear from 0 - 1, left to right. For -example. a value of 1 will place the ellipsis at the right of the -string, .5 in the middle, and 0 at the left. + The first parameter is the string to ellipsize, the second is the number + of characters in the final string. The third parameter is where in the + string the ellipsis should appear from 0 - 1, left to right. For + example. a value of 1 will place the ellipsis at the right of the + string, .5 in the middle, and 0 at the left. -An optional forth parameter is the kind of ellipsis. By default, -… will be inserted. + An optional forth parameter is the kind of ellipsis. By default, + … will be inserted. -Example:: + Example:: - $str = 'this_string_is_entirely_too_long_and_might_break_my_design.jpg'; - echo ellipsize($str, 32, .5); + $str = 'this_string_is_entirely_too_long_and_might_break_my_design.jpg'; + echo ellipsize($str, 32, .5); -Produces:: + Produces:: - this_string_is_e…ak_my_design.jpg
\ No newline at end of file + this_string_is_e…ak_my_design.jpg
\ No newline at end of file diff --git a/user_guide_src/source/helpers/typography_helper.rst b/user_guide_src/source/helpers/typography_helper.rst index 3c81687ac..deb3d164e 100644 --- a/user_guide_src/source/helpers/typography_helper.rst +++ b/user_guide_src/source/helpers/typography_helper.rst @@ -5,7 +5,12 @@ Typography Helper The Typography Helper file contains functions that help your format text in semantically relevant ways. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -14,58 +19,57 @@ This helper is loaded using the following code:: $this->load->helper('typography'); +Available Functions +=================== + The following functions are available: -auto_typography() -================= -.. php:function:: auto_typography($str, $reduce_linebreaks = FALSE) +.. function:: auto_typography($str[, $reduce_linebreaks = FALSE]) :param string $str: Input string :param bool $reduce_linebreaks: Whether to reduce multiple instances of double newlines to two - :returns: string + :returns: HTML-formatted typography-safe string + :rtype: string -Formats text so that it is semantically and typographically correct -HTML. + Formats text so that it is semantically and typographically correct + HTML. -This function is an alias for ``CI_Typography::auto_typography``. -For more info, please see the :doc:`Typography Library -<../libraries/typography>` documentation. + This function is an alias for ``CI_Typography::auto_typography``. + For more info, please see the :doc:`Typography Library + <../libraries/typography>` documentation. -Usage example:: + Usage example:: - $string = auto_typography($string); + $string = auto_typography($string); -.. note:: Typographic formatting can be processor intensive, particularly if - you have a lot of content being formatted. If you choose to use this - function you may want to consider `caching <../general/caching>` your - pages. + .. note:: Typographic formatting can be processor intensive, particularly if + you have a lot of content being formatted. If you choose to use this + function you may want to consider `caching <../general/caching>` your + pages. -nl2br_except_pre() -================== -.. php:function:: nl2br_except_pre($str) +.. function:: nl2br_except_pre($str) :param string $str: Input string - :returns: string - -Converts newlines to <br /> tags unless they appear within <pre> tags. -This function is identical to the native PHP ``nl2br()`` function, -except that it ignores <pre> tags. + :returns: String with HTML-formatted line breaks + :rtype: string -Usage example:: + Converts newlines to <br /> tags unless they appear within <pre> tags. + This function is identical to the native PHP ``nl2br()`` function, + except that it ignores <pre> tags. - $string = nl2br_except_pre($string); + Usage example:: -entity_decode() -=============== + $string = nl2br_except_pre($string); -.. php:function:: entity_decode($str, $charset = NULL) +.. function:: entity_decode($str, $charset = NULL) :param string $str: Input string :param string $charset: Character set - :returns: string + :returns: String with decoded HTML entities + :rtype: string -This function is an alias for ``CI_Security::entity_decode()``. -Fore more info, please see the :doc:`Security Library -<../libraries/security>` documentation.
\ No newline at end of file + This function is an alias for ``CI_Security::entity_decode()``. + Fore more info, please see the :doc:`Security Library + <../libraries/security>` documentation.
\ No newline at end of file diff --git a/user_guide_src/source/helpers/url_helper.rst b/user_guide_src/source/helpers/url_helper.rst index 7a49f188d..3bdcb8e17 100644 --- a/user_guide_src/source/helpers/url_helper.rst +++ b/user_guide_src/source/helpers/url_helper.rst @@ -4,7 +4,12 @@ URL Helper The URL Helper file contains functions that assist in working with URLs. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -15,371 +20,354 @@ This helper is loaded using the following code:: The following functions are available: -site_url() -========== +Available Functions +=================== -.. php:function:: site_url($uri = '', $protocol = NULL) +.. function:: site_url([$uri = ''[, $protocol = NULL]]) :param string $uri: URI string :param string $protocol: Protocol, e.g. 'http' or 'https' - :returns: string - -Returns your site URL, as specified in your config file. The index.php -file (or whatever you have set as your site **index_page** in your config -file) will be added to the URL, as will any URI segments you pass to the -function, plus the **url_suffix** as set in your config file. + :returns: Site URL + :rtype: string -You are encouraged to use this function any time you need to generate a -local URL so that your pages become more portable in the event your URL -changes. + Returns your site URL, as specified in your config file. The index.php + file (or whatever you have set as your site **index_page** in your config + file) will be added to the URL, as will any URI segments you pass to the + function, plus the **url_suffix** as set in your config file. -Segments can be optionally passed to the function as a string or an -array. Here is a string example:: + You are encouraged to use this function any time you need to generate a + local URL so that your pages become more portable in the event your URL + changes. - echo site_url('news/local/123'); + Segments can be optionally passed to the function as a string or an + array. Here is a string example:: -The above example would return something like: -*http://example.com/index.php/news/local/123* + echo site_url('news/local/123'); -Here is an example of segments passed as an array:: + The above example would return something like: + *http://example.com/index.php/news/local/123* - $segments = array('news', 'local', '123'); - echo site_url($segments); + Here is an example of segments passed as an array:: -This function is an alias for ``CI_Config::site_url()``. For more info, -please see the :doc:`Config Library <../libraries/config>` documentation. + $segments = array('news', 'local', '123'); + echo site_url($segments); -base_url() -=========== + This function is an alias for ``CI_Config::site_url()``. For more info, + please see the :doc:`Config Library <../libraries/config>` documentation. -.. php:function:: base_url($uri = '', $protocol = NULL) +.. function:: base_url($uri = '', $protocol = NULL) :param string $uri: URI string :param string $protocol: Protocol, e.g. 'http' or 'https' - :returns: string + :returns: Base URL + :rtype: string -Returns your site base URL, as specified in your config file. Example:: + Returns your site base URL, as specified in your config file. Example:: - echo base_url(); + echo base_url(); -This function returns the same thing as :php:func:`site_url()`, without -the *index_page* or *url_suffix* being appended. + This function returns the same thing as :func:`site_url()`, without + the *index_page* or *url_suffix* being appended. -Also like :php:func:`site_url()`, you can supply segments as a string or -an array. Here is a string example:: + Also like :func:`site_url()`, you can supply segments as a string or + an array. Here is a string example:: - echo base_url("blog/post/123"); + echo base_url("blog/post/123"); -The above example would return something like: -*http://example.com/blog/post/123* + The above example would return something like: + *http://example.com/blog/post/123* -This is useful because unlike :php:func:`site_url()`, you can supply a -string to a file, such as an image or stylesheet. For example:: + This is useful because unlike :func:`site_url()`, you can supply a + string to a file, such as an image or stylesheet. For example:: - echo base_url("images/icons/edit.png"); + echo base_url("images/icons/edit.png"); -This would give you something like: -*http://example.com/images/icons/edit.png* + This would give you something like: + *http://example.com/images/icons/edit.png* -This function is an alias for ``CI_Config::base_url()``. For more info, -please see the :doc:`Config Library <../libraries/config>` documentation. + This function is an alias for ``CI_Config::base_url()``. For more info, + please see the :doc:`Config Library <../libraries/config>` documentation. -current_url() -============= +.. function:: current_url() -.. php:function:: current_url() + :returns: The current URL + :rtype: string - :returns: string + Returns the full URL (including segments) of the page being currently + viewed. -Returns the full URL (including segments) of the page being currently -viewed. + .. note:: Calling this function is the same as doing this: + | + | site_url(uri_string()); -.. note:: Calling this function is the same as doing this: - | - | site_url(uri_string()); -uri_string() -============ +.. function:: uri_string() -.. php:function:: uri_string() + :returns: An URI string + :rtype: string - :returns: string + Returns the URI segments of any page that contains this function. + For example, if your URL was this:: -Returns the URI segments of any page that contains this function. -For example, if your URL was this:: + http://some-site.com/blog/comments/123 - http://some-site.com/blog/comments/123 + The function would return:: -The function would return:: + blog/comments/123 - blog/comments/123 + This function is an alias for ``CI_Config::uri_string()``. For more info, + please see the :doc:`Config Library <../libraries/config>` documentation. -This function is an alias for ``CI_Config::uri_string()``. For more info, -please see the :doc:`Config Library <../libraries/config>` documentation. -index_page() -============ +.. function:: index_page() -.. php:function:: index_page() + :returns: 'index_page' value + :rtype: mixed - :returns: string + Returns your site **index_page**, as specified in your config file. + Example:: -Returns your site **index_page**, as specified in your config file. -Example:: + echo index_page(); - echo index_page(); - -anchor() -======== - -.. php:function:: anchor($uri = '', $title = '', $attributes = '') +.. function:: anchor($uri = '', $title = '', $attributes = '') :param string $uri: URI string :param string $title: Anchor title :param mixed $attributes: HTML attributes - :returns: string + :returns: HTML hyperlink (anchor tag) + :rtype: string -Creates a standard HTML anchor link based on your local site URL. + Creates a standard HTML anchor link based on your local site URL. -The first parameter can contain any segments you wish appended to the -URL. As with the :php:func:`site_url()` function above, segments can -be a string or an array. + The first parameter can contain any segments you wish appended to the + URL. As with the :func:`site_url()` function above, segments can + be a string or an array. -.. note:: If you are building links that are internal to your application - do not include the base URL (http://...). This will be added - automatically from the information specified in your config file. - Include only the URI segments you wish appended to the URL. + .. note:: If you are building links that are internal to your application + do not include the base URL (http://...). This will be added + automatically from the information specified in your config file. + Include only the URI segments you wish appended to the URL. -The second segment is the text you would like the link to say. If you -leave it blank, the URL will be used. + The second segment is the text you would like the link to say. If you + leave it blank, the URL will be used. -The third parameter can contain a list of attributes you would like -added to the link. The attributes can be a simple string or an -associative array. + The third parameter can contain a list of attributes you would like + added to the link. The attributes can be a simple string or an + associative array. -Here are some examples:: + Here are some examples:: - echo anchor('news/local/123', 'My News', 'title="News title"'); - // Prints: <a href="http://example.com/index.php/news/local/123" title="News title">My News</a> + echo anchor('news/local/123', 'My News', 'title="News title"'); + // Prints: <a href="http://example.com/index.php/news/local/123" title="News title">My News</a> - echo anchor('news/local/123', 'My News', array('title' => 'The best news!')); - // Prints: <a href="http://example.com/index.php/news/local/123" title="The best news!">My News</a> + echo anchor('news/local/123', 'My News', array('title' => 'The best news!')); + // Prints: <a href="http://example.com/index.php/news/local/123" title="The best news!">My News</a> - echo anchor('', 'Click here'); - // Prints: <a href="http://example.com">Click Here</a> + echo anchor('', 'Click here'); + // Prints: <a href="http://example.com">Click Here</a> -anchor_popup() -============== -.. php:function:: anchor_popup($uri = '', $title = '', $attributes = FALSE) +.. function:: anchor_popup($uri = '', $title = '', $attributes = FALSE) :param string $uri: URI string :param string $title: Anchor title :param mixed $attributes: HTML attributes - :returns: string + :returns: Pop-up hyperlink + :rtype: string -Nearly identical to the :php:func:``anchor()`` function except that it -opens the URL in a new window. You can specify JavaScript window -attributes in the third parameter to control how the window is opened. -If the third parameter is not set it will simply open a new window with -your own browser settings. + Nearly identical to the :func:`anchor()` function except that it + opens the URL in a new window. You can specify JavaScript window + attributes in the third parameter to control how the window is opened. + If the third parameter is not set it will simply open a new window with + your own browser settings. -Here is an example with attributes:: + Here is an example with attributes:: - $atts = array( - 'width' => 800, - 'height' => 600, - 'scrollbars' => 'yes', - 'status'Â Â Â Â Â => 'yes', - 'resizable'Â Â => 'yes', - 'screenx' => 0, - 'screeny' => 0, - 'window_name' => '_blank' - ); + $atts = array( + 'width' => 800, + 'height' => 600, + 'scrollbars' => 'yes', + 'status'Â Â Â Â Â => 'yes', + 'resizable'Â Â => 'yes', + 'screenx' => 0, + 'screeny' => 0, + 'window_name' => '_blank' + ); - echo anchor_popup('news/local/123', 'Click Me!', $atts); + echo anchor_popup('news/local/123', 'Click Me!', $atts); -.. note:: The above attributes are the function defaults so you only need to - set the ones that are different from what you need. If you want the - function to use all of its defaults simply pass an empty array in the - third parameter: - | - | echo anchor_popup('news/local/123', 'Click Me!', array()); + .. note:: The above attributes are the function defaults so you only need to + set the ones that are different from what you need. If you want the + function to use all of its defaults simply pass an empty array in the + third parameter: + | + | echo anchor_popup('news/local/123', 'Click Me!', array()); -.. note:: The **window_name** is not really an attribute, but an argument to - the JavaScript `window.open() <http://www.w3schools.com/jsref/met_win_open.asp>` - method, which accepts either a window name or a window target. + .. note:: The **window_name** is not really an attribute, but an argument to + the JavaScript `window.open() <http://www.w3schools.com/jsref/met_win_open.asp>` + method, which accepts either a window name or a window target. -.. note:: Any other attribute than the listed above will be parsed as an - HTML attribute to the anchor tag. + .. note:: Any other attribute than the listed above will be parsed as an + HTML attribute to the anchor tag. -mailto() -======== -.. php:function:: mailto($email, $title = '', $attributes = '') +.. function:: mailto($email, $title = '', $attributes = '') :param string $email: E-mail address :param string $title: Anchor title :param mixed $attributes: HTML attributes - :returns: string + :returns: A "mail to" hyperlink + :rtype: string -Creates a standard HTML e-mail link. Usage example:: + Creates a standard HTML e-mail link. Usage example:: - echo mailto('me@my-site.com', 'Click Here to Contact Me'); + echo mailto('me@my-site.com', 'Click Here to Contact Me'); -As with the :php:func:`anchor()` tab above, you can set attributes using the -third parameter:: + As with the :func:`anchor()` tab above, you can set attributes using the + third parameter:: - $attributes = array('title' => 'Mail me'); - echo mailto('me@my-site.com', 'Contact Me', $attributes); + $attributes = array('title' => 'Mail me'); + echo mailto('me@my-site.com', 'Contact Me', $attributes); -safe_mailto() -============= - -.. php:function:: safe_mailto($email, $title = '', $attributes = '') +.. function:: safe_mailto($email, $title = '', $attributes = '') :param string $email: E-mail address :param string $title: Anchor title :param mixed $attributes: HTML attributes - :returns: string - -Identical to the :php:func:`mailto()` function except it writes an obfuscated -version of the *mailto* tag using ordinal numbers written with JavaScript to -help prevent the e-mail address from being harvested by spam bots. + :returns: A spam-safe "mail to" hyperlink + :rtype: string -auto_link() -=========== + Identical to the :func:`mailto()` function except it writes an obfuscated + version of the *mailto* tag using ordinal numbers written with JavaScript to + help prevent the e-mail address from being harvested by spam bots. -.. php:function:: auto_link($str, $type = 'both', $popup = FALSE) +.. function:: auto_link($str, $type = 'both', $popup = FALSE) :param string $str: Input string :param string $type: Link type ('email', 'url' or 'both') :param bool $popup: Whether to create popup links - :returns: string + :returns: Linkified string + :rtype: string -Automatically turns URLs and e-mail addresses contained in a string into -links. Example:: + Automatically turns URLs and e-mail addresses contained in a string into + links. Example:: - $string = auto_link($string); + $string = auto_link($string); -The second parameter determines whether URLs and e-mails are converted or -just one or the other. Default behavior is both if the parameter is not -specified. E-mail links are encoded as :php:func:`safe_mailto()` as shown -above. + The second parameter determines whether URLs and e-mails are converted or + just one or the other. Default behavior is both if the parameter is not + specified. E-mail links are encoded as :func:`safe_mailto()` as shown + above. -Converts only URLs:: + Converts only URLs:: - $string = auto_link($string, 'url'); + $string = auto_link($string, 'url'); -Converts only e-mail addresses:: + Converts only e-mail addresses:: - $string = auto_link($string, 'email'); + $string = auto_link($string, 'email'); -The third parameter determines whether links are shown in a new window. -The value can be TRUE or FALSE (boolean):: + The third parameter determines whether links are shown in a new window. + The value can be TRUE or FALSE (boolean):: - $string = auto_link($string, 'both', TRUE); + $string = auto_link($string, 'both', TRUE); -url_title() -=========== -.. php:function:: url_title($str, $separator = '-', $lowercase = FALSE) +.. function:: url_title($str, $separator = '-', $lowercase = FALSE) :param string $str: Input string :param string $separator: Word separator :param string $lowercase: Whether to transform the output string to lower-case - :returns: string + :returns: URL-formatted string + :rtype: string -Takes a string as input and creates a human-friendly URL string. This is -useful if, for example, you have a blog in which you'd like to use the -title of your entries in the URL. Example:: + Takes a string as input and creates a human-friendly URL string. This is + useful if, for example, you have a blog in which you'd like to use the + title of your entries in the URL. Example:: - $title = "What's wrong with CSS?"; - $url_title = url_title($title); - // Produces: Whats-wrong-with-CSS + $title = "What's wrong with CSS?"; + $url_title = url_title($title); + // Produces: Whats-wrong-with-CSS -The second parameter determines the word delimiter. By default dashes -are used. Preferred options are: **-** (dash) or **_** (underscore) + The second parameter determines the word delimiter. By default dashes + are used. Preferred options are: **-** (dash) or **_** (underscore) -Example:: + Example:: - $title = "What's wrong with CSS?"; - $url_title = url_title($title, 'underscore'); - // Produces: Whats_wrong_with_CSS + $title = "What's wrong with CSS?"; + $url_title = url_title($title, 'underscore'); + // Produces: Whats_wrong_with_CSS -.. note:: Old usage of 'dash' and 'underscore' as the second parameter - is DEPRECATED. + .. note:: Old usage of 'dash' and 'underscore' as the second parameter + is DEPRECATED. -The third parameter determines whether or not lowercase characters are -forced. By default they are not. Options are boolean TRUE/FALSE. + The third parameter determines whether or not lowercase characters are + forced. By default they are not. Options are boolean TRUE/FALSE. -Example:: + Example:: - $title = "What's wrong with CSS?"; - $url_title = url_title($title, 'underscore', TRUE); - // Produces: whats_wrong_with_css + $title = "What's wrong with CSS?"; + $url_title = url_title($title, 'underscore', TRUE); + // Produces: whats_wrong_with_css -prep_url() ----------- -.. php:function:: prep_url($str = '') +.. function:: prep_url($str = '') :param string $str: URL string - :returns: string + :returns: Protocol-prefixed URL string + :rtype: string -This function will add http:// in the event that a protocol prefix -is missing from a URL. + This function will add http:// in the event that a protocol prefix + is missing from a URL. -Pass the URL string to the function like this:: + Pass the URL string to the function like this:: - $url = prep_url('example.com'); + $url = prep_url('example.com'); -redirect() -========== -.. php:function:: redirect($uri = '', $method = 'auto', $code = NULL) +.. function:: redirect($uri = '', $method = 'auto', $code = NULL) :param string $uri: URI string :param string $method: Redirect method ('auto', 'location' or 'refresh') :param string $code: HTTP Response code (usually 302 or 303) - :returns: void + :rtype: void -Does a "header redirect" to the URI specified. If you specify the full -site URL that link will be built, but for local links simply providing -the URI segments to the controller you want to direct to will create the -link. The function will build the URL based on your config file values. + Does a "header redirect" to the URI specified. If you specify the full + site URL that link will be built, but for local links simply providing + the URI segments to the controller you want to direct to will create the + link. The function will build the URL based on your config file values. -The optional second parameter allows you to force a particular redirection -method. The available methods are **auto**, **location** and **refresh**, -with location being faster but less reliable on IIS servers. -The default is **auto**, which will attempt to intelligently choose the -method based on the server environment. + The optional second parameter allows you to force a particular redirection + method. The available methods are **auto**, **location** and **refresh**, + with location being faster but less reliable on IIS servers. + The default is **auto**, which will attempt to intelligently choose the + method based on the server environment. -The optional third parameter allows you to send a specific HTTP Response -Code - this could be used for example to create 301 redirects for search -engine purposes. The default Response Code is 302. The third parameter is -*only* available with **location** redirects, and not *refresh*. Examples:: + The optional third parameter allows you to send a specific HTTP Response + Code - this could be used for example to create 301 redirects for search + engine purposes. The default Response Code is 302. The third parameter is + *only* available with **location** redirects, and not *refresh*. Examples:: - if ($logged_in == FALSE) - { Â Â Â Â Â - redirect('/login/form/'); - } + if ($logged_in == FALSE) + { Â Â Â Â Â + redirect('/login/form/'); + } - // with 301 redirect - redirect('/article/13', 'location', 301); + // with 301 redirect + redirect('/article/13', 'location', 301); -.. note:: In order for this function to work it must be used before anything - is outputted to the browser since it utilizes server headers. + .. note:: In order for this function to work it must be used before anything + is outputted to the browser since it utilizes server headers. -.. note:: For very fine grained control over headers, you should use the - `Output Library </libraries/output>` ``set_header()`` method. + .. note:: For very fine grained control over headers, you should use the + `Output Library </libraries/output>` ``set_header()`` method. -.. note:: To IIS users: if you hide the `Server` HTTP header, the *auto* - method won't detect IIS, in that case it is advised you explicitly - use the **refresh** method. + .. note:: To IIS users: if you hide the `Server` HTTP header, the *auto* + method won't detect IIS, in that case it is advised you explicitly + use the **refresh** method. -.. note:: When the **location** method is used, an HTTP status code of 303 - will *automatically* be selected when the page is currently accessed - via POST and HTTP/1.1 is used. + .. note:: When the **location** method is used, an HTTP status code of 303 + will *automatically* be selected when the page is currently accessed + via POST and HTTP/1.1 is used. -.. important:: This function will terminate script execution.
\ No newline at end of file + .. important:: This function will terminate script execution.
\ No newline at end of file diff --git a/user_guide_src/source/helpers/xml_helper.rst b/user_guide_src/source/helpers/xml_helper.rst index be848bcd1..a40ea9ad3 100644 --- a/user_guide_src/source/helpers/xml_helper.rst +++ b/user_guide_src/source/helpers/xml_helper.rst @@ -5,7 +5,12 @@ XML Helper The XML Helper file contains functions that assist in working with XML data. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> Loading this Helper =================== @@ -16,23 +21,35 @@ This helper is loaded using the following code $this->load->helper('xml'); +Available Functions +=================== + The following functions are available: -xml_convert() -===================== +.. function:: xml_convert($str[, $protect_all = FALSE]) -Takes a string as input and converts the following reserved XML -characters to entities: + :param string $str: the text string to convert + :param bool $protect_all: Whether to protect all content that looks like a potential entity instead of just numbered entities, e.g. &foo; + :returns: XML-converted string + :rtype: string -- Ampersands: & -- Less then and greater than characters: < > -- Single and double quotes: ' " -- Dashes: - + Takes a string as input and converts the following reserved XML + characters to entities: -This function ignores ampersands if they are part of existing character -entities. Example + - Ampersands: & + - Less than and greater than characters: < > + - Single and double quotes: ' " + - Dashes: - -:: + This function ignores ampersands if they are part of existing numbered + character entities, e.g. {. Example:: + + $string = '<p>Here is a paragraph & an entity ({).</p>'; + $string = xml_convert($string); + echo $string; + + outputs: - $string = xml_convert($string); + .. code-block:: html + <p>Here is a paragraph & an entity ({).</p>
\ No newline at end of file diff --git a/user_guide_src/source/installation/upgrade_300.rst b/user_guide_src/source/installation/upgrade_300.rst index 88bb11178..292c1de9d 100644 --- a/user_guide_src/source/installation/upgrade_300.rst +++ b/user_guide_src/source/installation/upgrade_300.rst @@ -375,7 +375,7 @@ CodeIgniter 3.1+. String helper repeater() ======================== -:doc:`String Helper <../helpers/string_helper>` function :php:func:`repeater()` is now just an alias for +:doc:`String Helper <../helpers/string_helper>` function :func:`repeater()` is now just an alias for PHP's native ``str_repeat()`` function. It is deprecated and scheduled for removal in CodeIgniter 3.1+. .. note:: This function is still available, but you're strongly encouraged to remove its usage sooner @@ -384,7 +384,7 @@ PHP's native ``str_repeat()`` function. It is deprecated and scheduled for remov String helper trim_slashes() ============================ -:doc:`String Helper <../helpers/string_helper>` function :php:func:`trim_slashes()` is now just an alias +:doc:`String Helper <../helpers/string_helper>` function :func:`trim_slashes()` is now just an alias for PHP's native ``trim()`` function (with a slash passed as its second argument). It is deprecated and scheduled for removal in CodeIgniter 3.1+. @@ -396,8 +396,8 @@ Email helper functions :doc:`Email Helper <../helpers/email_helper>` only has two functions - - :php:func:`valid_email()` - - :php:func:`send_email()` + - :func:`valid_email()` + - :func:`send_email()` Both of them are now aliases for PHP's native ``filter_var()`` and ``mail()`` functions, respectively. Therefore the :doc:`Email Helper <../helpers/email_helper>` altogether is being deprecated and @@ -447,7 +447,7 @@ CodeIgniter 3.1+. String helper random_string() types 'unique' and 'encrypt' ========================================================== -When using the :doc:`String Helper <../helpers/string_helper>` function :php:func:`random_string()`, +When using the :doc:`String Helper <../helpers/string_helper>` function :func:`random_string()`, you should no longer pass the **unique** and **encrypt** randomization types. They are only aliases for **md5** and **sha1** respectively and are now deprecated and scheduled for removal in CodeIgniter 3.1+. @@ -458,7 +458,7 @@ in CodeIgniter 3.1+. URL helper url_title() separators 'dash' and 'underscore' ========================================================= -When using the :doc:`URL Helper <../helpers/url_helper>` function :php:func:`url_title()`, you +When using the :doc:`URL Helper <../helpers/url_helper>` function :func:`url_title()`, you should no longer pass **dash** or **underscore** as the word separator. This function will now accept any character and you should just pass the chosen character directly, so you should write '-' instead of 'dash' and '_' instead of 'underscore'. @@ -472,7 +472,7 @@ in CodeIgniter 3.1+. Session Library method all_userdata() ===================================== -As seen in the :doc:`Change Log <../changelog>`, :doc:`Session Library <libraries/sessions>` +As seen in the :doc:`Change Log <../changelog>`, :doc:`Session Library <../libraries/sessions>` method ``userdata()`` now allows you to fetch all userdata by simply omitting its parameter:: $this->session->userdata(); @@ -538,7 +538,7 @@ Input library method is_cli_request() Calls to the ``CI_Input::is_cli_request()`` method are necessary at many places in the CodeIgniter internals and this is often before the :doc:`Input Library <../libraries/input>` is loaded. Because of that, it is being replaced by a common -function named :php:func:`is_cli()` and this method is now just an alias. +function named :func:`is_cli()` and this method is now just an alias. The new function is both available at all times for you to use and shorter to type. @@ -556,6 +556,31 @@ CodeIgniter 3.1+. .. note:: This method is still available, but you're strongly encouraged to remove its usage sooner rather than later. +Config library method system_url() +================================== + +Usage of ``CI_Config::system_url()`` encourages insecure coding practices. +Namely, your CodeIgniter *system/* directory shouldn't be publicly accessible +from a security point of view. + +Because of this, this method is now deprecated and scheduled for removal in +CodeIgniter 3.1+. + +.. note:: This method is still available, but you're strongly encouraged to remove its usage + sooner rather than later. + +====================== +The Javascript library +====================== + +The :doc:`Javascript Library <../libraries/javascript>` has always had an +'experimental' status and was never really useful, nor a proper solution. + +It is now deprecated and scheduled for removal in CodeIgniter 3.1+. + +.. note:: This library is still available, but you're strongly encouraged to remove its usage + sooner rather than later. + *********************************************************** Step 18: Check your usage of Text helper highlight_phrase() *********************************************************** @@ -572,4 +597,4 @@ in order to avoid backwards compatibility with old browsers:: mark { background: #ff0; color: #000; - };
\ No newline at end of file + }; diff --git a/user_guide_src/source/libraries/benchmark.rst b/user_guide_src/source/libraries/benchmark.rst index 5b86142dd..ddbe04869 100644 --- a/user_guide_src/source/libraries/benchmark.rst +++ b/user_guide_src/source/libraries/benchmark.rst @@ -13,10 +13,16 @@ invoked, and ended by the output class right before sending the final view to the browser, enabling a very accurate timing of the entire system execution to be shown. -.. contents:: Table of Contents +.. contents:: + :local: +.. raw:: html + + <div class="custom-index container"></div> + +************************* Using the Benchmark Class -========================= +************************* The Benchmark class can be used within your :doc:`controllers </general/controllers>`, @@ -68,7 +74,7 @@ _end. Each pair of points must otherwise be named identically. Example:: // Some code happens here... - $this->benchmark->mark('my_mark_end'); + $this->benchmark->mark('my_mark_end'); $this->benchmark->mark('another_mark_start'); @@ -120,3 +126,43 @@ this pseudo-variable, if you prefer not to use the pure PHP:: {memory_usage} + +*************** +Class Reference +*************** + +.. class:: CI_Benchmark + + .. method:: mark($name) + + :param string $name: the name you wish to assign to your marker + :rtype: void + + Sets a benchmark marker. + + .. method:: elapsed_time([$point1 = ''[, $point2 = ''[, $decimals = 4]]]) + + :param string $point1: a particular marked point + :param string $point2: a particular marked point + :param int $decimals: number of decimal places for precision + :returns: 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. + + + .. 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 index 3f7dc2dd9..caece1aee 100644 --- a/user_guide_src/source/libraries/caching.rst +++ b/user_guide_src/source/libraries/caching.rst @@ -7,7 +7,12 @@ fast and dynamic caching. All but file-based caching require specific server requirements, and a Fatal Exception will be thrown if server requirements are not met. -.. contents:: Table of Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> ************* Example Usage @@ -20,16 +25,16 @@ available in the hosting environment. :: $this->load->driver('cache', array('adapter' => 'apc', 'backup' => 'file')); - + if ( ! $foo = $this->cache->get('foo')) { echo 'Saving to the cache!<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 @@ -43,28 +48,24 @@ to avoid collisions when you're running multiple applications on the same enviro $this->cache->get('foo'); // Will get the cache entry named 'my_foo' -****************** -Function Reference -****************** +*************** +Class Reference +*************** -.. php:class:: CI_Cache +.. class:: CI_Cache -is_supported() -============== + .. method:: is_supported($driver) - .. php:method:: is_supported ( $driver ) + :param string $driver: the name of the caching driver + :returns: TRUE if supported, FALSE if not + :rtype: bool - This function is automatically called when accessing drivers via - $this->cache->get(). However, if the individual drivers are used, make - sure to call this function to ensure the driver is supported in the + 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. - - :param string $driver: the name of the caching driver - :returns: TRUE if supported, FALSE if not - :rtype: Boolean - :: - + if ($this->cache->apc->is_supported() { if ($data = $this->cache->apc->get('my_cache')) @@ -73,103 +74,112 @@ is_supported() } } + .. method:: get($id) -get() -===== - - .. php:method:: get ( $id ) - - This function will attempt to fetch an item from the cache store. If the - item does not exist, the function will return FALSE. + :param string $id: Cache item name + :returns: Item value or FALSE if not found + :rtype: mixed - :param string $id: name of cached item - :returns: The item if it exists, FALSE if it does not - :rtype: Mixed - + This method will attempt to fetch an item from the cache store. If the + item does not exist, the method will return FALSE. :: $foo = $this->cache->get('my_cached_item'); + .. method:: save($id, $data[, $ttl = 60[, $raw = FALSE]]) -save() -====== - - .. php:method:: save ( $id , $data [, $ttl]) - - This function will save an item to the cache store. If saving fails, the - function will return FALSE. - - :param string $id: name of the cached item - :param mixed $data: the data to save - :param int $ttl: Time To Live, in seconds (default 60) - :returns: TRUE on success, FALSE on failure - :rtype: Boolean + :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'); - -delete() -======== - .. php:method:: delete ( $id ) - - This function will delete a specific item from the cache store. If item - deletion fails, the function will return FALSE. + .. note:: The ``$raw`` parameter is only utilized by APC and Memcache, + in order to allow usage of ``increment()`` and ``decrement()``. - :param string $id: name of cached item - :returns: TRUE if deleted, FALSE if the deletion fails - :rtype: Boolean - + .. 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'); -clean() -======= + .. method:: increment($id[, $offset = 1]) - .. php:method:: clean ( ) - - This function will 'clean' the entire cache. If the deletion of the - cache files fails, the function will return FALSE. + :param string $id: Cache ID + :param int $offset: Step/value to add + :returns: New value on success, FALSE on failure + :rtype: mixed - :returns: TRUE if deleted, FALSE if the deletion fails - :rtype: Boolean - + Performs atomic incrementation of a raw stored value. :: - $this->cache->clean(); + // 'iterator' has a value of 2 + + $this->cache->increment('iterator'); // 'iterator' is now 3 -cache_info() -============ + $this->cache->increment('iterator', 3); // 'iterator' is now 6 - .. php:method:: cache_info ( ) + .. method:: decrement($id[, $offset = 1]) - This function will return information on the entire cache. + :param string $id: Cache ID + :param int $offset: Step/value to reduce by + :returns: New value on success, FALSE on failure + :rtype: mixed - :returns: information on the entire cache - :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 + + .. 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(); + + .. 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. - -get_metadata() -============== + .. method:: get_metadata($id) - .. php:method:: get_metadata ( $id ) - - This function will return detailed information on a specific item in the + :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. - - :param string $id: name of cached item - :returns: metadadta for the cached item - :rtype: Mixed - :: var_dump($this->cache->get_metadata('my_cached_item')); @@ -184,7 +194,7 @@ Drivers Alternative PHP Cache (APC) Caching =================================== -All of the functions listed above can be accessed without passing a +All of the methods listed above can be accessed without passing a specific adapter to the driver loader as follows:: $this->load->driver('cache'); @@ -201,7 +211,7 @@ allows for pieces of view files to be cached. Use this with care, and make sure to benchmark your application, as a point can come where disk I/O will negate positive gains by caching. -All of the functions listed above can be accessed without passing a +All of the methods listed above can be accessed without passing a specific adapter to the driver loader as follows:: $this->load->driver('cache'); @@ -227,7 +237,7 @@ WinCache Caching Under Windows, you can also utilize the WinCache driver. -All of the functions listed above can be accessed without passing a +All of the methods listed above can be accessed without passing a specific adapter to the driver loader as follows:: $this->load->driver('cache'); diff --git a/user_guide_src/source/libraries/calendar.rst b/user_guide_src/source/libraries/calendar.rst index ed2a14c8c..65a447a3d 100644 --- a/user_guide_src/source/libraries/calendar.rst +++ b/user_guide_src/source/libraries/calendar.rst @@ -7,6 +7,17 @@ calendars can be formatted through the use of a calendar template, allowing 100% control over every aspect of its design. In addition, you can pass data to your calendar cells. +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + +*************************** +Using the Calendaring Class +*************************** + Initializing the Class ====================== @@ -86,23 +97,23 @@ 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 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. -====================== ================= =============================================== =================================================================== +====================== ================= ============================================ =================================================================== +Preference Default Options Description +====================== ================= ============================================ =================================================================== +**template** None None A string 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 @@ -180,4 +191,98 @@ pair of pseudo-variables as shown here:: $this->load->library('calendar', $prefs); - echo $this->calendar->generate();
\ No newline at end of file + echo $this->calendar->generate(); + +*************** +Class Reference +*************** + +.. class:: CI_Calendar + + .. method:: initialize([$config = array()]) + + :param array $config: Configuration parameters + :returns: CI_Calendar instance (method chaining) + :rtype: CI_Calendar + + Initializes the Calendaring preferences. Accepts an associative array as input, containing display preferences. + + .. 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. + + + .. 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. + + .. 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. + + .. 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, 2013)); + + outputs:: + + Array + ( Â Â Â + [month] => '01' + [year] => '2014' + ) + + .. 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 + + .. 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. + + + .. 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.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/cart.rst b/user_guide_src/source/libraries/cart.rst index 716e94bcb..fb92c280a 100644 --- a/user_guide_src/source/libraries/cart.rst +++ b/user_guide_src/source/libraries/cart.rst @@ -11,7 +11,16 @@ Please note that the Cart Class ONLY provides the core "cart" functionality. It does not provide shipping, credit card authorization, or other processing components. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + +******************** +Using the Cart Class +******************** Initializing the Shopping Cart Class ==================================== @@ -29,7 +38,7 @@ use the $this->load->library function:: $this->load->library('cart'); Once loaded, the Cart object will be available using:: - + $this->cart .. note:: The Cart Class will load and initialize the Session Class @@ -179,7 +188,7 @@ helper </helpers/form_helper>`. </table> <p><?php echo form_submit('', 'Update your Cart'); ?></p> - + Updating The Cart ================= @@ -197,7 +206,7 @@ function: 'qty' => 3 ); - $this->cart->update($data); + $this->cart->update($data); // Or a multi-dimensional array @@ -236,73 +245,125 @@ the product ID and any options associated with it. In nearly all cases, updating the cart will be something the user does via the "view cart" page, so as a developer, it is unlikely that you -will ever have to concern yourself with the "row ID", other then making +will ever have to concern yourself with the "row ID", other than making sure your "view cart" page contains this information in a hidden form field, and making sure it gets passed to the update function when the update form is submitted. Please examine the construction of the "view cart" page above for more information. -Function Reference -================== +*************** +Class Reference +*************** + +.. class:: CI_Cart + + .. attribute:: $product_id_rules = '\.a-z0-9_-' + + These are the regular expression rules that we use to validate the product + ID - alpha-numeric, dashes, underscores, or periods by default + + .. attribute:: $product_name_rules = '\w \-\.\:' + + These are the regular expression rules that we use to validate the product ID and product name - alpha-numeric, dashes, underscores, colons or periods by + default + + .. attribute:: $product_name_safe = TRUE + + Whether or not to only allow safe product names. Default TRUE. + + + .. method:: insert([$items = array()]) + + :param array $items: 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. + + + .. 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 the quantity of a given item to be changed. + Typically it is called from the "view cart" page if a user makes changes + to the quantity before checkout. That array must contain the product ID + and quantity for each item. + + .. method:: remove($rowid) + + :param int $rowid: ID of the item to remove from the cart + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Allows you to remove an item from the shopping cart by passing it the + ``$rowid``. + + .. method:: total() + + :returns: Total amount + :rtype: int + + Displays the total amount in the cart. -$this->cart->insert(); -********************** -Permits you to add items to the shopping cart, as outlined above. + .. method:: total_items() -$this->cart->update(); -********************** + :returns: Total amount of items in the cart + :rtype: int -Permits you to update items in the shopping cart, as outlined above. + Displays the total number of items in the cart. -$this->cart->remove(rowid); -*************************** -Allows you to remove an item from the shopping cart by passing it the rowid. + .. method:: contents([$newest_first = FALSE]) -$this->cart->total(); -********************* + :param bool $newest_first: Whether to order the array with newest items first + :returns: An array of cart contents + :rtype: array -Displays the total amount in the cart. + Returns an array containing everything in the cart. You can sort the + order by which the array is returned by passing it TRUE where the contents + will be sorted from newest to oldest, otherwise it is sorted from oldest + to newest. -$this->cart->total_items(); -*************************** + .. method:: get_item($row_id) -Displays the total number of items in the cart. + :param int $row_id: Row ID to retrieve + :returns: Array of item data + :rtype: array -$this->cart->contents(boolean); -******************************* + Returns an array containing data for the item matching the specified row + ID, or FALSE if no such item exists. -Returns an array containing everything in the cart. You can sort the order, -by which this is returned by passing it "true" where the contents will be sorted -from newest to oldest, by leaving this function blank, you'll automatically just get -first added to the basket to last added to the basket. + .. method:: has_options($row_id = '') -$this->cart->get_item($row_id); -******************************* + :param int $row_id: Row ID to inspect + :returns: TRUE if options exist, FALSE otherwise + :rtype: bool -Returns an array containing data for the item matching the specified row ID, -or FALSE if no such item exists. + 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 function, as shown in the Displaying + the Cart example above. -$this->cart->has_options($row_id); -********************************** + .. method:: product_options([$row_id = '']) -Returns TRUE (boolean) if a particular row in the cart contains options. -This function is designed to be used in a loop with -$this->cart->contents(), since you must pass the rowid to this function, -as shown in the Displaying the Cart example above. + :param int $row_id: Row ID + :returns: Array of product options + :rtype: array -$this->cart->product_options($row_id); -************************************** + 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. -Returns an array of options for a particular product. This function is -designed to be used in a loop with $this->cart->contents(), since you -must pass the rowid to this function, as shown in the Displaying the -Cart example above. + .. method:: destroy() -$this->cart->destroy(); -*********************** + :rtype: void -Permits you to destroy the cart. This function will likely be called -when you are finished processing the customer's order. + Permits you to destroy the cart. This method will likely be called + when you are finished processing the customer's order.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/config.rst b/user_guide_src/source/libraries/config.rst index 654dc4ded..3116b768a 100644 --- a/user_guide_src/source/libraries/config.rst +++ b/user_guide_src/source/libraries/config.rst @@ -9,7 +9,16 @@ These preferences can come from the default config file .. note:: This class is initialized automatically by the system so there is no need to do it manually. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + +***************************** +Working with the Config Class +***************************** Anatomy of a Config File ======================== @@ -157,27 +166,87 @@ folders: that you wish to change for your environment. The config items declared in your environment folders always overwrite those in your global config files. -Helper Functions -================ -The config class has the following helper functions: +*************** +Class Reference +*************** -$this->config->site_url(); -*************************** +.. class:: CI_Config -This function retrieves the URL to your site, along with the "index" -value you've specified in the config file. + .. attribute:: $config -$this->config->base_url(); -*************************** + Array of all loaded config values -This function retrieves the URL to your site, plus an optional path such -as to a stylesheet or image. + .. attribute:: $is_loaded -The two functions above are normally accessed via the corresponding -functions in the :doc:`URL Helper </helpers/url_helper>`. + Array of all loaded config files -$this->config->system_url(); -***************************** -This function retrieves the URL to your system folder. + .. method:: item($item[, $index='']) + + :param string $item: Config item name + :param string $index: Index name + :returns: Config item value or NULL if not found + :rtype: mixed + + Fetch a config file item. + + .. method:: set_item($item, $value) + + :param string $item: Config item name + :param string $value: Config item value + :rtype: void + + Sets a config file item to the specified value. + + .. 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. + + .. method:: load([$file = ''[, $use_sections = FALSE[, $fail_gracefully = FALSE]]]) + + :param string $file: Configuration file name + :param bool $use_sections: Whether config values shoud be loaded into their own section (index of the main config array) + :param bool $fail_gracefully: Whether to return FALSE or to display an error message + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Loads a configuration file. + + .. 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>`. + + .. 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>`. + + .. 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 index 86f440a74..ebfde809b 100644 --- a/user_guide_src/source/libraries/email.rst +++ b/user_guide_src/source/libraries/email.rst @@ -16,6 +16,17 @@ CodeIgniter's robust Email Class supports the following features: BCC batches. - Email Debugging tools +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + +*********************** +Using the Email Library +*********************** + Sending Email ============= @@ -31,12 +42,12 @@ This example assumes you are sending the email from one of your $this->load->library('email'); $this->email->from('your@example.com', 'Your Name'); - $this->email->to('someone@example.com'); - $this->email->cc('another@another-example.com'); - $this->email->bcc('them@their-example.com'); + $this->email->to('someone@example.com'); + $this->email->cc('another@another-example.com'); + $this->email->bcc('them@their-example.com'); $this->email->subject('Email Test'); - $this->email->message('Testing the email class.'); + $this->email->message('Testing the email class.'); $this->email->send(); @@ -83,7 +94,7 @@ Preference Default Value Options Descript =================== ====================== ============================ ======================================================================= **useragent** CodeIgniter None The "user agent". **protocol** mail mail, sendmail, or smtp The mail sending protocol. -**mailpath** /usr/sbin/sendmail None The server path to Sendmail. +**mailpath** /usr/sbin/sendmail None The server path to Sendmail. **smtp_host** No Default None SMTP Server Address. **smtp_user** No Default None SMTP Username. **smtp_pass** No Default None SMTP Password. @@ -106,230 +117,289 @@ Preference Default Value Options Descript **dsn** FALSE TRUE or FALSE (boolean) Enable notify message from server =================== ====================== ============================ ======================================================================= -Email Methods Reference -======================= +Overriding Word Wrapping +======================== -$this->email->from() --------------------- +If you have word wrapping enabled (recommended to comply with RFC 822) +and you have a very long link in your email it can get wrapped too, +causing it to become un-clickable by the person receiving it. +CodeIgniter lets you manually override word wrapping within part of your +message like this:: -Sets the email address and name of the person sending the email:: + The text of your email that + gets wrapped normally. - $this->email->from('you@example.com', 'Your Name'); + {unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap} -You can also set a Return-Path, to help redirect undelivered mail:: + More text that will be + wrapped normally. - $this->email->from('you@example.com', 'Your Name', 'returned_emails@example.com'); - -.. note:: Return-Path can't be used if you've configured - 'smtp' as your protocol. -$this->email->reply_to() ------------------------- +Place the item you do not want word-wrapped between: {unwrap} {/unwrap} -Sets the reply-to address. If the information is not provided the -information in the "from" method is used. Example:: +*************** +Class Reference +*************** - $this->email->reply_to('you@example.com', 'Your Name'); +.. class:: CI_Email -$this->email->to() ------------------- + .. method:: from($from[, $name = ''[, $return_path = NULL]]) -Sets the email address(s) of the recipient(s). Can be a single email, a -comma-delimited list or an array:: + :param string $from: "From" 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 - $this->email->to('someone@example.com'); + Sets the email address and name of the person sending the email:: -:: + $this->email->from('you@example.com', 'Your Name'); - $this->email->to('one@example.com, two@example.com, three@example.com'); + You can also set a Return-Path, to help redirect undelivered mail:: -:: + $this->email->from('you@example.com', 'Your Name', 'returned_emails@example.com'); - $list = array('one@example.com', 'two@example.com', 'three@example.com'); + .. note:: Return-Path can't be used if you've configured 'smtp' as + your protocol. - $this->email->to($list); + .. method:: reply_to($replyto[, $name = '']) -$this->email->cc() ------------------- + :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 CC email address(s). Just like the "to", can be a single email, -a comma-delimited list or an array. + Sets the reply-to address. If the information is not provided the + information in the :meth:from method is used. Example:: -$this->email->bcc() -------------------- + $this->email->reply_to('you@example.com', 'Your Name'); -Sets the BCC email address(s). Just like the "to", can be a single -email, a comma-delimited list or an array. + .. method:: to($to) -$this->email->subject() ------------------------ + :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 subject:: + Sets the email address(s) of the recipient(s). Can be a single e-mail, + a comma-delimited list or an array:: - $this->email->subject('This is my subject'); + $this->email->to('someone@example.com'); -$this->email->message() ------------------------ + :: -Sets the email message body:: + $this->email->to('one@example.com, two@example.com, three@example.com'); - $this->email->message('This is my message'); + :: -$this->email->set_alt_message() -------------------------------- + $this->email->to( + array('one@example.com', 'two@example.com', 'three@example.com') + ); -Sets the alternative email message body:: + .. method:: cc($cc) - $this->email->set_alt_message('This is the alternative message'); + :param mixed $cc: Comma-delimited string or an array of e-mail addresses + :returns: CI_Email instance (method chaining) + :rtype: CI_Email -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. + Sets the CC email address(s). Just like the "to", can be a single e-mail, + a comma-delimited list or an array. -$this->email->set_header() --------------------------- + .. method:: bcc($bcc[, $limit = '']) -Appends additional headers to the e-mail:: + :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 - $this->email->set_header('Header1', 'Value1'); - $this->email->set_header('Header2', 'Value2'); + Sets the BCC email address(s). Just like the ``to()`` method, can be a single + e-mail, a comma-delimited list or an array. -$this->email->clear() ---------------------- + If ``$limit`` is set, "batch mode" will be enabled, which will send + the emails to batches, with each batch not exceeding the specified + ``$limit``. -Initializes all the email variables to an empty state. This method is -intended for use if you run the email sending method in a loop, -permitting the data to be reset between cycles. + .. method:: subject($subject) -:: + :param string $subject: E-mail subject line + :returns: CI_Email instance (method chaining) + :rtype: CI_Email - foreach ($list as $name => $address) - { - $this->email->clear(); + Sets the email subject:: - $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(); - } + $this->email->subject('This is my subject'); -If you set the parameter to TRUE any attachments will be cleared as -well:: + .. method:: message($body) - $this->email->clear(TRUE); + :param string $body: E-mail message body + :returns: CI_Email instance (method chaining) + :rtype: CI_Email -$this->email->send() --------------------- + Sets the e-mail message body:: -The Email sending method. Returns boolean TRUE or FALSE based on -success or failure, enabling it to be used conditionally:: + $this->email->message('This is my message'); - if ( ! $this->email->send()) - { - // Generate error - } + .. method:: set_alt_message($str) -This method will automatically clear all parameters if the request was -successful. To stop this behaviour pass FALSE:: + :param string $str: Alternative e-mail message body + :returns: CI_Email instance (method chaining) + :rtype: CI_Email - if ($this->email->send(FALSE)) - { - // Parameters won't be cleared - } + Sets the alternative e-mail message body:: -.. note:: In order to use the ``print_debugger()`` method, you need - to avoid clearing the email parameters. + $this->email->set_alt_message('This is the alternative message'); -$this->email->attach() ----------------------- + 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. -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:: + .. method:: set_header($header, $value) - $this->email->attach('/path/to/photo1.jpg'); - $this->email->attach('/path/to/photo2.jpg'); - $this->email->attach('/path/to/photo3.jpg'); + :param string $header: Header name + :param string $value: Header value + :returns: CI_Email instance (method chaining) + :rtype: CI_Email -To use the default disposition (attachment), leave the second parameter blank, -otherwise use a custom disposition:: + Appends additional headers to the e-mail:: - $this->email->attach('image.jpg', 'inline'); + $this->email->set_header('Header1', 'Value1'); + $this->email->set_header('Header2', 'Value2'); -You can use URL:: + .. method:: clear([$clear_attachments = FALSE]) - $this->email->attach('http://example.com/filename.pdf'); + :param bool $clear_attachments: Whether or not to clear attachments + :returns: CI_Email instance (method chaining) + :rtype: CI_Email -If you'd like to use a custom file name, you can use the third paramater:: + 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. - $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:: + foreach ($list as $name => $address) + { + $this->email->clear(); - $this->email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf'); + $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(); + } -$this->email->attachment_cid() ------------------------------- - -Sets and returns an attachment's Content-ID, which enables your to embed an inline -(picture) attachment into HTML. First parameter must be attached file. - -:: - - $filename = '/img/photo1.jpg'; - $this->email->attach($filename); - foreach ($list as $address) - { - $this->email->to($address); - $cid = $this->email->attach_cid($filename); - $this->email->message('<img src='cid:". $cid ."' alt="photo1" />'); - $this->email->send(); - } + If you set the parameter to TRUE any attachments will be cleared as + well:: -CID for each Email have to be create again to be unique. + $this->email->clear(TRUE); -$this->email->print_debugger() ------------------------------- + .. method:: send([$auto_clear = TRUE]) -Returns a string containing any server messages, the email headers, and -the email messsage. Useful for debugging. + :param bool $auto_clear: Whether to clear message data automatically + :returns: TRUE on success, FALSE on failure + :rtype: bool -You can optionally specify which parts of the message should be printed. -Valid options are: **headers**, **subject**, **body**. + The e-mail sending method. Returns boolean TRUE or FALSE based on + success or failure, enabling it to be used conditionally:: -Example:: + if ( ! $this->email->send()) + { + // Generate error + } - // You need to pass FALSE while sending in order for the email data - // to not be cleared - if that happens, print_debugger() would have - // nothing to output. - $this->email->send(FALSE); + This method will automatically clear all parameters if the request was + successful. To stop this behaviour pass FALSE:: - // Will only print the email headers, excluding the message subject and body - $this->email->print_debugger(array('headers')); + if ($this->email->send(FALSE)) + { + // Parameters won't be cleared + } -.. note:: By default, all of the raw data will be printed. + .. note:: In order to use the ``print_debugger()`` method, you need + to avoid clearing the email parameters. -Overriding Word Wrapping -======================== + .. method:: attach($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]]) -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:: + :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 - The text of your email that - gets wrapped normally. + 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:: - {unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap} + $this->email->attach('/path/to/photo1.jpg'); + $this->email->attach('/path/to/photo2.jpg'); + $this->email->attach('/path/to/photo3.jpg'); - More text that will be - wrapped normally. - + 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 paramater:: + + $this->email->attach('filename.pdf', 'attachment', 'report.pdf'); + + If you need to use a buffer string instead of a real - physical - file you can + use the first parameter as buffer, the third parameter as file name and the fourth + parameter as mime-type:: + + $this->email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf'); + + .. method:: 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->attach_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. + + .. 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 messsage. Useful for debugging. + + You can optionally specify which parts of the message should be printed. + Valid options are: **headers**, **subject**, **body**. + + Example:: + + // You need to pass FALSE while sending in order for the email data + // to not be cleared - if that happens, print_debugger() would have + // nothing to output. + $this->email->send(FALSE); + + // Will only print the email headers, excluding the message subject and body + $this->email->print_debugger(array('headers')); -Place the item you do not want word-wrapped between: {unwrap} {/unwrap}
\ No newline at end of file + .. note:: By default, all of the raw data will be printed.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst index a38122203..567a1e990 100644 --- a/user_guide_src/source/libraries/encryption.rst +++ b/user_guide_src/source/libraries/encryption.rst @@ -10,6 +10,17 @@ reasonable degree of security for encrypted sessions or other such "light" purposes. If Mcrypt is available, you'll be provided with a high degree of security appropriate for storage. +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + +**************************** +Using the Encryption Library +**************************** + Setting your Key ================ @@ -61,104 +72,126 @@ initialized in your controller using the **$this->load->library** function:: $this->load->library('encrypt'); -Once loaded, the Encrypt library object will be available using: -$this->encrypt +Once loaded, the Encrypt library object will be available using +``$this->encrypt`` + +*************** +Class Reference +*************** + +.. class:: CI_Encrypt + + .. method:: encode($string[, $key = '']) + + :param string $string: 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); -$this->encrypt->encode() -======================== + You can optionally pass your encryption key via the second parameter if + you don't want to use the one in your config file:: -Performs the data encryption and returns it as a string. Example:: + $msg = 'My secret message'; + $key = 'super-secret-key'; - $msg = 'My secret message'; + $encrypted_string = $this->encrypt->encode($msg, $key); - $encrypted_string = $this->encrypt->encode($msg); - + .. method:: decode($string[, $key = '']) -You can optionally pass your encryption key via the second parameter if -you don't want to use the one in your config file:: + :param string $string: String to decrypt + :param string $key: Encryption key + :returns: Plain-text string + :rtype: string - $msg = 'My secret message'; - $key = 'super-secret-key'; + Decrypts an encoded string. Example:: - $encrypted_string = $this->encrypt->encode($msg, $key); + $encrypted_string = 'APANtByIGI1BpVXZTJgcsAG8GZl8pdwwa84'; -$this->encrypt->decode() -======================== + $plaintext_string = $this->encrypt->decode($encrypted_string); -Decrypts an encoded string. Example:: + You can optionally pass your encryption key via the second parameter if + you don't want to use the one in your config file:: - $encrypted_string = 'APANtByIGI1BpVXZTJgcsAG8GZl8pdwwa84'; + $msg = 'My secret message'; + $key = 'super-secret-key'; - $plaintext_string = $this->encrypt->decode($encrypted_string); + $encrypted_string = $this->encrypt->decode($msg, $key); -You can optionally pass your encryption key via the second parameter if -you don't want to use the one in your config file:: + .. method:: set_cipher($cipher) - $msg = 'My secret message'; - $key = 'super-secret-key'; + :param int $cipher: Valid PHP MCrypt cypher constant + :returns: CI_Encrypt instance (method chaining) + :rtype: CI_Encrypt - $encrypted_string = $this->encrypt->decode($msg, $key); + Permits you to set an Mcrypt cipher. By default it uses + ``MCRYPT_RIJNDAEL_256``. Example:: -$this->encrypt->set_cipher(); -============================== + $this->encrypt->set_cipher(MCRYPT_BLOWFISH); -Permits you to set an Mcrypt cipher. By default it uses -**MCRYPT_RIJNDAEL_256**. Example:: + Please visit php.net for a list of `available ciphers <http://php.net/mcrypt>`_. - $this->encrypt->set_cipher(MCRYPT_BLOWFISH); + If you'd like to manually test whether your server supports MCrypt you + can use:: -Please visit php.net for a list of `available -ciphers <http://php.net/mcrypt>`_. + echo extension_loaded('mcrypt') ? 'Yup' : 'Nope'; -If you'd like to manually test whether your server supports Mcrypt you -can use:: + .. method:: set_mode($mode) - echo ( ! function_exists('mcrypt_encrypt')) ? 'Nope' : 'Yup'; + :param int $mode: Valid PHP MCrypt mode constant + :returns: CI_Encrypt instance (method chaining) + :rtype: CI_Encrypt -$this->encrypt->set_mode(); -============================ + Permits you to set an Mcrypt mode. By default it uses **MCRYPT_MODE_CBC**. + Example:: -Permits you to set an Mcrypt mode. By default it uses **MCRYPT_MODE_CBC**. -Example:: + $this->encrypt->set_mode(MCRYPT_MODE_CFB); - $this->encrypt->set_mode(MCRYPT_MODE_CFB); + Please visit php.net for a list of `available modes <http://php.net/mcrypt>`_. -Please visit php.net for a list of `available -modes <http://php.net/mcrypt>`_. + .. method:: encode_from_legacy($string[, $legacy_mode = MCRYPT_MODE_ECB[, $key = '']]) -$this->encrypt->encode_from_legacy($orig_data, $legacy_mode = MCRYPT_MODE_ECB, $key = ''); -========================================================================================== + :param string $string: String to encrypt + :param int $legacy_mode: Valid PHP MCrypt cipher constant + :param string $key: Encryption key + :returns: Newly encrypted string + :rtype: string -Enables you to re-encode data that was originally encrypted with -CodeIgniter 1.x to be compatible with the Encryption library in -CodeIgniter 2.x. It is only necessary to use this method if you have -encrypted data stored permanently such as in a file or database and are -on a server that supports Mcrypt. "Light" use encryption such as -encrypted session data or transitory encrypted flashdata require no -intervention on your part. However, existing encrypted Sessions will be -destroyed since data encrypted prior to 2.x will not be decoded. + Enables you to re-encode data that was originally encrypted with + CodeIgniter 1.x to be compatible with the Encryption library in + CodeIgniter 2.x. It is only necessary to use this method if you have + encrypted data stored permanently such as in a file or database and are + on a server that supports Mcrypt. "Light" use encryption such as + encrypted session data or transitory encrypted flashdata require no + intervention on your part. However, existing encrypted Sessions will be + destroyed since data encrypted prior to 2.x will not be decoded. -.. important:: - **Why only a method to re-encode the data instead of maintaining legacy - methods for both encoding and decoding?** The algorithms in the - Encryption library have improved in CodeIgniter 2.x both for performance - and security, and we do not wish to encourage continued use of the older - methods. You can of course extend the Encryption library if you wish and - replace the new methods with the old and retain seamless compatibility - with CodeIgniter 1.x encrypted data, but this a decision that a - developer should make cautiously and deliberately, if at all. + .. important:: + **Why only a method to re-encode the data instead of maintaining legacy + methods for both encoding and decoding?** The algorithms in the + Encryption library have improved in CodeIgniter 2.x both for performance + and security, and we do not wish to encourage continued use of the older + methods. You can of course extend the Encryption library if you wish and + replace the new methods with the old and retain seamless compatibility + with CodeIgniter 1.x encrypted data, but this a decision that a + developer should make cautiously and deliberately, if at all. -:: + :: - $new_data = $this->encrypt->encode_from_legacy($old_encrypted_string); + $new_data = $this->encrypt->encode_from_legacy($old_encrypted_string); -====================== =============== ======================================================================= -Parameter Default Description -====================== =============== ======================================================================= -**$orig_data** n/a The original encrypted data from CodeIgniter 1.x's Encryption library -**$legacy_mode** MCRYPT_MODE_ECB The Mcrypt mode that was used to generate the original encrypted data. - CodeIgniter 1.x's default was MCRYPT_MODE_ECB, and it will assume that - to be the case unless overridden by this parameter. -**$key** n/a The encryption key. This it typically specified in your config file as - outlined above. -====================== =============== =======================================================================
\ No newline at end of file + ====================== =============== ======================================================================= + Parameter Default Description + ====================== =============== ======================================================================= + **$orig_data** n/a The original encrypted data from CodeIgniter 1.x's Encryption library + **$legacy_mode** MCRYPT_MODE_ECB The Mcrypt mode that was used to generate the original encrypted data. + CodeIgniter 1.x's default was MCRYPT_MODE_ECB, and it will assume that + to be the case unless overridden by this parameter. + **$key** n/a The encryption key. This it typically specified in your config file as + outlined above. + ====================== =============== =======================================================================
\ No newline at end of file diff --git a/user_guide_src/source/libraries/file_uploading.rst b/user_guide_src/source/libraries/file_uploading.rst index ac56fabce..d7ba3a6c1 100644 --- a/user_guide_src/source/libraries/file_uploading.rst +++ b/user_guide_src/source/libraries/file_uploading.rst @@ -5,6 +5,13 @@ File Uploading Class CodeIgniter's File Uploading Class permits files to be uploaded. You can set various preferences, restricting the type and size of the files. +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + *********** The Process *********** @@ -245,105 +252,97 @@ preferences in a config file. Class Reference *************** -The following methods are available: +.. class:: CI_Upload -$this->upload->do_upload() -========================== + .. method:: do_upload([$field = 'userfile']) -Performs the upload based on the preferences you've set. + :param string $field: Name of the form field + :returns: TRUE on success, FALSE on failure + :rtype: bool -.. note:: By default the upload routine expects the file to come from - a form field called userfile, and the form must be of type - "multipart". + Performs the upload based on the preferences you've set. -:: + .. note:: By default the upload routine expects the file to come from + a form field called userfile, and the form must be of type + "multipart". - <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:: + <form method="post" action="some_action" enctype="multipart/form-data" /> - $field_name = "some_field_name"; - $this->upload->do_upload($field_name); + If you would like to set your own field name simply pass its value to + the ``do_upload()`` method:: -$this->upload->display_errors() -=============================== + $field_name = "some_field_name"; + $this->upload->do_upload($field_name); -Retrieves any error messages if the ``do_upload()`` method returned -false. The method does not echo automatically, it returns the data so -you can assign it however you need. + .. method:: display_errors([$open = '<p>'[, $close = '</p>']]) -Formatting Errors -***************** + :param string $open: Opening markup + :param string $close: Closing markup + :returns: Formatted error message(s) + :rtype: string -By default the above method wraps any errors within <p> tags. You can -set your own delimiters like this:: + Retrieves any error messages if the ``do_upload()`` method returned + false. The method does not echo automatically, it returns the data so + you can assign it however you need. - $this->upload->display_errors('<p>', '</p>'); + **Formatting Errors** -$this->upload->data() -===================== + By default the above method wraps any errors within <p> tags. You can + set your own delimiters like this:: -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:: + $this->upload->display_errors('<p>', '</p>'); - 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:: + .. method:: data([$index = NULL]) - $this->upload->data('file_name'); // Returns: mypic.jpg + :param string $data: Element to return instead of the full array + :returns: Information about the uploaded file + :rtype: mixed -Explanation -*********** + 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: -Here is an explanation of the above array items. - -Item -Description -**file_name** -The name of the file that was uploaded including the file extension. -**file_type** -The file's Mime type -**file_path** -The absolute server path to the file -**full_path** -The absolute server path including the file name -**raw_name** -The file name without the extension -**orig_name** -The original file name. This is only useful if you use the encrypted -name option. -**client_name** -The file name as supplied by the client user agent, prior to any file -name preparation or incrementing. -**file_ext** -The file extension with period -**file_size** -The file size in kilobytes -**is_image** -Whether the file is an image or not. 1 = image. 0 = not. -**image_width** -Image width. -**image_height** -Image height -**image_type** -Image type. Typically the file extension without the period. -**image_size_str** -A string containing the width and height. Useful to put into an image -tag.
\ No newline at end of file + ================ ==================================================================================================== + Item Description + ================ ==================================================================================================== + file_name Name of the file that was uploaded, including the filename extension + file_type File MIME type identifier + file_path Absolute server path to the file + full_path Absolute server path, including the file name + raw_name File name, without the extension + orig_name Original file name. This is only useful if you use the encrypted name option. + client_name File name as supplied by the client user agent, prior to any file name preparation or incrementing + file_ext Filename extension, period included + file_size File size in kilobytes + is_image Whether the file is an image or not. 1 = image. 0 = not. + image_width Image width + image_height Image height + image_type Image type (usually the file name extension without the period) + image_size_str A string containing the width and height (useful to put into an image tag) + ================ ====================================================================================================
\ No newline at end of file diff --git a/user_guide_src/source/libraries/form_validation.rst b/user_guide_src/source/libraries/form_validation.rst index 1076b1433..988d6fa25 100644 --- a/user_guide_src/source/libraries/form_validation.rst +++ b/user_guide_src/source/libraries/form_validation.rst @@ -353,10 +353,10 @@ commonly is:: set_value('field name') Open your myform.php view file and update the **value** in each field -using the ``set_value()`` function: +using the :func:`set_value()` function: -**Don't forget to include each field name in the ``set_value()`` -functions!** +**Don't forget to include each field name in the :func:`set_value()` +function calls!** :: @@ -393,11 +393,11 @@ Now reload your page and submit the form so that it triggers an error. Your form fields should now be re-populated .. note:: The :ref:`class-reference` section below - contains functions that permit you to re-populate <select> menus, + contains methods that permit you to re-populate <select> menus, radio buttons, and checkboxes. -**Important Note:** If you use an array as the name of a form field, you -must supply it as an array to the function. Example:: +.. important:: If you use an array as the name of a form field, you + must supply it as an array to the function. Example:: <input type="text" name="colors[]" value="<?php echo set_value('colors[]'); ?>" size="50" /> @@ -497,8 +497,8 @@ some particular rule, use the set_rules() method:: Where rule corresponds to the name of a particular rule, and Error Message is the text you would like displayed. -If you'd like to include a field's "human" name, or the optional -parameter some rules allow for (such as max_length), you can add the +If you'd like to include a field's "human" name, or the optional +parameter some rules allow for (such as max_length), you can add the **{field}** and **{param}** tags to your message, respectively:: $this->form_validation->set_message('min_length', '{field} must have at least {param} characters.'); @@ -579,7 +579,7 @@ Showing Errors Individually =========================== If you prefer to show an error message next to each form field, rather -than as a list, you can use the ``form_error()`` function. +than as a list, you can use the :func:`form_error()` function. Try it! Change your form so that it looks like this:: @@ -880,15 +880,15 @@ use: ========================= ========== ============================================================================================= ======================= Rule Parameter Description Example ========================= ========== ============================================================================================= ======================= -**required** No Returns FALSE if the form element is empty. -**matches** Yes Returns FALSE if the form element does not match the one in the parameter. matches[form_item] -**differs** Yes Returns FALSE if the form element does not differ from the one in the parameter. differs[form_item] -**is_unique** Yes Returns FALSE if the form element is not unique to the table and field name in the is_unique[table.field] - parameter. Note: This rule requires :doc:`Query Builder <../database/query_builder>` to be +**required** No Returns FALSE if the form element is empty. +**matches** Yes Returns FALSE if the form element does not match the one in the parameter. matches[form_item] +**differs** Yes Returns FALSE if the form element does not differ from the one in the parameter. differs[form_item] +**is_unique** Yes Returns FALSE if the form element is not unique to the table and field name in the is_unique[table.field] + parameter. Note: This rule requires :doc:`Query Builder <../database/query_builder>` to be enabled in order to work. -**min_length** Yes Returns FALSE if the form element is shorter then the parameter value. min_length[3] -**max_length** Yes Returns FALSE if the form element is longer then the parameter value. max_length[12] -**exact_length** Yes Returns FALSE if the form element is not exactly the parameter value. exact_length[8] +**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] @@ -897,15 +897,15 @@ Rule Parameter Description not numeric. **less_than_equal_to** Yes Returns FALSE if the form element is greater than the parameter value, less_than_equal_to[8] or not numeric. -**alpha** No Returns FALSE if the form element contains anything other than alphabetical characters. +**alpha** No Returns FALSE if the form element contains anything other than alphabetical characters. **alpha_numeric** No Returns FALSE if the form element contains anything other than alpha-numeric characters. **alpha_numeric_spaces** No Returns FALSE if the form element contains anything other than alpha-numeric characters - or spaces. Should be used after trim to avoid spaces at the beginning or end. -**alpha_dash** No Returns FALSE if the form element contains anything other than alpha-numeric characters, - underscores or dashes. -**numeric** No Returns FALSE if the form element contains anything other than numeric characters. -**integer** No Returns FALSE if the form element contains anything other than an integer. -**decimal** No Returns FALSE if the form element contains anything other than a decimal number. + or spaces. Should be used after trim to avoid spaces at the beginning or end. +**alpha_dash** No Returns FALSE if the form element contains anything other than alpha-numeric characters, + underscores or dashes. +**numeric** No Returns FALSE if the form element contains anything other than numeric characters. +**integer** No Returns FALSE if the form element contains anything other than an integer. +**decimal** No Returns FALSE if the form element contains anything other than a decimal number. **is_natural** No Returns FALSE if the form element contains anything other than a natural number: 0, 1, 2, 3, etc. **is_natural_no_zero** No Returns FALSE if the form element contains anything other than a natural @@ -954,155 +954,118 @@ Name Parameter Description Class Reference *************** -.. php:class:: Form_validation - -The following methods are intended for use in your controller. +.. class:: CI_Form_validation -$this->form_validation->set_rules() -=================================== + .. method:: set_rules($field[, $label = ''[, $rules = '']]) - .. php:method:: set_rules ($field, $label = '', $rules = '', $errors = array()) - - :param string $field: The field name - :param string $label: The field label - :param mixed $rules: The rules, as a string with rules separated by a pipe "|", or an array or rules. - :param array $errors: Custom error messages - :rtype: Object + :param string $field: Field name + :param string $label: Field label + :param mixed $rules: Validation rules, as a string list separated by a pipe "|", or as an array or rules + :returns: CI_Form_validation instance (method chaining) + :rtype: CI_Form_validation Permits you to set validation rules, as described in the tutorial sections above: - - :ref:`setting-validation-rules` - - :ref:`saving-groups` + - :ref:`setting-validation-rules` + - :ref:`saving-groups` -$this->form_validation->run() -============================= - - .. php:method:: run ($group = '') + .. method:: run([$group = '']) - :param string $group: The name of the validation group to run - :rtype: Boolean + :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` -$this->form_validation->set_message() -===================================== - - .. php:method:: set_message ($lang, $val = '') + .. method:: set_message($lang[, $val = '']) - :param string $lang: The rule the message is for - :param string $val: The message - :rtype: Object + :param string $lang: The rule the message is for + :param string $val: The message + :returns: CI_Form_validation instance (method chaining) + :rtype: CI_Form_validation Permits you to set custom error messages. See :ref:`setting-error-messages` -$this->form_validation->set_data() -================================== - - .. php:method:: set_data ($data = '') + .. method:: set_error_delimiters([$prefix = '<p>'[, $suffix = '</p>']]) - :param array $data: The data to validate + :param string $prefix: Error message prefix + :param string $suffix: Error message suffix + :returns: CI_Form_validation instance (method chaining) + :rtype: CI_Form_validation + + Sets the default prefix and suffix for error messages. + + .. method:: set_data($data) + + :param array $data: 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. + ``$_POST`` array. -$this->form_validation->reset_validation() -========================================== + .. method:: reset_validation() - .. 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. -$this->form_validation->error_array() -===================================== - - .. php:method:: error_array () + .. method:: error_array() - :rtype: Array + :returns: Array of error messages + :rtype: array Returns the error messages as an array. -.. _helper-functions: - -**************** -Helper Reference -**************** - -The following helper functions are available for use in the view files -containing your forms. Note that these are procedural functions, so they -**do not** require you to prepend them with $this->form_validation. - -form_error() -============ - -Shows an individual error message associated with the field name -supplied to the function. Example:: - - <?php echo form_error('username'); ?> - -The error delimiters can be optionally specified. See the -:ref:`changing-delimiters` section above. + .. method:: error_string([$prefix = ''[, $suffix = '']]) -validation_errors() -=================== + :param string $prefix: Error message prefix + :param string $suffix: Error message suffix + :returns: Error messages as a string + :rtype: string -Shows all error messages as a string: Example:: + Returns all error messages (as returned from error_array()) formatted as a + string and separated by a newline character. - <?php echo validation_errors(); ?> + .. method:: error($field[, $prefix = ''[, $suffix = '']]) -The error delimiters can be optionally specified. See the -:ref:`changing-delimiters` section above. - -set_value() -=========== + :param string $field: Field name + :param string $prefix: Optional prefix + :param string $suffix: Optional suffix + :returns: Error message string + :rtype: string -Permits you to set the value of an input form or textarea. You must -supply the field name via the first parameter of the function. The -second (optional) parameter allows you to set a default value for the -form. Example:: + Returns the error message for a specific field, optionally adding a + prefix and/or suffix to it (usually HTML tags). - <input type="text" name="quantity" value="<?php echo set_value('quantity', '0'); ?>" size="50" /> + .. method:: has_rule($field) -The above form will show "0" when loaded for the first time. + :param string $field: Field name + :returns: TRUE if the field has rules set, FALSE if not + :rtype: bool -set_select() -============ + Checks to see if there is a rule set for the specified field. -If you use a <select> menu, this function permits you to display the -menu item that was selected. The first parameter must contain the name -of the select menu, the second parameter must contain the value of each -item, and the third (optional) parameter lets you set an item as the -default (use boolean TRUE/FALSE). - -Example:: - - <select name="myselect"> - <option value="one" <?php echo set_select('myselect', 'one', TRUE); ?> >One</option> - <option value="two" <?php echo set_select('myselect', 'two'); ?> >Two</option> - <option value="three" <?php echo set_select('myselect', 'three'); ?> >Three</option> - </select> - -set_checkbox() -============== - -Permits you to display a checkbox in the state it was submitted. The -first parameter must contain the name of the checkbox, the second -parameter must contain its value, and the third (optional) parameter -lets you set an item as the default (use boolean TRUE/FALSE). Example:: - - <input type="checkbox" name="mycheck[]" value="1" <?php echo set_checkbox('mycheck[]', '1'); ?> /> - <input type="checkbox" name="mycheck[]" value="2" <?php echo set_checkbox('mycheck[]', '2'); ?> /> +.. _helper-functions: -set_radio() -=========== +**************** +Helper Reference +**************** -Permits you to display radio buttons in the state they were submitted. -This function is identical to the **set_checkbox()** function above. +Please refer to the :doc:`Form Helper <../helpers/form_helper>` manual for +the following functions: -:: +- :func:`form_error()` +- :func:`validation_errors()` +- :func:`set_value()` +- :func:`set_select()` +- :func:`set_checkbox()` +- :func:`set_radio()` - <input type="radio" name="myradio" value="1" <?php echo set_radio('myradio', '1', TRUE); ?> /> - <input type="radio" name="myradio" value="2" <?php echo set_radio('myradio', '2'); ?> /> +Note that these are procedural functions, so they **do not** require you +to prepend them with ``$this->form_validation``.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/ftp.rst b/user_guide_src/source/libraries/ftp.rst index 05a3fdcc8..dd9440443 100644 --- a/user_guide_src/source/libraries/ftp.rst +++ b/user_guide_src/source/libraries/ftp.rst @@ -10,9 +10,19 @@ directory to be recreated remotely via FTP. .. note:: SFTP and SSL FTP protocols are not supported, only standard FTP. -********************** +.. contents:: + :local: + +.. raw:: html + + <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:: @@ -27,7 +37,6 @@ Usage Examples In this example a connection is opened to the FTP server, and a local file is read and uploaded in ASCII mode. The file permissions are set to 755. - :: $this->load->library('ftp'); @@ -44,7 +53,6 @@ file is read and uploaded in ASCII mode. The file permissions are set to $this->ftp->close(); In this example a list of files is retrieved from the server. - :: $this->load->library('ftp'); @@ -63,7 +71,6 @@ In this example a list of files is retrieved from the server. $this->ftp->close(); In this example a local directory is mirrored on the server. - :: $this->load->library('ftp'); @@ -79,171 +86,221 @@ In this example a local directory is mirrored on the server. $this->ftp->close(); -****************** -Function Reference -****************** +*************** +Class Reference +*************** -$this->ftp->connect() -===================== +.. class:: CI_FTP -Connects and logs into to the FTP server. Connection preferences are set -by passing an array to the function, or you can store them in a config -file. + .. method:: connect([$config = array()]) -Here is an example showing how you set preferences manually:: + :param array $config: Connection values + :returns: TRUE on success, FALSE on failure + :rtype: bool - $this->load->library('ftp'); + Connects and logs into to the FTP server. Connection preferences are set + by passing an array to the function, or you can store them in a config + file. - $config['hostname'] = 'ftp.example.com'; - $config['username'] = 'your-username'; - $config['password'] = 'your-password'; - $config['port'] = 21; - $config['passive'] = FALSE; - $config['debug'] = TRUE; + Here is an example showing how you set preferences manually:: - $this->ftp->connect($config); + $this->load->library('ftp'); -Setting FTP Preferences in a Config File -**************************************** + $config['hostname'] = 'ftp.example.com'; + $config['username'] = 'your-username'; + $config['password'] = 'your-password'; + $config['port'] = 21; + $config['passive'] = FALSE; + $config['debug'] = TRUE; -If you prefer you can store your FTP preferences in a config file. -Simply create a new file called the ftp.php, add the $config array in -that file. Then save the file at config/ftp.php and it will be used -automatically. + $this->ftp->connect($config); -Available connection options -**************************** + **Setting FTP Preferences in a Config File** -- **hostname** - the FTP hostname. Usually something like: - ftp.example.com -- **username** - the FTP username. -- **password** - the FTP password. -- **port** - The port number. Set to 21 by default. -- **debug** - TRUE/FALSE (boolean). Whether to enable debugging to - display error messages. -- **passive** - TRUE/FALSE (boolean). Whether to use passive mode. - Passive is set automatically by default. + If you prefer you can store your FTP preferences in a config file. + Simply create a new file called the ftp.php, add the $config array in + that file. Then save the file at *application/config/ftp.php* and it + will be used automatically. -$this->ftp->upload() -==================== + **Available connection options** -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:: + ============== =============== ============================================================================= + 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 + ============== =============== ============================================================================= - $this->ftp->upload('/local/path/to/myfile.html', '/public_html/myfile.html', 'ascii', 0775); + .. method:: upload($locpath, $rempath[, $mode = 'auto'[, $permissions = NULL]]) -**Mode options are:** ascii, binary, and auto (the default). If auto is -used it will base the mode on the file extension of the source file. + :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 -If set, permissions have to be passed as an octal value. + 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->download() -====================== + $this->ftp->upload('/local/path/to/myfile.html', '/public_html/myfile.html', 'ascii', 0775); -Downloads a file from your server. You must supply the remote path and -the local path, and you can optionally set the mode. Example:: + If 'auto' mode is used it will base the mode on the file extension of the source file. - $this->ftp->download('/public_html/myfile.html', '/local/path/to/myfile.html', 'ascii'); + If set, permissions have to be passed as an octal value. -**Mode options are:** ascii, binary, and auto (the default). If auto is -used it will base the mode on the file extension of the source file. + .. method:: download($rempath, $locpath[, $mode = 'auto']) -Returns FALSE if the download does not execute successfully (including -if PHP does not have permission to write the local file) + :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 -$this->ftp->rename() -==================== + Downloads a file from your server. You must supply the remote path and + the local path, and you can optionally set the mode. Example:: -Permits you to rename a file. Supply the source file name/path and the -new file name/path. + $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. - // Renames green.html to blue.html - $this->ftp->rename('/public_html/foo/green.html', '/public_html/foo/blue.html'); + Returns FALSE if the download does not execute successfully + (including if PHP does not have permission to write the local file). -$this->ftp->move() -================== + .. method:: rename($old_file, $new_file[, $move = FALSE]) -Lets you move a file. Supply the source and destination paths:: + :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 - // Moves blog.html from "joe" to "fred" - $this->ftp->move('/public_html/joe/blog.html', '/public_html/fred/blog.html'); + Permits you to rename a file. Supply the source file name/path and the new file name/path. + :: -Note: if the destination file name is different the file will be -renamed. + // Renames green.html to blue.html + $this->ftp->rename('/public_html/foo/green.html', '/public_html/foo/blue.html'); -$this->ftp->delete_file() -========================== + .. method:: move($old_file, $new_file) -Lets you delete a file. Supply the source path with the file name. + :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:: - $this->ftp->delete_file('/public_html/joe/blog.html'); + // Moves blog.html from "joe" to "fred" + $this->ftp->move('/public_html/joe/blog.html', '/public_html/fred/blog.html'); -$this->ftp->delete_dir() -========================= + .. note:: If the destination file name is different the file will be renamed. -Lets you delete a directory and everything it contains. Supply the -source path to the directory with a trailing slash. + .. method:: delete_file($filepath) -**Important** Be VERY careful with this function. It will recursively -delete **everything** within the supplied path, including sub-folders -and all files. Make absolutely sure your path is correct. Try using the -list_files() function first to verify that your path is correct. + :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_dir('/public_html/path/to/folder/'); + $this->ftp->delete_file('/public_html/joe/blog.html'); -$this->ftp->list_files() -========================= + .. method:: delete_dir($filepath) -Permits you to retrieve a list of files on your server returned as an -array. You must supply the path to the desired directory. + :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. - $list = $this->ftp->list_files('/public_html/'); + .. 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. - print_r($list); + :: -$this->ftp->mirror() -==================== + $this->ftp->delete_dir('/public_html/path/to/folder/'); -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:: + .. method:: list_files([$path = '.']) - $this->ftp->mirror('/path/to/myfolder/', '/public_html/myfolder/'); + :param string $path: Directory path + :returns: An array list of files or FALSE on failure + :rtype: array -$this->ftp->mkdir() -=================== + Permits you to retrieve a list of files on your server returned as an + array. You must supply the path to the desired directory. + :: -Lets you create a directory on your server. Supply the path ending in -the folder name you wish to create, with a trailing slash. Permissions -can be set by passed an octal value in the second parameter (if you are -running PHP 5). + $list = $this->ftp->list_files('/public_html/'); + print_r($list); -:: + .. 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/'); + + .. 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/', DIR_WRITE_MODE); + + .. 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 777 + $this->ftp->chmod('/public_html/foo/bar/', DIR_WRITE_MODE); + + .. method:: changedir($path[, $suppress_debug = FALSE]) - // Creates a folder named "bar" - $this->ftp->mkdir('/public_html/foo/bar/', DIR_WRITE_MODE); + :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 -$this->ftp->chmod() -=================== + Changes the current working directory to the specified path. -Permits you to set file permissions. Supply the path to the file or -folder you wish to alter permissions on:: + The ``$suppress_debug`` parameter is useful in case you want to use this method + as an ``is_dir()`` alternative for FTP. - // Chmod "bar" to 777 - $this->ftp->chmod('/public_html/foo/bar/', DIR_WRITE_MODE); + .. method:: close() -$this->ftp->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. + Closes the connection to your server. It's recommended that you use this + when you are finished uploading.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/image_lib.rst b/user_guide_src/source/libraries/image_lib.rst index dcdccbd92..16acf090b 100644 --- a/user_guide_src/source/libraries/image_lib.rst +++ b/user_guide_src/source/libraries/image_lib.rst @@ -19,6 +19,13 @@ ImageMagick order for the script to calculate the image properties. The image processing, however, will be performed with the library you specify. +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + ********************** Initializing the Class ********************** @@ -29,7 +36,7 @@ in your controller using the $this->load->library function:: $this->load->library('image_lib'); Once the library is loaded it will be ready for use. The image library -object you will use to call all functions is: $this->image_lib +object you will use to call all functions is: ``$this->image_lib`` Processing an Image =================== @@ -67,18 +74,17 @@ ratio. The thumbnail will be called *mypic_thumb.jpg* while processing images you may need to limit their maximum size, and/or adjust PHP memory limits. -Processing Functions -==================== +Processing Methods +================== -There are four available processing functions: +There are four available processing methods: - $this->image_lib->resize() - $this->image_lib->crop() - $this->image_lib->rotate() - $this->image_lib->watermark() -- $this->image_lib->clear() -These functions return boolean TRUE upon success and FALSE for failure. +These methods return boolean TRUE upon success and FALSE for failure. If they fail you can retrieve the error message using this function:: echo $this->image_lib->display_errors(); @@ -88,7 +94,7 @@ error upon failure, like this:: if ( ! $this->image_lib->resize()) { - echo $this->image_lib->display_errors(); + echo $this->image_lib->display_errors(); } .. note:: You can optionally specify the HTML formatting to be applied to @@ -97,6 +103,8 @@ error upon failure, like this:: $this->image_lib->display_errors('<p>', '</p>'); +.. _processing-preferences: + Preferences =========== @@ -146,7 +154,7 @@ Preference Default Value Options pixels. If the source image size does not allow perfect resizing to those dimensions, this setting determines which axis should be used as the hard value. "auto" sets the axis automatically based on whether the - image is taller then wider, or vice versa. + image is taller than wider, or vice versa. **rotation_angle** None 90, 180, 270, vrt, hor Specifies the angle of rotation when rotating images. Note that PHP X rotates counter-clockwise, so a 90 degree rotation to the right must be specified as 270. @@ -162,134 +170,10 @@ Setting preferences in a config file If you prefer not to set preferences using the above method, you can instead put them into a config file. Simply create a new file called image_lib.php, add the $config array in that file. Then save the file -in: config/image_lib.php and it will be used automatically. You will -NOT need to use the $this->image_lib->initialize function if you save +in *config/image_lib.php* and it will be used automatically. You will +NOT need to use the ``$this->image_lib->initialize()`` method if you save your preferences in a config file. -$this->image_lib->resize() -=========================== - -The image resizing function lets you resize the original image, create a -copy (with or without resizing), or create a thumbnail image. - -For practical purposes there is no difference between creating a copy -and creating a thumbnail except a thumb will have the thumbnail marker -as part of the name (ie, mypic_thumb.jpg). - -All preferences listed in the table above are available for this -function except these three: rotation_angle, x_axis, and y_axis. - -Creating a Thumbnail --------------------- - -The resizing function will create a thumbnail file (and preserve the -original) if you set this preference to TRUE:: - - $config['create_thumb'] = TRUE; - -This single preference determines whether a thumbnail is created or not. - -Creating a Copy ---------------- - -The resizing function will create a copy of the image file (and preserve -the original) if you set a path and/or a new filename using this -preference:: - - $config['new_image'] = '/path/to/new_image.jpg'; - -Notes regarding this preference: - -- If only the new image name is specified it will be placed in the same - folder as the original -- If only the path is specified, the new image will be placed in the - destination with the same name as the original. -- If both the path and image name are specified it will placed in its - own destination and given the new name. - -Resizing the Original Image ---------------------------- - -If neither of the two preferences listed above (create_thumb, and -new_image) are used, the resizing function will instead target the -original image for processing. - -$this->image_lib->crop() -========================= - -The cropping function works nearly identically to the resizing function -except it requires that you set preferences for the X and Y axis (in -pixels) specifying where to crop, like this:: - - $config['x_axis'] = '100'; - $config['y_axis'] = '40'; - -All preferences listed in the table above are available for this -function except these: rotation_angle, create_thumb, new_image. - -Here's an example showing how you might crop an image:: - - $config['image_library'] = 'imagemagick'; - $config['library_path'] = '/usr/X11R6/bin/'; - $config['source_image'] = '/path/to/image/mypic.jpg'; - $config['x_axis'] = '100'; - $config['y_axis'] = '60'; - - $this->image_lib->initialize($config); - - if ( ! $this->image_lib->crop()) - { - echo $this->image_lib->display_errors(); - } - -.. note:: Without a visual interface it is difficult to crop images, so this - function is not very useful unless you intend to build such an - interface. That's exactly what we did using for the photo gallery module - in ExpressionEngine, the CMS we develop. We added a JavaScript UI that - lets the cropping area be selected. - -$this->image_lib->rotate() -=========================== - -The image rotation function requires that the angle of rotation be set -via its preference:: - - $config['rotation_angle'] = '90'; - -There are 5 rotation options: - -#. 90 - rotates counter-clockwise by 90 degrees. -#. 180 - rotates counter-clockwise by 180 degrees. -#. 270 - rotates counter-clockwise by 270 degrees. -#. hor - flips the image horizontally. -#. vrt - flips the image vertically. - -Here's an example showing how you might rotate an image:: - - $config['image_library'] = 'netpbm'; - $config['library_path'] = '/usr/bin/'; - $config['source_image'] = '/path/to/image/mypic.jpg'; - $config['rotation_angle'] = 'hor'; - - $this->image_lib->initialize($config); - - if ( ! $this->image_lib->rotate()) - { - echo $this->image_lib->display_errors(); - } - -$this->image_lib->clear() -========================== - -The clear function resets all of the values used when processing an -image. You will want to call this if you are processing images in a -loop. - -:: - - $this->image_lib->clear(); - - ****************** Image Watermarking ****************** @@ -310,10 +194,12 @@ There are two types of watermarking that you can use: image (usually a transparent PNG or GIF) containing your watermark over the source image. +.. _watermarking: + Watermarking an Image ===================== -Just as with the other functions (resizing, cropping, and rotating) the +Just as with the other methods (resizing, cropping, and rotating) the general process for watermarking involves setting the preferences corresponding to the action you intend to perform, then calling the watermark function. Here is an example:: @@ -423,3 +309,164 @@ Preference Default Value Options Description coordinate to a pixel representative of the color you want to be transparent. ======================= =================== =================== ========================================================================== + +*************** +Class Reference +*************** + +.. class:: CI_Image_lib + + .. method:: initialize([$props = array()]) + + :param array $props: Image processing preferences + :returns: TRUE on success, FALSE in case of invalid settings + :rtype: bool + + Initializes the class for processing an image. + + .. 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. + + .. 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. + + .. 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(); + } + + .. 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. + + .. 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(); + + .. 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->diplay_errors();
\ No newline at end of file diff --git a/user_guide_src/source/libraries/input.rst b/user_guide_src/source/libraries/input.rst index 72746c147..6162a6664 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -10,6 +10,13 @@ The Input Class serves two purposes: .. note:: This class is initialized automatically by the system so there is no need to do it manually. +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + Security Filtering ================== @@ -17,7 +24,7 @@ The security filtering method is called automatically when a new :doc:`controller <../general/controllers>` is invoked. It does the following: -- If $config['allow_get_array'] is FALSE (default is TRUE), destroys +- If ``$config['allow_get_array']`` is FALSE (default is TRUE), destroys the global GET array. - Destroys all global variables in the event register_globals is turned on. @@ -34,7 +41,7 @@ XSS Filtering The Input class has the ability to filter input automatically to prevent cross-site scripting attacks. If you want the filter to run automatically every time it encounters POST or COOKIE data you can -enable it by opening your application/config/config.php file and setting +enable it by opening your *application/config/config.php* file and setting this:: $config['global_xss_filtering'] = TRUE; @@ -45,7 +52,7 @@ information on using XSS Filtering in your application. Using POST, GET, COOKIE, or SERVER Data ======================================= -CodeIgniter comes with four helper methods that let you fetch POST, GET, +CodeIgniter comes with helper methods that let you fetch POST, GET, COOKIE or SERVER items. The main advantage of using the provided methods rather than fetching an item directly (``$_POST['something']``) is that the methods will check to see if the item is set and return @@ -59,273 +66,344 @@ With CodeIgniter's built in methods you can simply do this:: $something = $this->input->post('something'); -The four methods are: +The main methods are: -- $this->input->post() -- $this->input->get() -- $this->input->cookie() -- $this->input->server() +- ``$this->input->post()`` +- ``$this->input->get()`` +- ``$this->input->cookie()`` +- ``$this->input->server()`` -$this->input->post() -==================== +Using the php://input stream +============================ -The first parameter will contain the name of the POST item you are -looking for:: +If you want to utilize the PUT, DELETE, PATCH or other exotic request +methods, they can only be accessed via a special input stream, that +can only be read once. This isn't as easy as just reading from e.g. +the ``$_POST`` array, because it will always exist and you can try +and access multiple variables without caring that you might only have +one shot at all of the POST data. - $this->input->post('some_data'); +CodeIgniter will take care of that for you, and you can access data +from the **php://input** stream at any time, just by calling the +``input_stream()`` method:: -The method returns NULL if the item you are attempting to retrieve -does not exist. + $this->input->input_stream('key'); -The second optional parameter lets you run the data through the XSS -filter. It's enabled by setting the second parameter to boolean TRUE; +Similar to other methods such as ``get()`` and ``post()``, if the +requested data is not found, it will return NULL and you can also +decide whether to run the data through ``xss_clean()`` by passing +a boolean value as the second parameter:: -:: + $this->input->input_stream('key', TRUE); // XSS Clean + $this->input->input_stream('key', FALSE); // No XSS filter - $this->input->post('some_data', TRUE); +.. note:: You can utilize ``method()`` in order to know if you're reading + PUT, DELETE or PATCH data. -To return an array of all POST items call without any parameters. +*************** +Class Reference +*************** -To return all POST items and pass them through the XSS filter set the -first parameter NULL while setting the second parameter to boolean; +.. class:: CI_Input -The method returns NULL if there are no items in the POST. + .. method:: post([$index = NULL[, $xss_clean = NULL]]) -:: + :param string $index: POST parameter name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: $_POST if no parameters supplied, otherwise the POST value if found or NULL if not + :rtype: mixed - $this->input->post(NULL, TRUE); // returns all POST items with XSS filter - $this->input->post(); // returns all POST items without XSS filter + The first parameter will contain the name of the POST item you are + looking for:: -$this->input->get() -=================== + $this->input->post('some_data'); -This method is identical to the POST method, only it fetches GET data -:: + The method returns NULL if the item you are attempting to retrieve + does not exist. - $this->input->get('some_data', TRUE); + The second optional parameter lets you run the data through the XSS + filter. It's enabled by setting the second parameter to boolean TRUE + or by setting your ``$config['global_xss_filtering']`` to TRUE. + :: -To return an array of all GET items call without any parameters. + $this->input->post('some_data', TRUE); -To return all GET items and pass them through the XSS filter set the -first parameter NULL while setting the second parameter to boolean; + To return an array of all POST items call without any parameters. -The method returns NULL if there are no items in the GET. + To return all POST items and pass them through the XSS filter set the + first parameter NULL while setting the second parameter to boolean TRUE. + :: -:: + $this->input->post(NULL, TRUE); // returns all POST items with XSS filter + $this->input->post(NULL, FALSE); // returns all POST items without XSS filter - $this->input->get(NULL, TRUE); // returns all GET items with XSS filter - $this->input->get(); // returns all GET items without XSS filtering + .. method:: get([$index = NULL[, $xss_clean = NULL]]) + :param string $index: GET parameter name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: $_GET if no parameters supplied, otherwise the GET value if found or NULL if not + :rtype: mixed -$this->input->post_get() -======================== + This method is identical to ``post()``, only it fetches GET data. + :: -This method will search through both the POST and GET streams for -data, looking first in POST, and then in GET:: + $this->input->get('some_data', TRUE); - $this->input->post_get('some_data', TRUE); + To return an array of all GET items call without any parameters. -$this->input->get_post() -======================== + To return all GET items and pass them through the XSS filter set the + first parameter NULL while setting the second parameter to boolean TRUE. + :: -This method will search through both the POST and GET streams for -data, looking first in GET, and then in POST:: + $this->input->get(NULL, TRUE); // returns all GET items with XSS filter + $this->input->get(NULL, FALSE); // returns all GET items without XSS filtering - $this->input->get_post('some_data', TRUE); + .. method:: post_get($index[, $xss_clean = NULL]) -$this->input->cookie() -====================== + :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 is identical to the POST method, only it fetches cookie data -:: + 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->cookie('some_cookie'); - $this->input->cookie('some_cookie, TRUE); // with XSS filter + $this->input->post_get('some_data', TRUE); + .. method:: get_post($index[, $xss_clean = NULL]) -$this->input->server() -====================== + :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 is identical to the above methods, only it fetches server -server data:: + This method works the same way as ``post_get()`` only it looks for GET + data first. - $this->input->server('some_data'); + $this->input->get_post('some_data', TRUE); -Using the php://input stream -============================ + .. note:: This method used to act EXACTLY like ``post_get()``, but it's + behavior has changed in CodeIgniter 3.0. -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. + .. method:: cookie([$index = NULL[, $xss_clean = NULL]]) -CodeIgniter will take care of that for you, and you can access data -from the **php://input** stream at any time, just by calling the -``input_stream()`` method:: + :param string $index: COOKIE parameter name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: $_COOKIE if no parameters supplied, otherwise the COOKIE value if found or NULL if not + :rtype: mixed - $this->input->input_stream('key'); + This method is identical to ``post()`` and ``get()``, only it fetches cookie + data:: -Similar to the methods above, if the requested data is not found, it -will return NULL and you can also decide whether to run the data -through ``xss_clean()`` by passing a boolean value as the second -parameter:: + $this->input->cookie('some_cookie'); + $this->input->cookie('some_cookie, TRUE); // with XSS filter - $this->input->input_stream('key', TRUE); // XSS Clean - $this->input->input_stream('key', FALSE); // No XSS filter + .. method:: server($index[, $xss_clean = NULL]) -.. note:: You can utilize method() in order to know if you're reading - PUT, DELETE or PATCH data. + :param string $index: Value name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: $_SERVER item value if found, NULL if not + :rtype: mixed + + This method is identical to the ``post()``, ``get()`` and ``cookie()`` + methods, only it fetches server data (``$_SERVER``):: + + $this->input->server('some_data'); + + .. method:: input_stream([$index = NULL[, $xss_clean = NULL]]) + + :param string $index: Key name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: Input stream array if no parameters supplied, otherwise the specified value if found or NULL if not + :rtype: mixed + + This method is identical to ``get()``, ``post()`` and ``cookie()``, + only it fetches the *php://input* stream data. + + .. method:: set_cookie($name = ''[, $value = ''[, $expire = ''[, $domain = ''[, $path = '/'[, $prefix = ''[, $secure = FALSE[, $httponly = FALSE]]]]]]]) + + :param mixed $name: Cookie name or an array of parameters + :param string $value: Cookie value + :param int $expire: Cookie expiration time in seconds + :param string $domain: Cookie domain + :param string $path: Cookie path + :param string $prefix: Cookie name prefix + :param bool $secure: Whether to only transfer the cookie through HTTPS + :param bool $httponly: Whether to only make the cookie accessible for HTTP requests (no JavaScript) + :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:: -$this->input->set_cookie() -========================== + $cookie = array( + 'name' => 'The Cookie Name', + 'value' => 'The Value', + 'expire' => '86500', + 'domain' => '.some-domain.com', + 'path' => '/', + 'prefix' => 'myprefix_', + 'secure' => TRUE + ); -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: + $this->input->set_cookie($cookie); -Array Method -^^^^^^^^^^^^ + **Notes** -Using this method, an associative array is passed to the first -parameter:: + Only the name and value are required. To delete a cookie set it with the + expiration blank. - $cookie = array( - 'name' => 'The Cookie Name', - 'value' => 'The Value', - 'expire' => '86500', - 'domain' => '.some-domain.com', - 'path' => '/', - 'prefix' => 'myprefix_', - 'secure' => TRUE - ); + The expiration is set in **seconds**, which will be added to the current + time. Do not include the time, but rather only the number of seconds + from *now* that you wish the cookie to be valid. If the expiration is + set to zero the cookie will only last as long as the browser is open. - $this->input->set_cookie($cookie); + 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 -**Notes:** + The path is usually not needed since the method sets a root path. -Only the name and value are required. To delete a cookie set it with the -expiration blank. + The prefix is only needed if you need to avoid name collisions with + other identically named cookies for your server. -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. + The secure boolean is only needed if you want to make it a secure cookie + by setting it to TRUE. -For site-wide cookies regardless of how your site is requested, add your -URL to the **domain** starting with a period, like this: -.your-domain.com + **Discrete Parameters** -The path is usually not needed since the method sets a root path. + If you prefer, you can set the cookie by passing data using individual + parameters:: -The prefix is only needed if you need to avoid name collisions with -other identically named cookies for your server. + $this->input->set_cookie($name, $value, $expire, $domain, $path, $prefix, $secure); -The secure boolean is only needed if you want to make it a secure cookie -by setting it to TRUE. + .. method:: ip_address() -Discrete Parameters -^^^^^^^^^^^^^^^^^^^ + :returns: Visitor's IP address or '0.0.0.0' if not valid + :rtype: string -If you prefer, you can set the cookie by passing data using individual -parameters:: + Returns the IP address for the current user. If the IP address is not + valid, the method will return '0.0.0.0':: - $this->input->set_cookie($name, $value, $expire, $domain, $path, $prefix, $secure); + echo $this->input->ip_address(); + .. important:: This method takes into account the ``$config['proxy_ips']`` + setting and will return the reported HTTP_X_FORWARDED_FOR, + HTTP_CLIENT_IP, HTTP_X_CLIENT_IP or HTTP_X_CLUSTER_CLIENT_IP + address for the allowed IP addresses. -$this->input->ip_address() -========================== + .. method:: valid_ip($ip[, $which = '']) -Returns the IP address for the current user. If the IP address is not -valid, the method will return an IP of: 0.0.0.0 + :param string $ip: IP address + :param string $which: IP protocol ('ipv4' or 'ipv6') + :returns: 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. - echo $this->input->ip_address(); + .. note:: The $this->input->ip_address() method above automatically + validates the IP address. -$this->input->valid_ip($ip) -=========================== + :: -Takes an IP address as input and returns TRUE or FALSE (boolean) if it -is valid or not. + if ( ! $this->input->valid_ip($ip)) + { + echo 'Not Valid'; + } + else + { + echo 'Valid'; + } -.. note:: The $this->input->ip_address() method above automatically - validates the IP address. + Accepts an optional second string parameter of 'ipv4' or 'ipv6' to specify + an IP format. The default checks for both formats. -:: + .. method:: user_agent() - if ( ! $this->input->valid_ip($ip)) - { - echo 'Not Valid'; - } - else - { - echo 'Valid'; - } + :returns: User agent string or NULL if not set + :rtype: mixed -Accepts an optional second string parameter of 'ipv4' or 'ipv6' to specify -an IP format. The default checks for both formats. + Returns the user agent string (web browser) being used by the current user, + or NULL if it's not available. + :: -$this->input->user_agent() -========================== + echo $this->input->user_agent(); -Returns the user agent (web browser) being used by the current user. -Returns FALSE if it's not available. + See the :doc:`User Agent Class <user_agent>` for methods which extract + information from the user agent string. -:: + .. method:: request_headers([$xss_clean = FALSE]) - echo $this->input->user_agent(); + :param bool $xss_clean: Whether to apply XSS filtering + :returns: An array of HTTP request headers + :rtype: array -See the :doc:`User Agent Class <user_agent>` for methods which extract -information from the user agent string. + Returns an array of HTTP request headers. + Useful if running in a non-Apache environment where + `apache_request_headers() <http://php.net/apache_request_headers>`_ + will not be supported. + :: -$this->input->request_headers() -=============================== + $headers = $this->input->request_headers(); -Useful if running in a non-Apache environment where -`apache_request_headers() <http://php.net/apache_request_headers>`_ -will not be supported. Returns an array of headers. + .. method:: get_request_header($index[, $xss_clean = FALSE]) -:: + :param string $index: HTTP request header name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: An HTTP request header or NULL if not found + :rtype: string - $headers = $this->input->request_headers(); + Returns a single member of the request headers array or NULL + if the searched header is not found. + :: -$this->input->get_request_header() -================================== + $this->input->get_request_header('some-header', TRUE); -Returns a single member of the request headers array. + .. method:: is_ajax_request() -:: + :returns: TRUE if it is an Ajax request, FALSE if not + :rtype: bool - $this->input->get_request_header('some-header', TRUE); + Checks to see if the HTTP_X_REQUESTED_WITH server header has been + set, and returns boolean TRUE if it is or FALSE if not. -$this->input->is_ajax_request() -=============================== + .. method:: is_cli_request() -Checks to see if the HTTP_X_REQUESTED_WITH server header has been -set, and returns a boolean response. + :returns: TRUE if it is a CLI request, FALSE if not + :rtype: bool -$this->input->is_cli_request() -============================== + Checks to see if the application was run from the command-line + interface. -Checks to see if the STDIN constant is set, which is a failsafe way to -see if PHP is being run on the command line. + .. note:: This method checks both the PHP SAPI name currently in use + and if the ``STDIN`` constant is defined, which is usually a + failsafe way to see if PHP is being run via the command line. -:: + :: - $this->input->is_cli_request() + $this->input->is_cli_request() -.. note:: This method is DEPRECATED and is now just an alias for the - :php:func:`is_cli()` function. + .. note:: This method is DEPRECATED and is now just an alias for the + :func:`is_cli()` function. -$this->input->method() -====================== + .. method:: method([$upper = FALSE]) -Returns the $_SERVER['REQUEST_METHOD'], optional set uppercase or lowercase (default lowercase). + :param bool $upper: Whether to return the request method name in upper or lower case + :returns: 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
\ No newline at end of file + echo $this->input->method(TRUE); // Outputs: POST + echo $this->input->method(FALSE); // Outputs: post + echo $this->input->method(); // Outputs: post
\ No newline at end of file diff --git a/user_guide_src/source/libraries/javascript.rst b/user_guide_src/source/libraries/javascript.rst index 393d4e321..9d0237e57 100644 --- a/user_guide_src/source/libraries/javascript.rst +++ b/user_guide_src/source/libraries/javascript.rst @@ -1,31 +1,52 @@ -.. note:: This driver is experimental. Its feature set and - implementation may change in future releases. - ################ Javascript Class ################ +.. note:: This library is DEPRECATED and should not be used. It has always + been with an 'experimental' status and is now no longer supported. + Currently only kept for backwards compatibility. + CodeIgniter provides a library to help you with certain common functions that you may want to use with Javascript. Please note that CodeIgniter does not require the jQuery library to run, and that any scripting library will work equally well. The jQuery library is simply presented as a convenience if you choose to use it. +.. 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 function. Currently, the only -available library is jQuery, which will automatically be loaded like -this:: +constructor, use the ``$this->load->library()`` method. Currently, +the only available library is jQuery, which will automatically be +loaded like this:: $this->load->library('javascript'); -The Javascript class also accepts parameters, js_library_driver -(string) default 'jquery' and autoload (bool) default TRUE. You may -override the defaults if you wish by sending an associative array:: +The Javascript class also accepts parameters: + +- js_library_driver (string) *default: 'jquery'* +- autoload (bool) *default: TRUE* - $this->load->library('javascript', array('js_library_driver' => 'scripto', 'autoload' => FALSE)); +You may override the defaults by sending an associative array:: + + $this->load->library( + 'javascript', + array( + 'js_library_driver' => 'scripto', + 'autoload' => FALSE + ) + ); Again, presently only 'jquery' is available. You may wish to set autoload to FALSE, though, if you do not want the jQuery library to @@ -34,7 +55,8 @@ is useful if you are loading it from a location outside of CodeIgniter, or already have the script tag in your markup. Once loaded, the jQuery library object will be available using: -$this->javascript + + $this->javascript Setup and Configuration ======================= @@ -47,8 +69,8 @@ application. As Javascript is a client side language, the library must be able to write content into your final output. This generally means a view. -You'll need to include the following variables in the <head> sections of -your output. +You'll need to include the following variables in the ``<head>`` +sections of your output. :: @@ -56,17 +78,17 @@ your output. <?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. +``$library_src``, is where the actual library file will be loaded, as +well as any subsequent plugin script calls; $script_head is where +specific events, functions and other commands will be rendered. Set the path to the librarys with config items ---------------------------------------------- There are some configuration items in Javascript library. These can -either be set in application/config.php, within its own -config/javascript.php file, or within any controller usings the -set_item() function. +either be set in *application/config.php*, within its own +*config/javascript.php* file, or within any controller usings the +``set_item()`` function. An image to be used as an "ajax loader", or progress indicator. Without one, the simple text message of "loading" will appear when Ajax calls @@ -84,7 +106,7 @@ The jQuery Class ================ To initialize the jQuery class manually in your controller constructor, -use the $this->load->library function:: +use the ``$this->load->library()`` method:: $this->load->library('javascript/jquery'); @@ -96,30 +118,29 @@ library as follows:: $this->load->library('javascript/jquery', FALSE); Once loaded, the jQuery library object will be available using: -$this->jquery + + $this->jquery jQuery Events ============= Events are set using the following syntax. - :: $this->jquery->event('element_path', code_to_run()); - In the above example: - "event" is any of blur, change, click, dblclick, error, focus, hover, keydown, keyup, load, mousedown, mouseup, mouseover, mouseup, resize, scroll, or unload. -- "element_path" is any valid `jQuery - selector <http://docs.jquery.com/Selectors>`_. Due to jQuery's unique +- "element_path" is any valid `jQuery selector + <http://docs.jquery.com/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 + 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 +- "``code_to_run()``" is script your write yourself, or an action such as an effect from the jQuery library below. Effects @@ -298,4 +319,4 @@ description to come calendar() ---------- -description to come +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 index d288cd65e..3014d8f09 100644 --- a/user_guide_src/source/libraries/language.rst +++ b/user_guide_src/source/libraries/language.rst @@ -19,11 +19,22 @@ 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> + +************************ +Using the Language Class +************************ + Creating Language Files ======================= -Language files must be named with **_lang.php** as the file extension. For -example, let's say you want to create a file containing error messages. +Language files must be named with **_lang.php** as the filename extension. +For example, let's say you want to create a file containing error messages. You might name it: error_lang.php Within the file you will assign each line of text to an array called @@ -79,7 +90,7 @@ Using language lines as form labels ----------------------------------- This feature has been deprecated from the language library and moved to -the :php:func:`lang()` function of the :doc:`Language Helper +the :func:`lang()` function of the :doc:`Language Helper <../helpers/language_helper>`. Auto-loading Languages @@ -89,4 +100,32 @@ If you find that you need a particular language globally throughout your application, you can tell CodeIgniter to :doc:`auto-load <../general/autoloader>` it during system initialization. This is done by opening the **application/config/autoload.php** file and adding the -language(s) to the autoload array.
\ No newline at end of file +language(s) to the autoload array. + +*************** +Class Reference +*************** + +.. class:: CI_Lang + + .. method:: load($langfile[, $idiom = ''[, $return = FALSE[, $add_suffix = TRUE[, $alt_path = '']]]]) + + :param string $langfile: Language file to load + :param string $idiom: Language name (i.e. 'english') + :param bool $return: Whether to return the loaded array of translations + :param bool $add_suffix: Whether to add the '_lang' suffix to the language file name + :param string $alt_path: An alternative path to look in for the language file + :returns: Array of language lines if $return is set to TRUE, otherwise void + :rtype: mixed + + Loads a language file. + + .. method:: line($line[, $log_errors = TRUE]) + + :param string $line: Language line key name + :param bool $log_errors: Whether to log an error if the line isn't found + :returns: Language line string or FALSE on failure + :rtype: string + + Fetches a single translation line from the already loaded language files, + based on the line's name.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/loader.rst b/user_guide_src/source/libraries/loader.rst index 91db5afbd..107b3ece3 100644 --- a/user_guide_src/source/libraries/loader.rst +++ b/user_guide_src/source/libraries/loader.rst @@ -11,368 +11,450 @@ can be libraries (classes) :doc:`View files <../general/views>`, .. note:: This class is initialized automatically by the system so there is no need to do it manually. -The following methods are available in this class: +.. contents:: + :local: -$this->load->library('class_name', $config, 'object name') -========================================================== +.. raw:: html -This method is used to load core classes. Where class_name is the -name of the class you want to load. + <div class="custom-index container"></div> -.. note:: We use the terms "class" and "library" interchangeably. +Application "Packages" +====================== -For example, if you would like to send email with CodeIgniter, the first -step is to load the email class within your controller:: +An application package allows for the easy distribution of complete sets +of resources in a single directory, complete with its own libraries, +models, helpers, config, and language files. It is recommended that +these packages be placed in the application/third_party directory. Below +is a sample map of an package directory. - $this->load->library('email'); +The following is an example of a directory for an application package +named "Foo Bar". -Once loaded, the library will be ready for use, using -$this->email->*some_method*(). +:: -Library files can be stored in subdirectories within the main -"libraries" directory, or within your personal application/libraries -directory. To load a file located in a subdirectory, simply include the -path, relative to the "libraries" directory. For example, if you have -file located at:: + /application/third_party/foo_bar - libraries/flavors/Chocolate.php + config/ + helpers/ + language/ + libraries/ + models/ -You will load it using:: +Whatever the purpose of the "Foo Bar" application package, it has its +own config files, helpers, language files, libraries, and models. To use +these resources in your controllers, you first need to tell the Loader +that you are going to be loading resources from a package, by adding the +package path via the ``add_package_path()`` method. - $this->load->library('flavors/chocolate'); +Package view files +------------------ -You may nest the file in as many subdirectories as you want. +By Default, package view files paths are set when ``add_package_path()`` +is called. View paths are looped through, and once a match is +encountered that view is loaded. -Additionally, multiple libraries can be loaded at the same time by -passing an array of libraries to the load method. +In this instance, it is possible for view naming collisions within +packages to occur, and possibly the incorrect package being loaded. To +ensure against this, set an optional second parameter of FALSE when +calling ``add_package_path()``. :: - $this->load->library(array('email', 'table')); + $this->load->add_package_path(APPPATH.'my_app', FALSE); + $this->load->view('my_app_index'); // Loads + $this->load->view('welcome_message'); // Will not load the default welcome_message b/c the second param to add_package_path is FALSE -Setting options ---------------- + // Reset things + $this->load->remove_package_path(APPPATH.'my_app'); -The second (optional) parameter allows you to optionally pass -configuration setting. You will typically pass these as an array:: + // Again without the second parameter: + $this->load->add_package_path(APPPATH.'my_app'); + $this->load->view('my_app_index'); // Loads + $this->load->view('welcome_message'); // Loads - $config = array ( - 'mailtype' => 'html', - 'charset' => 'utf-8, - 'priority' => '1' - ); +*************** +Class Reference +*************** - $this->load->library('email', $config); +.. class:: CI_Loader -Config options can usually also be set via a config file. Each library -is explained in detail in its own page, so please read the information -regarding each one you would like to use. + .. method:: library($library[, $params = NULL[, $object_name = NULL]]) -Please take note, when multiple libraries are supplied in an array for -the first parameter, each will receive the same parameter information. + :param mixed $library: Library name as a string or an array with multiple libraries + :param array $params: Optional array of parameters to pass to the loaded library's constructor + :param string $object_name: Optional object name to assign the library to + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader -Assigning a Library to a different object name ----------------------------------------------- + This method is used to load core classes. -If the third (optional) parameter is blank, the library will usually be -assigned to an object with the same name as the library. For example, if -the library is named Calendar, it will be assigned to a variable named -$this->calendar. + .. note:: We use the terms "class" and "library" interchangeably. -If you prefer to set your own class names you can pass its value to the -third parameter:: + For example, if you would like to send email with CodeIgniter, the first + step is to load the email class within your controller:: - $this->load->library('calendar', '', 'my_calendar'); + $this->load->library('email'); - // Calendar class is now accessed using: - $this->my_calendar + Once loaded, the library will be ready for use, using ``$this->email``. -Please take note, when multiple libraries are supplied in an array for -the first parameter, this parameter is discarded. + Library files can be stored in subdirectories within the main + "libraries" directory, or within your personal *application/libraries* + directory. To load a file located in a subdirectory, simply include the + path, relative to the "libraries" directory. For example, if you have + file located at:: -$this->load->driver('parent_name', $config, 'object name') -========================================================== + libraries/flavors/Chocolate.php -This method is used to load driver libraries. Where parent_name is the -name of the parent class you want to load. + You will load it using:: -As an example, if you would like to use sessions with CodeIgniter, the first -step is to load the session driver within your controller:: + $this->load->library('flavors/chocolate'); - $this->load->driver('session'); + You may nest the file in as many subdirectories as you want. -Once loaded, the library will be ready for use, using -$this->session->*some_method*(). + Additionally, multiple libraries can be loaded at the same time by + passing an array of libraries to the load method. + :: -Driver files must be stored in a subdirectory within the main -"libraries" directory, or within your personal application/libraries -directory. The subdirectory must match the parent class name. Read the -:doc:`Drivers <../general/drivers>` description for details. + $this->load->library(array('email', 'table')); -Additionally, multiple driver libraries can be loaded at the same time by -passing an array of drivers to the load method. + **Setting options** -:: + The second (optional) parameter allows you to optionally pass + configuration setting. You will typically pass these as an array:: - $this->load->driver(array('session', 'cache')); + $config = array ( + 'mailtype' => 'html', + 'charset' => 'utf-8, + 'priority' => '1' + ); -Setting options ---------------- + $this->load->library('email', $config); -The second (optional) parameter allows you to optionally pass -configuration settings. You will typically pass these as an array:: + Config options can usually also be set via a config file. Each library + is explained in detail in its own page, so please read the information + regarding each one you would like to use. - $config = array( - 'sess_driver' => 'cookie', - 'sess_encrypt_cookie' => true, - 'encryption_key' => 'mysecretkey' - ); + Please take note, when multiple libraries are supplied in an array for + the first parameter, each will receive the same parameter information. - $this->load->driver('session', $config); + **Assigning a Library to a different object name** -Config options can usually also be set via a config file. Each library -is explained in detail in its own page, so please read the information -regarding each one you would like to use. + If the third (optional) parameter is blank, the library will usually be + assigned to an object with the same name as the library. For example, if + the library is named Calendar, it will be assigned to a variable named + ``$this->calendar``. -Assigning a Driver to a different object name ---------------------------------------------- + If you prefer to set your own class names you can pass its value to the + third parameter:: -If the third (optional) parameter is blank, the library will be assigned -to an object with the same name as the parent class. For example, if -the library is named Session, it will be assigned to a variable named -``$this->session``. + $this->load->library('calendar', NULL, 'my_calendar'); -If you prefer to set your own class names you can pass its value to the -third parameter:: + // Calendar class is now accessed using: + $this->my_calendar - $this->load->library('session', '', 'my_session'); + Please take note, when multiple libraries are supplied in an array for + the first parameter, this parameter is discarded. - // Session class is now accessed using: - $this->my_session + .. method:: driver($library[, $params = NULL[, $object_name]]) -.. note:: Driver libraries may also be loaded with the ``library()`` method, - but it is faster to use ``driver()``. + :param mixed $library: Library name as a string or an array with multiple libraries + :param array $params: Optional array of parameters to pass to the loaded library's constructor + :param string $object_name: Optional object name to assign the library to + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader -$this->load->view('file_name', $data, TRUE/FALSE) -================================================= + This method is used to load driver libraries, acts very much like the + ``library()`` method. -This method is used to load your View files. If you haven't read the -:doc:`Views <../general/views>` section of the user guide it is -recommended that you do since it shows you how this method is -typically used. + As an example, if you would like to use sessions with CodeIgniter, the first + step is to load the session driver within your controller:: -The first parameter is required. It is the name of the view file you -would like to load. + $this->load->driver('session'); -.. note:: The .php file extension does not need to be specified unless - you use something other than .php. + Once loaded, the library will be ready for use, using ``$this->session``. -The second **optional** parameter can take an associative array or an -object as input, which it runs through the PHP -`extract() <http://www.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. + Driver files must be stored in a subdirectory within the main + "libraries" directory, or within your personal *application/libraries* + directory. The subdirectory must match the parent class name. Read the + :doc:`Drivers <../general/drivers>` description for details. -The third **optional** parameter lets you change the behavior of the -method so that it returns data as a string rather than sending it to -your browser. This can be useful if you want to process the data in some -way. If you set the parameter to true (boolean) it will return data. The -default behavior is false, which sends it to your browser. Remember to -assign it to a variable if you want the data returned:: + Additionally, multiple driver libraries can be loaded at the same time by + passing an array of drivers to the load method. + :: - $string = $this->load->view('myfile', '', true); + $this->load->driver(array('session', 'cache')); -$this->load->model('model_name'); -================================== + **Setting options** -:: + The second (optional) parameter allows you to optionally pass + configuration settings. You will typically pass these as an array:: - $this->load->model('model_name'); + $config = array( + 'sess_driver' => 'cookie', + 'sess_encrypt_cookie' => true, + 'encryption_key' => 'mysecretkey' + ); + $this->load->driver('session', $config); -If your model is located in a subdirectory, include the relative path -from your models directory. For example, if you have a model located at -application/models/blog/Queries.php you'll load it using:: + Config options can usually also be set via a config file. Each library + is explained in detail in its own page, so please read the information + regarding each one you would like to use. - $this->load->model('blog/queries'); + **Assigning a Driver to a different object name** -If you would like your model assigned to a different object name you can -specify it via the second parameter of the loading method:: + If the third (optional) parameter is blank, the library will be assigned + to an object with the same name as the parent class. For example, if + the library is named Session, it will be assigned to a variable named + ``$this->session``. - $this->load->model('model_name', 'fubar'); - $this->fubar->method(); + If you prefer to set your own class names you can pass its value to the + third parameter:: -$this->load->database('options', TRUE/FALSE) -============================================ + $this->load->library('session', '', 'my_session'); -This method lets you load the database class. The two parameters are -**optional**. Please see the :doc:`database <../database/index>` -section for more info. + // Session class is now accessed using: + $this->my_session -$this->load->vars($array) -========================= + .. method:: view($view[, $vars = array()[, return = FALSE]]) -This method takes an associative array as input and generates -variables using the PHP `extract <http://www.php.net/extract>`_ -method. This method produces the same result as using the second -parameter of the ``$this->load->view()`` method above. The reason you -might want to use this method independently is if you would like to -set some global variables in the constructor of your controller and have -them become available in any view file loaded from any method. You can -have multiple calls to this method. The data get cached and merged -into one array for conversion to variables. + :param string $view: View name + :param array $vars: An associative array of variables + :param bool $return: Whether to return the loaded view + :returns: View content string if $return is set to TRUE, otherwise CI_Loader instance (method chaining) + :rtype: mixed -$this->load->get_var($key) -========================== + This method is used to load your View files. If you haven't read the + :doc:`Views <../general/views>` section of the user guide it is + recommended that you do since it shows you how this method is + typically used. -This method checks the associative array of variables available to -your views. This is useful if for any reason a var is set in a library -or another controller method using ``$this->load->vars()``. + The first parameter is required. It is the name of the view file you + would like to load. -$this->load->get_vars() -======================= + .. note:: The .php file extension does not need to be specified unless + you use something other than .php. -This method retrieves all variables available to your views. + The second **optional** parameter can take an associative array or an + object as input, which it runs through the PHP + `extract() <http://www.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. -$this->load->clear_vars() -========================= + 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:: -Clears cached view variables. + $string = $this->load->view('myfile', '', TRUE); -$this->load->helper('file_name') -================================ + .. method:: vars($vars[, $val = '']) -This method loads helper files, where file_name is the name of the -file, without the _helper.php extension. + :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->load->file('filepath/filename', TRUE/FALSE) -================================================== + This method takes an associative array as input and generates + variables using the PHP `extract() <http://www.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. -This is a generic file loading method. Supply the filepath and name in -the first parameter and it will open and read the file. By default the -data is sent to your browser, just like a View file, but if you set the -second parameter to true (boolean) it will instead return the data as a -string. + .. method:: get_var($key) -$this->load->language('file_name') -================================== + :param string $key: Variable name key + :returns: Value if key is found, NULL if not + :rtype: mixed -This method is an alias of the :doc:`language loading -method <language>`: ``$this->lang->load()`` + This method checks the associative array of variables available to + your views. This is useful if for any reason a var is set in a library + or another controller method using ``$this->load->vars()``. -$this->load->config('file_name') -================================ + .. method:: get_vars() -This method is an alias of the :doc:`config file loading -method <config>`: ``$this->config->load()`` + :returns: An array of all assigned view variables + :rtype: array -$this->load->is_loaded('library_name') -====================================== + This method retrieves all variables available to your views. -The ``is_loaded()`` method allows you to check if a class has already -been loaded or not. + .. method:: clear_vars() -.. note:: The word "class" here refers to libraries and drivers. + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader -If the requested class has been loaded, the method returns its assigned -name in the CI Super-object and FALSE if it's not:: + Clears cached view variables. - $this->load->library('form_validation'); - $this->load->is_loaded('Form_validation'); // returns 'form_validation' + .. method:: model($model[, $name = ''[, $db_conn = FALSE]]) - $this->load->is_loaded('Nonexistent_library'); // returns 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 -.. important:: If you have more than one instance of a class (assigned to - different properties), then the first one will be returned. + :: -:: + $this->load->model('model_name'); - $this->load->library('form_validation', $config, 'fv'); - $this->load->library('form_validation'); - $this->load->is_loaded('Form_validation'); // returns 'fv' + 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:: -Application "Packages" -====================== + $this->load->model('blog/queries'); -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 + If you would like your model assigned to a different object name you can + specify it via the second parameter of the loading method:: -Sample Package "Foo Bar" Directory Map -====================================== + $this->load->model('model_name', 'fubar'); + $this->fubar->method(); -The following is an example of a directory for an application package -named "Foo Bar". + .. 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 - /application/third_party/foo_bar + This method lets you load the database class. The two parameters are + **optional**. Please see the :doc:`database <../database/index>` + section for more info. - config/ - helpers/ - language/ - libraries/ - models/ + .. method:: dbforge([$db = NULL[, $return = FALSE]]) -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. + :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 -$this->load->add_package_path() ---------------------------------- + Loads the :doc:`Database Forge <../database/forge>` class, please refer + to that manual for more info. -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:: + .. method:: dbutil([$db = NULL[, $return = FALSE]]) - $this->load->add_package_path(APPPATH.'third_party/foo_bar/'); - $this->load->library('foo_bar'); + :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 -$this->load->remove_package_path() ------------------------------------- + Loads the :doc:`Database Utilities <../database/utilities>` class, please + refer to that manual for more info. -When your controller is finished using resources from an application -package, and particularly if you have other application packages you -want to work with, you may wish to remove the package path so the Loader -no longer looks in that directory for resources. To remove the last path -added, simply call the method with no parameters. + .. method:: helper($helpers) -$this->load->remove_package_path() ------------------------------------- + :param mixed $helpers: Helper name as a string or an array containing multiple helpers + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader -Or to remove a specific package path, specify the same path previously -given to add_package_path() for a package.:: + This method loads helper files, where file_name is the name of the + file, without the _helper.php extension. - $this->load->remove_package_path(APPPATH.'third_party/foo_bar/'); + .. method:: file($path[, $return = FALSE]) -Package view files ------------------- + :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 -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. + 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. -In this instance, it is possible for view naming collisions within -packages to occur, and possibly the incorrect package being loaded. To -ensure against this, set an optional second parameter of FALSE when -calling add_package_path(). + .. method:: 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->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 + This method is an alias of the :doc:`language loading + method <language>`: ``$this->lang->load()``. - // Reset things - $this->load->remove_package_path(APPPATH.'my_app'); + .. method:: config($file[, $use_sections = FALSE[, $fail_gracefully = FALSE]]) - // Again without the second parameter: - $this->load->add_package_path(APPPATH.'my_app'); - $this->load->view('my_app_index'); // Loads - $this->load->view('welcome_message'); // Loads
\ No newline at end of file + :param 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()`` + + .. 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' + + .. 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'); + + .. 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/'); + + .. 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 index 9dc3c08da..e8ea1d977 100644 --- a/user_guide_src/source/libraries/migration.rst +++ b/user_guide_src/source/libraries/migration.rst @@ -10,8 +10,15 @@ need to be run against the production machines next time you deploy. The database table **migration** tracks which migrations have already been run so all you have to do is update your application files and -call **$this->migration->current()** to work out which migrations should be run. -The current version is found in **config/migration.php**. +call ``$this->migration->current()`` to work out which migrations should be run. +The current version is found in **application/config/migration.php**. + +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> ******************** Migration file names @@ -28,23 +35,24 @@ method taken. Two numbering styles are available: helps prevent numbering conflicts when working in a team environment, and is the preferred scheme in CodeIgniter 3.0 and later. -The desired style may be selected using the **$config['migration_type']** -setting in your **migration.php** config file. +The desired style may be selected using the ``$config['migration_type']`` +setting in your *application/config/migration.php* file. Regardless of which numbering style you choose to use, prefix your migration files with the migration number followed by an underscore and a descriptive name for the migration. For example: -* **001_add_blog.php** (sequential numbering) -* **20121031100537_add_blog.php** (timestamp numbering) +* 001_add_blog.php (sequential numbering) +* 20121031100537_add_blog.php (timestamp numbering) ****************** Create a Migration ****************** This will be the first migration for a new site which has a blog. All -migrations go in the folder **application/migrations/** and have names such -as **20121031100537_add_blog.php**.:: +migrations go in the **application/migrations/** directory and have names such +as *20121031100537_add_blog.php*. +:: <?php @@ -80,7 +88,7 @@ as **20121031100537_add_blog.php**.:: } } -Then in **application/config/migration.php** set **$config['migration_version'] = 1;**. +Then in **application/config/migration.php** set ``$config['migration_version'] = 1;``. ************* Usage Example @@ -93,54 +101,18 @@ to update the schema.:: class Migrate extends CI_Controller { - public function index() - { - $this->load->library('migration'); - - if ($this->migration->current() === FALSE) - { - show_error($this->migration->error_string()); - } - } - } - -****************** -Function Reference -****************** - -$this->migration->current() -============================ - -The current migration is whatever is set for **$config['migration_version']** in -**application/config/migration.php**. - -$this->migration->error_string() -================================= -This returns a string of errors while performing a migration. - -$this->migration->find_migrations() -==================================== - -An array of migration filenames are returned that are found in the **migration_path** -property. - -$this->migration->latest() -=========================== - -This works much the same way as current() but instead of looking for -the **$config['migration_version']** the Migration class will use the very -newest migration found in the filesystem. - -$this->migration->version() -============================ - -Version can be used to roll back changes or step forwards programmatically to -specific versions. It works just like current but ignores **$config['migration_version']**.:: + public function index() + { + $this->load->library('migration'); - $this->load->library('migration'); + if ($this->migration->current() === FALSE) + { + show_error($this->migration->error_string()); + } + } - $this->migration->version(5); + } ********************* Migration Preferences @@ -161,3 +133,52 @@ Preference Default Options Des **migration_type** 'timestamp' 'timestamp' / 'sequential' The type of numeric identifier used to name migration files. ========================== ====================== ========================== ============================================= + +*************** +Class Reference +*************** + +.. class:: CI_Migration + + .. method:: current() + + :returns: 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*). + + .. method:: error_string() + + :returns: Error messages + :rtype: string + + This returns a string of errors that were detected while performing a migration. + + .. 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. + + .. method:: latest() + + :returns: TRUE if no migrations are found, current version string on success, FALSE on failure + :rtype: mixed + + This works much the same way as ``current()`` but instead of looking for + the ``$config['migration_version']`` the Migration class will use the very + newest migration found in the filesystem. + + .. 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);
\ No newline at end of file diff --git a/user_guide_src/source/libraries/output.rst b/user_guide_src/source/libraries/output.rst index a3d67b847..e49ea5366 100644 --- a/user_guide_src/source/libraries/output.rst +++ b/user_guide_src/source/libraries/output.rst @@ -2,7 +2,7 @@ Output Class ############ -The Output class is a small class with one main function: To send the +The Output class is a core class with one main function: To send the finalized web page to the requesting browser. It is also responsible for :doc:`caching <../general/caching>` your web pages, if you use that feature. @@ -16,159 +16,193 @@ use the :doc:`Loader <../libraries/loader>` class to load a view file, it's automatically passed to the Output class, which will be called automatically by CodeIgniter at the end of system execution. It is possible, however, for you to manually intervene with the output if you -need to, using either of the two following functions: +need to. -$this->output->set_output(); -============================= +.. contents:: + :local: -Permits you to manually set the final output string. Usage example:: +.. raw:: html - $this->output->set_output($data); + <div class="custom-index container"></div> -.. important:: If you do set your output manually, it must be the last - thing done in the function you call it from. For example, if you build a - page in one of your controller functions, don't set the output until the - end. +*************** +Class Reference +*************** -$this->output->set_content_type(); -==================================== +.. class:: CI_Output -Permits you to set the mime-type of your page so you can serve JSON -data, JPEG's, XML, etc easily. + .. attribute:: $parse_exec_vars = TRUE; -:: + Enables/disables parsing of the {elapsed_time} and {memory_usage} pseudo-variables. - $this->output - ->set_content_type('application/json') - ->set_output(json_encode(array('foo' => 'bar'))); + CodeIgniter will parse those tokens in your output by default. To disable this, set + this property to FALSE in your controller. + :: - $this->output - ->set_content_type('jpeg') // You could also use ".jpeg" which will have the full stop removed before looking in config/mimes.php - ->set_output(file_get_contents('files/something.jpg')); + $this->output->parse_exec_vars = FALSE; -.. important:: Make sure any non-mime string you pass to this method - exists in config/mimes.php or it will have no effect. + .. method:: set_output($output) -You can also set the character set of the document, by passing a second argument:: + :param string $output: String to set the output to + :returns: CI_Output instance (method chaining) + :rtype: CI_Output - $this->output->set_content_type('css', 'utf-8'); + Permits you to manually set the final output string. Usage example:: -$this->output->get_content_type() -================================= + $this->output->set_output($data); -Returns the Content-Type HTTP header that's currently in use, -excluding the character set value. + .. 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. - $mime = $this->output->get_content_type(); + .. method:: set_content_type($mime_type[, $charset = NULL]) -.. note:: If not set, the default return value is 'text/html'. + :param string $mime_type: MIME Type idenitifer string + :param string $charset: Character set + :returns: CI_Output instance (method chaining) + :rtype: CI_Output -$this->output->get_header() -=========================== + Permits you to set the mime-type of your page so you can serve JSON data, JPEG's, XML, etc easily. + :: -Gets the requested HTTP header value, if set. + $this->output + ->set_content_type('application/json') + ->set_output(json_encode(array('foo' => 'bar'))); -If the header is not set, NULL will be returned. -If an empty value is passed to the method, it will return FALSE. + $this->output + ->set_content_type('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')); -Example:: + .. important:: Make sure any non-mime string you pass to this method + exists in *application/config/mimes.php* or it will have no effect. - $this->output->set_content_type('text/plain', 'UTF-8'); - echo $this->output->get_header('content-type'); - // Outputs: text/plain; charset=utf-8 + You can also set the character set of the document, by passing a second argument:: -.. note:: The header name is compared in a case-insensitive manner. + $this->output->set_content_type('css', 'utf-8'); -.. note:: Raw headers sent via PHP's native ``header()`` function are - also detected. + .. method:: get_content_type() -$this->output->get_output() -=========================== + :returns: Content-Type string + :rtype: string -Permits you to manually retrieve any output that has been sent for -storage in the output class. Usage example:: + Returns the Content-Type HTTP header that's currently in use, excluding the character set value. + :: - $string = $this->output->get_output(); + $mime = $this->output->get_content_type(); -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(). + .. note:: If not set, the default return value is 'text/html'. -$this->output->append_output(); -================================ + .. method:: get_header($header) -Appends data onto the output string. Usage example:: + :param string $header: HTTP header name + :returns: HTTP response header or NULL if not found + :rtype: mixed - $this->output->append_output($data); + Returns the requested HTTP header value, or NULL if the requested header is not set. + Example:: -$this->output->set_header(); -============================= + $this->output->set_content_type('text/plain', 'UTF-8'); + echo $this->output->get_header('content-type'); + // Outputs: text/plain; charset=utf-8 -Permits you to manually set server headers, which the output class will -send for you when outputting the final rendered display. Example:: + .. note:: The header name is compared in a case-insensitive manner. - $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"); + .. note:: Raw headers sent via PHP's native ``header()`` function are also detected. -$this->output->set_status_header(code, 'text'); -================================================= + .. method:: get_output() -Permits you to manually set a server status header. Example:: + :returns: Output string + :rtype: string - $this->output->set_status_header('401'); - // Sets the header as: Unauthorized + Permits you to manually retrieve any output that has been sent for + storage in the output class. Usage example:: -`See here <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>`_ for -a full list of headers. + $string = $this->output->get_output(); -.. note:: This method is an alias for :doc:`Common function <../general/common_functions>` - ``set_status_header()``. + Note that data will only be retrievable from this function if it has + been previously sent to the output class by one of the CodeIgniter + functions like ``$this->load->view()``. -$this->output->enable_profiler(); -================================== + .. method:: append_output($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. + :param string $output: Additional output data to append + :returns: CI_Output instance (method chaining) + :rtype: CI_Output -To enable the profiler place the following function anywhere within your -:doc:`Controller <../general/controllers>` functions:: + Appends data onto the output string. + :: - $this->output->enable_profiler(TRUE); + $this->output->append_output($data); -When enabled a report will be generated and inserted at the bottom of -your pages. + .. method:: set_header($header[, $replace = TRUE]) -To disable the profiler you will use:: + :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 - $this->output->enable_profiler(FALSE); + 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_profiler_sections(); -========================================= + $this->output->set_header('HTTP/1.0 200 OK'); + $this->output->set_header('HTTP/1.1 200 OK'); + $this->output->set_header('Last-Modified: '.gmdate('D, d M Y H:i:s', $last_update).' GMT'); + $this->output->set_header('Cache-Control: no-store, no-cache, must-revalidate'); + $this->output->set_header('Cache-Control: post-check=0, pre-check=0'); + $this->output->set_header('Pragma: no-cache'); -Permits you to enable/disable specific sections of the Profiler when -enabled. Please refer to the :doc:`Profiler <../general/profiling>` -documentation for further information. + .. method:: set_status_header([$code = 200[, $text = '']]) -$this->output->cache(); -======================= + :param int $code: HTTP status code + :param string $text: Optional message + :returns: CI_Output instance (method chaining) + :rtype: CI_Output -The CodeIgniter output library also controls caching. For more -information, please see the :doc:`caching -documentation <../general/caching>`. + Permits you to manually set a server status header. Example:: -Parsing Execution Variables -=========================== + $this->output->set_status_header('401'); + // Sets the header as: Unauthorized -CodeIgniter will parse the pseudo-variables {elapsed_time} and -{memory_usage} in your output by default. To disable this, set the -$parse_exec_vars class property to FALSE in your controller. -:: + `See here <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>`_ for a full list of headers. - $this->output->parse_exec_vars = FALSE; + .. note:: This method is an alias for :doc:`Common function <../general/common_functions>` + :func:`set_status_header()`. + .. 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); + + .. 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. + + .. method:: cache($time) + + :param int $time: Cache expiration time in seconds + :returns: CI_Output instance (method chaining) + :rtype: CI_Output + + Caches the current page for the specified amount of seconds. + + For more information, please see the :doc:`caching documentation <../general/caching>`.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst index d9d3f5092..ee12d9e6f 100644 --- a/user_guide_src/source/libraries/pagination.rst +++ b/user_guide_src/source/libraries/pagination.rst @@ -5,6 +5,13 @@ Pagination Class CodeIgniter's Pagination class is very easy to use, and it is 100% customizable, either dynamically or via stored preferences. +.. contents:: + :local: + +.. raw:: html + + <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:: @@ -15,7 +22,7 @@ Example ******* Here is a simple example showing how to create pagination in one of your -:doc:`controller <../general/controllers>` functions:: +:doc:`controller <../general/controllers>` methods:: $this->load->library('pagination'); @@ -30,8 +37,8 @@ Here is a simple example showing how to create pagination in one of your Notes ===== -The $config array contains your configuration variables. It is passed to -the $this->pagination->initialize function as shown above. Although +The ``$config`` array contains your configuration variables. It is passed to +the ``$this->pagination->initialize()`` method as shown above. Although there are some twenty items you can configure, at minimum you need the three shown. Here is a description of what those items represent: @@ -46,7 +53,7 @@ three shown. Here is a description of what those items represent: - **per_page** The number of items you intend to show per page. In the above example, you would be showing 20 items per page. -The create_links() function returns an empty string when there is no +The ``create_links()`` method returns an empty string when there is no pagination to show. Setting preferences in a config file @@ -54,9 +61,9 @@ Setting preferences in a config file If you prefer not to set preferences using the above method, you can instead put them into a config file. Simply create a new file called -pagination.php, add the $config array in that file. Then save the file -in: config/pagination.php and it will be used automatically. You will -NOT need to use the $this->pagination->initialize function if you save +pagination.php, add the ``$config`` array in that file. Then save the file +in *application/config/pagination.php* and it will be used automatically. +You will NOT need to use ``$this->pagination->initialize()`` if you save your preferences in a config file. ************************** @@ -67,14 +74,14 @@ The following is a list of all the preferences you can pass to the initialization function to tailor the display. $config['uri_segment'] = 3; -============================ +=========================== The pagination function automatically determines which segment of your URI contains the page number. If you need something different you can specify it. $config['num_links'] = 2; -========================== +========================= The number of "digit" links you would like before and after the selected page number. For example, the number 2 will place two digits on either @@ -92,25 +99,19 @@ $config['page_query_string'] = TRUE; By default, the pagination library assume you are using :doc:`URI Segments <../general/urls>`, and constructs your links something -like - -:: +like:: http://example.com/index.php/test/page/20 - -If you have $config['enable_query_strings'] set to TRUE your links +If you have ``$config['enable_query_strings']`` set to TRUE your links will automatically be re-written using Query Strings. This option can -also be explictly set. Using $config['page_query_string'] set to TRUE, -the pagination link will become. - -:: +also be explictly set. Using ``$config['page_query_string']`` set to TRUE, +the pagination link will become:: http://example.com/index.php?c=test&m=page&per_page=20 - Note that "per_page" is the default query string passed, however can be -configured using $config['query_string_segment'] = 'your_string' +configured using ``$config['query_string_segment'] = 'your_string'`` $config['reuse_query_string'] = FALSE; ====================================== @@ -118,9 +119,7 @@ $config['reuse_query_string'] = FALSE; By default your Query String arguments (nothing to do with other query string options) will be ignored. Setting this config to TRUE will add existing query string arguments back into the -URL after the URI segment and before the suffix - -:: +URL after the URI segment and before the suffix.:: http://example.com/index.php/test/page/20?query=search%term @@ -128,13 +127,13 @@ This helps you mix together normal :doc:`URI Segments <../general/urls>` as well as query string arguments, which until 3.0 was not possible. $config['prefix'] = ''; -================================== +======================= A custom prefix added to the path. The prefix value will be right before the offset segment. $config['suffix'] = ''; -================================== +======================= A custom suffix added to the path. The sufix value will be right after the offset segment. @@ -144,15 +143,15 @@ Adding Enclosing Markup *********************** If you would like to surround the entire pagination with some markup you -can do it with these two prefs: +can do it with these two preferences: $config['full_tag_open'] = '<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. @@ -161,18 +160,18 @@ Customizing the First Link ************************** $config['first_link'] = 'First'; -================================= +================================ The text you would like shown in the "first" link on the left. If you do not want this link rendered, you can set its value to FALSE. $config['first_tag_open'] = '<div>'; -====================================== +==================================== The opening tag for the "first" link. $config['first_tag_close'] = '</div>'; -======================================== +====================================== The closing tag for the "first" link. @@ -181,18 +180,18 @@ Customizing the Last Link ************************* $config['last_link'] = 'Last'; -=============================== +============================== The text you would like shown in the "last" link on the right. If you do not want this link rendered, you can set its value to FALSE. $config['last_tag_open'] = '<div>'; -===================================== +=================================== The opening tag for the "last" link. $config['last_tag_close'] = '</div>'; -======================================= +===================================== The closing tag for the "last" link. @@ -201,18 +200,18 @@ Customizing the "Next" Link *************************** $config['next_link'] = '>'; -=============================== +============================== The text you would like shown in the "next" page link. If you do not want this link rendered, you can set its value to FALSE. $config['next_tag_open'] = '<div>'; -===================================== +=================================== The opening tag for the "next" link. $config['next_tag_close'] = '</div>'; -======================================= +===================================== The closing tag for the "next" link. @@ -221,18 +220,18 @@ Customizing the "Previous" Link ******************************* $config['prev_link'] = '<'; -=============================== +============================== The text you would like shown in the "previous" page link. If you do not want this link rendered, you can set its value to FALSE. $config['prev_tag_open'] = '<div>'; -===================================== +=================================== The opening tag for the "previous" link. $config['prev_tag_close'] = '</div>'; -======================================= +===================================== The closing tag for the "previous" link. @@ -241,12 +240,12 @@ 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. @@ -255,12 +254,12 @@ 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. @@ -280,9 +279,7 @@ Adding attributes to anchors If you want to add an extra attribute to be added to every link rendered by the pagination class, you can set them as key/value pairs in the -"attributes" config - -:: +"attributes" config:: // Produces: class="myclass" $config['attributes'] = array('class' => 'myclass'); @@ -300,4 +297,25 @@ you can pass boolean FALSE as a regular attribute :: - $config['attributes']['rel'] = FALSE;
\ No newline at end of file + $config['attributes']['rel'] = FALSE; + +*************** +Class Reference +*************** + +.. class:: CI_Pagination + + .. method:: initialize([$params = array()]) + + :param array $params: Configuration parameters + :returns: CI_Pagination instance (method chaining) + :rtype: CI_Pagination + + Initializes the Pagination class with your preferred options. + + .. 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.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/parser.rst b/user_guide_src/source/libraries/parser.rst index 0b77ae4b9..5af504a03 100644 --- a/user_guide_src/source/libraries/parser.rst +++ b/user_guide_src/source/libraries/parser.rst @@ -35,6 +35,13 @@ representations that allow you to eliminate PHP from your templates template parsing solution. We've kept it very lean on purpose in order to maintain maximum performance. +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + Initializing the Class ====================== @@ -46,15 +53,10 @@ in your controller using the $this->load->library function:: Once loaded, the Parser library object will be available using: $this->parser -The following functions are available in this library: - -$this->parser->parse() -====================== - -This method accepts a template name and data array as input, and it -generates a parsed version. Example:: +Parsing templates +================= - $this->load->library('parser'); +You can use the ``parse()`` method to parse (or render) simple templates, like this:: $data = array( 'blog_title' => 'My Blog Title', @@ -77,12 +79,6 @@ third parameter:: $string = $this->parser->parse('blog_template', $data, TRUE); -$this->parser->parse_string() -============================== - -This method works exactly like parse(), only accepts a string as the -first parameter in place of a view file. - Variable Pairs ============== @@ -147,3 +143,37 @@ function:: $this->parser->parse('blog_template', $data); +*************** +Class Reference +*************** + +.. class:: CI_Parser + + .. method:: parse($template, $data[, $return = FALSE]) + + :param string $template: Path to view file + :param array $data: Variable data + :param bool $return: Whether to only return the parsed template + :returns: Parsed template string + :rtype: string + + Parses a template from the provided path and variables. + + .. method:: parse_string($template, $data[, $return = FALSE]) + + :param string $template: Path to view file + :param array $data: Variable data + :param bool $return: Whether to only return the parsed template + :returns: Parsed template string + :rtype: string + + This method works exactly like ``parse()``, only it accepts the template as a + string instead of loading a view file. + + .. method:: set_delimiters([$l = '{'[, $r = '}']]) + + :param string $l: Left delimiter + :param string $r: Right delimiter + :rtype: void + + Sets the delimiters (opening and closing) for a value "tag" in a template.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/security.rst b/user_guide_src/source/libraries/security.rst index be1f8d205..fb875a0d9 100644 --- a/user_guide_src/source/libraries/security.rst +++ b/user_guide_src/source/libraries/security.rst @@ -5,6 +5,13 @@ Security Class The Security Class contains methods that help you create a secure application, processing input data for security. +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + XSS Filtering ============= @@ -23,12 +30,7 @@ Note: This function should only be used to deal with data upon submission. It's not something that should be used for general runtime processing since it requires a fair amount of processing overhead. -To filter data through the XSS filter use this function: - -$this->security->xss_clean() -============================ - -Here is an usage example:: +To filter data through the XSS filter use the ``xss_clean()`` method:: $data = $this->security->xss_clean($data); @@ -38,10 +40,10 @@ application/config/config.php file and setting this:: $config['global_xss_filtering'] = TRUE; -Note: If you use the form validation class, it gives you the option of -XSS filtering as well. +.. note:: If you use the form validation class, it gives you the option of + XSS filtering as well. -An optional second parameter, is_image, allows this function to be used +An optional second parameter, *is_image*, allows this function to be used to test images for potential XSS attacks, useful for file upload security. When this second parameter is set to TRUE, instead of returning an altered string, the function returns TRUE if the image is @@ -52,40 +54,21 @@ browser may attempt to execute. if ($this->security->xss_clean($file, TRUE) === FALSE) { - // file failed the XSS test + // file failed the XSS test } -$this->security->sanitize_filename() -==================================== - -When accepting filenames from user input, it is best to sanitize them to -prevent directory traversal and other security related issues. To do so, -use the sanitize_filename() method of the Security class. Here is an -example:: - - $filename = $this->security->sanitize_filename($this->input->post('filename')); - -If it is acceptable for the user input to include relative paths, e.g. -file/in/some/approved/folder.txt, you can set the second optional -parameter, $relative_path to TRUE. - -:: - - $filename = $this->security->sanitize_filename($this->input->post('filename'), TRUE); - Cross-site request forgery (CSRF) ================================= -You can enable CSRF protection by opening your -application/config/config.php file and setting this:: +You can enable CSRF protection by altering your **application/config/config.php** +file in the following way:: $config['csrf_protection'] = TRUE; If you use the :doc:`form helper <../helpers/form_helper>`, then -``form_open()`` will automatically insert a hidden csrf field in +: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( @@ -114,15 +97,63 @@ by editing the 'csrf_exclude_uris' config parameter:: $config['csrf_exclude_uris'] = array('api/person/add'); -$this->security->get_csrf_token_name() -====================================== +*************** +Class Reference +*************** + +.. class:: CI_Security + + .. method:: xss_clean($str[, $is_image = FALSE]) + + :param mixed $str: Input string or an array of strings + :returns: XSS-clean data + :rtype: mixed + + Tries to remove XSS exploits from the input data and returns the cleaned string. + If the optional second parameter is set to true, it will return boolean TRUE if the image is safe to use and FALSE if malicious data was detected in it. + + .. method:: sanitize_filename($str[, $relative_path = FALSE]) + + :param string $str: File name/path + :param bool $relative_path: Whether to preserve any directories in the file path + :returns: 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); + + .. method:: get_csrf_token_name() + + :returns: CSRF token name + :rtype: string + + Returns the CSRF token name (the ``$config['csrf_token_name']`` value). + + .. 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. + + .. method:: entity_decode($str[, $charset = NULL]) -Returns the CSRF token name, which is set by -``$config['csrf_token_name']``. + :param string $str: Input string + :param string $charset: Character set of the input string + :returns: Entity-decoded string + :rtype: string -$this->security->get_csrf_hash() -================================ + This method acts a lot like PHP's own native ``html_entity_decode()`` function in ENT_COMPAT mode, only + it tries to detect HTML entities that don't end in a semicolon because some browsers allow that. -Returns the CSRF hash value. Useful in combination with -``get_csrf_token_name()`` for manually building forms or -sending valid AJAX POST requests.
\ No newline at end of file + If the ``$charset`` parameter is left empty, then your configured ``$config['charset']`` value will be used.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index 3368a9f5d..f05f86af1 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -9,6 +9,17 @@ which supports usage of the native PHP Session mechanism. In addition, you may create your own `Custom Drivers`_ to store session data however you wish, while still taking advantage of the features of the Session class. +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + +*********************** +Using the Session Class +*********************** + Initializing a Session ====================== @@ -21,12 +32,13 @@ initializing the class will cause it to read, create, and update sessions. To initialize the Session class manually in your controller constructor, -use the $this->load->driver function:: +use the ``$this->load->driver`` function:: $this->load->driver('session'); -Once loaded, the Sessions library object will be available using: -$this->session +Once loaded, the Sessions library object will be available using:: + + $this->session How do Sessions work? ===================== @@ -62,10 +74,10 @@ prototype:: [array] ( - 'session_id' => random hash, - 'ip_address' => 'string - user IP address', - 'user_agent' => 'string - user agent data', - 'last_activity' => timestamp + 'session_id' => random hash, + 'ip_address' => 'string - user IP address', + 'user_agent' => 'string - user agent data', + 'last_activity' => timestamp ) .. note:: Sessions are only updated every five minutes by default to @@ -91,6 +103,23 @@ fetch. For example, to fetch the session ID you will do this:: .. note:: The function returns NULL if the item you are trying to access does not exist. +If you want to retrieve all of the existing userdata, you can simply +omit the item key parameter:: + + $this->session->userdata(); + + /** + * Produces something similar to: + * + * Array + * ( + * [session_id] => 4a5a5dca22728fb0a84364eeb405b601 + * [ip_address] => 127.0.0.1 + * [user_agent] => Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_7; + * [last_activity] => 1303142623 + * ) + */ + Adding Custom Session Data ========================== @@ -112,43 +141,26 @@ Where $array is an associative array containing your new data. Here's an example:: $newdata = array( - 'username' => 'johndoe', - 'email' => 'johndoe@some-site.com', - 'logged_in' => TRUE - ); + 'username' => 'johndoe', + 'email' => 'johndoe@some-site.com', + 'logged_in' => TRUE + ); $this->session->set_userdata($newdata); -If you want to add userdata one value at a time, set_userdata() also +If you want to add userdata one value at a time, ``set_userdata()`` also supports this syntax. :: $this->session->set_userdata('some_name', 'some_value'); -If you want to verify that a userdata value exists, call has_userdata(). +If you want to verify that a userdata value exists, call ``has_userdata()``. :: $this->session->has_userdata('some_name'); -Retrieving All Session Data -=========================== - -An array of all userdata can be retrieved as follows:: - - $this->session->userdata() - -And returns an associative array like the following:: - - Array - ( - [session_id] => 4a5a5dca22728fb0a84364eeb405b601 - [ip_address] => 127.0.0.1 - [user_agent] => Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_7; - [last_activity] => 1303142623 - ) - Removing Session Data ===================== @@ -185,8 +197,8 @@ To add flashdata:: $this->session->set_flashdata('item', 'value'); -You can also pass an array to set_flashdata(), in the same manner as -set_userdata(). +You can also pass an array to ``set_flashdata()``, in the same manner as +``set_userdata()``. To read a flashdata variable:: @@ -198,7 +210,7 @@ An array of all flashdata can be retrieved as follows:: If you find that you need to preserve a flashdata variable through an -additional request, you can do so using the keep_flashdata() function. +additional request, you can do so using the ``keep_flashdata()`` function. You can either pass a single item or an array of flashdata items to keep. :: @@ -206,6 +218,8 @@ You can either pass a single item or an array of flashdata items to keep. $this->session->keep_flashdata('item'); $this->session->keep_flashdata(array('item1', 'item2', 'item3')); +.. note:: The function will return NULL if the item cannot be found. + Tempdata ======== @@ -219,7 +233,7 @@ To add tempdata:: $this->session->set_tempdata('item', 'value', $expire); -You can also pass an array to set_tempdata():: +You can also pass an array to ``set_tempdata()``:: $tempdata = array('newuser' => TRUE, 'message' => 'Thanks for joining!'); @@ -232,8 +246,12 @@ To read a tempdata variable:: $this->session->tempdata('item'); +And of course, if you want to retrieve all existing tempdata:: + + $this->session->tempdata(); + If you need to remove a tempdata value before it expires, -use unset_tempdata():: +use ``unset_tempdata()``:: $this->session->unset_tempdata('item'); @@ -246,7 +264,7 @@ To clear the current session:: .. note:: This function should be the last one called, and even flash variables will no longer be available. If you only want some items - destroyed and not all, use unset_userdata(). + destroyed and not all, use ``unset_userdata()``. Session Preferences =================== @@ -304,7 +322,7 @@ installed, and `Custom Drivers`_ may also be installed by the user. Typically, only one driver will be used at a time, but CodeIgniter does support loading multiple drivers. If a specific valid driver is called, it will be automatically loaded. Or, an additional driver may be explicitly -loaded by calling load_driver():: +loaded by ``calling load_driver()``:: $this->session->load_driver('native'); @@ -329,7 +347,7 @@ the call to unset the *native* 'foo' value. The drivers maintain independent sets of values, regardless of key names. A specific driver may also be explicitly selected for use by pursuant -methods with the select_driver() call:: +methods with the ``select_driver()`` call:: $this->session->select_driver('native'); @@ -391,11 +409,24 @@ session class:: KEY `last_activity_idx` (`last_activity`) ); +Or if you're using PostgreSQL:: + + CREATE TABLE ci_sessions ( + session_id varchar(40) DEFAULT '0' NOT NULL, + ip_address varchar(45) DEFAULT '0' NOT NULL, + user_agent varchar(120) NOT NULL, + last_activity bigint DEFAULT 0 NOT NULL, + user_data text NOT NULL, + PRIMARY KEY (session_id) + ); + + CREATE INDEX last_activity_idx ON ci_sessions(last_activity); + .. note:: By default the table is called ci_sessions, but you can name it anything you want as long as you update the - application/config/config.php file so that it contains the name you have - chosen. Once you have created your database table you can enable the - database option in your config.php file as follows:: + *application/config/config.php* file so that it contains the name + you have chosen. Once you have created your database table you + can enable the database option in your config.php file as follows:: $config['sess_use_database'] = TRUE; @@ -423,7 +454,7 @@ You may also :doc:`create your own <../general/creating_drivers>` custom session drivers. A session driver basically manages an array of name/value pairs with some sort of storage mechanism. -To make a new driver, extend CI_Session_driver. Overload the initialize() +To make a new driver, extend CI_Session_driver. Overload the ``initialize()`` method and read or create session data. Then implement a save handler to write changed data to storage (sess_save), a destroy handler to remove deleted data (sess_destroy), a regenerate handler to make a new session ID @@ -431,6 +462,7 @@ deleted data (sess_destroy), a regenerate handler to make a new session ID Your initial class might look like:: class CI_Session_custom extends CI_Session_driver { + protected function initialize() { // Read existing session data or create a new one @@ -455,15 +487,16 @@ Your initial class might look like:: { // Return a reference to your userdata array } + } -Notice that get_userdata() returns a reference so the parent library is +Notice that ``get_userdata()`` returns a reference so the parent library is accessing the same array the driver object is using. This saves memory and avoids synchronization issues during usage. Put your driver in the libraries/Session/drivers folder anywhere in your package paths. This includes the application directory, the system directory, -or any path you add with $CI->load->add_package_path(). Your driver must be +or any path you add with ``$CI->load->add_package_path()``. Your driver must be named CI_Session_<name>, and your filename must be Session_<name>.php, preferably also capitalized, such as:: @@ -484,3 +517,186 @@ without making it the initially loaded driver, set 'sess_valid_drivers' in your config.php file to an array including your driver name:: $config['sess_valid_drivers'] = array('sess_driver'); + +*************** +Class Reference +*************** + +.. class:: CI_Session + + .. method:: load_driver($driver) + + :param string $driver: Driver name + :returns: Instance of currently loaded session driver + :rtype: mixed + + Loads a session storage driver + + .. method:: select_driver($driver) + + :param string $driver: Driver name + :rtype: void + + Selects default session storage driver. + + .. method:: sess_destroy() + + :rtype: void + + Destroys current session + + .. note:: This method should be the last one called, and even flash + variables will no longer be available after it is used. + If you only want some items destroyed and not all, use + ``unset_userdata()``. + + .. method:: sess_regenerate([$destroy = FALSE]) + + :param bool $destroy: Whether to destroy session data + :rtype: void + + Regenerate the current session data. + + .. method:: userdata([$item = NULL]) + + :param string $item: Session item name + :returns: Item value if found, NULL if not or an array of all userdata if $item parameter is not used + :rtype: mixed + + If no parameter is passed, it will return an associative array of all existing userdata. + + Otherwise returns a string containing the value of the passed item or NULL if the item is not found. + Example:: + + $this->session->userdata('user'); + //returns example@example.com considering the set_userdata example. + + .. method:: all_userdata() + + :returns: An array of all userdata + :rtype: array + + Returns an array with all of the session userdata items. + + .. note:: This method is DEPRECATED. Use ``userdata()`` with no parameters instead. + + .. method:: &get_userdata() + + :returns: A reference to the userdata array + :rtype: &array + + Returns a reference to the userdata array. + + .. method:: set_userdata($newdata[, $newval = '']) + + :param mixed $newdata: Item name or array of items + :param mixed $newval: Item value or empty string (not required if $newdata is array) + :rtype: void + + Sets items into session example usages:: + + $this->session->set_userdata('user', 'example@example.com'); + // adds item user with value example@example.com to the session + + $this->session->set_userdata(array('user'=>'example@example.com')); + // does the same as the above example - adds item user with value example@example.com to the session + + .. method:: unset_userdata($item) + + :param mixed $item: Item name or an array containing multiple items + :rtype: void + + Unsets previously set items from the session. Example:: + + $this->session->unset_userdata('user'); + //unsets 'user' from session data. + + $this->session->unset_userdata(array('user', 'useremail')); + //unsets both 'user' and 'useremail' from the session data. + + .. method:: has_userdata($item) + + :param string $item: Item name + :returns: TRUE if item exists, FALSE if not + :rtype: bool + + Checks if an item exists in the session. + + .. method:: flashdata([$item = NULL]) + + :param string $item: Flashdata item name + :returns: Item value if found, NULL if not or an array of all flashdata if $item parameter is not used + :rtype: mixed + + If no parameter is passed, it will return an associative array of all existing flashdata. + + Otherwise returns a string containing the value of the passed item or NULL if the item is not found. + Example:: + + $this->session->flashdata('message'); + //returns 'Test message.' considering the set_flashdata example. + + .. method:: set_flashdata($newdata[, $newval = '']) + + :param mixed $newdata: Item name or an array of items + :param mixed $newval: Item value or empty string (not required if $newdata is array) + :rtype: void + + Sets items into session flashdata example usages:: + + $this->session->set_flashdata('message', 'Test message.'); + // adds item 'message' with value 'Test message.' to the session flashdata + + $this->session->set_flashdata(array('message'=>'Test message.')); + // does the same as the above example - adds item 'message' with value 'Test message.' + to the session flashdata + + .. method:: keep_flashdata($item) + + :param mixed $item: Item name or an array containing multiple flashdata items + :rtype: void + + Keeps items into flashdata for one more request. + + .. method:: tempdata([$item = NULL]) + + :param string $item: Tempdata item name + :returns: Item value if found, NULL if not or an array of all tempdata if $item parameter is not used + :rtype: mixed + + If no parameter is passed, it will return an associative array of all existing tempdata. + + Otherwise returns a string containing the value of the passed item or NULL if the item is not found. + Example:: + + $this->session->tempdata('message'); + //returns 'Test message.' considering the set_tempdata example. + + .. method:: set_tempdata($newdata[, $newval = ''[, $expire = 0]]) + + :param mixed $newdata: Item name or array containing multiple items + :param string $newval: Item value or empty string (not required if $newdata is array) + :param int $expire: Lifetime in seconds (0 for default) + :rtype: void + + Sets items into session tempdata example:: + + $this->session->set_tempdata('message', 'Test message.', '60'); + // adds item 'message' with value 'Test message.' to the session tempdata for 60 seconds + + $this->session->set_tempdata(array('message'=>'Test message.')); + // does the same as the above example - adds item 'message' with value 'Test message.' + to the session tempdata for the default value of + + .. method:: unset_tempdata($item) + + :param mixed $item: Item name or an array containing multiple items + :rtype: void + + Unsets previously set items from tempdata. Example:: + + $this->session->unset_tempdata('user'); + //unsets 'user' from tempdata. + + $this->session->unset_tempdata(array('user', 'useremail')); + //unsets both 'user' and 'useremail' from the tempdata.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/table.rst b/user_guide_src/source/libraries/table.rst index 6a808abc2..6e011083e 100644 --- a/user_guide_src/source/libraries/table.rst +++ b/user_guide_src/source/libraries/table.rst @@ -5,48 +5,60 @@ HTML Table Class The Table Class provides functions that enable you to auto-generate HTML tables from arrays or database result sets. +.. 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 function:: +in your controller using the ``$this->load->library()`` method:: $this->load->library('table'); -Once loaded, the Table library object will be available using: -$this->table +Once loaded, the Table library object will be available using:: + + $this->table Examples ======== Here is an example showing how you can create a table from a multi-dimensional array. Note that the first array index will become the -table heading (or you can set your own headings using the set_heading() -function described in the function reference below). +table heading (or you can set your own headings using the ``set_heading()`` +method described in the function reference below). :: $this->load->library('table'); $data = array( - array('Name', 'Color', 'Size'), - array('Fred', 'Blue', 'Small'), - array('Mary', 'Red', 'Large'), - array('John', 'Green', 'Medium') - ); + array('Name', 'Color', 'Size'), + array('Fred', 'Blue', 'Small'), + array('Mary', 'Red', 'Large'), + array('John', 'Green', 'Medium') + ); echo $this->table->generate($data); Here is an example of a table created from a database query result. The table class will automatically generate the headings based on the table -names (or you can set your own headings using the set_heading() -function described in the function reference below). +names (or you can set your own headings using the ``set_heading()`` +method described in the class reference below). :: $this->load->library('table'); - $query = $this->db->query("SELECT * FROM my_table"); + $query = $this->db->query('SELECT * FROM my_table'); echo $this->table->generate($query); @@ -82,28 +94,28 @@ Changing the Look of Your Table The Table Class permits you to set a table template with which you can specify the design of your layout. Here is the template prototype:: - $tmpl = array ( - 'table_open' => '<table border="0" cellpadding="4" cellspacing="0">', + $template = array( + 'table_open' => '<table border="0" cellpadding="4" cellspacing="0">', - 'heading_row_start' => '<tr>', - 'heading_row_end' => '</tr>', - 'heading_cell_start' => '<th>', - 'heading_cell_end' => '</th>', + 'heading_row_start' => '<tr>', + 'heading_row_end' => '</tr>', + 'heading_cell_start' => '<th>', + 'heading_cell_end' => '</th>', - 'row_start' => '<tr>', - 'row_end' => '</tr>', - 'cell_start' => '<td>', - 'cell_end' => '</td>', + '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>', + 'row_alt_start' => '<tr>', + 'row_alt_end' => '</tr>', + 'cell_alt_start' => '<td>', + 'cell_alt_end' => '</td>', - 'table_close' => '</table>' - ); + 'table_close' => '</table>' + ); - $this->table->set_template($tmpl); + $this->table->set_template($template); .. note:: You'll notice there are two sets of "row" blocks in the template. These permit you to create alternating row colors or design @@ -113,157 +125,167 @@ You are NOT required to submit a complete template. If you only need to change parts of the layout you can simply submit those elements. In this example, only the table opening tag is being changed:: - $tmpl = array ( 'table_open' => '<table border="1" cellpadding="2" cellspacing="1" class="mytable">' ); + $template = array( + 'table_open' => '<table border="1" cellpadding="2" cellspacing="1" class="mytable">' + ); - $this->table->set_template($tmpl); + $this->table->set_template($template); You can also set defaults for these in a config file. -****************** -Function Reference -****************** +*************** +Class Reference +*************** -$this->table->generate() -======================== +.. class:: CI_Table -Returns a string containing the generated table. Accepts an optional -parameter which can be an array or a database result object. + .. attribute:: $function = FALSE -$this->table->set_caption() -============================ + Allows you to specify a native PHP function or a valid function array object to be applied to all cell data. + :: -Permits you to add a caption to the table. + $this->load->library('table'); -:: + $this->table->set_heading('Name', 'Color', 'Size'); + $this->table->add_row('Fred', '<strong>Blue</strong>', 'Small'); - $this->table->set_caption('Colors'); + $this->table->function = 'htmlspecialchars'; + echo $this->table->generate(); -$this->table->set_heading() -============================ + In the above example, all cell data would be ran through PHP's :php:func:`htmlspecialchars()` function, resulting in:: -Permits you to set the table heading. You can submit an array or -discrete params:: + <td>Fred</td><td><strong>Blue</strong></td><td>Small</td> - $this->table->set_heading('Name', 'Color', 'Size'); + .. method:: generate([$table_data = NULL]) -:: + :param mixed $table_data: Data to populate the table rows with + :returns: HTML table + :rtype: string - $this->table->set_heading(array('Name', 'Color', 'Size')); + Returns a string containing the generated table. Accepts an optional parameter which can be an array or a database result object. -$this->table->add_row() -======================== + .. method:: set_caption($caption) -Permits you to add a row to your table. You can submit an array or -discrete params:: + :param string $caption: Table caption + :returns: CI_Table instance (method chaining) + :rtype: CI_Table - $this->table->add_row('Blue', 'Red', 'Green'); + Permits you to add a caption to the table. + :: -:: + $this->table->set_caption('Colors'); - $this->table->add_row(array('Blue', 'Red', 'Green')); + .. method:: set_heading([$args = array()[, ...]]) -If you would like to set an individual cell's tag attributes, you can -use an associative array for that cell. The associative key 'data' -defines the cell's data. Any other key => val pairs are added as -key='val' attributes to the tag:: + :param mixed $args: An array or multiple strings containing the table column titles + :returns: CI_Table instance (method chaining) + :rtype: CI_Table - $cell = array('data' => 'Blue', 'class' => 'highlight', 'colspan' => 2); - $this->table->add_row($cell, 'Red', 'Green'); + Permits you to set the table heading. You can submit an array or discrete params:: - // generates - // <td class='highlight' colspan='2'>Blue</td><td>Red</td><td>Green</td> + $this->table->set_heading('Name', 'Color', 'Size'); -$this->table->make_columns() -============================= + $this->table->set_heading(array('Name', 'Color', 'Size')); -This function takes a one-dimensional array as input and creates a -multi-dimensional array with a depth equal to the number of columns -desired. This allows a single array with many elements to be displayed -in a table that has a fixed column count. Consider this example:: + .. method:: add_row([$args = array()[, ...]]) - $list = array('one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve'); + :param mixed $args: An array or multiple strings containing the row values + :returns: CI_Table instance (method chaining) + :rtype: CI_Table - $new_list = $this->table->make_columns($list, 3); + Permits you to add a row to your table. You can submit an array or discrete params:: - $this->table->generate($new_list); + $this->table->add_row('Blue', 'Red', 'Green'); - // Generates a table with this prototype + $this->table->add_row(array('Blue', 'Red', 'Green')); - <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> + If you would like to set an individual cell's tag attributes, you can use an associative array for that cell. + The associative key **data** defines the cell's data. Any other key => val pairs are added as key='val' attributes to the tag:: -$this->table->set_template() -============================= + $cell = array('data' => 'Blue', 'class' => 'highlight', 'colspan' => 2); + $this->table->add_row($cell, 'Red', 'Green'); -Permits you to set your template. You can submit a full or partial -template. + // generates + // <td class='highlight' colspan='2'>Blue</td><td>Red</td><td>Green</td> -:: + .. method:: make_columns([$array = array()[, $col_limit = 0]]) - $tmpl = array ( 'table_open' => '<table border="1" cellpadding="2" cellspacing="1" class="mytable">' ); + :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->table->set_template($tmpl); + This method takes a one-dimensional array as input and creates a multi-dimensional array with a depth equal to the number of columns desired. + This allows a single array with many elements to be displayed in a table that has a fixed column count. Consider this example:: -$this->table->set_empty() -========================== + $list = array('one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve'); -Let's you set a default value for use in any table cells that are empty. -You might, for example, set a non-breaking space:: + $new_list = $this->table->make_columns($list, 3); - $this->table->set_empty(" "); + $this->table->generate($new_list); -$this->table->clear() -===================== + // Generates a table with this prototype -Lets you clear the table heading and row data. If you need to show -multiple tables with different data you should to call this function -after each table has been generated to empty the previous table -information. Example:: + <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> - $this->load->library('table'); - $this->table->set_heading('Name', 'Color', 'Size'); - $this->table->add_row('Fred', 'Blue', 'Small'); - $this->table->add_row('Mary', 'Red', 'Large'); - $this->table->add_row('John', 'Green', 'Medium'); + .. method:: set_template($template) - echo $this->table->generate(); + :param array $template: An associative array containing template values + :returns: TRUE on success, FALSE on failure + :rtype: bool - $this->table->clear(); + Permits you to set your template. You can submit a full or partial template. + :: - $this->table->set_heading('Name', 'Day', 'Delivery'); - $this->table->add_row('Fred', 'Wednesday', 'Express'); - $this->table->add_row('Mary', 'Monday', 'Air'); - $this->table->add_row('John', 'Saturday', 'Overnight'); + $template = array( + 'table_open' => '<table border="1" cellpadding="2" cellspacing="1" class="mytable">' + ); + + $this->table->set_template($template); - echo $this->table->generate(); + .. method:: set_empty($value) -$this->table->function -====================== + :param mixed $value: Value to put in empty cells + :returns: CI_Table instance (method chaining) + :rtype: CI_Table -Allows you to specify a native PHP function or a valid function array -object to be applied to all cell data. + 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(" "); - $this->load->library('table'); + .. method:: clear() - $this->table->set_heading('Name', 'Color', 'Size'); - $this->table->add_row('Fred', '<strong>Blue</strong>', 'Small'); + :returns: CI_Table instance (method chaining) + :rtype: CI_Table - $this->table->function = 'htmlspecialchars'; - echo $this->table->generate(); + Lets you clear the table heading and row data. If you need to show multiple tables with different data you should to call this method + after each table has been generated to clear the previous table information. Example:: + + $this->load->library('table'); + + $this->table->set_heading('Name', 'Color', 'Size'); + $this->table->add_row('Fred', 'Blue', 'Small'); + $this->table->add_row('Mary', 'Red', 'Large'); + $this->table->add_row('John', 'Green', 'Medium'); + + echo $this->table->generate(); -In the above example, all cell data would be ran through PHP's -htmlspecialchars() function, resulting in:: + $this->table->clear(); - <td>Fred</td><td><strong>Blue</strong></td><td>Small</td> + $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();
\ No newline at end of file diff --git a/user_guide_src/source/libraries/trackback.rst b/user_guide_src/source/libraries/trackback.rst index f9e0df882..22859a13d 100644 --- a/user_guide_src/source/libraries/trackback.rst +++ b/user_guide_src/source/libraries/trackback.rst @@ -8,16 +8,28 @@ receive Trackback data. If you are not familiar with Trackbacks you'll find more information `here <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 function:: +initialized in your controller using the ``$this->load->library()`` method:: $this->load->library('trackback'); -Once loaded, the Trackback library object will be available using: -$this->trackback +Once loaded, the Trackback library object will be available using:: + + $this->trackback Sending Trackbacks ================== @@ -28,38 +40,37 @@ similar to this example:: $this->load->library('trackback'); $tb_data = array( - 'ping_url' => 'http://example.com/trackback/456', - 'url' => 'http://www.my-example.com/blog/entry/123', - 'title' => 'The Title of My Entry', - 'excerpt' => 'The entry content.', - 'blog_name' => 'My Blog Name', - 'charset' => 'utf-8' - ); + 'ping_url' => 'http://example.com/trackback/456', + 'url' => 'http://www.my-example.com/blog/entry/123', + 'title' => 'The Title of My Entry', + 'excerpt' => 'The entry content.', + 'blog_name' => 'My Blog Name', + 'charset' => 'utf-8' + ); if ( ! $this->trackback->send($tb_data)) { - echo $this->trackback->display_errors(); + echo $this->trackback->display_errors(); } else { - echo 'Trackback was sent!'; + echo 'Trackback was sent!'; } Description of array data: - **ping_url** - The URL of the site you are sending the Trackback to. - You can send Trackbacks to multiple URLs by separating each URL with - a comma. + You can send Trackbacks to multiple URLs by separating each URL with a comma. - **url** - The URL to YOUR site where the weblog entry can be seen. - **title** - The title of your weblog entry. -- **excerpt** - The content of your weblog entry. Note: the Trackback - class will automatically send only the first 500 characters of your - entry. It will also strip all HTML. +- **excerpt** - The content of your weblog entry. - **blog_name** - The name of your weblog. -- **charset** - The character encoding your weblog is written in. If - omitted, UTF-8 will be used. +- **charset** - The character encoding your weblog is written in. If omitted, UTF-8 will be used. -The Trackback sending function returns TRUE/FALSE (boolean) on success +.. 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(); @@ -107,16 +118,16 @@ Before you can receive Trackbacks you must create a table in which to store them. Here is a basic prototype for such a table:: CREATE TABLE trackbacks ( - tb_id int(10) unsigned NOT NULL auto_increment, - entry_id int(10) unsigned NOT NULL default 0, - url varchar(200) NOT NULL, - title varchar(100) NOT NULL, - excerpt text NOT NULL, - blog_name varchar(100) NOT NULL, - tb_date int(10) NOT NULL, - ip_address varchar(45) NOT NULL, - PRIMARY KEY `tb_id` (`tb_id`), - KEY `entry_id` (`entry_id`) + tb_id int(10) unsigned NOT NULL auto_increment, + entry_id int(10) unsigned NOT NULL default 0, + url varchar(200) NOT NULL, + title varchar(100) NOT NULL, + excerpt text NOT NULL, + blog_name varchar(100) NOT NULL, + tb_date int(10) NOT NULL, + ip_address varchar(45) NOT NULL, + PRIMARY KEY `tb_id` (`tb_id`), + KEY `entry_id` (`entry_id`) ); The Trackback specification only requires four pieces of information to @@ -129,33 +140,31 @@ Processing a Trackback Here is an example showing how you will receive and process a Trackback. The following code is intended for use within the controller function -where you expect to receive Trackbacks. - -:: +where you expect to receive Trackbacks.:: $this->load->library('trackback'); $this->load->database(); if ($this->uri->segment(3) == FALSE) { - $this->trackback->send_error("Unable to determine the entry ID"); + $this->trackback->send_error('Unable to determine the entry ID'); } if ( ! $this->trackback->receive()) { - $this->trackback->send_error("The Trackback did not contain valid data"); + $this->trackback->send_error('The Trackback did not contain valid data'); } $data = array( - 'tb_id' => '', - 'entry_id' => $this->uri->segment(3), - 'url' => $this->trackback->data('url'), - 'title' => $this->trackback->data('title'), - 'excerpt' => $this->trackback->data('excerpt'), - 'blog_name' => $this->trackback->data('blog_name'), - 'tb_date' => time(), - 'ip_address' => $this->input->ip_address() - ); + 'tb_id' => '', + 'entry_id' => $this->uri->segment(3), + 'url' => $this->trackback->data('url'), + 'title' => $this->trackback->data('title'), + 'excerpt' => $this->trackback->data('excerpt'), + 'blog_name' => $this->trackback->data('blog_name'), + 'tb_date' => time(), + 'ip_address' => $this->input->ip_address() + ); $sql = $this->db->insert_string('trackbacks', $data); $this->db->query($sql); @@ -199,3 +208,132 @@ message using:: .. note:: The above code contains no data validation, which you are encouraged to add. + +*************** +Class Reference +*************** + +.. class:: CI_Trackback + + .. attribute:: $data = array('url' => '', 'title' => '', 'excerpt' => '', 'blog_name' => '', 'charset' => '') + + Trackback data array. + + .. attribute:: $convert_ascii = TRUE + + Whether to convert high ASCII and MS Word characters to HTML entities. + + .. method:: send($tb_data) + + :param array $tb_data: Trackback data + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Send trackback. + + .. 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. + + .. 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. + + .. method:: send_success() + + :rtype: void + + Responses to a trackback request with a success message. + + .. note:: This method will terminate script execution. + + .. method:: data($item) + + :param string $item: Data key + :returns: Data value or empty string if not found + :rtype: string + + Returns a single item from the reponse data array. + + .. method:: process($url, $data) + + :param string $url: Target url + :param string $data: Raw POST data + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Opens a socket connection and passes the data to the server, returning TRUE on success and FALSE on failure. + + .. method:: extract_urls($urls) + + :param string $urls: Comma-separated URL list + :returns: Array of URLs + :rtype: array + + This method lets multiple trackbacks to be sent. It takes a string of URLs (separated by comma or space) and puts each URL into an array. + + .. method:: validate_url(&$url) + + :param string $url: Trackback URL + :rtype: void + + Simply adds the *http://* prefix it it's not already present in the URL. + + .. method:: get_id($url) + + :param string $url: Trackback URL + :returns: URL ID or FALSE on failure + :rtype: string + + Find and return a trackback URL's ID or FALSE on failure. + + .. method:: convert_xml($str) + + :param string $str: Input string + :returns: Converted string + :rtype: string + + Converts reserved XML characters to entities. + + .. method:: limit_characters($str[, $n = 500[, $end_char = '…']]) + + :param string $str: Input string + :param int $n: Max characters number + :param string $end_char: Character to put at end of string + :returns: Shortened string + :rtype: string + + Limits the string based on the character count. Will preserve complete words. + + .. method:: convert_ascii($str) + + :param string $str: Input string + :returns: Converted string + :rtype: string + + Converts high ASCII text and MS Word special characterss to HTML entities. + + .. method:: set_error($msg) + + :param string $msg: Error message + :rtype: void + + Set an log an error message. + + .. 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 index db3f227be..65fea9d8e 100644 --- a/user_guide_src/source/libraries/typography.rst +++ b/user_guide_src/source/libraries/typography.rst @@ -2,104 +2,106 @@ Typography Class ################ -The Typography Class provides functions that help you format text. +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 function:: +initialized in your controller using the ``$this->load->library()`` method:: $this->load->library('typography'); -Once loaded, the Typography library object will be available using: -$this->typography +Once loaded, the Typography library object will be available using:: -auto_typography() -================== + $this->typography -Formats text so that it is semantically and typographically correct -HTML. Takes a string as input and returns it with the following -formatting: +*************** +Class Reference +*************** -- Surrounds paragraphs within <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. +.. class:: CI_Typography -Usage example:: + .. attribute:: $protect_braced_quotes = FALSE - $string = $this->typography->auto_typography($string); + When using the Typography library in conjunction with the :doc:`Template Parser library <parser>` + it can often be desirable to protect single and double quotes within curly braces. + To enable this, set the ``protect_braced_quotes`` class property to TRUE. -Parameters ----------- + Usage example:: -There is one optional parameters that determines whether the parser -should reduce more then two consecutive line breaks down to two. Use -boolean TRUE or FALSE. + $this->load->library('typography'); + $this->typography->protect_braced_quotes = TRUE; -By default the parser does not reduce line breaks. In other words, if no -parameters are submitted, it is the same as doing this:: + .. method auto_typography($str[, $reduce_linebreaks = FALSE]) - $string = $this->typography->auto_typography($string, FALSE); + :param string $str: Input string + :param bool $reduce_linebreaks: Whether to reduce consequitive linebreaks + :returns: HTML typography-safe string + :rtype: string -.. note:: Typographic formatting can be processor intensive, - particularly if you have a lot of content being formatted. If you choose - to use this function you may want to consider :doc:`caching <../general/caching>` - your pages. + Formats text so that it is semantically and typographically correct HTML. + Takes a string as input and returns it with the following formatting: -format_characters() -==================== + - Surrounds paragraphs within <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. -This function is similar to the auto_typography function above, except -that it only does character conversion: + Usage example:: -- Quotes are converted to correctly facing curly quote entities, except - those that appear within tags. -- Apostrophes are converted to curly apostrophe entities. -- Double dashes (either like -- this or like--this) are converted to - em—dashes. -- Three consecutive periods either preceding or following a word are - converted to ellipsis… -- Double spaces following sentences are converted to non-breaking - spaces to mimic double spacing. + $string = $this->typography->auto_typography($string); -Usage example:: + There is one optional parameter that determines whether the parser should reduce more than two consecutive line breaks down to two. + Pass boolean TRUE to enable reducing line breaks:: - $string = $this->typography->format_characters($string); + $string = $this->typography->auto_typography($string, TRUE); -nl2br_except_pre() -==================== + .. note:: Typographic formatting can be processor intensive, particularly if you have a lot of content being formatted. + If you choose to use this method you may want to consider :doc:`caching <../general/caching>` your pages. -Converts newlines to <br /> tags unless they appear within <pre> tags. -This function is identical to the native PHP nl2br() function, except -that it ignores <pre> tags. + .. method:: format_characters($str) -Usage example:: + :param string $str: Input string + :returns: Formatted string + :rtype: string - $string = $this->typography->nl2br_except_pre($string); + This method is similar to ``auto_typography()`` above, except that it only does character conversion: -protect_braced_quotes -======================= + - Quotes are converted to correctly facing curly quote entities, except those that appear within tags. + - Apostrophes are converted to curly apostrophe entities. + - Double dashes (either like -- this or like--this) are converted to em—dashes. + - Three consecutive periods either preceding or following a word are converted to ellipsis (…). + - Double spaces following sentences are converted to non-breaking spaces to mimic double spacing. -When using the Typography library in conjunction with the Template -Parser library it can often be desirable to protect single and double -quotes within curly braces. To enable this, set the -protect_braced_quotes class property to TRUE. + Usage example:: -Usage example:: + $string = $this->typography->format_characters($string); - $this->load->library('typography'); - $this->typography->protect_braced_quotes = TRUE; + .. method:: nl2br_except_pre($str) + + :param string $str: Input string + :returns: 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);
\ No newline at end of file diff --git a/user_guide_src/source/libraries/unit_testing.rst b/user_guide_src/source/libraries/unit_testing.rst index 6bd91bf88..0bc860f61 100644 --- a/user_guide_src/source/libraries/unit_testing.rst +++ b/user_guide_src/source/libraries/unit_testing.rst @@ -11,6 +11,13 @@ evaluation function and two result functions. It's not intended to be a full-blown test suite but rather a simple mechanism to evaluate your code to determine if it is producing the correct data type and result. +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + Initializing the Class ====================== @@ -19,16 +26,15 @@ initialized in your controller using the $this->load->library function:: $this->load->library('unit_test'); -Once loaded, the Unit Test object will be available using: $this->unit +Once loaded, the Unit Test object will be available using ``$this->unit`` Running Tests ============= -Running a test involves supplying a test and an expected result to the -following function: +Running a test involves supplying a test and an expected result in the +following way: -$this->unit->run( test, expected result, 'test name', 'notes'); -=============================================================== + $this->unit->run('test', 'expected result', 'test name', 'notes'); Where test is the result of the code you wish to test, expected result is the data type you expect, test name is an optional name you can give @@ -114,7 +120,7 @@ Enabling/Disabling Unit Testing If you would like to leave some testing in place in your scripts, but not have it run unless you need it, you can disable unit testing using:: - $this->unit->active(FALSE) + $this->unit->active(FALSE); Unit Test Display ================= @@ -150,15 +156,85 @@ template. Note the required pseudo-variables:: $str = ' <table border="0" cellpadding="4" cellspacing="1"> - {rows} - <tr> - <td>{item}</td> - <td>{result}</td> - </tr> - {/rows} + {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 +*************** + +.. class:: CI_Unit_test + + .. method:: set_test_items($items) + + :param array $items: List of visible test items + :returns: void + + Sets a list of items that should be visible in tests. + Valid options are: + + - test_name + - test_datatype + - res_datatype + - result + - file + - line + - notes + + .. method:: run($test[, $expected = TRUE[, $test_name = 'undefined'[, $notes = '']]]) + + :param mixed $test: Test data + :param mixed $expected: Expected result + :param string $test_name: Test name + :param string $notes: Any notes to be attached to the test + :returns: Test report + :rtype: string + + Runs unit tests. + + .. method:: report([$result = array()]) + + :param array $result: Array containing tests results + :returns: Test report + :rtype: string + + Generates a report about already complete tests. + + .. method:: use_strict([$state = TRUE]) + + :param bool $state: Strict state flag + :rtype: void + + Enables/disables strict type comparison in tests. + + .. method:: active([$state = TRUE]) + + :param bool $state: Whether to enable testing + :rtype: void + + Enables/disables unit testing. + + .. method:: result([$results = array()]) + + :param array $results: Tests results list + :returns: Array of raw result data + :rtype: array + + Returns raw tests results data. + + .. 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 index bb959b002..7db758ce7 100644 --- a/user_guide_src/source/libraries/uri.rst +++ b/user_guide_src/source/libraries/uri.rst @@ -2,187 +2,232 @@ URI Class ######### -The URI Class provides functions that help you retrieve information from +The URI Class provides methods that help you retrieve information from your URI strings. If you use URI routing, you can also retrieve information about the re-routed segments. .. note:: This class is initialized automatically by the system so there is no need to do it manually. -$this->uri->segment(n) -====================== +.. contents:: + :local: -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:: +.. raw:: html - http://example.com/index.php/news/local/metro/crime_is_up + <div class="custom-index container"></div> -The segment numbers would be this: +*************** +Class Reference +*************** -#. news -#. local -#. metro -#. crime_is_up +.. class:: CI_URI -By default the function returns NULL if the segment does not -exist. There is an optional second parameter that permits you to set -your own default value if the segment is missing. For example, this -would tell the function to return the number zero in the event of -failure:: + .. method:: segment($n[, $no_result = NULL]) - $product_id = $this->uri->segment(3, 0); + :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 -It helps avoid having to write code like this:: + 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:: - if ($this->uri->segment(3) === FALSE) - { - $product_id = 0; - } - else - { - $product_id = $this->uri->segment(3); - } + http://example.com/index.php/news/local/metro/crime_is_up -$this->uri->rsegment(n) -======================= + The segment numbers would be this: -This function is identical to the previous one, except that it lets you -retrieve a specific segment from your re-routed URI in the event you are -using CodeIgniter's :doc:`URI Routing <../general/routing>` feature. + #. news + #. local + #. metro + #. crime_is_up -$this->uri->slash_segment(n) -============================= + The optional second parameter defaults to NULL and allows you to set the return value + of this method when the requested URI segment is missing. + For example, this would tell the method to return the number zero in the event of failure:: -This function is almost identical to $this->uri->segment(), except it -adds a trailing and/or leading slash based on the second parameter. If -the parameter is not used, a trailing slash added. Examples:: + $product_id = $this->uri->segment(3, 0); - $this->uri->slash_segment(3); - $this->uri->slash_segment(3, 'leading'); - $this->uri->slash_segment(3, 'both'); + It helps avoid having to write code like this:: -Returns: + if ($this->uri->segment(3) === FALSE) + { + $product_id = 0; + } + else + { + $product_id = $this->uri->segment(3); + } -#. segment/ -#. /segment -#. /segment/ + .. method:: rsegment($n[, $no_result = NULL]) -$this->uri->slash_rsegment(n) -============================== + :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 function is identical to the previous one, except that it lets you -add slashes a specific segment from your re-routed URI in the event you -are using CodeIgniter's :doc:`URI Routing <../general/routing>` -feature. + This method is 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. -$this->uri->uri_to_assoc(n) -============================= + .. method:: slash_segment($n[, $where = 'trailing']) -This function lets you turn URI segments into and associative array of -key/value pairs. Consider this URI:: + :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 - index.php/user/search/name/joe/location/UK/gender/male + 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:: -Using this function you can turn the URI into an associative array with -this prototype:: + $this->uri->slash_segment(3); + $this->uri->slash_segment(3, 'leading'); + $this->uri->slash_segment(3, 'both'); - [array] - ( - 'name' => 'joe' - 'location' => 'UK' - 'gender' => 'male' - ) + Returns: -The first parameter of the function lets you set an offset. By default -it is set to 3 since your URI will normally contain a -controller/function in the first and second segments. Example:: + #. segment/ + #. /segment + #. /segment/ - $array = $this->uri->uri_to_assoc(3); + .. method:: slash_rsegment($n[, $where = 'trailing']) - echo $array['name']; + :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 -The second parameter lets you set default key names, so that the array -returned by the function will always contain expected indexes, even if -missing from the URI. Example:: + This method 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. - $default = array('name', 'gender', 'location', 'type', 'sort'); + .. method:: uri_to_assoc([$n = 3[, $default = array()]]) - $array = $this->uri->uri_to_assoc(3, $default); + :param int $n: Segment index number + :param array $default: Default values + :returns: Associative URI segments array + :rtype: array -If the URI does not contain a value in your default, an array index will -be set to that name, with a value of FALSE. + This method lets you turn URI segments into and associative array of + key/value pairs. Consider this URI:: -Lastly, if a corresponding value is not found for a given key (if there -is an odd number of URI segments) the value will be set to FALSE -(boolean). + index.php/user/search/name/joe/location/UK/gender/male -$this->uri->ruri_to_assoc(n) -============================== + Using this method you can turn the URI into an associative array with + this prototype:: -This function is identical to the previous one, except that it creates -an associative array using the re-routed URI in the event you are using -CodeIgniter's :doc:`URI Routing <../general/routing>` feature. + [array] + ( + 'name' => 'joe' + 'location' => 'UK' + 'gender' => 'male' + ) -$this->uri->assoc_to_uri() -============================ + 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:: -Takes an associative array as input and generates a URI string from it. -The array keys will be included in the string. Example:: + $array = $this->uri->uri_to_assoc(3); + echo $array['name']; - $array = array('product' => 'shoes', 'size' => 'large', 'color' => 'red'); + 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:: - $str = $this->uri->assoc_to_uri($array); + $default = array('name', 'gender', 'location', 'type', 'sort'); + $array = $this->uri->uri_to_assoc(3, $default); - // Produces: product/shoes/size/large/color/red + 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. -$this->uri->uri_string() -========================= + 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. -Returns a string with the complete URI. For example, if this is your -full URL:: + .. method:: ruri_to_assoc([$n = 3[, $default = array()]]) - http://example.com/index.php/news/local/345 + :param int $n: Segment index number + :param array $default: Default values + :returns: Associative routed URI segments array + :rtype: array -The function would return this:: + 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. - news/local/345 + .. method:: assoc_to_uri($array) -$this->uri->ruri_string() -========================== + :param array $array: Input array of key/value pairs + :returns: URI string + :rtype: string -This function is identical to the previous one, except that it returns -the re-routed URI in the event you are using CodeIgniter's :doc:`URI -Routing <../general/routing>` feature. + Takes an associative array as input and generates a URI string from it. + The array keys will be included in the string. Example:: -$this->uri->total_segments() -============================= + $array = array('product' => 'shoes', 'size' => 'large', 'color' => 'red'); + $str = $this->uri->assoc_to_uri($array); -Returns the total number of segments. + // Produces: product/shoes/size/large/color/red -$this->uri->total_rsegments() -============================== + .. method:: uri_string() -This function is identical to the previous one, except that it returns -the total number of segments in your re-routed URI in the event you are -using CodeIgniter's :doc:`URI Routing <../general/routing>` feature. + :returns: URI string + :rtype: string -$this->uri->segment_array() -============================ + Returns a string with the complete URI. For example, if this is your full URL:: -Returns an array containing the URI segments. For example:: + http://example.com/index.php/news/local/345 - $segs = $this->uri->segment_array(); + The method would return this:: - foreach ($segs as $segment) - { - echo $segment; - echo '<br />'; - } + news/local/345 -$this->uri->rsegment_array() -============================= + .. method:: ruri_string() -This function is identical to the previous one, except that it returns -the array of segments in your re-routed URI in the event you are using -CodeIgniter's :doc:`URI Routing <../general/routing>` feature. + :returns: 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. + + .. method:: total_segments() + + :returns: Count of URI segments + :rtype: int + + Returns the total number of segments. + + .. 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. + + .. 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 />'; + } + + .. 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.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/user_agent.rst b/user_guide_src/source/libraries/user_agent.rst index 97abd2244..517382a65 100644 --- a/user_guide_src/source/libraries/user_agent.rst +++ b/user_guide_src/source/libraries/user_agent.rst @@ -7,6 +7,17 @@ about the browser, mobile device, or robot visiting your site. In addition you can get referrer information as well as language and supported character-set information. +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + +************************** +Using the User Agent Class +************************** + Initializing the Class ====================== @@ -15,7 +26,7 @@ initialized in your controller using the $this->load->library function:: $this->load->library('user_agent'); -Once loaded, the object will be available using: $this->agent +Once loaded, the object will be available using: ``$this->agent`` User Agent Definitions ====================== @@ -38,163 +49,200 @@ is available. if ($this->agent->is_browser()) { - $agent = $this->agent->browser().' '.$this->agent->version(); + $agent = $this->agent->browser().' '.$this->agent->version(); } elseif ($this->agent->is_robot()) { - $agent = $this->agent->robot(); + $agent = $this->agent->robot(); } elseif ($this->agent->is_mobile()) { - $agent = $this->agent->mobile(); + $agent = $this->agent->mobile(); } else { - $agent = 'Unidentified User Agent'; + $agent = 'Unidentified User Agent'; } echo $agent; echo $this->agent->platform(); // Platform info (Windows, Linux, Mac, etc.) -****************** -Function Reference -****************** +*************** +Class Reference +*************** -$this->agent->is_browser() -=========================== +.. class:: CI_User_agent -Returns TRUE/FALSE (boolean) if the user agent is a known web browser. + .. method:: is_browser([$key = NULL]) -:: + :param string $key: Optional browser name + :returns: TRUE if the user agent is a (specified) browser, FALSE if not + :rtype: bool - if ($this->agent->is_browser('Safari')) - { - echo 'You are using Safari.'; - } - elseif ($this->agent->is_browser()) - { - echo 'You are using a browser.'; - } - + Returns TRUE/FALSE (boolean) if the user agent is a known web browser. + :: -.. note:: The string "Safari" in this example is an array key in the - list of browser definitions. You can find this list in - application/config/user_agents.php if you want to add new browsers or - change the stings. + if ($this->agent->is_browser('Safari')) + { + echo 'You are using Safari.'; + } + elseif ($this->agent->is_browser()) + { + echo 'You are using a browser.'; + } -$this->agent->is_mobile() -========================== + .. note:: The string "Safari" in this example is an array key in the list of browser definitions. + You can find this list in **application/config/user_agents.php** if you want to add new + browsers or change the stings. -Returns TRUE/FALSE (boolean) if the user agent is a known mobile device. + .. method:: is_mobile([$key = NULL]) -:: + :param string $key: Optional mobile device name + :returns: TRUE if the user agent is a (specified) mobile device, FALSE if not + :rtype: bool - if ($this->agent->is_mobile('iphone')) - { - $this->load->view('iphone/home'); - } - elseif ($this->agent->is_mobile()) - { - $this->load->view('mobile/home'); - } - else - { - $this->load->view('web/home'); - } - + Returns TRUE/FALSE (boolean) if the user agent is a known mobile device. + :: -$this->agent->is_robot() -========================= + if ($this->agent->is_mobile('iphone')) + { + $this->load->view('iphone/home'); + } + elseif ($this->agent->is_mobile()) + { + $this->load->view('mobile/home'); + } + else + { + $this->load->view('web/home'); + } -Returns TRUE/FALSE (boolean) if the user agent is a known robot. + .. method:: is_robot([$key = NULL]) -.. note:: The user agent library only contains the most common robot - definitions. It is not a complete list of bots. There are hundreds of - them so searching for each one would not be very efficient. If you find - that some bots that commonly visit your site are missing from the list - you can add them to your application/config/user_agents.php file. + :param string $key: Optional robot name + :returns: TRUE if the user agent is a (specified) robot, FALSE if not + :rtype: bool -$this->agent->is_referral() -============================ + Returns TRUE/FALSE (boolean) if the user agent is a known robot. -Returns TRUE/FALSE (boolean) if the user agent was referred from another -site. + .. note:: The user agent library only contains the most common robot definitions. It is not a complete list of bots. + There are hundreds of them so searching for each one would not be very efficient. If you find that some bots + that commonly visit your site are missing from the list you can add them to your + **application/config/user_agents.php** file. -$this->agent->browser() -======================= + .. method:: is_referral() -Returns a string containing the name of the web browser viewing your -site. + :returns: TRUE if the user agent is a referral, FALSE if not + :rtype: bool -$this->agent->version() -======================= + Returns TRUE/FALSE (boolean) if the user agent was referred from another site. -Returns a string containing the version number of the web browser -viewing your site. + .. method:: browser() -$this->agent->mobile() -====================== + :returns: Detected browser or an empty string + :rtype: string -Returns a string containing the name of the mobile device viewing your -site. + Returns a string containing the name of the web browser viewing your site. -$this->agent->robot() -===================== + .. method:: version() -Returns a string containing the name of the robot viewing your site. + :returns: Detected browser version or an empty string + :rtype: string -$this->agent->platform() -======================== + Returns a string containing the version number of the web browser viewing your site. -Returns a string containing the platform viewing your site (Linux, -Windows, OS X, etc.). + .. method:: mobile() -$this->agent->referrer() -======================== + :returns: Detected mobile device brand 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:: + Returns a string containing the name of the mobile device viewing your site. - if ($this->agent->is_referral()) - { - echo $this->agent->referrer(); - } + .. method:: robot() -$this->agent->agent_string() -============================= + :returns: Detected robot name or an empty string + :rtype: string -Returns a string containing the full user agent string. Typically it -will be something like this:: + Returns a string containing the name of the robot viewing your site. - Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.0.4) Gecko/20060613 Camino/1.0.2 + .. method:: platform() -$this->agent->accept_lang() -============================ + :returns: Detected operating system or an empty string + :rtype: string -Lets you determine if the user agent accepts a particular language. -Example:: + Returns a string containing the platform viewing your site (Linux, Windows, OS X, etc.). - if ($this->agent->accept_lang('en')) - { - echo 'You accept English!'; - } + .. method:: referrer() -.. note:: This function is not typically very reliable since some - browsers do not provide language info, and even among those that do, it - is not always accurate. + :returns: Detected referrer or an empty string + :rtype: string -$this->agent->accept_charset() -=============================== + The referrer, if the user agent was referred from another site. Typically you'll test for this as follows:: -Lets you determine if the user agent accepts a particular character set. -Example:: + if ($this->agent->is_referral()) + { + echo $this->agent->referrer(); + } - if ($this->agent->accept_charset('utf-8')) - { - echo 'You browser supports UTF-8!'; - } + .. method:: agent_string() + + :returns: 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 + + .. 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. + + .. method:: languages() + + :returns: An array list of accepted languages + :rtype: array + + Returns an array of languages supported by the user agent. + + .. method:: accept_charset([$charset = 'utf-8']) + + :param string $charset: Character set + :returns: 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. + + .. method:: charsets() + + :returns: An array list of accepted character sets + :rtype: array + + Returns an array of character sets accepted by the user agent. + + .. method:: parse($string) + + :param string $string: A custom user-agent string + :rtype: void -.. note:: This function is not typically very reliable since some - browsers do not provide character-set info, and even among those that - do, it is not always accurate. + Parses a custom user-agent string, different from the one reported by the current visitor.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/xmlrpc.rst b/user_guide_src/source/libraries/xmlrpc.rst index d2d695ee3..2cf548750 100644 --- a/user_guide_src/source/libraries/xmlrpc.rst +++ b/user_guide_src/source/libraries/xmlrpc.rst @@ -5,6 +5,13 @@ XML-RPC and XML-RPC Server Classes CodeIgniter's XML-RPC classes permit you to send requests to another server, or set up your own XML-RPC server to receive requests. +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + **************** What is XML-RPC? **************** @@ -24,8 +31,11 @@ it to determine which class/method should be called to process the request. Once processed, the server will then send back a response message. -For detailed specifications, you can visit the -`XML-RPC <http://www.xmlrpc.com/>`_ site. +For detailed specifications, you can visit the `XML-RPC <http://www.xmlrpc.com/>`_ site. + +*********************** +Using the XML-RPC Class +*********************** Initializing the Class ====================== @@ -123,6 +133,7 @@ with the data type in the second position:: The `Data Types <#datatypes>`_ section below has a full list of data types. + Creating an XML-RPC Server ========================== @@ -425,114 +436,142 @@ the Server. $size = $parameters[1]['size']; $shape = $parameters[1]['shape']; -************************** -XML-RPC Function Reference -************************** +Data Types +========== -$this->xmlrpc->server() -======================= +According to the `XML-RPC spec <http://www.xmlrpc.com/spec>`_ there are +seven types of values that you can send via XML-RPC: -Sets the URL and port number of the server to which a request is to be -sent:: +- *int* or *i4* +- *boolean* +- *string* +- *double* +- *dateTime.iso8601* +- *base64* +- *struct* (contains array of values) +- *array* (contains array of values) - $this->xmlrpc->server('http://www.sometimes.com/pings.php', 80); +*************** +Class Reference +*************** -$this->xmlrpc->timeout() -======================== +.. class:: CI_Xmlrpc -Set a time out period (in seconds) after which the request will be -canceled:: + .. method:: initialize([$config = array()]) - $this->xmlrpc->timeout(6); + :param array $config: Configuration data + :rtype: void -$this->xmlrpc->method() -======================= + Initializes the XML-RPC library. Accepts an associative array containing your settings. -Sets the method that will be requested from the XML-RPC server:: + .. method:: server($url[, $port = 80[, $proxy = FALSE[, $proxy_port = 8080]]]) - $this->xmlrpc->method('method'); + :param string $url: XML-RPC server URL + :param int $port: Server port + :param string $proxy: Optional proxy + :param int $proxy_port: Proxy listening port + :rtype: void -Where method is the name of the method. + Sets the URL and port number of the server to which a request is to be sent:: -$this->xmlrpc->request() -======================== + $this->xmlrpc->server('http://www.sometimes.com/pings.php', 80); -Takes an array of data and builds request to be sent to XML-RPC server:: + Basic HTTP authentication is also supported, simply add it to the server URL:: - $request = array(array('My Photoblog', 'string'), 'http://www.yoursite.com/photoblog/'); - $this->xmlrpc->request($request); + $this->xmlrpc->server('http://user:pass@localhost/', 80); -$this->xmlrpc->send_request() -============================== + .. method:: timeout($seconds = 5) -The request sending function. Returns boolean TRUE or FALSE based on -success for failure, enabling it to be used conditionally. + :param int $seconds: Timeout in seconds + :rtype: void -$this->xmlrpc->set_debug(TRUE); -================================ + Set a time out period (in seconds) after which the request will be canceled:: -Enables debugging, which will display a variety of information and error -data helpful during development. + $this->xmlrpc->timeout(6); -$this->xmlrpc->display_error() -=============================== + .. method:: method($function) -Returns an error message as a string if your request failed for some -reason. + :param string $function: Method name + :rtype: void -:: + Sets the method that will be requested from the XML-RPC server:: - echo $this->xmlrpc->display_error(); + $this->xmlrpc->method('method'); -$this->xmlrpc->display_response() -================================== + Where method is the name of the method. -Returns the response from the remote server once request is received. -The response will typically be an associative array. + .. method:: request($incoming) -:: + :param array $incoming: Request data + :rtype: void - $this->xmlrpc->display_response(); + Takes an array of data and builds request to be sent to XML-RPC server:: -$this->xmlrpc->send_error_message() -===================================== + $request = array(array('My Photoblog', 'string'), 'http://www.yoursite.com/photoblog/'); + $this->xmlrpc->request($request); -This function lets you send an error message from your server to the -client. First parameter is the error number while the second parameter -is the error message. + .. method:: send_request() -:: + :returns: TRUE on success, FALSE on failure + :rtype: bool - return $this->xmlrpc->send_error_message('123', 'Requested data not available'); + The request sending method. Returns boolean TRUE or FALSE based on success for failure, enabling it to be used conditionally. -$this->xmlrpc->send_response() -=============================== + .. method set_debug($flag = TRUE) -Lets you send the response from your server to the client. An array of -valid data values must be sent with this method. + :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. - $response = array( - array( - 'flerror' => array(FALSE, 'boolean'), - 'message' => "Thanks for the ping!" - ) - 'struct'); - return $this->xmlrpc->send_response($response); + .. method:: display_error() -Data Types -========== + :returns: Error message string + :rtype: string -According to the `XML-RPC spec <http://www.xmlrpc.com/spec>`_ there are -seven types of values that you can send via XML-RPC: + Returns an error message as a string if your request failed for some reason. + :: -- *int* or *i4* -- *boolean* -- *string* -- *double* -- *dateTime.iso8601* -- *base64* -- *struct* (contains array of values) -- *array* (contains array of values) + echo $this->xmlrpc->display_error(); + .. 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(); + + .. 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);
\ No newline at end of file diff --git a/user_guide_src/source/libraries/zip.rst b/user_guide_src/source/libraries/zip.rst index c27718273..5ff7d07d6 100644 --- a/user_guide_src/source/libraries/zip.rst +++ b/user_guide_src/source/libraries/zip.rst @@ -6,6 +6,17 @@ CodeIgniter's Zip Encoding Class classes permit you to create Zip archives. Archives can be downloaded to your desktop or saved to a directory. +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + +**************************** +Using the Zip Encoding Class +**************************** + Initializing the Class ====================== @@ -35,174 +46,180 @@ your server, and download it to your desktop. // Download the file to your desktop. Name it "my_backup.zip" $this->zip->download('my_backup.zip'); -****************** -Function Reference -****************** +*************** +Class Reference +*************** -$this->zip->add_data() -======================= +.. class:: CI_Zip -Permits you to add data to the Zip archive. The first parameter must -contain the name you would like given to the file, the second parameter -must contain the file data as a string:: + .. method:: add_data($filepath[, $data = NULL]) - $name = 'my_bio.txt'; - $data = 'I was born in an elevator...'; + :param mixed $filepath: A single file path or an array of file => data pairs + :param array $data: File contents (ignored if $filepath is an array) + :rtype: void - $this->zip->add_data($name, $data); + Adds data to the Zip archive. Can work both in single and multiple files mode. -You are allowed multiple calls to this function in order to add several -files to your archive. Example:: + When adding a single file, the first parameter must contain the name you would like given to the file and the second must contain the file contents:: - $name = 'mydata1.txt'; - $data = 'A Data String!'; - $this->zip->add_data($name, $data); + $name = 'mydata1.txt'; + $data = 'A Data String!'; + $this->zip->add_data($name, $data); - $name = 'mydata2.txt'; - $data = 'Another Data String!'; - $this->zip->add_data($name, $data); + $name = 'mydata2.txt'; + $data = 'Another Data String!'; + $this->zip->add_data($name, $data); + + When adding multiple files, the first parameter must contain *file => contents* pairs and the second parameter is ignored:: -Or you can pass multiple files using an array:: + $data = array( + 'mydata1.txt' => 'A Data String!', + 'mydata2.txt' => 'Another Data String!' + ); - $data = array( - 'mydata1.txt' => 'A Data String!', - 'mydata2.txt' => 'Another Data String!' - ); + $this->zip->add_data($data); - $this->zip->add_data($data); + If you would like your compressed data organized into sub-directories, simply include the path as part of the filename(s):: - $this->zip->download('my_backup.zip'); + $name = 'personal/my_bio.txt'; + $data = 'I was born in an elevator...'; -If you would like your compressed data organized into sub-folders, -include the path as part of the filename:: + $this->zip->add_data($name, $data); - $name = 'personal/my_bio.txt'; - $data = 'I was born in an elevator...'; + The above example will place my_bio.txt inside a folder called personal. - $this->zip->add_data($name, $data); + .. method:: add_dir($directory) -The above example will place my_bio.txt inside a folder called -personal. + :param mixed $directory: Directory name string or an array of multiple directories + :rtype: void -$this->zip->add_dir() -====================== + Permits you to add a directory. Usually this method is unnecessary since you can place your data into directories when using + ``$this->zip->add_data()``, but if you would like to create an empty directory you can do so:: -Permits you to add a directory. Usually this function is unnecessary -since you can place your data into folders when using -$this->zip->add_data(), but if you would like to create an empty folder -you can do so. Example:: + $this->zip->add_dir('myfolder'); // Creates a directory called "myfolder" - $this->zip->add_dir('myfolder'); // Creates a folder called "myfolder" + .. method:: read_file($path[, $archive_filepath = FALSE]) -$this->zip->read_file() -======================== + :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:: + Permits you to compress a file that already exists somewhere on your server. + Supply a file path and the zip class will read it and add it to the archive:: - $path = '/path/to/photo.jpg'; + $path = '/path/to/photo.jpg'; - $this->zip->read_file($path); + $this->zip->read_file($path); - // Download the file to your desktop. Name it "my_backup.zip" - $this->zip->download('my_backup.zip'); + // Download the file to your desktop. Name it "my_backup.zip" + $this->zip->download('my_backup.zip'); -If you would like the Zip archive to maintain the directory structure of -the file in it, pass TRUE (boolean) in the second parameter. Example:: + If you would like the Zip archive to maintain the directory structure of + the file in it, pass TRUE (boolean) in the second parameter. Example:: - $path = '/path/to/photo.jpg'; + $path = '/path/to/photo.jpg'; - $this->zip->read_file($path, TRUE); + $this->zip->read_file($path, TRUE); - // Download the file to your desktop. Name it "my_backup.zip" - $this->zip->download('my_backup.zip'); + // Download the file to your desktop. Name it "my_backup.zip" + $this->zip->download('my_backup.zip'); -In the above example, photo.jpg will be placed inside two folders: -path/to/ + In the above example, photo.jpg will be placed into the *path/to/* directory. -$this->zip->read_dir() -======================= + You can also specify a new name (path included) for the added file on the fly:: -Permits you to compress a folder (and its contents) that already exists -somewhere on your server. Supply a file path to the directory and the -zip class will recursively read it and recreate it as a Zip archive. All -files contained within the supplied path will be encoded, as will any -sub-folders contained within it. Example:: + $path = '/path/to/photo.jpg'; + $new_path = '/new/path/some_photo.jpg'; - $path = '/path/to/your/directory/'; + $this->zip->read_file($path, $new_path); - $this->zip->read_dir($path); + // Download ZIP archive containing /new/path/some_photo.jpg + $this->zip->download('my_archive.zip'); - // Download the file to your desktop. Name it "my_backup.zip" - $this->zip->download('my_backup.zip'); + .. method:: read_dir($path[, $preserve_filepath = TRUE[, $root_path = NULL]]) -By default the Zip archive will place all directories listed in the -first parameter inside the zip. If you want the tree preceding the -target folder to be ignored you can pass FALSE (boolean) in the second -parameter. Example:: + :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 - $path = '/path/to/your/directory/'; + Permits you to compress a directory (and its contents) that already exists somewhere on your server. + Supply a path to the directory and the zip class will recursively read and recreate it as a Zip archive. + All files contained within the supplied path will be encoded, as will any sub-directories contained within it. Example:: - $this->zip->read_dir($path, FALSE); + $path = '/path/to/your/directory/'; -This will create a ZIP with the folder "directory" inside, then all -sub-folders stored correctly inside that, but will not include the -folders /path/to/your. + $this->zip->read_dir($path); -$this->zip->archive() -===================== + // Download the file to your desktop. Name it "my_backup.zip" + $this->zip->download('my_backup.zip'); -Writes the Zip-encoded file to a directory on your server. Submit a -valid server path ending in the file name. Make sure the directory is -writable (666 or 777 is usually OK). Example:: + By default the Zip archive will place all directories listed in the first parameter inside the zip. + If you want the tree preceding the target directory to be ignored you can pass FALSE (boolean) in the second parameter. Example:: - $this->zip->archive('/path/to/folder/myarchive.zip'); // Creates a file named myarchive.zip + $path = '/path/to/your/directory/'; -$this->zip->download() -====================== + $this->zip->read_dir($path, FALSE); -Causes the Zip file to be downloaded from your server. The function must -be passed the name you would like the zip file called. Example:: + This will create a ZIP with a directory named "directory" inside, then all sub-directories stored correctly inside that, but will not include the + */path/to/your* part of the path. - $this->zip->download('latest_stuff.zip'); // File will be named "latest_stuff.zip" + .. method:: archive($filepath) -.. note:: Do not display any data in the controller in which you call - this function since it sends various server headers that cause the - download to happen and the file to be treated as binary. + :param string $filepath: Path to target zip archive + :returns: TRUE on success, FALSE on failure + :rtype: bool -$this->zip->get_zip() -====================== + Writes the Zip-encoded file to a directory on your server. Submit a valid server path ending in the file name. + Make sure the directory is writable (660 or 666 is usually OK). Example:: -Returns the Zip-compressed file data. Generally you will not need this -function unless you want to do something unique with the data. Example:: + $this->zip->archive('/path/to/folder/myarchive.zip'); // Creates a file named myarchive.zip - $name = 'my_bio.txt'; - $data = 'I was born in an elevator...'; + .. method:: download($filename = 'backup.zip') - $this->zip->add_data($name, $data); + :param string $filename: Archive file name + :rtype: void - $zip_file = $this->zip->get_zip(); + Causes the Zip file to be downloaded from your server. You must pass the name you would like the zip file called. Example:: -$this->zip->clear_data() -========================= + $this->zip->download('latest_stuff.zip'); // File will be named "latest_stuff.zip" -The Zip class caches your zip data so that it doesn't need to recompile -the Zip archive for each function you use above. If, however, you need -to create multiple Zips, each with different data, you can clear the -cache between calls. Example:: + .. 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. - $name = 'my_bio.txt'; - $data = 'I was born in an elevator...'; + .. method:: get_zip() - $this->zip->add_data($name, $data); - $zip_file = $this->zip->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(); + + .. 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:: - $this->zip->clear_data(); + $name = 'my_bio.txt'; + $data = 'I was born in an elevator...'; - $name = 'photo.jpg'; - $this->zip->read_file("/path/to/photo.jpg"); // Read the file's contents + $this->zip->add_data($name, $data); + $zip_file = $this->zip->get_zip(); + $this->zip->clear_data(); - $this->zip->download('myphotos.zip'); + $name = 'photo.jpg'; + $this->zip->read_file("/path/to/photo.jpg"); // Read the file's contents + $this->zip->download('myphotos.zip');
\ No newline at end of file |