1. zend_parse_parameters · PHP擴展開發及內核應用

# 7.1 函數的參數最簡單的獲取函數調用者傳遞過來的參數便是使用zend_parse_parameters()函數。 zend_parse_parameters()函數的前幾個參數我們直接用內核里宏來生成便可以了，形式為：ZEND_NUM_ARGS() TSRMLS_CC，注意兩者之間有個空格，但是沒有逗號。從名字可以看出，ZEND_NUM_ARGS()代表著參數的個數。緊接著需要傳遞給zend_parse_parameters()函數的參數是一個用于格式化的字符串，就像printf的第一個參數一樣。下面表示了最常用的幾個符號。 ````c type_spec是格式化字符串，其常見的含義如下：參數代表著的類型 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**類型 f 表示函數、方法名稱，PHP5.1里貌似木有... ... ```` 這個函數就像printf()函數一樣，后面的參數是與格式化字符串里的格式一一對應的。一些基礎類型的數據會直接映射成C語言里的類型。 ````c ZEND_FUNCTION(sample_getlong) { long foo; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC,"l", &foo) == FAILURE) { RETURN_NULL(); } php_printf("The integer value of the parameter is: %ld\n", foo); RETURN_TRUE; } ```` 一般來說，int和long這兩種數據類型的數據往往是相同的，但也有例外情況。所以我們不應改把long的數組放在一個int里，尤其是在64位平臺里，那將引發一些不容易排查的Bug。所以通過zend_parse_parameter()函數接收參數時，我們應該使用內核約定好的那些類型的變量作為載體。 ````c 參數對應C里的數據類型 b zend_bool l long d double s char*, int 前者接收指針，后者接收長度 r zval* a zval* o zval* O zval*, zend_class_entry* z zval* Z zval** ```` 注意，所有的PHP語言中的復合類型參數都需要zval*類型來作為載體，因為它們都是內核自定義的一些數據結構。我們一定要確認參數和載體的類型一致，如果需要，它可以進行類型轉換，比如把array轉換成stdClass對象。 s和O(字母大寫歐)類型需要單獨說一些，因為它們都需要兩個載體。我們將在接下來的章節里了解php中對象的具體實現。這樣我們改寫一下我們在第五章定義的一個函數： ````php <?php function sample_hello_world($name) { echo "Hello $name!\n"; } ```` 在編寫擴展時，我們需要用zend_parse_parameters()來接收這個字符串: ````c ZEND_FUNCTION(sample_hello_world) { char *name; int name_len; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s",&name, &name_len) == FAILURE) { RETURN_NULL(); } php_printf("Hello "); PHPWRITE(name, name_len); php_printf("!\n"); } ```` <div class="tip-warning"> 如果傳遞給函數的參數數量小于zend_parse_parameters()要接收的參數數量，它便會執行失敗，并返回FAILURE。 </div> 如果我們需要接收多個參數，可以直接在zend_parse_paramenters()的參數里羅列接收載體便可以了，如： ````php <?php function sample_hello_world($name, $greeting) { echo "Hello $greeting $name!\n"; } sample_hello_world('John Smith', 'Mr.'); ```` 在PHP擴展里應該這樣來實現： ````c ZEND_FUNCTION(sample_hello_world) { char *name; int name_len; char *greeting; int greeting_len; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "ss",&name, &name_len, &greeting, &greeting_len) == FAILURE) { RETURN_NULL(); } php_printf("Hello "); PHPWRITE(greeting, greeting_len); php_printf(" "); PHPWRITE(name, name_len); php_printf("!\n"); } ```` 除了上面定義的參數，還有其它的三個參數來增強我們接收參數的能力,如下： ````c Type Modifier Meaning | 它之前的參數都是必須的，之后的都是非必須的，也就是有默認值的。 ! 如果接收了一個PHP語言里的null變量，則直接把其轉成C語言里的NULL，而不是封裝成IS_NULL類型的zval。 / 如果傳遞過來的變量與別的變量共用一個zval，而且不是引用，則進行強制分離，新的zval的is_ref__gc==0, and refcount__gc==1. ```` ### 函數參數的默認值現在讓我們繼續改寫sample_hello_world(), 接下來我們使用一些參數的默認值，在php語言里就像下面這樣： ````php <?php function sample_hello_world($name, $greeting='Mr./Ms.') { echo "Hello $greeting $name!\n"; } sample_hello_world('Ginger Rogers','Ms.'); sample_hello_world('Fred Astaire'); ```` 此時即可以只向sample_hello_world中傳遞一個參數，也可以傳遞完整的兩個參數。那同樣的功能我們怎樣在擴展函數里實現呢？我們需要借助zend_parse_parameters中的(|)參數，這個參數之前的參數被認為是必須的，之后的便認為是非必須的了,如果沒有傳遞，則不會去修改載體。 ````c ZEND_FUNCTION(sample_hello_world) { char *name; int name_len; char *greeting = "Mr./Mrs."; int greeting_len = sizeof("Mr./Mrs.") - 1; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s|s", &name, &name_len, &greeting, &greeting_len) == FAILURE) { RETURN_NULL(); } php_printf("Hello "); PHPWRITE(greeting, greeting_len); php_printf(" "); PHPWRITE(name, name_len); php_printf("!\n"); } ```` 如果你不傳遞第二個參數，則擴展函數會被認為默認而不去修改載體。所以，我們需要自己來預先設置有載體的值，它往往是是NULL，或者一個與函數邏輯有關的值。每個zval，包括IS_NULL型的zval，都需要占用一定的內存空間，并且需要cpu的計算資源來為它申請內存、初始化，并在它們完成工作后釋放掉。但是很多代碼都都沒有意識到這一點。有很多代碼都會把一個null型的值包裹成zval的IS_NULL類型，在擴展開發里這種操作是可以優化的，我們可以把參數接收成C語言里的NULL。我們就這一個問題看以下代碼： ````c ZEND_FUNCTION(sample_arg_fullnull) { zval *val; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "z",&val) == FAILURE) { RETURN_NULL(); } if (Z_TYPE_P(val) == IS_NULL) { val = php_sample_make_defaultval(TSRMLS_C); } ... } ZEND_FUNCTION(sample_arg_nullok) { zval *val; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "z!",&val) == FAILURE) { RETURN_NULL(); } if (!val) { val = php_sample_make_defaultval(TSRMLS_C); } } ```` 這兩段代碼乍看起來并沒有什么很大的不同，但是第一段代碼確實需要更多的cpu和內存資源。可能這個技巧在平時并沒多大用，不過技多不壓身，知道總比不知道好。 ### Forced Separation 當一個變量被傳遞給函數時候，無論它是否被引用，它的refcoung__gc屬性都會加一，至少成為2。一份是它自己，另一份是傳遞給函數的copy。在改變這個zval之前，有時會需要提前把它分成實際意義上的兩份copy。這就是"/"格式符的作用。它將把寫時復制的zval提前分成兩個完整獨立的copy，從而使我們可以在下面的代碼中隨意的對其進行操作。否則我們可能需要不停的提醒自己對接收的參數進行分離等操作。Like the NULL flag, this modifier goes after the type it means to impact. Also like the NULL flag, you won't know you need this feature until you actually have a use for it. ### zend_get_arguments() 如果你想讓你的擴展能夠兼容老版本的PHP，或者你只想以zval*為載體來接收參數，便可以考慮使用zend_get_parameters()函數來接收參數。 zend_get_parameters()與zend_parse_parameters()不同，從名字上我們便可以看出，它直接獲取，而不做解析。首先，它不會自動進行類型轉換，所有的參數在擴展實現中的載體都需要是zval*類型的，下面讓我們來看一個最簡單的例子： ````c ZEND_FUNCTION(sample_onearg) { zval *firstarg; if (zend_get_parameters(ZEND_NUM_ARGS(), 1, &firstarg)== FAILURE) { php_error_docref(NULL TSRMLS_CC, E_WARNING,"Expected at least 1 parameter."); RETURN_NULL(); } /* Do something with firstarg... */ } ```` 其次，zend_get_parameters()在接收失敗的時候，并不會自己拋出錯誤，它也不能方便的處理具有默認值的參數。最后一點與zend_parse_parameters不同的是，它會自動的把所有符合copy-on-write的zval進行強制分離，生成一個嶄新的copy送到函數內部。如果你希望用它其它的特性，而唯獨不需要這個功能，可以去嘗試一下用zend_get_parameters_ex()函數來接收參數。為了不對copy-on-write的變量進行分離操作，zend_get_parameters_ex()的參數是zval**類型的，而不是zval*。這個函數不太經常用，可能只會在你碰到一些極端問題時候才會想到它，而它用起來卻很簡單： ````c ZEND_FUNCTION(sample_onearg) { zval **firstarg; if (zend_get_parameters_ex(1, &firstarg) == FAILURE) { WRONG_PARAM_COUNT; } /* Do something with firstarg... */ } ```` <div class="tip-common"> 注意zend_get_parameters_ex不需要ZEND_NUM_ARGS()作為參數，因為它是在是在后期加入的，那個參數已經不再需要了。 </div> 上面例子中還使用了WRONG_PARAM_COUNT宏,它的功能是拋出一個E_WARNING級別的錯誤信息，并自動return。 ### 可變參數有兩種其它的zend_get_parameter_**函數，專門用來解決參數很多或者無法提前知道參數數目的問題。想一下php語言中var_dump()函數的用法，我們可以向其傳遞任意數量的參數，它在內核中的實現其實是這樣的： ````c ZEND_FUNCTION(var_dump) { int i, argc = ZEND_NUM_ARGS(); zval ***args; args = (zval ***)safe_emalloc(argc, sizeof(zval **), 0); if (ZEND_NUM_ARGS() == 0 || zend_get_parameters_array_ex(argc, args) == FAILURE) { efree(args); WRONG_PARAM_COUNT; } for (i=0; i<argc; i++) { php_var_dump(args[i], 1 TSRMLS_CC); } efree(args); } ```` 程序首先獲取參數數量，然后通過safe_emalloc函數申請了相應大小的內存來存放這些zval**類型的參數。這里使用了zend_get_parameters_array_ex()函數來把傳遞給函數的參數填充到args中。你可能已經立即想到，還存在一個名為zend_get_parameters_array()的函數，唯一不同的是它將zval*類型的參數填充到args中，并且需要ZEND_NUM_ARGS()作為參數。 ## links * 6.3 [第六章小結](<6.3.md>) * 7.2 [Arg Info 與類型綁定](<7.2.md>)