PHP 函數執行超時處理：register_shutdown_function 實現最大執行時間捕獲

PHP 函數執行超時處理：register_shutdown_function 實現最大執行時間捕獲

PHP 腳本受 max_execution_time (默認 30 秒) 限制，超時會觸發 E_ERROR 並終止執行。無法在代碼中 try/catch 捕獲此致命錯誤，但可通過 register_shutdown_function 在腳本關閉階段檢測超時並執行清理/記錄/告警邏輯。本文提供標準實現模式與進階應用。

核心機制

// 註冊關閉處理器 (可多次註冊，按順序執行)
register_shutdown_function('handleShutdown');

function handleShutdown(): void {
    // 獲取最後發生的錯誤
    $error = error_get_last();

    // 判斷是否為最大執行時間超時
    // 錯誤信息: "Maximum execution time of 30 seconds exceeded"
    if ($error !== null && strpos($error['message'], 'Maximum execution time') !== false) {
        // 超時處理邏輯
        error_log("[TIMEOUT] Script exceeded max_execution_time at {$error['file']}:{$error['line']}");

        // 可選：發送告警、寫入審計日誌、釋放鎖、回滾業務狀態
        // 注意：此處無法輸出響應給客戶端 (連接已斷開)，只能做側邊效應操作
    }

    // 其他致命錯誤也會觸發
    if ($error !== null && in_array($error['type'], [E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR])) {
        error_log("[FATAL] {$error['message']} in {$error['file']}:{$error['line']}");
    }
}

// 設置執行時間限制 (僅影響當前腳本)
set_time_limit(2); // 2秒

// 模擬長時間運行
sleep(3); // 將觸發超時

進階：類封裝與上下文感知

class TimeoutHandler {
    private static $instance;
    private $startTime;
    private $timeoutThreshold;
    private $callbacks = [];

    private function __construct(int $thresholdSeconds = 30) {
        $this->startTime = microtime(true);
        $this->timeoutThreshold = $thresholdSeconds;
        register_shutdown_function([$this, 'onShutdown']);
    }

    public static function init(int $threshold = 30): self {
        self::$instance ??= new self($threshold);
        return self::$instance;
    }

    // 註冊超時回調
    public function onTimeout(callable $callback): self {
        $this->callbacks[] = $callback;
        return $this;
    }

    public function onShutdown(): void {
        $error = error_get_last();
        $elapsed = microtime(true) - $this->startTime;

        // 判斷超時：錯誤信息匹配 OR 實際耗時超過閾值 (防止錯誤信息本地化差異)
        $isTimeout = ($error !== null && stripos($error['message'], 'maximum execution time') !== false)
                  || $elapsed >= $this->timeoutThreshold;

        if ($isTimeout) {
            foreach ($this->callbacks as $cb) {
                try {
                    $cb($elapsed, $error);
                } catch (\Throwable $e) {
                    error_log("[TimeoutHandler] Callback failed: " . $e->getMessage());
                }
            }
        }
    }

    // 手動檢查並拋出異常 (用於循環中主動檢測)
    public function check(): void {
        if (microtime(true) - $this->startTime >= $this->timeoutThreshold) {
            throw new \RuntimeException("Execution timeout threshold reached");
        }
    }
}

// 使用
TimeoutHandler::init(25) // 25秒閾值 (留 5秒緩衝給 shutdown)
    ->onTimeout(function($elapsed, $error) {
        // 記錄到監控系統
        Metrics::gauge('script.timeout', 1, ['script' => basename($_SERVER['SCRIPT_FILENAME'])]);
        // 釋放分佈式鎖
        RedisLock::release('critical_section');
        // 發送告警
        Alert::send("Script timeout after {$elapsed}s");
    });

// 長時間循環中主動檢查
for ($i = 0; $i < 10000; $i++) {
    TimeoutHandler::init()->check(); // 超時拋出異常，可被上層捕獲
    processItem($i);
}

關鍵限制與注意事項

替代方案對比

最佳實踐總結

1. 設置合理閾值：Web 請求 max_execution_time = 30，CLI 任務根據業務設置 (300-3600s)。
2. 預留緩衝：Shutdown 邏輯預留 5-10 秒，避免清理邏輯本身超時。
3. 冪等設計：業務操作設計為冪等，超時重試不產生副作用。
4. 監控覆蓋：超時率、平均執行時間、P99 執行時間納入核心指標儀表板。
5. 異步化長任務：超過 30 秒的操作 (導出、轉碼、推送) 必須異步隊列處理，Web 請求只返回任務 ID。

register_shutdown_function 是 PHP 處理致命錯誤與超時的「最後一道防線」，配合合理的架構分層 (同步快速響應 + 異步重任務)，構建健壯的 PHP 應用體系。