PHP PDO::FETCH_KEY_PAIR 怎么构造键值映射

PDO::FETCH_KEY_PAIR 的用途很直接：让一条只返回两列的查询变成 PHP 键值数组。第一列作为数组键，第二列作为对应值；调用方式是 $stmt->fetchAll(PDO::FETCH_KEY_PAIR)。因此，决定结果形状的关键不是字段名，而是 SQL 中的列数和列顺序。

最小写法：第一列作键，第二列作值

假设 categories 表里有 id 与 name，需要得到“分类编号 => 分类名称”的映射，查询只选择这两列即可：

$stmt = $pdo->query(
    'SELECT id, name FROM categories ORDER BY id'
);

$categoryMap = $stmt->fetchAll(PDO::FETCH_KEY_PAIR);

// 结果形状示例：
// [
//     10 => 'PHP',
//     20 => 'Go',
//     30 => 'Python',
// ]

如果把 SQL 写成 SELECT name, id，结果会立刻反过来，变成“名称 => 编号”。FETCH_KEY_PAIR 不读取 AS key 或 AS value 之类的特殊别名，它只认位置：第 1 列是键，第 2 列是值。

带条件查询时照常使用预处理语句

获取模式不影响参数绑定。实际项目里可以先准备和执行查询，再把剩余结果一次取成映射：

$stmt = $pdo->prepare(
    'SELECT code, label
     FROM status_dictionary
     WHERE locale = :locale AND enabled = :enabled
     ORDER BY sort_order'
);

$stmt->execute([
    'locale' => 'zh-CN',
    'enabled' => 1,
]);

$statusMap = $stmt->fetchAll(PDO::FETCH_KEY_PAIR);

if ($statusMap === []) {
    // 查询成功但没有匹配记录；根据业务决定使用默认字典还是返回空选项。
}

这种返回形状适合下拉选项、状态码文案、配置字典和“编号换显示名”的快速查找。查询条件、排序和唯一性约束仍由 SQL 与数据库负责，获取模式只决定 PDO 如何组织已经返回的行。

与 array_column、FETCH_ASSOC 和 FETCH_UNIQUE 的区别

几种写法都能围绕某一列构造索引，但返回形状不同。只需要一键一值时，FETCH_KEY_PAIR 最短，也能让 SQL 明确只传输两列。

如果业务已经需要完整行，不必为了映射再执行一次数据库查询；可以先用 FETCH_ASSOC 取得行集，再用 array_column($rows, 'label', 'code') 派生映射。反过来，如果最终只消费键和值两列，直接使用 FETCH_KEY_PAIR 更能表达意图。

重复键和一对多关系怎么处理

官方文档明确提醒：第一列不唯一时会丢失值，而且不应依赖究竟保留哪一个值。因此不能把重复键覆盖当作稳定的“取最后一条”策略。最稳妥的做法是让第一列来自主键、唯一索引，或在 SQL 中先把数据收敛到每个键一行。

如果同一个键本来就对应多个值，例如“部门 => 员工姓名列表”，目标就不是键值对，而是分组结果。可以改用：

$stmt = $pdo->query(
    'SELECT department_id, employee_name
     FROM employees
     ORDER BY department_id, employee_name'
);

$employeesByDepartment = $stmt->fetchAll(
    PDO::FETCH_GROUP | PDO::FETCH_COLUMN
);

// 结果形状：
// [
//     1 => ['Alice', 'Bob'],
//     2 => ['Carol'],
// ]

上线前检查四个边界

• 列数：结果必须只有两列，新增第三列会改变该获取模式的适用条件。
• 列顺序：代码评审时把“第一列是键、第二列是值”写进查询附近的注释，避免重排后静默反转。
• 键唯一性：优先依赖主键或唯一约束，不用偶然不重复的数据做保证。
• 结果规模：fetchAll() 会一次取回剩余结果；大结果集应先用 WHERE、分页或更小的数据范围收敛，而不是构造超大映射。

还要留意 PHP 数组键的类型语义：来自数据库的数字编号可能以整数或字符串形式返回，具体取决于驱动与连接配置。若后续代码使用严格比较，建议在业务边界统一键的类型，而不是让调用方自行猜测。

常见问题

为什么加了第三列后不应该继续用 FETCH_KEY_PAIR？

因为这个模式要求结果只包含两列。若要以第一列为索引并保留多个字段，应改用 FETCH_UNIQUE 或先取关联数组再自行重组。

键和值一定要写成 key、value 这两个别名吗？

不需要。字段名和别名不会决定映射方向，列顺序才决定：第一列是键，第二列是值。

查询没有记录时会返回 false 吗？

fetchAll() 在没有可取记录时返回空数组，可以直接与 [] 比较或用 count() 判断。

重复键时能否依赖后出现的值覆盖前一个值？

不能。官方文档将丢失哪个值视为未定义；需要确定规则时，应在 SQL 中先明确聚合或筛选，或者改成分组结果。

判断是否该用 PDO::FETCH_KEY_PAIR，只需问三个问题：结果是不是恰好两列、第一列是不是唯一、业务是不是一键一值。三个答案都是“是”，它就是构造数据库键值映射最直接的获取模式。