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