Lorixen.
AR

env() تعيد null على الخادم في Laravel: ذاكرة الإعدادات المؤقتة

باختصار: إذا كان نظامك المبني بـ Laravel يعمل جيداً على جهاز المطور، ثم توقف على الخادم الحي جزء معين فقط، مثل إرسال الرسائل أو الربط مع بوابة الدفع أو مفتاح خدمة خارجية، وتبين أن قيمة من ملف .env تصل فارغة، فالسبب الشائع أن الكود يستدعي الدالة env مباشرة خارج ملفات الإعداد، بينما الخادم يستخدم ذاكرة الإعدادات المؤقتة. توثيق Laravel يقول صراحة إنه بعد تخزين الإعدادات مؤقتاً لا يُحمّل ملف .env أثناء الطلبات أو أوامر Artisan، فتعيد env فقط متغيرات البيئة الخارجية على مستوى النظام. الحل: استدعِ env داخل ملفات config فقط، واقرأ القيم في بقية الكود عبر الدالة config.

موقف يتكرر بعد النشر

شركة تأجير سيارات في عمّان لديها نظام حجوزات بـ Laravel. أضاف مطور مستقل ميزة جديدة: إرسال رسالة تأكيد عبر مزود رسائل نصية، ووضع مفتاح المزود في ملف .env. على جهازه أُرسلت الرسائل بلا مشكلة. بعد النشر، توقفت الرسائل، وكل شيء آخر يعمل: الحجوزات، والدفع، ولوحة الإدارة.

بعد ساعات من البحث، اكتشف المطور أن المفتاح يصل إلى الكود فارغاً على الخادم، مع أنه موجود في ملف .env هناك. هذا مثال توضيحي لحالة شائعة، وغالباً ما يُتهم مزود الرسائل أو الاستضافة قبل أن يُكتشف السبب الحقيقي.

كيف يتعامل Laravel مع ملف .env؟

توثيق الإعدادات في Laravel يشرح أن ملف .env يحتوي قيماً قد تختلف بين التشغيل المحلي وخادم الإنتاج، وأن هذه القيم تقرؤها ملفات الإعداد داخل مجلد config باستخدام الدالة env.

إذن التصميم المقصود في Laravel هو طبقتان:

  1. ملف .env يحمل القيم الخاصة بكل بيئة.
  2. ملفات config تقرأ هذه القيم بالدالة env، وتعطيها أسماء منظمة.
  3. بقية التطبيق تقرأ القيم من ملفات config بالدالة config.

ماذا يفعل تخزين الإعدادات مؤقتاً؟

التوثيق يوصي بأمر config:cache لتسريع التطبيق: يجمع كل خيارات الإعداد في ملف واحد يُحمّل بسرعة، ويقول إنه يجب تشغيله عادة كجزء من عملية النشر للإنتاج. ويضيف أنه لا يجب تشغيله أثناء التطوير المحلي، لأن الإعدادات تتغير كثيراً أثناء التطوير.

ثم تأتي الجملة التي تفسر المشكلة: بعد تخزين الإعدادات مؤقتاً، لا يُحمّل ملف .env أثناء الطلبات أو أوامر Artisan، وبالتالي تعيد الدالة env فقط متغيرات البيئة الخارجية على مستوى النظام. ولهذا السبب، يقول التوثيق، يجب التأكد من استدعاء env فقط من داخل ملفات الإعداد.

هذا يفسر لماذا تعمل الميزة على جهاز المطور ولا تعمل على الخادم: على جهازه لا يوجد تخزين مؤقت، فيُقرأ ملف .env في كل طلب. على الخادم، الإعدادات مخزنة، والكود الجديد الذي يستدعي env مباشرة لا يجد شيئاً.

الإصلاح الصحيح

بدلاً من أن يقرأ كود إرسال الرسائل المفتاح مباشرة من env، يُضاف المفتاح إلى ملف إعداد، مثل ملف الخدمات الخارجية في مجلد config، بالدالة env هناك. ثم يقرأ كود الإرسال القيمة بالدالة config. التوثيق يذكر أن قيم الإعداد يمكن الوصول إليها من أي مكان في التطبيق باستخدام الدالة config.

بعد التعديل، يُعاد تشغيل أمر تخزين الإعدادات على الخادم، فيدخل المفتاح الجديد ضمن الملف المخزن.

كيف يعثر المطور على الاستدعاءات المخالفة؟

إذا كان المشروع قديماً أو تناوب عليه أكثر من مطور، فقد تكون هناك استدعاءات env متفرقة في الكود. خطوة مراجعة بسيطة:

  • البحث في المشروع عن كل استدعاء للدالة env خارج مجلد config.
  • لكل استدعاء، نقل القيمة إلى ملف الإعداد المناسب، وإعطاؤها اسماً واضحاً.
  • استبدال الاستدعاء بالدالة config.
  • التأكد أن ملف .env.example يحتوي اسم المتغير بقيمة شكلية.

التوثيق نفسه يقول إنه يمكن رؤية أمثلة كثيرة على الاستخدام الصحيح في ملفات الإعداد الافتراضية لـ Laravel، فهي مرجع جيد للمطور الجديد.

حل مؤقت ليس حلاً

قد يقترح أحدهم تنفيذ config:clear على الخادم. التوثيق يذكر هذا الأمر لمسح الإعدادات المخزنة. بعد مسحها، يعود ملف .env ليُقرأ، فتعمل الميزة.

لكن هذا يُخفي المشكلة فقط. في النشر القادم، إذا أُعيد تخزين الإعدادات كما يوصي التوثيق، ستتوقف الميزة مجدداً. والأسوأ أن الفريق قد يقرر عدم استخدام التخزين المؤقت كلياً، فيخسر التطبيق تحسين الأداء. الإصلاح الحقيقي نقل استدعاء env إلى ملف الإعداد.

خطأ مشابه: تغيير .env دون إعادة التخزين

الحالة المعاكسة شائعة أيضاً: غيّر أحدهم قيمة في ملف .env على الخادم، مثل كلمة مرور البريد بعد تجديدها، ولم يحدث شيء. السبب نفسه: الإعدادات مخزنة، وملف .env لا يُقرأ. بعد أي تعديل على .env في الإنتاج، يجب إعادة تخزين الإعدادات حتى تأخذ القيم الجديدة مكانها.

اكتب هذه الخطوة في قائمة النشر:

  1. عدّل .env على الخادم.
  2. أعد تشغيل أمر تخزين الإعدادات.
  3. إذا كان لديكم عمال طوابير، أعد تشغيلهم أيضاً، لأنهم عمليات تعمل باستمرار وقد تحتفظ بالإعدادات القديمة.
  4. اختبر الميزة المتأثرة.

متغيرات البيئة على مستوى الخادم

التوثيق يذكر أن أي متغير في ملف .env يمكن أن تتجاوزه متغيرات بيئة خارجية على مستوى الخادم أو النظام. إذا كان مزود الاستضافة أو أداة النشر يضبط متغيرات بيئة من لوحة التحكم، فقد تختلف القيمة الفعلية عما في الملف. عند التشخيص، اسأل: هل هناك متغيرات بيئة مضبوطة خارج ملف .env؟

انتبه لأنواع القيم

نقطة أخيرة تسبب أخطاء صغيرة: التوثيق يذكر أن كل المتغيرات في ملف .env تُقرأ عادة كنصوص، وأن Laravel يحوّل بعض القيم المحجوزة إلى أنواعها، مثل true وfalse إلى قيم منطقية، وnull إلى قيمة فارغة، وempty إلى نص فارغ. ويذكر أن القيمة التي تحتوي مسافات توضع بين علامتي تنصيص. لذلك اكتب اسم الشركة أو رسالة الترحيب بين علامتي تنصيص إذا احتوت مسافات.

لا ترفع ملف .env إلى المستودع

بينما تراجع هذا الأمر، تأكد من نقطة أمان يذكرها التوثيق: لا يجب إضافة ملف .env إلى نظام التحكم بالإصدارات، لأن كل مطور وكل خادم قد يحتاج إعدادات مختلفة، ولأن ذلك خطر أمني إذا وصل متسلل إلى المستودع، فتنكشف كل البيانات الحساسة. ويقترح التوثيق الاحتفاظ بملف .env.example بقيم شكلية، كي يرى الفريق المتغيرات المطلوبة.

أسئلة شائعة

ليش env() بترجع null على السيرفر وعلى جهازي شغالة؟

لأن الخادم يخزن الإعدادات مؤقتاً، وبحسب توثيق Laravel لا يُقرأ ملف .env بعد التخزين، فتعيد env متغيرات النظام فقط.

شو الحل الصحيح؟

استدعِ env داخل ملفات config فقط، واقرأ القيم في الكود بالدالة config، ثم أعد تخزين الإعدادات.

غيرت قيمة بملف .env وما تغير إشي، ليش؟

لأن الإعدادات مخزنة. أعد تشغيل أمر تخزين الإعدادات بعد كل تعديل على .env في الإنتاج.

هل أوقف config:cache وأريّح حالي؟

لا. التوثيق يوصي به في النشر للإنتاج لتسريع التطبيق. أصلح مكان استدعاء env بدلاً من ذلك.

إذا توقفت ميزة في نظامك بعد النشر دون سبب واضح، راسلنا ونتتبع الإعدادات معك.

المصادر

WhatsAppاحجز مكالمة