Adding Query string params to a Guzzle GET request?

Adding Query string params to a Guzzle GET request?

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

Stefan Bogdanescu

Founder & Senior Architect

Handling Query Strings in Guzzle: Arrays, ArraysExplode, and Debugging

When you pass a query string as a single string to GuzzleHttp, it treats the entire value as one literal parameter. Your first example works because $request receives the full URL with the query parameters already embedded in the string. The second approach fails because Guzzle interprets the array passed to the query option as a map of key-value pairs, not as a raw string to be appended verbatim. If your configuration stores switch flags like -db and -lay as an array where values might be boolean or null, passing that directly often results in empty parameters or malformed output because Guzzle expects specific data structures for different query needs.

To construct a complex query string programmatically—especially when dealing with command-line style flags like -key=value—you need to ensure the data is shaped correctly before Guzzle serializes it. If your $config->Layout['switches'] contains an array of strings like ['-db' => 'database', '-lay' => 'layout'], you can pass this directly to the query option. However, if you want to treat these flags as a raw string that must not be re-interpreted, or if you need dynamic parameters based on runtime conditions, using an array of arrays is often the most robust method.

Consider a scenario where you have mixed data: some parameters are simple values, while others are complex strings containing spaces or special characters. Guzzle's default behavior is to URL-encode these automatically, which is usually what you want. However, if you need to preserve specific formatting or handle cases where the value itself is already an encoded string, you might need to use GuzzleHttp\Psr7\Uri for manual construction. This involves creating a new URI object, appending the query string manually, and then retrieving it.

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\Uri;

$client = new Client();
$baseUrl = 'http://192.168.50.8/foo';

// Method 1: Passing an associative array (Recommended for standard use)
$queryParams = [
    '-db' => 'database',
    '-lay' => 'layout',
    '-find' => true, // Guzzle handles booleans by converting to string "1" or omitting if false
];

$request = $client->get($baseUrl, [], ['query' => $queryParams]);
// To see the actual URL being sent:
echo (string) $request->getUri(); 

In this snippet, we pass an associative array directly. Guzzle will serialize this into a standard query string where true becomes 1. If your requirement is to send -find without a value or with a specific flag representation, you must adjust the data structure accordingly. For instance, if you need -find to be present but empty, pass an empty string. If you need it absent entirely when false, do not include the key at all.

If your configuration object provides raw strings that are meant to be appended exactly as written without further interpretation by Guzzle's serializer, you must construct the URI manually. This is useful when dealing with legacy APIs or specific CLI tools that expect exact string matching. You can use Uri::withQuery to append a custom query string while maintaining the base URI's scheme and host.

$customQuery = '-db=database&-lay=layout&-find';
$request = $client->get($baseUrl, [], [
    'query' => ['_q' => $customQuery] // This wraps it in a single parameter
]);
// Or manually constructing the URI if you need full control:
$uri = Uri::withQuery($baseUrl, '-db=database&-lay=layout&-find');
$request = $client->get((string) $uri);

Debugging these requests is straightforward once you understand what Guzzle outputs. The getBody() method of the response only contains the server's response body, not the request URL. To inspect the actual URL Guzzle constructed, cast the URI object to a string: (string) $request->getUri(). This reveals exactly how Guzzle has serialized your parameters, including any encoding applied to special characters.

The decision between passing an array of key-value pairs versus a raw string depends on your API's expectations. Most modern REST APIs expect standard query strings where keys are distinct and values are encoded. Command-line interface simulations often require exact string matching. By understanding how Guzzle serializes arrays into query strings, you can avoid common pitfalls like sending double-encoded parameters or missing required flags due to boolean value handling.

Our network