PHPackages                             xiasf/think-orm - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. xiasf/think-orm

ActiveLibrary[Database & ORM](/categories/database)

xiasf/think-orm
===============

从 ThinkPHP 5.0.24 抽离的独立 ORM 包，保留 think\\ 命名空间，提供 Db / Model / Validate / Paginator / Collection / Loader / Config 等完整模型层能力，可在非 ThinkPHP 项目（脚本、微服务、其他框架）中无缝复用 ThinkPHP 5.0 风格 ORM 用法。

v1.2.0(1mo ago)010Apache-2.0PHPPHP >=7.2

Since Jul 9Pushed 1mo agoCompare

[ Source](https://github.com/xiasf/think-orm)[ Packagist](https://packagist.org/packages/xiasf/think-orm)[ RSS](/packages/xiasf-think-orm/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (1)Versions (4)Used By (0)

think-orm
=========

[](#think-orm)

[![Packagist Version](https://camo.githubusercontent.com/096afefd3b875abfda7603bc5c16f921a24f5051e3b38cc372aec1c75d66a3ab/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f78696173662f7468696e6b2d6f726d2e7376673f7374796c653d666c61742d737175617265266c6f676f3d7061636b6167697374266c6162656c3d5061636b6167697374)](https://packagist.org/packages/xiasf/think-orm)[![PHP Version](https://camo.githubusercontent.com/c2f107dcedbbfad8480a48dd5e7568049af7b2033b01f87834873725ca07c238/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f78696173662f7468696e6b2d6f726d2e7376673f7374796c653d666c61742d737175617265266c6f676f3d706870)](https://packagist.org/packages/xiasf/think-orm)[![License](https://camo.githubusercontent.com/e7ead21fcfd9b14ea3443b6be6f041bd5ef9515b6688a2b04ffaf24f80fd3471/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f78696173662f7468696e6b2d6f726d2e7376673f7374796c653d666c61742d737175617265266c6162656c3d4c6963656e7365)](./LICENSE)[![Total Downloads](https://camo.githubusercontent.com/f8999124f3e310ef825f11a8517e1975da0d71c5ae270be03eaa367012ff16a1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f78696173662f7468696e6b2d6f726d2e7376673f7374796c653d666c61742d737175617265266c6f676f3d7061636b6167697374266c6162656c3d446f776e6c6f616473)](https://packagist.org/packages/xiasf/think-orm/stats)[![Monthly Downloads](https://camo.githubusercontent.com/e363d868c3fb5ce1de072c60b9e0838553a583bc13cafbcfc6e0b91e8a27146b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f78696173662f7468696e6b2d6f726d2e7376673f7374796c653d666c61742d737175617265266c6162656c3d4d6f6e74686c79)](https://packagist.org/packages/xiasf/think-orm/stats)[![Packagist Stars](https://camo.githubusercontent.com/fb748ff77eeadb889620fafc4321dde35e8a66ca27c7d41f33ef0a63dc331147/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f73746172732f78696173662f7468696e6b2d6f726d2e7376673f7374796c653d666c61742d737175617265266c6f676f3d7061636b6167697374266c6162656c3d5374617273)](https://packagist.org/packages/xiasf/think-orm)[![GitHub Stars](https://camo.githubusercontent.com/2098cbbd0f747c9b90d1ee80c2de0d8e699ce83a00e948c9c37ee1482c44c6a8/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f78696173662f7468696e6b2d6f726d2e7376673f7374796c653d666c61742d737175617265266c6f676f3d676974687562266c6162656c3d476974487562)](https://github.com/xiasf/think-orm)[![GitHub Issues](https://camo.githubusercontent.com/0467cec2db23b6d827d8fc52328815216724cce26ae78361163f52d9c0fb0d32/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f78696173662f7468696e6b2d6f726d2e7376673f7374796c653d666c61742d737175617265266c6f676f3d676974687562266c6162656c3d497373756573)](https://github.com/xiasf/think-orm/issues)[![Last Commit](https://camo.githubusercontent.com/b6014bdbef29a5e47b326d655b9ebae6d9b0f5acd9434c79f70862ff8a594900/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f78696173662f7468696e6b2d6f726d2e7376673f7374796c653d666c61742d737175617265266c6f676f3d676974687562266c6162656c3d4c617374253230436f6d6d6974)](https://github.com/xiasf/think-orm/commits)[![CI](https://camo.githubusercontent.com/25a5a462f09181c495d688ff28798021485a61841c26244acdbb6dd9db8f42c4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f43492d706c616e6e65642d6f72616e67652e7376673f7374796c653d666c61742d737175617265266c6f676f3d676974687562616374696f6e73)](https://github.com/xiasf/think-orm)

ThinkPHP 5.0.24 ORM 的独立 composer 包移植。**保留原 `think\` 命名空间**，零改动拷贝核心源码，配套 8 个桩文件替换框架依赖。

官方 [`topthink/think-orm`](https://github.com/top-think/think-orm) 从 TP **5.1+** 抽出，API 与 5.0.24 不兼容，因此必须直接 fork 5.0.24 实际源码。

---

安装
--

[](#安装)

```
composer require xiasf/think-orm
```

需要 PHP >= 7.2 + `ext-pdo`。MySQL 默认 `ext-pdo_mysql`。

---

三步上手
----

[](#三步上手)

### 1. 启动

[](#1-启动)

```
require __DIR__ . '/vendor/autoload.php';

\ThinkOrm\Orm::boot([
    'database' => [
        'type'     => 'mysql',
        'hostname' => '127.0.0.1',
        'hostport' => 3306,
        'database' => 'app',
        'username' => 'root',
        'password' => 'secret',
        'charset'  => 'utf8mb4',
        'prefix'   => '',
        'debug'    => false,
    ],
]);
```

### 2. 创建模型（默认解析到 `app\\model\`）

[](#2-创建模型默认解析到-appmodulemodelname)

> **⚠️ 强烈建议：yf 项目直接继承 `app\common\BaseModel`，不要继承 `think\Model`**
>
> BaseModel 在 `think\Model` 之上封装了 yf 业务高频方法（`add / adds / upd / upds / updBy / updAttr / del / info / infoBy / lists / listBy / listByIds / listPageBy / search / search_or / countBy / maxBy / minBy / avgBy / sumBy / valueBy / inc / dec / upSert / resultSet / resultListSet`），统一了 CRUD 入口、自动时间戳、错误处理、验证场景、字段格式化等约定。
>
> **直接继承 `think\Model` 是反模式**：会丢掉 yf 项目的统一调用风格、错误转异常、validatorName 推断等关键能力。

#### 推荐做法：继承 `app\common\BaseModel`

[](#推荐做法继承-appcommonbasemodel)

```
// 文件: app/model/User.php
namespace app\model;

use app\common\BaseModel;
use think\traits\model\SoftDelete;

class User extends BaseModel
{
    use SoftDelete;

    protected $table = 'users';
    protected $deleteTime = 'delete_time';
    protected $hidden = ['password'];
    protected $readonly = ['name'];

    // 关联（直接用类常量，IDE 可跳转、PHPStan 可静态分析）
    public function posts()      { return $this->hasMany(Post::class); }
    public function profile()    { return $this->hasOne(Profile::class); }
    public function roles()      { return $this->belongsToMany(Role::class, 'user_roles'); }
}
```

业务调用全部走 BaseModel 统一 API：

```
$User = model('User');

$User->add(['name' => 'tom', 'email' => 't@x']);       // 创建（带自动时间戳 + 验证场景 add）
$User->upds([['id' => 1, 'age' => 20], ...]);          // 批量更新
$User->info(1);                                         // 单条查询
$User->infoBy(['mobile' => '13800138000']);             // 条件查询单条
$User->listPageBy(['is_active' => 1], 'id,name', 1, 20); // 分页列表
$User->countBy(['status' => 1]);                        // 条件计数
$User->valueBy(['id' => 1], 'name');                    // 单值查询
$User->inc(['id' => 1], 'hits', 1);                     // 自增
$User->upSert(['uniq_key' => 'k1', 'val' => 'v1']);     // 不存在则插入，存在则更新
```

#### BaseModel 的核心能力（详见 `example/app/common/BaseModel.php`）

[](#basemodel-的核心能力详见-exampleappcommonbasemodelphp)

能力说明**统一 CRUD 入口**`add/adds/upd/upds/updBy/updAttr/del/delBy` 替代散落的 insert/update/delete**统一查询入口**`info/infoBy/lists/listBy/listByIds/listPageBy/search/search_or`**统一聚合**`countBy/maxBy/minBy/avgBy/sumBy/valueBy`**统一自增减**`inc/dec`**upSert**不存在则插入、存在则更新**自动时间戳**`autoWriteTimestamp = 'datetime'` 默认开启**字段格式化**`resultSet` 把 decimal 转 float、JSON 字段自动 decode、append 字段追加**验证场景自动推断**从命名空间推断 `validatorName()`（如 `app\parkinglot\model\v1\Car` → `parkinglot/Car`）**错误转异常**`validateData()` 包了 `set_error_handler`，规则写错抛 `ValidateException` 而非静默**trait spd/sca**子类实现 `get_Scope()` / `get_withModel()` / `get_ExtendField()` 等 hook> **拷贝到自己的项目**：BaseModel 不在 `src/` 里（它是业务层而非框架层）。把 `example/app/common/BaseModel.php` 和 `example/app/common/traits/model/Model.php` 复制到你项目的 `app/common/` 下即可。完整业务参考见 `example/app/parkinglot/`（BModel + 条件关联 + pivot 过滤 + 多层 with）。

#### 仅在简单脚本场景直接继承 `think\Model`

[](#仅在简单脚本场景直接继承-thinkmodel)

如果你的项目只是想用 ORM，不需要 yf 风格 CRUD：

```
namespace app\model;

use think\Model;
use think\traits\model\SoftDelete;

class User extends Model
{
    use SoftDelete;

    protected $table = 'users';
    protected $autoWriteTimestamp = 'datetime';
    protected $deleteTime = 'delete_time';
    protected $hidden = ['password'];
    protected $readonly = ['name'];

    public function posts()      { return $this->hasMany(Post::class); }
    public function getNameAttr($v) { return ucfirst($v); }
    public function scopeActive($q) { return $q->where('is_active', 1); }
}
```

### 3. 用 `model()` / `validate()` 操作

[](#3-用-model--validate-操作)

```
// 取模型实例（单例）
$User = model('User');

// CRUD
$user = $User->find(1);
$users = $User->where('age', '>', 18)->order('id desc')->select();
$newId = $User->insertGetId(['name' => 'a', 'email' => 'a@x']);
$User->where('id', $newId)->update(['age' => 20]);

// 或走静态
$user = \app\model\User::get(1);
$user->age = 21;
$user->save();
\app\model\User::destroy([2, 3]);

// 关联
foreach (\app\model\User::get(1)->posts as $p) { /* ... */ }

// 验证
$v = validate('User');
if (!$v->check($data)) {
    echo $v->getError();
}
```

---

创建验证器（默认解析到 `app\validate\`）
----------------------------------

[](#创建验证器默认解析到-appvalidatename)

```
// 文件: app/validate/User.php
namespace app\validate;

use think\Validate;

class User extends Validate
{
    protected $rule = [
        'name'  => 'require|max:30',
        'email' => 'require|email',
        'age'   => 'integer|>=:0|