# monitor

**Repository Path**: fiberphp/monitor

## Basic Information

- **Project Name**: monitor
- **Description**: 📊 FiberPHP 开发辅助监控组件 —— 文件变更自动重载、内存超限保护，开发环境必备，开箱即用。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FiberPHP Monitor

FiberPHP 框架的开发环境监控子包。提供文件变更监控（热重载）与 Worker 进程内存监控两项能力，帮助开发者在编码时即时看到代码改动生效，并在生产环境防止内存泄漏导致进程僵死。

## 特性

- **文件变更监控**：递归扫描监听目录，按扩展名过滤，文件改动后向主进程发送 `SIGUSR1` 触发 Worker reload（仅限 Unix 环境）
- **语法校验**：reload 前调用 `php -l` 校验改动文件，语法错误不会触发 reload，避免主进程被坏代码打挂
- **内存监控**：定时读取 `/proc/<pid>/status` 的 `VmRSS`，超过阈值向子进程发送 `SIGINT` 优雅重启
- **暂停 / 恢复**：通过 `runtime/monitor.lock` 文件实现 pause / resume，便于在部署或批处理期间临时关闭 reload
- **自动禁用**：`exec()` 被禁用时自动关闭文件监控并提示，内存监控仍可独立工作
- **进程感知**：通过 `/proc/<ppid>/cmdline` 校验父进程确实为 PHP/WorkerMan，避免误杀

## 环境要求

- PHP >= 8.3
- `ext-posix`
- `fiberphp/discovery` dev-master
- `fiberphp/support` dev-master
- `workerman/workerman` ^5.1（Monitor 作为 Worker 进程运行）
- 文件监控与内存监控均依赖 Linux `/proc` 文件系统，非 Linux 环境自动降级

## 安装

```bash
composer require fiberphp/monitor
```

安装后通过 `PackageManifest` 注册 Monitor 进程；进程配置 `config/process/monitor.php` 属保留目录（不进配置合并），由安装钩子幂等发布到应用 `config/process/monitor.php`（已存在则不覆盖）。

## 配置

`config/process/monitor.php`：

```php
use FiberPHP\Monitor\Monitor;

global $argv;

return [
    'Monitor' => [
        'enable'      => true,
        'handler'     => Monitor::class,
        'reloadable'  => false,
        'constructor' => [
            // 监控这些目录
            'monitorDir' => array_merge([
                app_path(),
                config_path(),
                base_path() . '/process',
                base_path() . '/.env',
            ]),
            // 监控这些扩展名的文件
            'monitorExtensions' => [
                'php', 'html', 'htm', 'env',
            ],
            'options' => [
                'enable_file_monitor'   => !in_array('-d', $argv) && DIRECTORY_SEPARATOR === '/',
                'enable_memory_monitor' => DIRECTORY_SEPARATOR === '/',
            ],
        ],
    ],
];
```

| 字段                            | 说明                                                          |
|---------------------------------|---------------------------------------------------------------|
| `enable`                        | 是否启用 Monitor 进程                                         |
| `handler`                       | 进程处理类，固定为 `FiberPHP\Monitor\Monitor`                 |
| `reloadable`                    | Monitor 进程自身是否参与 reload（通常为 false）               |
| `monitorDir`                    | 监控目录列表，支持字符串或数组                                |
| `monitorExtensions`             | 监控的文件扩展名白名单                                        |
| `options.enable_file_monitor`   | 是否启用文件变更监控                                          |
| `options.enable_memory_monitor` | 是否启用内存监控                                              |
| `options.memory_limit`          | 内存阈值（MB），缺省读取 `php.ini` 的 `memory_limit` 并取 80% |

## 使用

### 启动

Monitor 作为 FiberPHP 进程随主程序一同启动，无需单独调用。开发环境运行：

```bash
php start.php start
```

### 文件热重载

编辑 `app/`、`config/`、`process/` 或 `.env` 下被监听扩展名的文件并保存，Monitor 检测到变更后会输出：

```
/path/to/file.php updated and reload
```

并向主进程发送 `SIGUSR1`，Workerman 自动 reload 所有 Worker。

### 内存超限重启

当某个 Worker 子进程的 `VmRSS` 超过 `memory_limit`，Monitor 向其发送 `SIGINT`，Workerman 会重新拉起该子进程。

### 暂停 / 恢复

在部署、批处理或不想被打断的场景下，可通过锁文件暂停监控：

```php
use FiberPHP\Monitor\Monitor;

Monitor::pause();     // 创建锁文件，停止文件与内存检查
Monitor::isPaused();  // 是否已暂停
Monitor::resume();    // 删除锁文件，恢复监控
```

## 注意事项

- 文件监控依赖 `exec()` 执行 `php -l`，若 `disable_functions` 禁用了 `exec`，文件监控自动关闭
- 只能 reload 由 composer autoload 加载的文件，`get_included_files()` 中先于 autoload 加载的文件改动后不会触发
  reload（会输出提示）
- 单个监控目录文件数超过 1000 时会输出告警，建议收窄监控范围
- 内存监控读取 `/proc/<pid>/status`，仅在 Linux 下生效

## License

[MIT](LICENSE)