الدالة 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 فواصل أسطر وإزاحة بأربع مسافات، وهذا ما تريده في ملف إعدادات أو سجل تصحيح. واجمع عدة أعلام بـ |:

<?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 على شكل تسلسل هروب \u وتضع شرطة مائلة عكسية قبل كل /. وكلاهما JSON صالح ويُفك إلى النص نفسه، لكنهما يجعلان المخرجات صعبة القراءة وأطول. يحتفظ JSON_UNESCAPED_UNICODE بالمحارف، ويحتفظ JSON_UNESCAPED_SLASHES بالروابط كما هي:

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

إذا بدا النص الياباني مشوهًا (文字化け) بعد فك الترميز، فالمشكلة ليست في تسلسلات الهروب: النص لم يكن 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"
}

يُرمَّز التعداد المدعوم مثل enum Status: string على شكل قيمته ("active"). أما التعداد الخالص فليست له قيمة، فتفشل json_encode() معه برسالة "Non-backed enums have no default serialization".

الأعداد والأعداد العشرية والنصوص الرقمية

تُكتب الأعداد الصحيحة والعشرية أعدادَ 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) والقيمتان العشريتان 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 من واجهة 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. يحوّل تهريب الشرطة المائلة الافتراضي </script> إلى <\/script>، لكن تلك الحماية تختفي حالما يضيف أحدهم JSON_UNESCAPED_SLASHES، وما زال <!-- في قيمة ما يغيّر طريقة تحليل المتصفح للسكربت. تكتب الأعلام < و> و& و' و" على شكل \u003C و\u003E و\u0026 و\u0027 و\u0022، التي يقرؤها JavaScript مرة أخرى المحارف نفسها.