laravel-modules 实战指南:用模块化架构组织大型 Laravel 应用
laravel-modules 实战指南:用模块化架构组织大型 Laravel 应用
laravel-modules 是一个面向大型 Laravel 应用的模块化管理包,它将"模块(Module)"抽象为一种近似于 Laravel 独立包的结构——每个模块自带视图、控制器、模型、路由与配置文件,从而把单体应用拆解为边界清晰的业务单元。本文将以本仓库(nwidart/laravel-modules)的 README.md 为骨架,结合 config/config.php、src 源码与 tests 测试,系统讲解安装、自动加载、模块发现注册机制、核心配置、命令行用法与生命周期管理,帮助你从"会用"进阶到"理解其原理"。
一、模块是什么:理解 laravel-modules 的核心模型
官方文档对 laravel-modules 的定位非常直白:它用于管理大型 Laravel 应用,而一个模块(Module)就像是一个迷你版的 Laravel 包——拥有自己的视图、控制器、模型、迁移、语言包与路由。
这与 Laravel 生态中常见的"按功能目录分块"思路有本质区别:每个模块是自包含的单元,可以被独立启用、禁用、删除,也可以被当成一个可复用的包独立分发。模块的元信息记录在模块根目录下的 module.json 清单文件中,json.stub 展示了它的标准结构:
{
"name": "$STUDLY_NAME$",
"alias": "$LOWER_NAME$",
"description": "",
"keywords": [],
"priority": 0,
"providers": [
"$MODULE_NAMESPACE$\\$STUDLY_NAME$\\$PROVIDER_NAMESPACE$\\$STUDLY_NAME$ServiceProvider"
],
"files": []
}
从 src/Json.php 可以看到,module.json 会被解析为 Json 对象缓存到内存,供模块按 key 读取(如 name、alias、providers、priority、files)。测试目录 tests/stubs/valid/Recipe/module.json 给出了一个真实可用的模块清单示例,其中 providers 声明了模块的服务提供者,files 声明了模块启动时需要 include 的辅助文件——这些字段正是模块注册流程的数据来源。
版本兼容矩阵
README 给出 laravel-modules 各主版本与 Laravel 的对应关系,这是选择安装版本的第一依据:
| Laravel | laravel-modules |
|---|---|
| 5.4 | ^1.0 |
| 5.5 | ^2.0 |
| 5.6 | ^3.0 |
| 5.7 | ^4.0 |
| 5.8 | ^5.0 |
| 6.0 | ^6.0 |
| 7.0 | ^7.0 |
| 8.0 | ^8.0 |
| 9.0 | ^9.0 |
| 10.0 | ^10.0 |
| 11.0 | ^11.0 |
| 12.0 | ^12.0 |
| 13.0 | ^13.0 |
README 声明本包已在 Laravel 11 上得到支持与测试;而当前仓库的 composer.json 中 require-dev 已引入 laravel/framework: ^13.0、php: ^8.3,branch-alias 为 13.x-dev,说明仓库开发主线正面向 Laravel 13。安装时应以你项目的 Laravel 版本为基准,从表中选取对应主版本。
与 pingpong/modules 的关系
laravel-modules 是 pingpong/modules(已不再维护)的重新发布、重新组织并持续维护的版本,而它相对原包有一个关键优势:配套的测试体系。仓库 tests 目录下覆盖了激活器、命令、生成器、仓储、辅助函数等大量测试用例,这保证了重构与升级的可靠性。
二、安装与配置
通过 Composer 安装
composer require nwidart/laravel-modules
安装完成后,包会自动注册服务提供者与别名(alias),无需手动修改 config/app.php。这一点可以从 composer.json 的 extra.laravel 段得到验证:
"extra": {
"laravel": {
"providers": [
"Nwidart\\Modules\\LaravelModulesServiceProvider"
],
"aliases": {
"Module": "Nwidart\\Modules\\Facades\\Module"
}
}
}
服务提供者指向 src/LaravelModulesServiceProvider.php,别名指向 src/Facades/Module.php。
发布配置文件
如果需要自定义模块路径、命名空间、生成规则等,可以发布包的配置文件:
php artisan vendor:publish --provider="Nwidart\Modules\LaravelModulesServiceProvider"
发布后得到 config/modules.php。从 src/ModulesServiceProvider.php 的 registerNamespaces() 可以看到,该提供者除了发布配置,还支持发布 stubs(发布到 stubs/nwidart-stubs)与 Vite 辅助脚本(vite-module-loader.js,发布到项目根目录),分别对应 --tag 为 config、stubs、vite 的发布操作。
三、模块自动加载:v11.0 之后的新方式
这是 README 重点强调的破坏性变更,务必注意:
从 v11.0 开始,
"Modules\\": "modules/"这样的 PSR-4 自动加载配置已不再需要,如果 composer.json 中仍存在应予以删除。
默认情况下,模块类不会自动加载。v11.0 推荐的做法是借助 wikimedia/composer-merge-plugin,将各模块自己的 composer.json 合并进主应用的 Composer 配置,从而让模块内的类被自动加载。在项目根 composer.json 的 extra 段添加:
"extra": {
"laravel": {
"dont-discover": []
},
"merge-plugin": {
"include": [
"Modules/*/composer.json"
]
}
},
首次安装时的插件信任提示
重要:首次安装时,Composer 会询问是否信任 wikimedia/composer-merge-plugin:
Do you trust "wikimedia/composer-merge-plugin" to execute code and wish to enable it now? (writes "allow-plugins" to composer.json) [y,n,d,?]
应当回答 y,允许该插件执行;否则需要手动在 composer.json 中启用:
"config": {
"allow-plugins": {
"wikimedia/composer-merge-plugin": true
}
}
若
"wikimedia/composer-merge-plugin": false,模块将不会被自动加载。
这一点与当前仓库 composer.json 的自身配置完全一致——它在 require 中声明了 wikimedia/composer-merge-plugin: ^2.1,并在 config.allow-plugins 中将其设为 true。
Tip:配置完成后记得运行 composer dump-autoload,重新生成自动加载映射。实际上 module:make 命令在创建模块后也会自动执行一次 composer dump-autoload,见 ModuleMakeCommand.php。
四、模块的发现与注册机制(源码级)
理解 laravel-modules 的原理,关键在于看透它"扫描清单 → 构建 manifest → 批量注册"的三段式流程。
1. 扫描:以 module.json 为识别标志
src/FileRepository.php 的 scan() 方法遍历扫描路径,用 glob 匹配每个目录下的 module.json:
$manifests = (array) $this->getFiles()->glob("{$path}/module.json");
扫描路径由 getScanPaths() 决定(FileRepository.php):默认包含 paths.modules(即 base_path('Modules')),当配置项 scan.enabled 为 true 时还会并入 scan.paths(默认是 vendor/*/*,便于从 Packagist 安装模块)。每个命中 module.json 的目录都会通过 createModule() 创建为模块实例(Laravel 下对应 src/Laravel/LaravelFileRepository.php 与 src/Laravel/Module.php)。
2. 构建 manifest:过滤启用状态并按优先级排序
src/ModuleManifest.php 会读取所有 module.json,仅保留当前处于启用状态的模块(通过 ActivatorInterface::hasStatus($module['name'], true) 判断),并按 priority 字段升序排序,最后扁平化收集所有 providers。
3. 注册:ProviderRepository 批量加载
src/ModulesServiceProvider.php 的 registerModules() 把 manifest 中的 providers 交给 Laravel 的 ProviderRepository 加载,并调用 registerFiles() include 各模块清单中 files 字段声明的辅助文件。由此,每个模块的服务提供者、别名(aliases)、辅助文件(files)都被纳入应用生命周期。
在 Laravel 环境下,模块自身的注册细节见 src/Laravel/Module.php:registerProviders() 使用独立的缓存路径加载模块提供者;registerAliases() 通过 AliasLoader 注册别名;getCachedServicesPath() 还针对 Laravel Vapor 提供了可写路径的维护模式支持(对应配置项 vapor_maintenance_mode)。
五、核心配置项详解(config/modules.php)
发布后的配置基于 config/config.php,下面按功能块拆解关键参数。
5.1 命名空间与路径
- namespace:默认
'Modules',即模块的根命名空间。 - paths.modules:默认
base_path('Modules'),模块生成与扫描的根目录。 - paths.assets:默认
public_path('modules'),模块静态资源发布目录。 - paths.migration:默认
base_path('database/migrations'),module:publish-migration的发布目标。 - paths.app_folder:默认
'app/',应用目录名,可改为src/或App/。 - paths.generator:声明各类型代码(controller、model、migration、seeder、provider、routes、views、tests 等)在模块内的生成路径,以及
generate开关——设为false则生成模块时不会创建该目录。例如默认只开启provider、route-provider、controller、config、factory、migration、seeder、assets、views、routes、test-feature、test-unit等目录,而actions、casts、model、request、event、jobs等默认不生成(按需手动开启)。
5.2 stubs(生成模板)
'stubs' => [
'enabled' => false,
'path' => base_path('vendor/nwidart/laravel-modules/src/Commands/stubs'),
'files' => [
'routes/web' => 'routes/web.php',
'routes/api' => 'routes/api.php',
'views/index' => 'resources/views/index.blade.php',
'views/master' => 'resources/views/components/layouts/master.blade.php',
'scaffold/config' => 'config/config.php',
'composer' => 'composer.json',
'assets/js/app' => 'resources/assets/js/app.js',
'assets/sass/app' => 'resources/assets/sass/app.scss',
'vite' => 'vite.config.js',
'package' => 'package.json',
],
// ...
],
enabled为false时使用包内置模板;置为true并自定义path即可使用自己的模板目录(也可以通过php artisan vendor:publish --tag=stubs先发布)。files定义了生成模块时默认创建的文件及其目标路径。replacements定义模板占位符的替换规则,例如routes/web替换LOWER_NAME、STUDLY_NAME、PLURAL_LOWER_NAME、KEBAB_NAME、MODULE_NAMESPACE、CONTROLLER_NAMESPACE,composer还额外支持VENDOR、AUTHOR_NAME、AUTHOR_EMAIL、APP_FOLDER_NAME等。- 从配置注释可以看出,
replacements支持自定义替换类:将大写 KEY 映射为继承Nwidart\Modules\Support\ReplacementKeyCommand的类,该类实现handle(): string返回替换文本,从而注入动态值(对应源码 ModuleGenerator.php 的分支处理)。 gitkeep为true时,生成的空目录会放入.gitkeep文件。
5.3 自动发现与注册开关
- auto-discover.migrations(默认
true):自动把所有已启用模块的迁移目录注册到 Laravel Migrator。LaravelModulesServiceProvider.php 通过collect(Module::allEnabled())遍历模块并调用$migrator->path(...)完成注册。 - auto-discover.translations(默认
false):为已启用模块的语言目录注册翻译命名空间与 JSON 路径(对应 LaravelModulesServiceProvider.php)。 - register.translations(默认
true):控制模块自身boot()时是否加载Resources/lang翻译(见 src/Module.php)。 - register.files(默认
'register'):决定模块清单中files字段在register还是boot阶段加载。
5.4 激活器(Activator)
'activators' => [
'file' => [
'class' => FileActivator::class,
'statuses-file' => base_path('modules_statuses.json'),
],
],
'activator' => 'file',
模块的启用/禁用状态由 Activator 管理。默认使用文件激活器 src/Activators/FileActivator.php,状态持久化在项目根目录的 modules_statuses.json 中;配置注释也提示可以扩展数据库等类型的激活器(唯一必需参数是 class)。服务容器会在 LaravelModulesServiceProvider.php 中按 modules.activator 指定的类型实例化对应激活器。
5.5 其他配置
- vapor_maintenance_mode:Vapor 环境下把缓存 services 路径切换到可写位置(
env('VAPOR_MAINTENANCE_MODE', false))。 - commands:通过
ConsoleServiceProvider::defaultCommands()->merge([...])决定注册哪些 Artisan 命令,可在此追加自定义命令。 - scan:
enabled(默认false)与paths(默认base_path('vendor/*/*')),用于从 vendor 目录扫描模块。 - composer:生成
composer.json时使用的 vendor(env('MODULE_VENDOR', 'nwidart'))与作者信息(MODULE_AUTHOR_NAME/MODULE_AUTHOR_EMAIL),composer-output控制是否输出 composer 命令结果。 - inertia:默认前端框架,支持
"vue"、"react"、"svelte",默认"vue",供 Inertia 相关 make 命令在未指定--vue/--react/--svelte时使用。
六、命令行工具一览
所有默认命令在 src/Providers/ConsoleServiceProvider.php 的 defaultCommands() 中注册,可分为以下几类:
Actions(模块状态与运维):module:enable、module:disable、module:list、module:use、module:unuse、module:install、module:update、module:delete、module:dump、module:list-commands、module:check-lang、module:model-show、module:model-prune。
Database(模块级数据库操作):module:migrate、module:migrate-fresh、module:migrate-refresh、module:migrate-reset、module:migrate-rollback、module:migrate-status、module:seed。
Make(模块内代码生成):module:make 及其衍生命令,包括 module:make-controller、module:make-model、module:make-migration、module:make-seed、module:make-provider、module:make-event、module:make-listener、module:make-job、module:make-mail、module:make-notification、module:make-request、module:make-resource、module:make-rule、module:make-policy、module:make-middleware、module:make-command、module:make-test、module:make-factory、module:make-observer、module:make-enum、module:make-cast、module:make-exception、module:make-interface、module:make-trait、module:make-service、module:make-action、module:make-class、module:make-helper、module:make-repository、module:make-replacement、module:make-scope、module:make-channel、module:make-component、module:make-component-view、module:make-view、module:make-event-provider、module:make-route-provider、module:make-inertia-page、module:make-inertia-component 等。
Publish(资源发布):module:publish、module:publish-config、module:publish-migration、module:publish-translation、module:publish-inertia。
Other:module:composer-update、module:setup(安装向导)、module:v6:migrate(面向旧版本迁移,见 LaravelModulesV6Migrator.php)、module:update-phpunit-coverage。
常用命令示例
创建模块(同时可生成控制器、迁移、Seeder 等资源):
php artisan module:make Blog
创建纯模块(不含资源文件)或 API 模块、Inertia 模块:
php artisan module:make Blog --plain
php artisan module:make Blog --api
php artisan module:make Blog --inertia
相关选项在 ModuleMakeCommand.php 中定义,还包括 --disabled(创建后不启用)、--force(已存在时强制覆盖)、--author-name/--author-email/--author-vendor(覆盖 composer.json 作者信息)。
启用与禁用模块:
php artisan module:enable Blog
php artisan module:disable Blog
查看模块列表、切换当前操作的模块上下文:
php artisan module:list
php artisan module:use Blog
针对模块执行迁移与数据填充:
php artisan module:migrate Blog
php artisan module:seed Blog
注意:src/Facades/Module.php 提供
Module::prohibitDestructiveCommands(),可一键禁用module:migrate-fresh、module:migrate-refresh、module:migrate-reset三个破坏性命令,适用于生产环境防护。
七、模块生命周期与启用状态管理
状态机与事件
src/Module.php 定义了模块的核心生命周期:
isEnabled()/isDisabled()通过激活器查询当前状态;enable()依次触发modules.{lower_name}.enabling与modules.{lower_name}.enabled事件,disable()对应disabling/disabled(事件常量定义在 src/Constants/ModuleEvent.php);delete()触发deleting/deleted事件,并删除整个模块目录。
以 module:enable Blog 为例,EnableCommand.php 会先展示当前状态,再调用 $module->enable()——命令的输入输出可通过 EnableCommandTest.php 及快照文件验证。
文件激活器的工作方式
src/Activators/FileActivator.php 将模块名映射为布尔值,以 JSON 形式写入 modules_statuses.json(JSON_PRETTY_PRINT)。读取时若文件不存在视为全空;hasStatus() 对未记录模块默认返回"未启用"(即 $status === false 时为 true)。启用/禁用/删除模块都会触发一次 writeJson() 持久化。FileActivatorTest.php 及其快照(snapshots)对状态文件的读写行为有完整覆盖。
八、辅助函数与 Facade
全局辅助函数
src/helpers.php 提供开箱即用的全局函数:
// 判断模块是否启用(默认返回 bool;第二个参数传 true 返回模块实例)
module('Blog'); // bool
module('Blog', true); // Module 实例
// 拼接模块内路径
module_path('Blog', 'Http/Controllers/BlogController.php');
// Vite 资源入口(支持按模块隔离构建目录与热更新文件)
module_vite('Blog', 'resources/js/app.js');
其中 module() 通过 app('modules') 获取仓储实例,模块不存在时安全返回 false。
Module Facade
Module 门面(src/Facades/Module.php)代理到 modules 容器别名,即 LaravelFileRepository,可调用 Module::all()、Module::allEnabled()、Module::find('Blog')、Module::enable('Blog')、Module::assetPath('Blog')、Module::getOrdered() 等方法(完整方法签名见 Facade 的 @method 注释块)。
Blade 指令
src/LaravelModulesServiceProvider.php 在 boot() 中注册了 @module() Blade 指令,用于视图条件渲染:
@module('Blog')
{{-- 仅当 Blog 模块启用时渲染 --}}
@endmodule
版本信息
同一提供者还通过 AboutCommand::add('Laravel-Modules', ...) 把包版本写入 php artisan about 输出,方便在命令行快速核对安装版本。
九、模块内部的结构与标准 ServiceProvider
由 module:make 生成的模块,其 module.json 中的 providers 指向模块自己的 ServiceProvider(见 json.stub 与 ModuleGenerator.php)。包为此提供了基类 src/Support/ModuleServiceProvider.php,它要求子类定义 $name 与 $nameLower 两个属性,并在 boot() 中自动完成:
- 注册模块命令(
$commands数组)与命令调度(通过可选configureSchedules(Schedule $schedule)方法); - 注册翻译(
resource_path('lang/modules/{nameLower}')或模块内lang路径); - 递归合并模块
config/目录下的 PHP 配置(自动去重相邻段,config.php映射到config/{nameLower}.php并支持发布); - 注册视图命名空间与
View\Components组件命名空间; - 加载模块迁移目录。
与之配套的 provider.stub 是生成的 ServiceProvider 模板;web.stub 展示了模块路由文件模板——默认在 auth、verified 中间件组内注册资源路由,并以 $PLURAL_LOWER_NAME$、$LOWER_NAME$ 等占位符完成命名。
十、测试与质量保障
相对已停止维护的 pingpong/modules,测试是 laravel-modules 的核心卖点。仓库测试组织清晰:
- tests/Activators/FileActivatorTest.php:验证启用/禁用后
modules_statuses.json的正确生成; - tests/Commands 下按 Actions、Make、Publish 分组的命令测试,配合大量 快照文件 精确断言生成文件的每一行内容;
- tests/Support、tests/Contracts/RepositoryInterfaceTest.php、tests/HelpersTest.php 覆盖配置读取、仓储契约与辅助函数。
composer.json 的 scripts 提供 composer test(phpunit)、composer lint(pint)等质量入口,require-dev 中还包括 phpstan、php-cs-fixer 与 spatie/phpunit-snapshot-assertions。这意味着你可以放心升级主版本,回归成本由测试体系兜底。
总结
laravel-modules 的核心价值在于:把"目录分块"升级为"自包含模块",并通过 module.json 清单、Composer 合并插件自动加载、Manifest 批量注册、Activator 状态管理四条主线,让模块的创建、启用、禁用、删除与迁移都变得可命令化、可配置化。使用本文档时,请以 README 中的版本兼容表确定安装版本,在 Laravel 11 及以上记住"不再需要 Modules\\ PSR-4 前缀、改用 composer-merge-plugin"这一关键差异,再结合 config/config.php 的配置说明与 src 源码按需定制,即可在大型项目中落地一套稳定、可测试的模块化架构。