SaloonPHP 中参数点号转下划线问题的分析与解决

问题背景

在使用SaloonPHP进行API开发时，开发者可能会遇到一个令人困惑的问题：当请求参数中包含点号(.)时，这些点号会被自动转换为下划线(_)。例如，请求URL中的account.id参数会被转换为account_id，导致API服务端无法正确识别参数。

问题根源

这一问题的根源在于SaloonPHP内部使用了PHP的parse_str函数来处理查询参数。根据PHP官方文档的说明：

由于PHP变量名不能包含点和空格，这些字符会被转换为下划线。当使用此函数处理结果参数时，同样适用于相应键名的命名规则。

具体到SaloonPHP的实现，在ManagesPsrRequests特性中，有以下代码片段：

parse_str($uri->getQuery(), $existingQuery);
return $uri->withQuery(
    http_build_query(array_merge($existingQuery, $this->query()->all()))
);

这种处理方式会导致所有包含点号的参数名在解析过程中被自动转换。

临时解决方案

在等待官方修复期间，开发者可以采用以下临时解决方案：

1. 使用ArrayStore直接设置参数：

public function query() : ArrayStoreContract
{
    $query = new ArrayStore();
    $query->set([ "account.id" => $this->accountId ]);
    return $query;
}

2. 使用defaultQuery方法（推荐方式）：

protected function defaultQuery(): array
{
    return [
        'account.id' => $this->accountId,
    ];
}

3. 直接在resolveEndpoint中构建完整URL：

public function resolveEndpoint() : string
{
    return "/zones?account.id={$this->accountId}";
}

官方修复方案

SaloonPHP团队已经意识到这个问题，并提出了更健壮的解决方案。新方案将不再依赖parse_str函数，而是采用自定义的查询字符串解析器，主要改进包括：

1. 正确处理包含点号的参数名
2. 支持URL编码的字符（使用urldecode处理）
3. 处理边界情况（如空参数名、空值等）

新解析器的核心逻辑如下：

$parameters = explode('&', $queryString);
$result = [];

foreach ($parameters as $parameter) {
    $name = urldecode((string) strtok($parameter, '='));
    $value = urldecode((string) strtok('='));
    
    if (str_starts_with($parameter, "=") || !$name) {
        continue;
    }
    
    $result[$name] = $value;
}

最佳实践建议

1. 对于需要保留特殊字符的参数名，优先使用defaultQuery方法
2. 升级到包含此修复的SaloonPHP版本后，可以安全地在参数名中使用点号
3. 在构建复杂查询时，注意测试参数传递的正确性
4. 了解目标API对参数命名的具体要求，必要时进行编码处理

总结

参数名中的特殊字符处理是HTTP客户端开发中常见的边缘情况。SaloonPHP通过改进查询字符串解析逻辑，解决了点号被自动转换的问题，为开发者提供了更灵活的API调用方式。开发者应及时更新到包含此修复的版本，并按照推荐的最佳实践来构建请求参数。