PHP 知識卡 on Tarragon

SAPI（Server API）

Mon, 05 Oct 2026 00:00:00 +0800

SAPI（Server API）是 PHP 核心與外部環境之間的介面層：它把外部環境帶來的請求翻譯成 PHP 認得的形式（填好 $_SERVER、$_GET，把請求內容交給 php://input），再把 PHP 的輸出與回應標頭交回外部環境。同一份 PHP 核心配上不同的 SAPI，就是不同的執行方式。可先對照 Shared-nothing 請求模型與 PHP-FPM。

概念位置

SAPI 位在 PHP 核心（Zend 引擎與擴充）與 web 伺服器、命令列之間。它決定 PHP 直譯器住在哪個程序、那個程序活多久，這兩件事又決定 OPcache 有沒有編譯結果可以重用。mod_php 是 SAPI 的一種（apache2handler），PHP-FPM 是另一種（fpm-fcgi）。

可觀察訊號與例子

讀目前的 SAPI：程式裡的 PHP_SAPI 常數或 php_sapi_name()。命令列執行是 cli，PHP-FPM 是 fpm-fcgi，mod_php 是 apache2handler，php-cgi 是 cgi-fcgi，FrankenPHP 是 frankenphp。
同一支程式、兩種行為：php-cgi 被 web 伺服器以 CGI 啟動時處理一個請求就結束，以 FastCGI 模式啟動時常駐，SAPI 名稱都是 cgi-fcgi。
設定檔依 SAPI 分開：很多發行版把 php.ini 分成 cli/ 與 fpm/ 兩份，命令列改的設定不影響網頁請求。

設計責任

部署時要先知道服務跑的是哪個 SAPI，因為程序壽命、執行帳號、設定檔位置與 .htaccess 能不能改 PHP 設定都跟著它變。完整的比較見 PHP 的請求生命週期與 SAPI。

Shared-nothing 請求模型

Mon, 05 Oct 2026 00:00:00 +0800

Shared-nothing 請求模型的核心概念是「每個請求結束時，PHP 清空這個請求裡由 PHP 程式碼建立的全部狀態」：全域變數、函式內的 static 變數、類別的靜態屬性、物件與一般的資源都在請求結束時釋放，下一個請求從空白開始，即使由同一個程序處理。可先對照 SAPI 與 OPcache。

概念位置

Shared-nothing 是 PHP 傳統執行方式（CGI、mod_php、PHP-FPM）共有的狀態壽命：程序可能活過很多請求，狀態只活一個請求。它清的是 PHP 程式碼建立的狀態，程序層的資源（OPcache、持久連線、APCu）不在範圍內。常駐 worker 模型（FrankenPHP 的 worker 模式、Laravel Octane）放棄了它。

可觀察訊號與例子

同一個 PID、計數器仍是 1：在 PHP-FPM 下對一支每次把 static 變數加一的腳本連續請求，同一個 worker 處理第二次時計數器仍然是 1。
常駐 worker 下計數器累加：同一段程式碼放進 Octane 或 FrankenPHP worker，計數器變成 1、2、3……，往靜態陣列塞資料的程式會讓記憶體隨請求數線性增長。
框架每個請求重新啟動：Laravel 這類框架每個請求都要重建服務容器、讀設定、建路由表，這段成本是 shared-nothing 的代價。

設計責任

在 shared-nothing 下，程式可以放心把請求資料放在靜態屬性裡；要換成常駐 worker 之前，這類寫法都要改掉。實測與要避開的寫法見常駐 worker 模型。

mod_php

Mon, 05 Oct 2026 00:00:00 +0800

mod_php 是編譯成 Apache 模組的 PHP，Apache 啟動時用 LoadModule 載入，之後 Apache 的每個子程序裡都有一份 PHP 直譯器，收到 .php 請求就在自己的程序裡執行。它的 SAPI 名稱是 apache2handler。可先對照 PHP-FPM 與 Apache MPM。

概念位置

mod_php 把直譯器放進 web 伺服器的程序裡：省掉 CGI 每請求啟動程序的成本，代價是 PHP 的壽命、執行帳號與設定都綁在 Apache 上。沒有以 ZTS 編譯的 mod_php 只能搭配 prefork MPM。PHP 官方文件對新部署的建議是改用 PHP-FPM 搭配 Apache 的 mod_proxy_fcgi。

可觀察訊號與例子

apache2ctl -M 列出 php_module 與 mpm_prefork_module：多數發行版的 mod_php 沒有開 ZTS，php -i 顯示 Thread Safety => disabled。
送靜態檔的子程序也映射著 libphp：每個子程序都帶著 PHP，不論它在處理什麼請求。
所有站台以 Apache 的帳號（如 www-data）執行：PHP 產生的檔案屬於這個帳號。
.htaccess 的 php_value：mod_php 註冊了這個指令；沒載入 mod_php 的 Apache 讀到它會回 500（Invalid command 'php_value'），而且整個目錄都壞掉。

設計責任

從 mod_php 搬到 PHP-FPM 時，.htaccess 裡的 php_value / php_flag 要移到 .user.ini（見 php.ini / .user.ini）。完整的行為與實測見 mod_php。

ZTS（Zend Thread Safety）

Mon, 05 Oct 2026 00:00:00 +0800

ZTS（Zend Thread Safety）是 PHP 的編譯選項（--enable-zts）：開啟之後，PHP 把每個請求的狀態放在各執行緒自己的儲存區，而不是全域變數裡，多個執行緒才能同時執行 PHP 而不互相覆寫。沒有開 ZTS 的版本叫 NTS（Non Thread Safe）。可先對照 mod_php 與 SAPI。

概念位置

ZTS 決定 PHP 能不能住在一個多執行緒的程序裡。PHP 跑在獨立程序裡的執行方式（CGI、PHP-FPM）不需要它，每個 worker 一次只處理一個請求；PHP 嵌在多執行緒伺服器裡時需要它：mod_php 要搭配 Apache 的 worker 或 event MPM、FrankenPHP 用執行緒當 worker。

可觀察訊號與例子

php -i | grep "Thread Safety"：php:8.5-apache 與 php:8.5-fpm-alpine 是 disabled，FrankenPHP 映像檔是 enabled。
mod_php 只能用 prefork：PHP 官方安裝文件寫明，除非以 --enable-zts 編譯，mod_php 需要 prefork MPM。
擴充也要支援：PHP 能以執行緒安全的方式執行，不代表每個擴充與它依賴的 C 函式庫都能。

設計責任

選執行模型時，ZTS 是前提條件之一：要讓 Apache 用執行緒、或採用 FrankenPHP，就要拿到 ZTS 版的 PHP 與相容的擴充。不需要執行緒時，NTS 版本較常見、擴充相容性也較好。

PHP-FPM（FastCGI Process Manager）

Mon, 05 Oct 2026 00:00:00 +0800

PHP-FPM 是 PHP 內建的 FastCGI 程序管理器：一個 master 程序加一群常駐的 worker，master 負責讀設定、開 worker、補死掉的 worker 與處理訊號，worker 實際執行 PHP，透過 FastCGI 協定接收 web 伺服器轉來的請求。它的 SAPI 名稱是 fpm-fcgi。可先對照 mod_php 與 OPcache。

概念位置

PHP-FPM 把直譯器放在 web 伺服器外面的常駐程序裡：程序活過很多請求，應用程式狀態仍然只活一個請求（shared-nothing）。它只講 FastCGI，所以前面一定要有一個講 HTTP 的 web 伺服器（nginx 或 Apache 的 mod_proxy_fcgi）。PHP 5.3.3 起隨 PHP 本體發行。

可觀察訊號與例子

pm.max_children 決定並發上限：一個 worker 一次處理一個請求，超過上限的請求排隊，status 頁的 max listen queue 會大於 0。
502 加上「Connection reset by peer」：worker 被 request_terminate_timeout 終止、或 reload／停機時沒有等進行中的請求（process_control_timeout 預設 0）。
預設監聽 9000：FastCGI 沒有驗證，PHP 官方文件要求 php-fpm 不能讓不受信任的網路連到。
pool：每個 pool 可以指定執行帳號，讓不同站台的 PHP 互相讀不到檔案。

設計責任

部署 PHP-FPM 要決定 max_children（以最重請求的記憶體峰值估）、max_requests、request_terminate_timeout 與 process_control_timeout，並把 FastCGI 埠限制在信任的網路內。各設定的實測見 PHP-FPM。

OPcache

Mon, 05 Oct 2026 00:00:00 +0800

OPcache 是 PHP 內建的擴充，把 PHP 檔案編譯好的 opcode（Zend 引擎執行的指令）存進共享記憶體，之後執行同一個檔案時跳過讀檔與編譯。它快取的是程式碼的編譯結果，不是資料。可先對照 PHP-FPM 與 Shared-nothing 請求模型。

概念位置

OPcache 是程序層的資源，效果取決於執行 PHP 的程序活多久：CGI 每個請求一個新程序，快取永遠命中不了；PHP-FPM 與 mod_php 的父程序建立共享記憶體，所有 worker 共用同一份快取。PHP 8.5 起 OPcache 靜態編進 PHP 本體。它省掉的是編譯，框架每個請求的啟動流程它省不掉，那一段要靠常駐 worker 模型。

可觀察訊號與例子

opcache_get_status() 的 hits：CGI 下永遠是 0；PHP-FPM 下跨 worker 累加。
改了檔案頁面不變：opcache.validate_timestamps=0 時 OPcache 不檢查檔案，要 reload PHP-FPM 才生效；預設的 validate_timestamps=1、revalidate_freq=2 下，改檔後最多約 2 秒生效。
開與關的差距：Laravel 13 骨架的健康檢查請求，開 OPcache 約 3.8 ms、關掉約 49.3 ms。
快取滿了不報錯：放不進去的檔案每次重新編譯，從外面看只是變慢；要讀 free_memory 與 num_cached_scripts。

設計責任

部署要配合 validate_timestamps 的設定：程式碼在映像檔裡的容器部署可以關掉檢查，覆寫檔案的部署要留著或在換完程式碼後 reload。memory_consumption 與 max_accelerated_files 依實際專案跑過主要請求後的統計調整。詳見 OPcache 與程序壽命。