^Status|Draft|
^Todo|check grammar, enhance explanations and layout|


====== Valid Helper ======
Provides methods for validating inputs. It currently features validation for email-addresses, ip's, url's, digits/numbers and text. 

This helper provides functions for doing validation using the [[libraries/validation|validation library]].

===== Methods =====

==== email() ====

'email' checks whether an email address is valid. 
It is more strict than the valid::email_rfc() method.  
  * [string] Email address to validate
<code php>
    $email = 'bill@gates.com';
    if(valid::email($email) == true){
         echo "Valid email";
    }else{
         echo "Invalid email";
    }
</code>
It will result in HTML as:
<code html>
Valid email
</code>

==== email_domain() ====

'email_domain' validates the domain part of an email address by checking if the domain has a valid MX record.
  * [string] Email address to validate
<code php>
    $email = 'bill@gates.com';
    if(valid::email_domain($email) == true){
         echo "Valid email domain";
    }else{
         echo "Invalid email domain";
    }
</code>
It will result in HTML as:
<code html>
Valid email domain
</code>

<box red>
This function uses http://www.php.net/checkdnsrr which is not implemented on Windows platforms. So if your Kohana installation is running in Windows this function will return true no matter if the domain is valid or not.
A solution for this is to write your own checkdnsrr function. You can find an implementation here: http://www.php.net/manual/en/function.checkdnsrr.php#82701
</box>

==== email_rfc() ====

'email_rfc' validates an emailaddress based on the RFC specifications ([[http://www.w3.org/Protocols/rfc822/]]). 
This validation is **less** strict than the valid::email() function. 
  * [string] Email address to validate
<code php>
    $email = 'bill@gates.com';
    if(valid::email_rfc($email) == true){
         echo "Valid email";
    }else{
         echo "Invalid email";
    }
</code>
It will result in HTML as: 
<code html>
Valid email
</code>

==== url() ====

''url($url)'' does some simple validation on an URL to find out it if it //could// be existing. 
  * [string] URL to be validated
<code php>
    $url = 'http://www.kohanaphp.com';
    if(valid::url($url) == true){
         echo "Valid URL";
    }else{
         echo "Invalid URL";
    }
</code>
It will result in HTML as: 
<code html>
Valid URL
</code>

==== ip() ====

''ip($ip, $ipv6 = FALSE, $allow_private = TRUE)'' validates an IP-address to make sure it //could// exist, but does not guarantee it actually does. 
  * **[string]** //$ip// IP-address to be validated
  * **[bool]** //$ipv6// allow IPv6 addresses (default FALSE)
  * **[bool]** //$allow_private// allow [[http://en.wikipedia.org/wiki/IP_address#IPv4_private_addresses|private addresses]] (default TRUE)

<code php>
$ip="65.181.130.41";
if(valid::ip($ip) == true){
    echo "Valid IP";
}else{
    echo "Invalid IP";
}

$ip="123.456.678.912";
if(valid::ip($ip) == true){
    echo "Valid IP";
}else{
    echo "Invalid IP";

</code>

It will result in HTML as: 
<code html>
Valid IP
Invalid IP
</code>

==== credit_card() ====

'credit_card' checks if a credit card number is valid or not depending on the configuration defined on your credit_cards.php config file.
  * [string] Card number to be validated
  * [string|array] Card type, or an array of card types -- default = NULL
This method will check if the credit card number is valid taking into account the settings defined in the credits_cards.php config file. If nothing is passed as second parameter then the default type of the credits_cards.php config file will be used.
<code php>
$number = "4992739871600";
if(valid::credit_card($number)) {
    echo "Valid credit card number";
} else {
    echo "Invalid credit card number";
}
</code>
It will result in HTML as: 
<code html>
Valid credit card number
</code>

This method allows to pass as second argument an array of credit_cards type (which you define in the credit_cards.php config file). If you do so, the number will be considered valid if it matches with the specifications of at least one of the types added in the array.

Consider the following example:
<code php>
$number = "4992739871600";
$types = array(
    'default',
    'american express'
);
if(valid::credit_card($number, $types)) {
    echo "Valid credit card number";
} else {
    echo "Invalid credit card number";
}
</code>
It will result in HTML as: 
<code html>
Valid credit card number
</code>
Since the credit number passed as first argument matches at least the rules defined for the default type.

==== phone() ====

'phone' checks whether a phone number is valid or not. It strips all the characters which are not a digit from the string at the moment of the validation.
  * [string] The phone number to check
  * [array] Optional array containing the allowed lengths -- defaults = array(7,10,11)
<code php>
$phone = '+54 123-456 789';
if(valid::phone($phone) == true){
    echo "Valid phone number";
}else{
    echo "Invalid phone number";
}
</code>
It will result in HTML as:
<code html>
Valid phone number
</code>

==== date() ====
'date' checks whether a string is a valid date string.
  * [string] The date string to check.

<code php>
$date = '19th February 2009';
if (valid::date($date)) {
	echo "Valid date";
} else {
	echo "Invalid date";
}
</code>

It will result in HTML as:
<code>
Valid date 
</code>

====  alpha() ====

'alpha' checks whether a string consists of alphabetical characters only
  * [string] String to be validated
  * [boolean] If true UTF-8 mode will be used -- default = FALSE
<code php>
$string="KohanaPHP is cool";
if(valid::alpha($string) == true){
    echo "Valid string";
}else{
    echo "Invalid string";
}
</code>

It will result in HTML as: 
<code html>
Invalid string
</code>

<code php>
$string="KohanaPHPiscool";
if(valid::alpha($string) == true){
    echo "Valid string";
}else{
    echo "Invalid string";
}
</code>

It will result in HTML as: 
<code html>
Valid string
</code>


====  alpha_numeric() ==== 

'alpha_numeric' checks whether a string consists of alphabetical characters and numbers only
  * [string] String to be validated
  * [boolean] If true UTF-8 mode will be used -- default = FALSE
<code php>
$string="KohanaPHP Version 3 is cool";
if(valid::alpha_numeric($string) == true){
    echo "Valid string";
}else{
    echo "Invalid string";
}
</code>

It will result in HTML as: 
<code html>
Invalid string
</code>

<code php>
$string="KohanaPHPVersion2iscool";
if(valid::alpha_numeric($string) == true){
    echo "Valid string";
}else{
    echo "Invalid string";
}
</code>

It will result in HTML as: 
<code html>
Valid string
</code>


====  alpha_dash() ====

'alpha_dash' checks whether a string consists of alphabetical characters, numbers, underscores and dashes only
  * [string] String to be validated
  * [boolean] If true UTF-8 mode will be used -- default = FALSE
<code php>
$string="KohanaPHP Version 2 is cool";
if(valid::alpha_dash($string) == true){
    echo "Valid string";
}else{
    echo "Invalid string";
}
</code>

It will result in HTML as: 
<code html>
Invalid string
</code>

<code php>
$string="KohanaPHP_Version-2-is_cool";
if(valid::alpha_dash($string) == true){
    echo "Valid string";
}else{
    echo "Invalid string";
}
</code>

It will result in HTML as: 
<code html>
Valid string
</code>


====  digit() ====

'digit' checks whether a string consists of digits only (no dots or dashes)
  * [string] String to be validated
  * [boolean] If true UTF-8 mode will be used -- default = FALSE
<code php>
$digits = "23424.32";
if(valid::digit($digits) == true){
    echo "Valid";
}else{
    echo "Invalid";
}
</code>

It will result in HTML as: 
<code html>
Invalid
</code>

<code php>
$digits = "2342432";
if(valid::digit($digits) == true){
    echo "Valid";
}else{
    echo "Invalid";
}
</code>

It will result in HTML as: 
<code html>
Valid
</code>

====  numeric() ====

'numeric' checks whether a string is a valid number (negative and decimal numbers allowed). It supports international formats (ex. Spanish decimal format uses comma as separator). 

  * [string] the input string

<code php>
$number = "-23424.32";
if(valid::numeric($number) == true){
    echo "Valid";
}else{
    echo "Invalid";
}
</code>

It will result in HTML as: 
<code html>
Valid
</code>

==== standard_text() ====

'standard_text' checks whether a string is a valid text. Letters, numbers, whitespace, dashes (-), periods (.), underscores (_) and normal punctuation  are allowed.
  * [string] Text to be validated
<code php>
$text = 'this is not a valid text because of the : character';
if(valid::standard_text($text) == true){
    echo "Valid standard text";
}else{
    echo "Invalid standard text";
}
</code>

It will result in HTML as: 
<code html>
Invalid standard text
</code>

==== decimal() ====

'decimal' Checks if a string is a proper decimal format. The format array can be used to specify a decimal length, or a number and decimal length, eg:
	 * array(2) would force the number to have 2 decimal places, array(4,2)
	 * would force the number to have 4 digits and 2 decimal places.

  * [string] string to be validated
  * [array] decimal format: array(y) or array(x,y) - default NULL

<code php>
$decimal = '4.5';
if(valid::decimal($decimal) == true){
    echo "Valid decimal";
}else{
    echo "Invalid decimal";
}
</code>

It will result in HTML as: 
<code html>
Valid decimal
</code>

<code php>
$decimal = '4.5';
$format = array(2,1);
if(valid::decimal($decimal,$format) == true){
    echo "Valid decimal";
}else{
    echo "Invalid decimal";
}
</code>
It will result in HTML as: 

<code html>
Invalid decimal
</code>