json_encode() w PHP: tablice i obiekty do JSON

json_encode($value) zwraca tekst JSON dla wartości PHP. Tablica asocjacyjna staje się obiektem JSON, lista (klucze 0, 1, 2...) tablicą JSON, a stringi, liczby, true, false i null swoimi odpowiednikami w JSON.

<?php
$user = [
    'name'    => 'Ada',
    'age'     => 36,
    'langs'   => ['php', 'js'],
    'admin'   => true,
    'manager' => null,
];

$json = json_encode($user);
echo $json, "\n";
echo gettype($json), "\n";

Wynik:

{"name":"Ada","age":36,"langs":["php","js"],"admin":true,"manager":null}
string

Wynik to zwykły string, gotowy do wysłania do przeglądarki, zapisania w pliku lub kolumnie bazy danych albo przekazania do innego programu. Aby zamienić JSON z powrotem na PHP, użyj json_decode().

Ładne formatowanie JSON

json_encode() przyjmuje flagi jako drugi argument. JSON_PRETTY_PRINT dodaje złamania linii i wcięcia po 4 spacje, czego chcesz w pliku konfiguracyjnym albo logu do debugowania. Łącz kilka flag przez |:

<?php
$config = [
    'app'   => 'shop',
    'debug' => false,
    'db'    => ['host' => 'localhost', 'port' => 3306],
    'tags'  => [],
];

echo json_encode($config, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES), "\n";

Wynik:

{
    "app": "shop",
    "debug": false,
    "db": {
        "host": "localhost",
        "port": 3306
    },
    "tags": []
}

Czytelny tekst polski, japoński i inny UTF-8

Domyślnie json_encode() zapisuje każdy znak spoza ASCII jako sekwencję \u i wstawia ukośnik wsteczny przed każdym /. Oba zapisy to poprawny JSON i dekodują się do tego samego tekstu, ale utrudniają czytanie wyniku i go wydłużają. JSON_UNESCAPED_UNICODE zachowuje znaki, a JSON_UNESCAPED_SLASHES zostawia adresy URL bez zmian:

<?php
$item = ['name' => 'りんご', 'price' => 120, 'url' => 'https://example.com/fruit/apple'];

echo json_encode($item), "\n";
echo json_encode($item, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

Wynik:

{"name":"\u308a\u3093\u3054","price":120,"url":"https:\/\/example.com\/fruit\/apple"}
{"name":"りんご","price":120,"url":"https://example.com/fruit/apple"}

Jeśli tekst po zdekodowaniu wygląda na zepsuty (krzaki zamiast liter, po japońsku 文字化け), problemem nie są sekwencje ucieczki: string od początku nie był w UTF-8. json_encode() przyjmuje tylko UTF-8 i dla wszystkiego innego zwraca false, co pokazuje sekcja o błędach.

Kiedy tablica staje się obiektem zamiast listy

Tablica PHP jest kodowana jako tablica JSON tylko wtedy, gdy jej klucze to dokładnie 0, 1, 2... po kolei. Każde inne klucze czynią z niej obiekt JSON. To zaskakuje po unset() albo array_filter(), które zostawiają luki w kluczach:

<?php
$fruits = ['apple', 'banana', 'cherry'];
unset($fruits[1]);

echo json_encode($fruits), "\n";                // keys 0, 2: an object
echo json_encode(array_values($fruits)), "\n";  // renumbered: a list

echo json_encode([1 => 'a', 2 => 'b']), "\n";   // does not start at 0

echo json_encode([]), "\n";                     // empty array: always []
echo json_encode(new stdClass()), "\n";         // empty object
echo json_encode(['a', 'b'], JSON_FORCE_OBJECT), "\n";

Wynik:

{"0":"apple","2":"cherry"}
["apple","cherry"]
{"1":"a","2":"b"}
[]
{}
{"0":"a","1":"b"}

Wywołuj array_values() przed kodowaniem zawsze, gdy kod odbierający oczekuje listy. Jeśli oczekuje obiektu, który może być pusty, użyj new stdClass() albo (object) $array, żeby pusta wartość nadal wychodziła jako {}.

Kodowanie obiektu i kontrola jego JSON przez JsonSerializable

Zwykły obiekt jest kodowany tylko z publicznymi właściwościami; chronione i prywatne są pomijane. Aby dokładnie zdecydować, jak obiekt wygląda w JSON, zaimplementuj interfejs JsonSerializable i zwróć dane z jsonSerialize():

<?php
class User
{
    public string $name = 'Ada';
    public ?string $nick = null;
    private string $password = 'secret';   // never encoded
}

echo json_encode(new User()), "\n";

// A date object encodes its internals, which is rarely what an API wants
echo json_encode(new DateTimeImmutable('2026-03-14 09:30')), "\n";

class Order implements JsonSerializable
{
    public function __construct(
        private int $id,
        private float $total,
        private DateTimeImmutable $created,
    ) {}

    public function jsonSerialize(): array
    {
        return [
            'id'      => $this->id,
            'total'   => $this->total,
            'created' => $this->created->format(DATE_ATOM),
        ];
    }
}

$order = new Order(7, 19.5, new DateTimeImmutable('2026-03-14 09:30'));
echo json_encode($order, JSON_PRETTY_PRINT), "\n";

Wynik:

{"name":"Ada","nick":null}
{"date":"2026-03-14 09:30:00.000000","timezone_type":3,"timezone":"UTC"}
{
    "id": 7,
    "total": 19.5,
    "created": "2026-03-14T09:30:00+00:00"
}

Enum backed, taki jak enum Status: string, koduje się jako swoja wartość ("active"). Enum czysty nie ma wartości, więc json_encode() zawodzi na nim z komunikatem „Non-backed enums have no default serialization”.

Liczby, liczby zmiennoprzecinkowe i stringi liczbowe

Liczby całkowite i zmiennoprzecinkowe są zapisywane jako liczby JSON, a stringi pozostają stringami, nawet gdy zawierają cyfry. Zmieniają to trzy flagi:

<?php
echo json_encode(['price' => 10.0]), "\n";                               // 10.0 loses its .0
echo json_encode(['price' => 10.0], JSON_PRESERVE_ZERO_FRACTION), "\n";
echo json_encode(0.1 + 0.2), "\n";                                       // full float precision

echo json_encode(['qty' => '3', 'id' => '007']), "\n";
echo json_encode(['qty' => '3', 'id' => '007'], JSON_NUMERIC_CHECK), "\n";

Wynik:

{"price":10}
{"price":10.0}
0.30000000000000004
{"qty":"3","id":"007"}
{"qty":3,"id":7}

JSON_NUMERIC_CHECK konwertuje każdy string liczbowy, więc identyfikator taki jak "007" albo kod pocztowy taki jak "01234" traci zera wiodące. Zamiast używać tej flagi na całej tablicy, konwertuj wybrane pola przez (int).

json_encode zwraca false: znajdź błąd

json_encode() zwraca false, gdy nie potrafi zakodować wartości. Zwykłe przyczyny to string, który nie jest poprawnym UTF-8 (tekst odczytany ze starego pliku lub bazy w Latin-1 czy Windows-1250), oraz wartości zmiennoprzecinkowe NAN i INF. json_last_error_msg() mówi, co poszło nie tak; JSON_THROW_ON_ERROR sprawia, że zamiast tego rzucany jest JsonException:

<?php
$name = "Caf\xE9";   // "Café" in Latin-1, not valid UTF-8

var_dump(json_encode(['name' => $name]));
echo json_last_error_msg(), "\n";

// Replace the broken bytes instead of failing
echo json_encode(['name' => $name], JSON_INVALID_UTF8_SUBSTITUTE), "\n";

// Or convert the text to UTF-8 first
echo json_encode(['name' => mb_convert_encoding($name, 'UTF-8', 'ISO-8859-1')], JSON_UNESCAPED_UNICODE), "\n";

try {
    json_encode(NAN, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo get_class($e), ': ', $e->getMessage(), "\n";
}

Wynik:

bool(false)
Malformed UTF-8 characters, possibly incorrectly encoded
{"name":"Caf\ufffd"}
{"name":"Café"}
JsonException: Inf and NaN cannot be JSON encoded

JSON_THROW_ON_ERROR to lepsza wartość domyślna w nowym kodzie: false, którego nikt nie sprawdza, trafia w końcu do zapisu lub wysyłki jako pusty string.

Zwracanie JSON z API w PHP

Skrypt PHP odpowiadający JSON ustawia nagłówek Content-Type przed wypisaniem czegokolwiek, koduje raz i kończy działanie:

<?php
header('Content-Type: application/json; charset=utf-8');

$products = [
    ['id' => 1, 'name' => 'りんご', 'price' => 120],
    ['id' => 2, 'name' => 'みかん', 'price' => 80],
];

echo json_encode(['data' => $products], JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
exit;

Gdy zamiast tego wypisujesz JSON wewnątrz znacznika HTML <script>, dodaj JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT. Domyślne escapowanie ukośników zamienia </script> w <\/script>, ale ta ochrona znika, gdy tylko ktoś doda JSON_UNESCAPED_SLASHES, a <!-- w wartości nadal zmienia sposób, w jaki przeglądarka parsuje skrypt. Te flagi zapisują <, >, &, ' i " jako \u003C, \u003E, \u0026, \u0027 i \u0022, które JavaScript odczytuje z powrotem jako te same znaki.