Using PHP Headers When Serving JSON Data

Web browsers and other similar applications rely on headers to understand the content being served to them by a web server. While modern browsers will try to “guess” what format content is in and intelligently format it, it’s still good practice to use headers to ensure your application’s output is handled correctly. When sending a JSON Payload, the header is set using the following PHP code:

header('Content-type: application/json');

It’s important to be aware of a few things when setting headers, however.

First, to avoid the error “Headers already sent”, the headers must be the first thing sent by the web server. It’s a good idea to put any code relating to setting headers at the top of your PHP file to avoid issues caused by your script generating other output before the headers are set.

In addition, consider how you want the browser/client to handle the data. In this sample, we don’t just inform the browser that the data is in JSON format — we also set some instructions to do with caching and expiry.

header('Cache-Control: no-cache, must-revalidate');

This line tells the browser not to cache the data and that it should send a revalidation request each time it wants to load the data to ensure the information it has is still fresh. These instructions are useful for data that is time-sensitive or that changes regularly.

The expires header is used to help the browser know when it needs to re-request data.

header('Expires: Mon, 26 Jul 1997 05:00:00 GMT');

In this example, the expiry date is set to one a long time in the past, telling the server that it should always send a revalidation request. This date and time could be changed to anything the developer wishes. For example, a JSON file detailing class timetables could be set to expire on “Friday evening.” If a user requests the timetable on a Saturday, they’ll see the information for the following week.

Once the headers have been sent, the PHP script can send the JSON payload, confident the application will process it correctly.

Common Causes of “Headers Already Sent” Errors

The most common issue when setting headers in PHP is for the headers to be sent too late in the script. If the script sends any output — even a blank line or whitespace — before the headers are sent, this will result in an error. 

It’s common to encounter this error when using a single file for HTML and PHP. Even if the headers are set at the start of the PHP code, if the file has already sent some HTML tags, this means it’s too late to set the headers.

In some cases, the source of the error is not so obvious. PHP code that uses include or require to read additional files could cause an error when setting headers if the other PHP scripts create any output.  

Always run any code to do with header instructions before any other code or markup to prevent this error.