PHP 嵌入式 SAPI 宿主環境建置完整指南

PHP 嵌入式 SAPI 允許外部 C/C++ 應用程式直接呼叫 PHP 引擎執行腳本，適用於需要動態腳本能力的桌面軟體、遊戲引擎或專用伺服器。本文詳細說明從編譯嵌入式庫到建立宿主應用的完整流程。

編譯嵌入式 PHP 庫

./configure --enable-embed [--enable-debug] [--enable-maintainer-zts]
make && make install

產出 libphp5.so（或 Windows DLL）與 php_embed.h 頭文件，預設安裝至 $PREFIX/lib/ 與 $PREFIX/include/php/sapi/embed/。

ZTS (Zend Thread Safety) 選擇指南

• 單執行緒、短生命週期應用：關閉 ZTS 以獲取效能
• 多執行緒伺服器（如 Web Server）：必須啟用 ZTS，確保各執行緒獨立請求上下文
• 可同時建構兩版本並以不同名稱區分

最小宿主應用範例

#include <sapi/embed/php_embed.h>
int main(int argc, char *argv[]) {
    PHP_EMBED_START_BLOCK(argc, argv)
    PHP_EMBED_END_BLOCK()
    return 0;
}

編譯宿主應用

gcc -I /usr/local/php-dev/include/php/ \
    -I /usr/local/php-dev/include/php/main/ \
    -I /usr/local/php-dev/include/php/Zend/ \
    -I /usr/local/php-dev/include/php/TSRM/ \
    -lphp5 -o embed1 embed1.c

建議撰寫 Makefile 分離編譯與連結階段，並啟用 -Wall -g 便於除錯。靜態庫版本（--enable-embed=static）可避免 ZTS 衝突但會顯著增加二進制體積。