phpdotenv
V5.6.1 (20
يقوم بتحميل متغيرات البيئة من .env إلى getenv() و $_ENV و $_SERVER تلقائيًا.
يجب ألا تقوم مطلقًا بتخزين بيانات الاعتماد الحساسة في التعليمات البرمجية الخاصة بك . يعد تخزين التكوين في البيئة أحد مبادئ التطبيق المكون من اثني عشر عاملاً. يجب استخراج أي شيء من المحتمل أن يتغير بين بيئات النشر - مثل بيانات اعتماد قاعدة البيانات أو بيانات الاعتماد لخدمات الجهات الخارجية - من التعليمات البرمجية إلى متغيرات البيئة.
في الأساس، يعد ملف .env طريقة سهلة لتحميل متغيرات التكوين المخصصة التي يحتاجها تطبيقك دون الحاجة إلى تعديل ملفات htaccess أو مضيفات Apache/nginx الافتراضية. هذا يعني أنك لن تضطر إلى تحرير أي ملفات خارج المشروع، وسيتم تعيين جميع متغيرات البيئة دائمًا بغض النظر عن كيفية تشغيل مشروعك - Apache، وNginx، وCLI، وحتى خادم الويب المدمج في PHP. إنها طريقة أسهل من كل الطرق الأخرى التي تعرفها لتعيين متغيرات البيئة، وسوف تحبها!
php_value إلى ملفات .htaccessPHP dotenv هو إصدار PHP من Ruby dotenv الأصلي.
التثبيت سهل للغاية عبر Composer:
$ composer require vlucas/phpdotenv أو قم بإضافته يدويًا إلى ملف composer.json الخاص بك.
نحن نتبع الإصدار الدلالي، مما يعني أنه قد تحدث تغييرات جذرية بين الإصدارات الرئيسية. لدينا أدلة ترقية متاحة لـ V2 إلى V3، وV3 إلى V4، وV4 إلى V5 متاحة هنا.
عادةً ما يتم الاحتفاظ بملف .env خارج نطاق التحكم في الإصدار نظرًا لأنه يمكن أن يحتوي على مفاتيح API وكلمات مرور حساسة. يتم إنشاء ملف .env.example منفصل مع تحديد كافة متغيرات البيئة المطلوبة باستثناء المتغيرات الحساسة، والتي يتم توفيرها من قبل المستخدم لبيئات التطوير الخاصة بهم أو يتم توصيلها في مكان آخر إلى المتعاونين في المشروع. يقوم المتعاونون في المشروع بعد ذلك بنسخ ملف .env.example بشكل مستقل إلى ملف .env محلي والتأكد من صحة جميع الإعدادات لبيئتهم المحلية، أو ملء المفاتيح السرية أو توفير القيم الخاصة بهم عند الضرورة. في هذا الاستخدام، يجب إضافة ملف .env إلى ملف .gitignore الخاص بالمشروع بحيث لن يتم الالتزام به أبدًا من قبل المتعاونين. يضمن هذا الاستخدام عدم وجود كلمات مرور حساسة أو مفاتيح واجهة برمجة التطبيقات (API) في سجل التحكم في الإصدار، وبالتالي يكون خطر حدوث خرق أمني أقل، ولن يلزم أبدًا مشاركة قيم الإنتاج مع جميع المتعاونين في المشروع.
أضف تكوين التطبيق الخاص بك إلى ملف .env في جذر مشروعك. تأكد من إضافة ملف .env إلى .gitignore الخاص بك حتى لا يتم تسجيله في الكود
S3_BUCKET= " dotenv "
SECRET_KEY= " souper_seekret_key " الآن قم بإنشاء ملف باسم .env.example وتحقق من ذلك في المشروع. يجب أن يحتوي هذا على متغيرات ENV التي تحتاج إلى تعيينها، ولكن يجب أن تكون القيم فارغة أو مملوءة ببيانات وهمية. والفكرة هي السماح للناس بمعرفة المتغيرات المطلوبة، ولكن ليس منحهم قيم الإنتاج الحساسة.
S3_BUCKET= " devbucket "
SECRET_KEY= " abc123 " يمكنك بعد ذلك تحميل .env في تطبيقك باستخدام:
$ dotenv = Dotenv Dotenv :: createImmutable ( __DIR__ );
$ dotenv -> load (); لمنع الاستثناء الذي يتم طرحه عند عدم وجود ملف .env ، يمكنك:
$ dotenv = Dotenv Dotenv :: createImmutable ( __DIR__ );
$ dotenv -> safeLoad (); اختياريًا، يمكنك تمرير اسم ملف كمعامل ثانٍ، إذا كنت ترغب في استخدام شيء آخر غير .env :
$ dotenv = Dotenv Dotenv :: createImmutable ( __DIR__ , ' myconfig ' );
$ dotenv -> load (); جميع المتغيرات المحددة متاحة الآن في النطاقين العالميين الفائقين $_ENV و $_SERVER .
$ s3_bucket = $ _ENV [ ' S3_BUCKET ' ];
$ s3_bucket = $ _SERVER [ ' S3_BUCKET ' ]; لا يُنصح بشدة باستخدام getenv() و putenv() نظرًا لأن هذه الوظائف ليست آمنة لسلاسل العمليات، ومع ذلك لا يزال من الممكن توجيه PHP dotenv لاستخدام هذه الوظائف. بدلًا من استدعاء Dotenv::createImmutable ، يمكن استدعاء Dotenv::createUnsafeImmutable ، والذي سيضيف PutenvAdapter خلف الكواليس. ستكون متغيرات البيئة الخاصة بك متاحة الآن باستخدام طريقة getenv ، بالإضافة إلى المتغيرات العالمية الفائقة:
$ s3_bucket = getenv ( ' S3_BUCKET ' );
$ s3_bucket = $ _ENV [ ' S3_BUCKET ' ];
$ s3_bucket = $ _SERVER [ ' S3_BUCKET ' ];من الممكن دمج متغير بيئة داخل متغير آخر، وهو أمر مفيد لتقليل التكرار.
يتم ذلك عن طريق تغليف متغير بيئة موجود في ${…} على سبيل المثال
BASE_DIR= " /var/webroot/project-root "
CACHE_DIR= " ${BASE_DIR} /cache "
TMP_DIR= " ${BASE_DIR} /tmp " تشير الثبات إلى ما إذا كان مسموحًا لـ Dotenv بالكتابة فوق متغيرات البيئة الموجودة. إذا كنت تريد أن يقوم Dotenv بالكتابة فوق متغيرات البيئة الموجودة، فاستخدم createMutable بدلاً من createImmutable :
$ dotenv = Dotenv Dotenv :: createMutable ( __DIR__ );
$ dotenv -> load (); خلف الكواليس، يتم توجيه "المستودع" للسماح بالثبات أم لا. افتراضيًا، يتم تكوين المستودع للسماح بالكتابة فوق القيم الموجودة افتراضيًا، وهو أمر مناسب إذا تم استدعاء طريقة "إنشاء" باستخدام RepositoryBuilder لإنشاء مستودع أكثر تخصيصًا:
$ repository = Dotenv Repository RepositoryBuilder :: createWithNoAdapters ()
-> addAdapter ( Dotenv Repository Adapter EnvConstAdapter ::class)
-> addWriter ( Dotenv Repository Adapter PutenvAdapter ::class)
-> immutable ()
-> make ();
$ dotenv = Dotenv Dotenv :: create ( $ repository , __DIR__ );
$ dotenv -> load (); المثال أعلاه سوف يكتب القيم المحملة إلى $_ENV و putenv ، ولكن عند استيفاء متغيرات البيئة، سنقرأ فقط من $_ENV . علاوة على ذلك، فإنه لن يحل محل أي متغيرات تم تعيينها بالفعل قبل تحميل الملف.
ومن خلال مثال آخر، يمكن للمرء أيضًا تحديد مجموعة من المتغيرات التي سيتم السماح بإدراجها. أي أنه سيتم تحميل المتغيرات الموجودة في قائمة السماح فقط:
$ repository = Dotenv Repository RepositoryBuilder :: createWithDefaultAdapters ()
-> allowList ([ ' FOO ' , ' BAR ' ])
-> make ();
$ dotenv = Dotenv Dotenv :: create ( $ repository , __DIR__ );
$ dotenv -> load ();يحتوي PHP dotenv على وظيفة التحقق من الصحة، بما في ذلك فرض وجود متغير البيئة. يعد هذا مفيدًا بشكل خاص للسماح للأشخاص بمعرفة أي متغيرات مطلوبة صريحة لن يعمل تطبيقك بدونها.
يمكنك استخدام سلسلة واحدة:
$ dotenv -> required ( ' DATABASE_DSN ' );أو مجموعة من السلاسل:
$ dotenv -> required ([ ' DB_HOST ' , ' DB_NAME ' , ' DB_USER ' , ' DB_PASS ' ]); إذا كان هناك أي متغيرات ENV مفقودة، فسوف يقوم Dotenv بطرح RuntimeException مثل هذا:
One or more environment variables failed assertions: DATABASE_DSN is missing
بالإضافة إلى مجرد طلب تعيين متغير، قد تحتاج أيضًا إلى التأكد من أن المتغير ليس فارغًا:
$ dotenv -> required ( ' DATABASE_DSN ' )-> notEmpty ();إذا كان متغير البيئة فارغًا، فستحصل على استثناء:
One or more environment variables failed assertions: DATABASE_DSN is empty
قد تحتاج أيضًا إلى التأكد من أن المتغير ذو قيمة عددية. يمكنك القيام بما يلي:
$ dotenv -> required ( ' FOO ' )-> isInteger ();إذا لم يكن متغير البيئة عددًا صحيحًا، فستحصل على استثناء:
One or more environment variables failed assertions: FOO is not an integer.
قد يرغب المرء فقط في فرض قواعد التحقق من الصحة عند تعيين متغير. نحن نؤيد هذا أيضًا:
$ dotenv -> ifPresent ( ' FOO ' )-> isInteger ();قد تحتاج إلى التأكد من أن المتغير على شكل قيمة منطقية، بحيث يقبل "صحيح" و"خطأ" و"تشغيل" و"1" و"نعم" و"إيقاف" و"0" و"لا". يمكنك القيام بما يلي:
$ dotenv -> required ( ' FOO ' )-> isBoolean ();إذا لم يكن متغير البيئة منطقيًا، فستحصل على استثناء:
One or more environment variables failed assertions: FOO is not a boolean.
وبالمثل، يمكن للمرء أن يكتب:
$ dotenv -> ifPresent ( ' FOO ' )-> isBoolean ();من الممكن أيضًا تحديد مجموعة من القيم التي يجب أن يكون عليها متغير البيئة الخاص بك. يعد هذا مفيدًا بشكل خاص في المواقف التي لا يدعم فيها الكود الخاص بك سوى عدد قليل من الخيارات أو برامج التشغيل:
$ dotenv -> required ( ' SESSION_STORE ' )-> allowedValues ([ ' Filesystem ' , ' Memcached ' ]);إذا لم يكن متغير البيئة موجودًا في قائمة القيم المسموح بها، فستحصل على استثناء مماثل:
One or more environment variables failed assertions: SESSION_STORE is not an allowed value.
من الممكن أيضًا تحديد regex الذي يجب أن يكون عليه متغير البيئة الخاص بك.
$ dotenv -> required ( ' FOO ' )-> allowedRegexValues ( ' ([[:lower:]]{3}) ' ); يمكنك التعليق على ملف .env الخاص بك باستخدام الحرف # . على سبيل المثال
# this is a comment
VAR= " value " # comment
VAR=value # commentفي بعض الأحيان، تريد فقط تحليل الملف وحل متغيرات البيئة المتداخلة، من خلال إعطائنا سلسلة، وإرجاع المصفوفة إليك. على الرغم من أن هذا ممكن بالفعل، إلا أنه أمر مبتذل بعض الشيء، لذلك قدمنا طريقة مباشرة للقيام بذلك:
// ['FOO' => 'Bar', 'BAZ' => 'Hello Bar']
Dotenv Dotenv :: parse ( " FOO=Bar n BAZ= " Hello $ {FOO} "" );هذا هو بالضبط نفس:
Dotenv Dotenv :: createArrayBacked ( __DIR__ )-> load ();فقط، بدلاً من توفير الدليل للعثور على الملف، قمت بتوفير محتويات الملف مباشرة.
عندما يقوم مطور جديد باستنساخ قاعدة التعليمات البرمجية الخاصة بك، سيكون لديه خطوة إضافية لمرة واحدة لنسخ ملف .env.example يدويًا إلى .env وملء القيم الخاصة به (أو الحصول على أي قيم حساسة من زميل عمل في المشروع).
في إعدادات خادم معينة (الأكثر شيوعًا في الاستضافة المشتركة)، قد تقوم PHP بإلغاء تنشيط الكائنات العالمية الفائقة مثل $_ENV أو $_SERVER . إذا لم يتم تعيين هذه المتغيرات، قم بمراجعة variables_order في ملف php.ini . راجع php.net/manual/en/ini.core.php#ini.variables-order.
إذا اكتشفت ثغرة أمنية داخل هذه الحزمة، فيرجى إرسال بريد إلكتروني إلى [email protected]. سيتم معالجة جميع الثغرات الأمنية على الفور. يمكنك الاطلاع على سياستنا الأمنية الكاملة هنا.
تم ترخيص PHP dotenv بموجب ترخيص BSD المكون من 3 فقرات.
متاح كجزء من اشتراك Tidelift
يعمل القائمون على صيانة vlucas/phpdotenv وآلاف الحزم الأخرى مع Tidelift لتقديم الدعم التجاري والصيانة للتبعيات مفتوحة المصدر التي تستخدمها لبناء تطبيقاتك. يمكنك توفير الوقت وتقليل المخاطر وتحسين سلامة التعليمات البرمجية، مع الدفع لمشرفي التبعيات الدقيقة التي تستخدمها. يتعلم أكثر.
