How to Use http_build_query in PHP

The http_build_query() function in PHP is a built-in tool used to generate URL-encoded query strings from associative or indexed arrays, as well as objects. This article explains how the function works, explores its syntax and parameters, and demonstrates how it handles nested data structures and custom separators to create clean, URL-safe strings.

Basic Syntax and Operation

The basic syntax of the function is:

http_build_query(
    array|object $data,
    string $numeric_prefix = "",
    ?string $arg_separator = null,
    int $encoding_type = PHP_QUERY_RFC1738
): string

At its simplest, http_build_query() takes an associative array of key-value pairs and joins them with equal signs (=) and ampersands (&). It automatically URL-encodes both the keys and the values to ensure they are safe for HTTP requests.

$data = [
    'search' => 'php development',
    'page' => 2,
    'status' => 'active'
];

echo http_build_query($data);
// Output: search=php+development&page=2&status=active

As shown in the output, the space in “php development” is automatically encoded as + (or %20 depending on the encoding type).

Handling Numeric Keys with Numeric Prefixes

If you pass an indexed array (with numeric keys) to the function, the resulting query string would normally contain invalid variable names (e.g., 0=value1&1=value2). To prevent this, you can use the second parameter, $numeric_prefix.

$data = ['apple', 'banana', 'cherry'];

echo http_build_query($data, 'item_');
// Output: item_0=apple&item_1=banana&item_2=cherry

The specified prefix is prepended to each numeric index, making the query string valid and easier to parse on the receiving end.

Managing Nested Arrays

http_build_query() natively handles multi-dimensional (nested) arrays. It converts nested arrays into query strings using URL-encoded bracket notation.

$data = [
    'user' => [
        'name' => 'Jane Doe',
        'roles' => ['admin', 'editor']
    ]
];

echo http_build_query($data);
// Output: user%5Bname%5D=Jane+Doe&user%5Broles%5D%5B0%5D=admin&user%5Broles%5D%5B1%5D=editor

Decoded, this string represents: user[name]=Jane Doe&user[roles][0]=admin&user[roles][1]=editor.

Customizing the Argument Separator

By default, PHP uses the ampersand (&) as the separator. However, if you need to output HTML-compliant URLs (where & must be written as &), you can define a custom separator using the third parameter.

$data = ['id' => 101, 'action' => 'edit'];

echo http_build_query($data, '', '&amp;');
// Output: id=101&amp;action=edit

Specifying Encoding Types

The fourth parameter, $encoding_type, determines how spaces and special characters are encoded. It accepts two PHP constants:

PHP_QUERY_RFC1738 (Default): Encodes spaces as plus signs (+).
PHP_QUERY_RFC3986: Encodes spaces as %20按照 standard percent-encoding.

$data = ['query' => 'hello world'];

echo http_build_query($data, '', '&', PHP_QUERY_RFC3986);
// Output: query=hello%20world

Working with Objects

When passed an object, http_build_query() only extracts and encodes the public properties of that object. Private and protected properties are ignored.

class User {
    public $name = 'Alice';
    public $email = 'alice@example.com';
    protected $password = 'secret';
}

$user = new User();
echo http_build_query($user);
// Output: name=Alice&email=alice%40example.com