Download the PHP package easyswoole/fast-db without Composer

fast-db

EasySwoole 为了支持以 PHP 8 注解的方式来定义数据库对象映射，于是开发了 fast-db 这个数据库操作组件。

组件要求

• php: >= 8.1
• easyswoole/mysqli: ^3.0
• easyswoole/pool: ^2.0
• easyswoole/spl: ^2.0

安装方法

连接注册

在 EasySwoole 框架中使用

首先我们在 EasySwoole 框架的 EasySwooleEvent 事件（即框架根目录的 EasySwooleEvent.php 文件中）的 initialize 方法 或 mainServerCreate 方法中进行注册连接，如下所示：

EasySwooleEvent.php

上述2种注册方式注册结果是一样的。如需注册多个链接，请在配置项中加入 name 属性用于区分连接池。

在 其他框架中使用

配置项解析

\EasySwoole\FastDb\Config继承自 \EasySwoole\Pool\Config ，因此 ORM 具备连接池的特性。

• autoPing
• intervalCheckTime
• maxIdleTime
• maxObjectNum
• minObjectNum

AbstractEntity 使用

定义模型

定义模型规范

1. 任何模型都必须继承 \EasySwoole\FastDb\Entity 并实现 tableName() 方法，该方法用于返回该数据表的表名。

2. 任何模型都必须具有一个唯一主键，作为某个模型对象的唯一id，一般建议为 int 类型的自增id。

3. 对象的属性，也就是数据表对应的字段，请用 #[Property] 进行标记。

示例

例如，我们有个表名为 的数据表，表结构如下：

则它对应的实体类如下：

模型创建脚本

EasySwoole 提供了创建模型的命令，您可以很方便的根据数据表创建对应模型。不过这个功能目前仅限在 EasySwoole 框架中使用

在使用脚本之前需要先在 EasySwoole 框架中进行注册 ORM 连接池和注册创建脚本命令，修改 EasySwoole 框架根目录的 bootstrap.php 文件，如下：

创建模型

可选参数如下：

创建示例

在数据库中先导入数据表 DDL，如：

或数据库已有上述数据表也可。

执行如下命令，创建模型：

创建的模型如下：

新增

添加一条数据

insert() 方法，返回值为 bool 类型的值，返回值为 true 表示添加成功，返回值为 false 表示添加失败。

第一种是实例化模型对象后赋值并保存：

也可以使用 setData 方法批量赋值：

或者直接在实例化的时候传入数据

获取自增ID

如果要获取新增数据的自增ID，可以使用下面的方式：

注意这里其实是获取模型的主键，如果你的主键不是 id，而是 user_id 的话，其实获取自增ID就变成这样：

添加多条数据

insertAll() 方法新增数据返回的是包含新增模型（带自增ID）的对象数组 或 普通数组。

insertAll() 方法的返回类型受模型的 queryLimit 属性 的 fields 属性的 returnAsArray 属性影响（可能返回普通数组）。

支持批量新增，可以使用：

insertAll 方法新增数据默认会自动识别数据是需要新增还是更新操作，当数据中存在主键的时候会认为是更新操作，如果你需要带主键数据批量新增，可以使用下面的方式：

onInsert注解

修改 User 模型类文件，添加 OnInsert 注解 和 onInsert 方法，onInsert 方法用于对添加前的数据做一些处理。

User.php

然后尝试新增数据

ON DUPLICATE KEY UPDATE

更新

update() 方法，返回值为 bool 类型的值，值为 true时表示影响行数大于0的更新成功。

updateWithLimit() 方法，返回值为 int 类型的值，值表示更新影响的行数。

fastUpdate 方法，返回值为 int 类型的值，值表示更新影响的行数。

查找并更新

在取出数据后，更改字段内容后更新数据。

直接更新数据

也可以直接带更新条件来更新数据

必要的时候，你也可以使用 Query 对象来直接更新数据。

闭包更新

可以通过闭包函数使用更复杂的更新条件，例如：

删除

delete() 方法，返回值为 bool 类型的值，值为 true时表示影响行数大于0的删除成功。

fastDelete() 方法返回值为 int 类型的值

• 删除成功时返回值为 int 类型的值，表示删除操作影响的行数
• 删除失败时返回值为 null

查找并删除

在取出数据后，然后删除数据。

根据主键删除

直接调用静态方法

当 fastDelete 方法传入空值（包括空字符串和空数组）的时候不会做任何的数据删除操作，但传入0则是有效的。

条件删除

使用数组进行条件删除，例如：

还支持使用闭包删除，例如：

查询

获取单个数据

findRecord() 方法，返回值为当前模型的对象实例，可以使用模型的方法。

find() 方法，返回值为当前模型的对象实例，可以使用模型的方法。

获取单个数据的方法包括：

或者在实例化模型后调用查询方法

获取多个数据

findAll() 方法返回的是一个包含模型对象的二维普通数组或者对象数组。返回的结果类型受参数 returnAsArray 的影响。

all() 方法返回的是 \EasySwoole\FastDb\Beans\ListResult 类的对象。

数组方式和闭包方式的数据查询的区别在于，数组方式只能定义查询条件，闭包方式可以支持更多的连贯操作，包括排序、数量限制等。

转换字段

例如我们有数据表 student_info，DDL 如下：

我们可以对 address 和 sex 字段做转换处理来满足业务开发需求，这里我们用到了 php8 的枚举特性。

定义为模型为：

Address.php

SexEnum.php 使用枚举特性。

转换字段使用示例：

自定义返回结果类型

findAll() 方法的 returnAsArray 参数可以设置查询的返回对象的名称（默认是模型对象）。

all() 方法调用 queryLimit() 方法的 fields() 方法的 returnAsArray 参数可以设置查询的返回对象的名称（默认是模型对象）。

数据分批处理 chunk

模型也支持对返回的数据分批处理。特别是如果你需要处理成千上百条数据库记录，可以考虑使用 chunk 方法，该方法一次获取结果集的一小块，然后填充每一小块数据到要处理的闭包，该方法在编写处理大量数据库记录的时候非常有用。

比如，我们可以全部用户表数据进行分批处理，每次处理 100 个用户记录：

分页查询 page

• 方法说明：

  方法

• 使用示例：

聚合

在模型中也可以调用数据库的聚合方法进行查询，例如：

count

max

min

avg

sum

数组访问和转换

转换为数组

可以使用 toArray 方法将当前的模型实例输出为数组，例如：

事件注解

适用场景

模型事件类似于 ThinkPHP 框架模型的模型事件，可用于在数据写入数据库之前做一些预处理操作。

模型事件是指在进行模型的写入操作的时候触发的操作行为，包括调用模型对象的 insert、delete、update 方法以及对实体对象初始化时触发。

模型类支持 OnInitialize、OnInsert、OnDelete、OnUpdate 事件。

使用示例

• 声明事件注解

在模型类中可以通过注解及定义类方法来实现事件注解的声明，如下所示：

上面定义了 OnInitialize、OnInsert、OnDelete、OnUpdate 事件注解，并在注解中通过形如 #[OnInitialize('onInitialize')] 的方式给 OnInitialize 注解传入参数，给对应的事件行为设置事件被触发时执行的回调 onInitialize、onInsert 、onDelete、onUpdate。

设置的回调方法会自动传入一个参数（当前的模型对象实例），并且 OnInsert、OnDelete、OnUpdate 事件的回调方法(onInsert 、onDelete、onUpdate) 如果返回 false，则不会继续执行。

• 使用

关联

一对一关联

定义关联

定义一对一关联，例如，一个用户都有一个个人资料，我们定义 User 模型如下：

关联查找

定义好关联之后，就可以使用下面的方法获取关联数据：

一对多关联

定义关联

关联查询

FastDb 使用

调用方法说明

addDb

用于注册连接池。

testDb

用于测试连接池的数据库配置是否可用。

setOnQuery

设置连接池连接执行 SQL 查询时的回调，可用于监听 SQL，可查看监听 SQL 章节。

selectConnection

todo::

invoke

可用于执行数据库操作。

在高并发情况下，资源浪费的占用时间越短越好，可以提高程序的服务效率。

ORM 默认情况下都是使用 defer 方法获取 pool 内的连接资源，并在协程退出时自动归还，在此情况下，在带来便利的同时，会造成不必要资源的浪费。

我们可以使用 invoke 方式，让 ORM 查询结束后马上归还资源，可以提高资源的利用率。

begin

启动事务。

commit

提交事务。

rollback

回滚事务。

query

自定义 SQL 执行。

原生 SQL 表达式将会被当做字符串注入到查询中，因此你应该小心使用，避免创建 SQL 注入的漏洞。

rawQuery

自定义 SQL 执行。

原生 SQL 表达式将会被当做字符串注入到查询中，因此你应该小心使用，避免创建 SQL 注入的漏洞。

currentConnection

获取当前所用的连接。

reset

销毁所有连接池。

preConnect

用于预热连接池。

为了避免连接空档期突如其来的高并发，我们可以对数据库连接预热，也就是 Worker 进程启动的时候，提前准备好数据库连接。

对连接进行预热使用实例如下所示：

isInTransaction

当前连接是否处于事务中。

getConfig

根据连接池名称获取当前连接池配置。

事务操作

使用事务处理的话，需要数据库引擎支持事务处理。比如 MySQL 的 MyISAM 不支持事务处理，需要使用 InnoDB 引擎。

手动控制事务逻辑，如：

注意在事务操作的时候，确保你的数据库连接是同一个。确保在同一个协程环境下执行事务操作。

监听 SQL

如果你想对数据库执行的任何 SQL 操作进行监听，可以在注册连接池时设置 onQuery 回调函数，使用如下方法：

存储过程

如果我们定义了一个数据库存储过程 sp_query，可以使用下面的方式调用：

组件使用常见问题

1.Method Swoole\Coroutine\MySQL::__construct() is deprecated

如果在运行过程中出现类似 PHP Deprecated: Method Swoole\Coroutine\MySQL::__construct() is deprecated in /demo/vendor/easyswoole/mysqli/src/Client.php on line 160 这样的警告，请修改连接时使用的配置中的 useMysqli 为 true 选项，即可解决这个告警。