INI設(shè)置

和上一章你看到的超級(jí)全局變量以及持久化常量一樣, php.ini值必須在擴(kuò)展的MINIT代碼塊中定義. 然而, 和其他特性不同的是, INI選項(xiàng)的定義僅僅由簡單的啟動(dòng)/終止線組成.

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

定義并訪問INI設(shè)置

INI指令自身是在源碼文件中MINIT函數(shù)上面, 使用下面的宏完全獨(dú)立的定義的, 在這兩個(gè)宏之間可以定義一個(gè)或多個(gè)INI指令:

PHP_INI_BEIGN()
PHP_INI_END()

這兩個(gè)宏函數(shù)和ZEND_BEGIN_MODULE_GLOBALS()/ZEND_END_MODULE_GLOBALS()異曲同工. 不過這里不是typdef一個(gè)結(jié)構(gòu)體, 而是對(duì)靜態(tài)數(shù)據(jù)實(shí)例定義的框架組織:

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

如你所見, 它定義了一個(gè)zend_ini_entry值的向量, 以一條空的記錄結(jié)束. 這和你在前面看到的靜態(tài)向量function_entry的定義一致.

簡單的INI設(shè)置

現(xiàn)在, 你已經(jīng)有一個(gè)INI結(jié)構(gòu)體用于定義INI指令, 以及引擎注冊(cè)/卸載INI設(shè)置的機(jī)制, 因此我們可以真正的去為你的擴(kuò)展定義一些INI指令了. 假設(shè)你的擴(kuò)展暴露了一個(gè)打招呼的函數(shù), 就像第5章"你的第一個(gè)擴(kuò)展"中一樣, 不過, 你想讓打招呼的話可以自定義:

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

最簡單最直接的方式就是定義一個(gè)INI指令, 并給它一個(gè)默認(rèn)值"Hello world!":

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

你可能已經(jīng)猜到了, 這個(gè)宏的前兩個(gè)參數(shù)表示INI指令的名字和它的默認(rèn)值. 第三個(gè)參數(shù)用來確定引擎是否允許這個(gè)INI指令被修改(這將涉及到本章后面要介紹的訪問級(jí)別問題). 最后一個(gè)參數(shù)是一個(gè)回調(diào)函數(shù), 它將在每次INI指令的值發(fā)生變化時(shí)被調(diào)用. 你將在修改事件一節(jié)看到這個(gè)參數(shù)的細(xì)節(jié).

譯注: 如果你和譯者一樣遇到結(jié)果和原著結(jié)果預(yù)期不一致時(shí), 請(qǐng)?jiān)跍y試時(shí), 在你的MINIT()函數(shù)中增加一句"REGISTER_INI_ENTRIES();"調(diào)用, 并確保該調(diào)用在你的MINIT中分配全局空間之后執(zhí)行.

現(xiàn)在你的INI設(shè)置已經(jīng)定義, 只需要在你的打招呼函數(shù)中使用就可以了.

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

一定要注意, char *的值是引擎所有的, 一定不要修改. 正因?yàn)檫@樣, 所以將你本地用來臨時(shí)存儲(chǔ)INI設(shè)置值的變量定義為const修飾. 當(dāng)然, 并不是所有的INI值都是字符串; 還有其他的宏用來獲取整型, 浮點(diǎn)型以及布爾型的值:

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

通常你想要知道的是INI設(shè)置的當(dāng)前值; 不過, 作為補(bǔ)充, 存在幾個(gè)宏可以用來讀取未經(jīng)修改的INI設(shè)置值:

const char *strval = INI_ORIG_STR("sample4.stringval");
long lval = INI_ORIG_INT("sample4.intval");
double dval = INI_ORIG_FLT("sample4.fltval");
zend_bool bval = INI_ORIG_BOOL("sample4.boolval");

這個(gè)例子中, INI指令的名字"sample4.greeting"增加了擴(kuò)展名作為前綴, 這樣來保證不會(huì)和其他擴(kuò)展暴露的INI指令名字沖突. 對(duì)于私有的擴(kuò)展來說, 這個(gè)前綴不是必須的, 但是對(duì)于商業(yè)化或開源發(fā)布的公開擴(kuò)展還是鼓勵(lì)這樣做的.

訪問級(jí)別

對(duì)于INI指令, 開始總是有一個(gè)默認(rèn)值. 多數(shù)情況下, 理想是保持默認(rèn)值不變; 然而, 對(duì)于某些特殊的環(huán)境或者腳本內(nèi)特定的動(dòng)作, 這些值可能需要被修改. 如下表所示, INI指令的值可能在下面3個(gè)點(diǎn)被修改:

某些設(shè)置如果可以在任何地方被修改就沒有多大意義了, 比如safe_mode, 如果可以在任何地方去修改, 那么惡意腳本的作者就可以很簡單的去禁用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ì)為其測試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ù), 很簡單的翻譯成其他的標(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）！