From 58dfc089bf5b0ca35c2ff244e5bfdff726f9adcd Mon Sep 17 00:00:00 2001 From: Melounek Date: Fri, 29 Jun 2012 08:43:47 +0200 Subject: added parameter for returned-path in Email::from() --- user_guide_src/source/libraries/email.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/email.rst b/user_guide_src/source/libraries/email.rst index f99eb91df..8d2549d11 100644 --- a/user_guide_src/source/libraries/email.rst +++ b/user_guide_src/source/libraries/email.rst @@ -117,6 +117,13 @@ Sets the email address and name of the person sending the email:: $this->email->from('you@example.com', 'Your Name'); +:: + + $this->email->from('you@example.com', 'Your Name', 'returned_emails@example.com'); + +Third parameter is redirect for undelivered emails (may not be configured with +protocol 'smtp'). + $this->email->reply_to() ------------------------- -- cgit v1.2.3-24-g4f1b From 3169f26fe6b5e23d5ab5d791143d1dd51d78f80d Mon Sep 17 00:00:00 2001 From: dchill42 Date: Sat, 11 Aug 2012 20:12:05 -0400 Subject: Updated Loader and Session documentation --- user_guide_src/source/libraries/loader.rst | 71 +++++- user_guide_src/source/libraries/sessions.rst | 338 ++++++++++++++++++++------- 2 files changed, 326 insertions(+), 83 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/loader.rst b/user_guide_src/source/libraries/loader.rst index aadf9740a..5a17629d2 100644 --- a/user_guide_src/source/libraries/loader.rst +++ b/user_guide_src/source/libraries/loader.rst @@ -4,6 +4,7 @@ Loader Class Loader, as the name suggests, is used to load elements. These elements can be libraries (classes) :doc:`View files <../general/views>`, +:doc:`Drivers <../general/drivers>`, :doc:`Helpers <../general/helpers>`, :doc:`Models <../general/models>`, or your own files. @@ -74,6 +75,70 @@ Assigning a Library to a different object name If the third (optional) parameter is blank, the library will usually be assigned to an object with the same name as the library. For example, if +the library is named Calendar, it will be assigned to a variable named +$this->calendar. + +If you prefer to set your own class names you can pass its value to the +third parameter:: + + $this->load->library('calendar', '', 'my_calendar'); + + // Session class is now accessed using: + + $this->my_calendar + +Please take note, when multiple libraries are supplied in an array for +the first parameter, this parameter is discarded. + +$this->load->driver('parent_name', $config, 'object name') +=========================================================== + +This function is used to load driver libraries. Where parent_name is the +name of the parent class you want to load. + +As an example, if you would like to use sessions with CodeIgniter, the first +step is to load the session driver within your controller:: + + $this->load->driver('session'); + +Once loaded, the library will be ready for use, using +$this->session->*some_function*(). + +Driver files must be stored in a subdirectory within the main +"libraries" folder, or within your personal application/libraries +folder. The subdirectory must match the parent class name. Read the +:doc:`Drivers <../general/drivers>` description for details. + +Additionally, multiple driver libraries can be loaded at the same time by +passing an array of drivers to the load function. + +:: + + $this->load->driver(array('session', 'cache')); + +Setting options +--------------- + +The second (optional) parameter allows you to optionally pass +configuration settings. You will typically pass these as an array:: + + $config = array ( + 'sess_driver' => 'cookie', + 'sess_encrypt_cookie' => true, + 'encryption_key' => 'mysecretkey' + ); + + $this->load->driver('session', $config); + +Config options can usually also be set via a config file. Each library +is explained in detail in its own page, so please read the information +regarding each one you would like to use. + +Assigning a Driver to a different object name +---------------------------------------------- + +If the third (optional) parameter is blank, the library will be assigned +to an object with the same name as the parent class. For example, if the library is named Session, it will be assigned to a variable named $this->session. @@ -86,8 +151,8 @@ third parameter:: $this->my_session -Please take note, when multiple libraries are supplied in an array for -the first parameter, this parameter is discarded. +.. note:: Driver libraries may also be loaded with the library() method, + but it is faster to use driver() $this->load->view('file_name', $data, true/false) ================================================== @@ -281,4 +346,4 @@ calling add_package_path(). // Again without the second parameter: $this->load->add_package_path(APPPATH.'my_app', TRUE); $this->load->view('my_app_index'); // Loads - $this->load->view('welcome_message'); // Loads \ No newline at end of file + $this->load->view('welcome_message'); // Loads diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index 5400524a9..7a27a8f34 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -1,29 +1,19 @@ -############# -Session Class -############# +############## +Session Driver +############## The Session class permits you maintain a user's "state" and track their -activity while they browse your site. The Session class stores session -information for each user as serialized (and optionally encrypted) data -in a cookie. It can also store the session data in a database table for -added security, as this permits the session ID in the user's cookie to -be matched against the stored session ID. By default only the cookie is -saved. If you choose to use the database option you'll need to create -the session table as indicated below. - -.. note:: The Session class does **not** utilize native PHP sessions. It - generates its own session data, offering more flexibility for - developers. - -.. note:: Even if you are not using encrypted sessions, you must set - an :doc:`encryption key <./encryption>` in your config file which is used - to aid in preventing session data manipulation. +activity while they browse your site. CodeIgniter offers two default +session drivers: the classic `Cookie Driver`_, and the `Native Driver`_, +which supports usage of the native PHP Session mechanism. In addition, +you may create your own `Custom Drivers`_ to store session data however +you wish, while still taking advantage of the features of the Session class. Initializing a Session ====================== Sessions will typically run globally with each page load, so the session -class must either be :doc:`initialized <../general/libraries>` in your +class must either be :doc:`initialized <../general/drivers>` in your :doc:`controller <../general/controllers>` constructors, or it can be :doc:`auto-loaded <../general/autoloader>` by the system. For the most part the session class will run unattended in the background, so simply @@ -31,22 +21,25 @@ initializing the class will cause it to read, create, and update sessions. To initialize the Session class manually in your controller constructor, -use the $this->load->library function:: +use the $this->load->driver function:: - $this->load->library('session'); + $this->load->driver('session'); Once loaded, the Sessions library object will be available using: $this->session +.. note:: For backward compatibility, the Session class may stil be loaded + using the $this->load->library function, but converting your applications + to use $this->load->driver is strongly recommended. + How do Sessions work? ===================== When a page is loaded, the session class will check to see if valid -session data exists in the user's session cookie. If sessions data does -**not** exist (or if it has expired) a new session will be created and -saved in the cookie. If a session does exist, its information will be -updated and the cookie will be updated. With each update, the -session_id will be regenerated. +session data exists in the user's session. If sessions data does **not** +exist (or if it has expired) a new session will be created and saved. +If a session does exist, its information will be updated. With each update, +the session_id will be regenerated. It's important for you to understand that once initialized, the Session class runs automatically. There is nothing you need to do to cause the @@ -79,19 +72,12 @@ prototype:: 'last_activity' => timestamp ) -If you have the encryption option enabled, the serialized array will be -encrypted before being stored in the cookie, making the data highly -secure and impervious to being read or altered by someone. More info -regarding encryption can be :doc:`found here `, although -the Session class will take care of initializing and encrypting the data -automatically. - -Note: Session cookies are only updated every five minutes by default to -reduce processor load. If you repeatedly reload a page you'll notice -that the "last activity" time only updates if five minutes or more has -passed since the last time the cookie was written. This time is -configurable by changing the $config['sess_time_to_update'] line in -your system/config/config.php file. +.. note:: Sessions are only updated every five minutes by default to + reduce processor load. If you repeatedly reload a page you'll notice + that the "last activity" time only updates if five minutes or more has + passed since the last time the cookie was written. This time is + configurable by changing the $config['sess_time_to_update'] line in + your system/config/config.php file. Retrieving Session Data ======================= @@ -106,7 +92,7 @@ fetch. For example, to fetch the session ID you will do this:: $session_id = $this->session->userdata('session_id'); -.. note:: The function returns FALSE (boolean) if the item you are +.. note:: The function returns NULL if the item you are trying to access does not exist. Adding Custom Session Data @@ -117,7 +103,7 @@ to it and it will be stored in the user's cookie. Why would you want to do this? Here's one example: Let's say a particular user logs into your site. Once authenticated, you -could add their username and email address to the session cookie, making +could add their username and email address to the session, making that data globally available to you without having to run a database query when you need it. @@ -144,11 +130,11 @@ supports this syntax. $this->session->set_userdata('some_name', 'some_value'); +If you want to verify that a userdata value exists, call has_userdata(). -.. note:: Cookies can only hold 4KB of data, so be careful not to exceed - the capacity. The encryption process in particular produces a longer - data string than the original so keep careful track of how much data you - are storing. +:: + + $this->session->has_userdata('some_name'); Retrieving All Session Data =========================== @@ -195,8 +181,8 @@ available for the next server request, and are then automatically cleared. These can be very useful, and are typically used for informational or status messages (for example: "record 2 deleted"). -Note: Flash variables are prefaced with "flash\_" so avoid this prefix -in your own session names. +.. note:: Flash variables are prefaced with "flash\_" so avoid this prefix + in your own session names. To add flashdata:: @@ -222,9 +208,162 @@ additional request, you can do so using the keep_flashdata() function. $this->session->keep_flashdata('item'); +Tempdata +======== + +CodeIgniter also supports "tempdata", or session data with a specific +expiration time. After the value expires, or the session expires or is +deleted, the value is automatically removed. + +To add tempdata:: + + $expire = 300; // Expire in 5 minutes + + $this->session->set_tempdata('item', 'value', $expire); + +You can also pass an array to set_tempdata():: + + $tempdata = array('newuser' => TRUE, 'message' => 'Thanks for joining!'); + + $this->session->set_tempdata($tempdata, '', $expire); + +.. note:: If the expiration is omitted or set to 0, the default expiration of + 5 minutes will be used. + +To read a tempdata variable:: + + $this->session->tempdata('item'); + +If you need to remove a tempdata value before it expires, +use unset_tempdata():: + + $this->session->unset_tempdata('item'); + +Destroying a Session +==================== + +To clear the current session:: + + $this->session->sess_destroy(); + +.. note:: This function should be the last one called, and even flash + variables will no longer be available. If you only want some items + destroyed and not all, use unset_userdata(). + +Session Preferences +=================== + +You'll find the following Session related preferences in your +application/config/config.php file: + +=========================== =============== =========================== ========================================================================== +Preference Default Options Description +=========================== =============== =========================== ========================================================================== +**sess_driver** cookie cookie/native/*custom* The initial session driver to load. +**sess_valid_drivers** cookie, native None Additional valid drivers which may be loaded. +**sess_cookie_name** ci_session None The name you want the session cookie saved as (data for Cookie driver or + session ID for Native driver). +**sess_expiration** 7200 None The number of seconds you would like the session to last. The default + value is 2 hours (7200 seconds). If you would like a non-expiring + session set the value to zero: 0 +**sess_expire_on_close** FALSE TRUE/FALSE (boolean) Whether to cause the session to expire automatically when the browser + window is closed. +**sess_encrypt_cookie** FALSE TRUE/FALSE (boolean) Whether to encrypt the session data (Cookie driver only). +**sess_use_database** FALSE TRUE/FALSE (boolean) Whether to save the session data to a database. You must create the + table before enabling this option (Cookie driver only). +**sess_table_name** ci_sessions Any valid SQL table name The name of the session database table (Cookie driver only). +**sess_time_to_update** 300 Time in seconds This options controls how often the session class will regenerate itself + and create a new session id. +**sess_match_ip** FALSE TRUE/FALSE (boolean) Whether to match the user's IP address when reading the session data. + Note that some ISPs dynamically changes the IP, so if you want a + non-expiring session you will likely set this to FALSE. +**sess_match_useragent** TRUE TRUE/FALSE (boolean) Whether to match the User Agent when reading the session data. +=========================== =============== =========================== ========================================================================== + +In addition to the values above, the cookie and native drivers apply the +following configuration values shared by the :doc:`Input ` and +:doc:`Security ` classes: + +=========================== =============== ========================================================================== +Preference Default Description +=========================== =============== ========================================================================== +**cookie_prefix** '' Set a cookie name prefix in order to avoid name collisions +**cookie_domain** '' The domain for which the session is applicable +**cookie_path** / The path to which the session is applicable +=========================== =============== ========================================================================== + +Session Drivers +=============== + +By default, the `Cookie Driver`_ is loaded when a session is initialized. +However, any valid driver may be selected with the $config['sess_driver'] +line in your config.php file. + +The session driver library comes with the cookie and native drivers +installed, and `Custom Drivers`_ may also be installed by the user. + +Typically, only one driver will be used at a time, but CodeIgniter does +support loading multiple drivers. If a specific valid driver is called, it +will be automatically loaded. Or, an additional driver may be explicitly +loaded by calling load_driver():: + + $this->session->load_driver('native'); + +The Session library keeps track of the most recently selected driver to call +for driver methods. Normally, session class methods are called directly on +the parent class, as illustrated above. However, any methods called through +a specific driver will select that driver before invoking the parent method. + +So, alternation between multiple drivers can be achieved by specifying which +driver to use for each call:: + + $this->session->native->set_userdata('foo', 'bar'); + + $this->session->cookie->userdata('foo'); + + $this->session->native->unset_userdata('foo'); + +Notice in the previous example that the *native* userdata value 'foo' +would be set to 'bar', which would NOT be returned by the call for +the *cookie* userdata 'foo', nor would the *cookie* value be unset by +the call to unset the *native* 'foo' value. The drivers maintain independent +sets of values, regardless of key names. + +A specific driver may also be explicitly selected for use by pursuant +methods with the select_driver() call:: + + $this->session->select_driver('native'); + + $this->session->userdata('item'); // Uses the native driver + +Cookie Driver +------------- + +The Cookie driver stores session information for each user as serialized +(and optionally encrypted) data in a cookie. It can also store the session +data in a database table for added security, as this permits the session ID +in the user's cookie to be matched against the stored session ID. By default +only the cookie is saved. If you choose to use the database option you'll +need to create the session table as indicated below. + +If you have the encryption option enabled, the serialized array will be +encrypted before being stored in the cookie, making the data highly +secure and impervious to being read or altered by someone. More info +regarding encryption can be :doc:`found here `, although +the Session class will take care of initializing and encrypting the data +automatically. + +.. note:: Even if you are not using encrypted sessions, you must set + an :doc:`encryption key <./encryption>` in your config file which is used + to aid in preventing session data manipulation. + +.. note:: Cookies can only hold 4KB of data, so be careful not to exceed + the capacity. The encryption process in particular produces a longer + data string than the original so keep careful track of how much data you + are storing. Saving Session Data to a Database -================================= +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ While the session data array stored in the user's cookie contains a Session ID, unless you store session data in a database there is no way @@ -267,44 +406,83 @@ session class:: $config['sess_table_name'] = 'ci_sessions'; -.. note:: The Session class has built-in garbage collection which clears +.. note:: The Cookie driver has built-in garbage collection which clears out expired sessions so you do not need to write your own routine to do it. -Destroying a Session -==================== +Native Driver +------------- -To clear the current session:: +The Native driver relies on native PHP sessions to store data in the +$_SESSION superglobal array. All stored values continue to be available +through $_SESSION, but flash- and temp- data items carry special prefixes. - $this->session->sess_destroy(); +Custom Drivers +-------------- -.. note:: This function should be the last one called, and even flash - variables will no longer be available. If you only want some items - destroyed and not all, use unset_userdata(). +You may also :doc:`create your own <../general/creating_drivers>` custom +session drivers. A session driver basically manages an array of name/value +pairs with some sort of storage mechanism. -Session Preferences -=================== +To make a new driver, extend CI_Session_driver. Overload the initialize +method and read or create session data. Then implement a save handler to +write changed data to storage (sess_save), a destroy handler to remove +deleted data (sess_destroy), a regenerate handler to make a new session ID, +and an access handler to expose the data (get_userdata). Your initial class +might look like:: -You'll find the following Session related preferences in your -application/config/config.php file: + class CI_Session_custom extends CI_Session_driver { + protected function initialize() + { + // Read existing session data or create a new one + } + + public function sess_save() + { + // Save current data to storage + } + + public function sess_destroy() + { + // Destroy the current session and clean up storage + } + + public function sess_regenerate() + { + // Create new session ID + } + + public function &get_userdata() + { + // Return a reference to your userdata array + } + } + +Notice that get_userdata() returns a reference so the parent library is +accessing the same array the driver object is using. This saves memory +and avoids synchronization issues during usage. + +Put your driver in the libraries/Session/drivers folder anywhere in your +package paths. This includes the application directory, the system directory, +or any path you add with $CI->load->add_package_path(). Your driver must be +named CI_Session_, and your filename must be Session_.php, +preferably also capitalized, such as:: + + CI_Session_foo in libraries/Session/drivers/Session_foo.php + +Then specify the driver by setting 'sess_driver' in your config.php file or as a +parameter when loading the CI_Session object:: + + $config['sess_driver'] = 'foo'; + +OR:: + + $CI->load->driver('session', array('sess_driver' => 'foo')); + +The driver specified by 'sess_driver' is automatically included as a valid +driver. However, if you want to make a custom driver available as an option +without making it the initially loaded driver, set 'sess_valid_drivers' in +your config.php file to an array including your driver name:: + + $config['sess_valid_drivers'] = array('sess_driver'); -=========================== =============== =========================== ========================================================================== -Preference Default Options Description -=========================== =============== =========================== ========================================================================== -**sess_cookie_name** ci_session None The name you want the session cookie saved as. -**sess_expiration** 7200 None The number of seconds you would like the session to last. The default - value is 2 hours (7200 seconds). If you would like a non-expiring - session set the value to zero: 0 -**sess_expire_on_close** FALSE TRUE/FALSE (boolean) Whether to cause the session to expire automatically when the browser - window is closed. -**sess_encrypt_cookie** FALSE TRUE/FALSE (boolean) Whether to encrypt the session data. -**sess_use_database** FALSE TRUE/FALSE (boolean) Whether to save the session data to a database. You must create the - table before enabling this option. -**sess_table_name** ci_sessions Any valid SQL table name The name of the session database table. -**sess_time_to_update** 300 Time in seconds This options controls how often the session class will regenerate itself - and create a new session id. -**sess_match_ip** FALSE TRUE/FALSE (boolean) Whether to match the user's IP address when reading the session data. - Note that some ISPs dynamically changes the IP, so if you want a - non-expiring session you will likely set this to FALSE. -**sess_match_useragent** TRUE TRUE/FALSE (boolean) Whether to match the User Agent when reading the session data. -=========================== =============== =========================== ========================================================================== \ No newline at end of file -- cgit v1.2.3-24-g4f1b From b3816b794592873a4e98187e66745544b463e933 Mon Sep 17 00:00:00 2001 From: dchill42 Date: Mon, 13 Aug 2012 09:47:58 -0400 Subject: Minor doc fixes --- user_guide_src/source/libraries/loader.rst | 2 +- user_guide_src/source/libraries/sessions.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/loader.rst b/user_guide_src/source/libraries/loader.rst index 5a17629d2..33c1bafec 100644 --- a/user_guide_src/source/libraries/loader.rst +++ b/user_guide_src/source/libraries/loader.rst @@ -83,7 +83,7 @@ third parameter:: $this->load->library('calendar', '', 'my_calendar'); - // Session class is now accessed using: + // Calendar class is now accessed using: $this->my_calendar diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index 7a27a8f34..dd9e8cbb4 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -424,12 +424,12 @@ You may also :doc:`create your own <../general/creating_drivers>` custom session drivers. A session driver basically manages an array of name/value pairs with some sort of storage mechanism. -To make a new driver, extend CI_Session_driver. Overload the initialize +To make a new driver, extend CI_Session_driver. Overload the initialize() method and read or create session data. Then implement a save handler to write changed data to storage (sess_save), a destroy handler to remove -deleted data (sess_destroy), a regenerate handler to make a new session ID, -and an access handler to expose the data (get_userdata). Your initial class -might look like:: +deleted data (sess_destroy), a regenerate handler to make a new session ID +(sess_regenerate), and an access handler to expose the data (get_userdata). +Your initial class might look like:: class CI_Session_custom extends CI_Session_driver { protected function initialize() -- cgit v1.2.3-24-g4f1b From 19ac8bc3fc55460660cca618b6cce0ef212e7bdc Mon Sep 17 00:00:00 2001 From: RecoilUK Date: Thu, 23 Aug 2012 20:43:48 +0200 Subject: Update user_guide_src/source/libraries/form_validation.rst --- user_guide_src/source/libraries/form_validation.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/form_validation.rst b/user_guide_src/source/libraries/form_validation.rst index 3bcad7ba6..bc25d8292 100644 --- a/user_guide_src/source/libraries/form_validation.rst +++ b/user_guide_src/source/libraries/form_validation.rst @@ -488,6 +488,15 @@ the name of the function:: $this->form_validation->set_message('username_check') +If you are using an error message that can accept two $s in your error string, +such as .. + + $this->form_validation->set_message('min_length', 'The $s field must contain at least $s characters.'); + +Then you can also use %1$s and %2$s: + + $this->form_validation->set_message('min_length', 'This field must contain at least %2$s characters.'); + You can also override any error message found in the language file. For example, to change the message for the "required" rule you will do this:: -- cgit v1.2.3-24-g4f1b From f3fddf6e0f4b0b0976c433c139326bdcd45d2da0 Mon Sep 17 00:00:00 2001 From: Bo-Yi Wu Date: Fri, 31 Aug 2012 10:10:16 +0800 Subject: fix issue #1719 and update ip address length on captcha helper Signed-off-by: Bo-Yi Wu --- user_guide_src/source/libraries/trackback.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/trackback.rst b/user_guide_src/source/libraries/trackback.rst index 07b2b2177..f9e0df882 100644 --- a/user_guide_src/source/libraries/trackback.rst +++ b/user_guide_src/source/libraries/trackback.rst @@ -114,7 +114,7 @@ store them. Here is a basic prototype for such a table:: excerpt text NOT NULL, blog_name varchar(100) NOT NULL, tb_date int(10) NOT NULL, - ip_address varchar(16) NOT NULL, + ip_address varchar(45) NOT NULL, PRIMARY KEY `tb_id` (`tb_id`), KEY `entry_id` (`entry_id`) ); -- cgit v1.2.3-24-g4f1b From 7c70d10d699d7f7ecd446bf81c9e05de0811f282 Mon Sep 17 00:00:00 2001 From: pickupman Date: Sun, 2 Sep 2012 23:40:49 -0400 Subject: Fix #1741 is_unique duplicated in documentation for Form_validation --- user_guide_src/source/libraries/form_validation.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/form_validation.rst b/user_guide_src/source/libraries/form_validation.rst index 3bcad7ba6..39f787402 100644 --- a/user_guide_src/source/libraries/form_validation.rst +++ b/user_guide_src/source/libraries/form_validation.rst @@ -884,7 +884,6 @@ Rule Parameter Description 0, 1, 2, 3, etc. **is_natural_no_zero** No Returns FALSE if the form element contains anything other than a natural number, but not zero: 1, 2, 3, etc. -**is_unique** Yes Returns FALSE if the form element is not unique in a database table. is_unique[table.field] **valid_email** No Returns FALSE if the form element does not contain a valid email address. **valid_emails** No Returns FALSE if any value provided in a comma separated list is not a valid email. **valid_ip** No Returns FALSE if the supplied IP is not valid. -- cgit v1.2.3-24-g4f1b From 596e48d30d91c69a3a4a0bfbd059e8fa21d88ad1 Mon Sep 17 00:00:00 2001 From: Joe McFrederick Date: Tue, 4 Sep 2012 14:25:47 -0400 Subject: Add documation to user guide for Migrations class --- user_guide_src/source/libraries/migration.rst | 134 +++++++++++++++++++++++++- 1 file changed, 133 insertions(+), 1 deletion(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/migration.rst b/user_guide_src/source/libraries/migration.rst index 5192f1f29..cb7d96a6d 100644 --- a/user_guide_src/source/libraries/migration.rst +++ b/user_guide_src/source/libraries/migration.rst @@ -2,4 +2,136 @@ Migrations Class ################ -Coming soon. \ No newline at end of file +Migrations are a convenient way for you to alter your database in a +structured and organized manner. You could edit fragments of SQL by hand +but you would then be responsible for telling other developers that they +need to go and run them. You would also have to keep track of which changes +need to be run against the production machines next time you deploy. + +The database table **migration** tracks which migrations have already been +run so all you have to do is update your application files and +call **$this->migrate->current()** to work out which migrations should be run. +The current version is found in **config/migration.php**. + +****************** +Create a Migration +****************** + +.. note:: Each Migration is run in numerical order forward or backwards + depending on the method taken. Use a prefix of 3 numbers followed by an + underscore for the filename of your migration. + +This will be the first migration for a new site which has a blog. All +migrations go in the folder **application/migrations/** and have names such +as: **001_add_blog.php**.:: + + defined('BASEPATH') OR exit('No direct script access allowed'); + + class Migration_Add_blog extends CI_Migration { + + public function up() + { + $this->dbforge->add_field(array( + 'blog_id' => array( + 'type' => 'INT', + 'constraint' => 5, + 'unsigned' => TRUE, + 'auto_increment' => TRUE + ), + 'blog_title' => array( + 'type' => 'VARCHAR', + 'constraint' => '100', + ), + 'blog_description' => array( + 'type' => 'TEXT', + 'null' => TRUE, + ), + )); + + $this->dbforge->create_table('blog'); + } + + public function down() + { + $this->dbforge->drop_table('blog'); + } + +Then in **application/config/migration.php** set **$config['migration_version'] = 1;**. + +************* +Usage Example +************* + +In this example some simple code is placed in **application/controllers/migrate.php** +to update the schema.:: + + $this->load->library('migration'); + + if ( ! $this->migration->current()) + { + show_error($this->migration->error_string()); + } + +****************** +Function Reference +****************** + +There are five available methods for the Migration class: + +- $this->migration->current(); +- $this->migration->error_string(); +- $this->migration->find_migrations(); +- $this->migration->latest(); +- $this->migration->version(); + +$this->migration->current() +============================ + +The current migration is whatever is set for **$config['migration_version']** in +**application/config/migration.php**. + +$this->migration->error_string() +================================= + +This returns a string of errors while performing a migration. + +$this->migration->find_migrations() +==================================== + +An array of migration filenames are returned that are found in the **migration_path** +property. + +$this->migration->latest() +=========================== + +This works much the same way as current() but instead of looking for +the **$config['migration_version']** the Migration class will use the very +newest migration found in the filesystem. + +$this->migration->version() +============================ + +Version can be used to roll back changes or step forwards programmatically to +specific versions. It works just like current but ignores **$config['migration_version']**.:: + + $this->load->library('migration'); + + $this->migration->version(5); + +********************* +Migration Preferences +********************* + +The following is a table of all the config options for migrations. + +========================== ====================== ============= ============================================= +Preference Default Options Description +========================== ====================== ============= ============================================= +**migration_enabled** FALSE TRUE / FALSE Enable or disable migrations. +**migration_path** APPPATH.'migrations/' None The path to your migrations folder. +**migration_version** 0 None The current version your database should use. +**migration_table** migrations None The table name for storing the shema + version number. +**migration_auto_latest** FALSE TRUE / FALSE Enable or disable automatically + running migrations. +========================== ====================== ============= ============================================= -- cgit v1.2.3-24-g4f1b From 65bdaf5e2636cb7aa8780826529020ab0bfe9252 Mon Sep 17 00:00:00 2001 From: Bo-Yi Wu Date: Fri, 21 Sep 2012 13:49:09 +0800 Subject: Fixed pagination document error. Signed-off-by: Bo-Yi Wu --- user_guide_src/source/libraries/pagination.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst index 7d750bd23..00554c1c7 100644 --- a/user_guide_src/source/libraries/pagination.rst +++ b/user_guide_src/source/libraries/pagination.rst @@ -80,7 +80,7 @@ The number of "digit" links you would like before and after the selected page number. For example, the number 2 will place two digits on either side, as in the example links at the very top of this page. -$config['use_page_number'] = TRUE; +$config['use_page_numbers'] = TRUE; ================================== By default, the URI segment will use the starting index for the items -- cgit v1.2.3-24-g4f1b From a5e329ff95e0308c07b8db04117f056081997796 Mon Sep 17 00:00:00 2001 From: "W. Kristianto" Date: Sun, 23 Sep 2012 22:34:18 +0700 Subject: Update user_guide_src/source/libraries/loader.rst Remove the second parameter --- user_guide_src/source/libraries/loader.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/loader.rst b/user_guide_src/source/libraries/loader.rst index 33c1bafec..615aba1c2 100644 --- a/user_guide_src/source/libraries/loader.rst +++ b/user_guide_src/source/libraries/loader.rst @@ -344,6 +344,6 @@ calling add_package_path(). $this->load->remove_package_path(APPPATH.'my_app'); // Again without the second parameter: - $this->load->add_package_path(APPPATH.'my_app', TRUE); + $this->load->add_package_path(APPPATH.'my_app'); $this->load->view('my_app_index'); // Loads $this->load->view('welcome_message'); // Loads -- cgit v1.2.3-24-g4f1b From 9438e26671ee1f0b49c8da7a56a0a195788fd5da Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 5 Oct 2012 13:16:27 +0300 Subject: Fix issue #116 + other space/style fixes [ci skip --- user_guide_src/source/libraries/image_lib.rst | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/image_lib.rst b/user_guide_src/source/libraries/image_lib.rst index ed6575c62..dcdccbd92 100644 --- a/user_guide_src/source/libraries/image_lib.rst +++ b/user_guide_src/source/libraries/image_lib.rst @@ -91,9 +91,9 @@ error upon failure, like this:: echo $this->image_lib->display_errors(); } -Note: You can optionally specify the HTML formatting to be applied to -the errors, by submitting the opening/closing tags in the function, like -this:: +.. note:: You can optionally specify the HTML formatting to be applied to + the errors, by submitting the opening/closing tags in the function, + like this:: $this->image_lib->display_errors('

', '

'); @@ -225,8 +225,7 @@ pixels) specifying where to crop, like this:: $config['y_axis'] = '40'; All preferences listed in the table above are available for this -function except these: rotation_angle, width, height, create_thumb, -new_image. +function except these: rotation_angle, create_thumb, new_image. Here's an example showing how you might crop an image:: @@ -243,11 +242,11 @@ Here's an example showing how you might crop an image:: echo $this->image_lib->display_errors(); } -Note: Without a visual interface it is difficult to crop images, so this -function is not very useful unless you intend to build such an -interface. That's exactly what we did using for the photo gallery module -in ExpressionEngine, the CMS we develop. We added a JavaScript UI that -lets the cropping area be selected. +.. note:: Without a visual interface it is difficult to crop images, so this + function is not very useful unless you intend to build such an + interface. That's exactly what we did using for the photo gallery module + in ExpressionEngine, the CMS we develop. We added a JavaScript UI that + lets the cropping area be selected. $this->image_lib->rotate() =========================== @@ -338,8 +337,8 @@ The above example will use a 16 pixel True Type font to create the text bottom/center of the image, 20 pixels from the bottom of the image. .. note:: In order for the image class to be allowed to do any - processing, the image file must have "write" file permissions. For - example, 777. + processing, the image file must have "write" file permissions + For example, 777. Watermarking Preferences ======================== -- cgit v1.2.3-24-g4f1b From 241a69be96de350b18d875304eb1e361b710e148 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 5 Oct 2012 14:58:36 +0300 Subject: [ci skip] Add a note to the user guide regarding issue #1010 --- user_guide_src/source/libraries/form_validation.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/form_validation.rst b/user_guide_src/source/libraries/form_validation.rst index 39f787402..faf221981 100644 --- a/user_guide_src/source/libraries/form_validation.rst +++ b/user_guide_src/source/libraries/form_validation.rst @@ -861,8 +861,9 @@ Rule Parameter Description ========================= ========== ============================================================================================= ======================= **required** No Returns FALSE if the form element is empty. **matches** Yes Returns FALSE if the form element does not match the one in the parameter. matches[form_item] -**is_unique** Yes Returns FALSE if the form element is not unique to the is_unique[table.field] - table and field name in the parameter. is_unique[table.field] +**is_unique** Yes Returns FALSE if the form element is not unique to the table and field name in the is_unique[table.field] + parameter. Note: This rule requires :doc:`Query Builder ` to be + enabled in order to work. **max_length** Yes Returns FALSE if the form element is longer then the parameter value. max_length[12] **exact_length** Yes Returns FALSE if the form element is not exactly the parameter value. exact_length[8] **greater_than** Yes Returns FALSE if the form element is less than or equal to the parameter value or not greater_than[8] -- cgit v1.2.3-24-g4f1b From 6123b61e8ec95ac91f67bfbf442e34021c922319 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 5 Oct 2012 15:54:43 +0300 Subject: Fix issue #1340 [ci skip] --- user_guide_src/source/libraries/file_uploading.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/file_uploading.rst b/user_guide_src/source/libraries/file_uploading.rst index 65cd5c722..1698dcbb9 100644 --- a/user_guide_src/source/libraries/file_uploading.rst +++ b/user_guide_src/source/libraries/file_uploading.rst @@ -197,6 +197,7 @@ Preference Default Value Options Descripti Separate multiple types with a pipe. **file_name** None Desired file name If set CodeIgniter will rename the uploaded file to this name. The extension provided in the file name must also be an allowed file type. + If no extension is provided in the original file_name will be used. **overwrite** FALSE TRUE/FALSE (boolean) If set to true, if a file with the same name as the one you are uploading exists, it will be overwritten. If set to false, a number will be appended to the filename if another with the same name exists. -- cgit v1.2.3-24-g4f1b From ccd01c75f5802e4e4b74bb53414a58d2aa0fd0d8 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 5 Oct 2012 17:12:55 +0300 Subject: Polish changes from #1586 --- user_guide_src/source/libraries/email.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/email.rst b/user_guide_src/source/libraries/email.rst index fc324ffc9..e7ed9f74c 100644 --- a/user_guide_src/source/libraries/email.rst +++ b/user_guide_src/source/libraries/email.rst @@ -117,12 +117,12 @@ Sets the email address and name of the person sending the email:: $this->email->from('you@example.com', 'Your Name'); -:: +You can also set a Return-Path, to help redirect undelivered mail:: $this->email->from('you@example.com', 'Your Name', 'returned_emails@example.com'); -Third parameter is redirect for undelivered emails (may not be configured with -protocol 'smtp'). +.. note:: Return-Path can't be used if you've configured + 'smtp' as your protocol. $this->email->reply_to() ------------------------- -- cgit v1.2.3-24-g4f1b From 9e31f8f1600c6577f46a855eee6a3c7d527aebea Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 5 Oct 2012 17:31:46 +0300 Subject: Fix #1745 --- user_guide_src/source/libraries/form_validation.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/form_validation.rst b/user_guide_src/source/libraries/form_validation.rst index 29e1be032..bc922e69b 100644 --- a/user_guide_src/source/libraries/form_validation.rst +++ b/user_guide_src/source/libraries/form_validation.rst @@ -489,11 +489,13 @@ the name of the function:: $this->form_validation->set_message('username_check') If you are using an error message that can accept two $s in your error string, -such as .. +such as: +:: $this->form_validation->set_message('min_length', 'The $s field must contain at least $s characters.'); Then you can also use %1$s and %2$s: +:: $this->form_validation->set_message('min_length', 'This field must contain at least %2$s characters.'); -- cgit v1.2.3-24-g4f1b From 73766c239318974b7e8ed02ab441794cab7f523f Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 5 Oct 2012 20:32:14 +0300 Subject: [ci skip] Small doc fixes, thanks dchill42 --- user_guide_src/source/libraries/pagination.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst index 00554c1c7..d9d3f5092 100644 --- a/user_guide_src/source/libraries/pagination.rst +++ b/user_guide_src/source/libraries/pagination.rst @@ -81,7 +81,7 @@ page number. For example, the number 2 will place two digits on either side, as in the example links at the very top of this page. $config['use_page_numbers'] = TRUE; -================================== +=================================== By default, the URI segment will use the starting index for the items you are paginating. If you prefer to show the the actual page number, -- cgit v1.2.3-24-g4f1b From 92f00046751d44b3e938d6be1fc49017dd0e0040 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 5 Oct 2012 20:43:36 +0300 Subject: [ci skip] More doc fixes --- user_guide_src/source/libraries/form_validation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/form_validation.rst b/user_guide_src/source/libraries/form_validation.rst index bc922e69b..14305b664 100644 --- a/user_guide_src/source/libraries/form_validation.rst +++ b/user_guide_src/source/libraries/form_validation.rst @@ -873,7 +873,7 @@ Rule Parameter Description **required** No Returns FALSE if the form element is empty. **matches** Yes Returns FALSE if the form element does not match the one in the parameter. matches[form_item] **is_unique** Yes Returns FALSE if the form element is not unique to the table and field name in the is_unique[table.field] - parameter. Note: This rule requires :doc:`Query Builder ` to be + parameter. Note: This rule requires :doc:`Query Builder <../database/query_builder>` to be enabled in order to work. **max_length** Yes Returns FALSE if the form element is longer then the parameter value. max_length[12] **exact_length** Yes Returns FALSE if the form element is not exactly the parameter value. exact_length[8] -- cgit v1.2.3-24-g4f1b From 956631d2b8f0f1173f55134b8465b41d2018edfa Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Sat, 6 Oct 2012 20:43:47 +0300 Subject: [ci skip] Alter some changelog entries --- user_guide_src/source/libraries/output.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/output.rst b/user_guide_src/source/libraries/output.rst index 0472d14cf..3289a241f 100644 --- a/user_guide_src/source/libraries/output.rst +++ b/user_guide_src/source/libraries/output.rst @@ -105,6 +105,9 @@ Permits you to manually set a server status header. Example:: `See here `_ for a full list of headers. +.. note:: This method is an alias for :doc:`Common function <../general/common_funtions.rst>` + ``set_status_header()``. + $this->output->enable_profiler(); ================================== -- cgit v1.2.3-24-g4f1b From 960e616d18c77f463e7c53f666d98b09f5ca9057 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Sun, 7 Oct 2012 15:48:55 +0300 Subject: Fix a typo [ci skip] --- user_guide_src/source/libraries/form_validation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/libraries') diff --git a/user_guide_src/source/libraries/form_validation.rst b/user_guide_src/source/libraries/form_validation.rst index 14305b664..22272dc9b 100644 --- a/user_guide_src/source/libraries/form_validation.rst +++ b/user_guide_src/source/libraries/form_validation.rst @@ -399,7 +399,7 @@ The validation system supports callbacks to your own validation functions. This permits you to extend the validation class to meet your needs. For example, if you need to run a database query to see if the user is choosing a unique username, you can create a callback function -that does that. Let's create a example of this. +that does that. Let's create an example of this. In your controller, change the "username" rule to this:: -- cgit v1.2.3-24-g4f1b