php http_build_query — 生成 URL-encode 之后的请求字符串

深入解析PHP内置函数 http_build_query 的完整用法、参数细节、常见陷阱与实战技巧

⚡ http_build_query 是什么?

http_build_query 是 PHP 内置的用于将数组或对象转换为 URL 编码查询字符串的函数,其核心功能是将结构化数据(如关联数组)安全地转换为可附加在 URL 后的查询参数字符串(query string),格式为:key1=value1&key2=value2&...。

该函数自 PHP 5 起便已存在,广泛应用于 API 请求构建、表单数据提交、重定向参数传递等场景,是 PHP 开发者处理 URL 参数构建时最常用的工具函数之一。

其设计初衷是解决手动拼接查询字符串时可能出现的编码错误、重复键冲突、嵌套结构处理不当等问题,提供一套标准化、可靠的参数序列化方案。

🔍 核心价值

  • 自动 URL 编码:对键与值进行 urlencode 处理,避免特殊字符破坏 URL 结构
  • 嵌套支持:可自动处理多维数组与对象,生成 key[subkey] 形式的键名
  • 自定义分隔符:支持自定义参数分隔符(默认 &),适配不同协议要求
  • 兼容对象:支持 PHP 对象(通过公共属性转换),无需手动展开

⚙️ http_build_query 语法详解

http_build_query (
    mixed $data,
    ?string $numeric_prefix = null,
    string $arg_separator = "&",
    int $encoding_type = PHP_QUERY_RFC1738
): string

该函数接受最多四个参数,返回一个经过 URL 编码的查询字符串;若传入空数组或无效类型,则返回空字符串。

📌 返回值说明

  • 成功时:返回格式为 key1=value1&key2=value2 的字符串
  • 失败时(如传入 false 或资源类型):返回空字符串 ""
  • 注意:返回字符串中,& 不会被 HTML 转义(需在 HTML 中使用时注意)

〔参数〕完整说明

1. $data:必需,混合类型

可为数组或对象。数组中键为字符串(或可转为字符串),值为标量、数组或对象;对象仅转换其公共属性。

示例:关联数组

$data = [
    'name' => '张三',
    'age' => 28,
    'city' => '成都'
];
echo http_build_query($data);
// 输出:name=%E5%BC%A0%E4%B8%89&age=28&city=%E6%88%90%E9%83%BD

示例:索引数组(数字键)

$data = ['apple', 'banana', 'cherry'];
echo http_build_query($data);
// 输出:0=apple&1=banana&2=cherry

示例:多维数组

$data = [
    'user' => [
        'name' => '李四',
        'info' => [
            'email' => 'lisi@example.com',
            'phone' => '13800138000'
        ]
    ],
    'role' => 'admin'
];
echo http_build_query($data);
// 输出:user[name]=%E6%9D%8E%E5%9B%9B&user[info][email]=lisi%40example.com&user[info][phone]=13800138000&role=admin

💡 特殊处理规则

  • 数字键名若无 $numeric_prefix,将被转为字符串键(如 0 → 0)
  • 嵌套数组键名自动添加 [] 或 [key] 形式
  • 布尔值:true → 1,false → 空字符串(非 0)
  • NULL:转换为空字符串(如 key=)
  • 对象:仅转换公共属性;若属性为对象或数组,递归处理

2. $numeric_prefix:可选,字符串或 null

为索引数组的数字键名添加前缀(仅对第一层数组有效),避免键名冲突或增强可读性。

$data = ['apple', 'banana'];
echo http_build_query($data, 'item_');
// 输出:item_0=apple&item_1=banana

注意:仅影响顶层索引键;嵌套数组中的数字键不受影响。

3. $arg_separator:可选,默认 &

指定参数分隔符。可选值:&(RFC1738)、&(RFC3986)、;(旧式 CGI)等。

$data = ['a' => 1, 'b' => 2];
echo http_build_query($data, null, ';');
// 输出:a=1;b=2

⚠️ 安全提示

在 HTML 中使用时,应使用 &(HTML 实体),否则会导致验证错误;若需在 HTML 属性中使用,应先进行 HTML 转义:

<a href="page.php?&".http_build_query($data)."">链接</a>

4. $encoding_type:可选,默认 PHP_QUERY_RFC1738

指定编码方式,可选常量:

$data = ['msg' => 'hello world'];
echo http_build_query($data, null, '&', PHP_QUERY_RFC1738);
// 输出:msg=hello+world
echo http_build_query($data, null, '&', PHP_QUERY_RFC3986);
// 输出:msg=hello%20world

🔍 编码差异对比

字符RFC1738RFC3986
空格+%20
中文%E5%BC%A0%E5%BC%A0
&%26%26
=%3D%3D

现代 Web 标准(如 OAuth、REST API)更推荐 PHP_QUERY_RFC3986;但部分旧系统(如 Apache 2.x 默认配置)可能仅支持 + 表示空格。

〔示例〕典型应用场景

基础用法
API 请求构建
嵌套参数
对象序列化
重定向跳转

① 基础数组转查询串

$params = [
    'action' => 'search',
    'q' => 'PHP 教程',
    'page' => 2
];
$url = 'https://www.example.com/search.php?' . http_build_query($params);
echo $url;
// 输出:https://www.example.com/search.php?action=search&q=PHP+%E6%95%99%E7%A8%8B&page=2

注意:中文被自动 %E6%95%99%E7%A8%8B 编码,空格转为 +(RFC1738 模式)。

② 构建 RESTful API 请求参数

$apiParams = [
    'api_key' => 'sk_live_abc123',
    'timestamp' => time(),
    'nonce' => bin2hex(random_bytes(8)),
    'data' => json_encode(['user_id' => 1001])
];
$query = http_build_query($apiParams, null, '&', PHP_QUERY_RFC3986);
// 生成:api_key=sk_live_abc123&timestamp=1717020000&nonce=...&data=%7B%22user_id%22%3A1001%7D

💡 实战技巧:签名前序列化

在生成 API 签名(如 MD5/SHA256)前,常需对参数字典序排序后再序列化,http_build_query 可作为最终编码步骤:

function signParams($params, $secret) {
    ksort($params);
    $str = http_build_query($params, null, '&', PHP_QUERY_RFC3986);
    return md5($str . $secret);
}

③ 多层嵌套参数(表单模拟)

$formData = [
    'user' => [
        'profile' => [
            'name' => '王五',
            'age' => 32
        ],
        'contact' => [
            'email' => 'wang@example.com',
            'phones' => ['13900139000', '028-88888888']
        ]
    ]
];
echo http_build_query($formData);
// 输出:
// user[profile][name]=%E7%8E%8B%E4%BA%94&
// user[profile][age]=32&
// user[contact][email]=wang%40example.com&
// user[contact][phones][0]=13900139000&
// user[contact][phones][1]=028-88888888

后端可直接通过 $_POST['user']['profile']['name'] 获取,与 HTML 表单提交格式完全一致。

④ 对象转查询字符串

class User {
    public $name = '赵六';
    public $email = 'zhao@example.com';
    private $password = 'secret123'; // 不会被转换
    protected $role = 'member';      // 不会被转换
}
$user = new User();
echo http_build_query($user);
// 输出:name=%E8%B5%B5%E5%85%AD&email=zhao%40example.com

仅公共属性被序列化;若需转换受保护属性,需实现 JsonSerializable 或自定义方法。

⑤ 重定向时附加参数

$redirectUrl = '/dashboard';
$params = [
    'from' => 'login',
    'remember' => true,
    'token' => bin2hex(random_bytes(16))
];
header('Location: ' . $redirectUrl . '?' . http_build_query($params));
exit;

⚠️ 安全注意

若 $redirectUrl 来自用户输入,必须进行白名单校验,避免开放重定向漏洞(Open Redirect)!

〔对比〕与 urlencode / json_encode 的区别

① http_build_query vs urlencode

特性http_build_queryurlencode
输入类型数组/对象字符串
输出格式k1=v1&k2=v2单个编码值
嵌套支持自动处理多维结构需手动拼接
适用场景构建 URL 查询串编码单个参数值
// urlencode 示例
$params = [
    'q' => urlencode('PHP 教程'),
    'page' => 2
];
$query = 'q=' . $params['q'] . '&page=' . $params['page'];
// 等价于 http_build_query(['q' => 'PHP 教程', 'page' => 2])

② http_build_query vs json_encode

特性http_build_queryjson_encode
输出格式URL 编码字符串JSON 字符串
浏览器解析直接作为 query string需手动解析(如 URLSearchParams)
HTTP 方法GET/POST(表单格式)POST(application/json)
编码空格+(RFC1738)%20

💡 实战建议

  • 前端用 fetch 发送 JSON:用 json_encode,设置 Content-Type: application/json
  • 传统表单提交或 GET 请求:用 http_build_query
  • 混合场景(如 OAuth):通常要求 RFC3986 编码的 query string

〔陷阱〕常见错误与解决方案

① 中文空格编码不一致导致的问题

在部分服务器(如 Nginx + PHP-FPM)中,若请求头未指定 Accept-Charset,空格可能被错误解析为 %20 而非 +,导致参数丢失。

// 问题代码
$params = ['msg' => '你好 世界']; // 含两个空格
$query = http_build_query($params); // 默认 RFC1738 → msg=%E4%BD%A0%E5%A5%BD+%E4%B8%96%E7%95%8C
// 若服务端严格按 RFC3986 解析,+ 会被视为字面字符而非空格!

解决方案:统一使用 PHP_QUERY_RFC3986:

$query = http_build_query($params, null, '&', PHP_QUERY_RFC3986);
// msg=%E4%BD%A0%E5%A5%BD%20%E4%B8%96%E7%95%8C

② 布尔值与 NULL 的意外结果

$data = ['active' => true, 'deleted' => false, 'note' => null];
echo http_build_query($data);
// 输出:active=1&deleted=&note=

false 被转为空字符串,null 同理。若需保留逻辑值,应手动转换:

$data = ['active' => $data['active'] ? 'yes' : 'no', 'deleted' => $data['deleted'] ? '1' : '0', 'note' => $data['note'] ?? ''];
echo http_build_query($data);

③ 键名含特殊字符导致解析失败

若数组键名含 [、]、. 等字符,会被视为嵌套结构:

$data = ['user.name' => '张三', 'user[age]' => 28];
echo http_build_query($data);
// 输出:user[name]=%E5%BC%A0%E4%B8%89&user[age]=28

实际生成了 user[name] 而非 user.name!

解决方案:对键名预处理,或使用自定义分隔符(如 _):

function safeKeys($arr) {
    $result = [];
    foreach ($arr as $k => $v) {
        $newKey = preg_replace('/[.\[\]]/', '_', $k);
        $result[$newKey] = $v;
    }
    return $result;
}
$data = safeKeys($data);
echo http_build_query($data); // user_name=...&user_age=28

④ 大数据量性能问题

对于超大数组(如 >10,000 项),http_build_query 可能消耗较多内存与时间(需递归处理嵌套结构)。

优化建议:

  • 分批处理(分页查询)
  • 仅传递必要字段
  • 对非必要嵌套字段手动扁平化
  • 用 json_encode + base64 编码后传参(减少 URL 长度)

〔优化〕性能提升技巧

① 避免重复编码

若值已被编码,再次调用 http_build_query 会导致双重编码:

$value = urlencode('a=b'); // "a%3Db"
$params = ['q' => $value];
echo http_build_query($params);
// 输出:q=a%253Db(%3D 被二次编码为 %253D)

解决方案:使用 PHP_QUERY_RFC3986 + rawurlencode 统一编码方式:

$value = rawurlencode('a=b'); // "a%3Db"
$params = ['q' => $value];
echo http_build_query($params, null, '&', PHP_QUERY_RFC3986);
// 输出:q=a%3Db(正确保留)

② 自定义分隔符优化可读性

长查询字符串中,用 & 分隔易与 HTML 实体混淆;可改用 &(HTML 安全)或自定义符号:

$query = http_build_query($data, null, '&');
// HTML 中:<a href="search.php?&".http_build_query($data)."">

③ 缓存高频参数组合

对固定参数结构,可缓存生成的查询串:

$cacheKey = md5(serialize($params));
if (!isset($cache[$cacheKey])) {
    $cache[$cacheKey] = http_build_query($params);
}
$query = $cache[$cacheKey];

〔应用〕典型使用场景

① API SDK 参数构建

class ApiClient {
    private $baseUrl;
    private $apiKey;
    public function get($endpoint, array $params = []) {
        $params['api_key'] = $this->apiKey;
        $params['timestamp'] = time();
        $query = http_build_query($params, null, '&', PHP_QUERY_RFC3986);
        $url = $this->baseUrl . $endpoint . '?' . $query;
        // 发起请求...
    }
}

② 表单预填充(单页应用 SPA)

// 生成预填充链接
$params = [
    'form_id' => 'contact',
    'data' => json_encode(['name' => '张三', 'email' => 'zhang@example.com'])
];
$link = '/form?' . http_build_query($params);
// 前端解析 data 字段,恢复表单状态

③ OAuth 参数签名

OAuth 1.0a 要求对参数字典序排序后生成 base_string,其中需用 http_build_query 编码:

function oauthSign($params, $secret) {
    ksort($params);
    $normalized = http_build_query($params, null, '&', PHP_QUERY_RFC3986);
    return urlencode($normalized); // 用于签名 base string

④ 多语言 URL 生成

$lang = 'zh-CN';
$params = ['page' => 'home', 'q' => '搜索词'];
$query = http_build_query($params, null, '&', PHP_QUERY_RFC3986);
$url = "/$lang/search?$query";

〔FAQ〕高频问题解答

Q:如何生成不带方括号的嵌套参数?

A:使用自定义扁平化函数,或改用 PHP_QUERY_RFC3986 + 手动拼接:

$data = ['user' => ['name' => '张三']];
// 手动转为:user_name=...
function flatten($arr, $prefix = '') {
    $result = [];
    foreach ($arr as $k => $v) {
        $key = $prefix ? "$prefix[$k]" : $k;
        if (is_array($v)) {
            $result = array_merge($result, flatten($v, $key));
        } else {
            $result[$key] = $v;
        }
    }
    return $result;
}
$params = flatten($data);
echo http_build_query($params); // user[name]=%E5%BC%A0%E4%B8%89

Q:http_build_query 会自动排序键名吗?

A:不会!键顺序与输入数组一致。若需字典序排序,需手动 ksort():

$data = ['z' => 3, 'a' => 1, 'm' => 2];
echo http_build_query($data);
// 输出:z=3&a=1&m=2
ksort($data);
echo http_build_query($data);
// 输出:a=1&m=2&z=3

Q:如何处理值为对象的数组?

A:http_build_query 仅转换对象的公共属性。若对象有自定义序列化逻辑,应实现 JsonSerializable:

class Custom {
    public $id = 123;
    public $data = ['x' => 1, 'y' => 2];
    public function __toString() {
        return json_encode($this->data);
    }
}
$params = ['obj' => new Custom()];
echo http_build_query($params);
// 输出:obj={"x":1,"y":2}(对象转为 JSON 字符串后编码)

Q:PHP 8.1+ 中 $numeric_prefix 支持嵌套吗?

A:不支持!$numeric_prefix 仅对顶层索引数组有效,嵌套数组中的数字键不受影响。这是 PHP 设计决定,非 bug。

〔拓展〕常见问题速查表

问:如何让所有值都为字符串类型?

答:用 array_map('strval', $data) 预处理。

问:如何过滤空值参数?

答:$data = array_filter($data, fn($v) => $v !== '' && $v !== null)。

问:如何自定义空格编码为 %20?

答:http_build_query($data, null, '&', PHP_QUERY_RFC3986)。

问:如何支持中文键名?

答:直接使用,PHP 会自动 urlencode 中文键名(如 %E4%B8%AD%E6%96%87)。

问:如何避免键名带方括号?

答:改用自定义扁平化函数,或用点号分隔(如 user.name)。