Definition and Usage
The parse_str()
function is used to decode a URL-encoded query string and parse it into variables.
Instead of returning a value, this function stores the parsed data as an array in the second argument passed to it.
It's typically used to decode query strings encoded by the http_build_query()
function and parse them into variables.
http_build_query()
generates a URL-encoded query string from an array or object.
Basic Example
// An array to be encoded into a URL-encoded query string
$data = array(
'name' => 'John Doe',
'age' => 30,
'city' => 'New York'
);
// Encode the array into a query string using http_build_query()
$queryString = http_build_query($data);
echo $queryString; // Output: name=John+Doe&age=30&city=New+York'
// Decode the query string using parse_str()
// Store the parsed data as an array in the second argument, $decodedArray
parse_str($queryString, $decodedArray);
print_r($decodedArray); // Output: Array ( [name] => John Doe [age] => 30 [city] => New York )
The parse_str()
function is used to decode a URL-encoded query string and parse it into variables. It is typically used to decode URL queries encoded by the http_build_query()
function. While http_build_query()
primarily converts arrays into URL query strings, parse_str()
performs the reverse operation by decoding those strings.
The parse_str()
function converts a URL-encoded query string generated by http_build_query()
into key-value pairs and assigns them to an array or variables.
Therefore, parse_str()
and http_build_query()
can be considered complementary functions performing opposite roles.
Syntax
parse_str(string $string, array &$result): void
Parameters
$string |
The URL-encoded string to decode. |
---|---|
&$result |
If provided, this parameter will store the decoded key-value pairs as an array. Passed by reference. |
Return Values
This function does not return a value.
Changelog
Using parse_str()
without the second parameter has been discouraged since PHP 7.2 due to potential security risks. Malicious code injected into URL-encoded query strings could be executed.
Furthermore, starting from PHP 8.0.0, the &$result
parameter is mandatory. Therefore, you must provide the second parameter when using this function.
Warning!
Using this function without the second parameter is highly discouraged. Since PHP 7.2, it triggers an E_DEPRECATED
notice, and from PHP 8.0.0 onward, the second parameter &$result
is required.
Version | Description |
---|---|
8.0.0 | The &$result parameter is no longer optional and is required. |
7.2.0 | Using parse_str() without the second parameter triggers an E_DEPRECATED notice. |
Recommended and Discouraged Usage
The parse_str()
function is used to parse a URL query string (e.g., name=John+Doe&age=30
) into PHP variables. However, how you use this function determines whether the usage is recommended or discouraged. For safe and predictable code, following the recommended approach is essential.
Discouraged Usage: Omitting the Second Argument
This approach involves calling parse_str()
with only the query string, omitting the second argument.
$query_string = 'name=John+Doe&age=30';
// Discouraged: Omitting the array to store the result
parse_str($query_string);
// Variables $name and $age are created directly in the current scope
echo 'Name (Discouraged): ' . $name . '<br>'; // Output: 'Name (Discouraged): John Doe'
echo 'Age (Discouraged): ' . $age; // Output: 'Age (Discouraged): 30'
Why is this discouraged?
- It is difficult for someone reading the code to immediately know which variables have been created by
parse_str()
. - If variables like
$name
already exist, they could be unintentionally overwritten by the variables created byparse_str()
. - ince PHP 7.2.0, using
parse_str()
this way triggers anE_DEPRECATED
warning. - From PHP 8.0.0 onward, this usage causes an error because the second
&$result
parameter is required.
Recommended Usage: Providing an Array as the Second Argument
This approach passes both the query string and an array variable to store the parsed result as the second argument.
$query_string = 'name=John+Doe&age=30';
// Recommended: Store the result in the $parsed_data array
$parsed_data = []; // It's best to declare the array beforehand
parse_str($query_string, $parsed_data);
// The parsed data is now inside the $parsed_data array
$name = $parsed_data['name'];
$age = $parsed_data['age'];
echo 'Name (Recommended): ' . $name . '<br>'; // Output: 'Name (Recommended): John Doe'
echo 'Age (Recommended): ' . $age; // Output: 'Age (Recommended): 30'
Why is this recommended?
- All parsed results are encapsulated within a specified array, preventing external input from creating or overwriting variables elsewhere in the code.
- When reading the code, it is immediately clear that
parse_str()
stores results in the$parsed_data
array, making the code flow easier to understand. - This approach avoids variable name conflicts and provides a consistent way to access data, simplifying maintenance.
- It is the only correct and supported usage from PHP 8.0.0 onwards.
References
See also
- PHP URL Encoding Functions
- PHP urlencode() Function – Encoding a URL Query Parameter Value
- PHP rawurlencode() Function – Safely Encoding URI Components
- PHP http_build_query() Function – Generate URL-Encoded Query Strings from Arrays or Objects
- PHP URL Decoding Functions
- PHP urldecode() Function – Decoding URLs Encoded with urlencode()
- PHP rawurldecode() Function – Decoding URLs Encoded with rawurlencode()