How do I add query parameters to a request in Guzzle?

Overview

In Guzzle, an HTTP client for PHP, you can add query parameters to any request by including them in the request options array with the key query. Guzzle will automatically URL-encode and append the query parameters to the URI.

Basic GET Request with Query Parameters

Here's how to add query parameters to a GET request:

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

// Define query parameters
$queryParams = [
    'search' => 'web scraping',
    'limit' => 10,
    'sort' => 'date'
];

// Send GET request with query parameters
$response = $client->request('GET', 'https://api.example.com/search', [
    'query' => $queryParams
]);

// This will request: https://api.example.com/search?search=web+scraping&limit=10&sort=date

echo $response->getBody()->getContents();

POST Request with Both Form Data and Query Parameters

You can combine query parameters with form data in POST requests:

<?php
use GuzzleHttp\Client;

$client = new Client();

// Form data (sent in request body)
$formData = [
    'username' => 'john_doe',
    'password' => 'secret123'
];

// Query parameters (appended to URL)
$queryParams = [
    'redirect' => '/dashboard',
    'remember' => 'true'
];

$response = $client->request('POST', 'https://api.example.com/login', [
    'form_params' => $formData,  // Sent as application/x-www-form-urlencoded
    'query' => $queryParams      // Appended to URL
]);

// This will POST to: https://api.example.com/login?redirect=%2Fdashboard&remember=true

Working with Arrays and Special Characters

Query parameters can contain arrays and special characters, which Guzzle handles automatically:

<?php
use GuzzleHttp\Client;

$client = new Client();

$queryParams = [
    'tags' => ['php', 'web-scraping', 'guzzle'],  // Array values
    'q' => 'search term with spaces',             // Spaces
    'filter[status]' => 'active',                 // Brackets
    'email' => 'user@example.com'                 // Special characters
];

$response = $client->request('GET', 'https://api.example.com/data', [
    'query' => $queryParams
]);

// Results in: ?tags[0]=php&tags[1]=web-scraping&tags[2]=guzzle&q=search+term+with+spaces&filter[status]=active&email=user%40example.com

Merging with Existing Query Parameters

If your base URL already contains query parameters, Guzzle will merge them with your additional parameters:

<?php
use GuzzleHttp\Client;

$client = new Client();

// Base URL already has parameters
$baseUrl = 'https://api.example.com/search?existing=value';

$additionalParams = [
    'new_param' => 'new_value',
    'another' => 'parameter'
];

$response = $client->request('GET', $baseUrl, [
    'query' => $additionalParams
]);

// Final URL: https://api.example.com/search?existing=value&new_param=new_value&another=parameter

Using Query Parameters with Different HTTP Methods

Query parameters work with all HTTP methods:

<?php
use GuzzleHttp\Client;

$client = new Client();
$params = ['api_key' => 'your_key', 'format' => 'json'];

// GET request
$response = $client->get('https://api.example.com/data', ['query' => $params]);

// POST request  
$response = $client->post('https://api.example.com/create', ['query' => $params]);

// PUT request
$response = $client->put('https://api.example.com/update', ['query' => $params]);

// DELETE request
$response = $client->delete('https://api.example.com/delete', ['query' => $params]);

Best Practices

1. Use associative arrays for query parameters to ensure proper key-value pairing
2. Let Guzzle handle encoding - don't manually URL-encode your parameter values
3. Combine with other options like headers, timeouts, and authentication as needed
4. Validate sensitive parameters before including them in URLs (they're visible in logs)

<?php
use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('GET', 'https://api.example.com/secure', [
    'query' => [
        'public_param' => 'safe_value'
    ],
    'headers' => [
        'Authorization' => 'Bearer ' . $token,  // Keep sensitive data in headers
        'Accept' => 'application/json'
    ],
    'timeout' => 30
]);

Query parameters are automatically URL-encoded and merged with any existing parameters in the URL, making them perfect for API integrations, search functionality, and filtering operations.