Illuminate\Support\Facades\Http request body defaults to empty array [] (footgun)

[bcheidemann-kmbal]

Laravel Version

11.18.1

PHP Version

8.3.9

Database Driver & Version

n/a

Description

If no request body is specified when using the Illuminate\Support\Facades\Http post, patch, put, or delete methods, it defaults to an empty array, which is JSON encoded as []. This is unintuitive, and can lead to unexpected behaviour or bugs.

Example of Resulting Bug

Assume a REST API exists which is authenticated via a HMAC authentication header. Such an API may choose to hash either the request body and/or the request path if the request body is empty. A client calling this API with an empty body should only hash the request path. If the client is a Laravel application, the implementor may (as I did) assume that the default body is empty, and accidentally call the API with a non-empty body. This will result in the API and Laravel client application computing different hashes for the same request.

Workarounds

Http::post("http://0.0.0.0:4242/", data: null);
//                                 ^ This works but causes a ;int error because $data is not nullable (why?)
Http::withBody('')->post("http://0.0.0.0:4242/");
//             ^ This works but is a little inelegant

Proposed Fix

By default, the request body should be empty. The $data argument should also be made nullable.

Steps To Reproduce

Open two shell sessions.

In the first shell, run:

$ deno eval 'Deno.serve({ port: 4242 }, async (req) => { console.log(`"${await req.text()}"`); return new Response("ok"); });'
Listening on http://0.0.0.0:4242/

In the second shell, cd into a Laravel project and run:

$ php artisan tinker
Psy Shell v0.12.4 (PHP 8.3.9 — cli) by Justin Hileman
> Http::post("http://0.0.0.0:4242/");
= Illuminate\Http\Client\Response {#6304
    +cookies: GuzzleHttp\Cookie\CookieJar {#6321},
    +transferStats: GuzzleHttp\TransferStats {#6342},
  }

>  

Observe that in the first shell "[]" gets logged.

[ev-gor]

The absence of any body in a POST request that is really unintuitive. An empty array as a request body clearly indicates that you intentionally send no data to the server. For some rare cases where no body is preferable, you've offered the workaround

[bcheidemann-kmbal]

This certainly isn't a hill I would die on, but I'll lay out the arguments why I disagree with the above and see if I can convince you 😁

1. It's important to consider the intent of the API user when judging what would be intuitive to them

The absence of any body in a POST request that is really unintuitive.

I'm assuming you mean that it's unintuitive to you why a POST request would have no associated data. I think that's reasonable, and I'd be inclined to agree. However, to someone trying to make a POST request with no data, it is (in my personal experience) very unintuitive that an arbitrary default body would be sent.

2. An empty JSON array is the wrong choice to represent no data (it should be null)

An empty array as a request body clearly indicates that you intentionally send no data to the server.

To a human being, possibly. But in most cases there's no human beings interpreting the request payload. What constitutes intentionally sending no data depends entirely on the implementation and specification of the API you're trying to call. There's also many possible choices for signalling no data e.g. 0, false, {}, [], "". Arguably the only sane default, if not sending literally no data, would be to send null. In a JSON payload, null is the only value which actually means no data. At the risk of belabouring the point, an empty JSON array is quite an unusual way to signal no data, since it is typically used to represent an empty list.

3. The HTTP specification doesn't say that a POST request needs to have a body

As far as I can tell, there's nothing in RFC 2616 (Hypertext Transfer Protocol -- HTTP/1.1), RFC 7231 (https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.3), RFC 9113 (https://datatracker.ietf.org/doc/html/rfc9113), or any other relevant RFC/specification which says a POST request needs to have a body. Of course, as you rightly point out, sending a POST request without a body is unusual. But unless I'm mistaken it is completely valid.

4. The default body should be whatever is least likely to cause bugs and/or makes them easier to fix

There's two main scenarios where this comes into play. Firstly, someone accidentally doesn't specify a request body. Secondly, someone intends to send no request body but accidentally sends an empty array.

In the first scenario, defaulting to an empty array is very unlikely to fix their mistake and avoid any bugs. It's also likely they will receive unexpected validation errors; receiving the error "expected JSON object but received no data" is more helpful for debugging than "expected JSON object but received JSON array". Sending null would be better here since it would also clearly signal no data was sent in the body.

In the second scenario, defaulting to an empty array may introduce a bug. When trying to fix the bug, it's somewhat unclear where the empty array is coming from, since no body is specified when making the request. You need to actually check the Laravel framework code to find where it's coming from.

5. It's inconsistent with other methods like DELETE

The method signature for delete and post are the same:

public function delete(string $url, $data = []): Response
public function post(string $url, $data = []): Response

When I call delete($url) it sends no data in the body, but when I call post($url) it sends and empty JSON array in the body.

[shaedrich]

2. An empty JSON array is the wrong choice to represent no data (it should be null)
5. It's inconsistent with other methods like DELETE

The method signature for delete and post are the same:

public function delete(string $url, $data = []): Response
public function post(string $url, $data = []): Response

When I call delete($url) it sends no data in the body, but when I call post($url) it sends and empty JSON array in the body.

Ironically, shouldn't the method signatures then be:

public function delete(string $url, $data = null): Response
public function post(string $url, $data = null): Response

[bcheidemann-kmbal]

Based on the current implementation of post (where $data = null results in no body being sent) that would be preferable over $data = [].