json_encode() ב-PHP: המרת מערכים ואובייקטים ל-JSON

json_encode($value) מחזירה את טקסט ה-JSON של ערך PHP. מערך אסוציאטיבי הופך לאובייקט JSON, רשימה (המפתחות 0, 1, 2...) הופכת למערך JSON, ומחרוזות, מספרים, true, false ו-null הופכים למקבילים שלהם ב-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";

פלט:

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

התוצאה היא מחרוזת רגילה, מוכנה לשליחה לדפדפן, לשמירה בקובץ או בעמודה של מסד נתונים, או להעברה לתוכנית אחרת. כדי להפוך JSON בחזרה ל-PHP, השתמשו ב-json_decode().

הדפסת JSON מעוצב

json_encode() מקבלת דגלים כארגומנט השני. JSON_PRETTY_PRINT מוסיף ירידות שורה והזחה של 4 רווחים, וזה מה שרוצים בקובץ הגדרות או בלוג דיבאג. שלבו כמה דגלים עם |:

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

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

פלט:

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

שמירה על טקסט יפני וטקסט UTF-8 אחר קריא

כברירת מחדל json_encode() כותבת כל תו שאינו ASCII כ-escape בצורת \u ושמה לוכסן הפוך לפני כל /. שניהם JSON תקין ומפוענחים בחזרה לאותו טקסט, אבל הם הופכים את הפלט לקשה לקריאה וארוך יותר. JSON_UNESCAPED_UNICODE שומר על התווים, ו-JSON_UNESCAPED_SLASHES שומר על כתובות URL כמו שהן:

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

פלט:

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

אם טקסט יפני נראה משובש (文字化け) אחרי הפענוח, הבעיה היא לא ה-escapes: המחרוזת לא הייתה UTF-8 מלכתחילה. json_encode() מקבלת רק UTF-8 ומחזירה false לכל דבר אחר, כפי שמוצג בסעיף על שגיאות.

כשמערך הופך לאובייקט במקום לרשימה

מערך PHP מקודד כמערך JSON רק כשהמפתחות שלו הם בדיוק 0, 1, 2... לפי הסדר. כל מפתחות אחרים הופכים אותו לאובייקט JSON. זה תופס אנשים אחרי unset() או array_filter(), שמשאירות פערים במפתחות:

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

פלט:

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

קראו ל-array_values() לפני הקידוד בכל פעם שהקוד המקבל מצפה לרשימה. אם הוא מצפה לאובייקט שעשוי להיות ריק, השתמשו ב-new stdClass() או ב-(object) $array כדי שערך ריק עדיין ייצא כ-{}.

קידוד אובייקט ושליטה ב-JSON שלו עם JsonSerializable

אובייקט רגיל מקודד רק עם המאפיינים הציבוריים שלו; מאפיינים מוגנים ופרטיים מדולגים. כדי להחליט בדיוק איך אובייקט נראה ב-JSON, ממשו את הממשק JsonSerializable והחזירו את הנתונים מ-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";

פלט:

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

backed enum כמו enum Status: string מקודד כערך שלו ("active"). ל-enum טהור אין ערך, ולכן json_encode() נכשלת עליו עם "Non-backed enums have no default serialization".

מספרים, floats ומחרוזות מספריות

מספרים שלמים ו-floats נכתבים כמספרי JSON, ומחרוזות נשארות מחרוזות גם כשהן מכילות ספרות. שלושה דגלים משנים את זה:

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

פלט:

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

JSON_NUMERIC_CHECK ממיר כל מחרוזת מספרית, ולכן מזהה כמו "007" או מיקוד כמו "01234" מאבד את האפסים המובילים שלו. המירו את השדות שאתם מתכוונים אליהם עם (int) במקום להשתמש בו על מערך שלם.

json_encode מחזירה false: איך מוצאים את השגיאה

json_encode() מחזירה false כשהיא לא יכולה לקודד את הערך. הסיבות הרגילות הן מחרוזת שאינה UTF-8 תקין (טקסט שנקרא מקובץ ישן או ממסד נתונים ב-Latin-1) וערכי ה-float NAN ו-INF. json_last_error_msg() אומרת מה השתבש; JSON_THROW_ON_ERROR גורם לה לזרוק 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";
}

פלט:

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 היא ברירת המחדל הטובה יותר בקוד חדש: false שאף אחד לא בודק מגיע בסוף לאחסון או לשליחה כמחרוזת ריקה.

החזרת JSON מ-API ב-PHP

סקריפט PHP שעונה ב-JSON מגדיר את הכותרת Content-Type לפני שהוא מדפיס משהו, מקודד פעם אחת, ועוצר:

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

כשמדפיסים JSON בתוך תגית HTML <script>, הוסיפו JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT. ה-escape של הלוכסן כברירת מחדל הופך את </script> ל-<\/script>, אבל ההגנה הזו נעלמת ברגע שמישהו מוסיף JSON_UNESCAPED_SLASHES, ו-<!-- בתוך ערך עדיין משנה את האופן שבו הדפדפן מפענח את הסקריפט. הדגלים כותבים את <, >, &, ' ו-" כ-\u003C, \u003E, \u0026, \u0027 ו-\u0022, ש-JavaScript קוראת בחזרה כאותם תווים.