Guzzle如何设置同名查询参数 解决数组传参编码异常问题

问题原因 #

将同名参数对应值设为数组时出现转义异常，是Guzzle默认查询字符串编码规则导致的：默认规则下数组类型参数会被自动添加[索引]后缀，最终生成格式为item_id[0]=123&item_id[1]=3243的参数，其中的方括号[]经过URL编码后会变为%5B、%5D这类异常字符串，后端接口无法识别这种带方括号的数组传参格式时，就会返回错误请求。

可用解决方案 #

方案1：内置Query类构建（推荐，适用于Guzzle 6+版本） #

使用Guzzle自带的GuzzleHttp\Psr7\Query类构建查询字符串，关闭数组参数的方括号后缀生成逻辑，直接输出重复同名参数：

use GuzzleHttp\Psr7\Query;

$query_params = [
    'test' => 'abc',
    'test2' => true,
    'limit' => 10,
    'item_id' => ['8159', '333', '435', '123']
];

// 第三个参数传false，即不对数组参数添加[]索引后缀
$queryString = Query::build($query_params, PHP_QUERY_RFC1738, false);

$response = $this->client->request('GET', $endpoint, [
    'headers' => [
        'X-API-KEY' => KEY
    ],
    'query' => $queryString
]);

该方式生成的查询字符串完全符合预期格式：?test=abc&test2=1&limit=10&item_id=8159&item_id=333&item_id=435&item_id=123，无多余转义字符。

方案2：手动拼接查询字符串（兼容所有Guzzle版本） #

如果使用的Guzzle版本不支持上述构建方法，可以手动拼接查询字符串传入配置：

$itemIdList = ['8159', '333', '435', '123'];
$baseParams = [
    'test' => 'abc',
    'test2' => true,
    'limit' => 10
];

// 先构建非重复参数部分
$queryStr = http_build_query($baseParams);
// 逐段追加同名参数
foreach ($itemIdList as $id) {
    $queryStr .= '&item_id=' . urlencode($id);
}

$response = $this->client->request('GET', $endpoint, [
    'headers' => [
        'X-API-KEY' => KEY
    ],
    'query' => $queryStr
]);

注意：Guzzle接收到字符串格式的query参数时，会默认该字符串已经完成合规编码，不会做二次转义，因此手动拼接时必须对参数值做urlencode处理，避免特殊字符引发请求错误。

内容的提问来源于stack exchange，提问作者emrez