session_set_save_handler

(PHP 4, PHP 5, PHP 7, PHP 8)

session_set_save_handler — 設置用戶自定義會話存儲函數

說明

session_set_save_handler(
    callable $open,
    callable $close,
    callable $read,
    callable $write,
    callable $destroy,
    callable $gc,
    callable $create_sid = ?,
    callable $validate_sid = ?,
    callable $update_timestamp = ?
): bool

可以使用下面的方式來注冊自定義會話存儲函數：

session_set_save_handler(object $sessionhandler, bool $register_shutdown = true): bool

session_set_save_handler() 設置用戶自定義 會話存儲函數。 如果想使用 PHP 內置的會話存儲機制之外的方式， 可以使用本函數。 例如，可以自定義會話存儲函數來將會話數據存儲到數據庫。

參數

本函數有 2 種原型：

sessionhandler

實現了 SessionHandlerInterface， SessionIdInterface（可選） 和/或 SessionUpdateTimestampHandlerInterface 接口的對象， 例如 SessionHandler。

register_shutdown

將函數 session_write_close() 注冊為 register_shutdown_function() 函數。

或者
open(string $savePath, string $sessionName)

實現了以下簽名的 callable 回調：

open(string $savePath, string $sessionName): bool

open 回調函數類似于類的構造函數， 在會話打開的時候會被調用。 這是自動開始會話或者通過調用 session_start() 手動開始會話 之后第一個被調用的回調函數。 此回調函數操作成功返回 true，反之返回 false。

close

close 回調函數類似于類的析構函數。 在 write 回調函數調用之后調用。 當調用 session_write_close() 函數之后，也會調用 close 回調函數。 此回調函數操作成功返回 true，反之返回 false。

read

實現了以下簽名的 callable 回調：

read(string $sessionId): string

如果會話中有數據，read 回調函數必須返回將會話數據編碼（序列化）后的字符串。 如果會話中沒有數據，read 回調函數返回空字符串。

在自動開始會話或者通過調用 session_start() 函數手動開始會話之后，PHP 內部調用 read 回調函數來獲取會話數據。 在調用 read 之前，PHP 會調用 open 回調函數。

read 回調返回的序列化之后的字符串格式必須與 write 回調函數保存數據時的格式完全一致。 PHP 會自動反序列化返回的字符串并填充 $_SESSION 超級全局變量。 雖然數據看起來和 serialize() 函數很相似， 但是需要提醒的是，它們是不同的。 請參考： session.serialize_handler。

write

實現了以下簽名的 callable 回調：

write(string $sessionId, string $data): bool

在會話保存數據時會調用 write 回調函數。 此回調函數接收當前會話 ID 以及 $_SESSION 中數據序列化之后的字符串作為參數。 序列化會話數據的過程由 PHP 根據 session.serialize_handler 設定值來完成。

序列化后的數據將和會話 ID 關聯(lián)在一起進行保存。 當調用 read 回調函數獲取數據時，所返回的數據必須要和 傳入 write 回調函數的數據完全保持一致。

PHP 會在腳本執(zhí)行完畢或調用 session_write_close() 函數之后調用此回調函數。 注意，在調用完此回調函數之后，PHP 內部會調用 close 回調函數。

注意:

PHP 會在輸出流寫入完畢并且關閉之后 才調用 write 回調函數， 所以在 write 回調函數中的調試信息不會輸出到瀏覽器中。 如果需要在 write 回調函數中使用調試輸出， 建議將調試輸出寫入到文件。

destroy

實現了以下簽名的 callable 回調：

destroy(string $sessionId): bool

當調用 session_destroy() 函數， 或者調用 session_regenerate_id() 函數并且設置 destroy 參數為 true 時， 會調用此回調函數。此回調函數操作成功返回 true，反之返回 false。

gc

實現了以下簽名的 callable 回調：

gc(int $lifetime): bool

為了清理會話中的舊數據，PHP 會不時的調用垃圾收集回調函數。 調用周期由 session.gc_probability 和 session.gc_divisor 參數控制。 傳入到此回調函數的 lifetime 參數由 session.gc_maxlifetime 設置。 此回調函數操作成功返回 true，反之返回 false。

create_sid

實現了以下簽名的 callable 回調：

create_sid(): string

需要新的會話 ID 時，執(zhí)行此回調函數。 它被調用時不會傳入參數，其返回值應該是一個字符串格式的、有效的 session ID。

validate_sid

實現了以下簽名的 callable 回調：

validate_sid(string $key): bool

開啟 session.use_strict_mode 后， 當啟動一個 session 時，提供了 session ID 后會執(zhí)行此回調。 參數 key 是待驗證的 session ID。 如果該 ID 的 session 已經存在，則為有效 session ID。 成功時返回值應當為 true，失敗時為 false。

update_timestamp

實現了以下簽名的 callable 回調：

update_timestamp(string $key, string $val): bool

更新 session 時執(zhí)行此回調。 參數 key 是 session ID；參數 val 是 session 的數據。 成功時返回值應當為 true，失敗時為 false。

返回值

成功時返回 true， 或者在失敗時返回 false。

范例

示例 #1 自定義會話管理器： 完整代碼請參見 SessionHandlerInterface。

這里僅列出了調用方式，完整代碼請參見 SessionHandlerInterface。

這里使用了 session_set_save_handler() 函數的 OOP 原型 并且使用第二個參數來注冊 shutdown 函數。 當將對象注冊為會話保存管理器時，建議使用這種方式。

<?php
class MySessionHandler implements SessionHandlerInterface
{
    // 在這里實現接口
}

$handler = new MySessionHandler();
session_set_save_handler($handler, true);
session_start();

// 現在可以使用 $_SESSION 保存以及獲取數據了

注釋

警告

在對象銷毀之后才會調用 write 和 close 回調函數， 所以，在這兩個回調函數中不可以使用對象，也不可以拋出異常。 如果在函數中拋出異常，PHP 既不會捕獲它，也不會跟蹤它， 這樣會導致程序異常終止。 但是對象析構函數可以使用會話。

可以在析構函數中調用 session_write_close() 函數來解決這個問題。 但是注冊 shutdown 回調函數才是更加可靠的做法。

警告

如果會話在腳本結束后關閉，對于某些 SAPI 而言，當前工作目錄可能已經被改變。 可以調用 session_write_close() 函數在腳本執(zhí)行結束之前關閉會話。

參見