Decoding JSON Payloads in PHP: Why $_POST Looks Empty
When a payment interface sends data to your server, you expect the payload to appear inside the $_POST superglobal array. If you echo that variable and see only Array, while the sender's logs confirm the request was successful, the mismatch usually points to a fundamental misunderstanding of how HTTP forms interact with JSON.
The issue isn't that the data is missing; it's that the data isn't being sent in the format PHP's default form handler expects. When you send an HTML form submission, the browser automatically sets the Content-Type header to application/x-www-form-urlencoded. PHP's input streams are designed to parse this specific structure. However, if a third-party system or API sends JSON, they set the Content-Type header to application/json.
When PHP encounters a request with a Content-Type of application/json, it does not automatically populate $_POST. Instead, it populates php://input. Attempting to access $_POST in this scenario will result in an empty array because the raw input stream hasn't been parsed into name-value pairs. The data exists on the server, but you are looking at the wrong variable.
To fix this, you must read the raw body of the request. You can do this using the file_get_contents('php://input') function. This returns the payload as a string exactly as it arrived from the client. Once you have the string, you need to decode it into an array or object that your application logic can use.
$input = file_get_contents('php://input');
if (!empty($input)) {
$data = json_decode($input, true);
if (json_last_error() === JSON_ERROR_NONE) {
// $data is now a standard PHP array
$amount = $data['amount'] ?? null;
$currency = $data['currency'] ?? null;
// Proceed with your business logic
} else {
http_response_code(400);
echo json_encode(['error' => 'Invalid JSON payload']);
}
}
This approach is robust, but it requires handling the decoding process manually. Every time you receive a POST request, you have to decide whether to trust $_POST or php://input. This adds cognitive load and increases the risk of logic errors in your codebase. You might accidentally mix form fields with JSON data, leading to unexpected null values or type mismatches.
A more reliable solution is to centralize this logic within a framework. Laravel, for instance, abstracts this complexity away by providing a unified way to access request data. When using Laravel's request() helper, the framework automatically inspects the incoming Content-Type header. If the payload is JSON, it decodes it and makes the result available in request()->all(). This means you can write code that looks like this:
$request = request();
$amount = $request->input('amount');
Regardless of whether the client sent form-encoded data or a raw JSON string, Laravel ensures that request()->all() returns an array containing the decoded values. This consistency prevents the "empty array" confusion and reduces the boilerplate code needed to handle different input formats.
If you are building a custom application without a framework, wrapping your JSON handling logic in a utility function is a good practice. This keeps your controllers clean and ensures that any future changes to input parsing happen in one place. Always validate the JSON structure after decoding it before accessing properties; relying on json_last_error() prevents silent failures where missing keys might return null instead of throwing an exception, depending on your configuration.
For developers needing a comprehensive guide on handling various HTTP request types and stream inputs in PHP, you can refer to the resources available at https://laravelcompany.com. They provide detailed documentation on managing input streams and parsing payloads efficiently.
The core takeaway is that $_POST is context-dependent. It only works for form submissions. When dealing with APIs or modern web services sending JSON, always check the Content-Type header first. If it indicates JSON, switch to reading the raw input stream and decoding it explicitly. This discipline ensures your backend remains resilient against diverse client implementations.
