Session


>i 本文档的最新修订日期是: > **2021-02-17** # Session ## 模块简述 会话(Session)功能模块。 ## 模块配置 配置文件位于 `/Config/Session.php` 。 * **`System`** `(Array)` `~` : Session功能的参数定义,其中每一个元素为一个参数,元素的 `键` 为参数的名称(名称无需包含 `session.` 前缀),元素的 `值` 为参数对应的值,您可以自行添加/删除这些参数。 可被定义的参数的列表、值、类型、含义,请参看PHP的官方手册说明:[https://www.php.net/manual/zh/session.configuration.php](https://www.php.net/manual/zh/session.configuration.php)。 >w 此配置项中的部分/全部参数能否生效,取决于服务器运行环境的配置,例如在部分托管商提供的虚拟主机中就有可能不会生效。 * **`TokenLimit`** `(Int)` `20` : 用于CSRF校验的Token的最大存储数量。 * **`TokenExpTime`** `(Int)` `600` : 用于CSRF校验的Token的有效时间,单位为 `秒` 。 ## 公共参数 * **`token(token)`** `(String)` `默认值见方法参数`: 指定一个用于CSRF校验的token。 * **`id(id)`** `(String)` `默认值见方法参数`: 指定PHP中SESSION的ID,如不指定,将由PHP `自动生成` ID。 传入的字符串经 `MD5摘要` 运算后才会作为实际的SESSION的ID。 ## :: Token()方法 ### 语法 **Session :: Token ( )** ### 说明 种植用于CSRF校验的Token,并存储于Session中。 此方法 `支持` 中文参数名。 ### 参数 * **`token(token)`** `(String)` `''`: 详见本模块 `公共参数` 部分的说明。 * **`id(id)`** `(String)` `''`: 详见本模块 `公共参数` 部分的说明。 ### 返回 `(String)` 类型。 将返回一个 `UUID` 形式的字符串。 通常将其植入于表单页,在表单或Header、Cookie中附带字段 `csrf`(大小写敏感),值为本方法返回的字符串。 >w 可使用本方法防止跨站请求伪造(CSRF)攻击。 ## :: Csrf()方法 ### 语法 **Session :: Csrf ( 传参数组 )** ### 说明 对数据进行CSRF校验。 此方法 `支持` 中文参数名。 方法会检查token信息,如无token或token不正确,将 `报错` 。 ### 参数 * **`token(token)`** `(String)` `''`: 详见本模块 `公共参数` 部分的说明。 >w 当未指定本参数或值为空时,框架将依次寻找 `HTTP_GET``HTTP_POST``Cookie``Header` 中字段名为 `csrf` 的数据,并将其作为 `token` 进行校验。 如 `同时存在` 多个字段名为csrf的数据,将以 `最后一次` 寻找到的数据作为token。 * **`id(id)`** `(String)` `''`: 详见本模块 `公共参数` 部分的说明。 * **`unset_token(清除token)`** `(Bool)` `TRUE`: 是否在每一次检查后是否清空token,`TRUE` 代表清空、`FALSE` 代表不清空,默认清空。 ### 返回 `(Bool)` 类型。 返回值为 `TRUE` 时代表Token校验成功、`FALSE` 代表Token校验失败。 >w 若需要检测token,需在此之前已经通过 `Session` 模块中的 `Token()` 方法生成了token。 ### 示例 对请求进行 `CSRF` 检查,并在检查结束后销毁token: ```php $Config=array( '清除token'=>TRUE ) Session::Csrf($Config); ``` ## :: Start()方法 ### 语法 **Session :: Start ( 传参数组 )** ### 说明 开启SESSION。 此方法 `支持` 中文参数名。 如果在使用本方法前已经开启了SESSION,本方法将 `不会` 产生作用。 如果SESSION开启失败,将 `报错` 。 ### 参数 * **`id(id)`** `(String)` `''`: 详见本模块 `公共参数` 部分的说明。 ### 返回 无。 ### 示例 指定SESSION的ID为 `test` ,并开启SESSION: ```php $Config=array( 'id'=>'test' ) Session::Start($Config); ```