资源描述
Xenus 是一个专为 PHP 设计的轻量级 MongoDB 对象文档映射（ODM）框架，提供直观的类-文档映射、查询构建器、生命周期钩子与事务支持。适用于 Laravel/Lumen 项目、微服务后端及需快速迭代 MongoDB 应用的中小型团队，兼顾开发效率与运行时性能。
详细内容
## Xenus 框架简介与定位
Xenus 是一个现代、轻量且专注的 PHP MongoDB ODM（Object-Document Mapper）框架，旨在替代传统 ORM 思维，以符合文档数据库语义的方式实现 PHP 类与 MongoDB 文档的双向映射。它不依赖庞大生态（如 Doctrine），强调简洁 API、低侵入性设计和原生 MongoDB 特性支持（如聚合管道、地理空间索引、变更流集成），适用于需要直接、高效操作 MongoDB 的 PHP 应用场景。
## 核心特性
- **声明式实体映射**：通过 PHP 属性注解（`#[Field]`、`#[Reference]`、`#[Embedded]`）定义文档结构与关系，支持嵌套文档与引用关联。
- **链式查询构建器**：提供 Fluent 接口（如 `where()`, `sort()`, `limit()`, `project()`）生成可读性强、类型安全的 MongoDB 查询，兼容原生操作符（`$regex`, `$in`, `$expr` 等）。
- **生命周期事件钩子**：支持 `prePersist`, `postLoad`, `preUpdate`, `postRemove` 等事件，便于实现审计日志、数据脱敏或缓存同步。
- **原生事务与会话支持**：完整封装 MongoDB 4.0+ 多文档 ACID 事务，自动管理 `ClientSession`，支持跨集合原子操作。
- **无缝集成主流框架**：提供 Laravel Service Provider 与 Facade 支持，兼容 PSR-11 容器，亦可独立用于原生 PHP 或 Slim/Swoole 项目。
## 适用场景
- 构建以 MongoDB 为唯一/主数据源的 PHP Web 应用（如内容管理系统、实时分析仪表盘、用户行为日志平台）；
- 需要精细控制 MongoDB 原生能力（如聚合管道、文本搜索、时间序列集合）的中台服务；
- 替代 Doctrine ODM 或自建 DAO 层，追求更小体积、更低学习成本与更高执行效率的团队；
- 快速原型开发或微服务模块，要求开箱即用、无强耦合依赖。
## 快速入门步骤
### 1. 安装
```bash
composer require abellion/xenus
```
### 2. 基础配置（示例）
```php
use Xenus\Client;
$client = new Client('mongodb://localhost:27017', [
'database' => 'myapp',
]);
```
### 3. 定义实体
```php
#[Collection('users')]
class User
{
#[Field('_id', type: 'ObjectId')]
public ?ObjectId $id = null;
#[Field('name')]
public string $name;
#[Field('email', unique: true)]
public string $email;
}
```
### 4. 基本操作
```php
$user = new User();
$user->name = 'Alice';
$user->email = 'alice@example.com';
$client->persist($user); // 插入
$users = $client->repository(User::class)
->where(['email' => ['$regex' => '^a']])
->sort(['name' => 1])
->findAll();
```
## 生态与社区说明
Xenus 由开源开发者 Abellion 主导维护，源码托管于 GitHub（https://github.com/abellion/xenus），文档位于项目 Wiki 及 README 中。当前版本稳定支持 PHP 8.1+ 与 MongoDB PHP Driver ≥1.15。社区规模较小但响应及时，Issue 与 PR 处理活跃；暂无官方中文文档，但核心 API 设计清晰，符合 PSR 标准，易于上手。推荐结合 MongoDB 官方驱动文档与 Xenus 示例代码进行深度使用。