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

PHP 
// 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

PHP 
parse_str(string $string, array &$result): void

Parameters

Description of the parse_str() Function 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 History for parse_str() Function
VersionDescription
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.

PHP 
$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 by parse_str().
  • ince PHP 7.2.0, using parse_str() this way triggers an E_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.

PHP 
$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