Upgrading from 2.2.x to 3.0.x¶

Step 1: Update your CodeIgniter files¶

Replace all files and directories in your system/ directory 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.

Step 2: Update your classes file names¶

Starting with CodeIgniter 3.0, all class filenames (libraries, drivers, controllers and models) must be named in a Ucfirst-like manner or in other words - they must start with a capital letter.

For example, if you have the following library file:

application/libraries/mylibrary.php

... then you'll have to rename it to:

application/libraries/Mylibrary.php

The same goes for driver libraries and extensions and/or overrides of CodeIgniter's own libraries and core classes.

application/libraries/MY_email.php application/core/MY_log.php

The above files should respectively be renamed to the following:

application/libraries/MY_Email.php application/core/MY_Log.php

Controllers:

application/controllers/welcome.php -> application/controllers/Welcome.php

Models:

application/models/misc_model.php -> application/models/Misc_model.php

Please note that this DOES NOT affect directories, configuration files, views, helpers, hooks and anything else - it is only applied to classes.

You must now follow just one simple rule - class names in Ucfirst and everything else in lowercase.

Step 3: Replace config/mimes.php¶

This config file has been updated to contain more user mime-types, please copy it to application/config/mimes.php.

Step 4: 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.

Step 5: Move your Log class overrides or extensions¶

The Log Class is considered as a "core" class and is now located in the system/core/ directory. Therefore, in order for your Log class overrides or extensions to work, you need to move them to application/core/:

application/libraries/Log.php -> application/core/Log.php application/libraries/MY_Log.php -> application/core/MY_Log.php

Step 6: Update your Session library usage¶

The Session Library has been completely re-written in CodeIgniter 3 and now comes with a bunch of new features, but that also means that there are changes that you should make ...

Most notably, the library now uses separate storage drivers instead of always relying on (encrypted) cookies. In fact, cookies as storage have now been removed and you must always use some kind of server-side storage engine, with the file-system being the default option.

The Session Class now utilizes PHP's own mechanisms for building custom session handlers, which also means that your session data is now accessible via the $_SESSION superglobal (though, we've kept the possibility to use it as "userdata", like you've done until now).

A few configuration options have been removed and a few have been added. You should really read the whole Session library manual for the details, but here's a short list of changes that you should make:

• Set your $config['sess_driver'] value

  It will default to 'files', unless you've previously used $config['sess_use_database'], in which case it will be set to 'database'.

• Set a $config['sess_save_path'] value

  For the 'database' driver, a fallback to $config['sess_table_name'] is in place, but otherwise requires you to read the manual for the specific driver of your choice.

• Update your ci_sessions table ('database' driver only)

  The table structure has changed a bit, and more specifically:

  • session_id field is renamed to id
  • user_agent field is dropped
  • user_data field is renamed to data and under MySQL is now of type BLOB
  • last_activity field is renamed to timestamp

  This is accompanied by a slight change in the table indexes too, so please read the manual about the Session Database Driver for more information.

  重要

  Only MySQL and PostgreSQL are officially supported now. Other databases may still work, but due to lack of advisory locking features, they are unsafe for concurrent requests and you should consider using another driver instead.

• Remove $config['sess_match_useragent']

  The user-agent string is input supplied by the user's browser, or in other words: client side input. As such, it is an ineffective feature and hence why it has been removed.

• Remove $config['sess_encrypt_cookie']

  As already noted, the library no longer uses cookies as a storage mechanism, which renders this option useless.

• Remove $config['sess_expire_on_close']

  This option is still usable, but only for backwards compatibility purposes and it should be otherwise removed. The same effect is achieved by setting $config['sess_expiration'] to 0.

• Check "flashdata" for collisions with "userdata"

  Flashdata is now just regular "userdata", only marked for deletion on the next request. In other words: you can't have both "userdata" and "flashdata" with the same name, because it's the same thing.

• Check usage of session metadata

  Previously, you could access the 'session_id', 'ip_address', 'user_agent' and 'last_activity' metadata items as userdata. This is no longer possible, and you should read the notes about Session Metadata if your application relies on those values.

• Check unset_userdata() usage

  Previously, this method used to accept an associative array of 'key' => 'dummy value' pairs for unsetting multiple keys. That however makes no sense and you now have to pass only the keys, as the elements of an array.

  // Old
  $this->session->unset_userdata(array('item' => '', 'item2' => ''));
  
  // New
  $this->session->unset_userdata(array('item', 'item2'));
  

Finally, if you have written a Session extension, you must now move it to the application/libraries/Session/ directory, although chances are that it will now also have to be re-factored.

Step 7: Update your config/database.php¶

Due to 3.0.0's renaming of Active Record to Query Builder, inside your config/database.php, you will need to rename the $active_record variable to $query_builder:

$active_group = 'default';
// $active_record = TRUE;
$query_builder = TRUE;

Step 8: Replace your error templates¶

In CodeIgniter 3.0, the error templates are now considered as views and have been moved to the application/views/errors directory.

Furthermore, we've added support for CLI error templates in plain-text format that unlike HTML, is suitable for the command line. This of course requires another level of separation.

It is safe to move your old templates from application/errors to application/views/errors/html, but you'll have to copy the new application/views/errors/cli directory from the CodeIgniter archive.

Step 9: Update your config/routes.php file¶

(.+)    // matches ANYTHING
(:any)  // matches any character, except for '/'

$route['default_controller'] = 'main';

Step 10: Many functions now return NULL instead of FALSE on missing items¶

Many methods and functions now return NULL instead of FALSE when the required items don't exist:

• Common functions
  • config_item()
• Config Class
  • config->item()
  • config->slash_item()
• Input Class
  • input->get()
  • input->post()
  • input->get_post()
  • input->cookie()
  • input->server()
  • input->input_stream()
  • input->get_request_header()
• Session Class
  • session->userdata()
  • session->flashdata()
• URI Class
  • uri->segment()
  • uri->rsegment()
• Array Helper
  • element()
  • elements()

Step 11: Usage of XSS filtering¶

Many functions in CodeIgniter allow you to use its XSS filtering feature on demand by passing a boolean parameter. The default value of that parameter used to be boolean FALSE, but it is now changed to NULL and it will be dynamically determined by your $config['global_xss_filtering'] value.

If you used to manually pass a boolean value for the $xss_filter parameter or if you've always had $config['global_xss_filtering'] set to FALSE, then this change doesn't concern you.

Otherwise however, please review your usage of the following functions:

• Input Library
  • input->get()
  • input->post()
  • input->get_post()
  • input->cookie()
  • input->server()
  • input->input_stream()
• Cookie Helper get_cookie()

Step 12: Check for potential XSS issues with URIs¶

The URI Library used to automatically convert a certain set of "programmatic characters" to HTML entities when they are encountered in a URI segment.

This was aimed at providing some automatic XSS protection, in addition to the $config['permitted_uri_chars'] setting, but has proven to be problematic and is now removed in CodeIgniter 3.0.

If your application has relied on this feature, you should update it to filter URI segments through $this->security->xss_clean() whenever you output them.

Step 13: Check for usage of the 'xss_clean' Form validation rule¶

A largely unknown rule about XSS cleaning is that it should only be applied to output, as opposed to input data.

We've made that mistake ourselves with our automatic and global XSS cleaning feature (see previous step about XSS above), so now in an effort to discourage that practice, we're also removing 'xss_clean' from the officially supported list of form validation rules.

Because the Form Validation library generally validates input data, the 'xss_clean' rule simply doesn't belong in it.

If you really, really need to apply that rule, you should now also load the Security Helper, which contains xss_clean() as a regular function and therefore can be also used as a validation rule.

Step 14: Update usage of Input Class's get_post() method¶

Previously, the Input Class method get_post() was searching first in POST data, then in GET data. This method has been modified so that it searches in GET then in POST, as its name suggests.

A method has been added, post_get(), which searches in POST then in GET, as get_post() was doing before.

Step 15: Update usage of Directory Helper's directory_map() function¶

In the resulting array, directories now end with a trailing directory separator (i.e. a slash, usually).

Step 16: Update usage of Database Forge's drop_table() method¶

Up until now, drop_table() added an IF EXISTS clause by default or it didn't work at all with some drivers. In CodeIgniter 3.0, the IF EXISTS condition is no longer added by default and has an optional second parameter that allows that instead and is set to FALSE by default.

If your application relies on IF EXISTS, you'll have to change its usage.

// Now produces just DROP TABLE `table_name`
$this->dbforge->drop_table('table_name');

// Produces DROP TABLE IF EXISTS `table_name`
$this->dbforge->drop_table('table_name', TRUE);

Step 17: Change usage of Email library with multiple emails¶

The Email Library will automatically clear the set parameters after successfully sending emails. To override this behaviour, pass FALSE as the first parameter in the send() method:

if ($this->email->send(FALSE))
{
    // Parameters won't be cleared
}

Step 18: Update your Form_validation language lines¶

Two improvements have been made to the Form Validation Library's language files and error messages format:

• Language Library line keys now must be prefixed with form_validation_ in order to avoid collisions:

  // Old
  $lang['rule'] = ...
  
  // New
  $lang['form_validation_rule'] = ...
  

• The error messages format has been changed to use named parameters, to allow more flexibility than what sprintf() offers:

  // Old
  'The %s field does not match the %s field.'
  
  // New
  'The {field} field does not match the {param} field.'
  

Step 19: Make sure your 'base_url' config value is not empty¶

When $config['base_url'] is not set, CodeIgniter tries to automatically detect what your website's base URL is. This is done purely for convenience when you are starting development of a new application.

Auto-detection is never reliable and also has security implications, which is why you should always have it manually configured!

One of the changes in CodeIgniter 3.0.3 is how this auto-detection works, and more specifically it now falls back to the server's IP address instead of the hostname requested by the client. Therefore, if you've ever relied on auto-detection, it will change how your website works now.

In case you need to allow e.g. multiple domains, or both http:// and https:// prefixes to be dynamically used depending on the request, remember that application/config/config.php is still a PHP script, in which you can create this logic with a few lines of code. For example:

$allowed_domains = array('domain1.tld', 'domain2.tld');
$default_domain  = 'domain1.tld';

if (in_array($_SERVER['HTTP_HOST'], $allowed_domains, TRUE))
{
    $domain = $_SERVER['HTTP_HOST'];
}
else
{
    $domain = $default_domain;
}

if ( ! empty($_SERVER['HTTPS']))
{
    $config['base_url'] = 'https://'.$domain;
}
else
{
    $config['base_url'] = 'http://'.$domain;
}

Step 20: Remove usage of (previously) deprecated functionalities¶

In addition to the $autoload['core'] configuration setting, there's a number of other functionalities that have been removed in CodeIgniter 3.0.0:

// Old way
standard_date(); // defaults to standard_date('DATE_RFC822', now());

// Replacement
date(DATE_RFC822, now());

// Old way
standard_date('DATE_ATOM', $time);

// Replacement
date(DATE_ATOM, $time);

$this->session->userdata();

// Old usage:
$field = array(
    'new_field' => array('type' => 'TEXT')
);

$this->dbforge->add_column('table_name', $field, 'another_field');

// New usage:
$field = array(
    'new_field' => array('type' => 'TEXT', 'after' => 'another_field')
);

$this->dbforge->add_column('table_name', $field);

$this->router->directory;
$this->router->class;
$this->router->method;

// Old
$this->input->is_cli_request();

// New
is_cli();

Step 21: Check your usage of Text helper highlight_phrase()¶

The default HTML tag used by Text Helper function highlight_phrase() has been changed from <strong> to the new HTML5 tag <mark>.

Unless you've used your own highlighting tags, this might cause trouble for your visitors who use older web browsers such as Internet Explorer 8. We therefore suggest that you add the following code to your CSS files in order to avoid backwards compatibility with old browsers:

mark {
    background: #ff0;
    color: #000;
};