PHP session_set_save_handler 怎样保证自定义存储关闭

自定义 PHP 会话存储里最容易误判的一点，是把 close() 当成普通业务方法来调用：代码执行到文件末尾，并不等于你能在业务层看到它执行。真正的生命周期是：会话启动时进入 open()、read()，会话保存时先进入 write()，随后才进入 close()。如果需要在业务逻辑中提前释放会话锁，应显式调用 session_write_close()。

要保证自定义存储关闭，优先使用实现了 SessionHandlerInterface 的对象，并以 session_set_save_handler($handler, true) 注册，让 PHP 在请求关闭时安排保存；close() 只做幂等的连接、锁和临时资源释放，不承担业务提交，也不要依赖关闭阶段还能捕获异常。

官方地址：https://www.php.net/manual/en/function.session-set-save-handler.php

先把关闭时机和回调顺序分清

session_set_save_handler() 支持面向对象和回调函数两种注册方式。面向对象方式把最小接口固定为 open、read、write、close、destroy 和 gc，更容易把存储连接与释放动作放在同一个处理器里。

正常请求中可以按下面的顺序理解：session_start() 触发 open → read，脚本结束或显式调用 session_write_close() 时，PHP 先把当前会话编码后交给 write，随后调用 close。如果执行 session_destroy()，还会进入 destroy；定期清理过期数据则由 gc 负责。

用 SessionHandlerInterface 组织自定义存储

一个可维护的处理器应把“如何存储会话数据”和“如何收尾”分开。下面的示例用 PDO 表示外部存储，重点不是某一种数据库，而是四个核心边界：read 返回 PHP 原样写入的编码字符串，write 保存它，close 释放处理器持有的连接，所有关闭动作都可以重复执行而不会再次破坏状态。

pdo = new PDO(
            'mysql:host=127.0.0.1;dbname=app;charset=utf8mb4',
            'app_user',
            'app_password',
            [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]
        );
        return true;
    }

    public function read(string $id): string|false
    {
        // 必须返回 write 收到的同一种会话编码；没有记录时返回空字符串。
        $stmt = $this->pdo?->prepare(
            'SELECT payload FROM php_sessions WHERE session_id = :id'
        );
        if ($stmt === null) {
            return false;
        }
        $stmt->execute(['id' => $id]);
        $payload = $stmt->fetchColumn();
        return $payload === false ? '' : (string) $payload;
    }

    public function write(string $id, string $data): bool
    {
        // write 只保存 PHP 编码后的数据，不在这里释放连接或会话锁。
        $stmt = $this->pdo?->prepare(
            'INSERT INTO php_sessions (session_id, payload, touched_at)
             VALUES (:id, :payload, CURRENT_TIMESTAMP)
             ON DUPLICATE KEY UPDATE payload = VALUES(payload), touched_at = CURRENT_TIMESTAMP'
        );
        if ($stmt === null) {
            return false;
        }
        return $stmt->execute(['id' => $id, 'payload' => $data]);
    }

    public function close(): bool
    {
        // 用置空实现幂等释放；close 不抛出业务异常，也不依赖析构顺序。
        $this->pdo = null;
        return true;
    }

    public function destroy(string $id): bool
    {
        // destroy 只删除指定会话，和 close 的资源清理职责分开。
        $stmt = $this->pdo?->prepare(
            'DELETE FROM php_sessions WHERE session_id = :id'
        );
        return $stmt !== null && $stmt->execute(['id' => $id]);
    }

    public function gc(int $max_lifetime): int|false
    {
        // 先在 PHP 中计算截止时间，避免把动态值拼进 SQL 的 INTERVAL 语法。
        $cutoff = date('Y-m-d H:i:s', time() - $max_lifetime);
        $stmt = $this->pdo?->prepare(
            'DELETE FROM php_sessions
             WHERE touched_at execute(['cutoff' => $cutoff])) {
            return false;
        }
        return $stmt->rowCount();
    }
}

$handler = new DatabaseSessionHandler();
// true 表示注册会话关闭函数，让正常请求结束也走 write 后 close。
session_set_save_handler($handler, true);
session_start();

示例里的连接信息只是结构占位，生产环境应从安全配置注入，不能把真实凭据写进文章或项目。另一个关键点是 read() 返回值：PHP 会把它当作自己的会话编码来解码，不能因为后端使用数据库就擅自换成任意 JSON 格式。

让 close 真正释放共享资源

close() 没有参数，它的工作范围应尽量小：释放数据库连接、解锁文件或清理本次处理器持有的临时资源。若 open() 取得了会话锁，close() 就是释放锁的合适位置；但它不应该再去修改业务对象、触发新的会话写入或启动另一个请求。

实践中可以遵守三条规则：

• 幂等：第一次关闭后把资源引用置空，第二次调用仍返回可预期结果。
• 短小：关闭只处理资源收尾，不在关闭回调里做难以重试的业务动作。
• 可观测：若必须记录关闭失败，写入独立日志或指标，不要依赖浏览器输出；会话写入通常发生在输出流关闭之后。

官方文档还特别提醒，write 和 close 可能在对象析构之后被调用，因此不能把它们设计成依赖“另一个业务对象仍然活着”。更稳妥的做法是让处理器自己拥有最小的资源状态，并在业务代码还可控时主动调用 session_write_close()。

处理显式关闭、懒写入和失败边界

如果后续业务还要执行较慢的接口调用，而当前请求已经不再修改 $_SESSION，可以主动关闭会话：

显式关闭会走 write，随后走 close。如果之后再次需要修改会话，必须重新开始会话并确认当前请求允许这么做；不要把已经关闭的 $_SESSION 当成仍然会自动持久化的对象。

session.lazy_write 默认开启时，PHP 只有在会话数据发生变化时才重写存储内容。自定义处理器不要把“本次没有明显业务变化”误认为“close 不会执行”：close 仍是生命周期回调，真正是否调用 write 取决于 PHP 对会话数据变化的判断以及关闭方式。

失败处理要分层：read 返回 false 会让 session_start() 报告失败；write 和 close 应返回布尔结果。关闭阶段不要设计成依赖异常被业务层捕获，因为脚本终止阶段的回调可能已经离开了常规业务控制流。

用检查表排查关闭不生效

当你观察到“数据没有保存”“锁一直占着”或“close 里的日志没有出现”时，可以按下面顺序排查，不要先重复注册处理器：

1. 确认注册发生在 session_start() 之前；如果会话已经启动，后注册的处理器无法接管本次会话。
2. 确认使用的是 session_set_save_handler($handler, true)，第二个参数负责注册关闭时的会话写入安排。
3. 在可控业务点临时调用 session_write_close()，观察是否出现先 write 后 close 的记录。
4. 核对 read 返回的格式与 write 接收的格式一致，不要把空记录、false 和异常混为一谈。
5. 检查 close 是否依赖已被析构的连接、日志对象或容器服务；把收尾逻辑压缩到处理器自己的轻量状态。
6. 检查 session.lazy_write 与会话是否真的发生变化，并把“没有 write”与“没有 close”分开记录。

这段追踪类只用于理解回调顺序，实际项目仍需实现持久化读写和过期清理。日志里也不要写入完整会话 ID、Cookie、连接字符串或其他敏感数据。

常见问题

为什么只写了 close，却看不到它执行？

先确认处理器是在 session_start() 前注册，并且注册时启用了关闭安排；然后用独立日志观察，而不是依赖关闭阶段的浏览器输出。还要确认请求确实启动了会话。

close 是否负责保存会话数据？

不负责。PHP 会把编码后的数据交给 write，随后才调用 close。把保存逻辑塞进 close 会让职责和失败定位都变得模糊。

session_write_close() 会不会跳过 write？

它的用途就是保存并关闭当前会话，通常会先触发 write 再触发 close；但是否需要实际重写数据还会受到会话是否变化和 session.lazy_write 的影响。

close 里可以抛异常吗？

不应把业务正确性建立在这个假设上。PHP 官方文档提醒关闭回调可能在对象析构后运行，异常也未必能按常规方式捕获；应返回失败状态并把必要信息写入独立日志。

一句话总结：先用 SessionHandlerInterface 固定会话回调边界，再让 write 保存 PHP 编码数据、让 close 幂等释放资源；需要尽快解锁时显式调用 session_write_close()，并把关闭阶段当作受限的收尾环境处理。