Security 类別

Security 类別能让你在你的应用程序得到 CSRF 保護。

配置

Security 类別透過 app/config/config.php 配置档案的 security 段落來配置。

以下安全配置設定可以被定義：

參数 类型 預設 描述
token_salt 字串 
'put your salt value here...'
 用來產生安全符記的鹽。請確保这包含一些隨機的東西，以確保你的符記是不可預测的。
csrf_token_key 字串 
'fuel_csrf_token'
 用於 CSRF 符記 cookie 的名稱，以及包含符記的表单欄位的名稱。
csrf_expiration 整数 
0
 CSRF 符記 cookie 的過期時間。預設 cookie 会在瀏覽器 session 結束時過期。
uri_filter 陣列 
array('htmlentities')
 用來過濾 URI 的可呼叫項目的陣列（PHP 函式、物件方法、类別方法）。預設情況下，它使用 PHP 的 htmlentities 內部函式。
input_filter 陣列 
array()
 用來過濾 $_GET、$_POST 和 $_COOKIE 的可呼叫項目的陣列（PHP 函式、物件方法、类別方法）。預設情況下，沒有輸入過濾器被定義。
output_filter 陣列 
array('Security::htmlentities')
 用來過濾傳送給檢視或表现控件的變数的可呼叫項目的陣列（PHP 函式、物件方法、类別方法）。 为了安全起見，你需要定義一个輸出過濾器。
htmlentities_flags 整数 
null
 被用來在编码 HTML 實體的标誌。預設是 ENT_QUOTES 如果沒定義的話。
htmlentities_double_encode 布林 
null
 已经编码過的實體是否應該再被编码一次。預設是 false 如果沒定義。
auto_filter_output 布林 
true
 當为 true，所有傳遞給檢視物件的變数会自动被编码。
whitelisted_classes 陣列 
array('stdClass', 'Fuel\\Core\\View',
 'Fuel\\Core\\Presenter', 'Closure')
 當檢視變数的自动编码啟用，當傳遞物件到檢視時，你会遇到問題。 定義在此陣列的类別将免除自动编码。
csrf_autoload 布林 
true
 當为 true 時，自动使用 check_token() 載入并檢查 CSRF 符記。
csrf_autoload_methods 陣列 
array('post', 'put', 'delete')
 當 csrf_autoload 为 true，CSRF 符記将被用來驗證陣列中的所有 HTTP 方法。

請注意，如果你啟用 "csrf_autoload"，你所有的 HTTP 指定类型的請求必須包含一个 CSRF 符記，否則驗證将失敗，并拋出一个 SecurityException。

如果你需要处理 CSRF 驗證失敗在自动載入啟用時，你可以在你的 index.php 捕捉 SecurityException。

check_token($value = null)

check_token 方法能让你檢查 CSRF 符記。
檢查符記也確保符記存在，而且當它接收到下一个要被檢查的 session 值， 它将重置符記（無論檢查的結果）。

靜態 是
參数
參数 預設 描述
$value 
null
 要被檢查的 CSRF 符記，當沒給時檢查來自 POST 或 JSON 輸入的值。
回傳 布林
範例 
Security::check_token();

fetch_token()

fetch_token 方法能让你從 cookie 取回 CSRF 符記。

靜態 是
參数 無
回傳 字串
範例 
$csrf_token = Security::fetch_token();

js_fetch_token()

js_fetch_token 方法能让你產生 JavaScript fuel_csrf_token() 函式，當呼叫時，它将回傳目前的 CSRF 符記。用在表单提交 AJAX 操作時填充對的欄位。

靜態 是
參数 無
回傳 字串
範例 
// 輸出 javascript 函式
echo Security::js_fetch_token();

// 你现在可以在你的頁面上使用產生的 javascript 程式码 函式
<script type="text/javascript">
	var current_token = fuel_csrf_token();
</script>

js_set_token()

js_set_token 方法能让你產生 JavaScript fuel_set_csrf_token() 函式，當呼叫時，它将設定目前表单的 CSRF 符記欄位。 在一个表单的 onsubmit 使用， 用目前 CSRF cookie 的值來更新表单內的隱藏符記欄位。 你必須使用它在你希望允許多个視窗開啟時， 并使用一个嚴格的旋轉及 CSRF 符記的終結。

靜態 是
參数 無
回傳 字串
範例 
// 輸出 javascript 函式
echo Security::js_set_token();

// 你使用產生的函式做为 onsubmit 函式，像这樣。
// 不要忘記 'this' 參数，如此該函式知道要更新哪張表单！
<form onsubmit="fuel_set_csrf_token(this);">
	<!-- 在这裡做你的東西 -->
</form>

generate_token()

generate_token 方法能让你產生一个安全符記。 此方法是用來產生 CSRF 符記，但可用在你应用程序裡， 任何需要安全隨機符記的地方。

靜態 是
參数 無
回傳 字串
範例 
$token = Security::generate_token();

clean($value, $filters = null)

clean 方法能让你使用提供的過濾器來淨化資料。

靜態 是
參数
參数 預設 描述
$value 必要 要被淨化的值。这可以是一个字串值，或一个字串值的陣列。
$filters 
null
 要被用來淨化字串的過濾器。過濾器可以是单一值，或一个值的陣列。每个值必須是有效的 PHP 回呼（callback）。 你可能指定函式 ('htmlentities')、物件 ($this)、或靜態方法 ('Classname::method')。
回傳 字串
範例 
// 首先剝離标籤，在剩餘的資料中轉換 HTML 實體，并且使用我們的特別淨化解決方案完成它
$filters = array('strip_tags', 'htmlentities', '\\cleaners\\soap::clean');
$text = Security::clean($text, $filters);

strip_tags($value)

strip_tags 方法能让你從一个字串剝離 HTML 和 PHP 标籤。

靜態 是
參数
參数 預設 描述
$value 必要 輸入的字串。
回傳 字串
範例 
$text = '<p>Test paragraph.</p>';
$text = Security::strip_tags($text);

xss_clean($value, array $options = array())

xss_clean 方法能让你從一个字串剝離危險的 HTML 标籤，使用 HTMLawed 函式庫。

靜態 是
參数
參数 預設 描述
$value 必要 輸入的字串。
$options 
array()
 給 htmLawed 的選擇性配置陣列，如果你需要自訂淨化規則。
回傳 字串
範例 
$text = '<SCRIPT>alert("XSS attack!")</SCRIPT>';
$text = Security::xss_clean($text);

htmlentities($value, $flags = null, $encoding = null, $double_encode = null)

htmlentities 方法能让你轉化 HTML 字元为他們相等的實體。此方法與 PHP 的 htmlentities() 函式操作一致， 但也支援陣列及物件。

靜態 是
參数
參数 預設 描述
$value 必要 輸入的值。
$flags 
null
 要傳遞給 htmlentities() 的标誌。如果沒給也沒配置，它将預設是 ENT_QUOTES。
$encoding 
null
 用於傳遞值的编码。如果沒給它預設将使用 FuelPHP 的預設编码。
$double_encoding 
null
 如果为 true，已经编码的值将不会再次被编码。如果沒給或沒配置，它将預設是 false。
回傳 混合
拋出 RuntimeException，在物件已经被傳遞且不能被轉換为字串的情況下。
範例 
$text = '<p>Test paragraph.</p>';
$text = Security::htmlentities($text);

程序助手

e($string)

e 函式是 Security::htmlentities 的別名。

參数
參数 預設 描述
$string 必要 輸入的值。
回傳 字串，來自 Security::htmlentities
範例 
$text = '<p>Test paragraph.</p>';
$text = e($text);