PHP 擴展開發：zend_parse_parameters 參數解析與自動型別轉換全解析

擴展函式接收參數核心 API：zend_parse_parameters()。本文詳細解析格式字串、型別對應 C 資料型別、自動轉換規則、可選參數與錯誤處理模式。

函式原型

int zend_parse_parameters(int num_args TSRMLS_DC, const char *type_spec, ...);

• num_args：通常傳 ZEND_NUM_ARGS()（實際傳入參數數）。
• TSRMLS_DC：執行緒安全宏（ZTS 環境必需）。
• type_spec：格式字串，描述期望參數型別與屬性。
• ...：對應型別的 C 變數位址（輸出參數）。

基礎型別格式字元對照表

修飾字元

實戰範例

1. 單一必要整數參數

PHP_FUNCTION(sample_getlong) {
    long num;
    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", &num) == FAILURE) {
        RETURN_NULL();
    }
    php_printf("Received integer: %ld\n", num);
    RETURN_TRUE;
}

2. 字串 + 可選整數參數

PHP_FUNCTION(sample_greet) {
    char *name;
    int name_len;
    long times = 1;  // 預設值
    
    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s|l", &name, &name_len, ×) == FAILURE) {
        RETURN_NULL();
    }
    
    for (long i = 0; i < times; i++) {
        php_printf("Hello, %s!\n", name);
    }
    RETURN_TRUE;
}

3. 允許 NULL 的資源參數

PHP_FUNCTION(sample_process_resource) {
    zval *res = NULL;
    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "r!", &res) == FAILURE) {
        RETURN_NULL();
    }
    if (res == NULL) {
        php_printf("No resource provided\n");
    } else {
        // 處理資源
    }
    RETURN_TRUE;
}

型別自動轉換規則

• 呼叫端傳入 123 (Integer)，格式 "d" → 自動轉為 123.0 (double)。
• 呼叫端傳入 "456" (String)，格式 "l" → 自動轉為 456 (long)。
• 呼叫端傳入 1.5 (Float)，格式 "l" → 截斷為 1 (long)。
• 無法轉換（如 array 轉 long）→ 返回 FAILURE，拋出 Warning。

重要型別對應表（嚴格遵守）

錯誤處理模式

if (zend_parse_parameters(...) == FAILURE) {
    // 參數不匹配，引擎已拋出 Warning
    RETURN_NULL();  // 或 RETURN_FALSE，視語意而定
}
// 參數解析成功，繼續業務邏輯

原則：解析失敗時**直接返回**，不要繼續執行後續邏輯。