轻量、高性能、安全的 PHP 8.3 框架
A lightweight, high-performance, secure PHP framework
官网 · 快速开始 · 架构 · English · 文档分析
FssPHP 以 framework/ 为内核,组合 Symfony 7 组件、Workerman 常驻进程、ThinkPHP / Laravel 生态能力,形成一套可在 PHP-FPM 与 Workerman(以及可选 Swoole)之间共用同一套业务代码的现代 PHP 框架。本仓库既是框架本体,也是最佳实践示例项目。
性能与运行时
- 同一套控制器 / 服务代码,可在 PHP-FPM、Workerman HTTP、可选 Swoole 之间切换
- Workerman 同时提供 HTTP(默认
8000)、AI HTTP(8001)、WebSocket(1234)、SSE、Redis 队列消费者 - 生产环境编译 Symfony DI 容器与路由缓存;路由命中走 PSR-16 缓存
路由与请求处理
- 三种路由并存:
config/routes.php手动定义、PHP 8 Attribute、约定式自动路由 - 优先级:手动路由 > 属性路由 > 插件自动路由 > 应用前缀自动路由
- 洋葱模型中间件:全局栈 → 应用栈 → 路由 / 注解中间件
- 内置 CSRF、CORS、XSS 过滤、Referer 校验、IP 黑名单、限流、安全响应头、方法伪装
开发体验
- Symfony DI + Laravel 风格门面:
App::make()/app() - 属性注入
#[Autowire]/#[Inject]/#[Context] - Controller → Service → DAO 三层,基类提供 REST CRUD Trait
- 双 ORM:ThinkORM 与 Laravel Eloquent,通过
config/database.php的engine切换 - 双模板:Twig 与 ThinkTemplate
- 多应用:
config/apps.php配置独立命名空间、URL 前缀、可选域名绑定 - 插件系统:安装 / 启用 / 市场 / 迁移,CLI 一键生成脚手架
安全与基础设施
- Casbin RBAC、lcobucci/jwt(强制强密钥)、phpseclib
- 多租户上下文(Session / JWT)与模型 Scope
- PSR-14 事件、Monolog 日志、think-validate 校验
- Redis 连接池 / MySQL 连接池(Workerman 进程内)
| 类别 | 技术 |
|---|---|
| 语言 | PHP ^8.3,强制 declare(strict_types=1) |
| HTTP 运行时 | Workerman ^5.2 / PHP-FPM / 可选 Swoole |
| HTTP 抽象 | Symfony HttpFoundation / HttpKernel ^7.4 |
| 路由 | Symfony Routing + PHP 8 Attributes |
| DI | Symfony DependencyInjection(PSR-11)+ Framework\Core\App 门面 |
| ORM | ThinkORM ^4.0 或 Illuminate Database / Eloquent ^12.58 |
| 模板 | Twig ^3.x + ThinkTemplate |
| 缓存 | Symfony Cache + ThinkCache + Predis |
| 安全 | Casbin、lcobucci/jwt、HTMLPurifier、CSRF Token |
| 日志 / 校验 / 事件 | Monolog、think-validate、PSR-14 |
| 其它 | Guzzle、Intervention Image、Ramsey UUID、Symfony Translation |
- PHP 8.3+(
composer.json强制^8.3) - Composer 2.x
- MySQL 5.7+ / 8.x
- Redis(Session、缓存、队列推荐)
- Linux / macOS 推荐;Windows 下 Workerman 的 AI HTTP 与队列需拆分为
server-ai.php、queue.php
git clone https://github.com/xuey490/project.git
cd project
composer install
cp .env.example .env编辑 .env,设置 长度 ≥ 32 字节 的 JWT_SECRET(未设置或密钥过弱时 JWT 组件会拒绝启动):
php -r "echo 'base64:'.base64_encode(random_bytes(48)), PHP_EOL;"数据库账号、库名、主机写在 config/database.php(当前默认 ORM 为 laravelORM,连接默认为 127.0.0.1 / fssoa / root)。.env 里的 DB_*、ORM_DRIVER 尚未接到该文件,改环境变量不会改变实际连接。导入 database/sql/ 下的初始化脚本,或按项目迁移流程执行 database/migrate.php。
php -S localhost:8000 -t public浏览器打开 http://localhost:8000。
php server.php start # 前台
php server.php start -d # 守护进程
php server.php status
php server.php reload
php server.php stop默认服务:
| 服务 | 地址 |
|---|---|
| HTTP | http://0.0.0.0:8000 |
| AI HTTP | http://0.0.0.0:8001(/api/ai/*) |
| WebSocket | ws://0.0.0.0:1234 |
| 健康检查 | GET /_health |
热重载脚本
watch.php已被忽略、不随仓库分发。开发期请用php server.php start或 PHP 内置服务器。
将 Web 根目录指向 public/,其余请求转发到 public/index.php(仓库已提供 public/.htaccess)。
project/
├── app/ # 业务代码(多应用:default / admin / system / test)
│ ├── Controllers/ # 默认应用控制器
│ ├── admin/ # 管理后台
│ ├── system/ # 系统 API
│ ├── Dao/ # 数据访问层(自动注册为 DI 服务)
│ ├── Middlewares/ # 应用中间件
│ ├── Providers/ # 应用服务提供者(自动发现)
│ └── function.php
├── config/ # 配置中心
│ ├── app.php / apps.php # 应用与多应用
│ ├── routes.php # 手动路由
│ ├── services.php # Symfony DI 定义
│ ├── database.php # 双 ORM 与连接
│ ├── middleware.php # 中间件参数
│ └── plugin/ # 插件配置
├── framework/ # 框架内核(见下一节)
├── plugins/ # 插件(blog、bbs 示例)
├── public/index.php # FPM / 内置服务器入口
├── resource/ # 视图与翻译
├── database/ # SQL 与迁移
├── storage/ # 缓存、日志、视图编译
├── tests/Unit/ # PHPUnit
├── server.php # Workerman 入口
├── server-ai.php # Windows 独立 AI Worker
├── queue.php # 独立队列消费者
├── swoole.php # 可选 Swoole 入口
└── novaphp # CLI
framework/ 是框架本体,按职责拆成独立模块。启动链路:
public/index.php 或 server.php
│
▼
Framework::getInstance()
├── 注册多应用 PSR-4
├── Container::init() # .env + services.php,prod 编译缓存
├── Kernel::boot() # 时区、异常处理、App 门面
├── PluginManager # 加载已启用插件
├── loadAllRoutes() # 手动 → Attribute → 缓存
└── MiddlewareDispatcher # 洋葱调度
│
▼
Router::match() → 控制器 → Response
| 目录 | 职责 |
|---|---|
| Core | Framework 单例、Kernel、Router、AttributeRouteLoader、App 门面 |
| Container | Symfony DI 封装:.env、Provider register/boot、生产环境 PhpDumper |
| Attributes | #[Route]、GetMapping/PostMapping 等 REST 映射,以及 Auth、Role、Permission、Middlewares、Validate、Cache、Log |
| Middleware | 洋葱调度器 + CSRF / CORS / XSS / 限流 / IP 封禁 / Referer / 安全头 等内置中间件 |
| Basic | BaseController / BaseService / BaseDao / BaseJsonResponse,CRUD Trait,双 ORM 基模型与租户 Scope |
| DI | Injectable Trait,#[Autowire] / #[Inject] / #[Context] 属性注入 |
| ORM | ThinkORM / Eloquent 适配工厂 |
| Repository | 与 DAO 并行的仓储层,ThinkStrategy / EloquentStrategy 屏蔽语法差异 |
| Event | PSR-14 Dispatcher + #[EventListener] 扫描 |
| Plugin | 插件发现、清单、缓存、市场、迁移 |
| Providers | 框架级服务提供者(Request、Session、Cache、JWT、Twig、ThinkTemplate、Validate…) |
| Security | Casbin RBAC、CSRF Token |
| Tenant | 请求级租户上下文(Session / JWT) |
| Cache / Session / Validation / View / Translation | 缓存、会话、校验、双模板、i18n |
| Http | Workerman SSE(SseResponse / SseEmitter) |
| Pool / Queue / Schema | 连接池、Redis 队列、模型 Schema 预热 |
| Console | novaphp 脚手架与插件命令 |
| Utils | JWT 工厂、验证码、Cookie、JSON、日期等 |
| helpers.php | app()、config()、view()、cache_*、EventDispatch() 等全局函数 |
应用层约定:
Controller → Service(事务 / 业务) → Dao / Repository(ORM)
控制器继承 BaseController,通过 $serviceClass 自动解析服务,不必手写构造函数。
<?php
declare(strict_types=1);
namespace App\Controllers;
use Framework\Attributes\Auth;
use Framework\Attributes\Role;
use Framework\Attributes\Route;
use Framework\Basic\BaseController;
use Symfony\Component\HttpFoundation\JsonResponse;
#[Route(prefix: '/api/v1/users')]
class UserController extends BaseController
{
protected string $serviceClass = \App\Services\UserService::class;
#[Route(path: '/profile', methods: ['GET'], name: 'users.profile')]
#[Auth]
public function profile(): JsonResponse
{
return $this->success($this->service->current());
}
#[Route(path: '/{id}', methods: ['DELETE'], requirements: ['id' => '\d+'])]
#[Auth]
#[Role(roles: ['admin'])]
public function destroy(int $id): JsonResponse
{
$this->service->delete($id);
return $this->success(['id' => $id]);
}
}也可在 config/routes.php 用 Symfony RouteCollection 手动注册,或依赖 /Controller/Action 自动推断。
use Framework\Core\App;
$users = App::make(UserService::class);
$redis = app('redis');Service / DAO 属性上使用 #[Autowire] 即可,基类构造时会调用 inject()。
| 助手函数 | 作用 |
|---|---|
app($id) |
解析容器服务 |
config('app.debug') |
点分配置 |
view('index.twig', $data) |
Twig 渲染 |
ThinkView('index', $data) |
ThinkTemplate 渲染 |
cache_get / cache_set |
Symfony Cache |
EventDispatch($event) |
派发 PSR-14 事件 |
WebCsrfField() |
表单 CSRF 隐藏域 |
BaseController / BaseJsonResponse 提供统一信封:success()、fail()、error()、unauthorized()、csrfExpired()。
在 config/apps.php 增加一项即可,无需改 composer.json 或 dump-autoload:
'system' => [
'dir' => BASE_PATH . '/app/system/Controllers',
'namespace' => 'App\System\Controllers',
'prefix' => 'system', // /system/controller/action
'domain' => '', // 可选:system.example.com
],路由优先级:定义路由 > 插件自动路由 > 前缀自动路由 > 域名绑定自动路由 > 默认命名空间。
| 模式 | 命令 | 说明 |
|---|---|---|
| 内置服务器 | php -S localhost:8000 -t public |
快速开发 |
| FPM | Web 根目录 → public/ |
Apache / Nginx |
| Workerman | php server.php start |
HTTP + WS + 队列;Linux 同时监听 8000/8001 |
| Workerman AI | php server-ai.php start |
Windows 独立 AI 进程 |
| 队列 | php queue.php start |
独立 Redis LIST 消费者 |
| Swoole | swoole-cli swoole.php start |
可选;勿与 Workerman 抢同一端口 |
Workerman 进程启动时会初始化 MySQL / Redis 连接池,并对模型做 Schema 预热。
php novaphp make:controller User
php novaphp make:model User
php novaphp make:middleware Auth
php novaphp make:event UserLoggedIn
php novaphp make:listener LogUserLogin
php novaphp make:plugin blog
php novaphp route:list
php novaphp plugin:list
php novaphp plugin:enable blog
php novaphp plugin:market search keyword从 .env.example 复制后按环境修改。常用变量:
| 变量 | 说明 |
|---|---|
APP_ENV / APP_DEBUG |
环境与调试 |
APP_URL |
对外根地址 |
ORM_DRIVER / DB_* |
出现在 .env.example 中,当前未写入 config/database.php;ORM 引擎与连接请直接改该文件(engine、hostname、database、username、password) |
SESSION_STORAGE |
redis / file 等 |
CACHE_DRIVER |
缓存驱动 |
JWT_SECRET |
必填,≥ 32 字节随机密钥 |
JWT_SINGLE_DEVICE_LOGIN |
单设备登录 |
COOKIE_SECRET |
Cookie 签名 |
CORS_ALLOWED_ORIGINS |
跨域白名单,禁止 * |
WORKERMAN_HTTP_PORT / WORKERMAN_AI_PORT |
Workerman 端口 |
认证、租户、Casbin 等应用中间件默认写在 config/middlewares.php 中并注释掉,按需取消注释即可接入全局栈。
php vendor/bin/phpunit # tests/Unit
php vendor/bin/php-cs-fixer fix # PSR-12 + Symfony
php vendor/bin/phpstan analyze -c phpstan.neon # Level 6,当前分析 app/
vendor/bin/composer-unused代码约定:PHP 8.3 强类型、短数组 []、类 PascalCase、方法 camelCase。新增控制器 / 服务 / DAO 分别继承 BaseController、BaseService、BaseDao。完整规范见 AGENTS.md。
| 文档 | 内容 |
|---|---|
| 官网 | 项目主页 |
| English.md | English README |
| docs/tech-stack-report.md | 技术栈分析 |
| docs/plugin-system.md | 插件系统 |
| docs/permission-system.md | 权限系统 |
| framework/Core/readme.md | App 门面与容器 |
| framework/Attributes/readme.md | 注解路由 |
| framework/Basic/readme.md | 控制器 / Service / DAO |
| framework/Repository/readme.md | 双 ORM 仓储 |
| framework/Tenant/readme.md | 多租户 |
| Zread | AI 生成的仓库导读 |
代码质量扫描(历史报告):
站在巨人的肩膀上:
- Workerman — 高性能 PHP 应用容器
- Symfony — HTTP、路由、DI、缓存等基础设施
- ThinkPHP — ORM、模板、校验等中文生态组件
- Laravel Illuminate — Eloquent 与 Database 组件
欢迎 Issue 与 Pull Request。安全相关披露请见 SECURITY.md。

