Working with JSON APIs: A PHP Guide to Data Exchange

Previously in this course, we explored using traits for code reuse to keep our controllers lean. This lesson adds a critical capability: transforming that server-side data into a machine-readable format that modern frontend frameworks and browsers can consume seamlessly.

The Role of JSON in Modern Web Apps

In our previous MVC setup, we mostly rendered HTML directly from PHP. However, modern applications often require a separation where the backend acts as a data provider. By outputting JSON as the standard exchange format for REST APIs, we allow the frontend to request data independently of the page layout.

Encoding PHP Arrays to JSON

PHP provides a robust, built-in function called json_encode() to convert arrays or objects into JSON strings. Because JSON is a string-based format, this step is essential for "serializing" your internal PHP data for transmission over HTTP.

PHP
#6A9955">// An example of a PHP associative array
$user = [
    'id' => 101,
    'username' => 'dev_user',
    'email' => 'tech@example.com',
    'active' => true
];

#6A9955">// Encoding to JSON string
$jsonString = json_encode($user);

echo $jsonString; 
#6A9955">// Output: {"id":101,"username":"dev_user","email":"tech@example.com","active":true}

Setting HTTP Headers

By default, PHP sends a Content-Type: text/html header. If you send JSON without changing this, the browser might treat it as plain text. To ensure your API is interpreted correctly as data, you must explicitly set the Content-Type header to application/json.

PHP
#6A9955">// Always set this BEFORE outputting any data
header('Content-Type: application/json');

$data = ['status' => 'success', 'message' => 'Data retrieved'];
echo json_encode($data);

Consuming JSON via AJAX

Now that your PHP endpoint is outputting JSON, the frontend needs to fetch it. While you can use older methods, modern development favors the Fetch API. As we discussed in Mastering the Fetch API: GET Requests and JSON Data in JavaScript, this approach is clean and supports promises.

Here is how you would call your new PHP endpoint from a script:

JAVASCRIPT
// Assuming your PHP endpoint is at /api/user.php
fetch(CE9178">'/api/user.php')
    .then(response => response.json())
    .then(data => {
        console.log(CE9178">'User ID:', data.id);
        console.log(CE9178">'Username:', data.username);
    })
    .catch(error => console.error(CE9178">'Error fetching data:', error));

Hands-on Exercise

1. Create a new file named api_status.php.
2. Inside, define an associative array containing your application's current version, a status message, and a timestamp using time().
3. Use the header() function to set the application/json type.
4. Output the encoded JSON.
5. Create a simple HTML file with a <script> tag that fetches this endpoint and logs the version number to the browser console.

Common Pitfalls

• Outputting Extra Whitespace: If you have any echo statements or even whitespace outside of your <?php ?> tags before the header is sent, PHP will send text/html headers automatically. Always keep your API files clean.
• Ignoring Errors: If your PHP script fails or displays a notice, that text will end up in your JSON stream, causing a parsing error in JavaScript. Use try-catch blocks to ensure you always return a valid JSON object, even when an error occurs.
• Encoding Issues: json_encode requires UTF-8 encoded data. If you are pulling data from a database that uses a different collation, you may need to convert strings using mb_convert_encoding().

FAQ

Q: Can I return objects instead of arrays? A: Yes, json_encode() handles public properties of objects automatically. It is a great way to serialize your Model classes directly.

Q: What if I need to return a list of items? A: Simply pass a nested array (a list of associative arrays) to json_encode(). It will automatically generate a JSON array format (e.g., [...]).

Q: How do I handle large datasets? A: For large datasets, remember to include pagination metadata in your response so the frontend knows how to handle the data flow, as covered in Implementing Links in Responses: HATEOAS for Better APIs.

Recap

We have moved beyond static HTML output to building data-driven endpoints. By utilizing json_encode(), setting strict Content-Type headers, and utilizing fetch on the frontend, you are now equipped to create true API-driven architectures. This is the foundation for decoupling your backend from your frontend.

Up next: Handling File Uploads — managing the $_FILES superglobal and securing user uploads.