http_build_query 生成 url-encoded 之后的请求字符串

封面图 • 2025-04-27 • PHP

`http_build_query` 是 PHP 中的一个内置函数，用于将数组或对象转换为 URL 查询字符串（URL-encoded）。它会按照一定的规则对键值对进行编码，并以 `key=value` 的形式连接起来，通常用于构建 HTTP 请求参数。

### 函数语法：
```php
string http_build_query ( mixed $query_data [, string $numeric_prefix [, string $arg_separator [, int $encoding_type ]]] )
```

#### 参数说明：
1. **`$query_data`**:
   - 必填参数，可以是数组或对象。
   - 如果是数组，每个元素会被转换为 `key=value` 的形式。
   - 如果是对象，则对象的属性会被转换为 `key=value` 的形式。

2. **`$numeric_prefix`**（可选）:
   - 当数组中包含数字键时，可以用这个参数作为前缀。默认为空字符串。

3. **`$arg_separator`**（可选）:
   - 指定分隔符，默认是 `&`。

4. **`$encoding_type`**（可选）:
   - 指定编码类型，默认是 `PHP_QUERY_RFC3986`（RFC 3986 标准），也可以使用 `PHP_QUERY_RFC1738`。

---

### 示例代码：

#### 示例 1: 基本用法
```php
$data = [
    'name' => '张三',
    'age' => 25,
    'hobbies' => ['reading', 'swimming']
];

$query_string = http_build_query($data);
echo $query_string;
```

**输出结果：**
```
name=%E5%BC%A0%E4%B8%89&age=25&hobbies[0]=reading&hobbies[1]=swimming
```

---

#### 示例 2: 使用自定义分隔符
```php
$data = [
    'page' => 1,
    'limit' => 10
];

$query_string = http_build_query($data, '', ';');
echo $query_string;
```

**输出结果：**
```
page=1;limit=10
```

---

#### 示例 3: 数字键的处理
```php
$data = [
    0 => 'apple',
    1 => 'banana'
];

$query_string = http_build_query($data, 'num_');
echo $query_string;
```

**输出结果：**
```
num_0=apple&num_1=banana
```

---

#### 示例 4: 编码类型
```php
$data = [
    'file' => 'image.jpg'
];

// 默认使用 PHP_QUERY_RFC3986
$query_string_rfc3986 = http_build_query($data);
echo $query_string_rfc3986; // 输出：file=image.jpg

// 使用 PHP_QUERY_RFC1738
$query_string_rfc1738 = http_build_query($data, '', '&', PHP_QUERY_RFC1738);
echo $query_string_rfc1738; // 输出：file=image.jpg
```

---

### 注意事项：
1. **数组嵌套**:
   - 如果数组中有嵌套结构（例如二维数组），`http_build_query` 会自动将嵌套结构展开为带有索引的字符串。例如：
     ```php
     $data = [
         'user' => [
             'name' => '李四',
             'age' => 30
         ]
     ];
     echo http_build_query($data);
     ```
     输出：
     ```
     user[name]=%E6%9D%8E%E5%9B%9B&user[age]=30
     ```

2. **对象支持**:
   - 如果传入的对象没有实现 `ArrayAccess` 或 `IteratorAggregate` 接口，则只会转换对象的公共属性。

3. **特殊字符**:
   - 函数会对键和值进行 URL 编码（如空格会被替换为 `%20`，特殊字符会被转义）。

---

通过 `http_build_query`，你可以轻松地将复杂的数据结构转换为符合 HTTP 协议要求的查询字符串，非常适合用于构建 GET 请求的参数。