Moving from CodeIgniter 3 to CodeIgniter 4: what changes and how to plan it

Thousands of business applications still run on CodeIgniter 3: admin panels, booking systems, small SaaS products and internal tools written years ago and still earning their keep. The official download page describes CodeIgniter 3 as the legacy version, in maintenance and receiving mostly security updates, with 3.1.13 as the current release. It targets PHP 5.6 and later, while CodeIgniter 4.7 requires PHP 8.2.

The hard part is that CodeIgniter 4 is not an upgrade in the usual sense. The official guide says it plainly: version 4 is a rewrite, it is not backwards compatible, and it is "more appropriate to think of converting your app, rather than upgrading it." There is no automatic tool and no twelve-step checklist.

This article compares the two versions side by side, shows how the most common code patterns translate, and sets out a practical plan for moving an application without stopping feature work. It is written for developers doing the work and for founders deciding whether and when to fund it.

CodeIgniter 3 and 4 compared

Should you migrate, and when?

A conversion costs real time, so be honest about the reasons. The strongest reasons to move are usually these:

• PHP support. Your hosting provider or security policy needs a supported PHP version, and your CodeIgniter 3 code or its libraries do not run cleanly on it.
• Security posture. CodeIgniter 4 keeps application code outside the web root, enables context-aware escaping with esc(), ships CSRF, secure-headers and Content Security Policy support, and has an official authentication library.
• Hiring and maintenance. Developers who know modern PHP expect namespaces, Composer and tests. A framework in maintenance mode becomes harder to staff over time.
• New features. APIs, queues of work and integrations are simpler to build with CI4's REST resources, transformers and Composer packages.

Reasons to wait include an application that is being retired within a year, or one with no tests and no one who understands the business rules. In that second case, spend the first weeks writing characterisation tests or documenting behaviour, not converting code.

Plan the conversion

The official advice is to start with a fresh CodeIgniter 4 project in a new folder and bring your application across component by component. A plan that works for most small and medium applications:

1. Inventory. List controllers, models, libraries, helpers, hooks, config files and third-party packages. Mark anything that uses libraries removed in CI4: Calendaring, FTP, Javascript, Shopping Cart, Trackback, XML-RPC and Zip Encoding, plus the CAPTCHA, Email, Path and Smiley helpers.
2. Create the new project with composer create-project codeigniter4/appstarter, and point it at a copy of the production database.
3. Port configuration first: database, sessions, email and custom config files.
4. Port models, because controllers depend on them.
5. Port one module at a time (controllers, views and routes together), with tests or a manual checklist for each.
6. Replace hooks with events and filters, and authentication with Shield or your chosen library.
7. Run both versions side by side on staging, compare outputs, then switch traffic.

Since both versions can read the same database, a gradual move is possible: some teams route new sections of a site to the CI4 application at the web-server level while older sections stay on CI3. That needs care with sessions and shared login, so plan authentication early.

How common code translates

Controllers

Move files to app/Controllers, add a namespace, extend BaseController instead of CI_Controller, and delete the defined('BASEPATH') line. Return output instead of echoing it.

<?php
// CodeIgniter 3: application/controllers/Helloworld.php
class Helloworld extends CI_Controller
{
    public function index($name)
    {
        echo 'Hello ' . html_escape($name) . '!';
    }
}

<?php
// CodeIgniter 4: app/Controllers/Helloworld.php
namespace App\Controllers;

class Helloworld extends BaseController
{
    public function index($name)
    {
        return 'Hello ' . esc($name) . '!';
    }
}

Sub-folders become namespaces with capitalised names: application/controllers/users/auth/Register.php becomes app/Controllers/Users/Auth/Register.php in App\Controllers\Users\Auth.

Models and database code

Models move to app/Models, extend CodeIgniter\Model, and declare $table and $allowedFields. Instead of $this->load->model('x'), use model(X::class) or new X(). Query Builder method names move to camelCase and you start from a table builder:

<?php
// CodeIgniter 3
$query = $this->db->select('title')
    ->where('id', $id)
    ->limit(10, 20)
    ->get('mytable');
$rows = $query->result_array();

// CodeIgniter 4
$db      = db_connect();
$builder = $db->table('mytable');
$rows    = $builder->select('title')
    ->where('id', $id)
    ->limit(10, 20)
    ->get()
    ->getResultArray();

Other renames you will meet often: affected_rows() to affectedRows(), result() to getResult(), get_where() to getWhere() and select_max() to selectMax(). CI3's database result caching does not exist in CI4; use the Caching driver instead. One trap: limit(0) returns all rows in CI4 unless you change the setting described in the user guide (available since 4.5.0).

Views

Views move to app/Views and mostly keep working. Replace $this->load->view('x', $data) with return view('x', $data);, and $this->load->view('x', $data, TRUE) with $html = view('x', $data);. Replace html_escape() with esc(). For page templates, CI4's View Layouts replace the header-and-footer include pattern common in CI3 projects.

Routing

This is the change that most often breaks a converted site. CI4 disables auto-routing by default, so every URL needs a route. The routing upgrade guide also notes that CI3's (:any) wildcard becomes (:segment), because (:any) in CI4 matches several segments.

<?php
// CodeIgniter 3: application/config/routes.php
$route['product/(:any)'] = 'catalog/product_lookup';

// CodeIgniter 4: app/Config/Routes.php
$routes->get('product/(:segment)', 'Catalog::productLookup');

The guide uses $routes->add() in its examples for backwards compatibility but recommends HTTP-verb routes such as get() and post() for security. If you have hundreds of URLs, you can enable Auto Routing (Legacy) temporarily, but the safer target is Auto Routing (Improved) or explicit routes.

Configuration, libraries, helpers and hooks

• Config: custom files become classes in app/Config extending BaseConfig; $this->config->item('site_name') becomes config('Site')->siteName.
• Libraries: namespace them and instantiate with new or Factories::libraries('X'). To replace a core class, register your own in app/Config/Services.php instead of creating a MY_ class.
• Helpers: largely similar, and they can be autoloaded in app/Config/Autoload.php. String helper functions moved into the Text helper.
• Hooks: become Events::on() calls; pre_controller and post_controller are gone, so use controller filters.
• Redirects: redirect('login/form') becomes return redirect()->to('login/form');. It returns a response object instead of exiting.
• Input and output: CI3's Input class maps to IncomingRequest, and Output maps to the Response object.

Pitfalls that catch most teams

The official upgrade notes contain several small changes that cause confusing bugs if you miss them during a conversion:

• Redirects must be returned. In CI3, redirect() sent headers and stopped the script. In CI4 it returns a RedirectResponse; if you call it without return, execution carries on and the redirect never happens. Cookies and headers set before the redirect are not carried over automatically either, so call withCookies() or withHeaders() when you need them.
• HTTP method names are uppercase. Since 4.5.0, CI4 uses GET and POST rather than the lowercase names CI3 used. Code that compares $this->request->getMethod() to 'post' will silently fail.
• No more BASEPATH. CI4 does not define the constant, so the old defined('BASEPATH') OR exit(...) guard at the top of each file will stop it from running. Remove the line everywhere.
• Removed hook points. pre_controller and post_controller no longer exist; move that logic into controller filters. display_override and cache_override are gone too.
• Errors stop execution. In CI4, any error not ignored by error_reporting() stops the framework, so notices that CI3 logged quietly may now surface as failures. Fix them rather than lowering the error level.
• The testing environment is reserved. CI4 uses testing for PHPUnit only. If you had a CI3 environment named "testing" for a staging server, rename it and create a matching boot file in app/Config/Boot/.

Passwords deserve a separate note. If your CI3 application stores hashes created with PHP's password_hash(), any PHP 8 code can still check them with password_verify(), so users can keep their passwords. If it uses an older custom scheme, plan a rehash-on-login step before you switch, and test it with real (anonymised) accounts on staging.

Effort and risk at a glance

For public sites, export the full list of indexed URLs before you start and test that each one returns the same page, or a 301 redirect, on the new application.

Next steps

Start small: create a CI4 project, connect it to a copy of your database, and port one read-only section end to end. That first module shows the real cost of the conversion far better than any estimate. Once it works, put the remaining modules in a tracked list, port them in order of business value, and keep the CI3 application running until every route has a tested CI4 equivalent. After the switch, upgrades within CodeIgniter 4 are routine: read each release's upgrade notes and run composer update.