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 على مستوى الخادوم. يمكن أن يكون ذلك مفيدًا عندما تحتاج إلى مشاركة نفس التطبيق في بيئات مضبوطة ضبطًا مختلفًا، بحيث يمكنك إعداد مضيف معين لمطابقة بيئة معينة لضبط الخادم الخاص بك.

إخفاء متغيرات البيئة من صفحات التصحيح

عندما يكون الاستثناء غير معلوم ، وتكون قيمة متغير البيئة APP_DEBUG صحيحًة true ، ستُظهر صفحة التصحيح جميع متغيرات البيئة ومحتوياتها. في بعض الحالات ، قد ترغب في إخفاء بعض المتغيرات. يمكنك القيام بذلك عن طريق تحديث خيار debug_blacklist في ملف التكوين config / app.php.

تتوفر بعض المتغيرات في كل من متغيرات البيئة وبيانات الخادم ، قد تحتاج إلى إدراجها في القائمة السوداء لكل من ENV_$ و SERVER_$ :

return [

    // ...

    'debug_blacklist' => [
        '_ENV' => [
            'APP_KEY',
            'DB_PASSWORD',
        ],

        '_SERVER' => [
            'APP_KEY',
            'DB_PASSWORD',
        ],

        '_POST' => [
            'password',
        ],
    ],
];

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

يمكنك الوصول إلى قيم الضبط بسهولة باستخدام الدالة المساعدة العامة 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 الرسمي.