全部翻譯内容pdf文檔下載下傳位址: http://download.csdn.net/detail/lgg201/5107012
本書目前在github上由laruence(http://www.laruence.com)和walu(http://www.walu.cc)兩位大牛組織翻譯. 該翻譯項目位址為: https://github.com/walu/phpbook
原書名: <Extending and Embedding PHP>
原作者: Sara Golemon
譯者: goosman.lei(雷果國)
譯者Email: [email protected]
譯者Blog: http://blog.csdn.net/lgg201
你的第一個擴充
每一個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, 一行用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寫一個簡潔的登入頁面[圖]](data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=)