JSON Handling

Introduction

JSON (JavaScript Object Notation) is the format nearly every modern web API speaks. Whether you are building an endpoint for a JavaScript frontend, a mobile app, or another server, you will almost certainly need to convert PHP data into JSON — and parse JSON back into PHP data.

PHP makes this easy with two built-in functions: json_encode() and json_decode(). This lesson covers both, along with the common pitfalls that trip up beginners.

What Is JSON?

JSON is a lightweight, text-based data format for representing structured data — objects, arrays, strings, numbers, booleans, and null. It grew out of JavaScript syntax but is now language-independent and used everywhere: REST APIs, configuration files, and message queues.

{
  "name": "Jane Doe",
  "age": 27,
  "active": true,
  "roles": ["editor", "author"]
}

json_encode(): PHP to JSON

json_encode() converts a PHP value — usually an array or object — into a JSON-formatted string.

<?php
$user = [
    "name"   => "Jane Doe",
    "age"    => 27,
    "active" => true,
    "roles"  => ["editor", "author"],
];

echo json_encode($user);

{"name":"Jane Doe","age":27,"active":true,"roles":["editor","author"]}

That single line of output is valid but hard to read. Passing the JSON_PRETTY_PRINT flag formats the result with indentation and line breaks, which is useful for debugging or for developer-facing endpoints.

<?php
echo json_encode($user, JSON_PRETTY_PRINT);

{
    "name": "Jane Doe",
    "age": 27,
    "active": true,
    "roles": [
        "editor",
        "author"
    ]
}

json_decode(): JSON to PHP

json_decode() takes a JSON string and converts it back into PHP data. By default, it returns objects (instances of stdClass) rather than arrays.

<?php
$json = '{"name":"Jane Doe","age":27,"roles":["editor","author"]}';

$data = json_decode($json);

echo $data->name . "\n";
echo $data->age . "\n";
echo $data->roles[0];

Jane Doe
27
editor

Associative Arrays vs Objects

Passing true as the second argument to json_decode() tells it to return associative arrays instead of stdClass objects. Most PHP developers prefer this, since arrays are usually easier to work with using familiar syntax like $data["name"].

<?php
$json = '{"name":"Jane Doe","age":27,"roles":["editor","author"]}';

$data = json_decode($json, true);

echo $data["name"] . "\n";
echo $data["age"] . "\n";
echo $data["roles"][0];

Jane Doe
27
editor

Handling Errors

If the JSON string is malformed, json_decode() quietly returns null instead of throwing an error. Since a valid JSON document can also decode to null (the JSON value "null" itself), checking for null is not reliable on its own — always check json_last_error() as well.

<?php
$badJson = '{"name": "Jane", "age": }'; // malformed: missing value

$data = json_decode($badJson, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    echo "Failed to parse JSON: " . json_last_error_msg();
} else {
    echo "Parsed successfully.";
}

Failed to parse JSON: Syntax error

Example: A Tiny JSON API Response

Here is a minimal example of a PHP script that could act as a JSON API endpoint: it builds some data, encodes it, and sends it with the correct content type.

<?php
header("Content-Type: application/json");

$products = [
    ["id" => 1, "name" => "Keyboard", "price" => 49.99],
    ["id" => 2, "name" => "Mouse", "price" => 19.99],
];

$response = [
    "status" => "success",
    "count"  => count($products),
    "data"   => $products,
];

echo json_encode($response, JSON_PRETTY_PRINT);

{
    "status": "success",
    "count": 2,
    "data": [
        {
            "id": 1,
            "name": "Keyboard",
            "price": 49.99
        },
        {
            "id": 2,
            "name": "Mouse",
            "price": 19.99
        }
    ]
}

Setting the Content-Type header to application/json tells the client — a browser, a mobile app, or another server — exactly how to interpret the response body.

Common Mistakes

Best Practices

Frequently Asked Questions

Key Takeaways

Summary

JSON is the backbone of modern web communication, and PHP's json_encode() and json_decode() make working with it straightforward. The key details to remember are choosing between objects and associative arrays, and always checking for decoding errors on untrusted input.

Next, you will look at XML, an older but still relevant data format, and see how PHP can read and navigate it.