parse_str()的职责边界
parse_str()将符合URL查询字符串格式的输入解析为变量或数组。它模仿PHP自身处理$_GET、$_POST的方式，对输入执行URL解码和变量名规范化。
<?php
// 代码号学习PHP：基础解析行为
parse_str("name=John&age=26", $result);
print_r($result);
// Array ( [name] => John [age] => 26 )
函数签名从文档源文件可以看出经历了参数命名调整：早期为parse_str(string$str[,array&$arr])，后续修订为parse_str(string$encoded_string[,array&$result])。这一改动反映了文档对参数语义的明确。
变量名转换规则：一个容易被忽视的细节
查询字符串中的键名可能包含PHP变量命名不允许的字符。parse_str()对此采取了两套处理逻辑。
根键名的下划线替换：空格和点号会被转换为下划线。这是历史遗留行为，与register_globals时代保持兼容性有关。
<?php
// 代码号学习PHP：根键名规范化
parse_str("My Website=JavaTpoint", $output);
echo $output['My_Website']; // JavaTpoint
parse_str("na.me=kaibro&pass wd=ggininder", $test);
var_dump($test);
// ["na_me"] => "kaibro", ["pass_wd"] => "ggininder"
嵌套键名的特殊性：当键名包含方括号时，只有最外层的根键会被替换，内层键名保留原样。PHPBug报告中记录了这一行为：parse_str("aaa[heyall]=1",$r)的结果是array('aaa'=>array('heyall'=>'1'))，内层键名中的空格未被替换。
这是一个经过设计但容易引发调试困惑的行为。如果你需要解析含有特殊字符键名的查询字符串并保留原始键名，直接使用parse_str()无法满足需求。
数组解析的底层机制
parse_str()对key[]和key[index]格式有原生支持，这与PHP解析$_GET的机制一致。
PHP源码中的parse_str_basic3.phpt测试文件展示了完整的数组解析行为：
<?php
// 代码号学习PHP：数组格式解析（参考 PHP 官方测试用例）
$s1 = "first=abc&a[]=123&a[]=false&b[]=str&c[]=3.5&a[]=last";
parse_str($s1, $res);
var_dump($res);
输出结果中，a变成包含123、false、last三个元素的索引数组。数值键和关联键均被支持：arr[1]=sid&arr[4]=bill产生['arr'=>[1=>'sid',4=>'bill']]。
PHP版本差异
| 版本 | 变化 |
|---|---|
| PHP4 | 函数引入，最初无第二个参数 |
| PHP4.0.3 | 新增array参数 |
| PHP7.2.0 | 不带第二个参数使用时发出E_DEPRECATED警告 |
| PHP8.0.0 | 第二个参数变为强制要求 |
| PHP8.5（规划） | 引入新URI扩展，parse_str()仍可用但相关生态可能调整 |
E_DEPRECATED警告的引入有明确的安全背景。动态设置函数作用域变量与register_globals存在相同的安全问题，PHP文档对此有直接说明。
max_input_vars限制：容易被忽略的边界
这是parse_str()实际项目中容易踩到的限制。PHP的max_input_vars配置（默认1000）同样作用于parse_str()。当输入字符串包含超过此数量的变量对时，解析结果会被截断。
<?php
// 代码号学习PHP：max_input_vars 边界测试
$input = 'first=firstvalue';
for ($i = 1; $i <= 1100; $i++) {
$input .= '&arrLoopNumber[]=' . $i;
}
$output = [];
parse_str($input, $output);
// $output['arrLoopNumber'] 的元素数量不会达到 1100
如果你的应用需要解析来自API或配置文件的大型查询字符串，parse_str()可能因这一限制返回不完整结果。此时需要考虑分批次解析或改用其他解析策略。
常见错误与异常处理
parse_str()不抛出异常，其“错误”表现为静默的行为差异。
空值的处理：foo&bar格式的查询字符串中，无值的参数被解析为空字符串。parse_str("foo&bar",$r)产生['foo'=>'','bar'=>'']。
HTML实体编码的&：如果查询字符串中的&被编码为&，parse_str()无确分割参数对。这是不同编码方案混淆导致的，文档对此有说明——parse_str()期望的是URL编码后的参数值，而非HTML实体编码。
数值键的字符串化：arr[1]=sid&arr[4]=bill解析后，键1和4保持为整数键。但如果键名是arr[01]，需要留意PHP数组键的规范化规则。
与parse_url()的职责对比
两个函数常被组合使用，职责边界清晰：
| 函数 | 输入 | 输出 | 职责 |
|---|---|---|---|
parse_url() |
完整URL | 关联数组（scheme,host,path,query等） | 拆分URL结构 |
parse_str() |
查询字符串 | 变量或数组 | 拆分查询参数 |
<?php
// 代码号学习PHP：组合使用场景
$url = "https://example.com/search?q=php&page=2";
$parts = parse_url($url);
// $parts['query'] = "q=php&page=2"
parse_str($parts['query'], $params);
// $params = ['q' => 'php', 'page' => '2']
单独将完整URL传给parse_str()不会产生预期结果——函数会把https://example.com/search?q=php当作一个键值对处理。
性能与替代方案
parse_str()是C层面的实现，性能远高于PHP用户态逐字符解析。但它的替代方案在特定场景下更合适。
http_build_query()的反向操作：PHP5起，http_build_query()可以生成查询字符串，与parse_str()构成往返。
<?php
// 代码号学习PHP：往返操作
$params = ['action' => 'search', 'interest' => ['sports', 'music']];
$query = http_build_query($params);
// action=search&interest%5B0%5D=sports&interest%5B1%5D=music
parse_str($query, $restored);
// 结构基本还原，但数组键可能变为索引键
mb_parse_str()：多字节版本，行为类似但处理编码差异。parse_str()在单字节场景下更轻量。
常见误区速查
| 误区 | 实际行为 |
|---|---|
parse_str("MyValue=Something")产生$MyValue |
空格转下划线，产生$My_Value |
| 嵌套键名中的空格也会被替换 | 仅根键名被替换，内层保留原样 |
输入中的&可以用HTML实体&分隔 |
无法识别，需要原始& |
| 解析结果一定完整 | 受max_input_vars限制，超量部分被丢弃 |
| 无第二个参数只是风格问题 | PHP7.2+触发弃用警告，PHP8强制要求 |
现在框架中的惯用写法
Laravel、Symfony等框架不会在业务代码中直接暴露parse_str()。它们通过Request对象封装查询参数访问：
<?php
// Laravel 风格
$name = $request->query('name');
// Symfony 风格
$name = $request->query->get('name');
框架底层在初始化Request时使用parse_str()或类似机制填充参数包，业务层无需关心解析细节。直接使用parse_str()的场景集中在：自定义CLI工具解析参数、底层HTTP客户端库、与遗留系统交互的适配层。
延伸练习
练习一：编写一个函数，使用parse_str()解析查询字符串并检测根键名中是否含有被替换的特殊字符，返回原始键名与转换后键名的映射表。
练习二：在不使用max_input_vars限制的前提下，实现一个能解析超过5000个参数对的查询字符串的函数。提示：参考社区中proper_parse_str的实现思路。
练习三：对比parse_str()与手动explode('&')+explode('=',...)在解析100个简单参数对时的性能差异，并分析URL解码、数组格式、键名规范化三者的性能开销占比。
参考文献
PHP官方手册：parse_str()
https://www.php.net/manual/en/function.parse-str.php
官方函数文档，包含参数说明、返回值、版本变更记录以及关于max_input_vars限制的社区注释。
PHP源码测试：parse_str_basic3.phpt
https://svn.php.net/viewvc/php/php-src/trunk/ext/standard/tests/strings/parse_str_basic3.phpt
PHP官方测试文件，覆盖数组解析、数值键、关联键、编码数据、引号字符等场景，是理解函数实际行为的可靠依据。
PHPBug#55102：parse_str根键名清理行为
https://bugs.php.net/bug.php?id=55102
记录了对根键名中空格和点号被替换为下划线这一历史行为的讨论，解释了只清理根键而不清理嵌套键的原因。
PHP文档修订：parse-str.xml
https://svn.php.net/viewvc/phpdoc/en/trunk/reference/strings/functions/parse-str.xml
官方文档源文件的修订记录，展示了参数命名从$str/$arr到$encoded_string/$result的调整，以及PHP7.2弃用警告的添加过程。
PHPURI扩展RFC（PHP8.5）
https://wiki.php.net/rfc/url_parsing_api
PHP8.5引入的新URI扩展设计文档，涉及URL解析生态的长期演进方向，parse_str()在该框架下仍作为查询字符串解析工具使用。
