Sending JSON vs. Form Parameters in Laravel’s HTTP Client

When PHP code uses Laravel’s HTTP client to send data to an API, the API server needs to know how the request body is formatted. JSON stores data in a structured format. URL-encoded form data stores it as named fields. Laravel accepts a PHP array in either case. The method you call determines how Laravel formats the body and labels it.

Laravel sends array data as JSON by default in POST, PUT, and PATCH requests. Call Http::asForm() when the API expects URL-encoded fields. Use the format the endpoint documents so the server can read the values as intended.

How Laravel serializes the same array

With a regular post() call, Laravel sends the array as JSON:

use Illuminate\Support\Facades\Http;

$response = Http::post('https://api.example.test/users', [
    'name' => 'Sara',
    'role' => 'Consultant',
]);

The body is:

{"name":"Sara","role":"Consultant"}

Laravel sets the request’s Content-Type to application/json, which tells the server to read the body as JSON. The Laravel HTTP Client documentation says Laravel uses JSON by default when you pass an array to POST, PUT, or PATCH requests. Call Http::asJson() before sending the request to make that choice explicit.

To send the same values as URL-encoded form parameters, call asForm():

$response = Http::asForm()->post('https://api.example.test/users', [
    'name' => 'Sara',
    'role' => 'Consultant',
]);

For these simple string values, the body is:

name=Sara&role=Consultant

Laravel sets Content-Type to application/x-www-form-urlencoded. Laravel’s request implementation uses Guzzle’s form-parameter option when you call asForm(), and its JSON option when you call asJson(). Guzzle’s request options explain how each option encodes the body.

The PHP array looks the same in both examples, but Laravel sends different bytes in the request body and sets a different Content-Type header. Form data uses name/value pairs. Characters with a special meaning in a URL-encoded body are percent-encoded. JSON keeps a structured format, including the value types PHP can encode as JSON. Form fields generally represent strings or arrays of strings. For nested or repeated fields, use the encoding documented by the API because conventions vary.

Choose the format the endpoint expects

Use the format named in the API’s request specification. Send JSON when it documents a JSON request body. Call Http::asForm() when it asks for application/x-www-form-urlencoded. The endpoint cannot read the fields as intended if you send the right values in the wrong format.

Content-Type describes the body Laravel sends. Accept tells the server which response format the client wants. For example, Http::acceptJson() requests a JSON response, but it does not switch the request body to JSON.

Query parameters appear in the URL, while JSON and URL-encoded form data go in the request body. Multipart form data is another format, commonly used for file uploads. Laravel provides attach() to send files.

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