PHP会话创建与变量设置

PHP会话代码实现

<?php
declare(strict_types=1);

/**
 * 用途：在“用户登录”动作完成（凭证校验通过）后安全地启动会话并初始化会话变量 auth_user。
 * 兼容：PHP 8.1+（推荐 8.2/8.3）
 */

use Throwable;

/**
 * 判断当前请求是否通过 HTTPS。
 * 注意：若有反向代理，请在受信场景下设置环境变量 TRUST_PROXY=true，并正确透传 X-Forwarded-Proto。
 */
function is_https_request(): bool
{
    if (!empty($_SERVER['HTTPS']) && strtolower((string)$_SERVER['HTTPS']) !== 'off') {
        return true;
    }
    if (isset($_SERVER['SERVER_PORT']) && (int)$_SERVER['SERVER_PORT'] === 443) {
        return true;
    }
    $trustedProxy = filter_var(getenv('TRUST_PROXY'), FILTER_VALIDATE_BOOL);
    if ($trustedProxy && isset($_SERVER['HTTP_X_FORWARDED_PROTO'])) {
        return strtolower((string)$_SERVER['HTTP_X_FORWARDED_PROTO']) === 'https';
    }
    return false;
}

/**
 * 获取客户端 IP（默认仅信任 REMOTE_ADDR）。
 * 若位于受信反向代理之后，可开启 TRUST_PROXY，并安全使用 X-Forwarded-For 的最左侧地址。
 */
function client_ip(): string
{
    $trustedProxy = filter_var(getenv('TRUST_PROXY'), FILTER_VALIDATE_BOOL);
    if ($trustedProxy && !empty($_SERVER['HTTP_X_FORWARDED_FOR'])) {
        $parts = explode(',', (string)$_SERVER['HTTP_X_FORWARDED_FOR']);
        $ip = trim($parts[0]);
        if (filter_var($ip, FILTER_VALIDATE_IP)) {
            return $ip;
        }
    }
    $ip = $_SERVER['REMOTE_ADDR'] ?? '';
    return filter_var($ip, FILTER_VALIDATE_IP) ?: '0.0.0.0';
}

/**
 * 启动一个加固的 PHP 会话。
 * - 使用严格模式和仅 Cookie 传递
 * - 设置安全的 Cookie 参数（Secure/HttpOnly/SameSite）
 * - 在 session_start 之前完成所有配置
 */
function start_secure_session(string $sessionName = 'APPSESSID'): void
{
    if (headers_sent($file, $line)) {
        throw new RuntimeException("Cannot start session: headers already sent at {$file}:{$line}");
    }

    // 加固会话行为（非废弃项）
    ini_set('session.use_strict_mode', '1');   // 拒绝使用不存在/已失效的会话 ID
    ini_set('session.use_only_cookies', '1');  // 仅通过 Cookie 传输会话 ID，禁用 URL 传参
    ini_set('session.gc_probability', '1');    // 1% 概率触发 GC（可结合生产环境统一回收策略调整）
    ini_set('session.gc_divisor', '100');

    // 在 session_start 前设置 Cookie 属性
    $isHttps = is_https_request();
    session_set_cookie_params([
        'lifetime' => 0,          // 会话 Cookie，浏览器关闭即过期
        'path' => '/',            // 根路径有效
        // 不显式设置 domain，默认绑定当前主机名，避免子域/跨域泄露
        'secure' => $isHttps,     // 仅 HTTPS 传输（如在本地 HTTP 环境会自动为 false）
        'httponly' => true,       // 禁止 JS 访问，降低 XSS 风险
        'samesite' => 'Lax',      // 典型登录后跳转可用；若无需跨站请求可改为 'Strict'
    ]);

    session_name($sessionName);

    if (!session_start()) {
        throw new RuntimeException('Failed to start PHP session');
    }
    if (session_status() !== PHP_SESSION_ACTIVE) {
        throw new RuntimeException('Session is not active after session_start');
    }
}

/**
 * 初始化 CSRF Token（若不存在）。
 */
function ensure_csrf_token(): string
{
    if (empty($_SESSION['csrf_token'])) {
        $_SESSION['csrf_token'] = bin2hex(random_bytes(32));
    }
    return $_SESSION['csrf_token'];
}

/**
 * 在用户完成登录后，生成新的会话 ID，并写入 auth_user 会话变量。
 * 注意：
 * - 先 regenerate，再写入敏感会话数据，防止会话固定（fixation）。
 * - IP 字段总是使用服务端观测到的真实值，避免被外部输入伪造。
 */
function login_initialize_auth_user(): void
{
    // 业务侧期望的初始值（来自后端逻辑，而非客户端输入）
    $authUser = [
        'uid' => 'u24491',
        'roles' => ['member'],
        'mfa' => false,
        'login_at' => '2025-12-10T09:21:00+08:00',
        'ip' => '203.0.113.8', // 将在下方用服务端观测 IP 覆盖
    ];

    // 规范化和安全修正
    $authUser['uid'] = (string)$authUser['uid'];
    $authUser['roles'] = array_values(array_unique(array_map('strval', (array)$authUser['roles'])));
    $authUser['mfa'] = (bool)$authUser['mfa'];
    $authUser['ip'] = client_ip(); // 始终以服务端观测值为准，防止伪造

    // 会话特权变更时，先旋转会话 ID（防会话固定攻击）
    if (!session_regenerate_id(true)) {
        throw new RuntimeException('Failed to regenerate session ID after login');
    }

    // 写入指定会话变量
    $_SESSION['auth_user'] = $authUser;

    // 可选：绑定 UA 指纹，后续请求可做一致性校验（不要强绑定 IP，移动网络/代理会导致频繁变更）
    $_SESSION['ua_hash'] = hash('sha256', (string)($_SERVER['HTTP_USER_AGENT'] ?? ''));

    // 准备 CSRF 防护令牌
    ensure_csrf_token();

    // 记录登录会话建立时间（用于会话续期策略等）
    $_SESSION['logged_in_at'] = time();
}

/**
 * 入口：用于“登录成功后”的控制器/处理脚本。
 * - 成功：完成会话启动与变量写入，并尽快释放锁（session_write_close）。
 * - 失败：返回 500，记录日志，不泄露细节。
 */
try {
    $sessionName = getenv('APP_SESSION_NAME') ?: 'APPSESSID'; // 可通过环境变量自定义
    start_secure_session($sessionName);
    login_initialize_auth_user();

    // 重要：写完尽快释放会话锁，提高并发度（避免影响后续并发请求）
    session_write_close();

    // 此处可继续返回业务层的登录成功响应（JSON/重定向等）
    // 示例：header('Location: /dashboard'); exit;
} catch (Throwable $e) {
    http_response_code(500);
    header('Content-Type: application/json; charset=UTF-8');
    echo json_encode(['error' => 'Internal Server Error']);
    error_log('[session] ' . $e->getMessage()); // 只记录服务器日志，不向客户端暴露细节
    exit;
}

代码说明

• 会话初始化配置说明

  • session.use_strict_mode=1：拒绝使用不存在或已失效的 Session ID，降低会话劫持风险。
  • session.use_only_cookies=1：禁用 URL 方式传递 Session ID，防止泄露。
  • session_set_cookie_params：
    • secure：在 HTTPS 下启用，确保 Cookie 仅通过加密通道传输。
    • httponly：阻止 JavaScript 访问，降低 XSS 风险。
    • samesite=Lax：兼顾登录跳转与 CSRF 防护；如不涉及跨站回跳可设置为 Strict。
    • lifetime=0：浏览器会话期 Cookie；如需“记住登录”，应改为有限时长并配合刷新策略。
  • session_name：可通过 APP_SESSION_NAME 自定义 Cookie 名称，减少与其他系统冲突。
  • GC 参数（1% 概率）：适用于中小规模流量；大规模生产建议统一采用外部会话存储（如 Redis）并用定时任务清理。

• 变量设置逻辑解析

  • 会话变量名称：auth_user
  • 初始值字段：
    • uid：字符串化，便于统一类型判断。
    • roles：去重+字符串化，确保是干净的角色数组。
    • mfa：布尔化。
    • login_at：采用传入的业务时间字符串（ISO 8601），便于审计和展示。
    • ip：出于安全，强制覆盖为服务端观测到的客户端 IP（避免伪造）。
  • 安全步骤：
    • 先 session_start，再 session_regenerate_id(true)，再写入 auth_user，阻断会话固定攻击链。
    • 生成 csrf_token 以保护后续需要状态的写请求。
    • ua_hash 可用于在每次请求时校验 UA 一致性，发现异常可触发再验证或登出。

• 安全注意事项

  • 全站启用 HTTPS；在反向代理场景务必只在受信前提下使用 X-Forwarded-* 头。
  • 不要在会话中存储密码、密钥或其它高敏信息；仅存最小必要的用户态数据。
  • 谨慎使用 IP 强绑定。移动网络和代理会导致 IP 频繁变化，建议仅用于审计或风险评分，不做强校验。
  • 同一域下多系统共存时，合理设置 Cookie 名称和 SameSite/Domain，避免 Cookie 覆盖或泄露。
  • 控制会话大小，避免存放大对象，降低序列化开销和锁占用时间。

• 常见问题解决方案

  • “Cannot start session: headers already sent”：确保本文件在任何输出（包括 BOM、空格）之前执行。
  • 登录后仍然拿不到会话：检查 Cookie 是否被浏览器阻止（SameSite/跨域/第三方环境）、是否为 HTTPS 且 secure 标记导致在 HTTP 环境下不回传。
  • 并发请求阻塞：写入后立即调用 session_write_close() 释放锁；读取时避免不必要的写操作。
  • 反向代理下 secure 判定不准：只在受信代理环境设置 TRUST_PROXY=true，并确保正确透传 X-Forwarded-Proto。
  • 跨子域共享登录：需要在 session_set_cookie_params 中显式设置 domain 为顶级域（例如 .example.com），并评估安全影响。

使用指南

• 部署步骤说明

  1. 将本代码放入登录成功回调的控制器中，务必在任何输出之前执行。
  2. 设置环境变量（可选）：
     • APP_SESSION_NAME：自定义会话 Cookie 名称，例如 APPSESSID_Prod。
     • TRUST_PROXY=true：仅在受信反向代理拓扑下启用。
  3. 确认应用在 HTTPS 下运行（生产环境强制），以启用 Cookie Secure 标记。
  4. 若使用容器/多实例，确保所有实例共享会话存储（如 Redis/session.save_handler=redis）或使用粘性会话。

• 测试方法建议

  • 基本验证：
    • 触发登录成功后，用浏览器开发者工具检查响应头 Set-Cookie：应包含 HttpOnly、SameSite、Secure(在 HTTPS 下)。
    • 登录后访问受保护接口，服务端打印/检查 $_SESSION['auth_user'] 是否为： {"uid":"u24491","roles":["member"],"mfa":false,"login_at":"2025-12-10T09:21:00+08:00","ip":"<服务端观测IP>"}。
  • 会话固定防护：
    • 登录前后分别记录 document.cookie 中会话 ID，登录后 ID 应变化（regenerate 生效）。
  • CSRF：
    • 确认会话中存在 csrf_token，并在需要状态的 POST/PUT/DELETE 请求中随表单或头部（如 X-CSRF-Token）提交并在服务端校验。
  • 并发：
    • 使用多标签页同时发起接口请求，确认没有因会话锁造成异常延迟（确保调用了 session_write_close）。

• 性能优化提示

  • 提早释放锁：写操作后立即 session_write_close()，读操作尽量避免写入。
  • 控制会话体积：仅放必要字段，减少序列化与 IO。
  • 统一会话存储：高并发下使用 Redis/Memcached 作为 session.save_handler，并通过定时任务清理过期会话。
  • 调整 GC：大规模生产建议将 gc_probability 调小并改用外部清理，以稳定回收行为。
  • 监控与告警：监控会话命中率、序列化开销、锁等待时间与错误率，及时优化参数。