# FssPHP **Repository Path**: fsscms/NovaFrame ## Basic Information - **Project Name**: FssPHP - **Description**: FssPHP is a lightweight Powerful Fast, Simple, Secure PHP framework -- FssPHP 是一款轻量级强大,快速,简单,安全的php框架,这是FssPHP框架的实践使用项目。 - **Primary Language**: PHP - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 8 - **Forks**: 0 - **Created**: 2025-10-15 - **Last Updated**: 2026-11-12 ## Categories & Tags **Categories**: webframework **Tags**: Symfony, thinkorm, dependency-injection ## README

FssPHP

FssPHP

轻量、高性能、安全的 PHP 8.3 框架
A lightweight, high-performance, secure PHP framework

PHP >= 8.3 MIT License Symfony 7 Workerman 5 Composer Ask Zread

官网 · 快速开始 · 架构 · English · 文档分析

--- FssPHP 以 `framework/` 为内核,组合 Symfony 7 组件、Workerman 常驻进程、ThinkPHP / Laravel 生态能力,形成一套可在 **PHP-FPM** 与 **Workerman**(以及可选 **Swoole**)之间共用同一套业务代码的现代 PHP 框架。本仓库既是框架本体,也是最佳实践示例项目。 ## 目录 - [特性](#特性) - [技术栈](#技术栈) - [运行要求](#运行要求) - [快速开始](#快速开始) - [目录结构](#目录结构) - [framework 架构](#framework-架构) - [核心用法](#核心用法) - [运行模式](#运行模式) - [命令行](#命令行) - [配置要点](#配置要点) - [开发工具](#开发工具) - [文档](#文档) - [鸣谢](#鸣谢) - [许可证](#许可证) ## 特性 **性能与运行时** - 同一套控制器 / 服务代码,可在 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` ## 快速开始 ```bash git clone https://github.com/xuey490/project.git cd project composer install cp .env.example .env ``` 编辑 `.env`,设置 **长度 ≥ 32 字节** 的 `JWT_SECRET`(未设置或密钥过弱时 JWT 组件会拒绝启动): ```bash 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 内置服务器(开发) ```bash php -S localhost:8000 -t public ``` 浏览器打开 。 ### Workerman(推荐,生产 / 高性能) ```bash 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 内置服务器。 ### PHP-FPM / Nginx / Apache 将 Web 根目录指向 `public/`,其余请求转发到 `public/index.php`(仓库已提供 `public/.htaccess`)。 ## 目录结构 ```text 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 架构 `framework/` 是框架本体,按职责拆成独立模块。启动链路: ```text 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()` 等全局函数 | 应用层约定: ```text Controller → Service(事务 / 业务) → Dao / Repository(ORM) ``` 控制器继承 `BaseController`,通过 `$serviceClass` 自动解析服务,不必手写构造函数。 ## 核心用法 ### 属性路由 ```php 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` 自动推断。 ### 依赖注入 ```php 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 隐藏域 | ### JSON 响应 `BaseController` / `BaseJsonResponse` 提供统一信封:`success()`、`fail()`、`error()`、`unauthorized()`、`csrfExpired()`。 ### 多应用 在 `config/apps.php` 增加一项即可,无需改 `composer.json` 或 `dump-autoload`: ```php '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 预热。 ## 命令行 ```bash 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` 中并注释掉,按需取消注释即可接入全局栈。 ## 开发工具 ```bash 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](AGENTS.md)。 ## 文档 | 文档 | 内容 | |------|------| | [官网](https://www.phpframe.org/) | 项目主页 | | [English.md](English.md) | English README | | [docs/tech-stack-report.md](docs/tech-stack-report.md) | 技术栈分析 | | [docs/plugin-system.md](docs/plugin-system.md) | 插件系统 | | [docs/permission-system.md](docs/permission-system.md) | 权限系统 | | [framework/Core/readme.md](framework/Core/readme.md) | `App` 门面与容器 | | [framework/Attributes/readme.md](framework/Attributes/readme.md) | 注解路由 | | [framework/Basic/readme.md](framework/Basic/readme.md) | 控制器 / Service / DAO | | [framework/Repository/readme.md](framework/Repository/readme.md) | 双 ORM 仓储 | | [framework/Tenant/readme.md](framework/Tenant/readme.md) | 多租户 | | [Zread](https://zread.ai/xuey490/project) | AI 生成的仓库导读 | 代码质量扫描(历史报告): [![Code quality](quality.png)](https://gitee.com/fsscms/FssPhp) ## 鸣谢 站在巨人的肩膀上: - [Workerman](https://www.workerman.net/) — 高性能 PHP 应用容器 - [Symfony](https://symfony.com/) — HTTP、路由、DI、缓存等基础设施 - [ThinkPHP](https://thinkphp.cn/) — ORM、模板、校验等中文生态组件 - [Laravel Illuminate](https://laravel.com/) — Eloquent 与 Database 组件 ## 许可证 [MIT](LICENSE) © 2025 [blue2004](mailto:xuey863toy@gmail.com) / xuey490 欢迎 Issue 与 Pull Request。安全相关披露请见 [SECURITY.md](SECURITY.md)。