mongdch / gaia-framework

1.2.7 2026-11-06 03:06 UTC

Requires

• php: >=7.4.0
• mongdch/mon-console: ^1.1
• mongdch/mon-env: ^1.1
• mongdch/mon-log: ^1.0
• mongdch/mon-util: ^1.5
• workerman/workerman: ^4.1 || ^5.1

MIT

• Mon

• High Performance
• workerman
• multi process
• mon

Published on Packagist.org on 2026-11-06 03:06 UTC

README

基于 workerman 的多进程服务管理框架核心库。

Gaia 负责进程的定义、注册、启动与生命周期管理，并提供控制台指令、配置加载、钩子事件、插件体系和 phar/bin 打包能力，适合构建常驻内存的多进程服务（如 API 服务、队列消费、定时任务、WebSocket 服务等）。

特性

• 多进程管理：基于 gaia\Process 抽象类声明式定义进程，支持进程数、用户、协议、端口复用等配置
• 控制台指令：内置代码生成（make:）、打包（build:）、配置查看等指令，支持自定义指令加载
• 钩子事件：应用与进程全生命周期钩子（app_init / app_start / process_start / process_error 等）
• 插件体系：兼容 webman 风格插件的自动发现与安装（support/**/Bootstrap.php）
• 开发热重载：内置 Monitor 进程监听文件变更自动 reload，并支持进程内存超限自动重启
• 打包分发：一键打包 phar，或结合 workerman 微型 PHP 生成独立二进制文件

环境要求

• PHP >= 7.4
• workerman/workerman ^4.1 || ^5.1
• 依赖组件：mongdch/mon-env、mongdch/mon-log、mongdch/mon-console、mongdch/mon-util

Linux/macOS 下建议安装 posix、pcntl、event（或 libevent/swow 等事件扩展）；Windows 下无需额外扩展，框架会以多入口文件方式运行进程。

安装

composer require mongdch/gaia-framework

安装/升级时框架会通过 gaia\Install 自动发布以下文件到项目根目录：

源文件	目标路径	说明
gaia	gaia	控制台入口脚本
support/app.php	config/app.php	应用默认配置
support/bootstrap.php	support/bootstrap.php	路径常量与错误级别定义
support/Plugin.php	support/Plugin.php	插件安装驱动

快速开始

1. 定义一个进程

在 app/process/ 下创建进程类，继承 gaia\Process：

<?php

namespace app\process;

use gaia\Process;
use Workerman\Worker;

class Demo extends Process
{
    protected static $processConfig = [
        // 监听协议端口，纯后台任务可留空
        'listen'     => 'websocket://0.0.0.0:2346',
        // 进程数
        'count'      => 4,
        // 是否允许进程重载
        'reloadable' => true,
    ];

    public function onWorkerStart(Worker $worker): void
    {
        // 进程启动后的业务初始化
    }

    public function onMessage($connection, $data)
    {
        $connection->send('hello gaia');
    }
}

进程配置支持的完整属性见 gaia\Gaia::$property_map（count / user / group / reloadable / reusePort / transport / protocol / eventLoop），事件回调支持 onConnect / onMessage / onClose / onError / onBufferFull / onBufferDrain / onWebSocketConnect / onWorkerStart / onWorkerStop。

2. 创建启动入口

php gaia make:bin demo

生成的 bin/demo.php 中声明要启动的进程：

protected $process = [
    'demo' => \app\process\Demo::class,
];

3. 启动 / 停止 / 重载

php bin/demo.php start    # 前台启动（开发调试）
php bin/demo.php start -d # 守护进程启动
php bin/demo.php status   # 查看进程状态
php bin/demo.php reload   # 平滑重载
php bin/demo.php stop     # 停止

Linux 环境下未打包 phar 时会自动启动内置 Monitor 进程，监听 app.monitor.paths 中的文件变更并自动 reload；开发中可通过 runtime/gaia/<app>_monitor.lock 锁文件暂停扫描。

Windows 注意：Windows 下不支持多进程计数与信号控制，框架会在 runtime/gaia/windows/ 下为每个进程生成独立启动文件并统一托管，文件变更后自动重启全部子进程。

内置指令

指令	说明
version (v)	查看框架版本号
config:get [node]	查看配置，无参数输出全部配置
make:process <name>...	生成进程类文件到 app/process/
make:cmd <name>...	生成自定义指令类到 app/command/
make:controller <name>...	生成控制器类到 app/controller/
make:dao <name>...	生成 Dao 类到 app/dao/
make:bin <name>...	生成进程启动入口到 bin/
build:phar	将项目打包为 phar（需 phar.readonly=0）
build:bin [php版本]	基于 phar 生成独立二进制可执行文件
vendor:publish <namespace>	执行支持 Gaia 的扩展包 publish 操作

自定义指令放置于 app/command/（由 COMMAND_PATH 定义），框架会自动加载。

配置说明

配置文件位于 config/（由 CONFIG_PATH 定义），核心文件为 config/app.php：

return [
    // 调试模式
    'debug'    => env('APP_DEBUG', true),
    // 时区
    'timezone' => 'PRC',
    // 热重载监控（Monitor 进程）
    'monitor'  => [
        'paths' => [APP_PATH, CONFIG_PATH, SUPPORT_PATH], // 监听目录
        'exts'  => ['php', 'html'],                       // 监听后缀
    ],
    // 框架钩子
    'hooks'    => [
        'app_init'      => [], // 应用初始化
        'app_start'     => [], // 应用启动
        'app_run'       => [], // 进程加载前
        'process_init'  => [], // 进程创建（参数：进程名，进程配置）
        'process_start' => [], // 子进程启动（参数：Worker 实例）
        'process_error' => [], // 进程异常（参数：['worker' => Worker, 'error' => Throwable]）
    ],
    // workerman 全局配置
    'worker'   => [
        'max_package_size' => 10 * 1024 * 1024, // 最大数据包
        'pid_file'         => 'gaia.pid',       // 主进程 PID 文件
        'stdout_file'      => 'stdout.log',     // 守护模式标准输出文件
        'log_file'         => 'workerman.log',  // workerman 日志文件
        'status_file'      => 'gaia.status',    // status 指令结果文件
        'event_loop_class' => '',               // 事件循环类，默认 Select
        'stop_timeout'     => 2,                // 停止超时秒数
    ],
    // phar / bin 打包配置
    'phar'     => [ /* 见 config/app.php 注释 */ ],
];

workerman 运行文件统一存放于 runtime/gaia/workerman/<应用名>/。

钩子事件

钩子在 config/app.php 的 hooks 节点注册，也可通过 mon\util\Event 运行时注册：

Event::instance()->register([
    'process_error' => [MyHook::class, 'handle'],
]);

插件机制

兼容 webman 风格插件。扩展包需满足：

1. 提供命名空间下的 Install 类并定义 GAIA_PLUGIN = true
2. 提供 support/<插件名>/Bootstrap.php 且实现 gaia\interfaces\PluginInterface（start() 方法）

框架启动时（support\Plugin::register()）自动扫描 support/ 下的一级插件目录并依次启动。

打包分发

# 打包 phar
php -d phar.readonly=0 ./gaia build:phar

# 打包独立二进制（自动下载对应版本微型 PHP，默认当前 PHP 版本，最低 8.1）
php -d phar.readonly=0 ./gaia build:bin 8.3

打包细节（排除目录/文件、混淆目录、签名算法、自定义 ini 等）在 config/app.php 的 phar 节点配置。phar 环境下运行时请将 RUNTIME_PATH 指向固定的可写绝对路径。

目录结构（应用项目）

project/
├── app/                # 业务代码
│   ├── command/        # 自定义指令
│   ├── controller/     # 控制器
│   ├── dao/            # Dao
│   └── process/        # 进程类
├── bin/                # 进程启动入口
├── build/              # 打包产物
├── config/             # 配置目录
├── runtime/            # 运行时文件（pid、日志、windows 进程文件等）
├── support/            # 扩展支持库与插件目录
├── gaia                # 控制台入口
└── composer.json

LICENSE

MIT