PHP 8.5 partitioned Cookie 参数的兼容配置清单

如果应用准备使用 PHP 8.5 的 partitioned Cookie，兼容配置可以先记住四个结论：运行时必须是 PHP 8.5 或更高版本；partitioned 为 true 时必须同时开启 secure；samesite 仍然需要单独决定；PHP 8.4 及更早版本不要把未知的 partitioned 键直接传给 setcookie()。

PHP 官方手册把 partitioned 加入了 setcookie() 的 options 数组，Session 配置也从 PHP 8.5 开始提供 session.cookie_partitioned。因此兼容改造的重点不是只补一行参数，而是同时检查版本、传输安全和 Cookie 的配置入口。

官方资料：https://www.php.net/manual/en/function.setcookie.php

先确定 PHP 版本和参数边界

setcookie() 的数组写法从 PHP 7.3 开始可用，但 partitioned 这个键是在 PHP 8.5 才加入的。PHP 8.5 及以上可以使用下面的组合；低版本应当走普通 Cookie 回退，不能靠更换键名绕过版本限制。

另外，Cookie 仍然属于响应头，调用 setcookie() 前不能已经输出 HTML、空格或调试文本。这个限制与是否使用 partitioned 无关。

普通 Cookie 的推荐写法

普通业务 Cookie 使用 options 数组更容易集中管理。示例把有效期、路径、Secure、HttpOnly、SameSite 和 Partitioned 写在同一处，便于代码审查和按环境切换。

 time() + 1800,       // 只保留 30 分钟，避免把临时状态长期存储
    'path' => '/',                    // 让站点内的相关路径都能读取
    'secure' => true,                 // partitioned 为 true 时必须开启
    'httponly' => true,               // 不让前端脚本直接读取会话辅助值
    'samesite' => 'None',             // 需要跨站发送时显式选择 None
    'partitioned' => true,            // PHP 8.5+ 才支持该键
];

if (PHP_VERSION_ID >= 80500) {
    // 版本满足要求时再发送带 Partitioned 属性的 Cookie。
    setcookie('embed_preference', 'compact', $cookieOptions);
} else {
    // 旧版本不传未知键，回退到不带 Partitioned 的普通 Cookie。
    unset($cookieOptions['partitioned']);
    setcookie('embed_preference', 'compact', $cookieOptions);
}
?>

这里的版本分支解决的是 PHP 函数参数兼容，不代表所有浏览器都会接受该属性。若服务仍有 PHP 8.4 节点，必须让所有节点使用相同的回退规则，避免同一个 Cookie 在不同节点上得到不同的响应头。

secure 和 SameSite 要分别检查

根据 PHP 手册，partitioned => true 而 secure 没有开启时会抛出 ValueError。samesite => 'None' 也要求 secure，但这两个约束不是一回事：Partitioned 表示分区状态属性，SameSite 表示跨站请求策略，不能用其中一个替代另一个。

 time() + 3600,        // 只保存一个小时的组件状态
    'path' => '/',
    'secure' => true,                 // 同时满足 Partitioned 和 SameSite=None 的要求
    'httponly' => true,
    'samesite' => 'None',             // 只有明确需要跨站时才选 None
    'partitioned' => true,
]);
?>

如果业务不需要跨站场景，可以把 samesite 设为 Lax 或 Strict，但仍应保留 secure。不要为了让旧浏览器“看起来能用”而删掉安全属性。

Session Cookie 要选对配置入口

应用 Cookie 由 setcookie() 直接控制，Session Cookie 则可以通过 php.ini、session_set_cookie_params() 或 session_start() 的 options 配置。PHP 8.5 的 Session 运行时配置新增了 session.cookie_partitioned，默认值为 0。

= 80500) {
    session_set_cookie_params([
        'lifetime' => 1800,            // Session 空闲 30 分钟后过期
        'path' => '/',
        'secure' => true,              // partitioned Session Cookie 需要 HTTPS
        'httponly' => true,
        'samesite' => 'Lax',           // 登录态通常优先使用 Lax，按业务调整
        'partitioned' => true,         // PHP 8.5+ 的 Session Cookie 选项
    ]);
} else {
    // 旧版本只使用已支持的字段，避免把 partitioned 传给旧运行时。
    session_set_cookie_params([
        'lifetime' => 1800,
        'path' => '/',
        'secure' => true,
        'httponly' => true,
        'samesite' => 'Lax',
    ]);
}

session_start(); // 参数准备好后再启动 Session
?>

如果使用集中式配置文件，也可以在 PHP 8.5 环境中设置 session.cookie_partitioned=1。不要同时在多个入口写出互相冲突的值；团队最好选定“部署配置统一管理”或“代码按请求管理”其中一种主路径。

旧版本兼容的最小分支

兼容分支的目标是让 PHP 8.4 及以下节点继续发送可接受的普通 Cookie，而不是在旧运行时伪造一个 PHP 不认识的参数。可以把通用字段放在基础数组中，再只给 PHP 8.5 加入 partitioned。

 time() + 86400,       // 兼容节点都保留一天
    'path' => '/',
    'secure' => true,
    'httponly' => true,
    'samesite' => 'Lax',
];

if (PHP_VERSION_ID >= 80500) {
    // 仅在新运行时加入新键，保持旧节点可执行。
    $options['partitioned'] = true;
}

setcookie('account_hint', '1', $options);
?>

如果升级后仍看不到新属性，先确认请求实际命中了哪一个 PHP-FPM 或容器版本，再检查响应是否已经开始输出。不要只看应用日志中的“已设置 Cookie”，因为这个日志只能证明代码路径执行过，不能说明响应头已经被客户端接受。

发布前的兼容配置清单

1. 运行时：所有需要发送 partitioned 的节点都在 PHP 8.5 或更高版本。
2. 传输：secure 已开启，入口和反向代理不会把 HTTPS 误判为 HTTP。
3. 策略：根据实际跨站需求选择 samesite，不要把它与 Partitioned 混为一个开关。
4. Session：在 session_start() 前配置参数，或在部署配置中统一设置 session.cookie_partitioned。
5. 旧节点：PHP 8.4 及以下不传 partitioned，统一使用普通 Cookie 回退。
6. 输出时机：所有 Cookie 调用都在 HTML、调试输出和空格之前执行。

常见问题

PHP 8.4 传入 partitioned 会怎样？

它不是一个可以忽略的普通业务字段。旧运行时不认识该 options 键，应当在版本分支中不要传入；同时保留其他安全属性。

partitioned 能代替 SameSite=None 吗？

不能。两者表达的 Cookie 规则不同，是否使用 None 要由实际跨站请求决定；如果使用 None，仍需开启 secure。

Session Cookie 也必须开启 partitioned 吗？

不必须。只有确实需要分区状态的 Session 场景才开启；普通站点登录态可以沿用原有 Session 策略，并重点保持 HTTPS、HttpOnly 和 SameSite 配置一致。

总的来说，PHP 8.5 的兼容改造可以收敛为一条规则：新属性只在新运行时发送，secure 与 samesite 按各自语义配置，Session 在启动前统一准备参数，旧节点保留明确的普通 Cookie 回退。