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
- Use associative arrays for query parameters to ensure proper key-value pairing
- Let Guzzle handle encoding - don't manually URL-encode your parameter values
- Combine with other options like headers, timeouts, and authentication as needed
- 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.