PHP http_build_query 深度解析：陣列轉 URL 參數、多維編碼、索引前綴與對象支援

PHP http_build_query 深度解析：陣列轉 URL 參數、多維編碼、索引前綴與對象支援

http_build_query() 是將陣列/物件序列化為 URL 查詢字串 (application/x-www-form-urlencoded) 的標準函數，自動處理 urlencode、多維陣列方括號語法、數字索引前綴。本文系統講解參數、輸出格式、邊界情況與反向解析 parse_str。

一、基本語法與參數

string http_build_query(
    mixed $data,           // 陣列或物件 (public 屬性)
    string $numeric_prefix = '', // 數字索引鍵名前綴
    string $arg_separator = ini_get('arg_separator.output') // 分隔符，預設 &
)

二、核心範例與輸出格式

1. 簡單關聯陣列

<?php
$data = [
    'foo' => 'bar',
    'baz' => 'boom',
    'site' => 'www.example.com',
    'name' => 'nowa magic',
];
echo http_build_query($data);
// foo=bar&baz=boom&site=www.example.com&name=nowa+magic
?>

2. 數字索引混合關聯陣列

<?php
$data = ['foo', 'bar', 'site' => 'www.example.com'];
echo http_build_query($data);
// 0=foo&1=bar&site=www.example.com

echo http_build_query($data, 'nm_');
// nm_0=foo&nm_1=bar&site=www.example.com
?>

規則：僅**最外層**數字索引鍵加前綴；巢狀陣列數字索引不加 (如 pastimes[0])，因方括號語法已合法。

3. 多維陣列 (方括號語法)

<?php
$data = [
    'user' => [
        'name' => 'Bob Smith',
        'age'  => 47,
        'sex'  => 'M',
        'dob'  => '5/12/1956',
    ],
    'pastimes' => ['golf', 'opera', 'poker', 'rap'],
    'children' => [
        'bobby' => ['age' => 12, 'sex' => 'M'],
        'sally' => ['age' => 8,  'sex' => 'F'],
    ],
    'CEO', // 數字索引 0
];
echo http_build_query($data);
/* 輸出 (已 urlencode)：
user%5Bname%5D=Bob+Smith&user%5Bage%5D=47&user%5Bsex%5D=M&user%5Bdob%5D=5%2F12%2F1956
&pastimes%5B0%5D=golf&pastimes%5B1%5D=opera&pastimes%5B2%5D=poker&pastimes%5B3%5D=rap
&children%5Bbobby%5D%5Bage%5D=12&children%5Bbobby%5D%5Bsex%5D=M
&children%5Bsally%5D%5Bage%5D=8&children%5Bsally%5D%5Bsex%5D=F
&0=CEO
*/
?>

4. 物件支援 (public 屬性)

<?php
class MyClass {
    public $foo = 'bar';
    public $baz = 'boom';
}
$data = new MyClass();
echo http_build_query($data); // foo=bar&baz=boom
?>

三、反向解析：parse_str

<?php
$str = 'foo=bar&baz=boom&user%5Bname%5D=Bob+Smith';
parse_str($str, $arr);
print_r($arr);
/* Array
(
    [foo] => bar
    [baz] => boom
    [user] => Array ( [name] => Bob Smith )
)
*/
?>

注意：parse_str 無第二參數時會直接註冊全域變數 (已棄用/移除)，**務必傳第二參數陣列接收**。

四、配套函數：parse_url

<?php
$url = 'https://user:pass@example.com:8080/path?foo=bar&baz=boom#fragment';
print_r(parse_url($url));
/* Array
(
    [scheme] => https
    [host] => example.com
    [port] => 8080
    [user] => user
    [pass] => pass
    [path] => /path
    [query] => foo=bar&baz=boom
    [fragment] => fragment
)
*/
?>

五、常見坑點與最佳實踐

1. 空值處理：['key' => ''] 輸出 key=；['key' => null] 輸出 key= (PHP 8.1+ 拋警告)；建議預先 array_filter($data, fn($v) => $v !== null)。
2. 布林值：true → '1'、false → '' (空字串)；API 若需 true/false 字串需自行轉換。
3. 巢狀物件/資源：不支援，會觸發 Notice 並跳過；請先轉陣列 json_decode(json_encode($obj), true)。
4. 分隔符：預設 &，某些舊系統需 & (HTML 實體)；傳第三參數 '&'。
5. 超長 URL：GET 請求長度受限 (瀏覽器/伺服器約 2-8KB)；大量資料請改 **POST + json_encode**。