Currently Available: Need a skilled Software Developer for your next project?
Categories
Laravel

Building Query Strings with the Laravel HTTP Client

When PHP code sends a request to an API, the URL often needs values for search terms, filters, or pagination. A query string is the part of a URL after ?, such as ?page=2. Laravel’s HTTP client lets you pass those values as an array, so you can keep the endpoint readable and avoid assembling the URL by hand.

For a GET request, pass the query array as the second argument to Http::get(). Use withQueryParameters() to set query values in a fluent request chain; Laravel’s HTTP Client documentation covers both approaches.

Pass query parameters to a GET request

Pass an associative array of query keys and values to Http::get():

use Illuminate\Support\Facades\Http;

$query = [
    'search' => 'Laravel HTTP client',
    'page' => 2,
    'per_page' => 20,
];

$response = Http::get('https://api.example.test/articles', $query);

The URL identifies the endpoint, and the array holds the values that change between requests. Laravel’s HTTP client turns the array into a query string, adding ? before the first value and & before each additional one.

By comparison, manually concatenating the URL makes your code responsible for joining and formatting each value:

$url = 'https://api.example.test/articles'
    . '?search=' . urlencode($search)
    . '&page=' . $page;

$response = Http::get($url);

The array form groups the parameters and avoids manually building the query string. The underlying Guzzle client documents array-based query serialization through its query request option. The API you call still determines which parameter names and value formats it accepts.

Set query values in a fluent request chain

Use withQueryParameters() when you want to configure the query separately from the HTTP method call:

$response = Http::withQueryParameters([
    'search' => 'Laravel HTTP client',
    'page' => 2,
])
    ->get('https://api.example.test/articles');

Use this form when you want query settings alongside headers, authentication, or retry behavior. Choose it when keeping request configuration together makes the code easier to read; use the second argument to get() when the query array only needs to accompany that GET call.

Keep each key in either the URL or the query array, rather than defining it in both. Guzzle 7.0 documents that values supplied through its query option overwrite matching values in the URI, but check behavior against the versions installed in your project if you rely on that detail. See the Guzzle 7.0 request options.

Keep path values separate from query values

A path parameter sits inside the URL path, such as the 42 in /users/42. A query parameter follows ?, such as ?page=2. Laravel provides withUrlParameters() for filling placeholders in a URL path; use withQueryParameters() or the GET argument for query values. Laravel documents these as separate URL-building methods in its HTTP Client documentation.

For example, a request to a user-specific endpoint can put the identifier in the path and pagination in the query string:

$response = Http::withUrlParameters([
    'endpoint' => 'https://api.example.test',
    'user' => 42,
])
    ->withQueryParameters(['page' => 2])
    ->get('{+endpoint}/users/{user}');

Keep POST query data out of the request body

For Http::post(), the second argument supplies request data, which Laravel sends as JSON by default. If a POST request needs both query parameters and a body, set the query with withQueryParameters() and pass the body to post():

$response = Http::withQueryParameters([
    'notify' => false,
])->post('https://api.example.test/articles', [
    'title' => 'A new article',
]);

The query values go in the URL, while the article data goes in the request body. Check the API’s requirements for values such as booleans, empty values, or arrays, since an API can prescribe a particular representation.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com

Email updates

Usually a new article and a few links I found interesting.

No spam. Unsubscribe with one click.

Leave a Reply

Your email address will not be published. Required fields are marked *