README

Hyperf 本地模块发现与管理工具。自动扫描 modules/ 目录下的模块，聚合各模块的 ConfigProvider、数据库迁移路径和 Seeder 路径。

功能特性

自动模块发现 — 扫描项目 modules/ 目录下所有包含 composer.json 的子目录，按名称排序确保加载顺序一致
ConfigProvider 聚合 — 读取各模块 extra.hyperf.config，安全递归合并配置（dependencies 独立处理避免键覆盖）
迁移路径聚合 — 自动注册各模块 databases/migrations 目录到 Migrator
Seeder 路径聚合 — 自动收集各模块 databases/seeders 目录
单次扫描 — ModuleLoader 采用静态缓存，生命周期内仅扫描一次文件系统
零配置 — 只需将模块放入 modules/ 目录即可

安装

composer require molong/hyperf-modules

使用方法

1. 模块目录结构

在 Hyperf 项目根目录下创建 modules/ 目录，每个模块一个子目录：

project/
├── app/
├── modules/
│   ├── user/
│   │   ├── composer.json
│   │   ├── src/
│   │   │   └── ConfigProvider.php
│   │   └── databases/
│   │       ├── migrations/
│   │       └── seeders/
│   └── order/
│       ├── composer.json
│       └── src/
│           └── ConfigProvider.php
└── composer.json

2. 模块 composer.json 示例

{
    "name": "module/user",
    "autoload": {
        "psr-4": {
            "Module\\User\\": "src/"
        }
    },
    "extra": {
        "hyperf": {
            "config": "Module\\User\\ConfigProvider"
        }
    }
}

3. 配置自动生效

本包通过 extra.hyperf.config 注册了自身的 ConfigProvider，Hyperf 框架启动时会自动：

扫描 modules/ 目录下所有 composer.json
解析模块元信息（名称、命名空间、ConfigProvider）
实例化并合并各模块的 ConfigProvider（dependencies 单独 array_merge 防止递归覆盖）
注册所有模块的迁移和 Seeder 路径

API

ModuleLoader

方法	返回值	说明
`scan(string $basePath = '')`	`array`	扫描模块目录，返回模块列表（已扫描则直接返回缓存）
`isLoaded()`	`bool`	是否已完成扫描
`hasModule(string $name)`	`bool`	检查模块是否存在
`getModule(string $name)`	`?array`	获取单个模块信息
`getModules()`	`array`	获取所有已扫描模块
`getConfigProviders()`	`list<string>`	获取所有模块的 ConfigProvider FQCN
`getMigrationPaths()`	`list<string>`	获取所有模块的迁移目录
`getSeederPaths()`	`list<string>`	获取所有模块的 Seeder 目录
`reset()`	`void`	重置扫描状态

MigratorFactory

工厂类，自动聚合主项目、本包及所有模块的迁移路径，注入到 Hyperf Migrator。仅在未扫描时触发 scan()。

SeedFactory

通过 SeedFactory::paths() 获取主项目和所有模块的 Seeder 目录路径列表。

配置合并策略

ConfigProvider 在合并各模块配置时：

通用配置（annotations、commands、listeners 等）使用 array_merge_recursive 递归合并
dependencies 使用 array_merge 独立合并，避免递归合并导致字符串键被覆盖为数组

测试

composer test

代码分析

composer analyse

环境要求

PHP >= 8.1
Hyperf ~3.1

许可证

MIT License

molong / hyperf-modules

Maintainers

Package info

Statistics

Security