watsonhaw/think-orm

the PHP Database&ORM Framework

v4.0.18 2025-04-14 14:32 UTC

Requires

• php: >=8.0.0
• ext-json: *
• ext-pdo: *
• psr/log: >=1.0
• psr/simple-cache: >=1.0
• topthink/think-helper: ^3.1

Requires (Dev)

• phpunit/phpunit: ^9.6|^10

Suggests

• ext-mongodb: provide mongodb support

Apache-2.0

• liu21st

• database
• orm

README

基于 PHP 8.0+ 和 PDO 实现的轻量级 ORM，支持多数据库、参数绑定、模型关联等功能。3.x 版本采用 PHP 强类型实现，专注于高性能与类型安全。

主要特性

• 强类型实现：基于 PHP 8.0+ 与强类型系统
• PDO 抽象层：支持 MySQL / MariaDB / PostgreSQL / SQLite / SQL Server / Oracle / MongoDb
• 查询构造器：链式查询、原生 SQL、自动参数绑定
• 高级查询：WHERE IN、BETWEEN、LIKE、子查询、JOIN、UNION、聚合
• JSON 查询：MySQL JSON 字段的 field->key 语法
• 模型系统：字段类型转换、访问器/修改器、软删除、乐观锁、时间戳
• 关联模型：一对一、一对多、多对多、多态关联、预载入、延迟关联
• 事务机制：完整事务支持、保存点（Savepoint）、断点重连
• 分布式支持：主从分离、读写分离、多数据库动态切换
• 规范兼容：PSR-16 缓存规范、PSR-3 日志规范
• 数据库日志：完整 SQL 执行日志与监听接口

支持的数据库

驱动	类名	说明
MySQL / MariaDB	mysql	完整 JSON 字段、事务支持
PostgreSQL	pgsql	支持
SQLite	sqlite	支持
SQL Server	sqlsrv	支持
Oracle	oracle	支持
MongoDB	mongo	需要 ext-mongodb 扩展

安装

通过 Composer 安装：

composer require watsonhaw/think-orm

系统要求：

• PHP 8.0 或更高版本
• ext-pdo 及对应数据库的 PDO 驱动
• ext-json
• （可选）ext-mongodb 用于 MongoDB 支持

快速开始

use think\facade\Db;

// 配置数据库连接
Db::setConfig([
    'default' => 'mysql',
    'connections' => [
        'mysql' => [
            'type'     => 'mysql',
            'hostname' => 'localhost',
            'database' => 'your_db',
            'username' => 'root',
            'password' => '',
            'hostport' => '3306',
            'charset'  => 'utf8mb4',
        ],
    ],
]);

// 查询构造器
$users = Db::table('user')
    ->where('status', 1)
    ->where('age', '>', 18)
    ->order('id', 'desc')
    ->limit(10)
    ->select();

// 模型
class User extends \think\Model
{
    protected $name = 'user';
}

$user = User::find(1);
$user->name = 'New Name';
$user->save();

核心组件

src/
├── DbManager.php       # 数据库管理器 (Db Facade 的实现)
├── Model.php           # 模型基类
├── Paginator.php       # 分页器
├── db/                 # 数据库核心层
│   ├── Connection.php  # 连接基类 (SQL 生成与参数绑定)
│   ├── Query.php       # 查询构造器
│   ├── Builder.php     # SQL 语法构建器
│   ├── builder/        # 各数据库方言
│   ├── connector/      # 各数据库连接器
│   └── concern/        # 查询 concern (ParamsBind, Transaction, WhereQuery 等)
├── model/              # 模型层
│   ├── relation/       # 关联关系 (HasOne, HasMany, BelongsTo 等)
│   └── concern/        # 模型 concern (TimeStamp, SoftDelete, OptimLock 等)
└── facade/             # 门面 (Facade)

测试

本项目包含 65 个纯单元测试 与若干集成测试，通过 @group 注解分组管理。

测试分组

Group	描述	依赖	运行方式
unit	纯单元测试，使用 MockConnection 模拟数据库交互	无需真实数据库	composer test
database	集成测试，验证与真实数据库的交互	需要真实 MySQL 连接	vendor/bin/phpunit --group database

常用命令

# 运行纯单元测试（默认，无需数据库）
composer test

# 等同于：
vendor/bin/phpunit --group unit

# 只运行数据库集成测试（需要真实 MySQL）
vendor/bin/phpunit --group database

# 运行全部测试
vendor/bin/phpunit

测试覆盖

纯单元测试覆盖以下核心功能：

• ✅ SQL 参数绑定 (? 和命名参数)
• ✅ SQL 注入防护（单引号转义）
• ✅ 查询构造器：SELECT / WHERE / JOIN / LIMIT / ORDER / GROUP BY
• ✅ 条件子句：IN / NOT IN / BETWEEN / LIKE / NULL / EXP
• ✅ 聚合函数：COUNT / SUM / AVG / MAX / MIN
• ✅ 多表连接与别名
• ✅ 表前缀支持
• ✅ 事务与保存点（SQL 生成层面）
• ✅ 行锁 (FOR UPDATE)

文档

详细开发指南请参考官方文档： ThinkORM 开发指南

ThinkPHP 主文档：https://doc.thinkphp.cn

License

Apache-2.0