إدارة متغيرات البيئة باستخدام Kawkab

يوفر إطار العمل كوكب طريقة مريحة وفعالة للتعامل مع متغيرات البيئة بسهولة، مع دعم القيم الافتراضية وتحويل الأنواع مثل السلاسل النصية، والأرقام، والقيم البوليانية، بالإضافة إلى القيم المعقدة مثل JSON والقوائم.

التهيئة والاستخدام

1. إعداد ملف البيئة

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

• لإنشاء الملفات اللازمة لكل بيئة، استخدم الأمر التالي:

npm run kawkab env

سيقوم هذا الأمر بإنشاء الملفات التالية:

• .env.development
• .env.production

2. مثال على محتوى ملف البيئة

# معلومات التطبيق
APP_NAME="Kawkab App"
APP_DEBUG=true
APP_MAINTENANCE_MODE=false
 
# إعدادات الخادم
SERVER_URL=http://localhost
SERVER_PORT=3000
 
# إعدادات قاعدة البيانات
DATABASE_CLIENT=mysql
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
DATABASE_USER=root
DATABASE_PASSWORD=
DATABASE_NAME=kawkab
 
# إعدادات اللغة
LOCALE_CODE=en
 
# إعدادات البريد الإلكتروني
MAIL_HOST=sandbox.smtp.example.io
MAIL_PORT=587
MAIL_USER=
MAIL_PASS=
MAIL_TLS=false
MAIL_FROM_ADDRESS="hello@example.com"
MAIL_FROM_NAME="${APP_NAME}"

ملاحظات:

• يمكن كتابة القيم مع أو بدون علامات اقتباس.
• يمكن استخدام التعليقات داخل الملف باستخدام #.
• لدعم القيم الديناميكية، يمكن الإشارة إلى متغير آخر باستخدام ${key} كما في المثال.

3. قراءة متغيرات البيئة

الحصول على قيمة نصية

للحصول على قيمة نصية من متغير بيئة:

const appName = env.get("APP_NAME", "DefaultApp");
console.log(`اسم التطبيق: ${appName}`);

الشرح:

• إذا لم يتم تعريف APP_NAME في البيئة، سيتم استخدام القيمة الافتراضية "DefaultApp".

الحصول على قيمة بوليانية

للحصول على قيمة بوليانية:

const isDebug = env.bool("APP_DEBUG");
console.log(`وضع التصحيح: ${isDebug}`);

الشرح:

• تعيد طريقة bool القيمة true إذا كانت القيمة "true" أو "1"، و false خلاف ذلك.

الحصول على قيمة رقمية

للحصول على قيمة رقمية:

const serverPort = env.number("SERVER_PORT", 3000);
console.log(`منفذ الخادم: ${serverPort}`);

الشرح:

• إذا لم يتم تعريف SERVER_PORT، سيتم استخدام القيمة الافتراضية 3000.

4. التعامل مع القيم المعقدة

الحصول على قيمة JSON

إذا كان لديك متغير يحتوي على بيانات JSON:

const databaseConfig = env.json("DATABASE_CONFIG", { host: "localhost" });
console.log(databaseConfig);

الشرح:

• إذا لم يتم تعريف DATABASE_CONFIG، سيتم استخدام الكائن الافتراضي { host: "localhost" }.

الحصول على قائمة من القيم

إذا كان لديك قائمة مفصولة بفواصل:

const supportedLocales = env.array("SUPPORTED_LOCALES", ",", ["en", "ar"]);
console.log(`اللغات المدعومة: ${supportedLocales}`);

الشرح:

• يتم تحويل السلسلة إلى مصفوفة بناءً على الفاصل (, في المثال).

5. تعديل متغيرات البيئة

إضافة متغير جديد

لإضافة متغير بيئة جديد بشكل ديناميكي:

env.set("NEW_FEATURE", "enabled");
console.log(env.get("NEW_FEATURE")); // الإخراج: "enabled"

حذف متغير بيئة

لحذف متغير بيئة:

env.delete("TEMP_VARIABLE");
console.log(env.has("TEMP_VARIABLE")); // الإخراج: false

الختام

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