خطأ stdClass كمصفوفة: فخ PHP ستتجاوزه بسهولة

تكتب الكود وفجأة يصرخ PHP: «لا تتعامل معي كمصفوفة!»

تخيل الموقف: استلمت بيانات من API. كل شيء جميل، تم تحليل JSON بنجاح، وأنت متأكد أن لديك مصفوفة. تصل إلى عنصر باستخدام المفتاح — وبدلاً من النتيجة ترى Fatal error: Cannot use object of type stdClass as array. هل هذا مألوف؟ هذا الخطأ من أكثر الفخاخ شيوعاً للمبتدئين (وحتى المحترفين) في PHP. تمت مناقشته آلاف المرات على Stack Overflow. اليوم لن نشرح فقط سبب حدوثه، بل سنقارن 5 طرق لتجاوزه أو منعه. ستعرف أي طريقة تناسب مهمتك، وستنسى إلى الأبد الذعر عند رؤية stdClass.

هذه المقالة لمن يكتبون بلغة PHP، ويعملون مع JSON أو REST API أو قواعد البيانات. نقدم الشرح بالعربية مع أمثلة كود حية. هيا بنا!

لماذا يحدث الخطأ؟ جذر المشكلة — stdClass

في PHP يوجد كلاس مدمج اسمه stdClass (standard class). يُستخدم ككائن «فارغ» عندما تستدعي، مثلاً، json_decode() بدون المعامل الثاني. افتراضياً، json_decode يُرجع كائن وليس مصفوفة. وعند محاولة الوصول لخاصيته باستخدام الأقواس المربعة — يغضب PHP.

<?php\n$json = '{"name": "آمنة", "age": 25}';\n$data = json_decode($json); // يُرجع كائن stdClass\necho $data['name']; // Fatal error: Cannot use object of type stdClass as array\n?>\n

الكائن والمصفوفة في PHP نوعان مختلفان. الوصول لخصائص الكائن يكون عبر ->، وللمصفوفة عبر []. لا يمكن خلطهما. لكن ماذا تفعل إذا كنت لا تتحكم بمصدر البيانات؟ أو إذا كان الكود القديم (legacy) يعتمد كلياً على المصفوفات؟ لنكتشف الحلول.

الطريقة 1: تحويل النوع (array) — سريع ولكن بمفاجآت

أبسط طريقة — تحويل الكائن إلى مصفوفة صراحة باستخدام (array). سيعمل هذا، لكن ليس دائماً كما تتوقع.

<?php\n$json = '{"name": "آمنة", "age": 25}';\n$data = (array) json_decode($json);\necho $data['name']; // آمنة — يعمل!\n?>\n

هل كل شيء على ما يرام؟ ليس تماماً. إذا كان الكائن يحتوي على كائنات متداخلة، فإنها لا تتحول تلقائياً. ستبقى stdClass داخلياً، وعند محاولة الوصول إليها كمصفوفة سيعود الخطأ.

<?php\n$json = '{"user": {"name": "آمنة", "age": 25}}';\n$data = (array) json_decode($json);\necho $data['user']['name']; // خطأ مرة أخرى! user لا يزال كائن\n?>\n

متى تستخدمها: لهياكل JSON بسيطة (غير متداخلة). سريعة ولكنها سطحية.

الطريقة 2: json_decode مع true — المعيار الذهبي

الطريقة الأكثر شيوعاً وموثوقية — تمرير true كمعامل ثانٍ لـ json_decode. عندها سترجع الدالة مصفوفة ترابطية (associative array) بدلاً من كائن. والهياكل المتداخلة ستكون مصفوفات أيضاً.

<?php\n$json = '{"user": {"name": "آمنة", "age": 25}}';\n$data = json_decode($json, true); // true — إرجاع مصفوفة\necho $data['user']['name']; // آمنة — بدون أخطاء\n?>\n

هذه الطريقة — الموصى بها في توثيق PHP وفي المجتمع. تحل المشكلة من جذورها دون الحاجة لتحويلات إضافية.

متى تستخدمها: دائماً عندما تعمل مع JSON وتتوقع مصفوفة. العيب الوحيد — إذا نسيت وضع true.

الطريقة 3: التحويل التكراري — للهياكل المعقدة

أحياناً تأتي البيانات ليس فقط من JSON، بل من مصادر أخرى: قواعد البيانات، SOAP، محللات XML. وتحصل على كائن جاهز تحتاج لتحويله إلى مصفوفة بأي ثمن. هنا تأتي فائدة الدالة التكرارية.

<?php\nfunction objectToArray($data) {\n    if (is_object($data)) {\n        $data = get_object_vars($data);\n    }\n    if (is_array($data)) {\n