^Status|Draft|
^Todo|document xss_clean|


====== Input Library ======

The input library is useful for two things:
- pre-process global input for security
- provide some useful functions for retrieving input data

**Note**:
  * The **$_REQUEST** and **$_GLOBAL** variables are not available within Kohana. 
  * $_POST, $_GET, $_COOKIE and $_SERVER are all converted to utf-8.
  * Global GET, POST and COOKIE data are sanitized when the Input library is loaded


===== Loading the library =====

This library is automatically loaded by the controller so you don't need to load it yourself.
It is accessed by ''$this->input'' in the controller scope.

===== Methods =====

==== get() ====
allows you to retrieve GET variables. if global XSS filtering is on (config) then data returned by this function will be filtered.

''$this->input->get($key = array(), $default = NULL, $xss_clean = FALSE)''
  * **[string]** ''$key'' variable to retrieve -- default = empty array (returns all variables)
  * **[mixed]** ''$default'' default value if the variable isn't set
  * **[boolean]** ''$xss_clean'' whether or not to manually apply xss clean

<code php>
//URL is http://www.example.com/index.php?articleId=123&file=text.txt
//Note that print statements are for documentation purpose only

print Kohana::debug($this->input->get());
print Kohana::debug($this->input->get('file'));
</code>
It will result in HTML as:
<code html>
Array
(
    [articleId] => 123
    [file] => text.txt
)

text.txt
</code>

You can also pass a default value and manually XSS clean the request by passing parameters.

<code php>

$this->input->get('file','default_value'); //'default_value' is the default value if the key doesn't exist.
$this->input->get('file',null,true); //manually apply XSS clean

</code>


==== post() ====
allows you to retrieve POST variables. if global XSS filtering is on (config) then data returned by this function will be filtered.

''$this->input->post($key = array(), $default = NULL, $xss_clean = FALSE)''
  * **[string]** ''$key'' variable to retrieve -- default = empty array (returns all variables)
  * **[mixed]** ''$default'' default value if the variable isn't set
  * **[boolean]** ''$xss_clean'' whether or not to manually apply xss clean

<code php>
//POST variables are articleId=123 and file=text.txt
//Note that print statements are for documentation purpose only

print Kohana::debug($this->input->post());
print Kohana::debug($this->input->post('file'));
</code>
It will result in HTML as:
<code html>
Array
(
    [articleId] => 123
    [file] => text.txt
)

text.txt
</code>

You can also pass a default value and manually XSS clean the request by passing parameters.

<code php>

$this->input->post('file','default_value'); //'default_value' is the default value if the key doesn't exist.
$this->input->post('file',null,true); //manually apply XSS clean

</code>

==== cookie() ====
allows you to retrieve COOKIE variables. if global XSS filtering is on (config) then data returned by this function will be filtered.
  * [string] variable to retrieve -- default = empty array (returns all variables)

<code php>
//COOKIE name is "username" and the contents of this cookie is "aart-jan".
//Note that print statements are for documentation purpose only

print Kohana::debug($this->input->cookie());
print Kohana::debug($this->input->cookie('username'));
</code>
It will result in HTML as:
<code html>
Array
(
    [username] => aart-jan
)
aart-jan
</code>

You can also pass a default value and manually XSS clean the request by passing parameters.

<code php>

$this->input->cookie('username','default_value'); //'default_value' is the default value if the key doesn't exist.
$this->input->cookie('username',null,true); //manually apply XSS clean

</code>


==== server() ====
allows you to retrieve SERVER variables. if global XSS filtering is on (config) then data returned by this function will be filtered. An overview of these variables can be found in the [[http://nl2.php.net/manual/en/reserved.variables.server.php|php documentation]]
  * [string] variable to retrieve -- default = empty array (returns all variables)

<code php>
//Note that print statements are for documentation purpose only
print Kohana::debug($this->input->server('HTTP_HOST')); //this example ran on a local server
</code>
It will result in HTML as:
<code html>
localhost
</code>

You can also pass a default value and manually XSS clean the request by passing parameters.

<code php>

$this->input->server('HTTP_HOST','default_value'); //'default_value' is the default value if the key doesn't exist.
$this->input->server('HTTP_HOST',null,true); //manually apply XSS clean

</code>

==== ip_address() ====
'ip_address' returns the IP-address of the user visiting using your webapplication. 
It returns '0.0.0.0' if there's no IP.
<code php>
print $this->input->ip_address(); //this example ran on a local server
</code>
It will result in HTML as:
<code html>
127.0.0.1
</code>

==== valid_ip() ====
'valid_ip' will check whether the specified IP is a valid IPV4 ip-address according to the RFC specifications.
  * [string] IP address to be validated
This function is identical to the [[helpers:valid#ip()|IP address validation helper]].

==== xss_clean() ====

allows you to clean a string to make sure it is safe.

  * [string/array] The string or the array of strings to clean

<code php>
echo $this->input->xss_clean($suspect_input);
</code>