PHP PDO::FETCH_KEY_PAIR怎样把两列结果映射成键值表

PHP PDO 把两列查询结果转换成键值表，可以调用 $stmt->fetchAll(PDO::FETCH_KEY_PAIR)。查询结果必须恰好包含两列：第一列成为数组键，第二列成为对应值。它适合编码到名称、ID 到标题等小型字典映射；第一列必须在结果中唯一，否则会丢失值。

这个模式只改变取数后的结构，不会替你完成权限过滤、参数安全或唯一性判断。使用时应把键值关系和查询范围一并设计，尤其不能将不同租户的同名编码混在一个数组里。

官方地址：https://www.php.net/

先明确键值表承载什么数据

以租户内的工单状态字典为例，业务希望得到“状态编码到显示名称”的映射。假设表 ticket_status 包含 tenant_id、code、label、enabled，且数据库对 (tenant_id, code) 有非空唯一约束。下面只展示查询函数，不包含连接凭据或建表操作。

prepare(
        'SELECT code, label FROM ticket_status
         WHERE tenant_id = :tenant_id AND enabled = :enabled
         ORDER BY code'
    );

    try {
        $stmt->execute(['tenant_id' => $tenantId, 'enabled' => 1]);
        // 只选择两列，code为键，label为值
        return $stmt->fetchAll(PDO::FETCH_KEY_PAIR);
    } finally {
        // 释放语句游标，便于同一连接继续处理其他请求
        $stmt->closeCursor();
    }
}

若当前范围的查询行是 open / 待处理 与 closed / 已结束，映射语义就是 open 对应“待处理”、closed 对应“已结束”。这是说明结构的假设数据，本文没有连接数据库或执行代码。应用使用时可按状态编码直接查名称，不必为每次展示遍历全部行。

把列数和列顺序当成接口约定

FETCH_KEY_PAIR 依据结果列的位置工作，不依据列名是否叫 id、key 或 value。将查询改成 SELECT label, code，就把名称变成键了。给字段起别名有助于阅读，却不会改变第一列和第二列的角色。

不要使用 SELECT *。除了列数可能超过两列，后续表结构变化也容易改变结果形状。某次需求需要名称以外的颜色、排序号时，应改成返回完整行的模式，而不是继续强行套用两列映射。

重复键是数据丢失风险

官方手册明确指出，第一列不唯一时会丢失值，哪些值丢失不应被视为有保证的行为。不要把重复键当成“自动取最新记录”的写法，也不要只加 ORDER BY 就假设业务上的最新值一定被保留。选最新记录应在查询或业务逻辑中先定义规则。

唯一性必须针对实际查询结果判断。即使字典表自身的编码唯一，关联一对多明细后也可能让同一编码出现多行。应先修正关联或收敛结果，再映射，而不是把取数后数组变短当作正常去重。

若无法直接保证唯一、又需要在发现冲突时明确失败，可以改成逐行读取。下例假定 $stmt 已执行两列查询，且每个编码都是非空文本；它不与前面的 fetchAll() 接在同一个已消费结果集上运行。

fetch(PDO::FETCH_NUM)) !== false) {
        [$code, $label] = $row;
        // 前缀明确标识业务键，避免把纯数字编码当作连续数组下标使用
        $key = 'status:' . (string) $code;
        if (array_key_exists($key, $labels)) {
            throw new UnexpectedValueException('状态编码重复');
        }
        $labels[$key] = $label;
    }
} finally {
    $stmt->closeCursor();
}

这段代码选择的是“遇到重复就拒绝”的业务策略，而不是另一种 FETCH_KEY_PAIR 参数。前缀也会改变调用方取值的键，需要统一约定。PHP 数组键具有类型转换规则，例如部分数字字符串会转成整数，空值键会转为空字符串；需要保留编码身份时，应让存储约束和应用键规则一致。

把输入值与查询范围分别控制

预处理占位符用于绑定数据值，不能用来绑定表名、列名或排序关键字。示例把查询列固定在代码里，只绑定租户与启用状态。如果接口允许切换某种显示字典，应由服务端把有限选项映射到预先定义的查询，而不是让请求参数直接成为 SQL 片段。

参数绑定也不能证明调用方有权读取该租户的数据。$tenantId 应来自已经完成授权的业务上下文，而非原样相信请求中的编号。数据资产是租户自己的编码与名称，对应风险是跨范围读取；正确的转换模式无法补救错误的范围选择。

如果把字典结果放入缓存，缓存标识还要包含租户等影响查询结果的维度。否则两次查询分别正确，后续复用缓存时仍可能拿到另一个范围的映射。语言版本、多套状态规则等维度是否需要加入，应由应用实际的查询条件决定。

记录异常并限制一次读取的数据量

示例要求连接采用 PDO::ERRMODE_EXCEPTION，由应用统一处理数据库错误。不要捕获所有异常后直接返回空数组：这样会把查询失败与确实没有启用状态混为一谈，页面看起来只是没有选项，运维却失去故障线索。对用户返回简洁错误，对内部记录操作类别和关联编号即可，不必输出连接串或完整数据库异常到页面。

fetchAll() 读取结果集中剩余的行，因此不要在前面先调用 fetch() 消费一行，再期待键值表仍然完整。无匹配记录与结果集已经被消费，是两种不同原因。排查空结果时，先看查询条件和游标使用位置。

这种模式适合可控大小的字典。若要处理数百万条业务记录，数组仍然需要内存，不能因为省去一个 PHP 循环就把全量数据装入一次响应。需要分页、分批或逐行处理时，应按数据规模设计；逐行取数后仍把所有内容塞入数组，也不会消除最终数组的内存占用。

按样例清单确认映射语义

• 结果只有两列，第一列确实是业务查询键。
• 键在筛选和关联后的结果中唯一，数字、空值等编码有约定。
• 没有把一对多关系无意压成单值，也没有用覆盖代替“选最新”。
• 数据值绑定与租户授权分别处理，缓存按相同范围隔离。
• 空结果、数据库异常和已消费游标能够区分。
• 结果规模适合一次构建数组，多列需求使用其他模式。

名称相同但编码不同，会丢数据吗？

当编码在第一列时，相同名称只是第二列的相同值，不构成重复键。若颠倒列顺序，把名称当键，就会遇到另一种唯一性要求。

需要一个编码对应多个名称怎么办？

应保留多行并显式构造“编码到列表”的结构，或按已定义的分组取数方式处理。单值键值表不能表达一对多。

能用这个模式代替SQL权限过滤吗？

不能。它只负责结果形状。查询范围、调用方授权以及展示或缓存时的数据边界仍由应用决定。

官方资料：https://www.php.net/manual/en/pdo.constants.fetch-modes.php；https://www.php.net/manual/en/pdostatement.fetchall.php；https://www.php.net/manual/en/language.types.array.php；https://www.php.net/manual/en/pdo.prepare.php。