Session 类別

Session 类別能让你为你的应用程序在無狀態（stateless）的 web 环境下保持狀態。 它能让你在伺服器上使用各種變数解決方案來儲存變数，并且在下个頁面請求再呼叫變数。

記錄在本頁的靜態方法使用透過設定配置中 driver 設定配置的 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 設定來確定是否需要垃圾回收。 如果是这樣的話，它們将在頁面已经傳送給使用者之後的一个 shutdown 事件执行它。 这種方法的缺點是，如果这需要一點時間，頁面将不会完成，而会是「載入中……」直到 GC 完成。

當使用 cookie，請 務必 確保配置在你的 app/config/config.php 及／或你的 php.ini 档案中的時區與設定在你伺服器上的時區相符。因为 cookie 的到期時間戳記是 GMT，當你時區有不相符時， 計算到期時間将導致嚴重错误，從不正確的過期到 cookie 完全不被設定， 因为它們到達瀏覽器時已经逾期。

instance($instance = null)

instance 方法回傳預設的 session 實例，或一个指定的實例，透過名稱識別。

靜態 是
參数
參数 預設 描述
$instance 
null
 識別需求的 session 實例的 Cookie 名稱（如在 config/session.php 定義的）。
回傳 混合 - session 物件，或 false 在請求的實例不存在時。
範例 
// 取得預設 session 實例（由 'driver' 配置設定所标識）。
$session = Session::instance();

// 取得一个指定 session 實例
$session = Session::instance('myappcookie');

set($variable, $value = null)

set 方法能让你設定一个 session 變数。

靜態 是
參数
參数 类型 預設 描述
$variable 字串｜陣列 必要 要設定或關聯值陣列的 session 變数名稱。
$value 混合 
null
 session 變数值。
这可以是任何資料型態，但注意當在 session 中儲存物件，做为 session 資料是序列化的，而且要序列化一个物件是有限制的。
回傳 FuelCoreSession_Driver - 可鍊結
範例 
// 在 session 中儲存 userid
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 必要 要刪除的 session 變数名稱。
回傳 FuelCoreSession_Driver - 可鍊結
範例 
// 從 session 刪除儲存的 userid
Session::delete('userid');

// 你也可以從陣列刪除指定的鍵
Session::delete('array.varC');

set_flash($variable, $value = null)

set_flash 方法能让你設定一个 session 快閃變数。快閃變数的生命週期有限。根據配置的不同，它們将在下个頁面請求之後，或在被檢索被刪除。

靜態 是
參数
參数 預設 描述
$variable 必要 要設定的 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)

get_flash 方法能让你取得一个 session 快閃變数。快閃變数有生命週期的限制。根據配置的不同，它們将在下个頁面請求之後，或在被檢索被刪除。

靜態 是
參数
參数 預設 描述
$variable 必要 要取得的 session 變数名稱。
$default 
null
 在請求的變数不存在時要回傳的預設值。如果沒給預設，該方法将回傳 null。
$expire 
false
 如果为 true，session 變数立即過期，即使它在同一个請求中被設定。
回傳 混合 - 依據儲存的 $variable 型態。該方法回傳 null 如果請求的變数不存在。
範例 
// 找出要处理哪个步驟
$step = Session::get_flash('step');

此方法支援「句點表示法」來從一个多維陣列中檢索元素。

keep_flash($variable)

keep_flash 方法重設一个儲存在 session 中的快閃變数为「未請求」狀態。这能让你取得一个快閃變数，并繼續傳遞它到下个頁面請求。

靜態 是
參数
參数 預設 描述
$variable 必要 要保留的快閃變数名稱。
回傳 FuelCoreSession_Driver - 可鍊結
範例 
// 保留步驟值給更多頁面請求
Session::keep_flash('step');

delete_flash($variable)

delete_flash 方法能让你刪除一个儲存的快閃變数。

靜態 是
參数
參数 預設 描述
$variable 必要 要刪除的快閃變数名稱。
回傳 FuelCoreSession_Driver - 可鍊結
範例 
// 從 session 刪除步驟
Session::delete_flash('step');

create()

create 方法能让你建立一个新的 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。在正常情況下，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');