[翻譯][php擴充開發和嵌入式]第5章-您的第一個擴充

你的第一個擴充

每一個php擴充的構建至少需要兩個檔案: 一個configuration檔案, 它告訴編譯期要構建哪些檔案以及需要什麼外部的庫, 還需要至少一個源檔案, 它執行實際的工作.

剖析擴充

實際上, 通常會有第二個或第三個設定檔, 以及一個或多個標頭檔. 對於你的第一個擴充, 你需要添加每種類型的一個檔案並使用它們工作.

設定檔

要開始了, 首先在你的php原始碼分類樹的ext/目錄下建立名為sample的目錄. 實際上這個新的目錄可以放在任何地方, 但是為了在本章後面示範win32和靜態構建選項, 我們還是先建立在原始碼目錄下吧.

下一步, 進入這個目錄, 建立一個名為config.m4的檔案, 鍵入下面內容:

PHP_ARG_ENABLE(sample,    [Whether to enable the "sample" extension],    [  enable-sample        Enable "sample" extension support])    if test $PHP_SAMPLE != "no"; then    PHP_SUBST(SAMPLE_SHARED_LIBADD)    PHP_NEW_EXTENSION(sample, sample.c, $ext_shared)  fi

這是./configure時能夠調用enable-sample選項的最低要求.PHP_ARG_ENABLE的第二個參數將在./configure處理過程中到達這個擴充的設定檔時顯示. 第三個參數將在終端使用者執行./configure --help時顯示為協助資訊.

有沒有想過為什麼有的擴充配置使用enable-extname, 而有的擴充則使用with-extname? 功能上兩者沒有區別. 實際上, enable表示啟用這個特性不需要其他任何第三方庫, 相比之下, with則表示要使用這個特性還有其他先決條件

現在, 你的sample擴充並不需要和其他庫連結, 因此只需要使用enable版本. 在第17章"外部庫"中, 我們將介紹使用with並指示編譯器使用額外的CFLAGS和LDFLAGS設定.

如果終端使用者使用enable-sample選項調用了./configure, 那麼本地的環境變數$PHP_SAMPLE, 將被設定為yes. PHP_SUBST()是標準autoconf的AC_SUBST()宏的php修改版, 它在將擴充構建為共用模組時需要.

最後但並不是不重要的, PHP_NEW_EXTENSION()定義了模組並枚舉了所有必須作為擴充的一部分編譯的源檔案. 如果需要多個檔案, 它可以在第二個參數中使用空格分隔列舉, 例如:

PHP_NEW_EXTENSION(sample, sample.c sample2.c sample3.c, $ext_shared)

最後一個參數是對應於PHP_SUBST(SAMPLE_SHARED_LIBADD)命令的, 在構建共用模組的時候同樣需要它.

標頭檔

當使用C開發的時候, 將資料的類型定義放到外部的標頭檔中隔離起來, 由源檔案包含是常見的做法. 儘管php並不要求這樣, 但是這樣做在模組增長到不能放到單個源檔案時是有簡化作用的.

在你的php_sample.h標頭檔中, 以下面內容開始

#ifndef PHP_SAMPLE_H  /* 防止重複包含 */  #define PHP_SAMPLE_H    /* 定義擴充的屬性 */  #define PHP_SAMPLE_EXTNAME    "sample"  #define PHP_SAMPLE_EXTVER    "1.0"    /* 在php源碼樹外面構建時引入配置選項 */  #ifdef HAVE_CONFIG_H  #include "config.h"  #endif    /* 包含php的標準標頭檔 */  #include "php.h"    /* 定義進入點符號, Zend在載入這個模組的時候使用 */  extern zend_module_entry sample_module_entry;  #define phpext_sample_ptr &sample_module_entry    #endif /* PHP_SAMPLE_H */

這個標頭檔完成了兩個主要的任務: 如果擴充使用phpize工具構建(本書通常都使用這種方式), 那麼HAVE_CONFG_H就是已定義的, 這樣config.h就會被正常的包含進來. 無論擴充怎樣編譯, 都會從php源碼樹中包含php.h. 這個標頭檔中包含了php源碼中訪問大部分PHPAPI要使用的其他標頭檔.

接下來, 你的擴充使用的zend_module_entry結構定義為外部的, 這樣當這個模組使用extension=xxx載入時, 就可以被Zend使用dlopen和dlsym()取到.

譯註: 關於模組的載入過程, 請參考譯者的一篇部落格<從dl('xxx.so');函數分析PHP模組開發>(http://blog.csdn.Net/lgg201/article/details/6584095)

標頭檔中還會包含一些預先處理, 定義將在原檔案中使用的資訊.

原始碼

最後, 最重要的你需要在sample.c中建立一個簡單的源碼骨架:

#include "php_sample.h"    zend_module_entry sample_module_entry = {  #if ZEND_MODULE_API_NO >= 20010901       STANDARD_MODULE_HEADER,  #endif      PHP_SAMPLE_EXTNAME,      NULL, /* Functions */      NULL, /* MINIT */      NULL, /* MSHUTDOWN */      NULL, /* RINIT */      NULL, /* RSHUTDOWN */      NULL, /* MINFO */  #if ZEND_MODULE_API_NO >= 20010901      PHP_SAMPLE_EXTVER,  #endif      STANDARD_MODULE_PROPERTIES  };    #ifdef COMPILE_DL_SAMPLE  ZEND_GET_MODULE(sample)  #endif

就這樣簡單. 這三個檔案是建立一個模組骨架所需的一切.但是, 它沒有任何功能, 不過作為你在本節後面填充功能的模板是不錯的選擇. 不過先讓我們看看究竟發生了什麼.

開始的一行非常簡單, 包含了你剛才建立的標頭檔, 通過擴充得到了php源碼樹中的其他核心標頭檔.

接下來, 建立你在標頭檔中定義的zend_module_entry結構. 你應該注意到了, zend_module_entry的第一個元素是一個條件運算式, 給予當前的ZEND_MODULE_API_NO定義. 這個API編號大概是php4.2.0的, 如果你確定你的擴充不會安裝在比這還古老的版本, 你可以砍掉#ifdef部分, 直接包含STANDARD_MODULE_HEADER元素.

考慮一下, 無論如何, 它都會在編譯期耗費一點時間, 而不會對結果產生的二進位或處理需要的時間產生影響, 因此多數情況下最好直接砍掉這個條件. 這同樣適用於下面的版本屬性.

其他的6個元素現在初始設定為NULL; 你可以在它後面的注釋中看到它的用途.

最後, 在最底下你可以看到每個可以編譯為共用模組的php擴充都會有的一個公用元素. 這個簡短的條件在你動態載入時由Zend增加一個引用. 不要關心它的細節, 你只需要保證它的存在, 否則下一節可能就無法工作了.

構建你的第一個擴充

現在你擁有了所有的檔案, 是時候編譯安裝了. 相比編譯主php二進位, 步驟上略有不同.

在*nix上構建

第一步是使用config.m4中的資訊作為末班產生./configure指令碼. 這可以運行在你安裝主php二進位時附帶安裝的phpize程式來完成:

$ phpize  PHP Api Version: 20041225  Zend Module Api No: 20050617  Zend Extension Api No: 220050617

Zend Extension Api No前面多出來的2並不是印刷錯誤; 它對應於Zend引擎2這個版本號碼, 一般認為要保持這個API編號大於它對應的ZE1版本.

如果你此時查看目前的目錄 你會注意到比剛才的3個檔案多了不少檔案. phpize程式結合你擴充的config.m4檔案以及從你的php構建中收集的資訊和所有讓編譯發生所需的一切. 這意味著你不用糾纏在makefile和定位php頭上面. php已經幫你做了這個工作.

下一步就簡單了, 執行./configure. 這裡你只要配置你的擴充, 因此你需要做的如下:

$ ./configure --enable-sample

注意這裡沒有使用enable-debug和enable-maintainer-zts. 這是因為phpize已經將它們的值從主php構建中拿過來並應用到你的擴充的./configure指令碼中了.

現在, 構建它! 和其他任何的包一樣, 你只需要鍵入make, 產生的指令檔就會處理剩下的事情.

構建處理完成後, 你會得到一個訊息指出sample.so已經編譯並放在了當前構建目錄下一個名為"modules"的目錄中.

在windows上構建

譯者不熟悉windows平台, 因此略過.

將構建的擴充作為共用模組載入

在請求的時候為了讓php找到這個模組, 需要將它放到php.ini中extension_dir設定的目錄下. 預設的php.ini放在/usr/local/lib/php.ini; 不過這個預設值可能會因為包管理系統而不同. 檢查php -i的輸出可以看到你這個設定檔在哪裡.

如果php.ini中的這個設定沒有修改過, 它的值預設是"PHP_HOME/lib/php/extensions/debug-zts-20100525", 後面的debug-zts-20100525分別是是否啟用調試, 是否啟用zts, PHPAPI編號. 如果你還沒有已載入的擴充, 或者說除了sample.so沒有其他擴充, 可以將這個值修改到你make產生模組的路徑. 否則, 直接將產生的sample.so拷貝到這個設定的目錄下.(譯註: php -i | grep extension_dir尋找你的extension_dir設定)

在extension_dir指向正確的位置後, 有兩種方式告訴php去載入你的模組. 第一種是在指令碼中使用dl()函數:

<?php      dl('sample.so');      var_dump(get_loaded_modules());  ?>

如果指令碼沒有顯示sample已載入, 則表示有哪裡出了問題. 查看輸出上面的錯誤訊息作為線索, 或者如果在php.ini中進行了相應的設定就參考error_log.

第二種方式, 也是更常用的方式, 在php.ini中使用extension指令指定要載入的模組. 這個指令在php.ini的設定中是比較特殊的, 可以多次以不同的值使用它. 因此如果你已經在php.ini中設定了一個擴充, 不要在同一行使用分隔字元的方式列舉, 而是插入新的一行: extension=sample.so. 此時你的php.ini看起來是這樣的:

extension_dir=/usr/local/lib/php/modules/  extension=sample.so

現在你可以不使用dl()運行相同的指令碼, 或者直接執行php -m命令, 就可以在已載入模組列表中看到sample了.

所有本章剩餘以及以後章節的代碼, 都假設你已經按照這裡描述的方法載入了當前擴充. 如果你計劃使用dl(), 請確認在測試指令碼中加入載入的代碼(dl()).

靜態構建

在已載入模組列表中, 你可能注意到了一些在php.ini中並沒有使用extension指令包含的模組. 這些模組是直接構建到php中的, 它們作為主php程式的一部分被編譯進php中.

在*nix下靜態構建

現在, 如果你現在進入到php源碼樹的根目錄, 運行./configure --help, 你會看到雖然你的擴充和所有其他模組都在ext/目錄下, 但它並沒有作為一個選項列出. 這是因為, 此刻, ./configure指令碼已經產生了, 而你的擴充並不知道. 要重建./configure並讓它找到你的新擴充, 你需要做的只是執行一條命令:

$ ./buildconf

如果你使用產品發布版的php做開發, 你會發現./buildconf自己不能工作. 這種情況下, 你需要執行: ./buildconf --force來繞過對./configure命令的一些保護.

現在你執行./configure --help就可以看到--enable-sample是一個可用選項了. 此時, 你就可以重新執行./configure, 使用你原來構建主php時使用的所有選項, 外加--enable-sample, 這樣構建出來的php二進位檔案就是完整的, 包含你自己擴充的程式.

當然, 這樣做還有點早. 你的擴充除了佔用空間還應該做一些事情.

windows下靜態構建

譯者不熟悉windows環境, 因此略過.

功能函數

在使用者空間和擴充代碼之間最快捷的連結就是PHP_FUNCTION(). 首先在你的sample.c檔案頂部, #include "php_sample.h"之後增加下面代碼:

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

PHP_FUNCTION()宏函數就像一個普通的C函數定義, 因為它按照下面方式展開:

#define PHP_FUNCTION(name) \      void zif_##name(INTERNAL_FUNCTION_PARAMETERS)

這種情況下, 它就等價於:

void zif_sample_hello_world(zval *return_value,      char return_value_used, zval *this_ptr TSRMLS_DC)

當然, 只定義函數還不夠. 引擎需要知道函數的地址以及應該暴露給使用者空間的函數名. 這通過下一個代碼塊完成, 你需要在PHP_FUNCTION()塊後面增加:

static function_entry php_sample_functions[] = {      PHP_FE(sample_hello_world,        NULL)      { NULL, NULL, NULL }  };

php_sample_functions向量是一個簡單的NULL結束向量, 它會隨著你向擴充中增加功能而變大. 每個你要暴露出去的函數都需要在這個向量中給出說明. 展開PHP_FE()宏如下:

{ "sample_hello_world", zif_sample_hello_world, NULL},

這樣提供了新函數的名字, 以及指向它的實現函數的指標. 這裡第三個參數用於提供暗示資訊, 比如某些參數需要引用傳值. 在第7章"接受參數"你將看到這個特性.

現在, 你有了一個要暴露的函數列表, 但是仍然沒有串連到引擎. 這通過對sample.c的最後一個修改完成, 將你的sample_module_entry結構體中的NULL, /* Functions */一行用php_sample_functions替換(請確保留下那個逗號).

現在, 通過前面介紹的方式重新構建, 使用php命令列的-r選項進行測試, -r允許你不用建立檔案直接在命令列運行簡單的程式碼片段:

$ php -r 'sample_hello_world();

如果一切OK的話, 你將會看到輸出"Hello World!". 恭喜!!!

Zend內建函式

內建函式名首碼"zif_"是"Zend內建函式"的命名標準, 它用來避免可能的符號衝突. 比如, 使用者空間的strlen()函數並沒有實現為void strlen(INTERNAL_FUNCTION_PARAMETERS), 因為它會和C庫的strlen衝突.

zif_的首碼也並不能完全避免名字衝突的問題. 因此, php提供了可以使用任意名字定義內建函式的宏: PHP_NAMED_FUNCTION(); 例如PHP_NAMED_FUNCTION(zif_sample_hello_world)等同於前面使用的PHP_FUNCTION(sample_hello_world)

當使用PHP_NAMED_FUNCTION定義實現時, 在function_entry向量中, 可以對應使用PHP_NAMED_FE()宏. 因此, 如果你定義了自己的函數PHP_NAMED_FUNCTION(purplefunc), 就要使用PHP_NAMED_FE(sample_hello_world, purplefunc, NULL), 而不是使用PHP_FE(sample_hello_world, NULL).

我們可以在ext/standard/file.c中查看fopen()函數的實現, 它實際上使用PHP_NAMED_FUNCTION(php_if_fopen)定義.從使用者空間角度來看, 它並不關心函數是什麼東西, 只是簡單的調用fopen().

函數別名

有時一個函數可能會有不止一個名字. 回想一下, 普通的函數內部定義是使用者空間函數名加上zif_首碼, 我們可以看到用PHP_NAMED_FE()宏可以很容易的建立這個可選映射.

PHP_FE(sample_hello_world,    NULL)  PHP_NAMED_FE(sample_hi,    zif_sample_hello_world,     NULL)

PHP_FE()宏將使用者空間函數名sample_hello_world和PHP_FUNCTION(sample_hello_world)展開而來的zif_sample_hello_world關聯起來. PHP_NAMED_FE()宏則將使用者空間函數名sample_hi和同一個內部實現關聯起來.

現在, 假設Zend引擎發生了一個大的變更, 內建函式的首碼從zif_修改為pif_了. 這個時候, 你的擴充就不能工作了, 因為當到達PHP_NAMED_FE()時, 發現zif_sample_hello_world沒有定義.

這種情況並不常見, 但非常麻煩, 可以使用PHP_FNAME()宏展開sample_hello_world避免這個問題:

PHP_NAMED_FE(sample_hi, PHP_FNAME(sample_hello_world), NULL)

這種情況下, 即便函數首碼被修改, 擴充的zend_function_entry也會使用宏擴充自動的更新.

現在, 你這樣做已經可以工作了, 但是我們已經不需要這樣做了. php暴露了另外一個宏, 專門設計用於建立函數別名. 前面的例子可以如下重寫:

PHP_FALIAS(sample_hi, sample_hello_world, NULL)

實際上這是官方的建立函數別名的方法, 在php源碼樹中你時常會看到它.

小結

本章你建立了一個簡單的可工作的php擴充, 並學習了在主要平台上構建它需要的步驟. 在以後的章節中, 你將會繼續豐滿這個擴充, 最終讓它包含php的所有特性.

php源碼樹和它編譯/構建在各個平台上依賴的工具經常會發生變化, 如果本章介紹的某些地方不能正常工作, 請參考php.net線上手冊的Installation一掌, 查看你使用的版本的特殊需求.

以上就是 [翻譯][php擴充開發和嵌入式]第5章-您的第一個擴充的內容，更多相關內容請關注topic.alibabacloud.com（www.php.cn）！

