StartMVC开发手册

可以快速上手的开发文档

手册目录

插入数据

插入数据insert()

insert() 插入单条或批量数据,返回受影响行数(int);需要自增主键请用 insertGetId()。

方法一览

方法参数返回
insert($data, $type = 'INSERT')2受影响行数(int)
insertGetId($data, $type = 'INSERT')2自增主键(int)

参数

参数类型说明
$dataarray一维数组=单条(键为列名);二维数组(首元素为数组)=批量
$typestring插入类型,默认 'INSERT',取值见下表

$type 的四种取值

取值生成的 SQL说明
INSERT(默认)INSERT INTO t (...) VALUES (...)普通插入,主键冲突报错
IGNOREINSERT IGNORE INTO t (...)唯一键冲突时跳过该行,不报错
REPLACEREPLACE INTO t (...)冲突时先删除旧行再插入
DUPLICATEINSERT INTO ... ON DUPLICATE KEY UPDATE ...冲突时改为更新(upsert)

类型不区分大小写,内部统一转大写;'INSERT IGNORE' 与 'INSERT OR IGNORE' 是 'IGNORE' 的别名。

使用示例

1. 标准插入(默认)

单条传一维数组,批量传二维数组。

// 单条插入
$data = ['name' => '张三', 'email' => 'zhangsan@example.com'];
$rows = Db::table('users')->insert($data);
// $rows === 1

// 批量插入:返回写入行数,不是 ID 数组
$multiData = [
 ['name' => '张三', 'email' => 'zhangsan@example.com'],
 ['name' => '李四', 'email' => 'lisi@example.com']
];
$rows = Db::table('users')->insert($multiData);
// $rows === 2

// 需要自增主键
$newId = Db::table('users')->insertGetId($data);

2. 忽略错误插入(IGNORE)

插入的数据违反唯一约束时不报错,跳过该行;此时返回 0。

$data = ['id' => 1, 'name' => '张三', 'email' => 'zhangsan@example.com'];

$rows = Db::table('users')->insert($data, 'IGNORE');
// 冲突被跳过时 $rows === 0

// 别名写法等价
$rows = Db::table('users')->insert($data, 'INSERT IGNORE');

3. 替换插入(REPLACE)

存在相同主键或唯一索引时,先删除旧行再插入新行。

$data = ['id' => 1, 'name' => '张三', 'email' => 'new@example.com'];
$rows = Db::table('users')->insert($data, 'REPLACE');

4. 插入重复时更新(DUPLICATE)

主键或唯一索引冲突时改为更新,不会报错;框架会自动为所有字段生成 column = VALUES(column)。

$data = ['id' => 1, 'name' => '张三', 'email' => 'update@example.com', 'login_count' => 5];
$rows = Db::table('users')->insert($data, 'DUPLICATE');

插入并返回自增主键insertGetId()

参数与 insert() 完全一致,返回自增主键(int)。

$id = Db::table('users')->insertGetId([
 'name' => '张三',
 'email' => 'zhangsan@example.com'
]);
echo $id; // 例如: 25

insertId() 仍然可用(插入后立刻读),但它记录的是「最近一次插入」的状态,之后的任何查询都可能覆盖它;需要主键请优先用 insertGetId()。

返回值

场景返回
单条插入成功1(受影响行数,int)
批量插入 3 条成功3(受影响行数,int)
IGNORE 被唯一键跳过0(没有行被写入,不是失败)
SQL 执行出错抛 PDOException

两点提醒:

  1. insert() 不返回自增 ID,要 ID 用 insertGetId()。
  2. 批量插入返回的是行数,不是 ID 数组。MySQL 只提供首行的自增值,一条多值 INSERT 要么整体成功、要么整体失败,没有「每行是否成功」的逐行结果。

返回 SQL 而不执行

用 getSql():它返回一个快照并立即清空当前构建状态,因此不影响后续查询。写法是「先 getSql(),再链执行器」——getSql() 必须在执行器之前,因为「执不执行」要在执行前决定。

// 只出 SQL,不写库
$sql = Db::table('users')->getSql()->insert($data);
$sql = Db::table('users')->getSql()->insert($data, 'REPLACE'); // 指定插入类型

返回值是快照对象:getSql() 返回 SqlSnapshot,必须再链执行器才拿到字符串——插入场景用 ->insert() 或 ->insertGetId()。只写 getSql() 就 echo,会输出一段以 -- 开头的提示文本,而不是报致命错误。

旧的 insert($data, false, 'REPLACE') 三参写法与 get(true) 写法都已移除:前者抛「只接受 2 个参数」,后者抛 InvalidArgumentException 并提示改用 getSql()。快照支持的完整执行器列表见 数据查询。

参数约束

  • 只有两个参数。传第三个实参会抛 InvalidArgumentException——PHP 对用户函数的多余实参是静默忽略的,框架主动拦下,避免 insert($data, false, 'REPLACE') 退化成静默的普通插入。
  • 第二个参数不能传布尔值。insert($data, true) 与 insert($data, false) 都会抛 InvalidArgumentException,提示「没有第二个参数传布尔值的写法」。第二个位置只接受插入类型。
  • 类型必须精确。拼错(如 'REPLCE')会抛异常并列出可用取值,不会退化成普通 INSERT。

注意事项

  1. 表前缀会自动追加:Db::table('users') 实际写入 sm_users(前缀由配置决定),表名写全名会变成双前缀。
  2. 模型层对应 $model->insert() 与 $model->insertGetId(),会额外走自动验证、字段白名单与时间戳填充,详见 模型。
  3. 插入相关的读取方法(insertId()、numRows())见 数据查询。