Altın Konu PHP'de json_encode() Kullanarak Verileri JSON Formatına Dönüştürme

[Agora Metin2]

json_encode($value) fonksiyonu, PHP'deki bir değeri JSON formatında bir metne dönüştürür. Bu işlem sırasında ilişkisel diziler JSON nesnesine, indeksli diziler (0, 1, 2... şeklinde ilerleyenler) ise JSON dizilerine dönüştürülür. Metinler, sayılar, true, false ve null değerleri ise kendi JSON karşılıklarını alırlar.

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

İşlem sonucunda düz bir metin dizgesi elde edilir; bu çıktı bir tarayıcıya gönderilmeye, veritabanında veya bir dosyada saklanmaya ya da başka bir uygulamaya aktarılmaya hazırdır. JSON formatındaki veriyi tekrar PHP'ye dönüştürmek isterseniz json_decode() fonksiyonunu kullanabilirsiniz.

JSON Çıktısını Okunabilir Hale Getirmek

json_encode() fonksiyonu, ikinci parametre olarak çeşitli bayraklar kabul eder. JSON_PRETTY_PRINT bayrağı, çıktıya satır sonları ve 4 boşlukluk girintiler ekleyerek veriyi daha düzenli hale getirir; bu özellik özellikle hata ayıklama kayıtlarında veya yapılandırma dosyalarında oldukça kullanışlıdır. Birden fazla bayrağı aynı anda kullanmak için | operatörü ile birleştirme yapabilirsiniz:

<?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": []
}

UTF-8 Metinleri ve Özel Karakterleri Korumak

Varsayılan olarak json_encode(), ASCII dışındaki tüm karakterleri \u şeklinde kodlar ve her / işaretinin önüne ters eğik çizgi koyar. Bu yöntem geçerli bir JSON formatıdır ve geri çözüldüğünde aynı metni verir, ancak çıktının okunmasını zorlaştırır ve metni uzatır. JSON_UNESCAPED_UNICODE bayrağı karakterleri olduğu gibi korurken, JSON_UNESCAPED_SLASHES bayrağı URL'lerin yapısını bozmadan 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"}

Türkçe veya Japonca gibi metinler çözümleme işleminden sonra bozuk görünüyorsa, sorun kaçış karakterleri değil, dizgenin başlangıçta UTF-8 formatında olmamasıdır. json_encode() fonksiyonu yalnızca UTF-8 verilerini kabul eder ve diğer formatlarda false döndürür.

Dizilerin Liste Yerine Nesneye Dönüştüğü Durumlar

Bir PHP dizisinin JSON dizisi olarak kodlanabilmesi için anahtarlarının kesinlikle sırasıyla 0, 1, 2... şeklinde olması gerekir. Eğer anahtarlarda herhangi bir farklılık varsa, sonuç bir JSON nesnesi olur. Bu durum, array_filter() veya unset() kullanımı sonrası anahtarlarda boşluk oluştuğunda kafa karıştırıcı olabilir:

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

Eğer alıcı taraf mutlaka bir liste bekliyorsa, kodlama işleminden önce array_values() fonksiyonunu çağırmalısınız. Boş olsa dahi bir nesne dönmesi gerekiyorsa, boş değerin yine {} şeklinde çıkması için new stdClass() veya (object) $array kullanabilirsiniz.

Nesne Kodlama ve JsonSerializable ile Kontrol Sağlama

Sıradan bir nesne kodlandığında sadece public olan özellikleri JSON'a aktarılır; protected ve private özellikler ise dışarıda bırakılır. Bir nesnenin JSON'da tam olarak nasıl görüneceğini belirlemek için JsonSerializable arayüzünü uygulayabilir ve istenen veriyi jsonSerialize() metodu üzerinden döndürebilirsiniz:

<?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 enum yapıları, sahip oldukları değerle ("active" gibi) kodlanır. Ancak değeri olmayan saf enum'lar kodlanamaz ve json_encode() fonksiyonu "Non-backed enums have no default serialization" hatasıyla 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; ancak dizgeler, içerikleri rakamlardan oluşsa bile dizge olarak kalmaya devam eder. Üç farklı bayrak bu durumu değiştirebilir:

<?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 bayrağı tüm sayısal dizgeleri sayıya dönüştürür; bu nedenle "007" gibi bir ID veya "01234" gibi bir posta kodu baştaki sıfırlarını kaybeder. Bu bayrağı tüm diziye uygulamak yerine, sadece ilgili alanları (int) ile dönüştürmek daha doğru bir yaklaşımdır.

json_encode() Fonksiyonu false Döndürdüğünde Hata Ayıklama

json_encode() fonksiyonu, değeri kodlayamadığı durumlarda false döndürür. Bunun en yaygın nedenleri, UTF-8 olmayan dizgeler (örneğin Latin-1 veritabanından gelen metinler) veya NAN ve INF gibi geçersiz ondalık değerlerdir. Hatanın kaynağını öğrenmek için json_last_error_msg() fonksiyonu kullanılabilir; JSON_THROW_ON_ERROR bayrağı ise bunun yerine bir JsonException fırlatılması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

Güncel projelerde JSON_THROW_ON_ERROR kullanımı daha güvenlidir; çünkü kontrol edilmeyen bir false sonucu, verinin boş bir dizge olarak kaydedilmesine veya iletilmesine yol açabilir.

PHP API'leri Üzerinden JSON Verisi Döndürmek

JSON yanıtı veren bir PHP betiği, herhangi bir veri yazdırmadan önce Content-Type başlığını ayarlamalı, veriyi kodlamalı ve ardından işlemi durdurmalıdır:

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

Eğer JSON çıktısını bir HTML <script> etiketi içerisine yazdırıyorsanız, JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT bayraklarını eklemelisiniz. Varsayılan eğik çizgi kaçışları </script> ifadesini <\/script> şeklinde yaparak koruma sağlar, ancak JSON_UNESCAPED_SLASHES eklendiğinde bu koruma ortadan kalkar ve değer içindeki <!-- gibi ifadeler tarayıcının betiği yanlış yorumlamasına neden olabilir. Bu bayraklar <, >, &, ' ve " karakterlerini sırasıyla \u003C, \u003E, \u0026, \u0027 ve \u0022 şeklinde yazar; JavaScript tarafında ise bu değerler tekrar orijinal karakterler olarak okunur.

 

[Lightning]

Eline sağlık