PHP PDO 怎样为批量写入绑定不同参数

PHP PDO 做批量写入时，不需要为每一行拼一条新的 SQL。更稳妥的方式是先用 prepare() 固定一组占位符，再在循环中为当前行绑定不同值并调用 execute()，最后把整个批次放入事务。这样既能保持参数和 SQL 分离，也能明确失败时哪些数据应该一起回滚。

官方参考：https://www.php.net/manual/en/book.pdo.php

本文只讨论参数绑定与事务边界。重点是分清 bindValue()、bindParam() 和 execute($params) 的使用时机，不把一次批量写入误写成多段拼接 SQL。

先把批量写入拆成固定 SQL 和变化数据

假设每一行都要写入商品编号、数量和备注，SQL 的结构始终不变，变化的是数组里的值。先准备一个带命名占位符的 INSERT，然后复用同一个 PDOStatement：

 'A-100', 'quantity' => 3, 'note' => '首批'],
    ['sku' => 'B-200', 'quantity' => 8, 'note' => '补货'],
];

$sql = prepare($sql);

这里的关键不是“循环执行”本身，而是让每次执行都共享同一组参数形状。数组中的 sku、quantity 和 note 分别对应一个命名占位符，后续只替换值。

用 bindValue 为每一行绑定当前值

bindValue() 绑定的是传入时的值，适合循环中每一轮都明确写入当前行。绑定后执行语句，下一轮再次绑定新的值即可：

beginTransaction();

    foreach ($rows as $row) {
        // 当前行的值在 bindValue 调用时被绑定，不依赖后续变量变化。
        $statement->bindValue(':sku', $row['sku'], PDO::PARAM_STR);
        $statement->bindValue(':quantity', $row['quantity'], PDO::PARAM_INT);
        $statement->bindValue(':note', $row['note'], PDO::PARAM_STR);

        // 一组占位符对应一行，执行失败立即进入异常处理。
        $statement->execute();
    }

    // 所有行都成功后再一次性提交。
    $pdo->commit();
} catch (Throwable $error) {
    // 仅在事务仍然存在时回滚，避免覆盖原始异常。
    if ($pdo->inTransaction()) {
        $pdo->rollBack();
    }
    throw $error;
}

官方手册把 bindValue() 定义为绑定一个值；第三个参数可以使用 PDO::PARAM_INT、PDO::PARAM_STR 等类型常量。批量写入时，这种写法的优点是每轮绑定的对象很直观，排查“上一行的值跑到下一行”时也比较容易。

bindParam 不是 bindValue 的循环版

bindParam() 绑定的是变量引用，变量会在 execute() 时取值。因此它适合绑定一个会在执行前更新的变量，但不适合把表达式、数组元素或临时返回值直接当成普通值传入：

bindParam(':sku', $sku, PDO::PARAM_STR);
$statement->bindParam(':quantity', $quantity, PDO::PARAM_INT);
$statement->bindParam(':note', $note, PDO::PARAM_STR);

foreach ($rows as $row) {
    // 先更新引用变量，execute() 执行时才读取它们的当前值。
    $sku = $row['sku'];
    $quantity = $row['quantity'];
    $note = $row['note'];
    $statement->execute();
}

如果只是“拿当前数组值执行一次”，bindValue() 或 execute() 的参数数组更容易读懂。不要把 bindParam() 当作接收任意表达式的函数；它的引用语义正是循环写入时最容易被忽略的差异。

不需要显式绑定时，直接传 execute 参数数组

对于只有输入参数的批量写入，可以把每行参数直接传给 execute()。这种方式不用维护绑定变量，也能复用预处理语句：

execute([
        'sku' => $row['sku'],
        'quantity' => $row['quantity'],
        'note' => $row['note'],
    ]);
}

这种写法适合参数类型已经稳定、且不需要在语句对象上逐个声明类型的场景。需要注意的是，PHP 手册说明通过 execute($params) 传入的值会按输入参数处理；若整数类型对数据库或驱动行为很重要，就使用前面的 bindValue() 显式指定类型。

整数、字符串和 null 要按字段语义处理

“不同参数”不只是不同内容，也包括不同类型。数量字段应按整数绑定，SKU 和备注按字符串绑定；可选备注为 null 时，不要把它机械转成字符串 ""，否则数据库中的 NULL 语义会消失：

bindValue(':quantity', (int) $row['quantity'], PDO::PARAM_INT);
    $statement->bindValue(':sku', (string) $row['sku'], PDO::PARAM_STR);

    // null 需要单独传递，空字符串与数据库 NULL 不是同一个值。
    $note = $row['note'] ?? null;
    $statement->bindValue(
        ':note',
        $note,
        $note === null ? PDO::PARAM_NULL : PDO::PARAM_STR
    );

    // 类型处理结束后再执行这一行。
    $statement->execute();
}

参数类型不能代替业务校验。数量是否允许为零、SKU 是否为空、备注长度是否超出表字段，都应该在进入写入循环前单独判断。绑定只负责把已确定的值安全地交给预处理语句。

事务边界决定批量写入是否完整

批量写入通常要求“全部成功或全部撤销”。beginTransaction() 会关闭自动提交，所有行执行成功后调用 commit()；捕获到异常时调用 rollBack()。事务开始前不要把半成品状态写入外部队列或响应对象，否则数据库回滚并不能撤销那些外部副作用。

还要留意数据库本身对事务的支持以及隐式提交行为。PHP 手册特别提醒，部分数据库在事务中执行 DDL 时可能产生隐式提交；因此批量业务写入应尽量只包含预期的数据变更，不要把建表、改表之类的 DDL 混在同一个业务事务里。

按错误位置排查而不是盲目重试

如果错误来自连接、SQL 约束或事务驱动能力，重试同一批数据并不会自动解决。先保留原始异常，再根据失败点修复参数、约束或事务边界，才能避免把重复写入问题扩大。

一份可直接套用的选择清单

1. SQL 是否固定，变化内容是否全部通过占位符传入？
2. 循环中只是绑定当前值，还是确实需要引用变量在执行前更新？前者优先选 bindValue()，后者才考虑 bindParam()。
3. 输入参数类型是否明确，整数、字符串和 NULL 是否按字段语义处理？
4. 是否在循环外开启事务，并只在全部执行成功后提交？
5. 异常处理是否只在 inTransaction() 为真时回滚，并保留原始错误？

结论可以压缩成一句话：批量写入复用一条预处理语句，当前行是普通值就用 bindValue() 或 execute($params)，需要引用变量语义才用 bindParam()；再用一个清晰的事务包住整个循环。

相关问题

• bindValue 和 bindParam 最大的区别是什么？bindValue 绑定当前值，bindParam 绑定变量引用并在 execute 时取值。
• 每一行都要重新 prepare 吗？不需要，SQL 结构一致时可以复用同一个预处理语句。
• execute 参数数组能指定 PDO::PARAM_INT 吗？这种写法适合简单输入；需要显式类型时改用 bindValue。
• 批次中一行失败怎么办？让异常进入统一处理，在仍处于事务时回滚，并保留错误上下文。