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 框架启动时会自动：

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

API

ModuleLoader

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