Separating Public and Internal Documentation for Laravel Packages
Laravel package maintainers write for two main audiences: developers who install and use the package, and people who work on its code…
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 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.
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.
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}');
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.
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