PHP 5 自定義擴充模組開發完整教學：從 WebService 客戶端到 .so 動態庫

將現有 C/C++ 程式庫（如 WebService 客戶端）封裝為 PHP 擴充模組，能大幅提升效能並複用既有邏輯。本文記錄從原始碼改造、建置環境配置、模組骨架生成、函數實作到編譯測試的完整流程。

前置準備

1. 將既有程式的 main() 改為 testPhpModule()，將輸出改為回傳字串
2. 編譯生成動態庫 libTest.so，複製至 /usr/lib
3. 執行 /sbin/ldconfig 更新動態連結器快取
4. 準備 PHP 原始碼並解壓縮

步驟一：生成模組骨架

cd php-src/ext
./ext_skel --extname=Test
cd Test

生成標準目錄結構，核心檔案：config.m4、Test.c、php_Test.h。

步驟二：配置 config.m4

編輯 config.m4，啟用 --enable-Test 選項（動態載入建議用 enable）：

# 修改前（被 dnl 註解）
dnl PHP_ARG_ENABLE(Test, whether to enable Test support,
dnl [  --enable-Test           Enable Test support])

# 修改後（移除 dnl）
PHP_ARG_ENABLE(Test, whether to enable Test support,
[  --enable-Test           Enable Test support])

步驟三：編寫 PHP 函數進入點

編輯 Test.c，在 zend_function_entry Test_functions[] 陣列註冊函數：

zend_function_entry Test_functions[] = {
    PHP_FE(confirm_Test_compiled, NULL)  // 測試用，後續可移除
    PHP_FE(test, NULL)                   // 新增：對應 PHP 呼叫的 test() 函數
    {NULL, NULL, NULL}
};

檔案末尾實作 PHP_FUNCTION(test)：

PHP_FUNCTION(test) {
    RETURN_STRING(testPhpModule());  // 呼叫前置編譯好的 C 函數
}

步驟四：編譯安裝

# 配置（指定 php-config 路徑）
./configure --with-php-config=/usr/local/php/bin/php-config

# 編譯（鏈接 libTest.so）
make LDFLAGS=-lTest

# 測試
make test

步驟五：部署與驗證

1. 複製編譯產出的 modules/Test.so 至 Apache 擴充目錄（如 /usr/local/apache2/htdocs/）
2. 建立測試腳本 test.php：

   <?php
       dl("Test.so");  // 動態載入（PHP 7.2+ 已移除 dl()，建議改用 php.ini extension=Test.so）
       echo test();
   ?>

3. 啟動 Apache，瀏覽器訪問 test.php，應顯示原 main() 的輸出內容

關鍵提醒

• PHP 版本相容：PHP 5 系列適用 dl()；PHP 7/8 建議修改 php.ini 永久載入
• 記憶體管理：RETURN_STRING 會複製字串，若 C 函數回傳動態分配記憶體，需自行釋放避免洩漏
• 錯誤處理：C 層錯誤建議回傳錯誤碼或空字串，PHP 層再拋出 Exception
• 執行緒安全：若 Apache 採用 Worker MPM，擴充模組必須是執行緒安全的（TSRM）

掌握 PHP 擴充開發，能讓你將高效能 C/C++ 演算法、既有商業邏輯庫無縫整合進 PHP 應用，是效能優化與技術棧整合的利器。