session_set_save_handler

(PHP 4, PHP 5, PHP 7)

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

自 PHP 5.4 开始，可以使用下面的方式来注册自定义会话存储函数：

session_set_save_handler ( object $sessionhandler [, bool $register_shutdown = TRUE ] ) : bool

session_set_save_handler() 设置用户自定义 会话存储函数。 如果想使用 PHP 内置的会话存储机制之外的方式， 可以使用本函数。 例如，可以自定义会话存储函数来将会话数据存储到数据库。

参数

本函数有 2 种原型：

sessionhandler

实现了 SessionHandlerInterface， SessionIdInterface 和/或 SessionUpdateTimestampHandlerInterface 接口的对象， 例如 SessionHandler。 自 PHP 5.4 之后可以使用。

register_shutdown

将函数 session_write_close() 注册为 register_shutdown_function() 函数。

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

open 回调函数类似于类的构造函数， 在会话打开的时候会被调用。 这是自动开始会话或者通过调用 session_start() 手动开始会话 之后第一个被调用的回调函数。 此回调函数操作成功返回 TRUE，反之返回 FALSE。

close()

close 回调函数类似于类的析构函数。 在 write 回调函数调用之后调用。 当调用 session_write_close() 函数之后，也会调用 close 回调函数。 此回调函数操作成功返回 TRUE，反之返回 FALSE。

read(string $sessionId)

如果会话中有数据，read 回调函数必须返回将会话数据编码（序列化）后的字符串。 如果会话中没有数据，read 回调函数返回空字符串。

在自动开始会话或者通过调用 session_start() 函数手动开始会话之后，PHP 内部调用 read 回调函数来获取会话数据。 在调用 read 之前，PHP 会调用 open 回调函数。

read 回调返回的序列化之后的字符串格式必须与 write 回调函数保存数据时的格式完全一致。 PHP 会自动反序列化返回的字符串并填充 $_SESSION 超级全局变量。 虽然数据看起来和 serialize() 函数很相似， 但是需要提醒的是，它们是不同的。 请参考： session.serialize_handler。

write(string $sessionId, string $data)

在会话保存数据时会调用 write 回调函数。 此回调函数接收当前会话 ID 以及 $_SESSION 中数据序列化之后的字符串作为参数。 序列化会话数据的过程由 PHP 根据 session.serialize_handler 设定值来完成。

序列化后的数据将和会话 ID 关联在一起进行保存。 当调用 read 回调函数获取数据时，所返回的数据必须要和 传入 write 回调函数的数据完全保持一致。

PHP 会在脚本执行完毕或调用 session_write_close() 函数之后调用此回调函数。 注意，在调用完此回调函数之后，PHP 内部会调用 close 回调函数。

Note:

PHP 会在输出流写入完毕并且关闭之后 才调用 write 回调函数， 所以在 write 回调函数中的调试信息不会输出到浏览器中。 如果需要在 write 回调函数中使用调试输出， 建议将调试输出写入到文件。

destroy($sessionId)

当调用 session_destroy() 函数， 或者调用 session_regenerate_id() 函数并且设置 destroy 参数为 TRUE 时， 会调用此回调函数。此回调函数操作成功返回 TRUE，反之返回 FALSE。

gc($lifetime)

为了清理会话中的旧数据，PHP 会不时的调用垃圾收集回调函数。 调用周期由 session.gc_probability 和 session.gc_divisor 参数控制。 传入到此回调函数的 lifetime 参数由 session.gc_maxlifetime 设置。 此回调函数操作成功返回 TRUE，反之返回 FALSE。

create_sid()

当需要新的会话 ID 时被调用的回调函数。 回调函数被调用时无传入参数， 其返回值应该是一个字符串格式的、有效的会话 ID。

返回值

成功时返回 TRUE， 或者在失败时返回 FALSE。

范例

Example #1 自定义会话管理器： 完整代码请参见 SessionHandlerInterface。

下列代码适用于 PHP 5.4.0 及以上版本。 这里仅列出了调用方式，完整代码请参见 SessionHandlerInterface。

这里使用了 session_set_save_handler() 函数的 OOP 原型 并且使用第二个参数来注册 shutdown 函数。 当将对象注册为会话保存管理器时，建议使用这种方式。

<?php
class MySessionHandler implements SessionHandlerInterface
{
    // 在这里实现接口
}

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

// 现在可以使用 $_SESSION 保存以及获取数据了

Example #2 使用对象自定义会话保存管理器

下列代码适用于 PHP 5.4.0 之前的版本。

下例演示了基于文件的会话数据存储， 和 PHP 默认的 files 存储器很相似。 通过对此示例代码进行扩展， 你可以很方便的实现使用数据库保存会话数据的功能。

针对于 PHP 5.4.0 之前的版本， 通过调用 register_shutdown_function() 函数 来注册 session_write_close() 回调函数。 这也是我们建议的方式。

<?php
class FileSessionHandler
{
    private $savePath;

    function open($savePath, $sessionName)
    {
        $this->savePath = $savePath;
        if (!is_dir($this->savePath)) {
            mkdir($this->savePath, 0777);
        }

        return true;
    }

    function close()
    {
        return true;
    }

    function read($id)
    {
        return (string)@file_get_contents("$this->savePath/sess_$id");
    }

    function write($id, $data)
    {
        return file_put_contents("$this->savePath/sess_$id", $data) === false ? false : true;
    }

    function destroy($id)
    {
        $file = "$this->savePath/sess_$id";
        if (file_exists($file)) {
            unlink($file);
        }

        return true;
    }

    function gc($maxlifetime)
    {
        foreach (glob("$this->savePath/sess_*") as $file) {
            if (filemtime($file) + $maxlifetime < time() && file_exists($file)) {
                unlink($file);
            }
        }

        return true;
    }
}

$handler = new FileSessionHandler();
session_set_save_handler(
    array($handler, 'open'),
    array($handler, 'close'),
    array($handler, 'read'),
    array($handler, 'write'),
    array($handler, 'destroy'),
    array($handler, 'gc')
    );

// 下面这行代码可以防止使用对象作为会话保存管理器时可能引发的非预期行为
register_shutdown_function('session_write_close');

session_start();
// 现在可以使用 $_SESSION 保存以及获取数据了

注释

Warning

在脚本执行完毕之后，PHP 内部会清除对象， 所以有可能不调用 write 和 close 回调函数。 这样可能会引发非预期的行为，所以当使用对象作为会话保存管理器时， 需要通过注册 shutdown 回调函数来规避风险。 通常，你可以通过调用 register_shutdown_function() 函数 来注册 'session_write_close' 回调函数。

在 PHP 5.4.0 中，可以调用 session_register_shutdown() 函数来注册 shutdown 回调函数。 如果你使用 session_set_save_handler() 的 OOP 原型， 那么仅需设置 “register shutdown” 为 TRUE 即可。

Warning

在 PHP 5.0.5 中，在对象销毁之后才会调用 write 和 close 回调函数， 所以，在这两个回调函数中不可以使用对象，也不可以抛出异常。 如果在函数中抛出异常，PHP 既不会捕获它，也不会跟踪它， 这样会导致程序异常终止。 但是对象析构函数可以使用会话。

可以在析构函数中调用 session_write_close() 函数来解决这个问题。 但是注册 shutdown 回调函数才是更加可靠的做法。

Warning

如果会话在脚本结束后关闭，对于某些 SAPI 而言，当前工作目录可能已经被改变。 可以调用 session_write_close() 函数在脚本执行结束之前关闭会话。

更新日志

版本 说明
7.0.0 新增可选参数 validate_sid 和 参数 update_timestamp。
5.5.1 加入可选参数 create_sid。
5.4.0 加入 SessionHandlerInterface 接口以及 SessionHandler 类，以方便用户实现自定义的会话保存管理器。

参见