插入数据insert()
insert() 插入单条或批量数据,返回受影响行数(int);需要自增主键请用 insertGetId()。
方法一览
| 方法 | 参数 | 返回 |
|---|---|---|
insert($data, $type = 'INSERT') | 2 | 受影响行数(int) |
insertGetId($data, $type = 'INSERT') | 2 | 自增主键(int) |
参数
| 参数 | 类型 | 说明 |
|---|---|---|
$data | array | 一维数组=单条(键为列名);二维数组(首元素为数组)=批量 |
$type | string | 插入类型,默认 'INSERT',取值见下表 |
$type 的四种取值
| 取值 | 生成的 SQL | 说明 |
|---|---|---|
INSERT(默认) | INSERT INTO t (...) VALUES (...) | 普通插入,主键冲突报错 |
IGNORE | INSERT IGNORE INTO t (...) | 唯一键冲突时跳过该行,不报错 |
REPLACE | REPLACE INTO t (...) | 冲突时先删除旧行再插入 |
DUPLICATE | INSERT 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; // 例如: 25insertId() 仍然可用(插入后立刻读),但它记录的是「最近一次插入」的状态,之后的任何查询都可能覆盖它;需要主键请优先用 insertGetId()。
返回值
| 场景 | 返回 |
|---|---|
| 单条插入成功 | 1(受影响行数,int) |
| 批量插入 3 条成功 | 3(受影响行数,int) |
IGNORE 被唯一键跳过 | 0(没有行被写入,不是失败) |
| SQL 执行出错 | 抛 PDOException |
两点提醒:
insert()不返回自增 ID,要 ID 用insertGetId()。- 批量插入返回的是行数,不是 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。
注意事项