php CI框架手册

当前版本:CodeIgniter 4.6 · 更新时间:2026年3月 · 查看完整文档 · 常见问题解答

php CI框架手册

欢迎使用 CodeIgniter 4.x 官方开发指南

CodeIgniter 是一个轻量级、快速、安全的 PHP 开发框架,自 2006 年发布以来,已累计被数百万开发者采用,广泛应用于中小型 Web 应用、API 构建、企业内部系统等场景。本手册基于 CodeIgniter 4.6 版本编写,覆盖从环境搭建、核心概念到高级开发技巧的完整知识体系,所有示例均已通过实际运行验证,可直接用于生产环境。

本手册特别针对中国开发者在使用 CI 框架过程中高频遇到的问题进行了深度整理,包括路由规则冲突、模型关联查询性能瓶颈、表单验证规则定制、CSRF 防护配置、多语言支持实现、缓存策略设计等实战痛点,并提供清晰的代码示例与调试技巧。无论您是初学者,还是已有 CI 3.x 经验希望快速升级至 4.x 的开发者,本手册均可作为您日常开发的权威参考。

CodeIgniter 4.x 相较于 3.x 版本,在架构上做了重大重构:全面采用 PSR-4 命名规范、引入 Service Container、支持匿名函数路由、内置数据库组复制支持、增强的 CLI 工具链、更完善的单元测试支持等。这些改进显著提升了框架的可维护性与扩展性,同时也对开发者提出了更高要求。本手册将通过系统化讲解,帮助您掌握新版本的核心特性与最佳实践。

核心优势与适用场景

CodeIgniter 以“小而美”著称,其设计哲学强调简洁性、高性能与低学习曲线。相比 Laravel 等全功能框架,CI 更适合以下场景:

  • 快速原型开发:5 分钟内可启动一个基础项目,适合 MVP 构建与敏捷迭代。
  • 资源受限环境:最小化依赖,无需 Composer(可选),可在低配服务器稳定运行。
  • 遗留系统迁移:3.x 项目升级路径清晰,新旧模块可并存。
  • 微服务架构:轻量级路由与响应机制,易于构建独立服务模块。
  • 教育与学习:文档结构清晰,代码示例简洁,是理解 MVC 模式理想起点。

根据 2025 年 Stack Overflow 开发者调查,CodeIgniter 在“最喜爱框架”榜单中位列第 8,尽管市场份额被 Laravel 部分取代,但其在东南亚、中国台湾及部分企业内部系统中仍保持高活跃度。国内知名项目如“某省政务服务平台”、“某银行内部OA系统”均基于 CI 3.x 构建,稳定性经受住高并发考验。

一、框架架构深度解析

1.1 核心目录结构说明

CodeIgniter 4.x 采用更现代化的目录组织方式,主要目录结构如下:

app/
├── Controllers/       # 控制器类目录
├── Models/           # 数据模型目录
├── Filters/          # 过滤器实现目录
├── Libraries/        # 自定义库目录
├── Config/           # 配置文件目录
├── Views/            # 视图模板目录
├── Entities/         # 实体类(数据转换层)
├── Database/         # 数据库相关扩展
├── Validation/       # 自定义验证规则
└── Messages.php      # 语言消息文件
system/                # 核心框架代码(PSR-4 命名)
writable/              # 可写目录(缓存、日志、上传)
public/                # 入口目录(index.php 所在)
tests/                 # PHPUnit 测试文件

与 CI 3.x 最大区别在于:不再使用 application 目录,所有自定义代码统一置于 app 目录;引入 Service Container(系统服务管理器),通过 Config\Services 类统一实例化核心组件;支持 命名空间,控制器与模型需声明命名空间(如 namespace App\Controllers)。

1.2 请求生命周期详解

当浏览器发起请求时,CI 4 的处理流程如下:

  1. public/index.php 加载 Config\Paths 配置,确定系统路径;
  2. 实例化 CodeIgniter\CodeIgniter 内核对象;
  3. 执行 run() 方法,创建 Request 与 Response 对象;
  4. 通过 Router 解析 URI,匹配路由规则(支持闭包、控制器方法、命名空间);
  5. 执行 Filters(前置过滤器如 CSRF、后置过滤器如响应压缩);
  6. 调用控制器方法,执行业务逻辑;
  7. 返回视图渲染结果或 JSON 数据;
  8. 执行后置事件(如日志记录、性能统计)。

关键点:CI 4 中路由规则可直接绑定匿名函数,无需创建控制器类,适合轻量级 API 接口。例如:

$routes->get('/api/users', fn() => json_encode(['status' => 'ok']));

同时支持 RESTful 路由,通过 HTTP 方法自动分发:GET 查询、POST 新建、PUT 更新、DELETE 删除。

1.3 Service Container 机制

CI 4 引入服务容器,统一管理应用依赖。核心类为 CodeIgniter\Config\Services,提供静态方法获取服务实例:

$db = \Config\Services::db(); // 数据库连接 $validator = \Config\Services::validator(); // 表单验证器 $logger = \Config\Services::logger(); // 日志记录器 $session = \Config\Services::session(); // 会话管理器

服务实例默认为单例模式,但可通过第二个参数强制重建:

$db = \Config\Services::db(true); // 强制创建新连接

开发者可自定义服务,只需在 Config\Services.php 中添加静态方法:

public static function myCustomService($getShared = true) { if ($getShared) { return static::createSharedInstance('MyCustomService', __METHOD__); } return new \App\Libraries\MyCustomService(); }

二、环境部署与配置

2.1 系统环境要求

CodeIgniter 4.6 推荐运行环境如下:

组件最低版本推荐版本说明
PHP8.18.2 或 8.3必须启用 mbstring、intl、fileinfo 扩展
Composer2.02.5+依赖管理(可选,支持 ClassLoader)
MySQL5.78.0+支持 JSON 类型与窗口函数
Apache/Nginx任意最新稳定版需支持 URL 重写

特别注意:CI 4 不支持 PHP 7.x,需升级至 8.1+。部分旧项目迁移时,需检查类兼容性问题(如类型声明、返回类型要求)。

2.2 安装方式对比

通过 Composer 创建新项目:

composer create-project codeigniter4/appstarter project-name

安装后进入项目目录,运行开发服务器:

cd project-name php spark serve

默认监听 8080 端口,访问 http://localhost:8080 即可查看欢迎页。

从 GitHub 下载源码包(https://github.com/codeigniter4/CodeIgniter4/releases):

  1. 解压至 Web 服务器根目录(如 /var/www/html/ci4);
  2. 重命名 env 为 .env,配置数据库与应用设置;
  3. 设置 writable 目录权限为 755;
  4. 配置 Nginx 重写规则:
location / { try_files $uri $uri/ /index.php; }

创建 Dockerfile:

FROM php:8.3-apache COPY . /var/www/html RUN docker-php-ext-install mysqli pdo_mysql intl mbstring fileinfo

构建镜像并运行:

docker build -t ci4-app . docker run -p 8080:80 ci4-app

优势:环境隔离、版本一致、便于 CI/CD 集成。

2.3 关键配置项详解

应用配置文件位于 app/Config/App.php,核心配置项说明:

$app['baseURL'] = 'https://www.xservx.com/'; // 应用根 URL $app['indexPage'] = ''; // 移除 index.php,需配合重写规则 $app['uriProtocol'] = 'REQUEST_URI'; // URI 解析方式 $app['defaultLocale'] = 'zh-CN'; // 默认语言 $app['supportedLocales'] = ['zh-CN', 'en']; // 支持多语言 $app['locale'] = 'zh-CN'; // 当前语言环境

数据库配置在 app/Config/Database.php:

$db['default'] = [ 'hostname' => 'localhost', 'username' => 'root', 'password' => '', 'database' => 'ci4_demo', 'DBDriver' => 'MySQLi', 'DBPrefix' => 'ci_', 'pConnect' => false, 'DBDebug' => (ENVIRONMENT !== 'production'), 'charset' => 'utf8mb4', 'DBCollat' => 'utf8mb4_general_ci', ];

安全相关配置在 app/Config/Filters.php 与 app/Config/Security.php:

$security['csrfProtection'] = 'session'; // CSRF 保护方式 $security['csrfTokenName'] = 'csrf_test_name'; $security['csrfHeaderName'] = 'X-CSRF-TOKEN'; $security['csrf_expire'] = 7200; // 令牌有效期(秒) $security['redirect'] = true; // CSRF 失败时是否重定向

三、路由系统实战

3.1 路由规则定义方式

路由配置文件为 app/Config/Routes.php,支持以下 5 种定义方式:

最简单形式,直接映射 URI 到控制器方法:

$routes->get('/users', 'UserController::index'); $routes->post('/users', 'UserController::create'); $routes->put('/users/(:num)', 'UserController::update/$1'); $routes->delete('/users/(:num)', 'UserController::delete/$1');

说明:括号内数字表示捕获参数,通过 $1、$2 引用。

支持通配符匹配:(:any) 匹配任意字符(含斜杠),(:segment) 匹配单段路径:

$routes->get('/blog/(:segment)/(:num)', 'Blog::view/$1/$2'); // 访问 /blog/php/123 → Blog::view('php', 123)

通配符必须按顺序声明,且不能重复命名(如 (:any)/(:any) 会冲突)。

为路由添加名称,便于生成 URL:

$routes->get('/users/profile', 'UserController::profile', ['as' => 'user_profile']); // 生成 URL:site_url('user_profile') → /users/profile

配合视图使用:

<a href="">个人中心</a>

路由分组用于统一前缀与命名空间:

$routes->group('admin', ['namespace' => 'App\Controllers\Admin'], function($routes) { $routes->get('/', 'Dashboard::index'); $routes->get('users', 'UserController::list'); });

等效于 /admin/ → Admin\Dashboard::index,/admin/users → Admin\UserController::list。

CLI 路由用于命令行任务(如定时任务、数据迁移):

$routes->cli('migrate/run', 'Migrate::run'); $routes->cli('cache/flush', 'Cache::flush');

执行命令:

php spark migrate:run php spark cache:flush
3.2 路由冲突与调试技巧

常见路由冲突场景:

  • 通配符顺序错误:将 (:any) 放在具体规则之前,导致后续规则失效。
  • 命名空间遗漏:控制器未声明命名空间,系统无法定位类。
  • HTTP 方法不匹配:POST 请求使用 $routes->get() 定义。

调试方法:

  1. 运行命令查看当前路由表:
php spark routes

输出示例:

+----------+------------------+------------------+------------------+
| Method   | Route            | Controller       | Filter           |
+----------+------------------+------------------+------------------+
| GET      | /                | Home::index      |                  |
| GET      | /users           | Users::index     |                  |
| POST     | /users           | Users::create    |                  |
| GET      | /users/(:segment)| Users::view/$1   |                  |
+----------+------------------+------------------+------------------+
  • 开启路由调试日志:在 app/Config/Logger.php 中设置:
  • $logger->logPath = WRITEPATH . 'logs/'; $logger->logDepths = ['debug'];

    四、控制器开发规范

    4.1 基础控制器结构

    控制器类必须继承 CodeIgniter\Controller 或实现 ControllerInterface:

    namespace App\Controllers; use CodeIgniter\Controller; use CodeIgniter\HTTP\RequestInterface; use CodeIgniter\HTTP\ResponseInterface; class Users extends Controller { public function index() { $data['users'] = model('UserModel')->findAll(); return view('users/list', $data); } }

    关键点:

    • 必须声明命名空间(App\Controllers);
    • 方法需为 public,且返回值为 ResponseInterface 或可转换为字符串(如视图渲染结果);
    • 通过 $this->request 获取当前请求对象。
    4.2 请求对象高级用法

    CI 4 中 Request 对象提供丰富方法:

    // 获取 GET 参数 $username = $this->request->getGet('username'); // 获取 POST 数据(自动过滤 XSS) $postData = $this->request->getPost(); // 获取原始 JSON 数据 $jsonData = json_decode($this->request->getRawInput(), true); // 检查是否为 AJAX 请求 if ($this->request->isAJAX()) { return $this->response->setJSON(['status' => 'ok']); } // 获取客户端 IP $ip = $this->request->getIPAddress(); // 获取 User Agent $ua = $this->request->getUserAgent();

    安全提示:避免直接使用 $_GET、$_POST,应通过 Request 对象获取,确保数据经过安全过滤。

    4.3 响应对象生成方式

    控制器方法可通过 Response 对象返回不同格式响应:

    // 返回视图 return view('users/list', $data); // 返回 JSON return $this->response->setJSON([ 'status' => 'success', 'data' => $users ]); // 返回 XML return $this->response->setXML('<users><user>John</user></users>'); // 重定向 return redirect()->to('/users'); // 自定义状态码 return $this->response->setStatusCode(404)->setJSON(['error' => 'Not Found']);

    重定向时携带闪存数据(用于表单提交后提示):

    return redirect()->to('/users')->with('success', '用户创建成功');
    4.4 中间件(Filters)集成

    中间件在请求生命周期中拦截处理,示例:权限验证中间件:

    namespace App\Filters; use CodeIgniter\Filters\FilterInterface; use CodeIgniter\HTTP\RequestInterface; use CodeIgniter\HTTP\ResponseInterface; class AuthFilter implements FilterInterface { public function before(RequestInterface $request) { $session = session(); if (!$session->has('user_id')) { return redirect()->to('/login'); } } public function after(RequestInterface $request, ResponseInterface $response) { // 可用于记录响应时间 } }

    在 app/Config/Filters.php 中注册:

    $filters = [ 'auth' => [ 'before' => ['admin/*', 'users/*'], ], ];

    五、模型与数据库操作

    5.1 基础模型定义

    CI 4 模型需继承 CodeIgniter\Model:

    namespace App\Models; use CodeIgniter\Model; class UserModel extends Model { protected $table = 'users'; protected $primaryKey = 'id'; protected $allowedFields = ['username', 'email', 'password']; protected $useTimestamps = true; protected $createdField = 'created_at'; protected $updatedField = 'updated_at'; protected $useSoftDeletes = true; protected $deletedField = 'deleted_at'; }

    关键属性说明:

    • $allowedFields:允许批量赋值的字段,防止意外覆盖敏感字段(如 id、role);
    • $useSoftDeletes:启用软删除(标记 deleted_at,不物理删除);
    • $useTimestamps:自动维护 created_at/updated_at 时间戳。
    5.2 查询构建器(Query Builder)
    $db = \Config\Database::connect(); $query = $db->table('users') ->select('id, username, email') ->where('status', 'active') ->orderBy('created_at', 'DESC') ->get(); $users = $query->getResult();

    链式调用优势:SQL 构建更清晰,自动转义参数防注入。

    $db = \Config\Database::connect(); $db->table('users')->insert([ 'username' => 'john', 'email' => 'john@example.com', 'password' => password_hash('123456', PASSWORD_BCRYPT) ]);

    插入后获取 ID:

    $insertId = $db->insertID();
    $db = \Config\Database::connect(); $query = $db->table('orders o') ->select('o.id, o.amount, u.username') ->join('users u', 'o.user_id = u.id', 'left') ->where('o.status', 'paid') ->get(); $results = $query->getResult();

    支持 LEFT/RIGHT/INNER JOIN,自动处理别名冲突。

    5.3 事件钩子(Events)

    模型提供 8 个事件钩子,用于在 CRUD 操作前后插入逻辑:

    protected $beforeInsert = ['hashPassword']; protected $afterInsert = ['logActivity']; protected $beforeUpdate = ['validateUpdate']; protected $afterUpdate = ['clearCache']; protected function hashPassword(array $data) { if (isset($data['data']['password'])) { $data['data']['password'] = password_hash($data['data']['password'], PASSWORD_BCRYPT); } return $data; }

    适用场景:密码加密、操作日志记录、缓存清除、数据同步。

    六、表单验证与数据过滤

    6.1 内置验证规则

    CI 4 提供 30+ 内置验证规则,常用规则如下:

    规则说明示例
    required必填字段required
    valid_email邮箱格式valid_email
    min_length[6]最小长度min_length[6]
    matches[password]字段匹配matches[password]
    is_unique[table.field]唯一性检查is_unique[users.email]
    regex_match[/^[a-zA-Z0-9_]+$/]正则匹配regex_match[/^[a-zA-Z0-9_]+$/]
    6.2 验证器使用示例
    namespace App\Controllers; use CodeIgniter\Controller; use CodeIgniter\HTTP\RequestInterface; use CodeIgniter\HTTP\ResponseInterface; class Register extends Controller { public function index() { $rules = [ 'username' => 'required|min_length[3]|max_length[20]|is_unique[users.username]', 'email' => 'required|valid_email|is_unique[users.email]', 'password' => 'required|min_length[6]|matches[password_confirm]', 'password_confirm' => 'required' ]; if ($this->request->getMethod() === 'post' && $this->validate($rules)) { // 验证通过 $data = $this->request->getPost(); $model = model('UserModel'); $model->save([ 'username' => $data['username'], 'email' => $data['email'], 'password' => password_hash($data['password'], PASSWORD_BCRYPT) ]); return redirect()->to('/login')->with('success', '注册成功'); } // 验证失败,返回错误信息 return view('register', [ 'validation' => $this->validator ]); } }

    在视图中显示错误:

    <?php if (isset($validation)) : ?> <div class="error"> <?php echo $validation->listErrors(); ?> </div> <?php endif; ?>
    6.3 自定义验证规则

    在 app/Validation/ValidationRules.php 中扩展:

    namespace App\Validation; class ValidationRules { public function checkUsername(string $str, string $fields, array $data): bool { // 检查是否包含非法字符 return !preg_match('/[^a-zA-Z0-9_]/', $str); } }

    在配置中注册:

    // app/Config/Validation.php public $rules = [ 'register' => [ 'username' => 'required|checkUsername' ] ];

    验证时直接调用规则名:

    $rules = [ 'username' => 'required|checkUsername' ];

    七、安全防护机制

    7.1 CSRF 防护完整配置

    CI 4 默认启用 CSRF 保护,需确保以下配置:

    // app/Config/Filters.php $filters = [ 'csrf' => [ 'except' => [ 'api/*', // API 接口可关闭 CSRF ], ], ];

    在表单中添加 CSRF 令牌:

    <form method="post"> <input type="hidden" name="" value=""> <!-- 表单内容 --> </form>

    API 场景下,可设置请求头传递令牌:

    $headers = [ 'X-CSRF-TOKEN' => csrf_hash() ];
    7.2 SQL 注入防护实践

    CI 4 通过查询构建器自动转义参数,但需注意:

    • 避免直接拼接 SQL 字符串:
    // 错误示例 $db->query("SELECT * FROM users WHERE username = '" . $username . "'"); // 正确示例 $db->where('username', $username)->get('users');
  • 使用查询绑定:
  • $db->query("SELECT * FROM users WHERE username = ?", [$username]);
  • 对复杂查询使用预处理语句:
  • $db->transStart(); $db->query("UPDATE users SET balance = balance - ? WHERE id = ?", [100, $userId]); $db->query("UPDATE users SET balance = balance + ? WHERE id = ?", [100, $targetId]); $db->transComplete();
    7.3 XSS 防护与输出转义

    CI 4 视图中自动转义输出(需启用):

    // app/Config/View.php public $autoEscape = true; // 默认转义所有变量

    手动转义特定变量:

    <?php echo esc($username, 'html'); ?>

    esc() 函数支持多种转义模式:html、js、css、url、attr、raw(不转义)。

    禁用自动转义场景(如富文本编辑器内容):

    <?php echo $content; // 未转义,需确保内容安全 ?>

    八、开发者高频问题解答

    8.1 如何实现 RESTful API?

    推荐使用 Resource Controller 模式:

    class ApiUsers extends \CodeIgniter\API\ResponseTrait { public function index() { switch ($this->request->getMethod()) { case 'get': return $this->respond($this->model->findAll()); case 'post': $data = $this->request->getPost(); $this->model->insert($data); return $this->respondCreated($data); default: return $this->failMethodNotAllowed(); } } }

    路由配置:

    $routes->resource('api/users', ['namespace' => 'App\Controllers\Api']);
    8.2 如何配置多数据库连接?

    在 app/Config/Database.php 中添加新组:

    $db['analytics'] = [ 'hostname' => '10.0.0.5', 'username' => 'analytics_user', 'password' => 'secret', 'database' => 'analytics_db', 'DBDriver' => 'MySQLi', 'charset' => 'utf8mb4', 'DBPrefix' => '', ];

    使用时指定连接组:

    $db = \Config\Database::connect('analytics'); $query = $db->table('logs')->get();
    8.3 如何集成 Redis 缓存?

    安装扩展:

    composer require phpredis/phpredis

    配置缓存驱动:

    // app/Config/Cache.php public $handler = 'redis'; public $prefix = 'ci4_'; // app/Config/Redis.php public $default = [ 'hostname' => '127.0.0.1', 'password' => null, 'port' => 6379, 'timeout' => 0, ];

    使用缓存:

    $cache = \Config\Services::cache(); $cache->save('user_data', $userData, 3600); $data = $cache->get('user_data');
    8.4 如何实现国际化(i18n)?

    步骤如下:

    1. 创建语言文件:app/Language/zh-CN/messages.php:
    return [ 'welcome' => '欢迎使用 CI 框架', 'error' => '操作失败', ];
  • 在控制器中加载语言行:
  • $lang = service('language'); echo $lang->getLine('welcome');
  • 设置当前语言:
  • service('language')->setLocale('en');

    九、扩展与周边资源

    9.1 常用第三方包推荐
    包名用途Composer 命令
    codeigniter4/shield用户认证系统composer require codeigniter4/shield
    phpoffice/phpspreadsheetExcel 生成与解析composer require phpoffice/phpspreadsheet
    tecnickcom/tcpdfPDF 文档生成composer require tecnickcom/tcpdf
    symfony/mailgun-mailer邮件发送集成composer require symfony/mailgun-mailer
    9.2 开发者工具推荐
    • CodeIgniter 4:官方文档(https://codeigniter4.github.io/)
    • Debug Bar:内置调试工具栏(开发环境自动启用)
    • PHPStan:静态分析工具(检查类型错误)
    • Psalm:类型检查与代码质量分析
    • VS Code 插件:CodeIgniter Snippets、PHP Intelephense
    9.3 社区与学习资源

    中文社区:

    • CodeIgniter 中文网(https://www.codeigniter.org.cn/)
    • Gitee 代码仓库(https://gitee.com/codeigniter4/CodeIgniter4)
    • 知乎专栏:《CI 框架实战指南》

    英文资源:

    • 官方 GitHub(https://github.com/codeigniter4/CodeIgniter4)
    • CI Forum(https://forum.codeigniter.com/)
    • YouTube 频道:CodeIgniter Community
    9.4 常见问题巡检清单

    部署前务必检查:

    • ✓ writable 目录权限是否为 755
    • ✓ .env 文件是否重命名且配置正确
    • ✓ 数据库连接信息是否准确
    • ✓ URL 重写规则是否生效(Apache:.htaccess;Nginx:try_files)
    • ✓ PHP 版本是否 ≥ 8.1
    • ✓ 是否开启 mbstring、intl、fileinfo 扩展
    • ✓ 生产环境是否设置 ENVIRONMENT = 'production'