PHP/configuration

ملف الإعدادات

يُقرأ ملف الإعدادات (php.ini)  عندما تبدأ اللغة بالعمل، أما الإصدارات الخاصة بالمخدّمات فإنّ عملية القراءة تحدث عندما يبدأ المخدّم بالعمل، وتبدأ هذه العملية في إصدارات CGI و CLI عند كل طلب invocation.

يجري البحث عن ملف php.ini في الأماكن التالية (بنفس الترتيب التالي):

• موقع وحدة SAPI المحدّد (موجّه PHPIniDir في Apache 2، خيار سطر الأوامر ‎-c في CGI و CLI، المعامل php_ini في NASPI، متغير البيئة PHP_INI_PATH في THTTPD).
• متغيّر البيئة التابع لـ PHPRC. قبل الإصدار 5.2.0، كانت عملية التحقّق تجري بعد مفتاح التسجيل المذكور أدناه.
• في الإصدار 5.2.0 وما بعده، أصبح بالإمكان تعيين مكان ملف php.ini لعدة إصدارات من اللغة. يعتمد جذر مفاتيح التسجيل على طبيعة النظام المثبّت وPHP، فإمّا 32-بت أو 64-بت. في حال كانت PHP والنظام المثبت من نوع 32-بت أو كان من نوع 64-بت، يستخدم المفتاح [(HKEY_LOCAL_MACHINE\SOFTWARE\PHP]، أما في حال كانت PHP من نوع 32-بت والنظام المثبّت هو 64-بت، فيستخدم المفتاح [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]] بدلًا عنه. في حال استخدام نفس نظام البتات، مفاتيح التسجيل التالية تفحص حسب الترتيب: [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]، [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]‎ و [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]‎، حيث تمثّل x و y و z الإصدارات الرئيسية والثانوية والإصدار على التوالي. في حال كانت PHP من نوع 32-بت والنظام المثبّت من نوع 64-بت، فإنّ مفاتيح السجيل التالية تفحص حسب الترتيب: [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z] و [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y]‎ و [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]‎ حيث تمثّل x و y و z الإصدارات الرئيسية والثانوية والإصدار على التوالي. إن كانت هناك قيمة لـ IniFilePath في أيّ من هذه المفاتيح، ستُستخدم أوّل قيمة يُعثر عليها كموقع لملف php.ini (في نظام ويندوز فقط).
• قيمة IniFilePath (نظام ويندوز فقط)، [HKEY_LOCAL_MACHINE\SOFTWARE\PHP] أو [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP].
• المجلد العامل الحالي (باستثناء CLI).
• مجلّد مخدّم الويب (في وحدات SAPI) أو مجلد PHP (في نظام ويندوز).

• مجلد windows ‏(C:\windows أو C:\winnt) (في نظام ويندوز) أو الخيار المتاح في وقت التصريف ‎--with-config-file-path.

إن كان الملف php-SAPI.ini متوفّرًا (SAPI هنا هي واجهة المخدّم البرمجية المستخدمة مثل php-cli.ini أو php-apache.ini) فإنّه يستخدم بدلًا عن الملف php.ini. ويمكن تحديد اسم واجهة المخدّم البرمجية بواسطة الدالة php_sapi_name()‎.

ملاحظة: يغيّر مخدّم ويب Apache المجلّد إلى root عند بدء التشغيل، مما يتسبّب في محاولة قراءة ملف php.ini في جذر ملفات النظام في حال توافره.

يمكن استخدام متغيّرات البيئة في ملف php.ini كما هو موضح في المثال التالي.

المثال 1: متغيّرات البيئة في ملف php.ini

; PHP_MEMORY_LIMIT is taken from environment
memory_limit = ${PHP_MEMORY_LIMIT}

توثّق الصفحات الخاصة بالملحقات الموجّهات التي تتعامل معها تلك الملحقات في ملف php.ini، وهناك قائمة بالموجّهات الداخلية في الملاحق، ولكن ليست كلّ الموجّهات موثّقة في هذا الدليل. يمكنك قراءة التعليقات في ملف php.ini للتعرف على قائمة الموجّهات الكاملة في إصدار PHP المثبّت لديك، أو يمكنك استعراض آخر إصدار من ملف php.ini في Git. المثال 2: مثال عن ملف php.ini

; any text on a line after an unquoted semicolon (;) is ignored
[php] ; section markers (text within square brackets) are also ignored
; Boolean values can be set to either:
;    true, on, yes
; or false, off, no, none
register_globals = off
track_errors = yes

; you can enclose strings in double-quotes
include_path = ".:/usr/local/lib/php"

; backslashes are treated the same as any other character
include_path = ".;c:\php\lib"

أصبح من الممكن في الإصدار 5.1.0 من PHP الإشارة إلى متغيّرات ‎.ini موجودة من داخل ملفات ‎.ini فمثلًا:

open_basedir = ${open_basedir} ":/new/dir".

مسح المجلدات

من الممكن إعداد PHP لمسح (scan) مجلّد ما بحثًا عن ملفات ‎.ini بعد قراءة ملف php.ini، ويمكن القيام بهذا في وقت التصريف عن طريق تعيين الخيار ‎--with-config-file-scan-dir. في الإصدار 5.2.0 وما بعده من اللغة، يمكن إعادة تعريف المجلد الذي ستمسحه اللغة في وقت التشغيل بتعيين متغيّر البيئة PHP_INI_SCAN_DIR.

يمكن إجراء عملية المسح على مجلدات متعددة وذلك بفصلها عن بعضها البعض بفاصل المسار الخاصّ بالمنصّة (العلامة (;) في ويندوز و NetWare و RISC OS، والعلامة (:) في جميع المنصات، تكون القيمة التي تستخدمها PHP متوفّرة في الثابت PATH_SEPARATOR). إن قدّم مجلّد فارغ في PHP_INI_SCAN_DIR فإنّ اللغة ستمسح ذلك المجلد في وقت التصريف بواسطة ‎--with-config-file-scan-dir.

تمسح PHP جميع الملفات ذات اللاحقة ‎.ini ضمن كل مجلّد وبحسب الحروف الأبجدية. يمكن الحصول على قائمة بالملفات المحمّلة وترتيبها باستدعاء الدالة php_ini_scanned_files()‎ أو بتشغيل PHP مع الخيار ‎--ini.

على فرض أنّ إعدادات PHP تتضمّن ‎--with-config-file-scan-dir=/etc/php.d وأنّ فاصل المسار هو : ...

$ php

ستحمّل اللغة جميع الملفات في المجلد ‎/etc/php.d/*.ini كملفات إعدادات.

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php

ستحمّل اللغة جميع الملفات في المجلد ‎/usr/local/etc/php.d/*.ini كملفات إعدادات.

$ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php

ستحمّل اللغة جميع الملفات في المجلد ‎/‎etc/php.d/*.ini ثم ‎/usr/local/etc/php.d/*.ini‎ كملفات إعدادات.

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php

ستحمل اللغة جميع الملفات في المجلد ‎/usr/local/etc/php.d/*.ini ثم ‎/etc/php.d/*.ini كملفات إعدادات.

سجل التغييرات

الإصدار	الوصف
7.0.0	لم تعد علامات (#) تمثّل التعليقات.
5.3.0	يجب عدم استخدام علامات (#) للتعبير عن التعليقات وستطلق اللغة تحذيرًا استخدام مهمل في حال استخدامها.
5.2.0	يمكن تعيين قيمة متغيّر البيئة PHP_INI_SCAN_DIR لتغيير المجلد المعيَّن بواسطة شيفرة الإعداد.
5.1.0	من الممكن الإشارة إلى متغيرات ‎.ini موجودة من داخل ملفات ‎.ini

ملفات ‎‎.user.ini

أصبحت PHP منذ الإصدار 5.3.0 تدعم ملفات INI للإعدادات ولكل مجلد على حدة، وتُعالج هذه الملفات بواسطة CGI/FastCGI SAPI، وقد أمست الإضافة PECL htscanner متروكة لصالح هذه الميزة. إن كنت تستخدم PHP كوحدة Apache فيمكنك استخدام ملفات ‎.htaccess لأداء نفس العمل.

تمسح اللغة إضافة إلى ملف php.ini الرئيسي ملفات INI في كل مجلّد، وتبدأ بذلك من المجلد الذي يحتوي على ملف PHP الذي طلبه الخادم، ثم تتدرّج صعودًا إلى أن تصل إلى مجلد الجذر للملف الحالي (كما هو معيّن في ‎$_SERVER['DOCUMENT_ROOT']‎)، وفي حال كون ملف PHP خارج المجلد الجذر فإن عملية المسح تجري على المجلد الحاوي له فقط.

تتعرّف اللغة على إعدادات INI من نمط PHP_INI_PERDIR و PHP_INI_USER في ملفات INI من النمط ‎.user.ini

يتحكّم موجّها INI هما user_ini.filename و user_ini.cache_ttl استخدام ملفات INI الخاصّة بالمستخدم.

يعيّن الموجّه user_ini.filename اسم الملف الذي تبحث عنه اللغة في كل مجلد، وإن عيّنت سلسلة نصية فارغة كقيمة لهذا الموجه، فإن اللغة لا تبحث عن الملفات إطلاقًا. القيمة الافتراضية لهذا الموجّه هي ‎.user.ini.

يتحكّم الموجّه user_ini.cache_ttl بتواتر عملية إعادة قراءة ملفات INI الخاصة بالمستخدم، والقيمة الافتراضية هي 300 ثانية (5 دقائق).

أين يمكن تعيين الإعدادات

تحدّد هذه الأوضاع المكان والزمان الذي يمكن فيه أو لا يمكن تعيين موجّه PHP، وكلّ موجّه في هذا الدليل يشير إلى واحد من هذه الأوضاع. فعلى سبيل المثال تعيّن بعض الإعدادات ضمن شيفرة PHP باستخدام الدالة ini_set()‎ في حين يتطلب تعيين إعدادات أخرى استخدام ملف php.ini أو httpd.conf.

مثلًا: الموّجه output_buffering هو من الوضع PHP_INI_PERDIR لهذا لا يمكن تعيينه باستخدام الدالة ini_set()‎ ولكن الموجّه display_errors هو من الوضع PHP_INI_ALL لهذا يمكن تعيينه في أي مكان حتّى بواسطة الدالة ini_set()‎.

تعريف أوضاع PHP_INI_*‎

الوضع	المعنى
PHP_INI_USER	يمكن تعيين العنصر في شيفرة المستخدم (مثل استخدام الدالة ini_set()‎) أو في سجلات ويندوز. في الإصدار 5.3 وما بعده من PHP أصبح بالإمكان تعيين العنصر في ملف ‎.user.ini
PHP_INI_PERDIR	يمكن تعيين المدخل في ملف php.ini أو ‎.htaccess أو httpd.conf أو ‎.user.ini (منذ الإصدار 5.3)
PHP_INI_SYSTEM	يمكن تعيين العنصر في ملف php.ini أو httpd.conf
PHP_INI_ALL	يمكن تعيين العنصر في أي مكان.

كيف تغير إعدادات الضبط

تشغيل PHP كوحدة Apache

عند استخدام PHP كوحدة Apache يمكن أيضًا تغيير إعدادات الضبط باستخدام موجهات في ملفات الضبط الخاصة بخادم Apache (مثل httpd.conf) وملفات ‎.htaccess، وللقيام بذلك ستحتاج إلى صلاحيات "AllowOverride Options" أو "AllowOverride All".

وهناك العديد من موجهات Apache التي تتيح تغيير إعدادات اللغة من داخل ملفات الإعدادات الخاصة بخادم Apache. لمعرفة ما إذا كان الموجّه من نوع PHP_INI_ALL أو PHP_INI_PERDIR أو PHP_INI_SYSTEM اطّلع على الملحق الذي يعرض قائمة بموجّهات php.ini.

php_value name value

تعيين قيمة الموجِّه المُحدَّد. ويمكن أن يُستخدَم مع أنواع الموجِّهات PHP_INI_ALL و PHP_INI_PERDIR، ولإلغاء تعيين القيم السابقة استخدم القيمة none.

ملاحظة: لا تستخدم php_value لتعيين قيم منطقية (بوليانية). يجب استخدام php_flag (انظر أدناه) لهذا الغرض.

php_flag name on|off

يستخدم لتعيين موجّه تهيئة منطقي. يمكن استخدامه مع الموجّهات من نوع PHP_INI_ALL و PHP_INI_PERDIR فقط.

php_admin_value name value

يعين قيمة الموجّه المحدّد، ولا يمكن استخدامه في ملفات ‎.htaccess، ولا يمكن تجاوز أي نوع من الموجهات بواسطة ملف ‎.htaccess أو دالة ini_set()‎ إذا عُيّن بواسطة php_admin_value. لإلغاء تعيين القيم السابقة استخدم القيمة none.

php_admin_flag name on|off

يستخدم لتعيين موجّه تهيئة منطقي، ولا يمكن استخدامه في ملفات ‎.htaccess، ولا يمكن تجاوز أي نوع من الموجهات بواسطة ملف ‎.htaccess أو دالة ini_set()‎ إذا عيّن بواسطة php_admin_flag.

المثال 3: مثال على ملف تهيئة Apache

<IfModule mod_php5.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag engine on
</IfModule>
<IfModule mod_php4.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag engine on
</IfModule>

تنبيه: ثوابت PHP غير موجودة خارج اللغة، فعلى سبيل المثال، لا يمكن استخدام ثوابت PHP مثل E_ALL و E_NOTICE في ملف httpd.conf لتعيين موجّهات التبليغ عن الأخطاء error_reporting إذ ستكون هذه الثوابت بلا معنى وستعالج إلى القيمة 0. ولكن يمكن استخدام قيم bitmask المرتبطة بها، فهذه الثوابت صالحة للاستخدام ملف php.ini.

تغيير إعدادات PHP باستخدام سجلات نظام ويندوز Windows registry

يمكن تعديل الإعدادات عند استخدام PHP على نظام ويندوز وحسب المجلد باستخدام سجلات النظام، إذ تخزّن قيم الإعدادات في مفتاح التسجيل HKLM\SOFTWARE\PHP\Per Directory Values في المفاتيح الفرعية المرتبطة باسم المسار. فعلى سبيل المثال، تخزّن قيم الإعدادات الخاصة بالمجلد c:\inetpub\wwwroot في المفتاح HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot، وتكون الإعدادات الخاصة بهذا المجلد متاحة لأي شيفرة تعمل في ذلك المجلد أو في المجلدات الفرعية التابعة له.

يجب أن تحمل القيم الموجودة ضمن المفتاح اسم موجّه الإعدادات الخاصة باللغة وقيمة السلسلة النصية، ولا يمكن استخدام ثوابت PHP كقيم لأنّها لن تُفسَّر، ولكن تكون قيم الإعدادات في PHP_INI_USER وحدها قابلة للتغيير بهذه الطريقة، وليست القيم في PHP_INI_PERDIR.

الواجهات interfaces الأخرى للغة

بغض النظر عن طريقة تشغيل PHP، يمكن تغيير قيم معيّنة في وقت تشغيل الشيفرة بواسطة الدالة ini_set()‎. راجع التوثيق الخاص بالدالة في صفحة ini_set()‎ للمزيد من المعلومات.

إن كنتَ ترغب بالإطلاع على قائمة كاملة بالإعدادات في نظام التشغيل الخاص بك مع قيمها الحالية، فيمكن تنفيذ الدالة phpinfo()‎ ومراجعة النتيجة. يمكنك أيضًا الوصول إلى القيم التابعة لموجّه معيّن في وقت تشغيل الشيفرة باستخدام الدالة ini_get()‎ أو get_cfg_var()‎.

مصادر

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