====== PHP RFC: Add http_parse_query as an alternative to parse_str ======
  * Date: 2021-06-23
  * Author: Kamil Tekiela <dharman@php.net>
  * Status: Withdrawn
  * Implementation: https://github.com/php/php-src/pull/7344
  * Target Version: PHP 8.2

===== Introduction =====

PHP offers a function for parsing query string into an array. The function, for historical reasons, has been designed to allow registering the values as global variables. Since PHP 8.0 this is no longer possible. The function still has two main downsides: a confusing name, and no return value (it returns by out parameter instead). 

<PHP>
$str = "first=value&arr[]=foo+bar&arr[]=baz";

parse_str($str, $output);
echo $output['first'];  // value
echo $output['arr'][0]; // foo bar
echo $output['arr'][1]; // baz
</PHP>


===== Proposal =====

The proposal is to create a new function as a copy of %%parse_str()%% but change the name to %%http_parse_query()%% and return the array instead of using the out parameter. The new function will take only one argument.

The new function will also be maintained in the manual under https://www.php.net/manual/en/ref.url.php instead of https://www.php.net/manual/en/ref.strings.php

<PHP>
$str = "first=value&arr[]=foo+bar&arr[]=baz";

$output = http_parse_query($str);
echo $output['first'];  // value
echo $output['arr'][0]; // foo bar
echo $output['arr'][1]; // baz
</PHP>


===== Open Points =====

==== Should PHP remove name mangling? ====

As suggested on the mailing list, the name mangling does not serve any purpose anymore. It was a way to simplify variable access when register globals was used. Since PHP 8.0, this functionality is not available anymore, so the question is should we remove the name mangling from PHP parse functions completely (which would require a separate RFC and smart deprecation path) or should we remove it only from the new function?

If we should remove name mangling, what should happen to mismatched square brackets? 

==== Should it be implemented in OOP way instead? ====

Maybe the replacement should be in a form of a full-fledged class with properties from two-way conversion from string to PHP array/object. What would such API look like? What functionality is missing currently from PHP? Do we need such API in core or can we just expose a function like %%http_parse_query()%% and let the rest be implemented in userland?

===== Future Scope =====

The %%parse_str()%% function will get deprecated in the next minor release and removed in the next major release. 

===== Backward Incompatible Changes =====

There will be no breaking change to existing functionality. The new function is designed to give users a way to move away from %%parse_str()%% so that we can deprecate it and remove it. 

===== Vote =====

Simple yes/no vote.


<doodle title="Add new http_parse_query() function?" auth="dharman" voteType="single" closed="true"> 
   * Yes
   * No
</doodle>

===== Discussion on internals ======
https://externals.io/message/115546