PHP json_encode ve json_decode Kullanımı: Bayraklar, Hatalar ve İpuçları

json_encode: temel kullanım ve Türkçe karakterler

json_encode() verilen değeri JSON metnine çevirir; dizi veya nesne verilirse içindekileri de özyinelemeli olarak dönüştürür. Başarısız olursa false döndürür. Kaynak türü (resource) dışındaki her türü kabul eder ve kılavuza göre tüm metin verilerinin UTF-8 kodlanmış olması gerekir. Varsayılan ayarlarla çıktıya bakalım:

<?php
$kullanici = [
    'ad'     => 'Şule Çağlar',
    'sehir'  => 'İzmir',
    'aktif'  => true,
    'puan'   => 4.5,
    'etiket' => ['php', 'json'],
    'site'   => 'https://www.keydal.tr/blog',
    'not'    => null,
];

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

{"ad":"\u015eule \u00c7a\u011flar","sehir":"\u0130zmir","aktif":true,"puan":4.5,"etiket":["php","json"],"site":"https:\/\/www.keydal.tr\/blog","not":null}
{"ad":"Şule Çağlar","sehir":"İzmir","aktif":true,"puan":4.5,"etiket":["php","json"],"site":"https://www.keydal.tr/blog","not":null}

İlk satırda iki şey göze çarpıyor. Türkçe karakterler \u015e, \u00c7 gibi Unicode kaçış dizilerine dönüştü; bu geçerli bir JSON'dur ve her ayrıştırıcı doğru okur, ama insanlar için okunaksızdır ve metni büyütür. Ayrıca adresteki eğik çizgiler \/ olarak kaçırıldı. İkinci satırda JSON_UNESCAPED_UNICODE çok baytlı karakterleri olduğu gibi bırakıyor, JSON_UNESCAPED_SLASHES ise / işaretine dokunmuyor. Bayraklar bit maskesidir; birden fazlasını | ile birleştirirsiniz.

Kılavuz JSON_UNESCAPED_LINE_TERMINATORS adlı bir bayrağı da listeler: JSON_UNESCAPED_UNICODE kullanırken Unicode satır sonlandırıcılarını da kaçırmadan bırakmak için PHP 7.1'de eklenmiştir. JSON çıktısını bir HTML sayfasının içine gömüyorsanız tersine JSON_HEX_TAG, JSON_HEX_AMP, JSON_HEX_APOS ve JSON_HEX_QUOT bayrakları <, >, &, tek ve çift tırnak karakterlerini \u003C gibi kaçış dizilerine çevirir. HTML çıktısında güvenliğin genel kuralları için XSS ve CSP koruması yazısına bakabilirsiniz.

Okunur çıktı: JSON_PRETTY_PRINT

Ayar dosyası yazarken ya da hata ayıklarken girintili çıktı işinizi kolaylaştırır. JSON_PRETTY_PRINT her düzeyi dört boşlukla girintiler ve her elemanı ayrı satıra yazar:

<?php
$veri = ['urun' => 'Kılıf', 'fiyat' => 149.9, 'stok' => [3, 0]];
echo json_encode($veri, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE), "\n";

{
    "urun": "Kılıf",
    "fiyat": 149.9,
    "stok": [
        3,
        0
    ]
}

Girintili çıktı yalnızca görünüşü değiştirir; anlamı aynıdır ve json_decode() ile aynı değeri geri alırsınız. Bir API yanıtında gereksiz boşluklar boyutu artırdığı için genellikle sıkıştırılmış biçim tercih edilir.

PHP dizisi ne zaman JSON dizisi, ne zaman nesne olur?

PHP'de tek bir dizi türü vardır, JSON'da ise dizi ([]) ve nesne ({}) ayrıdır. json_encode() bu ayrımı anahtarlara bakarak yapar: kılavuza göre anahtarlar 0'dan başlayan kesintisiz bir sayı dizisi değilse tüm anahtarlar metin olarak yazılır ve sonuç bir JSON nesnesi olur. Bu kural en çok unset() sonrasında sürpriz yaratır:

<?php
echo json_encode(['a', 'b', 'c']), "\n";          // çıktı: ["a","b","c"]
echo json_encode([1 => 'a', 2 => 'b']), "\n";     // çıktı: {"1":"a","2":"b"}

$liste = ['a', 'b', 'c'];
unset($liste[1]);
echo json_encode($liste), "\n";                   // çıktı: {"0":"a","2":"c"}
echo json_encode(array_values($liste)), "\n";     // çıktı: ["a","c"]

echo json_encode([]), "\n";                        // çıktı: []
echo json_encode([], JSON_FORCE_OBJECT), "\n";     // çıktı: {}
echo json_encode(new stdClass()), "\n";            // çıktı: {}
echo json_encode(12.0), ' ', json_encode(12.0, JSON_PRESERVE_ZERO_FRACTION), "\n"; // çıktı: 12 12.0

Ortadaki elemanı silmek anahtar dizisini 0, 2 haline getirdiği için çıktı aniden bir nesneye dönüştü. JavaScript tarafında dizi bekleyen bir kod bu durumda bozulur. Çözüm, kodlamadan önce array_values() ile anahtarları yeniden numaralandırmaktır; array_filter() sonrasında da aynı şey geçerlidir, çünkü o fonksiyon da anahtarları korur. Boş dizi varsayılan olarak [] olur; karşı taraf her zaman bir nesne bekliyorsa JSON_FORCE_OBJECT bayrağını kullanın. Sonuncu satırdaki JSON_PRESERVE_ZERO_FRACTION ise 12.0 gibi küsuratsız ondalık sayıların 12 olarak değil ondalık olarak yazılmasını sağlar. Dizilerin anahtar kuralları için PHP dizi temelleri yazısına bakabilirsiniz.

json_decode: nesne mi, dizi mi?

json_decode() varsayılan olarak JSON nesnelerini stdClass nesnelerine çevirir. İkinci parametre true olduğunda nesneler ilişkisel diziye dönüşür; null bırakılırsa davranışı JSON_OBJECT_AS_ARRAY bayrağı belirler. JSON'daki true, false ve null değerleri PHP'deki karşılıklarına dönüşür.

<?php
$json = '{"ad":"Ece","rol":{"kod":"admin","yetki":["oku","yaz"]},"ozel-alan":1}';

$nesne = json_decode($json);
echo $nesne->ad, "\n";                 // çıktı: Ece
echo $nesne->rol->yetki[1], "\n";      // çıktı: yaz
echo $nesne->{'ozel-alan'}, "\n";      // çıktı: 1

$dizi = json_decode($json, true);
echo $dizi['rol']['kod'], "\n";        // çıktı: admin
var_dump(is_array($dizi['rol']));      // çıktı: bool(true)

Nesne olarak çözdüğünüzde, PHP değişken adı kurallarına uymayan anahtarlara (örneğin tire içeren ozel-alan) $nesne->{'ozel-alan'} sözdizimiyle erişirsiniz. Dizi olarak çözmek çoğu durumda daha pratiktir: dizi fonksiyonlarıyla doğrudan çalışabilir, eksik anahtarları ?? operatörüyle kolayca ele alabilirsiniz. Eksik anahtara erişildiğinde çıkan uyarılar için Undefined array key uyarısı yazısına bakın.

Hataları yakalamak: json_last_error ve JSON_THROW_ON_ERROR

Varsayılan modda hata olduğunda json_decode() null, json_encode() false döndürür ve hatanın nedeni genel bir durumda saklanır. Bu durumu json_last_error() (tamsayı kod) ve json_last_error_msg() (metin) ile okursunuz. Kılavuz, JavaScript'te geçerli olan ama JSON'da geçersiz olan birkaç yaygın yazımı örnek verir:

<?php
$hatalilar = [
    "{'ad': 'Ece'}",      // tek tırnak geçersiz
    '{ad: "Ece"}',        // anahtar tırnaksız
    '{"ad": "Ece",}',     // sondaki virgül
    '',                   // boş metin
];

foreach ($hatalilar as $j) {
    $sonuc = json_decode($j, true);
    echo var_export($sonuc, true), ' | ', json_last_error(), ' | ', json_last_error_msg(), "\n";
}

var_dump(json_decode('null'));
echo json_last_error_msg(), "\n";

NULL | 4 | Syntax error
NULL | 4 | Syntax error
NULL | 4 | Syntax error
NULL | 4 | Syntax error
NULL
No error

Dört girdinin hepsi "Syntax error" (JSON_ERROR_SYNTAX, değeri 4) verdi: JSON'da anahtarlar ve metinler çift tırnak içinde olmalıdır, sondaki virgüle izin verilmez ve boş metin geçerli bir JSON değildir. Son iki satır ise varsayılan modun asıl zayıflığını gösteriyor: geçerli null JSON'u da null döndürür. Dönüş değerine bakarak hatayı ayırt edemezsiniz; her seferinde json_last_error() kontrol etmeniz gerekir ve bu kontrol unutulmaya çok açıktır.

PHP 7.3 ile gelen JSON_THROW_ON_ERROR bayrağı bu sorunu çözer. Bayrak verildiğinde hata durumunda bir JsonException fırlatılır ve istisnanın kodu json_last_error() değerleriyle aynıdır. Kılavuza göre bu bayrak kullanıldığında genel hata durumu güncellenmez; yani json_last_error_msg() son çağrıyı yansıtmaz. Bayrak json_decode() çağrısında dördüncü parametredir, bu yüzden önceki iki parametreyi de yazmanız gerekir:

<?php
function ayarOku(string $json): array
{
    try {
        return json_decode($json, true, 512, JSON_THROW_ON_ERROR);
    } catch (JsonException $e) {
        throw new InvalidArgumentException('Ayar dosyası bozuk: ' . $e->getMessage(), 0, $e);
    }
}

print_r(ayarOku('{"tema":"koyu","dil":"tr"}'));

try {
    ayarOku('{"tema":"koyu"');
} catch (InvalidArgumentException $e) {
    echo $e->getMessage(), "\n";
    echo 'JSON hata kodu: ', $e->getPrevious()->getCode(), ' (JSON_ERROR_SYNTAX = ', JSON_ERROR_SYNTAX, ")\n";
}

Array
(
    [tema] => koyu
    [dil] => tr
)
Ayar dosyası bozuk: Syntax error
JSON hata kodu: 4 (JSON_ERROR_SYNTAX = 4)

Örnekte JsonException, uygulamaya özgü daha anlamlı bir istisnaya sarılıyor ve asıl istisna $previous olarak saklanıyor. İstisna zincirleme kalıbının ayrıntıları PHP try/catch ve exception yazısında anlatılıyor. Yeni yazdığınız kodda JSON_THROW_ON_ERROR kullanmak, hata kontrolünü unutma riskini ortadan kaldırdığı için iyi bir varsayılandır.

Kodlama hataları: bozuk UTF-8, NAN ve döngüsel yapı

json_encode() da başarısız olabilir. En yaygın neden, UTF-8 olmayan metindir; örneğin eski bir veritabanından ya da dosyadan Latin-5 kodlamayla gelen veri. Kılavuz bu durumlar için iki bayrak sunar: JSON_INVALID_UTF8_SUBSTITUTE geçersiz baytları Unicode yer değiştirme karakteriyle (U+FFFD) değiştirir, JSON_INVALID_UTF8_IGNORE ise onları atar.

<?php
$bozukUtf8 = "Fiyat: 10 \xB1 2";

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

echo json_encode(['m' => $bozukUtf8], JSON_INVALID_UTF8_SUBSTITUTE), "\n";
echo json_encode(['m' => $bozukUtf8], JSON_INVALID_UTF8_IGNORE), "\n";

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

bool(false)
Malformed UTF-8 characters, possibly incorrectly encoded
{"m":"Fiyat: 10 \ufffd 2"}
{"m":"Fiyat: 10  2"}
JsonException: Inf and NaN cannot be JSON encoded

Bu bayraklar sorunu gizler, çözmez: veri kaybı yaşarsınız. Asıl çözüm metni kaynağında UTF-8'e çevirmektir; PHP'de UTF-8 metinlerle çalışmanın genel kuralları için PHP mbstring ve UTF-8 yazısına bakabilirsiniz. Örneğin son satırı ise NAN ve INF değerlerinin JSON'da karşılığı olmadığını gösteriyor. Bir dizi kendini referansla içeriyorsa da kodlama "Recursion detected" hatasıyla başarısız olur. JSON_PARTIAL_OUTPUT_ON_ERROR bayrağı bu tür değerlerin yerine null veya 0 yazarak kısmi çıktı üretir; kılavuza göre bu bayrak JSON_THROW_ON_ERROR bayrağından önceliklidir.

İç içe yapılar ve depth parametresi

Hem json_encode() hem json_decode() bir azami derinlik parametresi alır ve varsayılanı 512'dir. Derinlik, iç içe dizi ve nesne düzeylerinin sayısıdır; en dıştaki yapı da bir düzey sayılır. Verinin derinliği sınırı aşarsa çözme başarısız olur ve "Maximum stack depth exceeded" hatası alınır. Kılavuza göre json_decode() için geçersiz bir derinlik (sıfır ya da 2147483647'den büyük) verildiğinde PHP 8.0'dan beri ValueError fırlatılır.

<?php
$json = json_encode(['a' => ['b' => ['c' => 1]]]);
echo $json, "\n";                                   // çıktı: {"a":{"b":{"c":1}}}

var_dump(json_decode($json, true, 3));              // çıktı: NULL
echo json_last_error_msg(), "\n";                   // çıktı: Maximum stack depth exceeded
var_dump(json_decode($json, true, 4) !== null);     // çıktı: bool(true)

try {
    json_decode($json, true, 0);
} catch (ValueError $e) {
    echo $e->getMessage(), "\n";
}

{"a":{"b":{"c":1}}}
NULL
Maximum stack depth exceeded
bool(true)
json_decode(): Argument #3 ($depth) must be greater than 0

Örnekteki JSON üç nesne düzeyi ve bir skaler değerden oluşuyor; derinlik 3 ile çözülemedi, 4 ile çözüldü. Dışarıdan gelen veride derinliği bilinçli olarak düşük tutmak, beklenmedik biçimde iç içe geçmiş büyük verilerin işlenmesini baştan reddetmenin basit bir yoludur.

json_validate: yalnızca geçerlilik kontrolü (PHP 8.3)

Bazen veriyi kullanmayacak, sadece geçerli JSON olup olmadığını bilmek isteyeceksiniz; örneğin bir kuyruğa yazmadan önce. PHP 8.3 ile gelen json_validate() bu iş içindir. Kılavuza göre çözülmüş yapıyı oluşturmadığı için, sonuç kullanılmayacaksa json_decode() fonksiyonundan daha az bellek harcar.

<?php
var_dump(json_validate('{"siparis": 42, "durum": "hazır"}'));  // çıktı: bool(true)
var_dump(json_validate('{"siparis": 42,}'));                    // çıktı: bool(false)
echo json_last_error_msg(), "\n";                               // çıktı: Syntax error

Kılavuz önemli bir uyarı da yapar: json_validate() fonksiyonunu hemen ardından json_decode() çağıracağınız bir yerde kullanmak metni gereksiz yere iki kez ayrıştırır, çünkü json_decode() zaten ayrıştırırken doğrulama yapar. Veriyi kullanacaksanız doğrudan JSON_THROW_ON_ERROR ile çözün. json_validate() şu an bayrak olarak yalnızca JSON_INVALID_UTF8_IGNORE kabul eder ve başarısız olduğunda nedeni json_last_error_msg() ile okunur.

Nesneler, enum'lar ve JsonSerializable

Bir nesneyi doğrudan kodladığınızda varsayılan olarak yalnızca public özellikleri çıktıya girer; protected ve private özellikler atlanır. Bu kural, gizli kalması gereken alanların yanlışlıkla dışarı çıkmasını önler ama çıktının biçimini de sınıfın iç yapısına bağlar.

<?php
class Urun
{
    public string $ad = 'Kalem';
    protected int $maliyet = 3;
    private int $stok = 12;
}

echo json_encode(new Urun()), "\n";   // çıktı: {"ad":"Kalem"}

$json = '{"id": 12345678901234567890}';
var_dump(json_decode($json, true));
var_dump(json_decode($json, true, 512, JSON_BIGINT_AS_STRING));

{"ad":"Kalem"}
array(1) {
  ["id"]=>
  float(1.2345678901234567E+19)
}
array(1) {
  ["id"]=>
  string(20) "12345678901234567890"
}

Çıktının ikinci kısmı ayrı bir tuzağı gösteriyor: PHP'nin tamsayı sınırını (PHP_INT_MAX) aşan bir sayı varsayılan olarak float değerine dönüşür ve hassasiyet kaybolur. Sipariş veya kullanıcı kimliği gibi büyük sayılar taşıyan JSON'larda JSON_BIGINT_AS_STRING bayrağı sayıyı orijinal metin olarak korur.

Çıktının biçimini kendiniz belirlemek için sınıfa JsonSerializable arayüzünü uygulatırsınız. Tek metodu olan jsonSerialize(), kaynak türü dışında json_encode() tarafından kodlanabilen herhangi bir değer döndürebilir; json_encode() nesne yerine bu değeri kodlar.

<?php
enum Durum: string
{
    case Hazir = 'hazir';
    case Kargoda = 'kargoda';
}

final class Siparis implements JsonSerializable
{
    public function __construct(
        public int $no,
        private string $musteriEposta,
        public Durum $durum,
        public DateTimeImmutable $tarih,
    ) {}

    public function jsonSerialize(): array
    {
        return [
            'no'    => $this->no,
            'durum' => $this->durum,
            'tarih' => $this->tarih->format(DATE_ATOM),
        ];
    }
}

$s = new Siparis(42, 'ali@example.com', Durum::Kargoda, new DateTimeImmutable('2026-11-07 10:30:00', new DateTimeZone('Europe/Istanbul')));
echo json_encode($s), "\n";

{"no":42,"durum":"kargoda","tarih":"2026-11-07T10:30:00+03:00"}

Bu örnekte e-posta adresi çıktıya hiç girmedi, tarih ISO 8601 biçiminde yazıldı ve Durum enum'u doğrudan döndürüldüğü halde metin değeri "kargoda" olarak kodlandı. Değer taşıyan (backed) enum'lar JSON'a değerleriyle yazılır. Değer taşımayan (pure) enum'larda ise durum farklıdır:

<?php
enum Renk
{
    case Kirmizi;
}

var_dump(json_encode(['renk' => Renk::Kirmizi]));
echo json_last_error(), ' ', json_last_error_msg(), "\n";

echo json_encode(new DateTimeImmutable('2026-11-07 10:30:00', new DateTimeZone('Europe/Istanbul'))), "\n";
echo json_encode(0.1 + 0.2), "\n";   // çıktı: 0.30000000000000004

bool(false)
11 Non-backed enums have no default serialization
{"date":"2026-11-07 10:30:00.000000","timezone_type":3,"timezone":"Europe\/Istanbul"}
0.30000000000000004

Saf enum kodlanamaz ve PHP 8.1 ile eklenen JSON_ERROR_NON_BACKED_ENUM (11) hatası oluşur. DateTimeImmutable nesnesi ise iç alanlarıyla (date, timezone_type, timezone) kodlanır; bu biçim çoğu istemci için kullanışlı olmadığından tarihi format() ile metne çevirmek daha doğrudur. Ondalık sayıların yazımı da serialize_precision ayarına bağlıdır, bu yüzden 0.1 + 0.2 tam olarak 0.30000000000000004 biçiminde görünür. Enum'lar için PHP enum kullanımı, tarih biçimleri için PHP DateTime ve tarih işlemleri yazılarına bakabilirsiniz.

Bayraklar özet tablosu

JSON_NUMERIC_CHECK bayrağına dikkat edin: telefon numarası veya posta kodu gibi sayı görünümlü ama metin kalması gereken değerleri de sayıya çevirir ve baştaki sıfırlar kaybolur:

<?php
echo json_encode(['tel' => '05321234567', 'pk' => '06100'], JSON_NUMERIC_CHECK), "\n";
// çıktı: {"tel":5321234567,"pk":6100}

var_dump(json_decode('{bozuk', JSON_THROW_ON_ERROR)); // çıktı: NULL (istisna yok!)

Bu yüzden bu bayrak genel amaçlı bir varsayılan olarak kullanılmamalıdır; sayısal alanları kodlamadan önce kendiniz (int) veya (float) ile dönüştürmek daha güvenlidir. Aynı şekilde json_decode() tarafında da yanlış yere yazılan bir bayrak sessizce yanlış çalışabilir: bayraklar dördüncü parametredir ve ikinci parametreye yazılan JSON_THROW_ON_ERROR istisna fırlatmaz, yalnızca dizi biçimini açar.

Sık yapılan hatalar

• Hata kontrolü yapmamak. json_decode() dönüşünün null olması hem hata hem geçerli null anlamına gelebilir; JSON_THROW_ON_ERROR kullanın.
• Tek tırnaklı veya sondaki virgüllü JSON yazmak. JavaScript nesne sözdizimi JSON değildir.
• unset() sonrası diziyi doğrudan kodlamak. Anahtarlar kesintili kalırsa çıktı nesneye dönüşür; önce array_values().
• Türkçe karakterlerin bozulduğunu sanmak. \u015f gibi kaçışlar geçerlidir; okunur çıktı için JSON_UNESCAPED_UNICODE verin.
• json_decode() çağrısında bayrağı yanlış yere yazmak. Bayraklar dördüncü parametredir; json_decode($j, JSON_THROW_ON_ERROR) yazarsanız bayrak associative parametresine gider.
• json_validate() ardından json_decode() çağırmak. Metin iki kez ayrıştırılır; yalnızca json_decode() yeterlidir.

Sık Sorulan Sorular

JSON'da Türkçe karakterler neden \u015f gibi görünüyor?

json_encode() varsayılan olarak ASCII dışındaki karakterleri Unicode kaçış dizileriyle yazar. Bu geçerli JSON'dur ve okuyan taraf doğru karakteri elde eder. Metnin okunur kalmasını istiyorsanız JSON_UNESCAPED_UNICODE bayrağını ekleyin.

stdClass mı dizi mi kullanmalıyım?

İkisi de çalışır. Dizi biçimi PHP'nin dizi fonksiyonlarıyla doğrudan kullanılabildiği için genellikle daha pratiktir; nesne biçiminde tire veya boşluk içeren anahtarlara {'...'} sözdizimiyle erişmeniz gerekir. Büyük projelerde veriyi kendi sınıflarınıza aktarmak tip güvenliği sağlar.

JSON verisini veritabanına nasıl kaydederim?

JSON bir metindir; json_encode() çıktısını parametreli bir sorguyla bir metin sütununa yazabilirsiniz. Parametreli sorgu yazmanın kuralları PHP PDO veritabanı bağlantısı yazısında anlatılıyor.

JSON dosyasını nasıl okurum?

file_get_contents() ile metni okuyup json_decode($metin, true, 512, JSON_THROW_ON_ERROR) ile çözebilirsiniz. Yazarken de file_put_contents() kullanılır; ayrıntılar PHP dosya okuma ve yazma yazısında.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: PHP öğrenme rehberi · PHP dizi temelleri · PHP enum kullanımı · PHP try/catch · PHP dosya okuma ve yazma