Why $_POST Returns Empty for Raw JSON Payloads
When a client submits data via an HTTP POST request, the server expects to find it in $_POST. However, if you inspect $_POST and see an empty array while the raw request body contains valid JSON like {a:1}, the issue isn't with your PHP syntax or the JSON itself. It is a fundamental misunderstanding of how the HTTP protocol distinguishes between different types of payload data.
The core problem lies in the Content-Type header sent by the client. When you submit raw JSON directly to a PHP script without explicitly setting the content type, browsers and many tools default to sending it as application/x-www-form-urlencoded or multipart/form-data. These are the formats designed for HTML forms where data is key-value pairs separated by ampersands.
In these scenarios, PHP automatically parses the body and populates the $_POST superglobal with keys matching your form fields. However, when the actual content is a single JSON object wrapped in braces, the server needs to know it's receiving an encoded string, not form variables. If the header is missing or incorrect, PHP treats the raw body as a large file upload or ignores it entirely for $_POST, resulting in that empty array you are seeing.
To extract values from a JSON payload in PHP, you must explicitly inform the client to send the data with the Content-Type: application/json header. Once your client (whether a browser, API tool, or another service) sends this header, PHP's php://input stream becomes the correct mechanism for retrieval.
You can read the raw input stream using file_get_contents('php://input'). This function reads the entire body of the request as a string without attempting any automatic parsing. You then need to manually decode this string into an associative array using json_decode().
Here is how that looks in practice:
$jsonInput = file_get_contents('php://input');
$data = json_decode($jsonInput, true);
if (json_last_error() === JSON_ERROR_NONE) {
// Access the value safely
$value = $data['a'];
} else {
// Handle parsing errors
throw new InvalidArgumentException('Invalid JSON payload');
}
Using php://input is critical here. Unlike $_POST, which relies on the server's automatic parsing of specific content types, php://input gives you unfiltered access to whatever the client sent. This approach works regardless of whether the data is a simple string or a complex nested object, provided the JSON structure is valid.
A common pitfall involves the second argument passed to json_decode. Passing true converts the resulting object into an associative array, which allows you to access properties using standard bracket notation like $data['a']. If you omit this flag, PHP returns a stdClass object, requiring you to use property accessors like $data->a. While functionally similar for simple structures, the array format is generally safer when dealing with dynamic keys or JSON objects containing numeric strings.
Another consideration is handling malformed JSON. The json_decode() function does not throw exceptions by default; instead, it returns null if parsing fails. You should always check json_last_error() to determine if the decode succeeded before attempting to access data properties. Accessing an undefined index on a null result will trigger a notice and potentially expose sensitive stack traces in production environments.
If you are building an API or integrating with existing services that send JSON, switching your codebase to handle raw input streams is often more robust than relying on $_POST. This pattern decouples your application logic from the specific quirks of form submission standards. For projects built on the Laravel framework, this same principle applies; reading from request()->input('key') or accessing $request->json() internally handles these stream mechanics to provide a consistent interface for developers.