PHPackages bingcool/swoolefy - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Framework](/categories/framework) 4. / 5. bingcool/swoolefy ActiveProject[Framework](/categories/framework) bingcool/swoolefy ================= swoolefy is a HV Framework based on swoole extension, for everyone use it easily! v6.2.1(3w ago)50964576[2 issues](https://github.com/bingcool/swoolefy/issues)MITPHPPHP ^8.4 Since Apr 27Pushed 2d ago25 watchersCompare [ Source](https://github.com/bingcool/swoolefy)[ Packagist](https://packagist.org/packages/bingcool/swoolefy)[ RSS](/packages/bingcool-swoolefy/feed)WikiDiscussions master Synced yesterday READMEChangelog (10)Dependencies (48)Versions (114)Used By (0) swoolefy ======== [](#swoolefy) ``` ______ _ _ _ _ _ / ____| | | | _ _ _| _ _ | (__ __ __ ___ ___ | | ___ | | | | | | \___ \ \ \ /\ / / / _ \ / _ \ | | / _ \ | |_ _ _ | | | | ____) | \ V V / | (_) | | (_) | | | | ___/ | _ _ _| | |_| | |_____ / \_/\_/ \___/ \___/ |_| \___| | | \__, | |_| | | __ / | |_ _ / ``` [![License](https://camo.githubusercontent.com/8fa57094cbf78aab9cb10b725745aec3fb4769344972c8ac72b333e7cf939646/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f62696e67636f6f6c2f73776f6f6c6566792e737667)](https://packagist.org/packages/bingcool/swoolefy)[![Latest Stable Version](https://camo.githubusercontent.com/e926d131da4b133da81346b644640a30ab1d7eb6347ce385011f61cec59fa762/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f62696e67636f6f6c2f73776f6f6c6566792e737667)](https://packagist.org/packages/bingcool/swoolefy)[![PHP Version Require](https://camo.githubusercontent.com/f2b9f3509ceefe435bb8377c17b5869239c823756356e6f4f21a4cc9514088df/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f62696e67636f6f6c2f73776f6f6c6566792e737667)](https://packagist.org/packages/bingcool/swoolefy)[![Total Downloads](https://camo.githubusercontent.com/e77cfdd7c577c4a08118ec7a56cd895d9401d24e659b89ccb6b55f5e66223129/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f62696e67636f6f6c2f73776f6f6c6566792e737667)](https://packagist.org/packages/bingcool/swoolefy) --- 📑 导航 ---- [](#-导航) - [一、📖 简介](#nav-1-intro) - [🎯 核心特性](#nav-core) - [🏛️ 架构设计](#nav-arch) - [进程模型](#nav-arch-process) - [http 请求处理流程](#nav-arch-http) - [二、📦 版本选择](#nav-2-version) - [三、⚙️ 实现的功能特性](#nav-3-features) - [四、🔌 适配协程环境组件](#nav-4-components) - [五、📚 bingcool/library 组件库](#nav-5-library) - [六、📥 安装](#nav-6-install) - [七、📝 添加 cli.php 入口](#nav-7-cli) - [八、📂 创建 App 项目](#nav-8-create) - [九、🚀 启动 http 应用](#nav-9-start) - [十、🌐 访问](#nav-10-access) - [十一、🧩 定义组件](#nav-11-define) - [十二、💡 使用组件](#nav-12-use) - [十三、⚙️ Protocol/conf.php](#nav-13-protocol) - [十四、🛣️ 路由系统](#nav-14-route) - [十五、⚡ 协程单例](#nav-15-singleton) - [十六、⚡ 协程并发](#nav-16-concurrent) - [十七、🗄️ 数据库操作](#nav-17-db) - [十八、📦 SDK 自动生成](#nav-18-sdk) - [十九、📘 ApiDoc 自动生成](#nav-19-apidoc) - [二十、☁️ Nacos 微服务集成](#nav-20-nacos) --- ### 一、📖 简介 [](#一-简介) swoolefy是一个基于swoole实现的轻量级高性能的常驻内存型的协程级应用服务框架， 高度支持httpApi，websocket，udp服务器，以及基于tcp实现可扩展的rpc服务，worker多进程消费模型 同时支持composer包方式安装部署项目。基于实用主义设计出发，swoolefy抽象Event事件处理类， 实现与底层的回调的解耦，支持协程单例调度，同步|异步调用，全局事件注册，心跳检查，异步任务，多进程(池)，连接池等， 内置`log、session、mysql、pgsql、redis、mongodb、kafka、amqp、uuid、route midelware、cache、queue、rateLimit、traceId`等常用组件等. ### 🎯 核心特性 [](#-核心特性) - ⚡ **高性能**: 基于 Swoole 协程，单机支持数万并发连接 - 🔧 **易扩展**: 自定义进程、进程池、连接池机制 - 🏗️ **多协议**: HTTP/WebSocket/TCP/UDP/MQTT 统一架构 - 🎨 **易用性**: Laravel 风格的路由、中间件、ORM - 🔄 **热更新**: 文件修改自动重启 Worker，无需停机 (开发环境) - 👥 **多进程管理**: - **守护进程 (Daemon)**: 常驻内存，自动拉起多个 Worker 进程，支持进程健康监控和动态扩缩容 - **Cron 计划任务**: 类似 Linux crontab，支持 local/fork/url 三种调度模式，定时执行业务逻辑 - ⚛️ **协程并发**: - **goApp()**: 一键创建协程单例，自动处理 DB/Redis/Curl 等组件的协程隔离 - **Parallel**: 限制最大并发数，防止瞬间创建大量协程拖垮下游服务 - **GoWaitGroup**: 类似 Go 语言的 WaitGroup，优雅的协程同步等待机制 - 📦 **组件化**: - **bingcool/library** 大量常用协程组件库 @see - ☁️ **Nacos 微服务集成**: - **配置变更监听**: 长轮询 Nacos 配置，拉取最新内容写入 `APP_PATH/.env`，自动执行 `restart --force` 使 Worker 加载新配置 - **服务注册**: 应用实例注册到 Nacos 注册中心，支持心跳保活（`application.yaml` → `nacos.service_register`） - **服务发现**: `DiscoveryClient` 拉取健康实例，内置 `random` / `round_robin` / `weight` 负载均衡 - **SDK 服务发现**: `gen:sdk` 生成的 API 客户端在未传入 Guzzle Client 时，自动通过 Nacos 解析目标服务 `base_uri`（`serviceName` 在生成时从 `application.yaml` 注入） ### 🏛️ 架构设计 [](#️-架构设计) ### 进程模型 [](#进程模型) ``` ┌─────────────────────────────────────────────────────┐ │ Master Process (主进程) │ │ - 管理 Reactor 线程 │ │ - 接收并分发客户端连接 │ └──────────────┬──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Master Process (主进程) │ │ - 管理 Reactor 线程 │ │ - 接收并分发客户端连接 │ └──────────────┬──────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Manager Process (管理进程) │ │ - 管理 Worker 进程池 │ │ - 管理 Task 进程池 │ │ - 管理自定义进程 (通过 addProcess 拉起) │ │ - 进程重启和监控 │ └──────────┬────────────────────┬─────────────────────────┘ │ │ ├───────────┬────────┴──────────┐ │ │ │ ┌──────▼──────┐ ┌──▼──────────┐ ┌──────▼──────────┐ │ Worker │ │ Task │ │ User Process │ │ Processes │ │ Processes │ │ (MainProcess) │ │ (业务处理) │ │ (异步任务) │ │ (管理进程) │ │ │ │ │ │ │ │ - onRequest │ │ - onTask │ │ 通过 MainManager │ │ - onConnect │ │ │ │ 拉起多个 Worker │ │ - onReceive │ │ │ │ │ │ │ │ │ │ - Cron 任务管理 │ │ 协程池/组件池 │ │ │ │ - Daemon 常驻 │ │ - DB 连接池 │ │ │ │ - 动态进程管理 │ │ - Redis 池 │ │ │ │ │ │ - Curl 池 │ │ │ │ run() -> start() │ └─────────────┘ └─────────────┘ └──────┬──────────┘ │ ┌────────────────┼───────────────┐ │ │ │ ┌──────▼─────┐ ┌──────▼─────┐ ┌──────▼─────┐ │ Cron │ │ Daemon │ │ Script │ │ Workers │ │ Workers │ │ Workers │ │ (定时任务) │ │ (常驻进程) │ │ (脚本) │ │ │ │ │ │ │ │ - 定时调度 │ │ - 消息消费 │ │ - 临时脚本 │ │ - 任务队列 │ │ - 数据处理 │ │ - 数据迁移 │ │ - URL请求 │ │ - 实时计算 │ │ - 修复工具 │ └────────────┘ └────────────┘ └────────────┘ ``` **进程层级说明:** 1. **Master Process**: 最高层级，管理 Reactor 线程和连接分发 2. **Manager Process**: 第二层级，统一管理所有子进程 3. **Worker/Task/User Process**: 第三层级，由 Manager 直接管理 4. **Cron/Daemon/Script Workers**: 第四层级，由 User Process (MainProcess) 通过 `MainManager::start()` 拉起 ### http请求处理流程 [](#http请求处理流程) ``` Client Request ↓ ┌────────────────────────┐ │ Swoole HTTP Server │ │ (Reactor 线程接收) │ └───────────┬────────────┘ │ ↓ ┌────────────────────────┐ │ Worker Process │ │ (onRequest 回调) │ └───────────┬────────────┘ │ ↓ ┌────────────────────────┐ │ 1. App::__construct() │ │ - 加载配置 │ │ - 初始化协程 ID │ └───────────┬────────────┘ │ ↓ ┌────────────────────────┐ │ 2. App::run() │ │ - parseHeaders() │ │ - initCoreComponent()│ │ - Application::setApp()│ ← 绑定到协程上下文 │ - defer() │ ← 注册清理钩子 └───────────┬────────────┘ │ ↓ ┌────────────────────────┐ │ 3. HttpRoute::dispatch()│ │ - 加载路由配置 │ │ - 匹配路由 │ └───────────┬──────────── ┘ │ ↓ ┌────────────────────────────────┐ │ 4. 执行中间件 (Middleware) │ │ - beforeHandle (前置中间件) │ │ - 验证/鉴权/CORS 等 │ │ - 请求参数处理 │ └───────────┬────────────────────┘ │ ↓ ┌────────────────────────────────┐ │ 5. 调用控制器 Action │ │ - Controller::action() │ │ - 业务逻辑处理 │ └───────────┬────────────────────┘ │ ↓ ┌─────────────────────────────────────┐ │ 6. 执行业务 (Business Logic) │ │ │ │ ┌─────────────────────────────┐ │ │ │ goApp(function() { │ │ │ │ // 协程并发处理 │ │ │ │ - DB 查询 │ │ │ │ - Redis 操作 │ │ │ │ - HTTP 请求 │ │ │ │ - 文件 IO │ │ │ │ }) │ │ │ │ │ │ │ │ Parallel::run(50, $list, │ │ │ │ function($item) { │ │ │ │ // 限制并发数处理 │ │ │ │ } │ │ │ │ ) │ │ │ └─────────────────────────────┘ │ │ │ │ - 协程调度器自动切换 │ │ - IO 密集型任务异步执行 │ │ - CPU 继续执行其他协程 │ └───────────┬────────────────────────┘ │ ↓ ┌────────────────────────┐ │ 7. 后置中间件 │ │ - afterHandle │ │ - 响应格式化 │ │ - 日志记录 │ └───────────┬────────────┘ │ ↓ ┌────────────────────────┐ │ 8. App::end() │ │ - handleLog() │ │ - pushComponentPools()│ ← 归还连接池 │ - clearComponent() │ │ - response->end() │ └───────────┬────────────┘ │ ↓ Client Response ``` --- ### 二、📦 版本选择 [](#二-版本选择) #### 6.x 版本 (推荐 - 最新稳定版) [](#6x-版本-推荐---最新稳定版) **最低要求:** - PHP >= 8.4 - Swoole >= 6.1 (推荐使用 Swoole 6.x 最新版本) #### 4.9 LTS 版本 (长期维护版) [](#49-lts-版本-长期维护版) **最低要求:** - PHP 7.3 ~ 7.4 - Swoole 4.8.x (推荐 4.8.13+) **选择哪个版本?** 1、如果确定项目是使用php81+的，那么直接选择 `swoole > 6.1.x，推荐直接使用 swoole-6.2.0+ 以上最新版本更好` 安装，然后选择 `bingcool/swoolefy:^6.1` 作为项目分支安装最新稳定版本 2、如果确定项目是使用 `php7.3 ~ php7.4` 的，那么选择 swoole-v4.8+ 版本来进行编译安装(不能直接使用 swoole-cli-v4.8+ 了, 因为其内置的是php8.1，与你的项目的php7不符合) 所有只能通过编译swoole源码的方式来生成swoole扩展，然后选择 `bingcool/swoolefy:^4.9` 作为项目分支稳定版本 3、依赖编译： ./configure --enable-openssl --enable-sockets --enable-swoole-curl --enable-swoole-pgsql --enable-swoole-stdext --enable-iouring 4、若不希望自己编译构建，也可以直接使用本目录下的Dockerfile来构建镜像: ``` // 构建镜像 docker build --no-cache -t swoolefy-php84-swoole62:v1 -f ./php84-swoole62-io-uring.Dockerfile . // 启动容器(开发环境下 --security-opt seccomp=unconfined的作用是禁用这个默认配置，让容器内的进程可以使用所有系统调用比如io_uring) // 生产环境下建议使用配置文件方式 --security-opt seccomp=./seccomp_profile.json // @see https://github.com/moby/moby/blob/v28.3.3/profiles/seccomp/default.json docker run -d -it --security-opt seccomp=unconfined -p 9501:9501 -p 9502:9502 -v /host_mnt/Users/macbook/Documents/wwwphp:/home/wwwroot --name=swoolefy-php84-v62 swoolefy-php84-swoole62:v1 ``` ### 三、⚙️ 实现的功能特性 [](#三️-实现的功能特性) #### 基础特性 [](#基础特性) - 支持架手脚一键创建项目自动生成最小项目骨架 - 支持swagger一键生成api文档 - 支持分组路由, 路由中间件middleware, 前置路由组件, 后置路由组件middleware,多模块应用 - 支持扫描Router路由配置自动生成PHP SDK，自动提取 Request/Response DTO，生成类型安全的客户端SDK代码 - 支持按模块扫描Router路由配置自动生成open-api协议的swagger的API文档 - 支持自定义注册不同根命名空间，快速多项目部署 - 支持httpServer，实用轻量Api接口开发 - 支持多协议websocketServer、udpServer、mqttServer - 支持基于tcp实现的rpc服务，开放式的系统接口，可自定义协议数据格式，并提供rpc-client协程组件 - 支持DI容器，组件IOC、配置化，Channel公共组件池 - 支持协程单例注册,协程上下文变量寄存 - 支持mysql、postgreSql、redis协程组件 - 支持全局logger组件，包括system log, runtime log, request log, sql log - 支持opentelemetry的trace链路追踪组件 - 支持分布式锁组件 - 支持滑动窗口的流量速率组件 - 支持mysql协程连接池 - 支持redis协程池 - 支持curl协程池 - 支持protobuf buffer的数据接口结构验证，压缩传输等 - 支持异步务管理TaskManager - 定时器管理TickManager - 内存表管理TableManager - 支持自定义进程管理ProcessManager，进程池管理PoolsManger - 支持底层异常错误的所有日志捕捉,支持全局日志,包括debug、info、notice、warning、error等级 - 支持自定义进程的redis，rabbitmq，kafka的订阅发布，消息队列等 - 支持热更新reload worker 监控以及更新 - 支持定时的系统信息采集，并以订阅发布，udp等方式收集至存贮端 - 支持命令行形式高度封装启动|停止控制的脚本，简单命令即可管理整个框架, 并对外提供控制启动|停止|重启|查看状态的api接口，可开发成可视化控制页面 ##### 高级特性 [](#高级特性) - 支持cron计划任务模式. 类似crontab，支持local|fork|remote url三种方式 支持方式说明local自定义进程内定时执行代码fork自定义进程定时拉起一个新的进程，由新的进程去执行任务，可异步，类似laravel的schedule计划任务url自定义进程定时发起远程url请求，可设置callback回调处理结果 - 支持daemon模式.worker下后台daemon模式的多进程协程消费模型,包括进程自动拉起，进程数动态调整，进程健康状态监控 - 支持console终端脚本模式. 跑完脚本自动退出，可用于修复数据、数据迁移等临时脚本功能 - **Nacos 配置中心与服务治理**（`Swoolefy\Support\Nacos`，详见 [src/Support/Nacos/README.md](src/Support/Nacos/README.md)） 创建应用（`php cli.php create App`）时会自动生成 `APP_PATH/application.yaml` 模板；Nacos 连接信息放在 `APP_PATH/nacos.yaml`。 文件说明`APP_PATH/nacos.yaml`Nacos **服务器连接**（host、port、data\_id、username/password 等）`APP_PATH/application.yaml`**应用行为**：`service_register`、`discovery_service_client`、`monitor_config_change`能力说明主要类配置变更监听长轮询配置 → 写入 `.env` → 后台 `cli.php restart {App} --force=1``NacosMonitor`、`ConfigWatcher`（见 [Monitor/README.md](src/Support/Nacos/Monitor/README.md)）服务注册注册实例到 Nacos 并定时心跳`ServiceRegister`服务发现实例列表缓存 + 负载均衡选节点`DiscoveryClient`、`DiscoveryConfig`、`LoadBalancerFactory`SDK 服务发现`gen:sdk` 生成客户端，未传 Guzzle 时自动 Nacos 发现 `base_uri``BaseClientApi`、`SdkNacosServiceDiscovery`（sdk自动生成）自定义进程示例（`Event.php` 中注册）： ``` // 配置变更监听重启服务 ProcessManager::getInstance()->addProcess( 'nacos-config-change-reload', \App\Process\NacosProcess\NacosConfigReload::class, true, [], null, true, ); // 服务注册 + 心跳 ProcessManager::getInstance()->addProcess( 'nacos-service-register', \App\Process\NacosProcess\NacosServiceRegister::class, true, [], null, true, ); ``` 服务发现代码示例： ``` use Swoolefy\Support\Nacos\Discovery\DiscoveryClient; use Swoolefy\Support\Nacos\NacosConfig; $client = DiscoveryClient::create('my-service', NacosConfig::load()); $uri = $client->chooseUri(); ``` ### 四、🔌 适配协程环境组件 [](#四-适配协程环境组件) 组件名称安装说明prediscomposer require predis/predis:~1.1.7predis组件、或者Phpredis扩展mongodbcomposer require mongodb/mongodb:~1.3mongodb组件，需要使用mongodb必须安装此组件rpc-clientcomposer require bingcool/rpc-client:dev-masterswoolefy的rpc客户端组件，当与rpc服务端通信时，需要安装此组件，支持在php-fpm中使用cron-expressioncomposer require dragonmantank/cron-expression:~3.3.0crontab计划任务组件，类似Linux的crobtabredis lockcomposer require malkusch/lockRedis锁组件amqpcomposer require php-amqplib/php-amqplib:~3.7.0amqp php原生实现amqp协议客户端ffmpegcomposer require php-ffmpeg/php-ffmpeg:~1.4.0php proc-open 调用ffmpeg处理音视频imagecomposer require intervention/image:~3.11.0php 图像处理组件validatecomposer require vlucas/valitronvalidate数据校验组件guzzlehttpcomposer require guzzlehttp/guzzle:~7.9.0guzzlehttp 组件oauth 2.0composer require league/oauth2-serveroauth 2.0 授权认证组件php-standard-librarycomposer require php-standard-library/php-standard-libraryphp标准库(推荐)bingcool/librarycomposer require bingcool/librarylibrary组件库 ### 五、📚 bingcool/library 是 swoolefy require 内置库，专为 swoole 协程实现的组件库 [](#五-bingcoollibrary-是-swoolefy-require-内置库专为-swoole-协程实现的组件库) 实现了包括： - Db ORM Model 组件(支持mysql、 postSql、 sqlite、 Oracle) - DB Query Builder 链式操作查询组件 - Kafka Producer Consumer组件 - Rabbitmq Queue组件 - Rabbitmq Delay Queue 死信延迟队列组件 - Redis Cache组件 - Redis Queue队列组件 - Redis Delay Queue延迟队列组件 - RedisLock锁组件 - RateLimit限流组件 - Redis Public Subscribe组件 - Db、Redis、 Curl协程连接池组件 - UUid 分布式自增id组件 - OpenTelemetry 链路追踪组件 - nacos 服务注册、服务发现、服务配置组件 - Curl基础组件 - Jwt 组件 - Validate 组件 - Encrypt 加密解密组件 - Captcha 验证码组件 - Translation 国际化（I18N） github: ### 六、📥 安装 [](#六-安装) #### 1、先配置环境变量(必须设置) [](#1先配置环境变量必须设置) ``` // 独立物理机或者云主机配置系统环境变量 vi /etc/profile 在/etc/profile末尾添加一行，标识环境变量，下面是支持的4个环境,框架将通过这个环境变量区分环境，加载不同的配置 export SWOOLEFY_CLI_ENV='dev' // 开发环境 export SWOOLEFY_CLI_ENV='test' // 测试环境 export SWOOLEFY_CLI_ENV='gra' // 灰度环境 export SWOOLEFY_CLI_ENV='prd' // 生产环境 // 最后是配置生效 source /etc/profile ``` ``` // 如果是通过dockerfile 创建容器的, 可以根据不同环境生成的内置环境变量不同镜像，每个不同的环境镜像可以用在不同环境，代码将通过这个环境变量区分环境，加载不同的配置 ENV SWOOLEFY_CLI_ENV=dev ``` #### 2、创建项目 [](#2创建项目) ``` // 下载代码到到你的自定义目录，这里定义为myproject, 新建composer.json { "name": "project/order-service", "description": "description", "minimum-stability": "dev", "prefer-stable": true, "license": "proprietary", "require": { "bingcool/swoolefy": "~6.2", "bingcool/library": "dev-library-6.x" } } // 终端执行安装 composer install ``` ### 七、📝 添加项目入口启动文件 `cli.php`, 并定义你的项目目录，命名为 `App` [](#七-添加项目入口启动文件-cliphp-并定义你的项目目录命名为-app) ```