萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 調用 C/C++ 擴展開發指南:從 .so 構建到生產部署

為什麼寫 PHP C 擴展?

  • 性能關鍵路徑:密集計算 (圖像處理、加密、壓縮、解析) 可提升 10x-100x
  • 複用現有 C 庫:OpenSSL、libcurl、FFmpeg、LevelDB、SQLite 等
  • 系統級能力:底層網絡、文件系統、進程控制、共享內存
  • 語言互操作:為 PHP 提供 Rust/Go/C++ 庫的綁定 (FFI 替代方案)

開發流程總覽


┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ 1. 骨架生成  │───▶│ 2. 編寫 C 代碼 │───▶│ 3. 編譯 .so  │───▶│ 4. 測試/部署  │
│ ext_skel    │    │ php_*.h/*.c  │    │ phpize/make │    │ dl()/php.ini  │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

步驟 1:生成擴展骨架

# 進入 PHP 源碼 ext 目錄 (或安裝 php-dev 提供的 ext_skel)
cd /usr/src/php/ext
./ext_skel --extname=myext

# 生成目錄結構
myext/
├── config.m4          # Unix 構建配置
├── config.w32         # Windows 構建配置
├── myext.c            # 核心 C 代碼
├── php_myext.h        # 頭文件
├── tests/             # .phpt 測試文件
└── README.md

步驟 2:核心代碼實現

php_myext.h - 導出函數聲明

#ifndef PHP_MYEXT_H
#define PHP_MYEXT_H

#define PHP_MYEXT_VERSION "1.0.0"
#define PHP_MYEXT_EXTNAME "myext"

extern zend_module_entry myext_module_entry;
#define phpext_myext_ptr &myext_module_entry

// 函數聲明宏
PHP_FUNCTION(myext_hello);
PHP_FUNCTION(myext_fibonacci);
PHP_FUNCTION(myext_sha256);

#endif

myext.c - 核心實現

#include "php.h"
#include "php_myext.h"
#include   // 示例:鏈接 OpenSSL

// 函數參數解析宏
ZEND_BEGIN_ARG_INFO_EX(arginfo_myext_hello, 0, 0, 1)
    ZEND_ARG_TYPE_INFO(0, name, IS_STRING, 0)
ZEND_END_ARG_INFO()

ZEND_BEGIN_ARG_INFO_EX(arginfo_myext_fibonacci, 0, 0, 1)
    ZEND_ARG_TYPE_INFO(0, n, IS_LONG, 0)
ZEND_END_ARG_INFO()

ZEND_BEGIN_ARG_INFO_EX(arginfo_myext_sha256, 0, 0, 1)
    ZEND_ARG_TYPE_INFO(0, data, IS_STRING, 0)
    ZEND_ARG_TYPE_INFO(0, raw_output, _IS_BOOL, 1)  // 可選參數
ZEND_END_ARG_INFO()

// 函數表註冊
static const zend_function_entry myext_functions[] = {
    PHP_FE(myext_hello, arginfo_myext_hello)
    PHP_FE(myext_fibonacci, arginfo_myext_fibonacci)
    PHP_FE(myext_sha256, arginfo_myext_sha256)
    PHP_FE_END
};

// 模塊入口
zend_module_entry myext_module_entry = {
    STANDARD_MODULE_HEADER,
    PHP_MYEXT_EXTNAME,
    myext_functions,
    PHP_MINIT(myext),    // 模塊啟動
    PHP_MSHUTDOWN(myext),// 模塊關閉
    PHP_RINIT(myext),    // 請求啟動
    PHP_RSHUTDOWN(myext),// 請求關閉
    PHP_MINFO(myext),    // phpinfo() 顯示
    PHP_MYEXT_VERSION,
    STANDARD_MODULE_PROPERTIES
};

ZEND_GET_MODULE(myext)

// ===== 生命週期鉤子 =====
PHP_MINIT_FUNCTION(myext)
{
    // 註冊常數
    REGISTER_LONG_CONSTANT("MYEXT_VERSION", 10000, CONST_CS | CONST_PERSISTENT);
    return SUCCESS;
}

PHP_RINIT_FUNCTION(myext)
{
    // 請求級初始化 (如線程局部存儲)
    return SUCCESS;
}

PHP_RSHUTDOWN_FUNCTION(myext)
{
    // 請求級清理
    return SUCCESS;
}

PHP_MSHUTDOWN_FUNCTION(myext)
{
    // 模塊卸載清理
    return SUCCESS;
}

PHP_MINFO_FUNCTION(myext)
{
    php_info_print_table_start();
    php_info_print_table_header(2, "myext support", "enabled");
    php_info_print_table_row(2, "Version", PHP_MYEXT_VERSION);
    php_info_print_table_row(2, "OpenSSL support", "enabled");
    php_info_print_table_end();
}

// ===== 函數實現 =====
PHP_FUNCTION(myext_hello)
{
    char *name;
    size_t name_len;
    
    // 參數解析: "s" = string, "&" = 引用, "|" = 可選
    ZEND_PARSE_PARAMETERS_START(1, 1)
        Z_PARAM_STRING(name, name_len)
    ZEND_PARSE_PARAMETERS_END();
    
    // 返回字符串 (需手動內存管理)
    RETURN_STR(strpprintf(0, "Hello, %s!", name));
}

PHP_FUNCTION(myext_fibonacci)
{
    zend_long n;
    ZEND_PARSE_PARAMETERS_START(1, 1)
        Z_PARAM_LONG(n)
    ZEND_PARSE_PARAMETERS_END();
    
    if (n < 0 || n > 92) { // 92 為 64 位有符號整數溢出邊界
        zend_argument_value_error(1, "must be between 0 and 92");
        RETURN_THROWS();
    }
    
    // 迭代算法 O(n)
    unsigned long long a = 0, b = 1, c;
    for (zend_long i = 0; i < n; i++) {
        c = a + b;
        a = b;
        b = c;
    }
    RETURN_LONG(a);
}

PHP_FUNCTION(myext_sha256)
{
    char *data;
    size_t data_len;
    zend_bool raw_output = 0;
    
    ZEND_PARSE_PARAMETERS_START(1, 2)
        Z_PARAM_STRING(data, data_len)
        Z_PARAM_OPTIONAL
        Z_PARAM_BOOL(raw_output)
    ZEND_PARSE_PARAMETERS_END();
    
    unsigned char hash[SHA256_DIGEST_LENGTH];
    SHA256((unsigned char*)data, data_len, hash);
    
    if (raw_output) {
        RETURN_STRINGL((char*)hash, SHA256_DIGEST_LENGTH);
    } else {
        // 十六進制輸出
        char hex[SHA256_DIGEST_LENGTH * 2 + 1];
        for (int i = 0; i < SHA256_DIGEST_LENGTH; i++) {
            sprintf(hex + i * 2, "%02x", hash[i]);
        }
        RETURN_STRINGL(hex, 64);
    }
}

config.m4 - 構建配置 (關鍵:鏈接外部庫)

PHP_ARG_ENABLE(myext, whether to enable myext support,
[  --enable-myext          Enable myext support])

if test "$PHP_MYEXT" != "no"; then
    # 依賴 OpenSSL
    PHP_ADD_LIBRARY_WITH_PATH(ssl, , MYEXT_SHARED_LIBADD)
    PHP_ADD_LIBRARY_WITH_PATH(crypto, , MYEXT_SHARED_LIBADD)
    
    # 檢查頭文件
    PHP_CHECK_HEADERS([openssl/sha.h], [], [
        AC_MSG_ERROR([openssl/sha.h not found. Install libssl-dev.])
    ])
    
    PHP_NEW_EXTENSION(myext, myext.c, $ext_shared, , -DZEND_ENABLE_STATIC_TSRMLS_CACHE=1)
    PHP_SUBST(MYEXT_SHARED_LIBADD)
fi

步驟 3:編譯安裝

cd myext

# 1. 生成 configure (需 phpize、autoconf、automake、libtool)
phpize

# 2. 配置 (指定 php-config 路徑)
./configure --with-php-config=/usr/bin/php-config --enable-myext

# 3. 編譯
make -j$(nproc)

# 4. 安裝 (需 root)
sudo make install
# 輸出:Installing shared extensions: /usr/lib/php/20220829/myext.so

步驟 4:加載與測試

方式一:動態加載 (開發/測試)

<?php
// 僅當前請求生效
if (!extension_loaded('myext')) {
    dl('myext.so');  // 需 php.ini: enable_dl=On (CLI 默認 On)
}
var_dump(myext_hello('World'));
var_dump(myext_fibonacci(10));
var_dump(myext_sha256('test'));

方式二:php.ini 永久加載 (生產)

; /etc/php/8.2/cli/php.ini 或 fpm/php.ini
extension=myext.so

; 或具體路徑
extension=/usr/lib/php/20220829/myext.so
# 重載 PHP-FPM
sudo systemctl reload php8.2-fpm

# 驗證
php -m | grep myext
php -r "var_dump(myext_hello('PHP'));"

進階主題

類與對象導出

// 類聲明
zend_class_entry *myext_ce;

PHP_MINIT_FUNCTION(myext)
{
    zend_class_entry ce;
    INIT_CLASS_ENTRY(ce, "MyExt\\Calculator", myext_calculator_methods);
    myext_ce = zend_register_internal_class(&ce);
    
    // 靜態屬性
    zend_declare_property_long(myext_ce, "precision", 10, ZEND_ACC_PUBLIC | ZEND_ACC_STATIC);
    
    // 常數
    zend_declare_class_constant_long(myext_ce, "PI", 3141592653);
    return SUCCESS;
}

// 方法表
static const zend_function_entry myext_calculator_methods[] = {
    PHP_ME(MyExt\Calculator, add, arginfo_add, ZEND_ACC_PUBLIC)
    PHP_ME(MyExt\Calculator, mul, arginfo_mul, ZEND_ACC_PUBLIC)
    PHP_FE_END
};

內存管理鐵律

除錯技巧

  • gdb --args php test.php 斷點調試 C 代碼
  • valgrind --tool=memcheck php test.php 內存洩漏檢測
  • php -d zend_extension=xdebug.so -d xdebug.mode=develop test.php
  • 日誌:php_printf("DEBUG: %s\n", "msg"); 輸出到 stdout

現代替代方案對比

操作宏/函數說明
分配emalloc(), ecalloc(), estrdup(), safe_emalloc()請求結束自動釋放
釋放efree()配對使用
持久化分配pemalloc(size, 1)進程生命週期,需手動釋放
字符串返回RETURN_STRING(), RETURN_STR(), RETVAL_STRINGL()引擎接管內存
數組返回array_init(), add_assoc_*(), add_next_index_*()返回前 RETURN_ARR()

總結

C 擴展是 PHP 性能的終極武器,但維護成本極高 (PHP 版本升級需重新編譯、記憶體安全、跨平台編譯)。優先考慮:算法優化 → OPcache/JIT → FFI → Swoole 異步 → 最後才是 C 擴展。若必須編寫,嚴格遵循內存管理規範,編寫完整 .phpt 測試,接入 CI/CD 自動化編譯測試矩陣 (PHP 8.1/8.2/8.3、ZTS/non-ZTS)。

copyright © 萬盛學電腦網 all rights reserved
方案性能開發難度部署複雜度適用場景
C 擴展最高高 (C、Zend API)高 (編譯、版本綁定)核心熱點、綁定成熟 C 庫
FFI (PHP 7.4+)中 (有調用開銷)低 (純 PHP 聲明)低 (無編譯、共享 .so)調用系統庫、快速原型、插件系統
Swoole/Workerman高 (協程異步)中 (PHP 代碼)中 (擴展/Phar)高併發服務器、長連接、異步 I/O
PHP 原生 + OPcache/JIT中高 (PHP 8 JIT)最低最低大多數業務邏輯、非極致性能敏感