PHP json_encode(): Dizileri ve Nesneleri JSON'a Çevirme

json_encode($value) bir PHP değeri için JSON metnini döndürür. İlişkisel bir dizi bir JSON nesnesi, bir liste (0, 1, 2... anahtarları) bir JSON dizisi olur; dizgeler, sayılar, true, false ve null ise JSON karşılıklarına dönüşür.

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

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

Çıktı:

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

Sonuç düz bir dizgedir; bir tarayıcıya gönderilmeye, bir dosyada veya veritabanı sütununda saklanmaya ya da başka bir programa verilmeye hazırdır. JSON'u geri PHP'ye çevirmek için json_decode() kullanın.

JSON'u okunur biçimde yazdırma

json_encode() ikinci argüman olarak bayraklar alır. JSON_PRETTY_PRINT satır sonları ve 4 boşluklu girinti ekler; bir yapılandırma dosyasında veya hata ayıklama logunda istediğiniz budur. Birkaç bayrağı | ile birleştirin:

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

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

Çıktı:

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

Japonca ve diğer UTF-8 metinleri okunur tutma

Varsayılan olarak json_encode() ASCII olmayan her karakteri bir \u kaçışı olarak yazar ve her / işaretinin önüne bir ters eğik çizgi koyar. İkisi de geçerli JSON'dur ve aynı metne geri çözülür, ama çıktıyı okunması zor ve daha uzun yapar. JSON_UNESCAPED_UNICODE karakterleri korur, JSON_UNESCAPED_SLASHES ise URL'leri olduğu gibi tutar:

<?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";

Çıktı:

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

Japonca veya Türkçe metin çözümlemeden sonra bozuk görünüyorsa sorun kaçışlar değildir: dizge baştan UTF-8 değildi. json_encode() yalnızca UTF-8 kabul eder ve hatalar bölümünde gösterildiği gibi diğer her şey için false döndürür.

Bir dizi liste yerine nesneye dönüştüğünde

Bir PHP dizisi yalnızca anahtarları tam olarak sırasıyla 0, 1, 2... olduğunda bir JSON dizisi olarak kodlanır. Başka herhangi bir anahtar onu bir JSON nesnesi yapar. Bu, anahtarlarda boşluk bırakan unset() veya array_filter() sonrasında insanları şaşırtır:

<?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";

Çıktı:

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

Alıcı kod bir liste beklediğinde kodlamadan önce array_values() çağırın. Boş olabilecek bir nesne bekliyorsa new stdClass() veya (object) $array kullanın, böylece boş bir değer yine {} olarak çıkar.

Bir nesneyi kodlama ve JSON'unu JsonSerializable ile kontrol etme

Düz bir nesne yalnızca public özellikleriyle kodlanır; protected ve private olanlar atlanır. Bir nesnenin JSON'da tam olarak nasıl görüneceğine karar vermek için JsonSerializable arayüzünü uygulayın ve veriyi jsonSerialize() metodundan döndürün:

<?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";

Çıktı:

{"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 Status: string gibi değerli bir enum değeri ("active") olarak kodlanır. Saf bir enum'un değeri yoktur, bu yüzden json_encode() onda "Non-backed enums have no default serialization" ile başarısız olur.

Sayılar, ondalıklı sayılar ve sayısal dizgeler

Tam sayılar ve ondalıklı sayılar JSON sayıları olarak yazılır ve dizgeler rakam içerseler bile dizge olarak kalır. Üç bayrak bunu değiştirir:

<?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";

Çıktı:

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

JSON_NUMERIC_CHECK her sayısal dizgeyi dönüştürür, bu yüzden "007" gibi bir ID veya "01234" gibi bir posta kodu baştaki sıfırlarını kaybeder. Onu bütün bir dizi üzerinde kullanmak yerine kastettiğiniz alanları (int) ile dönüştürün.

json_encode false döndürüyor: hatayı bulma

json_encode() değeri kodlayamadığında false döndürür. Olağan nedenler geçerli UTF-8 olmayan bir dizge (eski bir dosyadan veya Latin-1 bir veritabanından okunan metin) ve NAN ile INF ondalık değerleridir. json_last_error_msg() neyin yanlış gittiğini söyler; JSON_THROW_ON_ERROR ise bunun yerine bir JsonException fırlatmasını sağlar:

<?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";
}

Çıktı:

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

Yeni kodda JSON_THROW_ON_ERROR daha iyi bir varsayılandır: kimsenin kontrol etmediği bir false sonunda boş bir dizge olarak saklanır veya gönderilir.

Bir PHP API'sinden JSON döndürme

JSON ile yanıt veren bir PHP betiği herhangi bir şey yazdırmadan önce Content-Type başlığını ayarlar, bir kez kodlar ve durur:

<?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;

Bunun yerine JSON'u bir HTML <script> etiketinin içine yazdırdığınızda JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT ekleyin. Varsayılan eğik çizgi kaçışı </script> ifadesini <\/script> yapar, ama biri JSON_UNESCAPED_SLASHES eklediği anda bu koruma kaybolur ve bir değerdeki <!-- yine tarayıcının betiği ayrıştırma şeklini değiştirir. Bayraklar <, >, &, ' ve " karakterlerini \u003C, \u003E, \u0026, \u0027 ve \u0022 olarak yazar; JavaScript onları aynı karakterler olarak geri okur.