php擴充開發執行個體詳解

h1. 一、自動化建立擴充架構

到源碼ext目錄下

協助
1
./ext_skel --extname=xiami_ext
產生如下幾個檔案檔案清單：
* CREDITS
* EXPERIMENTAL
* config.m4
* config.w32
* php_xiami_ext.h
* tests
* xiami_ext.c
* xiami_ext.php

.c檔案就是C語言系列的源檔案，而.h檔案則是C語言的標頭檔，即C系列中存放函數和全域變數的檔案。子程式不要定義在*.h中。函數定義要放在*.c中，而*.h只做聲明.否則多引用幾次，就會發生函數重複定義的錯誤。

h1. 二、編寫函數xiami_hello

h3. 1、不帶參數

php_xiami_ext.h

 
PHP_MINIT_FUNCTION(xiami_ext);
PHP_MSHUTDOWN_FUNCTION(xiami_ext);
PHP_RINIT_FUNCTION(xiami_ext);
PHP_RSHUTDOWN_FUNCTION(xiami_ext);
PHP_MINFO_FUNCTION(xiami_ext);
 
PHP_FUNCTION(xiami_hello);
xiami_ext.c

 
const zend_function_entry xiami_ext_functions[] = {
    ZEND_FE(confirm_xiami_ext_compiled, NULL)
    ZEND_FE(xiami_hello,        NULL)
    PHP_FE_END
};
 
ZEND_FUNCTION(xiami_hello)
{
    php_printf("Hello World!n");
}
h3. 2、接收外來參數

xiami_ext.c
 
ZEND_BEGIN_ARG_INFO(arg_xiami_hello, 0)
ZEND_ARG_INFO(0, name)
ZEND_END_ARG_INFO()
 
ZEND_FUNCTION(xiami_hello)
{
    char *name = NULL;
    int argc = ZEND_NUM_ARGS();
    int name_len;
 
    if (zend_parse_parameters(argc TSRMLS_CC, "s", &name, &name_len) == FAILURE)
        return;
    php_printf("hello %s",name);
}
 
const zend_function_entry xiami_ext_functions[] = {
    ZEND_FE(confirm_xiami_ext_compiled, NULL)
    ZEND_FE(xiami_hello,        arg_xiami_hello)
    PHP_FE_END
};
以ZEND_BEGIN_ARG_INFO宏定義開始，以ZEND_END_ARG_INFO()結束，這兩個宏定義解釋如下：

ZEND_BEGIN_ARG_INFO(name, pass_rest_by_reference)：
開始參數區塊定義，pass_rest_by_reference為1時，強制所有參數為參考型別
ZEND_END_ARG_INFO()

ZEND_NUM_ARGS()代表著參數的個數:

 
參數   代表著的類型
b   Boolean
l   Integer 整型
d   Floating point 浮點型
s   String 字串
r   Resource 資源
a   Array 數組
o   Object instance 對象
O   Object instance of a specified type 特定類型的對象
z   Non-specific zval 任意類型～
Z   zval**類型
h1. 三、編寫類XiamiClass

h3. 1、步驟

# 建立一個全域的zend_class_entry變數，用於儲存類的入口。
# 建立一個zend_function_entry結構體數組，用於儲存類中包含的方法。
# 在擴充的MINIT方法中註冊類。

h3. 2、空類

xiami_ext.c
首先，我們建立一個名為php_xiamiclass_entry的zend_class_entry結構體變數，該結構體變數實際儲存了我們建立的類的入口。

 
zend_class_entry *php_xiamiclass_entry;
這裡的php_xiamiclass_entry在擴充源檔案中是一個全域變數，為了使其它擴充可以使用我們建立的類，
這個全域變數應該在標頭檔中定義。

接下來，我們建立zend_function_entry結構體數組，這個數組與函數定義時的數組是一樣的。
 
const zend_function_entry xiami_ext_methods[] = {
    PHP_FE_END
};
在MINIT函數中，首先建立了一個xiami_ce變數用於儲存臨時的類入口，接下來使用INIT_CLASS_ENTRY
宏初始化該變數，之後使用zend_register_internal_class()將該類註冊到Zend引擎，
該函數會返回一個最終的類入口，將其賦值給前面建立的全域變數。

 
PHP_MINIT_FUNCTION(xiami_ext)
{
    zend_class_entry xiami_ce;
    INIT_CLASS_ENTRY(xiami_ce, "XiamiClass", xiami_ext_methods);
 
    php_xiamiclass_entry = zend_register_internal_class(&xiami_ce TSRMLS_CC);
    return SUCCESS;
}
h3. 3、類方法

php_xiami_ext.h
 
PHP_MINIT_FUNCTION(xiami_ext);
PHP_MSHUTDOWN_FUNCTION(xiami_ext);
PHP_RINIT_FUNCTION(xiami_ext);
PHP_RSHUTDOWN_FUNCTION(xiami_ext);
PHP_MINFO_FUNCTION(xiami_ext);
 
PHP_METHOD(XiamiClass,__construct);
PHP_METHOD(XiamiClass, set_xiami_age);
xiami_ext.c
 
ZEND_BEGIN_ARG_INFO_EX(arg_construct, 0, 0, 1)
    ZEND_ARG_INFO(0, age)
ZEND_END_ARG_INFO();
 
ZEND_BEGIN_ARG_INFO(arg_xiami_age, 0)
    ZEND_ARG_INFO(0, age)
ZEND_END_ARG_INFO()
 
PHP_METHOD(XiamiClass, __construct)
{
    long age;
    if(zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", &age) == FAILURE){
        WRONG_PARAM_COUNT;
    }
    if( age <= 0 ) {
        age = 1;
    }
 
    zend_update_property_long(Z_OBJCE_P(getThis()), getThis(), ZEND_STRL("_age"), age TSRMLS_CC);
    RETURN_TRUE;
}
 
PHP_METHOD(XiamiClass, set_xiami_age)
{
    long age;
    if(zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", &age) == FAILURE){
        WRONG_PARAM_COUNT;
    }
    if( age <= 0 ) {
        age = 1;
    }
    zend_update_property_long(Z_OBJCE_P(getThis()), getThis(), ZEND_STRL("_age"), age TSRMLS_CC);
    RETURN_TRUE;
}
 
PHP_MINIT_FUNCTION(xiami_ext)
{
    zend_class_entry xiami_ce;
    INIT_CLASS_ENTRY(xiami_ce, "XiamiClass", xiami_ext_methods);
 
    php_xiamiclass_entry = zend_register_internal_class(&xiami_ce TSRMLS_CC);
 
    zend_declare_property_null(php_xiamiclass_entry, ZEND_STRL("_age"), ZEND_ACC_PRIVATE TSRMLS_CC);
    return SUCCESS;
}
zend_declare_property_*系列函數:

 
ZEND_API int zend_declare_property_null(zend_class_entry *ce, char *name, int name_length, int access_type TSRMLS_DC);
用zend_read_property()和zend_update_property()函數：

 
ZEND_API zval *zend_read_property(zend_class_entry *scope, zval *object, char *name, int name_length, zend_bool silent TSRMLS_DC);
 
ZEND_API void zend_update_property(zend_class_entry *scope, zval *object, char *name, int name_length, zval *value TSRMLS_DC);
h1. 四、讀取ini檔案

php_xiami_ext.h

 
PHP_MINIT_FUNCTION(xiami_ext);
PHP_MSHUTDOWN_FUNCTION(xiami_ext);
PHP_RINIT_FUNCTION(xiami_ext);
PHP_RSHUTDOWN_FUNCTION(xiami_ext);
PHP_MINFO_FUNCTION(xiami_ext);
 
PHP_FUNCTION(xiami_hello);
ZEND_BEGIN_MODULE_GLOBALS(xiami_ext)
    long  age;
ZEND_END_MODULE_GLOBALS(xiami_ext)
 
#ifdef ZTS
#define XIAMI_EXT_G(v) TSRMG(xiami_ext_globals_id, zend_xiami_ext_globals *, v)
#else
#define XIAMI_EXT_G(v) (xiami_ext_globals.v)
#endif
xiami_ext.c

 
ZEND_DECLARE_MODULE_GLOBALS(xiami_ext)
 
PHP_INI_BEGIN()
   STD_PHP_INI_ENTRY("xiami_ext.age",      "42", PHP_INI_ALL, OnUpdateLong, age, zend_xiami_ext_globals, xiami_ext_globals)
PHP_INI_END()
 
static void php_xiami_ext_init_globals(zend_xiami_ext_globals *xiami_ext_globals)
{
    xiami_ext_globals->age = 10;
}
 
PHP_MINIT_FUNCTION(xiami_ext)
{
    ZEND_INIT_MODULE_GLOBALS(xiami_ext, php_xiami_ext_init_globals, NULL);
    REGISTER_INI_ENTRIES();
 
    return SUCCESS;
}
 
ZEND_FUNCTION(xiami_hello)
{
    RETURN_LONG(XIAMI_EXT_G(age));
}
 
const zend_function_entry xiami_ext_functions[] = {
    ZEND_FE(xiami_hello,        NULL)
    PHP_FE_END
};
STD_PHP_INI_ENTRY的最後三個參數是來告訴PHP修改哪個全域變數，我們擴充的全域變數的資料結構，以及這些全域變數被儲存到的全域容器的名稱。
在php_xiami_ext.h添加的內容中，使用了一對宏ZEND_BEGIN_MODULE_GLOBALS()和ZEND_END_MODULE_GLOBALS() — 用來建立一個包含一個age類型，名為zend_xiami_ext_globals的結構體。然後繼續聲明了XIAMI_EXT_G()來從一個線程池中擷取值，或者只是從全域空間中擷取 － 如果你為一個非線程環境編譯的話。

在php_xiami_ext.c中你用了ZEND_DECLARE_MODULE_GLOBALS()宏來真正執行個體化zend_xiami_ext_globals結構體為一個真正的全域變數.最後，在MINIT中，你使用了ZEND_INIT_MODULE_GLOBALS()來分配一個安全執行緒的資源id.

phpinfo擴充資訊中，顯示ini資訊

 
PHP_MINFO_FUNCTION(xiami_ext)
{
    php_info_print_table_start();
    php_info_print_table_header(2, "xiami_ext support", "enabled");
    php_info_print_table_end();
 
    DISPLAY_INI_ENTRIES();
}
h1. 五、設定常量
 
PHP_MINIT_FUNCTION(ggg)
{
    zend_constant c;
    char *trim_key = "xiami";
    char *trim_val = "hello";
    int trim_val_len,trim_key_len;
 
    trim_key_len = strlen(trim_key);
    trim_val_len = strlen(trim_val);
 
    c.value.type = IS_STRING;
    c.value.value.str.val = pestrdup(trim_val, trim_val_len+1);
    c.value.value.str.len = trim_val_len;
    c.flags = CONST_PERSISTENT | CONST_CS;
    c.name = pestrdup(trim_key, trim_key_len+1);
    c.name_len = trim_key_len+1;
    c.module_number = module_number;
    zend_register_constant(&c TSRMLS_CC);
 
    return SUCCESS;
}
h1. 六、資源處理

PHP中的資源類型在核心中是通過一個zend_rsrc_list_entry結構體來實現:
 
typedef struct _zend_rsrc_list_entry {
    void *ptr;
    int type;
    int refcount;
} zend_rsrc_list_entry;
其中，ptr是一個指向資源的最終實現的指標，例如一個檔案控制代碼，或者一個資料庫連接結構。type是一個類型標記，用於區分不同的資源類型。refcount用於資源的引用計數。
資源類型可分為普通的資源，以及持久型的資源。例如mysql普通串連與持久串連。均儲存在_zend_executor_globals結構體當中，其中包含如下兩個HashTable
 
struct _zend_executor_globals {
    ...
    HashTable regular_list;
    HashTable persistent_list;
    ...
}
regular_list儲存普通資源，persistent_list則儲存持久型資源。
要使用資源，先要註冊一個資源類型，使用如下的API函數：
 
ZEND_API int zend_register_list_destructors_ex(rsrc_dtor_func_t ld, rsrc_dtor_func_t pld, const char *type_name, int module_number);
此函數返回一個資源類型id，zend_rsrc_list_entry結構體當中的type成員即對應此值。在擴充當中，此id應作為一個全域變數儲存，以傳遞給其它資源API。
函數的第一及第二個參數，分別對應普通資源及持久資源的解構函式，第三個參數為資源類型的簡簡短名稱描述，一般用於錯誤提示，最後一個參數module_number為引擎內部使用，當我們調用這個函數時，只需要傳遞一個已經定義好的module_number變數。

 
static void myfile_dtor(zend_rsrc_list_entry *rsrc TSRMLS_DC){
     FILE *fp = (FILE *) rsrc->ptr;
     fclose(fp);
}
 
PHP_MINIT_FUNCTION(myfile) {
 
//le_myfile是一個用於儲存資源類型id的全域變數
     le_myfile = zend_register_list_destructors_ex(myfile_dtor,NULL,"standard-c-file", module_number);
     return SUCCESS;
要建立一個資源，通過ZEND_REGISTER_RESOURCE()函數：

 
ZEND_API int zend_register_resource(zval *rsrc_result, void *rsrc_pointer, int rsrc_type TSRMLS_DC);
#define ZEND_REGISTER_RESOURCE(rsrc_result, rsrc_pointer, rsrc_type)  zend_register_resource(rsrc_result, rsrc_pointer, rsrc_type TSRMLS_CC);
其第一個參數rsrc_result是一個指向zval的指標，很顯然其作用是將PHP變數和資源進行綁定。
第二個參數rsrc_pointer是一個指向資源資料的指標。
第三個參數rsrc_type，很顯然，是上面通過zend_register_list_destructors_ex()函數註冊所返回的資源類型id。

 
PHP_FUNCTION(file_open){
     char *filename = NULL;
     char *mode = NULL;
     int argc = ZEND_NUM_ARGS();
     int filename_len;
     int mode_len;
     FILE *fp;
 
     if (zend_parse_parameters(argc TSRMLS_CC, "ss", &filename,&filename_len, &mode, &mode_len) == FAILURE) {
          return;
     }
 
     fp = fopen(filename, mode);
 
     if (fp == NULL) {
          RETURN_FALSE;
     }
 
     ZEND_REGISTER_RESOURCE(return_value, fp, le_myfile);
}
要訪問一個資源，是通過ZEND_FETCH_RESOURCE()函數來進行的：

 
ZEND_API void *zend_fetch_resource(zval **passed_id TSRMLS_DC, int default_id, const char *resource_type_name, int *found_resource_type, int num_resource_types, ...);
#define ZEND_VERIFY_RESOURCE(rsrc)  if (!rsrc) { RETURN_FALSE; }
#define ZEND_FETCH_RESOURCE(rsrc, rsrc_type, passed_id, default_id, resource_type_name, resource_type)  rsrc = (rsrc_type) zend_fetch_resource(passed_id TSRMLS_CC, default_id, resource_type_name, NULL, 1, resource_type);    ZEND_VERIFY_RESOURCE(rsrc);
第一個參數rsrc，是要儲存資源值所對應的變數名。
第二個參數，是一個指標轉換的定義，用於內部將資源轉換為正確的類型。
第三個參數，是一個對應的資源值
第四個參數，用於實現資源的預設值
第五個參數，同zend_register_list_destructors_ex()的第三個參數
第六個參數，對應zend_register_list_destructors_ex()的傳回值

 
PHP_FUNCTION(file_write){
     char *buffer = NULL;
     int argc = ZEND_NUM_ARGS();
     int buffer_len;
     zval *filehandle = NULL;
     FILE *fp;
 
     if (zend_parse_parameters(argc TSRMLS_CC, "rs", &filehandle,&buffer, &buffer_len) == FAILURE) {
          return;
     }
 
     ZEND_FETCH_RESOURCE(fp, FILE *, &filehandle, -1, "standard-cfile", le_myfile);
 
     if (fwrite(buffer, 1, buffer_len, fp) != buffer_len) {
          RETURN_FALSE;
     }
 
     RETURN_TRUE;
}
要刪除一個資源，則使用zend_list_delete()函數：

 
ZEND_API int _zend_list_delete(int id TSRMLS_DC);
#define zend_list_delete(id)  _zend_list_delete(id TSRMLS_CC)
這個函數僅有一個資源id的參數，返回SUCCESS或者FAILURE。
 
 
PHP_FUNCTION(file_close){
     int argc = ZEND_NUM_ARGS();
     zval *filehandle = NULL;
 
     if (zend_parse_parameters(argc TSRMLS_CC, "r", &filehandle) == FAILURE) {
          return;
     }
 
     if (zend_list_delete(Z_RESVAL_P(filehandle)) == FAILURE) {
          RETURN_FALSE;
     }
 
     RETURN_TRUE;
}
參考：