Modules

Kohana_Validation
extends ArrayObject

Implements: Countable | Serializable | ArrayAccess | Traversable | IteratorAggregate

Array and variable validation.

package
Kohana
category
Security
author
Kohana Team
copyright
© 2008-2012 Kohana Team
license
http://kohanaframework.org/license

Class declared in SYSPATH/classes/kohana/validation.php on line 11.

Constants

STD_PROP_LIST

integer 1

ARRAY_AS_PROPS

integer 2

Properties

protected $_bound

protected $_empty_rules

protected $_errors

protected $_labels

protected $_rules

Methods

public __construct( array $array ) (defined in Kohana_Validation)

Sets the unique "any field" key and creates an ArrayObject from the passed array.

Parameters

  • array $array required - Array to validate

Return Values

  • void

Source Code

public function __construct(array $array)
{
	parent::__construct($array, ArrayObject::STD_PROP_LIST);
}

public as_array( ) (defined in Kohana_Validation)

Returns the array representation of the current object.

Return Values

  • array

Source Code

public function as_array()
{
	return $this->getArrayCopy();
}

public bind( string $key [, mixed $value = NULL ] ) (defined in Kohana_Validation)

Bind a value to a parameter definition.

// This allows you to use :model in the parameter definition of rules
$validation->bind(':model', $model)
    ->rule('status', 'valid_status', array(':model'));

Parameters

  • string $key required - Variable name or an array of variables
  • mixed $value = NULL - Value

Return Values

  • $this

Source Code

public function bind($key, $value = NULL)
{
	if (is_array($key))
	{
		foreach ($key as $name => $value)
		{
			$this->_bound[$name] = $value;
		}
	}
	else
	{
		$this->_bound[$key] = $value;
	}

	return $this;
}

public check( ) (defined in Kohana_Validation)

Executes all validation rules. This should typically be called within an if/else block.

if ($validation->check())
{
     // The data is valid, do something here
}

Return Values

  • boolean

Source Code

public function check()
{
	if (Kohana::$profiling === TRUE)
	{
		// Start a new benchmark
		$benchmark = Profiler::start('Validation', __FUNCTION__);
	}

	// New data set
	$data = $this->_errors = array();

	// Store the original data because this class should not modify it post-validation
	$original = $this->getArrayCopy();

	// Get a list of the expected fields
	$expected = Arr::merge(array_keys($original), array_keys($this->_labels));

	// Import the rules locally
	$rules     = $this->_rules;

	foreach ($expected as $field)
	{
		// Use the submitted value or NULL if no data exists
		$data[$field] = Arr::get($this, $field);

		if (isset($rules[TRUE]))
		{
			if ( ! isset($rules[$field]))
			{
				// Initialize the rules for this field
				$rules[$field] = array();
			}

			// Append the rules
			$rules[$field] = array_merge($rules[$field], $rules[TRUE]);
		}
	}

	// Overload the current array with the new one
	$this->exchangeArray($data);

	// Remove the rules that apply to every field
	unset($rules[TRUE]);

	// Bind the validation object to :validation
	$this->bind(':validation', $this);

	// Execute the rules
	foreach ($rules as $field => $set)
	{
		// Get the field value
		$value = $this[$field];

		// Bind the field name and value to :field and :value respectively
		$this->bind(array
		(
			':field' => $field,
			':value' => $value,
		));

		foreach ($set as $array)
		{
			// Rules are defined as array($rule, $params)
			list($rule, $params) = $array;

			foreach ($params as $key => $param)
			{
				if (is_string($param) AND array_key_exists($param, $this->_bound))
				{
					// Replace with bound value
					$params[$key] = $this->_bound[$param];
				}
			}

			// Default the error name to be the rule (except array and lambda rules)
			$error_name = $rule;

			if (is_array($rule))
			{
				// This is an array callback, the method name is the error name
				$error_name = $rule[1];
				$passed = call_user_func_array($rule, $params);
			}
			elseif ( ! is_string($rule))
			{
				// This is a lambda function, there is no error name (errors must be added manually)
				$error_name = FALSE;
				$passed = call_user_func_array($rule, $params);
			}
			elseif (method_exists('Valid', $rule))
			{
				// Use a method in this object
				$method = new ReflectionMethod('Valid', $rule);

				// Call static::$rule($this[$field], $param, ...) with Reflection
				$passed = $method->invokeArgs(NULL, $params);
			}
			elseif (strpos($rule, '::') === FALSE)
			{
				// Use a function call
				$function = new ReflectionFunction($rule);

				// Call $function($this[$field], $param, ...) with Reflection
				$passed = $function->invokeArgs($params);
			}
			else
			{
				// Split the class and method of the rule
				list($class, $method) = explode('::', $rule, 2);

				// Use a static method call
				$method = new ReflectionMethod($class, $method);

				// Call $Class::$method($this[$field], $param, ...) with Reflection
				$passed = $method->invokeArgs(NULL, $params);
			}

			// Ignore return values from rules when the field is empty
			if ( ! in_array($rule, $this->_empty_rules) AND ! Valid::not_empty($value))
				continue;

			if ($passed === FALSE AND $error_name !== FALSE)
			{
				// Add the rule to the errors
				$this->error($field, $error_name, $params);

				// This field has an error, stop executing rules
				break;
			}
		}
	}

	// Restore the data to its original form
	$this->exchangeArray($original);

	if (isset($benchmark))
	{
		// Stop benchmarking
		Profiler::stop($benchmark);
	}

	return empty($this->_errors);
}

public copy( array $array ) (defined in Kohana_Validation)

Copies the current rule to a new array.

$copy = $array->copy($new_data);

Parameters

  • array $array required - New data set

Tags

  • Since - 3.0.5

Return Values

  • Validation

Source Code

public function copy(array $array)
{
	// Create a copy of the current validation set
	$copy = clone $this;

	// Replace the data set
	$copy->exchangeArray($array);

	return $copy;
}

public error( string $field , string $error [, array $params = NULL ] ) (defined in Kohana_Validation)

Add an error to a field.

Parameters

  • string $field required - Field name
  • string $error required - Error message
  • array $params = NULL - $params

Return Values

  • $this

Source Code

public function error($field, $error, array $params = NULL)
{
	$this->_errors[$field] = array($error, $params);

	return $this;
}

public errors( [ string $file = NULL , mixed $translate = bool TRUE ] ) (defined in Kohana_Validation)

Returns the error messages. If no file is specified, the error message will be the name of the rule that failed. When a file is specified, the message will be loaded from "field/rule", or if no rule-specific message exists, "field/default" will be used. If neither is set, the returned message will be "file/field/rule".

By default all messages are translated using the default language. A string can be used as the second parameter to specified the language that the message was written in.

// Get errors from messages/forms/login.php
$errors = $Validation->errors('forms/login');

Parameters

  • string $file = NULL - File to load error messages from
  • mixed $translate = bool TRUE - Translate the message

Tags

Return Values

  • array

Source Code

public function errors($file = NULL, $translate = TRUE)
{
	if ($file === NULL)
	{
		// Return the error list
		return $this->_errors;
	}

	// Create a new message list
	$messages = array();

	foreach ($this->_errors as $field => $set)
	{
		list($error, $params) = $set;

		// Get the label for this field
		$label = $this->_labels[$field];

		if ($translate)
		{
			if (is_string($translate))
			{
				// Translate the label using the specified language
				$label = __($label, NULL, $translate);
			}
			else
			{
				// Translate the label
				$label = __($label);
			}
		}

		// Start the translation values list
		$values = array(
			':field' => $label,
			':value' => Arr::get($this, $field),
		);

		if (is_array($values[':value']))
		{
			// All values must be strings
			$values[':value'] = implode(', ', Arr::flatten($values[':value']));
		}

		if ($params)
		{
			foreach ($params as $key => $value)
			{
				if (is_array($value))
				{
					// All values must be strings
					$value = implode(', ', Arr::flatten($value));
				}
				elseif (is_object($value))
				{
					// Objects cannot be used in message files
					continue;
				}

				// Check if a label for this parameter exists
				if (isset($this->_labels[$value]))
				{
					// Use the label as the value, eg: related field name for "matches"
					$value = $this->_labels[$value];

					if ($translate)
					{
						if (is_string($translate))
						{
							// Translate the value using the specified language
							$value = __($value, NULL, $translate);
						}
						else
						{
							// Translate the value
							$value = __($value);
						}
					}
				}

				// Add each parameter as a numbered value, starting from 1
				$values[':param'.($key + 1)] = $value;
			}
		}

		if ($message = Kohana::message($file, "{$field}.{$error}"))
		{
			// Found a message for this field and error
		}
		elseif ($message = Kohana::message($file, "{$field}.default"))
		{
			// Found a default message for this field
		}
		elseif ($message = Kohana::message($file, $error))
		{
			// Found a default message for this error
		}
		elseif ($message = Kohana::message('validation', $error))
		{
			// Found a default message for this error
		}
		else
		{
			// No message exists, display the path expected
			$message = "{$file}.{$field}.{$error}";
		}

		if ($translate)
		{
			if (is_string($translate))
			{
				// Translate the message using specified language
				$message = __($message, $values, $translate);
			}
			else
			{
				// Translate the message using the default language
				$message = __($message, $values);
			}
		}
		else
		{
			// Do not translate, just replace the values
			$message = strtr($message, $values);
		}

		// Set the message for this field
		$messages[$field] = $message;
	}

	return $messages;
}

public static factory( array $array ) (defined in Kohana_Validation)

Creates a new Validation instance.

Parameters

  • array $array required - Array to use for validation

Return Values

  • Validation

Source Code

public static function factory(array $array)
{
	return new Validation($array);
}

public label( string $field , string $label ) (defined in Kohana_Validation)

Sets or overwrites the label name for a field.

Parameters

  • string $field required - Field name
  • string $label required - Label

Return Values

  • $this

Source Code

public function label($field, $label)
{
	// Set the label for this field
	$this->_labels[$field] = $label;

	return $this;
}

public labels( array $labels ) (defined in Kohana_Validation)

Sets labels using an array.

Parameters

  • array $labels required - List of field => label names

Return Values

  • $this

Source Code

public function labels(array $labels)
{
	$this->_labels = $labels + $this->_labels;

	return $this;
}

public rule( string $field , callback $rule [, array $params = NULL ] ) (defined in Kohana_Validation)

Overwrites or appends rules to a field. Each rule will be executed once. All rules must be string names of functions method names. Parameters must match the parameters of the callback function exactly

Aliases you can use in callback parameters: - :validation - the validation object - :field - the field name - :value - the value of the field

// The "username" must not be empty and have a minimum length of 4
$validation->rule('username', 'not_empty')
           ->rule('username', 'min_length', array(':value', 4));

// The "password" field must match the "password_repeat" field
$validation->rule('password', 'matches', array(':validation', 'password', 'password_repeat'));

Parameters

  • string $field required - Field name
  • callback $rule required - Valid PHP callback
  • array $params = NULL - Extra parameters for the rule

Return Values

  • $this

Source Code

public function rule($field, $rule, array $params = NULL)
{
	if ($params === NULL)
	{
		// Default to array(':value')
		$params = array(':value');
	}

	if ($field !== TRUE AND ! isset($this->_labels[$field]))
	{
		// Set the field label to the field name
		$this->_labels[$field] = preg_replace('/[^\pL]+/u', ' ', $field);
	}

	// Store the rule and params for this rule
	$this->_rules[$field][] = array($rule, $params);

	return $this;
}

public rules( string $field , array $rules ) (defined in Kohana_Validation)

Add rules using an array.

Parameters

  • string $field required - Field name
  • array $rules required - List of callbacks

Return Values

  • $this

Source Code

public function rules($field, array $rules)
{
	foreach ($rules as $rule)
	{
		$this->rule($field, $rule[0], Arr::get($rule, 1));
	}

	return $this;
}

public append( ) (defined in ArrayObject)

public asort( ) (defined in ArrayObject)

public count( ) (defined in ArrayObject)

public exchangeArray( ) (defined in ArrayObject)

public getArrayCopy( ) (defined in ArrayObject)

public getFlags( ) (defined in ArrayObject)

public getIterator( ) (defined in ArrayObject)

public getIteratorClass( ) (defined in ArrayObject)

public ksort( ) (defined in ArrayObject)

public natcasesort( ) (defined in ArrayObject)

public natsort( ) (defined in ArrayObject)

public offsetExists( ) (defined in ArrayObject)

public offsetGet( ) (defined in ArrayObject)

public offsetSet( ) (defined in ArrayObject)

public offsetUnset( ) (defined in ArrayObject)

public serialize( ) (defined in ArrayObject)

public setFlags( ) (defined in ArrayObject)

public setIteratorClass( ) (defined in ArrayObject)

public uasort( ) (defined in ArrayObject)

public uksort( ) (defined in ArrayObject)

public unserialize( ) (defined in ArrayObject)