Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Reading a JSON request body in PHP returns nothing

Errorjson_decode(file_get_contents('php://input')) returns NULL

Short answer

A JSON body is not form data, so PHP never puts it in $_POST. Read the raw body with file_get_contents('php://input') and decode it yourself. If json_decode then gives null, the body is empty or is not valid JSON; decode with JSON_THROW_ON_ERROR to get the exact reason.

  • Applies to PHP 8.3, PHP 8.4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Dump the raw body and the decode error together. This shows whether the body is empty or invalid.

    $raw = file_get_contents('php://input');
    var_dump($raw);
    json_decode($raw);
    var_dump(json_last_error_msg());
  2. 2Match what you see, then jump to its fix

    1. 1$_POST is an empty array while the client sends JSONThe body is read from $_POST instead of php://inputFix
    2. 2json_last_error_msg() says Syntax errorThe JSON itself is invalidFix
    3. 3php://input is empty although the request has a body, and the client uses a file or multipart formThe body is sent as multipart form dataFix

What does the error look like?

  • json_decode(file_get_contents('php://input')) returns NULL
  • JsonException: Syntax error

Cause 1 of 3

The body is read from $_POST instead of php://input

1Check

php://input is the read-only stream of the raw request body, and PHP's request parsing does not turn a JSON body into $_POST.

curl -s -X POST -H 'Content-Type: application/json' -d '{"a":1}' http://localhost:8000/api.php

2Fix

Read the stream and decode it, asking for an exception on bad input.

$raw = file_get_contents('php://input');
$data = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);

3Verify

The decoded array holds the fields you sent.

curl -s -X POST -H 'Content-Type: application/json' -d '{"a":1}' http://localhost:8000/api.php

Confirmed by php.net

Did this fix it?

Cause 2 of 3

The JSON itself is invalid

1Check

json_decode returns null for undecodable input, and null is also a valid result for the JSON text null, so check the error code. Only double-quoted names and strings are valid, and trailing commas are not allowed.

var_dump(json_last_error() === JSON_ERROR_NONE);

2Fix

Fix the sender so it uses double quotes and no trailing commas, and make the server catch JsonException and return 400.

try {
    $data = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    http_response_code(400);
    exit('Invalid JSON');
}

3Verify

A bad body returns 400, a good one is decoded.

curl -si -X POST -d '{bad}' http://localhost:8000/api.php | head -1

Confirmed by php.net

Did this fix it?

Cause 3 of 3

The body is sent as multipart form data

1Check

The manual says php://input is not available for multipart/form-data requests when enable_post_data_reading is on. In that case the fields arrive in $_POST and $_FILES.

php -r 'echo ini_get("enable_post_data_reading");'

2Fix

Read $_POST and $_FILES for multipart requests, or make the client send application/json.

var_dump($_POST, $_FILES);

3Verify

The fields now appear.

curl -s -F 'a=1' http://localhost:8000/api.php

Confirmed by php.net

Did this fix it?

How do I stop it coming back?

  • Decide per endpoint whether it takes JSON or a form, and document the Content-Type it expects.
  • Always decode with JSON_THROW_ON_ERROR and answer 400 on failure.
  • Log the raw body length when debugging so an empty body is obvious.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

Apache returns 403 when a URL contains %3F

a request like /page%3Fname=test is refused while /page?name=test works

Recent Apache httpd blocks a rewrite when the request contains an encoded question mark (%3F) and the rewritten target has a literal ?.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.