Download the PHP package watsonhaw/think-orm without Composer

ThinkORM

基于PHP8.0+ 和PDO实现的ORM，支持多数据库，3.0版本主要特性包括：

• 基于PDO和PHP强类型实现
• 支持原生查询和查询构造器
• 自动参数绑定和预查询
• 简洁易用的查询功能
• 强大灵活的模型用法
• 支持预载入关联查询和延迟关联查询
• 支持多数据库及动态切换
• 支持分布式及事务
• 支持断点重连
• 支持JSON查询
• 支持数据库日志
• 支持PSR-16缓存及PSR-3日志规范
• 支持乐观锁（Optimistic Lock） 处理并发更新冲突

安装

composer require watsonhaw/think-orm

文档

详细参考 ThinkORM开发指南

模型事件

模型事件允许在数据写入、更新、删除的前后自动执行自定义逻辑。框架在 ModelEvent trait 中提供了以下事件方法，子类可直接重写：

Before 与 After 的区别

Before 事件：在数据库操作之前触发，此时修改模型数据会随本次操作一起写入，无需调用 save()。

After 事件：在数据库操作之后触发，此时修改模型数据不会自动持久化，如需保存需显式调用 save()。

注意事项

1. 不要在 Before 事件中调用 save()：会导致无限递归（save() → Before* → save()）。
2. 避免在 onAfterWrite 中调用 save()：onAfterWrite 在 insert/update 后都会触发，调用 save() 会再次触发 onAfterWrite，造成递归。
3. 只有通过模型方法（save()、create()、update()、destroy() 等）写入才会触发事件，直接使用 Db 查询构造器写入不会触发模型事件。

乐观锁使用指南

乐观锁用于处理并发场景下的数据更新冲突问题。其原理是通过在数据表中增加一个版本号字段， 在更新数据时校验版本号是否一致，如果不一致则抛出异常，表示数据已被其他进程修改。

数据库准备

首先需要在数据表中添加版本号字段（字段名可自定义，默认为 lock_version）：

模型中使用乐观锁

在模型类中引入 OptimLock trait：

基本使用

创建记录

创建新记录时，乐观锁版本号会自动初始化为 0：

更新记录

每次成功更新记录后，版本号会自动 +1：

处理并发冲突

当两个进程同时读取同一条记录并尝试更新时，先更新成功的进程会使版本号 +1， 后更新的进程会因为版本号不匹配而抛出 OptimLockException 异常：

冲突重试机制

捕获异常后，可以重新读取数据并重试更新操作：

删除操作的乐观锁

删除记录时同样会进行乐观锁检查，如果版本号不匹配则抛出异常：

强制操作（跳过乐观锁检查）

在某些特殊场景下，可以强制跳过乐观锁检查：

自定义版本号字段

如果不想使用默认的 lock_version 字段，可以在模型中自定义：

注意事项

1. 先读取再更新：使用乐观锁时，必须先通过 find() / select() 等方法从数据库读取数据， 然后再调用 save() 更新。如果直接使用静态 update() 方法而没有设置正确的版本号， 可能无法正确触发乐观锁检查。

2. 批量更新：乐观锁仅适用于单条记录的 save() 和 delete() 操作。 使用查询构造器执行的批量更新（如 User::where('status', 1)->update(...)） 不会自动触发乐观锁机制。

3. 事务环境：乐观锁与数据库事务兼容。如果在事务中更新失败抛出异常， 事务会自动回滚（前提是更新操作在事务内）。

4. 高并发场景：在高并发写入场景下，建议配合合理的重试机制使用， 同时考虑是否需要使用悲观锁（Db::lock(true)）等其他方案。

参与开发

单元测试编写

创建创建一个名为 UserInfo 的迁移文件（以测试单元为单位来创建迁移）

迁移命令

下面相关命令都是 mysql 与 pgsql 同时执行，如果环境不完整可以通过 phinx 手动执行独立的迁移命令。

执行迁移（mysql、pgsql）

重建，先回滚在迁移（mysql、pgsql）

回滚迁移（mysql、pgsql）

迁移状态（mysql、pgsql）

环境问题

1. 如果提示 phinx 不存在，尝试手动执行composer bin phinx install安装。