Laravel/configuration

المقدمة

جميع ملفات الضبط الخاصة بإطار عمل Laravel موجودة في المسار config. وجميع الخيارات موثّقة، لذا لا تتردد في النظر في ملفات Laravel والتعرف على جميع الخيارات المتاحة لك.

ضبط البيئة

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

للقيام بهكذا أمر، يستخدم Laravel مكتبة DotEnv PHP. عند تثبيت Laravel جديد، سيحتوي المجلد الجذر للتطبيق الخاص بك على ملف ‎env.example. إذا قمت بتثبيت Laravel باستخدام Composer، فستُعاد تسمية هذا الملف تلقائيًا إلى ‎.env. خلاف ذلك، يجب إعادة تسمية الملف يدويًا.

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

إذا كنت تقوم بالتطوير مع فريق، فقد ترغب في الاستمرار في تضمين الملف ‎.env.example مع التطبيق الخاص بك. من خلال وضع قيم بديلة وهمية في ملف تكوين المثال، يمكن لمطوري البرامج الآخرين في فريقك أن يروا بوضوح متغيرات البيئة المطلوبة لتشغيل التطبيق الخاص بك. يمكنك أيضًا إنشاء ملف ‎.env.testing. سيتجاوز هذا الملف ملف ‎.env عند تشغيل اختبارات PHPUnit أو تنفيذ الأمر Artisan باستخدام خيار env=testing--.

ملاحظة: يمكن تجاوز أي متغير في ملف env. الخاص بك بواسطة متغيرات البيئة الخارجية مثل متغيرات البيئة على مستوى الخادم أو مستوى النظام.

أنواع البيئة المتغيرة

تُحلَّل جميع المتغيرات في ملفات env. الخاصة بك كسلاسل نصية، لذلك أُنشِئَت بعض القيم المحجوزة للسماح لك بإعادة نطاق أوسع من الأنواع من الدالة env()‎:

قيمة ‎.env	قيمة env()‎
true	(bool) true
(true)	(bool) true
false	(bool) false
(false)	(bool) false
empty	(string) ''
(empty)	(string) ''
null	(null) null
(null)	(null) null

إذا كنت بحاجة إلى تعريف متغير بيئة بقيمة تحتوي على مسافات، فيمكنك القيام بذلك عن طريق إحاطة القيمة بعلامات اقتباس مزدوجة.

APP_NAME="My Application"

استرجاع ضبط البيئة

ستُحمَّل جميع المتغيرات المدرجة في هذا الملف في المتغير  العام $‎ _ENV عندما يتلقى مشروعك طلبًا. ومع ذلك، يمكنك استخدام المساعد env لاسترداد القيم من هذه المتغيرات في ملفات الضبط الخاصة بك. في الواقع، إذا قمت بمراجعة ملفات ضبط Laravel، ستلاحظ العديد من الخيارات التي تستخدم بالفعل هذا المتغير:

'debug' => env('APP_DEBUG', false),

القيمة الثانية التي مُرِّرَت إلى الدالة env هي "القيمة الافتراضية". سيتم استخدام هذه القيمة في حالة عدم وجود متغير بيئة للمفتاح المحدد.

تحديد البيئة الحالية

يتم تحديد بيئة التطبيق الحالية عبر المتغير APP_ENV من الملف ‎.env. يمكنك الوصول إلى هذه القيمة من خلال التابع environment على الواجهة الساكنة (facade)‏ App:

$environment = App::environment();

يمكنك أيضًا تمرير الوسائط إلى التابع environment للتحقق مما إذا كانت البيئة تتطابق مع قيمة معينة. سيُعيد هذا التابع القيمة true إذا كانت البيئة مطابقة لأي من القيم المعطاة:

if (App::environment('local')) {

   // بيئة التطوير المحلية

}

if (App::environment(['local', 'staging'])) {

// إما أن تكون البيئة هي بيئة التطوير أو بيئة الخادم التخزيني

}

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

الوصول إلى قيم الضبط

يمكنك الوصول إلى قيم الضبط بسهولة باستخدام الدالة المساعدة العامة config من أي مكان في التطبيق الخاص بك. يمكن الوصول إلى قيم الضبط باستخدام صيغة «النقطة» (dot syntax)، والتي تتضمن اسم الملف والخيار الذي ترغب في الوصول إليه. قد تُحدَّد قيمة افتراضية أيضًا، وستُعاد إذا لم يكن خيار الضبط موجودًا:

$ value = config ('app.timezone');

لتعيين قيم الضبط في وقت التشغيل، مرِّر مصفوفةً إلى الدالة المساعدة config:

config(['app.timezone' => 'America/Chicago']);

ضبط التخزين المؤقت

لإعطاء تطبيقك سرعة مضاعفة، يجب تخزين جميع ملفات التهيئة في ملف واحد باستخدام الأمر Artisan الآتي config: cache. سيؤدي هذا الأمر إلى دمج جميع خيارات الضبط لتطبيقك في ملف واحد والذي سيُحمَّل تحميله بسرعة بواسطة إطار العمل.

يجب أن تُعيد تشغيل الأمر php artisan config: cache كجزء من عملية نشر التطبيق الخاص بك على الخادم الإنتاجي. يجب ألا يُشغَّل الأمر أثناء التطوير المحلي إذ ستحتاج إلى تغيير خيارات الضبط بشكل متكرر أثناء تطوير التطبيق الخاص بك.

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

وضع الصيانة

عندما يكون التطبيق في وضع الصيانة، سيتم عرض واجهة مخصصة لجميع طلبات التطبيق. هذا يجعل من السهل "تعطيل" التطبيق الخاص بك أثناء تحديث أو عند إجراء الصيانة. يتم تضمين فحص وضع الصيانة في حزمة البرامج الوسيطة الافتراضية للتطبيق الخاص بك. إذا كان التطبيق في وضع الصيانة، سيرمى الاستثناء MaintenanceModeException مع رمز الحالة 503.

لتمكين وضع الصيانة، نفِّذ down من خلال الأمر Artisan:

php artisan down

يمكنك أيضًا توفير الخيارات message و retry إلى الأمر down. يمكن استخدام قيمة message لعرض أو تسجيل رسالة خاصة، بينما سيتم تعيين قيمة retry كقيمة Retry-After لترويسة HTTP:

php artisan down --message="Upgrading Database" --retry=60

حتى في حالة الصيانة، قد يتم السماح لعناوين IP أو شبكات محددة بالوصول إلى التطبيق باستخدام الخيار allow:

php artisan down --allow=127.0.0.1 --allow=192.168.0.0/16

لتعطيل وضع الصيانة، استخدم الأمر up:

php artisan up

ملاحظة: يمكنك تخصيص قالب وضع الصيانة الافتراضي عن طريق تعريف القالب الخاص بك في resources/views/errors/503.blade.php.

وضع الصيانة و الطوابير

بينما يكون التطبيق الخاص بك في وضع الصيانة، لن يتم التعامل مع أي مهمة في قائمة الانتظار. سيستمر التعامل مع المهام كالمعتاد بمجرد انتهاء التطبيق من وضع الصيانة.

البدائل لوضع الصيانة

نظرًا لأن وضع الصيانة يتطلب أن يحتوي  التطبيق على عدة ثوانٍ من وقت التوقف، ففكر في بدائل مثل Envoyer لإنجاز النشر بدون توقف مع Laravel.

مصادر

• صفحة Configuration في توثيق Laravel الرسمي.