Merge branch 'master' of git@github.com:gallery/gallery3

1 files changed, 103 insertions, 16 deletions

diff --git a/system/helpers/valid.php b/system/helpers/valid.php
index cffcd7c0..1f7be223 100644
--- a/system/helpers/valid.php
+++ b/system/helpers/valid.php
@@ -1,10 +1,36 @@
 <?php defined('SYSPATH') OR die('No direct access allowed.');
 /**
- * Validation helper class.
+ * The Valid Helper provides functions to help validate data. They can be used as standalone static functions or
+ * as rules for the Validation Library.
  *
- * $Id: valid.php 4679 2009-11-10 01:45:52Z isaiah $
+ * ###### Validation Library Example:
+ *     $data = new Validation($_POST);
+ *     $data->add_rules('phone', 'required', 'valid::phone[7, 10, 11, 14]')
  *
- * @package    Core
+ *     if ($data->validate())
+ *     {
+ *         echo 'The phone number is valid';
+ *     }
+ *     else
+ *     {
+ *         echo Kohana::debug($data->errors());
+ *     }
+ *
+ * [!!] The *valid::* part of the rule is optional, but is recommended to avoid conflicts with php functions.
+ *
+ * For more informaiton see the [Validation] Library.
+ *
+ * ###### Standalone Example:
+ *     if (valid::phone($_POST['phone'], array(7, 10, 11, 14))
+ *     {
+ *         echo 'The phone number is valid';
+ *     }
+ *     else
+ *     {
+ *         echo 'Not valid';
+ *     }
+ *
+ * @package    Kohana
  * @author     Kohana Team
  * @copyright  (c) 2007-2009 Kohana Team
  * @license    http://kohanaphp.com/license
@@ -12,9 +38,20 @@
 class valid_Core {
 
 	/**
-	 * Validate email, commonly used characters only
+	 * Validate an email address. This method is more strict than valid::email_rfc();
 	 *
-	 * @param   string   email address
+	 * ###### Example:
+	 *     $email = 'bill@gates.com';
+	 *     if (valid::email($email))
+	 *     {
+	 *         echo "Valid email";
+	 *     }
+	 *     else
+	 *     {
+	 *         echo "Invalid email";
+	 *     }
+	 *
+	 * @param   string   A email address
 	 * @return  boolean
 	 */
 	public static function email($email)
@@ -26,6 +63,8 @@ class valid_Core {
 	 * Validate the domain of an email address by checking if the domain has a
 	 * valid MX record.
 	 *
+	 * [!!] This function will always return `TRUE` if the checkdnsrr() function isn't avaliable (All Windows platforms before php 5.3)
+	 *
 	 * @param   string   email address
 	 * @return  boolean
 	 */
@@ -41,8 +80,7 @@ class valid_Core {
 	}
 
 	/**
-	 * Validate email, RFC compliant version
-	 * Note: This function is LESS strict than valid_email. Choose carefully.
+	 * RFC compliant email validation. This function is __LESS__ strict than [valid::email]. Choose carefully.
 	 *
 	 * @see  Originally by Cal Henderson, modified to fit Kohana syntax standards:
 	 * @see  http://www.iamcal.com/publish/articles/php/parsing_email/
@@ -70,7 +108,18 @@ class valid_Core {
 	}
 
 	/**
-	 * Validate URL
+	 * Basic URL validation.
+	 *
+	 * ###### Example:
+	 *     $url = 'http://www.kohanaphp.com';
+	 *     if (valid::url($url))
+	 *     {
+	 *         echo "Valid url";
+	 *     }
+	 *     else
+	 *     {
+	 *         echo "Invalid url";
+	 *     }
 	 *
 	 * @param   string   URL
 	 * @return  boolean
@@ -81,7 +130,9 @@ class valid_Core {
 	}
 
 	/**
-	 * Validate IP
+	 * Validates an IP Address. This only tests to see if the ip address is valid,
+	 * it doesn't check to see if the ip address is actually in use. Has optional support for
+	 * IPv6, and private ip address ranges.
 	 *
 	 * @param   string   IP address
 	 * @param   boolean  allow IPv6 addresses
@@ -102,8 +153,19 @@ class valid_Core {
 	}
 
 	/**
-	 * Validates a credit card number using the Luhn (mod10) formula.
-	 * @see http://en.wikipedia.org/wiki/Luhn_algorithm
+	 * Validates a credit card number using the [Luhn (mod10)](http://en.wikipedia.org/wiki/Luhn_algorithm)
+	 * formula.
+	 *
+	 * ###### Example:
+	 *     $cc_number = '4111111111111111';
+	 *     if (valid::credit_card($cc_number, array('visa', 'mastercard')))
+	 *     {
+	 *         echo "Valid number";
+	 *     }
+	 *     else
+	 *     {
+	 *         echo "Invalid number";
+	 *     }
 	 *
 	 * @param   integer       credit card number
 	 * @param   string|array  card type, or an array of card types
@@ -178,7 +240,19 @@ class valid_Core {
 	}
 
 	/**
-	 * Checks if a phone number is valid.
+	 * Checks if a phone number is valid. This function will strip all non-digit
+	 * characters from the phone number for testing.
+	 *
+	 * ###### Example:
+	 *     $phone_number = '(201) 664-0274';
+	 *     if (valid::phone($phone_number))
+	 *     {
+	 *         echo "Valid phone number";
+	 *     }
+	 *     else
+	 *     {
+	 *         echo "Invalid phone number";
+	 *     }
 	 *
 	 * @param   string   phone number to check
 	 * @return  boolean
@@ -198,7 +272,8 @@ class valid_Core {
 	}
 
 	/**
-	 * Tests if a string is a valid date string.
+	 * Tests if a string is a valid date using the php
+	 * [strtotime()](http://php.net/strtotime) function
 	 *
 	 * @param   string   date to check
 	 * @return  boolean
@@ -266,9 +341,8 @@ class valid_Core {
 
 	/**
 	 * Checks whether a string is a valid number (negative and decimal numbers allowed).
-	 *
-	 * @see Uses locale conversion to allow decimal point to be locale specific.
-	 * @see http://www.php.net/manual/en/function.localeconv.php
+	 * This function uses [localeconv()](http://www.php.net/manual/en/function.localeconv.php)
+	 * to support international number formats.
 	 *
 	 * @param   string   input string
 	 * @return  boolean
@@ -318,6 +392,19 @@ class valid_Core {
 	 * 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.
 	 *
+	 * ###### Example:
+	 *     $decimal = '4.5';
+	 *     if (valid::decimal($decimal, array(2,1)))
+	 *     {
+	 *         echo "Valid decimal";
+	 *     }
+	 *     else
+	 *     {
+	 *         echo "Invalid decimal";
+	 *     }
+	 *     
+	 *     Output: Invalid decimal
+	 *
 	 * @param   string   input string
 	 * @param   array    decimal format: y or x,y
 	 * @return  boolean