為什麼寫 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
};
內存管理鐵律
| 操作 | 宏/函數 | 說明 |
| 分配 | emalloc(), ecalloc(), estrdup(), safe_emalloc() | 請求結束自動釋放 |
| 釋放 | efree() | 配對使用 |
| 持久化分配 | pemalloc(size, 1) | 進程生命週期,需手動釋放 |
| 字符串返回 | RETURN_STRING(), RETURN_STR(), RETVAL_STRINGL() | 引擎接管內存 |
| 數組返回 | array_init(), add_assoc_*(), add_next_index_*() | 返回前 RETURN_ARR() |
除錯技巧
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
現代替代方案對比
| 方案 | 性能 | 開發難度 | 部署複雜度 | 適用場景 |
| C 擴展 | 最高 | 高 (C、Zend API) | 高 (編譯、版本綁定) | 核心熱點、綁定成熟 C 庫 |
| FFI (PHP 7.4+) | 中 (有調用開銷) | 低 (純 PHP 聲明) | 低 (無編譯、共享 .so) | 調用系統庫、快速原型、插件系統 |
| Swoole/Workerman | 高 (協程異步) | 中 (PHP 代碼) | 中 (擴展/Phar) | 高併發服務器、長連接、異步 I/O |
| PHP 原生 + OPcache/JIT | 中高 (PHP 8 JIT) | 最低 | 最低 | 大多數業務邏輯、非極致性能敏感 |
總結
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