PHP 擴展開發入門指南：環境建置、原始碼結構與記憶體管理基礎

從零編寫 PHP C 擴展：完整流程與核心概念

PHP 擴展以 C 實作，提供原生效能、系統呼叫、庫整合能力。本文基於 Ubuntu 20.04 + PHP 8.1 示範基本開發流程。

1. 取得 PHP 原始碼並建置環境

sudo apt install php-dev build-essential libtool autoconf re2c
# 或下載原始碼
wget https://www.php.net/distributions/php-8.1.0.tar.gz
tar xzf php-8.1.0.tar.gz
cd php-8.1.0
./configure --enable-debug # 開發建議開啟 debug
make -j$(nproc)
sudo make install

2. 使用 ext_skel 產生擴展骨架

cd php-8.1.0/ext
./ext_skel --ext myext
cd myext
# 編輯 config.m4 加入 PHP_ARG_ENABLE(myext, ...)
phpize
./configure --enable-myext
make
sudo make install
# 在 php.ini 加入 extension=myext
php -m | grep myext

3. 核心檔案結構

• php_myext.h：模組入口宣告、函數原型、常數定義。
• myext.c：zend_module_entry 結構體、MINIT/RINIT/MSHUTDOWN/RSHUTDOWN/MINFO 生命週期鉤子、函數實作 (PHP_FUNCTION)。
• config.m4：Autoconf 腳本，偵測依賴、定義編譯選項。

4. 記憶體管理基礎 (Zend Memory Manager)

• emalloc/efree：請求級記憶體，請求結束自動釋放，防洩漏。
• pemalloc/pefree：持久記憶體 (persistent)，跨請求存活，需手動釋放。
• zval：PHP 變數容器，參考計數 (refcount) + 型別標籤，使用 ZVAL_* 宏操作。
• 參考計數規則：複製 zval 時 Z_ADDREF_P()，銷毀 zval_ptr_dtor() (PHP 7+) / zval_dtor() (PHP 5)。

5. 簡單函數實作範例

// myext.c
PHP_FUNCTION(myext_hello) {
    char *name;
    size_t name_len;
    if (zend_parse_parameters(ZEND_NUM_ARGS(), "s", &name, &name_len) == FAILURE) {
        RETURN_NULL();
    }
    char *greeting = emalloc(name_len + 8);
    snprintf(greeting, name_len + 8, "Hello %s", name);
    RETVAL_STRING(greeting);
    efree(greeting);
}
// 在 zend_function_entry 陣列註冊
const zend_function_entry myext_functions[] = {
    PHP_FE(myext_hello, arginfo_myext_hello)
    PHP_FE_END
};

6. 編譯、測試、除錯

make clean && make
php -r "echo myext_hello('World');"
// 使用 gdb 除錯
gdb --args php -r "myext_hello('test');"
# 設定斷點於 myext_hello

掌握基礎流程後，可進階學習類別封裝 (zend_class_entry)、物件處理、資源類型、非同步 I/O 整合等主題。