http_build_query() without url encoding

http_build_query() without url encoding

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Bypassing URL Encoding in http_build_query() for Legacy APIs

The PHP built-in function http_build_query() is designed to be the standard solution for constructing query strings. It adheres strictly to RFC 3986, automatically escaping special characters like spaces, parentheses, and brackets into their percent-encoded equivalents (%20, %28, %29). While this compliance is essential for modern web standards where browsers and servers expect strict adherence, it creates a specific friction point when interfacing with older or rigid third-party APIs.

The Ebay API is a prime example of this constraint. Certain endpoints require parameter names to remain unencoded, even if they contain characters that http_build_query() would normally sanitize. A common scenario involves parameters like DomainName(0). If you pass this string directly into http_build_query(), the function converts it to DomainName%280%29. When sent to the API, this causes a failure because the server parses the percent-encoded characters as part of the URL structure rather than literal text within the parameter name.

The Core Limitation

There is no flag or option within http_build_query() to disable encoding for specific keys while leaving values encoded. The function operates as an all-or-nothing process regarding character escaping based on the current locale settings and RFC standards. Attempting to work around this by manually reconstructing the string after calling the function defeats the purpose of using a helper function in the first place, introducing the risk of typos or inconsistent logic.

A Practical Workaround: Manual Construction

To solve this without violating API requirements, you must bypass http_build_query() for the specific problematic parameters and handle the query string construction manually. This approach involves splitting the task: encoding standard values while leaving raw parameter names intact.

Here is a pattern that works effectively in this scenario:

$params = [
    'DomainName(0)' => 'mydomain',
    'StandardKey' => 'value with spaces'
];

$parts = [];

foreach ($params as $key => $value) {
    // Check if the key contains characters that would be encoded
    // but are required to be raw for the API.
    if (preg_match('/[()]/', $key)) {
        // Keep the key raw, encode only the value if necessary
        // Note: The value usually still needs encoding unless specified otherwise by the API
        $encodedKey = $key; 
        $encodedValue = rawurlencode($value);
    } else {
        // Standard behavior for safe keys
        $encodedKey = urlencode($key);
        $encodedValue = rawurlencode($value);
    }

    $parts[] = $encodedKey . '=' . $encodedValue;
}

$query_string = implode('&', $parts);

Leveraging http_build_query with Custom Options

In PHP 5.3 and later, http_build_query() accepts an optional third argument that defines the encoding style. However, this still defaults to full encoding of keys when using the standard 'PHP' or default behavior. If you are on a newer version of PHP (7.4+), you might consider using urlencode() directly for the keys in question, but http_build_query() itself remains rigid about key encoding unless you bypass it entirely.

A more robust approach for complex scenarios involving mixed requirements is to use http_build_query exclusively for the values and manually construct the key-value pairs. You can iterate through your data array, checking if the key matches a specific pattern that requires raw output.

Handling the Value Encoding Trade-off

It is important to distinguish between encoding keys and encoding values. In the Ebay API example provided, the parameter name DomainName(0) must remain literal. However, the value associated with it (e.g., 'mydomain') typically still requires URL encoding if it contains spaces or ampersands. The manual loop above demonstrates this distinction: $encodedKey is set to the raw $key, while $encodedValue undergoes rawurlencode().

Using urlencode() instead of rawurlencode() for values ensures that special characters like & and = within the payload are safely escaped. If you use rawurlencode() on both keys and values, you lose the ability to encode delimiters in the key, which is often necessary for API parameters containing non-alphanumeric characters.

Why Not Just Pass a String?

You might consider bypassing arrays entirely and constructing the string manually:
"$key=$value"
This is less maintainable. If your API requirements change or if you need to handle nested structures, an array-based approach combined with conditional logic offers better separation of concerns. The manual loop ensures that only the specific characters mandated by the API contract are preserved, while all other safety mechanisms (like preventing SQL injection in values or breaking out of query strings) remain active through standard encoding functions.

Conclusion on Implementation

When dealing with APIs that deviate from modern URL standards, relying solely on helper functions like http_build_query() is risky. The most reliable solution is to identify the specific parameters requiring raw names and handle them outside the automated encoding loop. This hybrid approach maintains code readability while respecting the strict parsing rules of legacy systems like the Ebay API.

Our network