PHP 擴展開發：函式回傳值機制與 RETURN_VALUE 宏詳解

PHP 內部函式不直接 return zval*，而是由 Zend 引擎預先分配 return_value 參數，擴展僅需填充該 zval。本文解析回傳值機制、ZVAL_* 與 RETVAL_* 宏家族用法。

核心機制：return_value 參數

// 錯誤示範：手動分配 zval 並 return
PHP_FUNCTION(sample_wrong) {
    zval *retval;
    MAKE_STD_ZVAL(retval);
    ZVAL_LONG(retval, 42);
    return retval;  // 錯誤！引擎不接收回傳值
}

// 正確示範：填充預分配的 return_value
PHP_FUNCTION(sample_long) {
    ZVAL_LONG(return_value, 42);
    return;  // 無需回傳值
}

ZVAL_LONG 宏展開

// 等價於：
Z_TYPE_P(return_value) = IS_LONG;
Z_LVAL_P(return_value) = 42;

// 或直接存取：
return_value->type = IS_LONG;
return_value->value.lval = 42;

注意：return_value 的 refcount、is_ref 由引擎管理，**擴展不可直接修改**。

RETVAL_* 宏家族：省略 return_value 參數

實戰範例：整合到 sample 擴展

// sample.c 新增函式
PHP_FUNCTION(sample_long) {
    RETVAL_LONG(42);
    return;
}

PHP_FUNCTION(sample_hello_world) {
    RETVAL_STRING("Hello World!", 1);
    return;
}

// function_entry 陣列註冊
static function_entry php_sample_functions[] = {
    PHP_FE(sample_hello_world, NULL)
    PHP_FE(sample_long, NULL)
    {NULL, NULL, NULL}
};

重新編譯測試

make clean && make && make install
php -r 'var_dump(sample_long());'
// 輸出: int(42)

php -r 'var_dump(sample_hello_world());'
// 輸出: string(12) "Hello World!"

進階：回傳陣列與物件

PHP_FUNCTION(sample_array) {
    array_init(return_value);
    add_assoc_long(return_value, "id", 1);
    add_assoc_string(return_value, "name", "test", 1);
    add_next_index_long(return_value, 100);
    // 無需 return，return_value 已填充
}

關鍵 API：array_init()、add_assoc_*()、add_next_index_*()、add_index_*()。

1. 上一篇文章： 編寫第一個 PHP 擴展：從骨架到編譯載入完整流程
2. 下一篇文章： PHP 擴展開發：zend_parse_parameters 參數解析與自動型別轉換全解析

PHP 綜合知識

Laravel 4 安裝入門圖文教學

一、安裝 Composer 首先需安裝 Composer，P

ThinkPHP 2.2 文檔未提及的 5 大實戰坑位與解決方案

前言 ThinkPHP 2.2 官方文檔較精簡，實際開發中常

PHP Session 機制完整指南：從原理到安全最佳實踐

Session 運作原理 session_start()

Laravel 5.1 資料庫連線、遷移建表、Model 與 Controller 建立完整流程

前言 Laravel 5.1 作為長期支援版本（LTS），提