diff options
Diffstat (limited to 'user_guide_src')
36 files changed, 1559 insertions, 288 deletions
diff --git a/user_guide_src/cilexer/cilexer/cilexer.py b/user_guide_src/cilexer/cilexer/cilexer.py index 265b4077f..713268e9c 100644 --- a/user_guide_src/cilexer/cilexer/cilexer.py +++ b/user_guide_src/cilexer/cilexer/cilexer.py @@ -1,3 +1,25 @@ +# CodeIgniter +# http://codeigniter.com +# +# An open source application development framework for PHP 5.1.6 or newer +# +# NOTICE OF LICENSE +# +# Licensed under the Open Software License version 3.0 +# +# This source file is subject to the Open Software License (OSL 3.0) that is +# bundled with this package in the files license.txt / license.rst. It is +# also available through the world wide web at this URL: +# http://opensource.org/licenses/OSL-3.0 +# If you did not receive a copy of the license and are unable to obtain it +# through the world wide web, please send an email to +# licensing@ellislab.com so we can send you a copy immediately. +# +# Copyright (c) 2008 - 2012, EllisLab, Inc. (http://ellislab.com/) +# http://opensource.org/licenses/OSL-3.0 Open Software License (OSL 3.0) + + + import re import copy diff --git a/user_guide_src/source/_themes/eldocs/layout.html b/user_guide_src/source/_themes/eldocs/layout.html index da59e5302..4b1a0221c 100644 --- a/user_guide_src/source/_themes/eldocs/layout.html +++ b/user_guide_src/source/_themes/eldocs/layout.html @@ -84,7 +84,7 @@ <div id="brand" class="{{ project_abbreviation }}"> <a href="http://{{ project_domain }}/"><img src="{{ pathto('_static/asset/img/' + project_abbreviation + '-logo.gif', 1) }}" alt="{{ project }}"></a> - <p>{{ version }} User Guide</p> + <p>{{ release }} User Guide</p> {%- if show_source and has_source and sourcename %} <p><a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow">{{ _('Show Source') }}</a></p> @@ -124,7 +124,15 @@ {%- block footer %} <div id="footer"> - <p class="top"><a href="#header" title="Return to top">Return to top</a></p> + <p class="top"> + {% if prev %} + <span class="prev">Previous Topic: <a href="{{ prev.link }}">{{ prev.title }}</a></span> + {% endif %} + {% if next %} + <span class="next">Next Topic: <a href="{{ next.link }}">{{ next.title }}</a></span> + {% endif %} + <a href="#header" title="Return to top">Return to top</a> + </p> <p><a href="{{ project_url }}">{{ project }}</a> – Copyright © {{ copyright }}</a> – Last updated: {{ last_updated }}</p> </div><!-- /#footer --> {%- endblock %} 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 c216c3666..b9e28aec0 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 @@ -1,3 +1,25 @@ +/* +CodeIgniter +http://codeigniter.com + +An open source application development framework for PHP 5.1.6 or newer + +NOTICE OF LICENSE + +Licensed under the Open Software License version 3.0 + +This source file is subject to the Open Software License (OSL 3.0) that is +bundled with this package in the files license.txt / license.rst. It is +also available through the world wide web at this URL: +http://opensource.org/licenses/OSL-3.0 +If you did not receive a copy of the license and are unable to obtain it +through the world wide web, please send an email to +licensing@ellislab.com so we can send you a copy immediately. + +Copyright (c) 2008 - 2012, EllisLab, Inc. (http://ellislab.com/) +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; } @@ -119,6 +141,8 @@ img{ display: block; max-width: 100%; } fieldset{ border: 0; } .top{ float: right; } +.next{ padding: 0 20px 0 10px; } +.prev{ padding-right: 10px; } .highlight-ci, .highlight-ee, diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst index 925785d13..00d70f323 100644 --- a/user_guide_src/source/changelog.rst +++ b/user_guide_src/source/changelog.rst @@ -2,25 +2,124 @@ Change Log ########## -Version 2.1.0 (planned) +Version 3.0 (planned) ======================= Release Date: Not Released +- License + + - CodeIgniter has been relicensed with the Open Software License (3.0), + eliminating its old proprietary licensing. + + - All system files are licensed with OSL 3.0. + - Config, error, and sample files shipped in the application folder are + licensed with the Academic Free License (3.0) to allow you to retain + all licensing authority over your own application code. + - General Changes + - Added an optional backtrace to php-error template. - Added Android to the list of user agents. - Added Windows 7 to the list of user platforms. + - Ability to log certain error types, not all under a threshold. + - Added support for pem, p10, p12, p7a, p7c, p7m, p7r, p7s, crt, crl, der, kdb, rsa, cer, sst, csr Certs to mimes.php. + - Added support for pgp and gpg to mimes.php. + - Added support for 3gp, 3g2, mp4, wmv, f4v, vlc Video files to mimes.php. + - Added support for m4a, aac, m4u, xspf, au, ac3, flac, ogg Audio files to mimes.php. + - Added support for kmz and kml (Google Earth) files to mimes.php. + - Added application/xml for xml and application/xml, text/xsl for xsl in mimes.php. + - Changed logger to only chmod when file is first created. + - Removed previously deprecated SHA1 Library. + - Removed previously deprecated use of ``$autoload['core']`` in application/config/autoload.php. + Only entries in ``$autoload['libraries']`` are auto-loaded now. + +- Helpers + + - url_title() will now trim extra dashes from beginning and end. + - Added XHTML Basic 1.1 doctype to :doc:`HTML Helper <helpers/html_helper>`. + - Changed humanize to include a second param for the separator. + +- Database + + - Added new :doc:`Active Record <database/active_record>` methods that return + the SQL string of queries without executing them: get_compiled_select(), + get_compiled_insert(), get_compiled_update(), get_compiled_delete(). + - Taking care of LIKE condition when used with MySQL UPDATE statement. + - Adding $escape parameter to the order_by function, this enables ordering by custom fields. + - MySQLi driver now uses mysqli_get_server_info() for server version checking. + - MySQLi driver now supports persistent connections when running on PHP >= 5.3. + - Added dsn if the group connections in the config use PDO or any driver which need DSN. + - Improved PDO database support. + +- Libraries + + - Added max_filename_increment config setting for Upload library. + - CI_Loader::_ci_autoloader() is now a protected method. + - Modified valid_ip() to use PHP's filter_var() when possible (>= PHP 5.2) in the :doc:`Form Validation library <libraries/form_validation>`. + - Added custom filename to Email::attach() as $this->email->attach($filename, $disposition, $newname) + - Cart library changes include: + - It now auto-increments quantity's instead of just resetting it, this is the default behaviour of large e-commerce sites. + - Product Name strictness can be disabled via the Cart Library by switching "$product_name_safe" + - Added function remove() to remove a cart item, updating with quantity of 0 seemed like a hack but has remained to retain compatability + - Image manipulation library changes include: + - The initialize() method now only sets existing class properties. + - Added support for 3-length hex color values for wm_font_color and wm_shadow_color properties, as well as validation for them. + - Class properties wm_font_color, wm_shadow_color and wm_use_drop_shadow are now protected, to avoid breaking the text_watermark() method + if they are set manually after initialization. + - If property maintain_ratio is set to TRUE, image_reproportion() now doesn't need both width and height to be specified. + - Minor speed optimizations and method & property visibility declarations in the Calendar Library. + - Removed SHA1 function in the :doc:`Encryption Library <libraries/encryption>`. + - Added $config['csrf_regeneration'] to the CSRF protection in the :doc:`Security library <libraries/security>`, which makes token regeneration optional. + +- Core + + - Changed private functions in CI_URI to protected so MY_URI can override them. + - Removed CI_CORE boolean constant from CodeIgniter.php (no longer Reactor and Core versions). + - Added method get_vars() to CI_Loader to retrieve all variables loaded with $this->load->vars(). + - is_loaded() function from system/core/Commons.php now returns a reference. + +Bug fixes for 3.0 +------------------ + +- 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) that mishandled Active Record nested transactions because _trans_depth was not getting incremented. +- Fixed a bug (#737, #75) where pagination anchor class was not set properly when using initialize method. +- Fixed a bug (#419) - auto_link() now recognizes URLs that come after a word boundary. +- Fixed a bug (#724) - is_unique in form validation now checks that you are connected to a database. +- Fixed a bug (#647) - _get_mod_time() in Zip library no longer generates stat failed errors +- Fixed a bug (#608) - Fixes an issue with the Image_lib class not clearing properties completely +- Fixed bugs (#157 and #174) - the Image_lib clear() function now resets all variables to their default values. +- Fixed a bug where using $this->dbforge->create_table() with PostgreSQL database could lead to fetching whole table. +- Fixed a bug (#795) - Fixed form method and accept-charset when passing an empty array. +- Fixed a bug (#797) - 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 (#406) - sqlsrv DB driver not reuturning resource on <samp>db_pconnect()</samp>. +- 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. +- In Pagination library, when use_page_numbers=TRUE previous link and page 1 link do 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. + +Version 2.1.0 +============= + +Release Date: Not Released + +- General Changes + - Callback validation rules can now accept parameters like any other validation rule. - - Ability to log certain error types, not all under a threshold. - Added html_escape() to :doc:`Common functions <general/common_functions>` to escape HTML output for preventing XSS. - - Added support for pem,p10,p12,p7a,p7c,p7m,p7r,p7s,crt,crl,der,kdb,rsa,cer,sst,csr Certs to mimes.php. - - Added support pgp,gpg to mimes.php. - - Added support 3gp, 3g2, mp4, wmv, f4v, vlc Video files to mimes.php. - - Added support m4a, aac, m4u, xspf, au, ac3, flac, ogg Audio files to mimes.php. - Helpers @@ -30,22 +129,22 @@ Release Date: Not Released - Altered form helper - made action on form_open_multipart helper function call optional. Fixes (#65) - url_title() will now trim extra dashes from beginning and end. - - Improved speed of <a href="helpers/string_helper.html">String Helper</a>'s <b>random_string()</b> method - - Added XHTML Basic 1.1 doctype to <a href="helpers/html_helper.html">HTML Helper</a>. + - Improved speed of :doc:`String Helper <helpers/string_helper>`'s random_string() method - Database - - Added a `CUBRID <http://www.cubrid.org/>`_ driver to the `Database + - Added a `CUBRID <http://www.cubrid.org/>`_ driver to the :doc:`Database Driver <database/index>`. Thanks to the CUBRID team for supplying this patch. - - Added a PDO driver to the <a href="database/index.html">Database Driver</a>. + - Added a PDO driver to the :doc:`Database Driver <database/index>`. - Typecast limit and offset in the :doc:`Database Driver <database/queries>` to integers to avoid possible injection. - Added additional option 'none' for the optional third argument for $this->db->like() in the :doc:`Database Driver <database/active_record>`. - - Added <kbd>$this->db->insert_batch()</kbd> support to the OCI8 (Oracle) driver. + - Added $this->db->insert_batch() support to the OCI8 (Oracle) driver. + - Added failover if the main connections in the config should fail - Libraries @@ -55,13 +154,13 @@ Release Date: Not Released - Added support to set an optional parameter in your callback rules of validation using the :doc:`Form Validation Library <libraries/form_validation>`. + - Added a :doc:`Migration library <libraries/migration>` to assist with applying + incremental updates to your database schema. - Driver children can be located in any package path. - Added max_filename_increment config setting for Upload library. - - CI_Loader::_ci_autoloader() is now a protected method. - Added is_unique to the :doc:`Form Validation library <libraries/form_validation>`. - - Modified valid_ip() to use PHP's filter_var() when possible (>= PHP 5.2) in the <a href="libraries/form_validation.html">Form Validation</a> library. - - Added <kbd>$config['use_page_numbers']</kbd> to the <a href="libraries/pagination.html">Pagination library</a>, which enables real page numbers in the URI. + - Added $config['use_page_numbers'] to the :doc:`Pagination library <libraries/pagination>`, which enables real page numbers in the URI. - Added TLS and SSL Encryption for SMTP. - Core @@ -70,10 +169,11 @@ Release Date: Not Released override them. - Removed CI_CORE boolean constant from CodeIgniter.php (no longer Reactor and Core versions). + Bug fixes for 2.1.0 ------------------- -- Unlink raised an error if cache file did not exist when you try to delete it. + - Fixed #378 Robots identified as regular browsers by the User Agent class. - If a config class was loaded first then a library with the same name @@ -84,30 +184,28 @@ Bug fixes for 2.1.0 but the requested method did not. - Fixed a bug (Reactor #89) where MySQL export would fail if the table had hyphens or other non alphanumeric/underscore characters. -- Fixed a bug (#200) where MySQL queries would be malformed after - calling count_all() then db->get() -- Fixed bug #105 that stopped query errors from being logged unless database debugging was enabled -- Fixed a bug (#181) where a mis-spelling was in the form validation - language file. +- Fixed a bug (#200) where MySQL queries would be malformed after calling $this->db->count_all() then $this->db->get() +- Fixed a bug (#105) that stopped query errors from being logged unless database debugging was enabled - Fixed a bug (#160) - Removed unneeded array copy in the file cache driver. - Fixed a bug (#150) - field_data() now correctly returns column length. - Fixed a bug (#8) - load_class() now looks for core classes in APPPATH first, allowing them to be replaced. -- Fixed a bug (#24) - ODBC database driver called incorrect parent in - __construct(). -- Fixed a bug (#85) - OCI8 (Oracle) database escape_str() function did - not escape correct. -- Fixed a bug (#344) - Using schema found in <a href="libraries/sessions.html">Saving Session Data to a Database</a>, system would throw error "user_data does not have a default value" when deleting then creating a session. +- Fixed a bug (#24) - ODBC database driver called incorrect parent in __construct(). +- Fixed a bug (#85) - OCI8 (Oracle) database escape_str() function did not escape correct. +- Fixed a bug (#344) - Using schema found in :doc:`Saving Session Data to a Database <libraries/sessions>`, system would throw error "user_data does not have a default value" when deleting then creating a session. - Fixed a bug (#112) - OCI8 (Oracle) driver didn't pass the configured database character set when connecting. - Fixed a bug (#182) - OCI8 (Oracle) driver used to re-execute the statement whenever num_rows() is called. -- Fixed a bug (#82) - WHERE clause field names in the DB <samp>update_string()</samp> method were not escaped, resulting in failed queries in some cases. -- Fixed a bug (#89) - Fix a variable type mismatch in DB <samp>display_error()</samp> where an array is expected, but a string could be set instead. +- Fixed a bug (#82) - WHERE clause field names in the DB update_string() method were not escaped, resulting in failed queries in some cases. +- Fixed a bug (#89) - Fix a variable type mismatch in DB display_error() where an array is expected, but a string could be set instead. - Fixed a bug (#467) - Suppress warnings generated from get_magic_quotes_gpc() (deprecated in PHP 5.4) - Fixed a bug (#484) - First time _csrf_set_hash() is called, hash is never set to the cookie (in Security.php). -- Fixed a bug (#60) - Added _file_mime_type() method to the `File Uploading Library <libraries/file_uploading>` in order to fix a possible MIME-type injection. +- Fixed a bug (#60) - Added _file_mime_type() method to the :doc:`File Uploading Library <libraries/file_uploading>` in order to fix a possible MIME-type injection. - Fixed a bug (#537) - Support for all wav type in browser. +- Fixed a bug (#576) - Using ini_get() function to detect if apc is enabled or not. +- Fixed invalid date time format in :doc:`Date helper <helpers/date_helper>` and :doc:`XMLRPC library <libraries/xmlrpc>`. +- Fixed a bug (#200) - MySQL queries would be malformed after calling count_all() then db->get(). Version 2.0.3 ============= @@ -145,16 +243,8 @@ Release Date: August 20, 2011 Thanks to epallerols for the patch. - Added "application/x-csv" to mimes.php. - Added CSRF protection URI whitelisting. - - Fixed a bug where `Email library <libraries/email>` + - Fixed a bug where :doc:`Email library <libraries/email>` attachments with a "." in the name would using invalid MIME-types. - - Added support for - pem,p10,p12,p7a,p7c,p7m,p7r,p7s,crt,crl,der,kdb,rsa,cer,sst,csr - Certs to mimes.php. - - Added support pgp,gpg to mimes.php. - - Added support 3gp, 3g2, mp4, wmv, f4v, vlc Video files to - mimes.php. - - Added support m4a, aac, m4u, xspf, au, ac3, flac, ogg Audio files - to mimes.php. - Helpers @@ -281,7 +371,7 @@ Hg Tag: v2.0.1 TRUE and Reactor: FALSE. - Added an ENVIRONMENT constant in index.php, which affects PHP error reporting settings, and optionally, which configuration - files are loaded (see below). Read more on the `Handling + files are loaded (see below). Read more on the :doc:`Handling Environments <general/environments>` page. - Added support for :ref:`environment-specific <config-environments>` @@ -289,7 +379,7 @@ Hg Tag: v2.0.1 - Libraries - - Added decimal, less_than and greater_than rules to the `Form + - Added decimal, less_than and greater_than rules to the :doc:`Form validation Class <libraries/form_validation>`. - :doc:`Input Class <libraries/input>` methods post() and get() will now return a full array if the first argument is not @@ -319,6 +409,8 @@ Bug fixes for 2.0.1 - Fixed a bug (Reactor #69) where the SHA1 library was named incorrectly. +.. _2.0.0-changelog: + Version 2.0.0 ============= @@ -361,7 +453,7 @@ Hg Tag: v2.0.0 - Removed the deprecated Validation Class. - Added CI\_ Prefix to all core classes. - Package paths can now be set in application/config/autoload.php. - - `Upload library <libraries/file_uploading>` file_name can + - :doc:`Upload library <libraries/file_uploading>` file_name can now be set without an extension, the extension will be taken from the uploaded file instead of the given name. - In :doc:`Database Forge <database/forge>` the name can be omitted @@ -533,7 +625,7 @@ Hg Tag: v2.0.0 - Added "default" to the list :doc:`Reserved Names <general/reserved_names>`. - Added 'application/x-msdownload' for .exe files and - ''application/x-gzip-compressed' for .tgz files to + 'application/x-gzip-compressed' for .tgz files to config/mimes.php. - Updated the output library to no longer compress output or send content-length headers if the server runs with @@ -664,7 +756,7 @@ Hg Tag: v1.7.2 - General - - Compatible with PHP 5.3.0 + - Compatible with PHP 5.3.0. - Modified :doc:`show_error() <general/errors>` to allow sending of HTTP server response codes. - Modified :doc:`show_404() <general/errors>` to send 404 status @@ -1272,7 +1364,7 @@ Hg Tag: 1.6.1 URL encoded strings. - Added $_SERVER, $_FILES, $_ENV, and $_SESSION to sanitization of globals. - - Added a `Path Helper <./helpers/path_helper>`. + - Added a :doc:`Path Helper <./helpers/path_helper>`. - Simplified _reindex_segments() in the URI class. - Escaped the '-' in the default 'permitted_uri_chars' config item, to prevent errors if developers just try to add additional @@ -1679,7 +1771,7 @@ Version 1.5.2 Release Date: February 13, 2007 - Added subversion information - to the `downloads <installation/downloads>` page. + to the :doc:`downloads <installation/downloads>` page. - Added support for captions in the :doc:`Table Library <./libraries/table>` - Fixed a bug in the @@ -1735,7 +1827,7 @@ Version 1.5.0 Release Date: October 30, 2006 -- Added `DB utility class <./database/utilities>`, permitting DB +- Added :doc:`DB utility class <./database/utilities>`, permitting DB backups, CVS or XML files from DB results, and various other functions. - Added :doc:`Database Caching Class <./database/caching>`. @@ -1894,7 +1986,7 @@ Release Date: September 17, 2006 sub-folders <general/controllers>`. Kudos to Marco for `suggesting <http://codeigniter.com/forums/viewthread/627/>`_ this (and the next two) feature. -- Added regular expressions support for `routing +- Added regular expressions support for :doc:`routing rules <./general/routing>`. - Added the ability to :doc:`remap function calls <./general/controllers>` within your controllers. diff --git a/user_guide_src/source/conf.py b/user_guide_src/source/conf.py index bd5e65297..593ceaf1c 100644 --- a/user_guide_src/source/conf.py +++ b/user_guide_src/source/conf.py @@ -41,16 +41,16 @@ master_doc = 'index' # General information about the project. project = u'CodeIgniter' -copyright = u'2011, EllisLab, Inc.' +copyright = u'2012, EllisLab, Inc.' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '2.1' +version = '3.0' # The full version, including alpha/beta/rc tags. -release = '2.1.0' +release = '3.0-dev' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -223,7 +223,7 @@ man_pages = [ epub_title = u'CodeIgniter' epub_author = u'EllisLab, Inc.' epub_publisher = u'EllisLab, Inc.' -epub_copyright = u'2011, EllisLab, Inc.' +epub_copyright = u'2012, EllisLab, Inc.' # The language of the text. It defaults to the language option # or en if the language is not set. diff --git a/user_guide_src/source/database/active_record.rst b/user_guide_src/source/database/active_record.rst index e1fc00bc5..c04e67d2a 100644 --- a/user_guide_src/source/database/active_record.rst +++ b/user_guide_src/source/database/active_record.rst @@ -45,7 +45,7 @@ You'll notice that the above function is assigned to a variable named $query, which can be used to show the results:: $query = $this->db->get('mytable'); - + foreach ($query->result() as $row) { echo $row->title; @@ -54,6 +54,37 @@ $query, which can be used to show the results:: Please visit the :doc:`result functions <results>` page for a full discussion regarding result generation. +$this->db->get_compiled_select() +================================ + +Compiles the selection query just like `$this->db->get()`_ but does not *run* +the query. This method simply returns the SQL query as a string. + +Example:: + + $sql = $this->db->get_compiled_select('mytable'); + echo $sql; + + // Produces string: SELECT * FROM mytable + +The second parameter enables you to set whether or not the active record query +will be reset (by default it will be—just like `$this->db->get()`):: + + echo $this->db->limit(10,20)->get_compiled_select('mytable', FALSE); + // Produces string: SELECT * FROM mytable LIMIT 20, 10 + // (in MySQL. Other databases have slightly different syntax) + + echo $this->db->select('title, content, date')->get_compiled_select(); + + // Produces string: SELECT title, content, date FROM mytable + +The key thing to notice in the above example is that the second query did not +utilize `$this->db->from()`_ and did not pass a table name into the first +parameter. The reason for this outcome is because the query has not been +executed using `$this->db->get()`_ which resets values or reset directly +using `$this->db->reset_query()`_. + + $this->db->get_where() ====================== @@ -65,8 +96,7 @@ function:: Please read the about the where function below for more information. -Note: get_where() was formerly known as getwhere(), which has been -removed +.. note:: get_where() was formerly known as getwhere(), which has been removed $this->db->select() =================== @@ -86,7 +116,7 @@ with backticks. This is useful if you need a compound select statement. :: - $this->db->select('(SELECT SUM(payments.amount) FROM payments WHERE payments.invoice_id=4') AS amount_paid', FALSE); + $this->db->select('(SELECT SUM(payments.amount) FROM payments WHERE payments.invoice_id=4') AS amount_paid', FALSE); $query = $this->db->get('mytable'); @@ -100,7 +130,7 @@ include a second parameter to rename the resulting field. $this->db->select_max('age'); $query = $this->db->get('members'); // Produces: SELECT MAX(age) as age FROM members - + $this->db->select_max('age', 'member_age'); $query = $this->db->get('members'); // Produces: SELECT MAX(age) as member_age FROM members @@ -165,9 +195,9 @@ Permits you to write the JOIN portion of your query:: $this->db->from('blogs'); $this->db->join('comments', 'comments.id = blogs.id'); $query = $this->db->get(); - + // Produces: - // SELECT * FROM blogs // JOIN comments ON comments.id = blogs.id + // SELECT * FROM blogs JOIN comments ON comments.id = blogs.id Multiple function calls can be made if you need several joins in one query. @@ -194,7 +224,7 @@ methods: :: - $this->db->where('name', $name); // Produces: WHERE name = 'Joe' + $this->db->where('name', $name); // Produces: WHERE name = 'Joe' Notice that the equal sign is added for you. @@ -206,7 +236,7 @@ methods: $this->db->where('name', $name); $this->db->where('title', $title); $this->db->where('status', $status); - // WHERE name = 'Joe' AND title = 'boss' AND status = 'active' + // WHERE name = 'Joe' AND title = 'boss' AND status = 'active' #. **Custom key/value method:** You can include an operator in the first parameter in order to @@ -215,7 +245,7 @@ methods: :: $this->db->where('name !=', $name); - $this->db->where('id <', $id); // Produces: WHERE name != 'Joe' AND id < 45 + $this->db->where('id <', $id); // Produces: WHERE name != 'Joe' AND id < 45 #. **Associative array method:** @@ -223,7 +253,7 @@ methods: $array = array('name' => $name, 'title' => $title, 'status' => $status); $this->db->where($array); - // Produces: WHERE name = 'Joe' AND title = 'boss' AND status = 'active' + // Produces: WHERE name = 'Joe' AND title = 'boss' AND status = 'active' You can include your own operators using this method as well: @@ -324,7 +354,7 @@ searches. :: - $this->db->like('title', 'match'); // Produces: WHERE title LIKE '%match%' + $this->db->like('title', 'match'); // Produces: WHERE title LIKE '%match%' If you use multiple function calls they will be chained together with AND between them:: @@ -341,7 +371,7 @@ searches. $this->db->like('title', 'match', 'before'); // Produces: WHERE title LIKE '%match' $this->db->like('title', 'match', 'after'); // Produces: WHERE title LIKE 'match%' - $this->db->like('title', 'match', 'both'); // Produces: WHERE title LIKE '%match%' + $this->db->like('title', 'match', 'both'); // Produces: WHERE title LIKE '%match%' #. **Associative array method:** @@ -413,7 +443,7 @@ Permits you to write the HAVING portion of your query. There are 2 possible syntaxes, 1 argument or 2:: $this->db->having('user_id = 45'); // Produces: HAVING user_id = 45 - $this->db->having('user_id', 45); // Produces: HAVING user_id = 45 + $this->db->having('user_id', 45); // Produces: HAVING user_id = 45 You can also pass an array of multiple values as well:: @@ -456,7 +486,7 @@ Or multiple function calls can be made if you need multiple fields. :: $this->db->order_by("title", "desc"); - $this->db->order_by("name", "asc"); // Produces: ORDER BY title DESC, name ASC + $this->db->order_by("name", "asc"); // Produces: ORDER BY title DESC, name ASC .. note:: order_by() was formerly known as orderby(), which has been @@ -488,7 +518,7 @@ where(), or_where(), like(), or_like(), etc. Example:: echo $this->db->count_all_results('my_table'); // Produces an integer, like 25 $this->db->like('title', 'match'); $this->db->from('my_table'); - echo $this->db->count_all_results(); // Produces an integer, like 17 + echo $this->db->count_all_results(); // Produces an integer, like 17 $this->db->count_all() ====================== @@ -499,6 +529,54 @@ Submit the table name in the first parameter. Example:: echo $this->db->count_all('my_table'); // Produces an integer, like 25 ************** +Query grouping +************** + +Query grouping allows you to create groups of WHERE clauses by enclosing them in parentheses. This will allow +you to create queries with complex WHERE clauses. Nested groups are supported. Example: + + $this->db->select('*')->from('my_table') + ->group_start() + ->where('a', 'a') + ->or_group_start() + ->where('b', 'b') + ->where('c', 'c') + ->group_end() + ->group_end() + ->where('d', 'd') + ->get(); + + // Generates: + // SELECT * FROM (`my_table`) WHERE ( `a` = 'a' OR ( `b` = 'b' AND `c` = 'c' ) ) AND `d` = 'd' + +.. note:: groups need to be balanced, make sure every group_start() is matched by a group_end(). + +$this->db->group_start() +======================== + +Starts a new group by adding an opening parenthesis to the WHERE clause of the query. + +$this->db->or_group_start() +=========================== + +Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'OR'. + +$this->db->not_group_start() +============================ + +Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'NOT'. + +$this->db->or_not_group_start() +=============================== + +Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'OR NOT'. + +$this->db->group_end() +====================== + +Ends the current group by adding an closing parenthesis to the WHERE clause of the query. + +************** Inserting Data ************** @@ -514,7 +592,7 @@ function. Here is an example using an array:: 'name' => 'My Name', 'date' => 'My date' ); - + $this->db->insert('mytable', $data); // Produces: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date') @@ -530,7 +608,7 @@ Here is an example using an object:: var $date = 'My Date'; } */ - + $object = new Myclass; $this->db->insert('mytable', $object); // Produces: INSERT INTO mytable (title, content, date) VALUES ('My Title', 'My Content', 'My Date') @@ -540,6 +618,41 @@ object. .. note:: All values are escaped automatically producing safer queries. +$this->db->get_compiled_insert() +================================ +Compiles the insertion query just like `$this->db->insert()`_ but does not +*run* the query. This method simply returns the SQL query as a string. + +Example:: + + $data = array( + 'title' => 'My title', + 'name' => 'My Name', + 'date' => 'My date' + ); + + $sql = $this->db->set($data)->get_compiled_insert('mytable'); + echo $sql; + + // Produces string: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date') + +The second parameter enables you to set whether or not the active record query +will be reset (by default it will be--just like `$this->db->insert()`_):: + + echo $this->db->set('title', 'My Title')->get_compiled_insert('mytable', FALSE); + + // Produces string: INSERT INTO mytable (title) VALUES ('My Title') + + echo $this->db->set('content', 'My Content')->get_compiled_insert(); + + // Produces string: INSERT INTO mytable (title, content) VALUES ('My Title', 'My Content') + +The key thing to notice in the above example is that the second query did not +utlize `$this->db->from()`_ nor did it pass a table name into the first +parameter. The reason this worked is because the query has not been executed +using `$this->db->insert()`_ which resets values or reset directly using +`$this->db->reset_query()`_. + $this->db->insert_batch() ========================= @@ -559,7 +672,7 @@ function. Here is an example using an array:: 'date' => 'Another date' ) ); - + $this->db->insert_batch('mytable', $data); // Produces: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date'), ('Another title', 'Another name', 'Another date') @@ -587,7 +700,7 @@ based on whether you are doing an insert or an update:: $this->db->set('name', $name); $this->db->set('title', $title); $this->db->set('status', $status); - $this->db->insert('mytable'); + $this->db->insert('mytable'); **set()** will also accept an optional third parameter ($escape), that will prevent data from being escaped if set to FALSE. To illustrate the @@ -609,7 +722,7 @@ You can also pass an associative array to this function:: 'title' => $title, 'status' => $status ); - + $this->db->set($array); $this->db->insert('mytable'); @@ -622,7 +735,7 @@ Or an object:: var $date = 'My Date'; } */ - + $object = new Myclass; $this->db->set($object); $this->db->insert('mytable'); @@ -644,7 +757,7 @@ is an example using an array:: 'name' => $name, 'date' => $date ); - + $this->db->where('id', $id); $this->db->update('mytable', $data); // Produces: // UPDATE mytable // SET title = '{$title}', name = '{$name}', date = '{$date}' // WHERE id = $id @@ -658,7 +771,7 @@ Or you can supply an object:: var $date = 'My Date'; } */ - + $object = new Myclass; $this->db->where('id', $id); $this->db->update('mytable', $object); @@ -699,14 +812,14 @@ Here is an example using an array:: ) ); - $this->db->update_batch('mytable', $data, 'title'); + $this->db->update_batch('mytable', $data, 'title'); - // Produces: + // Produces: // UPDATE `mytable` SET `name` = CASE // WHEN `title` = 'My title' THEN 'My Name 2' // WHEN `title` = 'Another title' THEN 'Another Name 2' // ELSE `name` END, - // `date` = CASE + // `date` = CASE // WHEN `title` = 'My title' THEN 'My date 2' // WHEN `title` = 'Another title' THEN 'Another date 2' // ELSE `date` END @@ -717,6 +830,14 @@ array of values, the third parameter is the where key. .. note:: All values are escaped automatically producing safer queries. +$this->db->get_compiled_update() +================================ + +This works exactly the same way as ``$this->db->get_compiled_insert()`` except +that it produces an UPDATE SQL string instead of an INSERT SQL string. + +For more information view documentation for `$this->db->get_compiled_insert()`_. + ************* Deleting Data @@ -737,7 +858,7 @@ the data to the second parameter of the function:: $this->db->where('id', $id); $this->db->delete('mytable'); - + // Produces: // DELETE FROM mytable // WHERE id = $id @@ -762,7 +883,7 @@ $this->db->empty_table() Generates a delete SQL string and runs the query.:: - $this->db->empty_table('mytable'); // Produces // DELETE FROM mytable + $this->db->empty_table('mytable'); // Produces: DELETE FROM mytable $this->db->truncate() @@ -773,18 +894,25 @@ Generates a truncate SQL string and runs the query. :: $this->db->from('mytable'); - $this->db->truncate(); - - // or - + $this->db->truncate(); + + // or + $this->db->truncate('mytable'); - + // Produce: - // TRUNCATE mytable + // TRUNCATE mytable .. note:: If the TRUNCATE command isn't available, truncate() will execute as "DELETE FROM table". +$this->db->get_compiled_delete() +================================ +This works exactly the same way as ``$this->db->get_compiled_insert()`` except +that it produces a DELETE SQL string instead of an INSERT SQL string. + +For more information view documentation for `$this->db->get_compiled_insert()`_. + *************** Method Chaining *************** @@ -797,8 +925,6 @@ multiple functions. Consider this example:: ->limit(10, 20) ->get('mytable'); -.. note:: Method chaining only works with PHP 5. - .. _ar-caching: ********************* @@ -839,11 +965,11 @@ Here's a usage example:: $this->db->stop_cache(); $this->db->get('tablename'); //Generates: SELECT `field1` FROM (`tablename`) - + $this->db->select('field2'); $this->db->get('tablename'); //Generates: SELECT `field1`, `field2` FROM (`tablename`) - + $this->db->flush_cache(); $this->db->select('field2'); $this->db->get('tablename'); @@ -854,3 +980,29 @@ Here's a usage example:: where, like, group_by, having, order_by, set +$this->db->reset_query() +======================== + +Resetting Active Record allows you to start fresh with your query without +executing it first using a method like $this->db->get() or $this->db->insert(). +Just like the methods that execute a query, this will *not* reset items you've +cached using `Active Record Caching`_. + +This is useful in situations where you are using Active Record to generate SQL +(ex. ``$this->db->get_compiled_select()``) but then choose to, for instance, +run the query:: + + // Note that the second parameter of the get_compiled_select method is FALSE + $sql = $this->db->select(array('field1','field2')) + ->where('field3',5) + ->get_compiled_select('mytable', FALSE); + + // ... + // Do something crazy with the SQL code... like add it to a cron script for + // later execution or something... + // ... + + $data = $this->db->get()->result_array(); + + // Would execute and return an array of results of the following query: + // SELECT field1, field1 from mytable where field3 = 5; diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index 687f0d920..040e7e33f 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -28,6 +28,52 @@ prototype:: $db['default']['autoinit'] = TRUE; $db['default']['stricton'] = FALSE; +If you use PDO as your dbdriver, you can specify the full DSN string describe a connection to the database like this:: + + $db['default']['dsn'] = 'pgsql:host=localhost;port=5432;dbname=database_name'; + +You can also specify failovers for the situation when the main connection cannot connect for some reason. +These failovers can be specified by setting the failover for a connection like this:: + + $db['default']['failover'] = array( + array( + 'hostname' => 'localhost1', + 'username' => '', + 'password' => '', + 'database' => '', + 'dbdriver' => 'mysql', + 'dbprefix' => '', + 'pconnect' => TRUE, + 'db_debug' => TRUE, + 'cache_on' => FALSE, + 'cachedir' => '', + 'char_set' => 'utf8', + 'dbcollat' => 'utf8_general_ci', + 'swap_pre' => '', + 'autoinit' => TRUE, + 'stricton' => FALSE + ), + array( + 'hostname' => 'localhost2', + 'username' => '', + 'password' => '', + 'database' => '', + 'dbdriver' => 'mysql', + 'dbprefix' => '', + 'pconnect' => TRUE, + 'db_debug' => TRUE, + 'cache_on' => FALSE, + 'cachedir' => '', + 'char_set' => 'utf8', + 'dbcollat' => 'utf8_general_ci', + 'swap_pre' => '', + 'autoinit' => TRUE, + 'stricton' => FALSE + ) + ); + +You can specify as many failovers as you like. + The reason we use a multi-dimensional array rather than a more simple one is to permit you to optionally store multiple sets of connection values. If, for example, you run multiple environments (development, @@ -116,6 +162,7 @@ Explanation of Values: while developing an application. **port** The database port number. To use this value you have to add a line to the database config array. :: + $db['default']['port'] = 5432; ====================== ================================================================================================== diff --git a/user_guide_src/source/database/connecting.rst b/user_guide_src/source/database/connecting.rst index 64adc3047..a834cc0f7 100644 --- a/user_guide_src/source/database/connecting.rst +++ b/user_guide_src/source/database/connecting.rst @@ -57,7 +57,19 @@ file. To connect manually to a desired database you can pass an array of values:: - $config['hostname'] = "localhost"; $config['username'] = "myusername"; $config['password'] = "mypassword"; $config['database'] = "mydatabase"; $config['dbdriver'] = "mysql"; $config['dbprefix'] = ""; $config['pconnect'] = FALSE; $config['db_debug'] = TRUE; $config['cache_on'] = FALSE; $config['cachedir'] = ""; $config['char_set'] = "utf8"; $config['dbcollat'] = "utf8_general_ci"; $this->load->database($config); + $config['hostname'] = "localhost"; + $config['username'] = "myusername"; + $config['password'] = "mypassword"; + $config['database'] = "mydatabase"; + $config['dbdriver'] = "mysql"; + $config['dbprefix'] = ""; + $config['pconnect'] = FALSE; + $config['db_debug'] = TRUE; + $config['cache_on'] = FALSE; + $config['cachedir'] = ""; + $config['char_set'] = "utf8"; + $config['dbcollat'] = "utf8_general_ci"; + $this->load->database($config); For information on each of these values please see the :doc:`configuration page <configuration>`. @@ -68,14 +80,16 @@ page <configuration>`. Or you can submit your database values as a Data Source Name. DSNs must have this prototype:: - $dsn = 'dbdriver://username:password@hostname/database'; $this->load->database($dsn); + $dsn = 'dbdriver://username:password@hostname/database'; + $this->load->database($dsn); To override default config values when connecting with a DSN string, add the config variables as a query string. :: - $dsn = 'dbdriver://username:password@hostname/database?char_set=utf8&dbcollat=utf8_general_ci&cache_on=true&cachedir=/path/to/cache'; $this->load->database($dsn); + $dsn = 'dbdriver://username:password@hostname/database?char_set=utf8&dbcollat=utf8_general_ci&cache_on=true&cachedir=/path/to/cache'; + $this->load->database($dsn); Connecting to Multiple Databases ================================ @@ -83,7 +97,8 @@ Connecting to Multiple Databases If you need to connect to more than one database simultaneously you can do so as follows:: - $DB1 = $this->load->database('group_one', TRUE); $DB2 = $this->load->database('group_two', TRUE); + $DB1 = $this->load->database('group_one', TRUE); + $DB2 = $this->load->database('group_two', TRUE); Note: Change the words "group_one" and "group_two" to the specific group names you are connecting to (or you can pass the connection values diff --git a/user_guide_src/source/database/index.rst b/user_guide_src/source/database/index.rst index 3b59986be..ab12b7cb7 100644 --- a/user_guide_src/source/database/index.rst +++ b/user_guide_src/source/database/index.rst @@ -6,24 +6,20 @@ CodeIgniter comes with a full-featured and very fast abstracted database class that supports both traditional structures and Active Record patterns. The database functions offer clear, simple syntax. -- :doc:`Quick Start: Usage Examples <examples>` -- :doc:`Database Configuration <configuration>` -- :doc:`Connecting to a Database <connecting>` -- :doc:`Running Queries <queries>` -- :doc:`Generating Query Results <results>` -- :doc:`Query Helper Functions <helpers>` -- :doc:`Active Record Class <active_record>` -- :doc:`Transactions <transactions>` -- :doc:`Table MetaData <table_data>` -- :doc:`Field MetaData <fields>` -- :doc:`Custom Function Calls <call_function>` -- :doc:`Query Caching <caching>` -- :doc:`Database manipulation with Database Forge <forge>` -- :doc:`Database Utilities Class <utilities>` - .. toctree:: - :glob: :titlesonly: - :hidden: - *
\ No newline at end of file + Quick Start: Usage Examples <examples> + Database Configuration <configuration> + Connecting to a Database <connecting> + Running Queries <queries> + Generating Query Results <results> + Query Helper Functions <helpers> + Active Record Class <active_record> + Transactions <transactions> + Table MetaData <table_data> + Field MetaData <fields> + Custom Function Calls <call_function> + Query Caching <caching> + Database Manipulation with Database Forge <forge> + Database Utilities Class <utilities>
\ No newline at end of file diff --git a/user_guide_src/source/general/index.rst b/user_guide_src/source/general/index.rst index ae0d0961c..2162b8140 100644 --- a/user_guide_src/source/general/index.rst +++ b/user_guide_src/source/general/index.rst @@ -1,39 +1,32 @@ -################## -General -################## - - -- :doc:`CodeIgniter URLs <urls>` -- :doc:`Controllers <controllers>` -- :doc:`Reserved Names <reserved_names>` -- :doc:`Views <views>` -- :doc:`Models <models>` -- :doc:`Helpers <helpers>` -- :doc:`Using CodeIgniter Libraries <libraries>` -- :doc:`Creating Your Own Libraries <creating_libraries>` -- :doc:`Using CodeIgniter Drivers <drivers>` -- :doc:`Creating Your Own Drivers <creating_drivers>` -- :doc:`Creating Core Classes <core_classes>` -- :doc:`Creating Ancillary Classes <ancillary_classes>` -- :doc:`Hooks - Extending the Core <hooks>` -- :doc:`Auto-loading Resources <autoloader>` -- :doc:`Common Function <common_functions>` -- :doc:`URI Routing <routing>` -- :doc:`Error Handling <errors>` -- :doc:`Caching <caching>` -- :doc:`Profiling Your Application <profiling>` -- :doc:`Running via the CLI <cli>` -- :doc:`Managing Applications <managing_apps>` -- :doc:`Handling Multiple Environments <environments>` -- :doc:`Alternative PHP Syntax <alternative_php>` -- :doc:`Security <security>` -- :doc:`PHP Style Guide <styleguide>` -- :doc:`Server Requirements <requirements>` -- :doc:`Credits <credits>` +############## +General Topics +############## .. toctree:: - :glob: :titlesonly: - :hidden: - *
\ No newline at end of file + urls + controllers + reserved_names + views + models + Helpers <helpers> + libraries + creating_libraries + drivers + creating_drivers + core_classes + ancillary_classes + hooks + autoloader + common_functions + routing + errors + Caching <caching> + profiling + cli + managing_apps + environments + alternative_php + security + PHP Style Guide <styleguide> diff --git a/user_guide_src/source/general/styleguide.rst b/user_guide_src/source/general/styleguide.rst index 0373fc791..d8bdd0531 100644 --- a/user_guide_src/source/general/styleguide.rst +++ b/user_guide_src/source/general/styleguide.rst @@ -1,6 +1,7 @@ -######################## -General Style and Syntax -######################## +############### +PHP Style Guide +############### + The following page describes the use of coding rules adhered to when developing CodeIgniter. @@ -440,6 +441,13 @@ same level as the control statement that "owns" them. // ... } } + + try { + // ... + } + catch() { + // ... + } **CORRECT**:: @@ -469,6 +477,15 @@ same level as the control statement that "owns" them. // ... } } + + try + { + // ... + } + catch() + { + // ... + } Bracket and Parenthetic Spacing =============================== diff --git a/user_guide_src/source/general/urls.rst b/user_guide_src/source/general/urls.rst index 211537675..6b390b559 100644 --- a/user_guide_src/source/general/urls.rst +++ b/user_guide_src/source/general/urls.rst @@ -39,18 +39,22 @@ By default, the **index.php** file will be included in your URLs:: example.com/index.php/news/article/my_article -You can easily remove this file by using a .htaccess file with some -simple rules. Here is an example of such a file, using the "negative" -method in which everything is redirected except the specified items: +If your Apache server has mod_rewrite enabled, you can easily remove this +file by using a .htaccess file with some simple rules. Here is an example +of such a file, using the "negative" method in which everything is redirected +except the specified items: :: - RewriteEngine on - RewriteCond $1 !^(index\.php|images|robots\.txt) - RewriteRule ^(.*)$ /index.php/$1 [L] + RewriteEngine On + RewriteCond %{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_FILENAME} !-d + RewriteRule ^(.*)$ index.php/$1 [L] -In the above example, any HTTP request other than those for index.php, -images, and robots.txt is treated as a request for your index.php file. +In the above example, any HTTP request other than those for existing +directories and existing files is treated as a request for your index.php file. + +.. note:: Note: These specific rules might not work for all server configurations. Adding a URL Suffix =================== diff --git a/user_guide_src/source/helpers/date_helper.rst b/user_guide_src/source/helpers/date_helper.rst index 378ff362b..ad06dd628 100644 --- a/user_guide_src/source/helpers/date_helper.rst +++ b/user_guide_src/source/helpers/date_helper.rst @@ -162,7 +162,8 @@ Example :: - $mysql = '20061124092345'; $unix = mysql_to_unix($mysql); + $mysql = '20061124092345'; + $unix = mysql_to_unix($mysql); unix_to_human() =============== diff --git a/user_guide_src/source/helpers/directory_helper.rst b/user_guide_src/source/helpers/directory_helper.rst index 6c259adb1..fd169886c 100644 --- a/user_guide_src/source/helpers/directory_helper.rst +++ b/user_guide_src/source/helpers/directory_helper.rst @@ -18,15 +18,20 @@ This helper is loaded using the following code The following functions are available: -directory_map('source directory') -================================= +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]]) -Example - -:: + :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/'); @@ -35,23 +40,17 @@ Example 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 - -:: +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) - -:: +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 - -:: +be numerically indexed. Here is an example of a typical array:: Array ( [libraries] => Array diff --git a/user_guide_src/source/helpers/inflector_helper.rst b/user_guide_src/source/helpers/inflector_helper.rst index cf246b9de..cc46a1851 100644 --- a/user_guide_src/source/helpers/inflector_helper.rst +++ b/user_guide_src/source/helpers/inflector_helper.rst @@ -77,3 +77,9 @@ them. Each word is capitalized. Example $word = "my_dog_spot"; echo humanize($word); // Returns "My Dog Spot" +To use dashes instead of underscores + +:: + + $word = "my-dog-spot"; + echo humanize($word, '-'); // Returns "My Dog Spot"
\ 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 28bc2f200..af6cdad57 100644 --- a/user_guide_src/source/helpers/number_helper.rst +++ b/user_guide_src/source/helpers/number_helper.rst @@ -42,4 +42,4 @@ 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//number_lang.php + language file: language/<your_lang>/number_lang.php diff --git a/user_guide_src/source/helpers/string_helper.rst b/user_guide_src/source/helpers/string_helper.rst index b8a69e036..dc70e461a 100644 --- a/user_guide_src/source/helpers/string_helper.rst +++ b/user_guide_src/source/helpers/string_helper.rst @@ -58,7 +58,7 @@ 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_4'); // "file_5" alternator() ============ diff --git a/user_guide_src/source/helpers/text_helper.rst b/user_guide_src/source/helpers/text_helper.rst index e97643275..8cb2d6f96 100644 --- a/user_guide_src/source/helpers/text_helper.rst +++ b/user_guide_src/source/helpers/text_helper.rst @@ -46,6 +46,9 @@ more or less then what you specify. Example 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() =================== @@ -136,6 +139,8 @@ complete words. Example // Would produce: Here is a simple string of text that will help us demonstrate this function +.. _ellipsize: + ellipsize() =========== diff --git a/user_guide_src/source/helpers/url_helper.rst b/user_guide_src/source/helpers/url_helper.rst index c72558705..e6d51b22b 100644 --- a/user_guide_src/source/helpers/url_helper.rst +++ b/user_guide_src/source/helpers/url_helper.rst @@ -284,23 +284,24 @@ redirect() ========== Does a "header redirect" to the URI specified. If you specify the full -site URL that link will be build, but for local links simply providing +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 choose between the -"location" method (default) or the "refresh" method. Location is faster, -but on Windows servers it can sometimes be a problem. 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 second parameter allows you to force a particular redirection +method. The available methods are "location" or "refresh", with location +being faster but less reliable on Windows 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:: if ($logged_in == FALSE) { - redirect('/login/form/', 'refresh'); + redirect('/login/form/'); } // with 301 redirect diff --git a/user_guide_src/source/index.rst b/user_guide_src/source/index.rst index e53182550..6cdeb2442 100644 --- a/user_guide_src/source/index.rst +++ b/user_guide_src/source/index.rst @@ -37,9 +37,13 @@ CodeIgniter is right for you if: * overview/index + general/requirements installation/index general/index libraries/index - database/index helpers/index - documentation/index
\ No newline at end of file + database/index + documentation/index + tutorial/index + general/quick_reference + general/credits
\ No newline at end of file diff --git a/user_guide_src/source/installation/upgrade_200.rst b/user_guide_src/source/installation/upgrade_200.rst index 064e1b534..0bcbd5c99 100644 --- a/user_guide_src/source/installation/upgrade_200.rst +++ b/user_guide_src/source/installation/upgrade_200.rst @@ -5,6 +5,10 @@ Upgrading from 1.7.2 to 2.0.0 Before performing an update you should take your site offline by replacing the index.php file with a static one. +******************* +Update Instructions +******************* + Step 1: Update your CodeIgniter files ===================================== @@ -88,3 +92,51 @@ Step 8: Update your user guide Please replace your local copy of the user guide with the new version, including the image files. + + +************ +Update Notes +************ + +Please refer to the :ref:`2.0.0 Change Log <2.0.0-changelog>` for full +details, but here are some of the larger changes that are more likely to +impact your code: + +- CodeIgniter now requires PHP 5.1.6. +- Scaffolding has been removed. +- The CAPTCHA plugin in now a :doc:`helper </helpers/captcha_helper>`. +- The JavaScript calendar plugin was removed. +- The *system/cache* and *system/logs* directories are now in the application + directory. +- The Validation class has been removed. Please see the + :doc:`Form Validation library </libraries/form_validation>` +- "default" is now a reserved name. +- The xss_clean() function has moved to the :doc:`Security Class + </libraries/security>`. +- do_xss_clean() now returns FALSE if the uploaded file fails XSS checks. +- The :doc:`Session Class </libraries/sessions>` requires now the use of an + encryption key set in the config file. +- The following deprecated Active Record functions have been removed: + ``orwhere``, ``orlike``, ``groupby``, ``orhaving``, ``orderby``, + ``getwhere``. +- ``_drop_database()`` and ``_create_database()`` functions have been removed + from the db utility drivers. +- The ``dohash()`` function of the :doc:`Security helper + </helpers/security_helper>` + has been renamed to ``do_hash()`` for naming consistency. + +The config folder +================= + +The following files have been changed: + +- config.php +- database.php +- mimes.php +- routes.php +- user_agents.php + +The following files have been added: + +- foreign_chars.php +- profiler.php diff --git a/user_guide_src/source/installation/upgrade_300.rst b/user_guide_src/source/installation/upgrade_300.rst new file mode 100644 index 000000000..4c594ab17 --- /dev/null +++ b/user_guide_src/source/installation/upgrade_300.rst @@ -0,0 +1,33 @@ +############################# +Upgrading from 2.1.0 to 3.0.0 +############################# + +.. note:: These upgrade notes are for a version that is yet to be released. + + +Before performing an update you should take your site offline by +replacing the index.php file with a static one. + +Step 1: Update your CodeIgniter files +===================================== + +Replace all files and directories in your "system" folder and replace +your index.php file. If any modifications were made to your index.php +they will need to be made fresh in this new one. + +.. note:: If you have any custom developed files in these folders please + make copies of them first. + +Step 2: Change References to the SHA Library +============================================ + +The previously deprecated SHA library has been removed in CodeIgniter 3.0. +Alter your code to use the native `sha1()` PHP function to generate a sha1 hash. + +Additionally, the `sha1()` method in the :doc:`Encryption Library <../libraries/encryption>` has been removed. + +Step 3: Remove $autoload['core'] from your config/autoload.php +============================================================== + +Use of the `$autoload['core']` config array has been deprecated as of CodeIgniter 1.4.1 and is now removed. +Move any entries that you might have listed there to `$autoload['libraries']` instead. diff --git a/user_guide_src/source/libraries/cart.rst b/user_guide_src/source/libraries/cart.rst index 850d7e9a8..6594b3b9a 100644 --- a/user_guide_src/source/libraries/cart.rst +++ b/user_guide_src/source/libraries/cart.rst @@ -256,23 +256,31 @@ $this->cart->update(); Permits you to update items in the shopping cart, as outlined above. +$this->cart->remove(rowid); +*************************** + +Allows you to remove an item from the shopping cart by passing it the rowid. + $this->cart->total(); ********************* Displays the total amount in the cart. $this->cart->total_items(); -**************************** +*************************** Displays the total number of items in the cart. -$this->cart->contents(); -************************ +$this->cart->contents(boolean); +******************************* -Returns an array containing everything in the cart. +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. $this->cart->has_options(rowid); -********************************* +******************************** Returns TRUE (boolean) if a particular row in the cart contains options. This function is designed to be used in a loop with @@ -280,7 +288,7 @@ $this->cart->contents(), since you must pass the rowid to this function, as shown in the Displaying the Cart example above. $this->cart->product_options(rowid); -************************************* +************************************ 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 diff --git a/user_guide_src/source/libraries/email.rst b/user_guide_src/source/libraries/email.rst index 759899242..27b704dae 100644 --- a/user_guide_src/source/libraries/email.rst +++ b/user_guide_src/source/libraries/email.rst @@ -228,7 +228,11 @@ use the function multiple times. For example:: $this->email->attach('/path/to/photo2.jpg'); $this->email->attach('/path/to/photo3.jpg'); - $this->email->send(); +If you'd like to change the disposition or add a custom file name, you can use the second and third paramaters. To use the default disposition (attachment), leave the second parameter blank. Here's an example:: + + $this->email->attach('/path/to/photo1.jpg', 'inline'); + $this->email->attach('/path/to/photo1.jpg', '', 'birthday.jpg'); + $this->email->print_debugger() ------------------------------- diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst index 80b45e4d7..28bdca203 100644 --- a/user_guide_src/source/libraries/encryption.rst +++ b/user_guide_src/source/libraries/encryption.rst @@ -126,21 +126,6 @@ Example:: Please visit php.net for a list of `available modes <http://php.net/mcrypt>`_. -$this->encrypt->sha1(); -======================= - -SHA1 encoding function. Provide a string and it will return a 160 bit -one way hash. Note: SHA1, just like MD5 is non-decodable. Example:: - - $hash = $this->encrypt->sha1('Some string'); - -Many PHP installations have SHA1 support by default so if all you need -is to encode a hash it's simpler to use the native function:: - - $hash = sha1('Some string'); - -If your server does not support SHA1 you can use the provided function. - $this->encrypt->encode_from_legacy($orig_data, $legacy_mode = MCRYPT_MODE_ECB, $key = ''); ========================================================================================== diff --git a/user_guide_src/source/libraries/image_lib.rst b/user_guide_src/source/libraries/image_lib.rst index 300cbef31..ed6575c62 100644 --- a/user_guide_src/source/libraries/image_lib.rst +++ b/user_guide_src/source/libraries/image_lib.rst @@ -360,7 +360,7 @@ Preference Default Value Options Description image headers. **quality** 90% 1 - 100% Sets the quality of the image. The higher the quality the larger the file size. -**padding** None A number The amount of padding, set in pixels, that will be applied to the +**wm_padding** None A number The amount of padding, set in pixels, that will be applied to the watermark to set it away from the edge of your images. **wm_vrt_alignment** bottom top, middle, bottom Sets the vertical alignment for the watermark image. **wm_hor_alignment** center left, center, right Sets the horizontal alignment for the watermark image. @@ -390,13 +390,11 @@ Preference Default Value Options Description **wm_font_size** 16 None The size of the text. Note: If you are not using the True Type option above, the number is set using a range of 1 - 5. Otherwise, you can use any valid pixel size for the font you're using. -**wm_font_color** ffffff None The font color, specified in hex. Note, you must use the full 6 - character hex value (ie, 993300), rather than the three character - abbreviated version (ie fff). +**wm_font_color** ffffff None The font color, specified in hex. Both the full 6-length (ie, 993300) and + the short three character abbreviated version (ie, fff) are supported. **wm_shadow_color** None None The color of the drop shadow, specified in hex. If you leave this blank - a drop shadow will not be used. Note, you must use the full 6 character - hex value (ie, 993300), rather than the three character abbreviated - version (ie fff). + a drop shadow will not be used. Both the full 6-length (ie, 993300) and + the short three character abbreviated version (ie, fff) are supported. **wm_shadow_distance** 3 None The distance (in pixels) from the font that the drop shadow should appear. ======================= =================== =================== ========================================================================== diff --git a/user_guide_src/source/libraries/loader.rst b/user_guide_src/source/libraries/loader.rst index bbe2ed530..2090404bf 100644 --- a/user_guide_src/source/libraries/loader.rst +++ b/user_guide_src/source/libraries/loader.rst @@ -165,6 +165,12 @@ This function 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->get_vars() +=========================== + +This function retrieves all variables available to +your views. + $this->load->helper('file_name') ================================= diff --git a/user_guide_src/source/libraries/migration.rst b/user_guide_src/source/libraries/migration.rst new file mode 100644 index 000000000..5192f1f29 --- /dev/null +++ b/user_guide_src/source/libraries/migration.rst @@ -0,0 +1,5 @@ +################ +Migrations Class +################ + +Coming soon.
\ 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 8ee0c6e77..e7d25555f 100644 --- a/user_guide_src/source/libraries/security.rst +++ b/user_guide_src/source/libraries/security.rst @@ -85,6 +85,10 @@ If you use the :doc:`form helper <../helpers/form_helper>` the form_open() function will automatically insert a hidden csrf field in your forms. +Tokens may be either regenerated on every submission (default) or kept the same throughout the life of the CSRF cookie. The default regeneration of tokens provides stricter security but may result in usability concerns as other tokens become invalid (back/forward navigation, multiple tabs/windows, asynchronous actions, etc). You may alter this behavior by editing the following config parameter:: + + $config['csrf_regeneration'] = TRUE; + Select URIs can be whitelisted from csrf protection (for example API endpoints expecting externally POSTed content). You can add these URIs by editing the 'csrf_exclude_uris' config parameter:: diff --git a/user_guide_src/source/license.rst b/user_guide_src/source/license.rst index bf689a03a..17179a95c 100644 --- a/user_guide_src/source/license.rst +++ b/user_guide_src/source/license.rst @@ -1,62 +1,245 @@ -############################# -CodeIgniter License Agreement -############################# - -Copyright (c) 2008 - 2011, EllisLab, Inc. -All rights reserved. - -This license is a legal agreement between you and EllisLab Inc. for the -use of CodeIgniter Software (the "Software"). By obtaining the Software -you agree to comply with the terms and conditions of this license. - -Permitted Use -============= - -You are permitted to use, copy, modify, and distribute the Software and -its documentation, with or without modification, for any purpose, -provided that the following conditions are met: - -#. A copy of this license agreement must be included with the - distribution. -#. Redistributions of source code must retain the above copyright notice - in all source code files. -#. Redistributions in binary form must reproduce the above copyright - notice in the documentation and/or other materials provided with the - distribution. -#. Any files that have been modified must carry notices stating the - nature of the change and the names of those who changed them. -#. Products derived from the Software must include an acknowledgment - that they are derived from CodeIgniter in their documentation and/or - other materials provided with the distribution. -#. Products derived from the Software may not be called "CodeIgniter", - nor may "CodeIgniter" appear in their name, without prior written - permission from EllisLab, Inc. - -Indemnity -========= - -You agree to indemnify and hold harmless the authors of the Software and -any contributors for any direct, indirect, incidental, or consequential -third-party claims, actions or suits, as well as any related expenses, -liabilities, damages, settlements or fees arising from your use or -misuse of the Software, or a violation of any terms of this license. - -Disclaimer of Warranty -====================== - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF -QUALITY, PERFORMANCE, NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR -A PARTICULAR PURPOSE. - -Limitations of Liability -======================== - -YOU ASSUME ALL RISK ASSOCIATED WITH THE INSTALLATION AND USE OF THE -SOFTWARE. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS OF THE -SOFTWARE BE LIABLE FOR CLAIMS, DAMAGES OR OTHER LIABILITY ARISING FROM, -OUT OF, OR IN CONNECTION WITH THE SOFTWARE. LICENSE HOLDERS ARE SOLELY -RESPONSIBLE FOR DETERMINING THE APPROPRIATENESS OF USE AND ASSUME ALL -RISKS ASSOCIATED WITH ITS USE, INCLUDING BUT NOT LIMITED TO THE RISKS OF -PROGRAM ERRORS, DAMAGE TO EQUIPMENT, LOSS OF DATA OR SOFTWARE PROGRAMS, -OR UNAVAILABILITY OR INTERRUPTION OF OPERATIONS. +################################### +Open Software License ("OSL") v 3.0 +################################### + +This Open Software License (the "License") applies to any original work of +authorship (the "Original Work") whose owner (the "Licensor") has placed the +following licensing notice adjacent to the copyright notice for the Original +Work: + +*Licensed under the Open Software License version 3.0* + + +***************************** +1) Grant of Copyright License +***************************** + +Licensor grants You a worldwide, royalty-free, non-exclusive, sublicensable +license, for the duration of the copyright, to do the following: + + *a)* to reproduce the Original Work in copies, either alone or as part of + a collective work; + + *b)* to translate, adapt, alter, transform, modify, or arrange the + Original Work, thereby creating derivative works ("Derivative Works") + based upon the Original Work; + + *c)* to distribute or communicate copies of the Original Work and + Derivative Works to the public, *with the proviso that copies of Original + Work or Derivative Works that You distribute or communicate shall be + licensed under this Open Software License*; + + *d)* to perform the Original Work publicly; and + + *e)* to display the Original Work publicly. + + +************************** +2) Grant of Patent License +************************** + +Licensor grants You a worldwide, royalty-free, non-exclusive, sublicensable +license, under patent claims owned or controlled by the Licensor that are +embodied in the Original Work as furnished by the Licensor, for the duration +of the patents, to make, use, sell, offer for sale, have made, and import the +Original Work and Derivative Works. + + +******************************* +3) Grant of Source Code License +******************************* + +The term "Source Code" means the preferred form of the Original Work for +making modifications to it and all available documentation describing how to +modify the Original Work. Licensor agrees to provide a machine-readable copy +of the Source Code of the Original Work along with each copy of the Original +Work that Licensor distributes. Licensor reserves the right to satisfy this +obligation by placing a machine-readable copy of the Source Code in an +information repository reasonably calculated to permit inexpensive and +convenient access by You for as long as Licensor continues to distribute the +Original Work. + + +******************************** +4) Exclusions From License Grant +******************************** + +Neither the names of Licensor, nor the names of any contributors to the +Original Work, nor any of their trademarks or service marks, may be used to +endorse or promote products derived from this Original Work without express +prior permission of the Licensor. Except as expressly stated herein, nothing +in this License grants any license to Licensor's trademarks, copyrights, +patents, trade secrets or any other intellectual property. No patent license +is granted to make, use, sell, offer for sale, have made, or import +embodiments of any patent claims other than the licensed claims defined in +Section 2) No license is granted to the trademarks of Licensor even if such +marks are included in the Original Work. Nothing in this License shall be +interpreted to prohibit Licensor from licensing under terms different from +this License any Original Work that Licensor otherwise would have a right to +license. + + +********************** +5) External Deployment +********************** + +The term "External Deployment" means the use, distribution, or communication +of the Original Work or Derivative Works in any way such that the Original +Work or Derivative Works may be used by anyone other than You, whether those +works are distributed or communicated to those persons or made available as an +application intended for use over a network. As an express condition for the +grants of license hereunder, You must treat any External Deployment by You of +the Original Work or a Derivative Work as a distribution under section 1(c). + + +********************* +6) Attribution Rights +********************* + +You must retain, in the Source Code of any Derivative Works that You create, +all copyright, patent, or trademark notices from the Source Code of the +Original Work, as well as any notices of licensing and any descriptive text +identified therein as an "Attribution Notice." You must cause the Source Code +for any Derivative Works that You create to carry a prominent Attribution +Notice reasonably calculated to inform recipients that You have modified the +Original Work. + + +**************************************************** +7) Warranty of Provenance and Disclaimer of Warranty +**************************************************** + +Licensor warrants that the copyright in and to the Original Work and the +patent rights granted herein by Licensor are owned by the Licensor or are +sublicensed to You under the terms of this License with the permission of the +contributor(s) of those copyrights and patent rights. Except as expressly +stated in the immediately preceding sentence, the Original Work is provided +under this License on an "AS IS" BASIS and WITHOUT WARRANTY, either express or +implied, including, without limitation, the warranties of non-infringement, +merchantability or fitness for a particular purpose. THE ENTIRE RISK AS TO THE +QUALITY OF THE ORIGINAL WORK IS WITH YOU. This DISCLAIMER OF WARRANTY +constitutes an essential part of this License. No license to the Original Work +is granted by this License except under this disclaimer. + + +************************** +8) Limitation of Liability +************************** + +Under no circumstances and under no legal theory, whether in tort (including +negligence), contract, or otherwise, shall the Licensor be liable to anyone +for any indirect, special, incidental, or consequential damages of any +character arising as a result of this License or the use of the Original Work +including, without limitation, damages for loss of goodwill, work stoppage, +computer failure or malfunction, or any and all other commercial damages or +losses. This limitation of liability shall not apply to the extent applicable +law prohibits such limitation. + + +***************************** +9) Acceptance and Termination +***************************** + +If, at any time, You expressly assented to this License, that assent indicates +your clear and irrevocable acceptance of this License and all of its terms and +conditions. If You distribute or communicate copies of the Original Work or a +Derivative Work, You must make a reasonable effort under the circumstances to +obtain the express assent of recipients to the terms of this License. This +License conditions your rights to undertake the activities listed in Section +1, including your right to create Derivative Works based upon the Original +Work, and doing so without honoring these terms and conditions is prohibited +by copyright law and international treaty. Nothing in this License is intended +to affect copyright exceptions and limitations (including "fair use" or "fair +dealing"). This License shall terminate immediately and You may no longer +exercise any of the rights granted to You by this License upon your failure to +honor the conditions in Section 1(c). + + +********************************* +10) Termination for Patent Action +********************************* + +This License shall terminate automatically and You may no longer exercise any +of the rights granted to You by this License as of the date You commence an +action, including a cross-claim or counterclaim, against Licensor or any +licensee alleging that the Original Work infringes a patent. This termination +provision shall not apply for an action alleging patent infringement by +combinations of the Original Work with other software or hardware. + + +***************************************** +11) Jurisdiction, Venue and Governing Law +***************************************** + +Any action or suit relating to this License may be brought only in the courts +of a jurisdiction wherein the Licensor resides or in which Licensor conducts +its primary business, and under the laws of that jurisdiction excluding its +conflict-of-law provisions. The application of the United Nations Convention +on Contracts for the International Sale of Goods is expressly excluded. Any +use of the Original Work outside the scope of this License or after its +termination shall be subject to the requirements and penalties of copyright or +patent law in the appropriate jurisdiction. This section shall survive the +termination of this License. + + +******************* +12) Attorneys' Fees +******************* + +In any action to enforce the terms of this License or seeking damages relating +thereto, the prevailing party shall be entitled to recover its costs and +expenses, including, without limitation, reasonable attorneys' fees and costs +incurred in connection with such action, including any appeal of such action. +This section shall survive the termination of this License. + + +***************** +13) Miscellaneous +***************** + +If any provision of this License is held to be unenforceable, such provision +shall be reformed only to the extent necessary to make it enforceable. + + +*************************************** +14) Definition of "You" in This License +*************************************** + +"You" throughout this License, whether in upper or lower case, means an +individual or a legal entity exercising rights under, and complying with all +of the terms of, this License. For legal entities, "You" includes any entity +that controls, is controlled by, or is under common control with you. For +purposes of this definition, "control" means (i) the power, direct or +indirect, to cause the direction or management of such entity, whether by +contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the +outstanding shares, or (iii) beneficial ownership of such entity. + + +**************** +15) Right to Use +**************** + +You may use the Original Work in all ways not otherwise restricted or +conditioned by this License or by law, and Licensor promises not to interfere +with or be responsible for such uses by You. + + +******************************** +16) Modification of This License +******************************** + +This License is Copyright © 2005 Lawrence Rosen. Permission is granted to +copy, distribute, or communicate this License without modification. Nothing in +this License permits You to modify this License as applied to the Original +Work or to Derivative Works. However, You may modify the text of this License +and copy, distribute or communicate your modified version (the "Modified +License") and apply it to other original works of authorship subject to the +following conditions: (i) You may not indicate in any way that your Modified +License is the "Open Software License" or "OSL" and you may not use those +names in the name of your Modified License; (ii) You must replace the notice +specified in the first paragraph above with the notice "Licensed under <insert +your license name here>" or with a notice of your own that is not confusingly +similar to the notice in this License; and (iii) You may not claim that your +original works are open source software unless your Modified License has been +approved by Open Source Initiative (OSI) and You comply with its license +review and certification process.
\ No newline at end of file diff --git a/user_guide_src/source/overview/index.rst b/user_guide_src/source/overview/index.rst index d541e796c..dc91f78c4 100644 --- a/user_guide_src/source/overview/index.rst +++ b/user_guide_src/source/overview/index.rst @@ -4,15 +4,13 @@ CodeIgniter Overview The following pages describe the broad concepts behind CodeIgniter: -- :doc:`CodeIgniter at a Glance <at_a_glance>` -- :doc:`Supported Features <features>` -- :doc:`Application Flow Chart <appflow>` -- :doc:`Introduction to the Model-View-Controller <mvc>` -- :doc:`Design and Architectural Goals <goals>` - .. toctree:: - :glob: - :hidden: :titlesonly: - *
\ No newline at end of file + Getting Started <getting_started> + CodeIgniter at a Glance <at_a_glance> + CodeIgniter Cheatsheets <cheatsheets> + Supported Features <features> + Application Flow Chart <appflow> + Model-View-Controller <mvc> + Architectural Goals <goals>
\ No newline at end of file diff --git a/user_guide_src/source/tutorial/conclusion.rst b/user_guide_src/source/tutorial/conclusion.rst new file mode 100644 index 000000000..48fbdcc8a --- /dev/null +++ b/user_guide_src/source/tutorial/conclusion.rst @@ -0,0 +1,26 @@ +########## +Conclusion +########## + +This tutorial did not cover all of the things you might expect of a +full-fledged content management system, but it introduced you to the +more important topics of routing, writing controllers, and models. We +hope this tutorial gave you an insight into some of CodeIgniter's basic +design patterns, which you can expand upon. + +Now that you've completed this tutorial, we recommend you check out the +rest of the documentation. CodeIgniter is often praised because of its +comprehensive documentation. Use this to your advantage and read the +"Introduction" and "General Topics" sections thoroughly. You should read +the class and helper references when needed. + +Every intermediate PHP programmer should be able to get the hang of +CodeIgniter within a few days. + +If you still have questions about the framework or your own CodeIgniter +code, you can: + +- Check out our `forums <http://codeigniter.com/forums>`_ +- Visit our `IRC chatroom <http://codeigniter.com/wiki/IRC>`_ +- Explore the `Wiki <http://codeigniter.com/wiki/>`_ + diff --git a/user_guide_src/source/tutorial/create_news_items.rst b/user_guide_src/source/tutorial/create_news_items.rst new file mode 100644 index 000000000..794b67eed --- /dev/null +++ b/user_guide_src/source/tutorial/create_news_items.rst @@ -0,0 +1,153 @@ +################# +Create news items +################# + +You now know how you can read data from a database using CodeIgniter, but +you haven't written any information to the database yet. In this section +you'll expand your news controller and model created earlier to include +this functionality. + +Create a form +------------- + +To input data into the database you need to create a form where you can +input the information to be stored. This means you'll be needing a form +with two fields, one for the title and one for the text. You'll derive +the slug from our title in the model. Create the new view at +application/views/news/create.php. + +:: + + <h2>Create a news item</h2> + + <?php echo validation_errors(); ?> + + <?php echo form_open('news/create') ?> + + <label for="title">Title</label> + <input type="input" name="title" /><br /> + + <label for="text">Text</label> + <textarea name="text"></textarea><br /> + + <input type="submit" name="submit" value="Create news item" /> + + </form> + +There are only two things here that probably look unfamiliar to you: the +form_open() function and the validation_errors() function. + +The first function is provided by the `form +helper <../helpers/form_helper.html>`_ and renders the form element and +adds extra functionality, like adding a hidden `CSFR prevention +field <../libraries/security.html>`_. The latter is used to report +errors related to form validation. + +Go back to your news controller. You're going to do two things here, +check whether the form was submitted and whether the submitted data +passed the validation rules. You'll use the `form +validation <../libraries/form_validation.html>`_ library to do this. + +:: + + public function create() + { + $this->load->helper('form'); + $this->load->library('form_validation'); + + $data['title'] = 'Create a news item'; + + $this->form_validation->set_rules('title', 'Title', 'required'); + $this->form_validation->set_rules('text', 'text', 'required'); + + if ($this->form_validation->run() === FALSE) + { + $this->load->view('templates/header', $data); + $this->load->view('news/create'); + $this->load->view('templates/footer'); + + } + else + { + $this->news_model->set_news(); + $this->load->view('news/success'); + } + } + +The code above adds a lot of functionality. The first few lines load the +form helper and the form validation library. After that, rules for the +form validation are set. The set\_rules() method takes three arguments; +the name of the input field, the name to be used in error messages, and +the rule. In this case the title and text fields are required. + +CodeIgniter has a powerful form validation library as demonstrated +above. You can read `more about this library +here <../libraries/form_validation.html>`_. + +Continuing down, you can see a condition that checks whether the form +validation ran successfully. If it did not, the form is displayed, if it +was submitted **and** passed all the rules, the model is called. After +this, a view is loaded to display a success message. Create a view at +application/view/news/success.php and write a success message. + +Model +----- + +The only thing that remains is writing a method that writes the data to +the database. You'll use the Active Record class to insert the +information and use the input library to get the posted data. Open up +the model created earlier and add the following: + +:: + + public function set_news() + { + $this->load->helper('url'); + + $slug = url_title($this->input->post('title'), 'dash', TRUE); + + $data = array( + 'title' => $this->input->post('title'), + 'slug' => $slug, + 'text' => $this->input->post('text') + ); + + return $this->db->insert('news', $data); + } + +This new method takes care of inserting the news item into the database. +The third line contains a new function, url\_title(). This function - +provided by the `URL helper <../helpers/url_helper.html>`_ - strips down +the string you pass it, replacing all spaces by dashes (-) and makes +sure everything is in lowercase characters. This leaves you with a nice +slug, perfect for creating URIs. + +Let's continue with preparing the record that is going to be inserted +later, inside the $data array. Each element corresponds with a column in +the database table created earlier. You might notice a new method here, +namely the post() method from the `input +library <../libraries/input.html>`_. This method makes sure the data is +sanitized, protecting you from nasty attacks from others. The input +library is loaded by default. At last, you insert our $data array into +our database. + +Routing +------- + +Before you can start adding news items into your CodeIgniter application +you have to add an extra rule to config/routes.php file. Make sure your +file contains the following. This makes sure CodeIgniter sees 'create' +as a method instead of a news item's slug. + +:: + + $route['news/create'] = 'news/create'; + $route['news/(:any)'] = 'news/view/$1'; + $route['news'] = 'news'; + $route['(:any)'] = 'pages/view/$1'; + $route['default_controller'] = 'pages/view'; + +Now point your browser to your local development environment where you +installed CodeIgniter and add index.php/news/create to the URL. +Congratulations, you just created your first CodeIgniter application! +Add some news and check out the different pages you made. diff --git a/user_guide_src/source/tutorial/index.rst b/user_guide_src/source/tutorial/index.rst new file mode 100644 index 000000000..c959d04d2 --- /dev/null +++ b/user_guide_src/source/tutorial/index.rst @@ -0,0 +1,46 @@ +######## +Tutorial +######## + +This tutorial is intended to introduce you to the CodeIgniter framework +and the basic principles of MVC architecture. It will show you how a +basic CodeIgniter application is constructed in step-by-step fashion. + +In this tutorial, you will be creating a **basic news application**. You +will begin by writing the code that can load static pages. Next, you +will create a news section that reads news items from a database. +Finally, you'll add a form to create news items in the database. + +This tutorial will primarily focus on: + +- Model-View-Controller basics +- Routing basics +- Form validation +- Performing basic database queries using "Active Record" + +The entire tutorial is split up over several pages, each explaining a +small part of the functionality of the CodeIgniter framework. You'll go +through the following pages: + +- Introduction, this page, which gives you an overview of what to + expect. +- `Static pages <static_pages.html>`_, which will teach you the basics + of controllers, views and routing. +- `News section <news_section.html>`_, where you'll start using models + and will be doing some basic database operations. +- `Create news items <create_news_items.html>`_, which will introduce + more advanced database operations and form validation. +- `Conclusion <conclusion.html>`_, which will give you some pointers on + further reading and other resources. + +Enjoy your exploration of the CodeIgniter framework. + +.. toctree:: + :glob: + :hidden: + :titlesonly: + + static_pages + news_section + create_news_items + conclusion
\ No newline at end of file diff --git a/user_guide_src/source/tutorial/news_section.rst b/user_guide_src/source/tutorial/news_section.rst new file mode 100644 index 000000000..38e4214ca --- /dev/null +++ b/user_guide_src/source/tutorial/news_section.rst @@ -0,0 +1,214 @@ +############ +News section +############ + +In the last section, we went over some basic concepts of the framework +by writing a class that includes static pages. We cleaned up the URI by +adding custom routing rules. Now it's time to introduce dynamic content +and start using a database. + +Setting up your model +--------------------- + +Instead of writing database operations right in the controller, queries +should be placed in a model, so they can easily be reused later. Models +are the place where you retrieve, insert, and update information in your +database or other data stores. They represent your data. + +Open up the application/models directory and create a new file called +news_model.php and add the following code. Make sure you've configured +your database properly as described +`here <../database/configuration.html>`_. + +:: + + <?php + class News_model extends CI_Model { + + public function __construct() + { + $this->load->database(); + } + } + +This code looks similar to the controller code that was used earlier. It +creates a new model by extending CI\_Model and loads the database +library. This will make the database class available through the +$this->db object. + +Before querying the database, a database schema has to be created. +Connect to your database and run the SQL command below. Also add some +seed records. + +:: + + CREATE TABLE news ( + id int(11) NOT NULL AUTO_INCREMENT, + title varchar(128) NOT NULL, + slug varchar(128) NOT NULL, + text text NOT NULL, + PRIMARY KEY (id), + KEY slug (slug) + ); + +Now that the database and a model have been set up, you'll need a method +to get all of our posts from our database. To do this, the database +abstraction layer that is included with CodeIgniter — `Active +Record <../database/active_record.html>`_ — is used. This makes it +possible to write your 'queries' once and make them work on `all +supported database systems <../general/requirements.html>`_. Add the +following code to your model. + +:: + + public function get_news($slug = FALSE) + { + if ($slug === FALSE) + { + $query = $this->db->get('news'); + return $query->result_array(); + } + + $query = $this->db->get_where('news', array('slug' => $slug)); + return $query->row_array(); + } + +With this code you can perform two different queries. You can get all +news records, or get a news item by its `slug <#>`_. You might have +noticed that the $slug variable wasn't sanitized before running the +query; Active Record does this for you. + +Display the news +---------------- + +Now that the queries are written, the model should be tied to the views +that are going to display the news items to the user. This could be done +in our pages controller created earlier, but for the sake of clarity, a +new "news" controller is defined. Create the new controller at +application/controllers/news.php. + +:: + + <?php + class News extends CI_Controller { + + public function __construct() + { + parent::__construct(); + $this->load->model('news_model'); + } + + public function index() + { + $data['news'] = $this->news_model->get_news(); + } + + public function view($slug) + { + $data['news'] = $this->news_model->get_news($slug); + } + } + +Looking at the code, you may see some similarity with the files we +created earlier. First, the "\_\_construct" method: it calls the +constructor of its parent class (CI\_Controller) and loads the model, so +it can be used in all other methods in this controller. + +Next, there are two methods to view all news items and one for a +specific news item. You can see that the $slug variable is passed to the +model's method in the second method. The model is using this slug to +identify the news item to be returned. + +Now the data is retrieved by the controller through our model, but +nothing is displayed yet. The next thing to do is passing this data to +the views. + +:: + + public function index() + { + $data['news'] = $this->news_model->get_news(); + $data['title'] = 'News archive'; + + $this->load->view('templates/header', $data); + $this->load->view('news/index', $data); + $this->load->view('templates/footer'); + } + +The code above gets all news records from the model and assigns it to a +variable. The value for the title is also assigned to the $data['title'] +element and all data is passed to the views. You now need to create a +view to render the news items. Create application/views/news/index.php +and add the next piece of code. + +:: + + <?php foreach ($news as $news_item): ?> + + <h2><?php echo $news_item['title'] ?></h2> + <div id="main"> + <?php echo $news_item['text'] ?> + </div> + <p><a href="<?php echo $news_item['slug'] ?>">View article</a></p> + + <?php endforeach ?> + +Here, each news item is looped and displayed to the user. You can see we +wrote our template in PHP mixed with HTML. If you prefer to use a +template language, you can use CodeIgniter's `Template +Parser <../libraries/parser.html>`_ class or a third party parser. + +The news overview page is now done, but a page to display individual +news items is still absent. The model created earlier is made in such +way that it can easily be used for this functionality. You only need to +add some code to the controller and create a new view. Go back to the +news controller and add the following lines to the file. + +:: + + public function view($slug) + { + $data['news_item'] = $this->news_model->get_news($slug); + + if (empty($data['news_item'])) + { + show_404(); + } + + $data['title'] = $data['news_item']['title']; + + $this->load->view('templates/header', $data); + $this->load->view('news/view', $data); + $this->load->view('templates/footer'); + } + +Instead of calling the get\_news() method without a parameter, the $slug +variable is passed, so it will return the specific news item. The only +things left to do is create the corresponding view at +application/views/news/view.php. Put the following code in this file. + +:: + + <?php + echo '<h2>'.$news_item['title'].'</h2>'; + echo $news_item['text']; + +Routing +------- + +Because of the wildcard routing rule created earlier, you need need an +extra route to view the controller that you just made. Modify your +routing file (application/config/routes.php) so it looks as follows. +This makes sure the requests reaches the news controller instead of +going directly to the pages controller. The first line routes URI's with +a slug to the view method in the news controller. + +:: + + $route['news/(:any)'] = 'news/view/$1'; + $route['news'] = 'news'; + $route['(:any)'] = 'pages/view/$1'; + $route['default_controller'] = 'pages/view'; + +Point your browser to your document root, followed by index.php/news and +watch your news page. diff --git a/user_guide_src/source/tutorial/static_pages.rst b/user_guide_src/source/tutorial/static_pages.rst new file mode 100644 index 000000000..708eaeb7b --- /dev/null +++ b/user_guide_src/source/tutorial/static_pages.rst @@ -0,0 +1,170 @@ +############ +Static pages +############ + +**Note:** This tutorial assumes you've downloaded CodeIgniter and +`installed the framework <../installation/index.html>`_ in your +development environment. + +The first thing you're going to do is set up a **controller** to handle +static pages. A controller is simply a class that helps delegate work. +It is the glue of your web application. + +For example, when a call is made to: +``http://example.com/news/latest/10`` We might imagine that there is a +controller named "news". The method being called on news would be +"latest". The news method's job could be to grab 10 news items, and +render them on the page. Very often in MVC, you'll see URL patterns that +match: +``http://example.com/[controller-class]/[controller-method]/[arguments]`` +As URL schemes become more complex, this may change. But for now, this +is all we will need to know. + +Create a file at application/controllers/pages.php with the following +code. + +:: + + <?php + class Pages extends CI_Controller { + + public function view($page = 'home') + { + + } + + } + +You have created a class named "pages", with a view method that accepts +one argument named $page. The pages class is extending the +CI_Controller class. This means that the new pages class can access the +methods and variables defined in the CI_Controller class +(system/core/Controller.php). + +The **controller is what will become the center of every request** to +your web application. In very technical CodeIgniter discussions, it may +be referred to as the *super object*. Like any php class, you refer to +it within your controllers as $this. Referring to $this is how you will +load libraries, views, and generally command the framework. + +Now you've created your first method, it's time to make some basic page +templates. We will be creating two "views" (page templates) that act as +our page footer and header. + +Create the header at application/views/templates/header.php and add the +following code. + +:: + + <html> + <head> + <title>CodeIgniter 2 Tutorial</title> + </head> + <body> + + <h1>CodeIgniter 2 Tutorial</h1> + +The header contains the basic HTML code that you'll want to display +before loading the main view, together with a heading. It will also +output the $title variable, which we'll define later in the controller. +Now create a footer at application/views/templates/footer.php that +includes the following code: + +:: + + <em>© 2012</em> + </body> + <html> + +Adding logic to the controller +------------------------------ + +Earlier you set up a controller with a view() method. The method accepts +one parameter, which is the name of the page to be loaded. The static +page templates will be located in the application/views/pages/ +directory. + +In that directory, create two files named home.php and about.php. Within +those files, type some text − anything you'd like − and save them. If +you like to be particularly un-original, try "Hello World!". + +In order to load those pages, you'll have to check whether the requested +page actually exists: + +:: + + <?php + public function view($page = 'home') + { + + if ( ! file_exists(APPPATH.'/views/pages/'.$page.'.php')) + { + // Whoops, we don't have a page for that! + show_404(); + } + + $data['title'] = ucfirst($page); // Capitalize the first letter + + $this->load->view('templates/header', $data); + $this->load->view('pages/'.$page, $data); + $this->load->view('templates/footer', $data); + + } + +Now, when the page does exist, it is loaded, including the header and +footer, and displayed to the user. If the page doesn't exist, a "404 +Page not found" error is shown. + +The first line in this method checks whether the page actually exists. +PHP's native file\_exists() function is used to check whether the file +is where it's expected to be. show\_404() is a built-in CodeIgniter +function that renders the default error page. + +In the header template, the $title variable was used to customize the +page title. The value of title is defined in this method, but instead of +assigning the value to a variable, it is assigned to the title element +in the $data array. + +The last thing that has to be done is loading the views in the order +they should be displayed. The second parameter in the view() method is +used to pass values to the view. Each value in the $data array is +assigned to a variable with the name of its key. So the value of +$data['title'] in the controller is equivalent to $title in the view. + +Routing +------- + +The controller is now functioning! Point your browser to +[your-site-url]index.php/pages/view to see your page. When you visit +index.php/pages/view/about you'll see the about page, again including +the header and footer. + +Using custom routing rules, you have the power to map any URI to any +controller and method, and break free from the normal convention: +``http://example.com/[controller-class]/[controller-method]/[arguments]`` + +Let's do that. Open the routing file located at +application/config/routes.php and add the following two lines. Remove +all other code that sets any element in the $route array. + +:: + + $route['default_controller'] = 'pages/view'; + $route['(:any)'] = 'pages/view/$1'; + +CodeIgniter reads its routing rules from top to bottom and routes the +request to the first matching rule. Each rule is a regular expression +(left-side) mapped to a controller and method name separated by slashes +(right-side). When a request comes in, CodeIgniter looks for the first +match, and calls the appropriate controller and method, possibly with +arguments. + +More information about routing can be found in the URI Routing +`documentation <../general/routing.html>`_. + +Here, the second rule in the $routes array matches **any** request using +the wildcard string (:any). and passes the parameter to the view() +method of the pages class. + +Now visit index.php/about. Did it get routed correctly to the view() +method in the pages controller? Awesome! |