Paramètres INI

et les précédents 1 Comme les variables superglobales et les constantes persistantes que vous avez vues au chapitre 1, les valeurs php.ini doivent être définies dans le bloc MINIT étendu. Cependant, contrairement à d'autres fonctionnalités, la définition des options INI se compose uniquement de simples lignes de démarrage/arrêt.

PHP_MINIT_FUNCTION(sample4)
{
    REGISTER_INI_ENTRIES();
    return SUCCESS;
}
PHP_MSHUTDOWN_FUNCTION(sample4)
{
    UNREGISTER_INI_ENTRIES();
    return SUCCESS;
}

Définir et accéder aux paramètres INI

La commande INI elle-même est au-dessus de la fonction MINIT dans la source fichier de code, défini de manière totalement indépendante à l'aide des macros suivantes, une ou plusieurs instructions INI peuvent être définies entre ces deux macros :

PHP_INI_BEIGN()
PHP_INI_END()

Ces deux fonctions de macro sont similaires à ZEND_BEGIN_MODULE_GLOBALS()/ZEND_END_MODULE_GLOBALS() Cependant, il ne s'agit pas d'une structure typdef, mais d'une organisation-cadre pour la définition d'instances de données statiques?:

static zend_ini_entry ini_entries[] = {
{0,0,NULL,0,NULL,NULL,NULL,NULL,NULL,0,NULL,0,0,NULL} };

Comme vous pouvez le voir, il définit un vecteur de valeurs zend_ini_entry, se terminant par un enregistrement vide. C'est la même chose que. vous feriez La définition du vecteur statique function_entry vue plus t?t est cohérente.

Paramètres INI simples

Maintenant, vous have Il existe une structure INI utilisée pour définir les instructions INI, ainsi que le mécanisme permettant au moteur d'enregistrer/désinstaller les paramètres INI, afin que nous puissions réellement définir certaines instructions INI pour votre extension. Supposons que votre extension expose une fonction de message d'accueil, comme Identique à. au chapitre 5 "Votre première extension", vous pouvez cependant la personnaliser si vous souhaitez lui dire bonjour?:

PHP_FUNCTION(sample4_hello_world)
{
    php_printf("Hello World!\n");
}

La manière la plus simple et la plus directe est de définir une commande INI, et donnez-lui la valeur par défaut "Bonjour tout le monde?!"?:

#include "php_ini.h"
PHP_INI_BEGIN()
    PHP_INI_ENTRY("sample4.greeting", "Hello World",
                                    PHP_INI_ALL, NULL)
PHP_INI_END()

Vous avez peut-être Je l'ai deviné, les deux premiers paramètres de cette macro représentent le nom de l'instruction INI et sa valeur par défaut. Le troisième paramètre est utilisé pour déterminer si le moteur autorise la modification de l'instruction INI (cela impliquera d'introduire le problème du niveau d'accès). plus loin dans ce chapitre) . Le dernier paramètre est une fonction de rappel qui sera appelée à chaque fois que la valeur de l'instruction INI change. Vous verrez les détails de ce paramètre dans la section Modifier les événements. Remarque sur la traduction?: si vous, comme le traducteur, rencontrez des résultats incompatibles avec les résultats attendus du travail original, veuillez ajouter un appel "REGISTER_INI_ENTRIES();" à votre fonction MINIT() pendant le test, et assurez-vous que l'appel est dans votre exécution après avoir alloué un espace global dans MINIT.

Maintenant que vos paramètres INI ont été définis, il ne vous reste plus qu'à l'utiliser dans votre fonction d'accueil .

Assurez-vous de noter que la valeur de char * appartient au moteur et ne doit pas être modifiée. Pour cette raison, définissez votre variable locale utilisée pour stocker temporairement le. INI définissant la valeur comme const Bien s?r, toutes les valeurs INI ne sont pas des cha?nes?; il existe d'autres macros pour obtenir des valeurs entières, à virgule flottante et booléennes?:

PHP_FUNCTION(sample4_hello_world)
{
    const char *greeting = INI_STR("sample4.greeting");
    php_printf("%s\n", greeting);
}

long lval = INI_INT("sample4.intval");
double dval = INI_FLT("sample4.fltval");
zend_bool bval = INI_BOOL("sample4.boolval");

Dans cet exemple, le nom de l'instruction INI "sample4.greeting" est préfixé par une extension pour garantir qu'elle n'entrera pas en conflit avec les noms d'instructions INI exposés par d'autres extensions privées. ce préfixe n'est pas obligatoire, mais est encouragé pour les extensions publiques pour les versions commerciales ou open source

Niveau d'accès

Pour les instructions INI, il existe toujours une valeur par défaut avec laquelle commencer. Dans la plupart des cas, l'idéal est de laisser la valeur par défaut inchangée. Cependant, pour certaines circonstances particulières ou actions spécifiques au sein du script, ces valeurs ??peut Doit être modifié. Comme le montre le tableau ci-dessous, la valeur de l'instruction INI peut être modifiée aux trois points suivants?:

某些設(shè)置如果可以在任何地方被修改就沒有多大意義了, 比如safe_mode, 如果可以在任何地方去修改, 那么惡意腳本的作者就可以很簡(jiǎn)單的去禁用safe_mode, 接著去讀或修改本不允許操作的文件.

類似的, 某些非安全相關(guān)的指令比如register_globals或magic_quotes_gpc, 在腳本中不能被修改, 因?yàn)? 在腳本執(zhí)行時(shí), 它所影響的事情已經(jīng)發(fā)生過了.

這些指令的訪問控制是通過PHP_INI_ENTRY()的第三個(gè)參數(shù)完成的. 在你前面例子中, 使用了PHP_INI_ALL, 它的定義是一個(gè)位域操作: PHP_INI_SYSTEM | PHP_INI_PERDIR | PHP_INI_USER.

對(duì)于register_globals和magic_quotes_gpc這樣的指令, 定義的訪問級(jí)別為PHP_INI_SYSTEM | PHP_INI_PERDIR. 排除了PHP_INI_USER將導(dǎo)致以這個(gè)名字調(diào)用ini_set()時(shí)最終會(huì)失敗.

現(xiàn)在, 你可能已經(jīng)猜到, safe_mode和open_basedir這樣的指令應(yīng)該僅被定義為PHP_INI_SYSTEM. 這樣的設(shè)置就確保了只有系統(tǒng)管理員可以修改這些值, 因?yàn)橹挥兴鼈兛梢栽L問修改php.ini或httpd.conf文件中的配置.

修改事件

當(dāng)INI指令被修改時(shí), 無論是通過ini_set()函數(shù)還是某個(gè)perdir指令的處理, 引擎都會(huì)為其測(cè)試OnModify回調(diào). 修改處理器可以使用ZEND_INI_MH()宏定義, 并通過在OnModify參數(shù)上傳遞函數(shù)名附加到INI指令上:

ZEND_INI_MH(php_sample4_modify_greeting)
{
    if (new_value_length == 0) {
        return FAILURE;
    }
    return SUCCESS;
}
PHP_INI_BEGIN()
    PHP_INI_ENTRY("sample4.greeting", "Hello World",
            PHP_INI_ALL, php_sample4_modify_greeting)
PHP_INI_END()

通過在new_value_length為0時(shí)返回FAILURE, 這個(gè)修改處理器禁止將greeting設(shè)置為空字符串. ZEND_INI_MH()宏產(chǎn)生的整個(gè)原型如下:

int php_sample4_modify_greeting(zend_ini_entry *entry,
    char *new_value, uint new_value_length,
    void *mh_arg1, void *mh_arg2, void *mh_arg3,
    int stage TSRMLS_DC);

各個(gè)參數(shù)的含義見下表:

核心結(jié)構(gòu)體: zend_ini_entry

struct _zend_ini_entry {
    int module_number;
    int modifiable;
    char *name;
    uint name_length;
    ZEND_INI_MH((*on_modify));
    void *mh_arg1;
    void *mh_arg2;
    void *mh_arg3;

    char *value;
    uint value_length;

    char *orig_value;
    uint orig_value_length;
    int modified;

    void ZEND_INI_DISP(*displayer);
};

展示INI設(shè)置

在上一章, 你看到了MINFO函數(shù)以及相關(guān)的指令用于展示擴(kuò)展的信息. 由于擴(kuò)展暴露INI指令是很常見的, 因此引擎提供了一個(gè)公共的宏可以放置到PHP_MINFO_FUNCTION()中用于展示INI指令信息.

PHP_MINFO_FUNCTION(sample4)
{
    DISPLAY_INI_ENTRIES();
}

這個(gè)宏將迭代PHP_INI_BEGIN()和PHP_INI_END()宏之間定義的INI指令集和, 在一個(gè)3列的表格中展示它們的INI指令名, 原始值(全局的), 以及當(dāng)前值(經(jīng)過PERDIR指令或ini_set()調(diào)用修改后)

默認(rèn)情況下, 所有的指令都直接以其字符串形式輸出. 對(duì)于某些指令, 比如布爾值以及用于語法高亮的顏色值, 則在展示處理時(shí)應(yīng)用了其他格式. 這些格式是通過每個(gè)INI設(shè)置的顯示處理器處理的, 它和你看到的OnModify一樣是一個(gè)動(dòng)態(tài)的回調(diào)函數(shù)指針.

顯示處理器可以使用PHP_INI_ENTRY()宏的擴(kuò)展版指定, 它接受一個(gè)額外的參數(shù). 如果設(shè)置為NULL, 則使用展示字符串值的處理器作為默認(rèn)處理器:

PHP_INI_ENTRY_EX("sample4.greeting", "Hello World", PHP_INI_ALL,
    php_sample4_modify_greeting, php_sample4_display_greeting)

顯然, 需要在INI設(shè)置定義之前聲明這個(gè)函數(shù). 和OnModify回調(diào)函數(shù)一樣, 這可以通過一個(gè)包裝宏以及少量編碼完成:

#include "SAPI.h" /* needed for sapi_module */
PHP_INI_DISP(php_sample4_display_greeting)
{
    const char *value = ini_entry->value;

    /* 選擇合適的當(dāng)前值或原始值 */
    if (type == ZEND_INI_DISPLAY_ORIG &&
        ini_entry->modified) {
        value = ini_entry->orig_value;
    }

    /* 使得打招呼的字符串粗體顯示(當(dāng)以HTML方式輸出時(shí)) */
    if (sapi_module.phpinfo_as_text) {
        php_printf("%s", value);
    } else {
        php_printf("<b>%s</b>", value);
    }
}

綁定到擴(kuò)展的全局空間

所有的INI指令都在Zend引擎內(nèi)有一塊存儲(chǔ)空間, 可以用以跟蹤腳本內(nèi)的變更并進(jìn)行請(qǐng)求外部的全局設(shè)置維護(hù). 在這塊存儲(chǔ)空間中, 所有的INI指令都以字符串值存儲(chǔ). 你已經(jīng)知道了, 這些值可以使用INI_INT(), INI_FLT(), INI_BOOL()等宏函數(shù), 很簡(jiǎn)單的翻譯成其他的標(biāo)量類型.

這個(gè)查找和轉(zhuǎn)換過程由于兩個(gè)原因非常低效: 首先, 每次一個(gè)INI的值在獲取時(shí), 它必須通過名字在一個(gè)HashTable中進(jìn)行定位. 這種查找方式對(duì)于僅在運(yùn)行時(shí)編譯的用戶空間腳本而言是沒有問題的, 但是對(duì)于已編譯的機(jī)器代碼源, 運(yùn)行時(shí)做這個(gè)工作就毫無意義.

每次請(qǐng)求標(biāo)量值的時(shí)候都需要將底層的字符串值轉(zhuǎn)換到標(biāo)量值是非常低效的. 因此我們使用你已經(jīng)學(xué)習(xí)過的線程安全全局空間作為存儲(chǔ)媒介, 每次INI指令值變更時(shí)更新它即可. 這樣, 所有訪問INI指令的代碼都只需要查找你的線程安全全局空間結(jié)構(gòu)體中的某個(gè)指針即可, 這樣就獲得了編譯期優(yōu)化的優(yōu)點(diǎn).

在你的php_sample4.h文件MODULE_GLOBALS結(jié)構(gòu)體中增加const char *greeting; 接著更新sample4.c中的下面兩個(gè)方法:

ZEND_INI_MH(php_sample4_modify_greeting)
{
    /* Disallow empty greetings */
    if (new_value_length == 0) {
        return FAILURE;
    }
    SAMPLE4_G(greeting) = new_value;
    return SUCCESS;
}
PHP_FUNCTION(sample4_hello_world)
{
    php_printf("%s\n", SAMPLE4_G(greeting));
}

由于這是對(duì)INI訪問的一種非常常見的優(yōu)化方式, 因此引擎暴露了一組專門處理INI指令到全局變量的綁定宏:

STD_PHP_INI_ENTRY_EX("sample4.greeting", "Hello World",
    PHP_INI_ALL, OnUpdateStringUnempty, greeting,
    zend_sample4_globals, sample4_globals,
    php_sample4_display_greeting)

這個(gè)宏執(zhí)行和上面你自己的php_sample4_modify_greeting相同的工作, 但它不需要OnModify回調(diào). 取而代之的是, 它使用了一個(gè)泛化的修改回調(diào)OnUpdateStringUnempty, 以及信息應(yīng)該存儲(chǔ)的空間. 如果要允許空的greeting指令值, 你可以直接指定OnUpdateString替代OnUpdateStringUnempty.

類似的, INI指令也可以綁定long, double, zend_bool的標(biāo)量值. 在你的php_sample4.h中MODULE_GLOBALS結(jié)構(gòu)體上增加幾個(gè)字段:

long mylong;
double mydouble;
zend_bool mybool;

現(xiàn)在在你的PHP_INI_BEGIN()/PHP_INI_END()代碼塊中使用STD_PHP_INI_ENTRY()宏創(chuàng)建新的INI指令, 它和對(duì)應(yīng)的_EX版本的宏的區(qū)別只是顯示處理器以及綁定到的值不同.

STD_PHP_INI_ENTRY("sample4.longval", "123",
    PHP_INI_ALL, OnUpdateLong, mylong,
    zend_sample4_globals, sample4_globals)
STD_PHP_INI_ENTRY("sample4.doubleval", "123.456",
    PHP_INI_ALL, OnUpdateDouble, mydouble,
    zend_sample4_globals, sample4_globals)
STD_PHP_INI_ENTRY("sample4.boolval", "1",
    PHP_INI_ALL, OnUpdateBool, mybool,
    zend_sample4_globals, sample4_globals)

這里要注意, 如果調(diào)用了DISPLAY_INI_ENTRIES(), 布爾類型的INI指令"sample4.boolval"將和其他設(shè)置一樣, 被顯示為它的字符串值; 然而, 首選的布爾值指令應(yīng)該被顯示為"on"或"off". 要使用這些更加表意的顯示, 你可以使用STD_PHP_INI_ENTRY_EX()宏并創(chuàng)建顯示處理器, 或者使用另外一個(gè)宏:

STD_PHP_INI_BOOLEAN("sample4.boolval", "1",
    PHP_INI_ALL, OnUpdateBool, mybool,
    zend_sample4_globals *, sample4_globals)

這個(gè)特定類型的宏是布爾類型特有的, 它提供的是將布爾值轉(zhuǎn)換為"on"/"off"值的顯示處理器.

小結(jié)

在本章, 你了解了php語言中最古老的特性之一的實(shí)現(xiàn), 它也是阻礙php可移植的罪魁. 對(duì)于每個(gè)新的INI設(shè)置, 都會(huì)使得編寫可移植代碼變得更加復(fù)雜. 使用這些特性要非常慎重, 因?yàn)閿U(kuò)展以后時(shí)鐘都要使用它了. 并且, 在使用時(shí)要注意不同系統(tǒng)間的行為一致性, 以免在維護(hù)時(shí)出現(xiàn)不可預(yù)期的狀況.

接下來的三張, 我們將深入到流API, 開始使用流的實(shí)現(xiàn)層和包裝操作, 上下文, 過濾器等.

以上就是[翻譯][php擴(kuò)展開發(fā)和嵌入式]第13章-php的INI設(shè)置?的內(nèi)容，更多相關(guān)內(nèi)容請(qǐng)關(guān)注PHP中文網(wǎng)（miracleart.cn）！