# hyperf-modules

**Repository Path**: ycgpp/hyperf-modules

## Basic Information

- **Project Name**: hyperf-modules
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-09
- **Last Updated**: 2026-04-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# hyperf-modules

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

## 功能特性

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

## 安装

```bash
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 示例

```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

| 方法 | 返回值 | 说明 |
|------|--------|------|
| `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` 独立合并，避免递归合并导致字符串键被覆盖为数组

## 测试

```bash
composer test
```

## 代码分析

```bash
composer analyse
```

## 环境要求

- PHP >= 8.1
- Hyperf ~3.1

## 许可证

MIT License