CodeIgniter 4 代码模块化完全指南:命名空间、PSR-4 自动加载与 Auto-Discovery 实战
CodeIgniter 4 代码模块化完全指南:命名空间、PSR-4 自动加载与 Auto-Discovery 实战
CodeIgniter 4 通过 PSR-4 命名空间与自动发现(Auto-Discovery)机制,为开发者提供了一种把业务代码按主题拆分为可复用模块(Module)的方式——每个模块就像大应用内部的一个"迷你应用",可包含控制器、模型、视图、配置文件、辅助函数、语言文件等任意标准文件类型。本文以官方用户指南 general/modules.rst 为核心,结合框架源码与测试用例,系统讲解如何搭建模块目录、配置命名空间、自动加载非类文件,以及路由、过滤器、服务、事件、迁移、视图等各类文件在模块中的实际用法,帮助读者把模块化能力真正落地到自己的项目中。
什么是 CodeIgniter 4 的代码模块
模块化的核心思想是围绕某个具体主题(例如博客、商城、用户中心)组织可复用代码,把它视为更大应用中的一个"迷你应用"。CodeIgniter 4 对模块的定义非常轻量:模块并没有特殊的目录约定或强制结构,只要代码遵循 PSR-4 命名空间并通过框架的自动加载机制注册,就能获得模块的全部能力。
框架内的所有标准文件类型都可以放进模块,包括:
- 控制器(Controllers)、模型(Models)、视图(Views)
- 配置文件(Config)
- 辅助函数(Helpers)、语言文件(Language)
- 数据库迁移(Migrations)与种子数据(Seeds)
- 库(Libraries)、实体(Entities)、接口(Interfaces)、仓储(Repositories)等自定义目录
模块中可以只放一种文件,也可以包含全部类型,完全由业务需求决定。如果你希望把模块发布为 Composer 包,可以参考官方指南中的 Composer 包扩展(user_guide_src/source/extending/composer_packages.rst)。
命名空间:模块化的核心基石
模块功能的核心来自 CodeIgniter 4 使用的 PSR-4 兼容自动加载机制(详见 自动加载器概念)。虽然任意代码都可以使用 PSR-4 自动加载器与命名空间,但充分利用模块化的主要方式,是把代码放入命名空间,并注册到 app/Config/Autoload.php 的 $psr4 属性中。
第一步:规划模块目录
假设我们要构建一个可在多个应用之间复用的博客模块,可以在项目根目录下创建以公司名(如 acme)命名的文件夹,与 app 目录平级存放所有模块:
acme/ // 新增的模块目录
app/
public/
system/
tests/
writable/
第二步:注册模块命名空间
打开 app/Config/Autoload.php,在 $psr4 数组中为模块添加命名空间映射:
namespace Config;
use CodeIgniter\Config\AutoloadConfig;
class Autoload extends AutoloadConfig
{
// ...
public $psr4 = [
APP_NAMESPACE => APPPATH,
'Acme\Blog' => ROOTPATH . 'acme/Blog',
];
// ...
}
完成这一步后,acme/Blog 文件夹内的任何文件都可以通过 Acme\Blog 命名空间被访问。按照官方文档的说法,仅此一项就完成了模块化所需工作的约 80%——因为后续所有自动发现能力都建立在这条命名空间映射之上。源码层面,Autoloader 会把这些 PSR-4 前缀写入自身的 $prefixes,并在首次实例化类时按前缀定位文件(见 system/Autoloader/Autoloader.php)。
$psr4 的映射值是 array<string, list<string>|string> 类型:既可以是单个路径字符串,也可以是路径数组(一个命名空间对应多个目录)。APP_NAMESPACE => APPPATH 这一默认映射将应用自身的命名空间指向 app/ 目录,它与你的模块映射遵循同一套解析规则。
第三步:设计模块内部结构
一个常见的模块内部结构会模仿主应用的目录组织方式:
acme/
Blog/
Config/
Controllers/
Database/
Migrations/
Seeds/
Helpers/
Language/
en/
Libraries/
Models/
Views/
当然,没有任何规则强制你采用这种结构。完全可以按模块自身最合适的方式来组织,删除不需要的目录,或为 Entities、Interfaces、Repositories 等新建专属目录。框架只关心"命名空间前缀 → 目录路径"的映射关系,以及约定好的子目录名(如 Config/、Helpers/、Views/)。
自动加载非类文件
模块中往往不只有 PHP 类,还会包含过程式函数、引导(bootstrap)文件、模块常量文件等不会按"类"方式加载的文件。有两种处理方式:
- 手动
require:在使用位置的文件开头手动引入这些文件。简单直接,但需要处处维护。 - 借助框架的
$files配置自动加载:在 app/Config/Autoload.php 的$files属性中列出这些文件的路径,让框架像自动加载类一样自动加载它们:
namespace Config;
use CodeIgniter\Config\AutoloadConfig;
class Autoload extends AutoloadConfig
{
// ...
public $files = [
'path/to/my/functions.php',
'path/to/my/constants.php',
'path/to/my/bootstrap.php',
];
// ...
}
这些路径可以是绝对路径,也可以是相对项目根的路径。源码中,Autoloader::register() 会在向 SPL 自动加载栈注册类加载器后,遍历 $files 逐个 include(见 system/Autoloader/Autoloader.php),因此这些文件会在应用引导阶段被自动引入。
Auto-Discovery:模块自动发现机制
很多时候你都需要为要引入的文件指定完整命名空间,但 CodeIgniter 4 可以通过自动发现(Auto-Discovery)机制让模块集成简单得多。框架会自动扫描并发现多种文件类型:
- 事件 Events(
user_guide_src/source/extending/events.rst) - 过滤器 Filters(
user_guide_src/source/incoming/filters.rst) - 注册器(Registrars)
- 路由文件(
user_guide_src/source/incoming/routing.rst) - 服务 Services(
user_guide_src/source/concepts/services.rst)
自动发现的配置位于 app/Config/Modules.php。当前仓库的默认配置如下(app/Config/Modules.php):
namespace Config;
use CodeIgniter\Modules\Modules as BaseModules;
class Modules extends BaseModules
{
public $enabled = true;
public $discoverInComposer = true;
public $composerPackages = [];
public $aliases = [
'events',
'filters',
'registrars',
'routes',
'services',
];
}
从源码看,自动发现系统的工作方式(见 system/Modules/Modules.php):
public function shouldDiscover(string $alias): bool
{
if (! $this->enabled) {
return false;
}
return in_array(strtolower($alias), $this->aliases, true);
}
即:只有 $enabled 为 true 且对应别名存在于 $aliases 中时,该类型的自动发现才会执行。系统会遍历在 Config/Autoload.php 和 Composer 包中定义的所有 PSR-4 命名空间,扫描其中特定的目录与文件。例如,路由发现会通过 FileLocator::search('Config/Routes.php') 找到 acme/Blog/Config/Routes.php(见 system/Router/RouteCollection.php 与 system/Autoloader/FileLocator.php)。
启用 / 禁用自动发现
通过 $enabled 类变量可以一键开启或关闭全部自动发现。设置为 false 会禁用所有发现,从而优化性能,但会丧失模块和 Composer 包的特殊能力:
public $enabled = false;
指定发现项
通过 $aliases 选项可以精确控制哪些条目被自动发现。如果某个条目不在数组中,该条目的自动发现不会执行,但数组中其余条目仍然会被发现。默认开启的事件、过滤器、注册器、路由、服务五种发现类型如上所示,你可以按需增删。
与 Composer 的协同
通过 Composer 安装并使用 PSR-4 命名空间的包默认也会被自动发现;PSR-0 命名空间的包不会被检测到。这一点在源码中有直接体现:Autoloader::loadComposerAutoloader() 只有在 $modules->discoverInComposer 为真时才加载 Composer 命名空间(见 system/Autoloader/Autoloader.php)。
指定 Composer 包(4.3.0 起)
为避免浪费时间去扫描无关的 Composer 包,可以编辑 app/Config/Modules.php 中的 $composerPackages 变量,手动指定要发现的包:
public $composerPackages = [
'only' => [
// 列出所有需要自动发现的包
'codeigniter4/shield',
],
];
也可以反过来,指定要从发现中排除的包:
public $composerPackages = [
'exclude' => [
// 列出需要排除的包
'pestphp/pest',
],
];
$composerPackages 的类型为 array{only?: list<string>, exclude?: list<string>},两个键互斥使用。注意 'only' 与 'exclude' 是配置数组的键名,不是代码中定义的常量或方法。
禁用 Composer 包发现
如果不想扫描所有 Composer 已知目录来定位文件,可以把 app/Config/Modules.php 中的 $discoverInComposer 设为 false:
public $discoverInComposer = false;
模块中的各类文件实战
这一节逐一说明控制器、视图、语言文件等各类文件在模块中的使用方法。部分内容在用户指南相关章节有更详细介绍,这里集中复述是为了让读者看清各部件如何拼装在一起。
路由(Routes)
默认情况下,模块内的路由会被自动扫描。这个行为可以在上文所述的 Modules 配置文件中关闭。
注意: 由于这些路由文件是在当前作用域内被 include 的,$routes 实例已经为你定义好了——如果你试图重新定义该类,会引发错误。这一点在源码中体现得很清楚:RouteCollection::discoverRoutes() 在局部作用域声明 $routes = $this; 后逐个 include 找到的路由文件(见 system/Router/RouteCollection.php)。
此外,如果应用中的路由包含通配符(wildcards),模块路由可能无法被正确处理。此时可以参考 路由优先级(user_guide_src/source/incoming/routing.rst 的 "Route Priority" 一节)中介绍的方法:用 priority 选项调低通配符路由的处理优先级,数值越大优先级越低(默认所有路由优先级为 0,负整数会被转换为绝对值)。
过滤器(Filters)
已弃用(自 4.4.2 起): 过滤器的模块自动发现功能已被弃用,官方推荐改用注册器(Registrars)来实现同样效果:
namespace CodeIgniter\Shield\Config;
use CodeIgniter\Shield\Filters\SessionAuth;
use CodeIgniter\Shield\Filters\TokenAuth;
class Registrar
{
/**
* Registers the Shield filters.
*/
public static function Filters(): array
{
return [
'aliases' => [
'session' => SessionAuth::class,
'tokens' => TokenAuth::class,
],
];
}
}
在注册器(Registrar)方案中,注册器类位于命名空间的 Config/Registrar.php 文件里,其中与配置类短名同名的方法(如上面的 Filters())返回一个属性数组,框架会在配置类实例化前把返回的属性合并进对应配置(见 system/Config/BaseConfig.php)。
历史上(若你仍使用旧版本),过滤器默认会在模块内被自动扫描,也可在 Modules 配置文件中关闭。由于过滤器文件同样是在当前作用域内被 include,$filters 实例已经定义好,不允许重新定义。旧机制下,需要在模块的 Config/Filters.php 中定义所用过滤器的别名,例如:
$filters->aliases['menus'] = \App\Filters\MenusFilter::class;
对应旧实现位于 system/Filters/Filters.php:构造时若 shouldDiscover('filters') 为真,就会通过 $locator->search('Config/Filters.php') 扫描并 include 各命名空间下的过滤器配置文件(会跳过主应用的 FiltersConfig 与 BaseFiltersConfig)。使用 4.4.2 及以上版本时请直接使用 Registrar 方案。
控制器(Controllers)
位于主 app/Controllers 目录之外的控制器无法通过 URI 检测自动路由,必须显式在路由文件中指定:
// Routes.php
$routes->get('blog', '\Acme\Blog\Controllers\Blog::index');
为了减少这里的重复输入,group 路由 功能非常有用——在分组中指定命名空间,分组内即可使用控制器短名:
$routes->group('blog', ['namespace' => 'Acme\Blog\Controllers'], static function ($routes) {
$routes->get('/', 'Blog::index');
});
配置文件(Config)
处理配置文件无需任何特殊改动。它们仍然是带命名空间的类,用 new 直接实例化即可:
$config = new \Acme\Blog\Config\Blog();
同时,只要使用框架中始终可用的 config() 函数并传入短类名,配置文件也会被自动发现。config() 内部通过 Factories::get('config', $name) 解析(见 system/Common.php),Factories 会按命名空间搜索对应配置类。
两个需要注意的点:
- 不建议在多个模块中使用相同的短类名。需要覆盖或扩充 app/Config/ 中已知配置的模块,应使用隐式注册器(Registrars)机制。
- 4.4.0 之前的行为差异: 在 v4.4.0 之前,即使你指定了完整类名(如
config(\Acme\Blog\Config\Blog::class)),当 app/Config/ 中存在同短类名的类时,config()仍会优先找到 app/Config/ 中的文件。该行为已在 v4.4.0 修复,现在会返回你指定的实例。
迁移(Migrations)
迁移文件会在已定义的命名空间内被自动发现,所有命名空间下发现的迁移在每次执行时都会被运行。源码印证了这一点:MigrationRunner::findMigrations() 在未指定命名空间时,会取自动加载器注册的全部命名空间逐一扫描 Database/Migrations/ 目录(见 system/Database/MigrationRunner.php),并按迁移 UID 升序排序后统一执行。
种子(Seeds)
种子文件既可以从 CLI 使用,也可以在其他种子文件中被调用,前提是提供完整的命名空间。在 CLI 中调用时,需要注意双反斜杠的写法:
Unix / Linux / macOS:
php spark db:seed Acme\\Blog\\Database\\Seeds\\TestPostSeeder
Windows:
php spark db:seed Acme\Blog\Database\Seeds\TestPostSeeder
辅助函数(Helpers)
只要辅助函数文件位于命名空间的 Helpers 目录下,使用 helper() 函数时就会被自动发现:
helper('blog');
helper() 内部使用 FileLocator::search('Helpers/' . $filename) 在所有命名空间中搜索同名文件(见 system/Common.php)。文件会被自动补上 _helper 后缀并去重加载。你也可以指定命名空间来加载特定命名空间下的辅助函数文件(详见用户指南 helpers 加载 中"从指定命名空间加载"一节)。
语言文件(Language)
当语言文件遵循与主应用目录相同的目录结构时,使用 lang() 函数会自动从已定义的命名空间定位语言文件。例如模块内按 Language/en/ 组织文件,即可通过 lang('Blog.someKey') 引用。lang() 函数在 system/Common.php 中实现,它通过 Language 服务加载对应行内容,并支持指定 locale 与参数替换。
库(Libraries)
库总是通过其完整限定类名来实例化,因此没有提供特殊访问方式:
$lib = new \Acme\Blog\Libraries\BlogLib();
模型(Models)
如果用 new 关键字以完整限定类名实例化模型,同样没有特殊访问方式:
$model = new \Acme\Blog\Models\PostModel();
但模型文件在使用始终可用的 model() 函数时会被自动发现。model() 内部通过 Factories::models($name, ...) 解析(见 system/Common.php)。
与配置类似,需要注意:
- 不建议在模块中使用相同的短类名。
- 4.4.0 之前的行为差异: 在 v4.4.0 之前,即使指定完整限定类名(如
model(\Acme\Blog\Model\PostModel::class)),当 app/Models/ 中存在同短类名的类时,model()仍会返回 app/Models/ 中的实例。详细说明可参见 Factories 文档(user_guide_src/source/concepts/factories.rst的 "Passing Fully Qualified Classname" 一节),其中指出 v4.4.0 之前需要把preferApp选项设为false才能取到模块中的类。
视图(Views)
视图可以按 命名空间视图 文档描述的方式,使用类命名空间加载:
echo view('Acme\Blog\Views\index');
view() 函数会把 Acme\Blog\Views\index 解析为 acme/Blog/Views/index.php,并支持向视图传递数据数组作为第二个参数。
模块化最佳实践小结
- 命名空间先行:模块的一切能力都源自 PSR-4 命名空间映射(app/Config/Autoload.php 的
$psr4),这是模块化的地基,务必先把它配置正确。 - 按需开关自动发现:生产环境若不需要模块能力,可在 app/Config/Modules.php 中设
$enabled = false换取性能;需要精细控制时用$aliases收缩发现范围。 - 优先使用 Registrar:自 4.4.2 起,过滤器发现已弃用,向现有配置(如过滤器别名)追加内容请统一走隐式注册器(
Config/Registrar.php)机制。 - 避免短类名冲突:多模块共用同一短类名会导致
config()、model()等工厂函数解析到错误实例,尽量保持类名唯一。 - CLI 双反斜杠:在 Unix 类系统上通过 CLI 调用模块内的种子类时,务必使用
Acme\\Blog\\Database\\Seeds\\TestPostSeeder的双反斜杠写法。
把上述内容串联起来,一个可复用的 Acme Blog 模块就完整具备了路由、过滤器(或注册器)、控制器、配置、迁移、种子、辅助函数、语言文件、库、模型与视图的全部能力,可以被任意 CodeIgniter 4 应用通过一次命名空间配置轻松接入,从而真正做到"一次开发,多处复用"。