Session类

session类能让你的应用程序在无状态（stateless）的web环境下保持状态。 它允许你使用一系列的存储方案在服务器上保存变量，并在下一个页面请求中回调这些变量。

本页列出的静态方法，使用了在驱动设置中配置的session驱动。 当你将auto_initialize设置为true时，Session类加载时会初始化一个session。 若将其设置为false，你需要使用下面的方法，或手动启动一个session实例来初始化这个session。

如果你的应用程序需要session支持，要么“总是加载(always_load)”你的session，要么确保你的(基础)控制器会加载它。 如果你要加载它，但又不想自动初始化(auto_initialize)这个session，也不使用下面这些session方法， 那么这个session将不会被刷新！这可能因为一个逾期的session导致你的应用程序出现无法预期的行为。

垃圾回收

session驱动内置了垃圾回收机制来移除过期的条目。内置支持数据过期的存储后台，例如APC，Memcached或Redis，会利用这一特性，自动作废过期的缓存条目。

存储后台（例如数据库或文档系统驱动器）不使用gc_probability设置来确定是否需要垃圾回收。这样一来，在页面发送给用户之后，会在关机事件中执行垃圾回收。 这个方法的弊端是，如果此行为需时，直到垃圾回收完成，页面都不会完全载入而是显示“加载中......”。

使用sessions时，务必确保app/config/config.php中配置的时区与/或php.ini文件中的时区与服务器设定的时区相符。 由于cookie有效期限为GMT格式，时区不匹会使有效期限计算夸张般地失常，小到非正常过期，大至session cookies压根儿未被设定，因为它们到达浏览器时已经过期。

instance($instance = null)

instance方法返回一个默认的session实例，或一个可通过名称识别的特定实例。

静态 总是加载
参数
参数 默认值 说明
$instance 
null
 用来识别被请求的session实例的Cookiename(如在config/session.php中定义的)。
返回值 混合值 - session对象，或false以防请求的实例不存在。
范例 
// 获取默认session实例（在‘驱动’设定中配置）
$session = Session::instance();

// 获取指定session实例
$session = Session::instance('myappcookie');

set($variable, $value = null)

set方法用于设定session变量。

静态 是
参数
参数 类型 默认值 说明
$variable string|array required 用来设定或关联数组值的session变量名。
$value mixed 
null
 session变量值。
可以是任何数据类型，但注意：在session中保存对象时，session数据是序列化的，序列化一个对象是有限制的。
返回值 FuelCoreSession_Driver - 可链接
范例 
// 保存userid至session中
Session::set('userid', $userid);

// 也可以保存更为复杂的值
Session::set('array', array('varA', 'varB', 'varC' => array('val1', 'val2'));

// 也可以使用数组一次设置多个值
Session::set(array(
    'userid' => $userid,
    'has_cookies' => function()
    {
        return (bool) \Cookie::get('has_them', false);
    }
));

// 也可以通过连锁调用来设定值
Session::set('userid', $userid)->set('foo', 'bar');

get($variable = null, $default = null)

get方法用于从session获取已保存的变量值。

静态 是
参数
参数 默认值 说明
$variable 
null
 用于获取的session变量名。若未指定，则返回所有session变量。
$default 
null
 请求的变量不存在时返回默认值，若未给定默认值，则返回null。
返回值 混合值 - 取决于保存的$variable类型。若请求的变量不存在，则返回null。
范例 
// 从session获取已保存的userid
$userid = Session::get('userid');
if ( $userid === false )
{
    echo "no user is logged in";
}

// 可以检索整个数组
$arr = Session::get('array');

// 或从数组中获取一个特定的键
$arr = Session::get('array.varC');

// 获取全部session变量
$vars = Session::get();

delete($variable)

delete方法用于删除已保存的session变量。

静态 是
参数
参数 默认值 说明
$variable required 要删除的session变量名。
返回值 FuelCoreSession_Driver - 可链式访问
范例 
// 从session删除已存储的userid
Session::delete('userid');

// 也可以删除数组中一个指定的key
Session::delete('array.varC');

set_flash($variable, $value = null)

set_flash方法用于设置session闪存变量。闪存变量具有有限的生命周期。这取决于配置，或于下一个页面请求发生后删除，或于被检索后删除。

静态 是
参数
参数 默认值 说明
$variable required 要设定的session闪存变量名。
$value 
null
 session闪存变量。
可以是任何数据类型，但注意：在session中保存对象时，session数据是序列化的，序列化一个对象是有限制的。
返回值 FuelCoreSession_Driver - 可链式访问
范例 
// 告诉下一页的请求要处理哪一个步骤
Session::set_flash('step', 2);

// 也可以保存更复杂的值
Session::set_flash('array', array('varA', 'varB', 'varC' => array('val1', 'val2')));

此方法支持有限制的“点记法”来保存元素到多维数组。只有顶级元素才可以被版本化，整个多维数组亦会在此刻过期。

get_flash($variable, $default = null, $expire = false)

The get_flash方法用于获取flash变量。Flash变量具有其生命周期。它是在下一个页面请求之后被删除，还是在检索后删除，取决于配置。

静态 是
参数
参数 默认值 说明
$variable required 要获取的session变量名。
$default 
null
 请求的变量不存在是返回的默认值。如果没有默认值，则返回null。
$expire 
false
 若为true，该session变量将立刻过期，即使在同意请求中设置过。
返回值 混合值 - 取决于保存的$variable变量类型。若请求的变量不存在，该方法返回null。
范例 
// 找出要处理的步骤
$step = Session::get_flash('step');

该方法支持“点记法”来从多维数组中读取元素。

keep_flash($variable)

keep_flash方法重设session中的flash变量为“未请求”状态。这允许你获取一个flash变量并将其传至下一个页面请求。

静态 是
参数
参数 默认值 说明
$variable required 将保留的flash变量。
返回值 FuelCoreSession_Driver - 可链式访问
范例 
// 保留step值以用于下一次页面请求
Session::keep_flash('step');

delete_flash($variable)

The delete_flash方法用于删除保存的flash变量。

静态 是
参数
参数 默认值 说明
$variable required 将删除的flash变量名。
返回值 FuelCoreSession_Driver - 可链式访问
范例 
// 删除session中的step值
Session::delete_flash('userid');

create()

create方法用于创建新的session。若session已存在，创建新的session的同时会干掉旧的。

静态 是
参数 无
返回值 FuelCoreSession_Driver - 可链式访问
范例 
// 创建新的session
Session::create();

destroy()

destroy方法用于干掉已存在的session。

静态 是
参数 无
返回值 FuelCoreSession_Driver - 可链式访问
范例 
// 干掉session
Session::destroy();

read()

read方法用于手动读取session。session类初始化时会自动读取session，所以在正常情况下无需使用此方法。

静态 是
参数 无
返回值 FuelCoreSession_Driver - 可链式访问
范例 
// 读取session
Session::read();

write()

write方法用于手动写入session。在正常情况下，脚本执行结束时会自动写入。

静态 是
参数 无
返回值 FuelCoreSession_Driver - 可链式访问
范例 
// 写入session
Session::write();

rotate()

rotate方法用于手动变换session ID。 在正常情况下，session ID会按照配置中的定义做定期自动变换。 出于额外安全考虑，可能需要手动变换它，例如当你改变一个已登录用户的权限时。

静态 是
参数 无
返回值 FuelCoreSession_Driver - 可链式访问
范例 
// 变换session
Session::rotate();

key()

key方法用于检索能够唯一识别session的session键。

静态 是
参数
参数 默认值 说明
$name 可选 键元素的名字。默认情况下，它被设为‘session_id’。 其他可能可用的元素有‘ip_hash’，‘created’，‘updated’， ‘user_agent’与‘payload’。
返回值 混合值 - 元素值，或在请求的元素不存在时返回false。
范例 
// 获取当前session ID
$session_id = Session::key('session_id');