Security Class

The security class allows you to have CSRF protection in your application.

Configuration

The security class is configured through the security section of the app/config/config.php configuration file.

The following security configuration settings can be defined:

Param Type Default Description
csrf_autoload boolean
true
When true, load and check the CSRF token using check_token() automatically.
csrf_token_key string
'fuel_csrf_token'
Name used for the CSRF token cookie, and the name of the form field containing the token.
csrf_expiration integer
0
Expiration time for the CRSF token cookie. Default, the cookie expires at end of browser session.
uri_filter array
array('htmlentities')
Array of callable items (PHP functions, object methods, static class methods) used to filter the URI. By default, it uses PHP's htmlentities internal function.
input_filter array
array()
Array of callable items (PHP functions, object methods, static class methods) used to filter $_GET, $_POST and $_COOKIE. By default, no input filters are defined.
output_filter array
array('Security::htmlentities')
Array of callable items (PHP functions, object methods, static class methods) used to filter variables send to a View or Viewmodel. For security reasons, you are required to define an output filter.
htmlentities_flags integer
null
Flags to be used when encoding HTML entities. Defaults to ENT_QUOTES if nothing is defined.
htmlentities_double_encode boolean
null
Whether of not already encoded entities should be encoded again. Defaults to false if nothing is defined.
auto_encode_view_data boolean
true
When true, all variables passed on to view objects are automatically encoded.
whitelisted_classes array
array('stdClass', 'Fuel\\Core\\View',
'Fuel\\Core\\ViewModel', 'Closure')
When auto encoding of view variables is enabled, you can run into issues when passing objects to the view. Classes defined in this array will be exempt from auto encoding.

check_token($value = null)

The check_token method allows you to check the CSRF token.
Check token also ensures a token is present and will reset the token for the next session when it receives a value to check (no matter the result of the check).

Static Yes
Parameters
Param Default Description
$value
null
CSRF token to be checked, checks value from POST when empty.
Returns boolean
Example
Security::check_token();

fetch_token()

The fetch_token method allows you to fetch the CSRF token from the cookie.

Static Yes
Parameters None
Returns string
Example
$csrf_token = Security::fetch_token();

js_fetch_token()

The js_fetch_token method allows you to produce JavaScript fuel_csrf_token() function that will return the current CSRF token when called. Use to fill right field on form submit for AJAX operations.

Static Yes
Parameters None
Returns string
Example
// output the javascript function
echo Security::js_fetch_token();

// you can now use the generated function in the javascript code on your page
<script type="text/javascript">
	var current_token = fuel_csrf_token();
</script>

js_set_token()

The js_set_token method allows you to produce JavaScript fuel_set_csrf_token() function that will set the current CSRF token field in the form when called. Use this on an onsubmit of a form, to update the hidden token field in the form with the current value of the csrf cookie.

Static Yes
Parameters None
Returns string
Example
// output the javascript function
echo Security::js_set_token();

// you use the function generated as an onsubmit function, like so.
// do NOT forget the 'this' parameter, so the function knows which form to update!
<form onsubmit="fuel_set_csrf_token(this);">
	<!-- do your stuff here -->
</form>

clean($value, $filters = null)

The clean method allows you clean data using the filters provided.

Static Yes
Parameters
Param Default Description
$value Required The value to be cleaned. This can be a string value, or an array of string values.
$filters
null
The filters to be used to clean the string(s). A filter can be a single value, or an array of values. Each value must be a valid PHP callback. You may specify functions ('htmlentities'), objects ($this), or static methods ('Classname::method').
Returns string
Example
// first strip tags, convert html entities in the remaining data, and finish it off using our special cleaning solution
$filters = array('strip_tags', 'htmlentities', '\\cleaners\\soap::clean');
$text = Security::clean($text, $filters);

strip_tags($value)

The strip_tags method allows you to strip HTML and PHP tags from a string.

Static Yes
Parameters
Param Default Description
$value Required The input string.
Returns string
Example
$text = '<p>Test paragraph.</p>';
$text = Security::strip_tags($text);

xss_clean($value)

The xss_clean method allows you to strip dangerous HTML tags from a string, using the HTMLawed library.

Static Yes
Parameters
Param Default Description
$value Required The input string.
Returns string
Example
$text = '<SCRIPT>alert("XSS attack!")</SCRIPT>';
$text = Security::xss_clean($text);

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

The htmlentities method allows you to turn HTML characters into their entity equivalent. This method operates identical to PHP's htmlentities() function but supports arrays and objects as well.

Static Yes
Parameters
Param Default Description
$value Required The input value.
$flags
null
Flags to be passed to htmlentities(). If not given and not configured, it will default to ENT_QUOTES.
$encoding
null
The encoding used for the value passed. If not given it will default the FuelPHP's default encoding.
$double_encoding
null
If true, already encoded values will not be encoded again. If not given and not configured it will default to false.
Returns mixed
Throws RuntimeException, in case an object has been passed that can't be cast as string.
Example
$text = '<p>Test paragraph.</p>';
$text = Security::htmlentities($text);

Procedural helpers

e($string)

The e function is an alias for Security::htmlentities.

Parameters
Param Default Description
$string required The input value.
Returns string, result from Security::htmlentities
Example
$text = '<p>Test paragraph.</p>';
$text = e($text);