تنسيق JSON في PHP: دليل شامل للمبتدئين

مقدمة: لماذا يبدو JSON في PHP وكأنه فوضى؟

تخيل الموقف: لقد كتبت سكربت PHP يحصل على بيانات من API أو يُنشئ ردًا للواجهة الأمامية. تقوم بعرض النتيجة باستخدام echo json_encode($data) — وتحصل في المتصفح أو الطرفية على شيء كهذا:

{"users":[{"id":1,"name":"أحمد","email":"ahmed@example.com"},{"id":2,"name":"مريم","email":"mariam@example.com"}]}

أتفق معي، قراءة هذا السطر بدون تنسيق أشبه بمحاولة فك خط طبيب! خاصةً إذا كانت البيانات كثيرة والتداخل عميق. هنا يأتي دور طباعة JSON بشكل منسق في PHP.

هذه المقالة موجهة لمن بدأوا للتو في العمل مع PHP وJSON. سنشرح كيفية جعل مخرجات JSON جميلة، قابلة للقراءة، وسهلة التصحيح. ستتعلم ليس فقط الطرق الأساسية، بل أيضًا حيلًا مفيدة ستوفر عليك ساعات من الإحباط. هيا بنا!

ما هي الطباعة الجميلة (pretty-print) ولماذا نحتاجها؟

Pretty-print (حرفيًا: "طباعة جميلة") — هي تنسيق البيانات باستخدام مسافات بادئة، فواصل أسطر، ومحاذاة. في حالة JSON، يعني ذلك أنه بدلاً من سطر طويل واحد، ستحصل على مخرجات منظمة حيث يكون كل مفتاح وقيمة في مكانهما الصحيح.

تخيل أنك تتصحح طلب API أو تتحقق من ملف إعدادات. بدون pretty-print، ستضيع وقتًا طويلاً في محاولة فهم أين ينتهي كائن وأين يبدأ آخر. مع التنسيق، كل شيء واضح كالشمس.

في PHP، هناك عدة طرق للحصول على مخرجات JSON جميلة. سنبدأ بالأسهل والأكثر شيوعًا — استخدام العلم JSON_PRETTY_PRINT.

الطريقة 1: JSON_PRETTY_PRINT — صديقك المفضل

أسهل طريقة لطباعة JSON بشكل منسق في PHP هي استخدام الثابت JSON_PRETTY_PRINT عند استدعاء الدالة json_encode(). هذا الثابت متاح منذ PHP 5.4.0.

مثال أساسي

<?php\n$data = [\n    'users' => [\n        ['id' => 1, 'name' => 'أحمد', 'email' => 'ahmed@example.com'],\n        ['id' => 2, 'name' => 'مريم', 'email' => 'mariam@example.com']\n    ]\n];\n\n$json = json_encode($data, JSON_PRETTY_PRINT);\necho $json;\n?>

النتيجة:

{\n    "users": [\n        {\n            "id": 1,\n            "name": "أحمد",\n            "email": "ahmed@example.com"\n        },\n        {\n            "id": 2,\n            "name": "مريم",\n            "email": "mariam@example.com"\n        }\n    ]\n}

أفضل بكثير، أليس كذلك؟ كل عنصر من المصفوفة الآن في سطر منفصل، المسافات البادئة مرتبة، والهيكل قابل للقراءة بشكل بديهي.

الدمج مع أعلام أخرى

يمكن ويجب دمج JSON_PRETTY_PRINT مع أعلام أخرى للحصول على تحكم أدق. على سبيل المثال:

\n
• JSON_UNESCAPED_UNICODE — لا يقوم بتشفير الأحرف العربية وغيرها من أحرف Unicode (بدلاً من \\u0623\\u062d\\u0645\\u062f سترى أحمد).
\n
• JSON_UNESCAPED_SLASHES — لا يقوم بتشفير الخطوط المائلة (مفيد لعناوين URL).
\n
• JSON_NUMERIC_CHECK — يحول السلاسل النصية التي تحتوي على أرقام إلى نوع رقمي.
\n

<?php\n$data = [\n    'message' => 'مرحبًا بالعالم!',\n    'url' => 'https://example.com/api/v1/users'\n];\n\n$json = json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);\necho $json;\n?>

النتيجة:

{\n    "message": "مرحبًا بالعالم!",\n    "url": "https://example.com/api/v1/users"\n}

لاحظ: الأحرف العربية تظهر بشكل طبيعي، والخطوط المائلة غير مشفرة. هكذا يجب أن يكون مخرجات JSON المخصصة للبشر.

الطريقة 2: تنسيق سلسلة JSON موجودة مسبقًا

ماذا لو كان لديك سلسلة JSON موجودة بالفعل (مثلًا، تم الحصول عليها من ملف أو قاعدة بيانات)، وتريد تنسيقها؟