How to post JSON to PHP with curl

How to post JSON to PHP with curl

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

The Hidden Header: Why Your JSON POST Returns an Empty Array

When you execute a curl command to send JSON data to a PHP endpoint, receiving an empty array or unexpected null values often points to a missing configuration detail rather than a logic error in your application code. The core issue lies in how the web server interprets the incoming request payload. Without explicit instruction, servers default to treating POST data as application/x-www-form-urlencoded.

In your specific scenario, where you are sending a JSON object like {"screencast":{"subject":"tools"}}, the server attempts to parse this string using URL decoding rules. It looks for keys and values separated by & or = signs. Since your payload lacks these delimiters, the parser sees no valid form fields, resulting in an empty array on the PHP side. The HTTP 409 Conflict response you observed is a downstream effect of the application trying to process null values against expected data types.

To resolve this, you must explicitly tell the client that the payload is JSON by setting the Content-Type header. When using curl, this is done with the -H flag:

curl -i -X POST \
  -H "Content-Type: application/json" \
  -d '{"screencast":{"subject":"tools"}}' \
  http://localhost:3570/index.php/trainingServer/screencast.json

This single header addition changes the behavior of the web server. Upon receiving application/json, the PHP framework (or your own controller) will invoke the JSON decoder to parse the raw string into an associative array or object. This ensures that $POST['screencast']['subject'] returns the string "tools" instead of null.

It is important to note that while setting the header on the client side is best practice, some frameworks attempt to guess the content type based on the application/json extension in the URL or by inspecting the raw body if no header is present. However, relying on such heuristics is fragile and prone to failure, as seen in the Recess Framework tutorial where the request consistently failed without the header. Always assume the server requires explicit instruction unless you have verified its specific parsing logic.

There is a subtle distinction between -d and --data-binary. In older versions of curl, specifically when dealing with binary data or large files, -d might attempt to interpret the input as text, adding a newline character at the end of the payload. This can break JSON parsing in strict environments. While -d works for most standard JSON payloads and is generally safe, using --data-binary ensures the byte stream is sent exactly as defined without any post-processing.

curl -i -X POST \
  -H "Content-Type: application/json" \
  --data-binary '{\"screencast\":{\"subject\":\"tools\"}}' \
  http://localhost:3570/index.php/trainingServer/screencast.json

For most modern development workflows, the standard -d flag with the correct header is sufficient and preferred for readability. If you are maintaining legacy systems or dealing with strict parsers, switch to --data-binary.

When debugging these issues, always inspect the raw request headers sent by your client. Tools like Postman or curl -v reveal exactly what the server sees before PHP processes it. Understanding the flow from HTTP header to PHP variable is crucial for troubleshooting API integrations. For developers looking to streamline this process in larger ecosystems, libraries that handle HTTP clients with robust header management are available. Resources like LaravelCompany often discuss best practices for handling JSON payloads within modern frameworks, emphasizing the importance of consistent header negotiation between client and server.

Finally, ensure your PHP application does not rely on magic type detection. If your endpoint expects a specific structure, validating the Content-Type header before processing the body adds an extra layer of security and clarity, preventing malformed data from silently corrupting your database or state.

Our network