Validation Class

The Validation class helps you validate user input, if you want to create a form & its validation at the same time use the Fieldset class instead.

Class Methods

forge($fieldset = 'default')

The forge method returns a new Validation instance, and links it with a Fieldset with name $fieldset.

Static Yes
Parameters
Param Type Default Description
$fieldset string | Fieldset 
'default'
 The name or instance of the Fieldset to link to.
Returns Validation object
Throws \DomainException, when the Fieldset name or instance already has a related Validation instance.
Example 
// Create a new validation instance
$val = Validation::forge();

// Associate the new Validation instance with a Fieldset, using the fieldset name
$val = Validation::forge('my_fieldset');

// Associate the new Validation instance with a Fieldset, by passing the fieldset instance
$fieldset = Fieldset::instance('my_fieldset');
$val = Validation::forge($fieldset);

instance($name = null)

The instance method returns the Validation instance related with the Fieldset instance with the identifier $name, or the default Fieldset (is created if necessary).

Static Yes
Parameters
Param Type Default Description
$name string 
null
 The name of the Fieldset whose Validation instance you want to return.
Returns Validation object
or false if the specified Fieldset instance doesn't exist
Example 
// Get the Validation instance of the default Fieldset
$val = Validation::instance();

// Get the Validation instance of a particular Fieldset
$val = Validation::instance('my_fieldset');

active()

The active method returns the currently active validation instance.

Static Yes
Parameters None
Returns Validation - currently active validation instance
Example 
// Get the currently active validation instance
$val = Validation::active();

active_field()

The active_field method returns the field currently being validated.

Static Yes
Parameters None
Returns Fieldset_Field - the field currently being validated
Example 
// Get the field currently being validated
$field = Validation::active_field();

fieldset()

The fieldset method returns the related Fieldset.

Static No
Parameters None
Returns Fieldset - the related Fieldset
Example 
// Get the related Fieldset
$val = Validation::forge('my_fieldset');
$fieldset = $val->fieldset();

add_field($name, $label, $rules)

The add_field method is a simpler alias for add() method which allows specifying the field name, label and rules in a single step.

Static No
Parameters
Param Type Default Description
$name string 
None
 The field name to assign the validation rule to.
$label string 
None
 Label of the field.
$rules mixed 
None
 The set of validation rules with (optional) rule parameters grouped in square brackets, and separated with commas. It can be passed as a string where the rules are separated with a vertical bar or pipe symbol (|), or as a array of rules.
Returns Fieldset_Field
Example 
// Set rules on different types of fields
$val->add_field('username', 'Username', 'required|trim|valid_string[alpha,lowercase,numeric]');
$val->add_field('email', 'Email', 'required|trim|valid_email');
$val->add_field('age', 'Age', 'valid_string[numeric]');

// as an array
$val->add_field('username', 'Username', array('required', 'trim', 'valid_string[alpha,lowercase,numeric]'));

set_message($rule, $message)

The set_message method overwrites the language file messages for this validation instance. It's also useful when no message is assigned to the rule you're using.

Static No
Parameters
Param Type Default Description
$rule string 
None
 Name of the rule to assign this message to.
$message string | null 
None
 The message to display for this rule, if a string is passed, or null to revert to the language file.
Returns Validation instance
Example 
// Overwrite the required rule message
$val->set_message('required', 'You have to fill in your :label so you can proceed');
// .. when done, set back the default message
$val->set_message('required', null);
// A message for a custom rule you created
$val->set_message('custom_rule', 'The :label you entered is previously registered. Please choose another one');

get_message($rule)

The get_message method fetches a specific error message for this validation instance. Only messages set through the set_message method are returned.

Static No
Parameters
Param Type Default Description
$rule string 
None
 Name of the rule of which you need to get the message.
Returns string
Example 
// Overwrite the required rule message
$val->set_message('custom_rule', 'The :label you entered is previously registered. Please choose another one');
// .. later, or some where else in your code, get this message
$val->get_message('required', null);

add_callable($class)

The add_callable method adds a set of custom or extended validation rules. You don't need to write a full callback, just the class name as a string will do. This also allows for overwriting functionality from this object because the new class is prepended.

Static No
Parameters
Param Type Default Description
$class string|Object 
None
 Name of the class as string, or object name
Returns Validation instance
Example 

$val->add_callable('myvalidation');

Check the Extending the Validation class for a complete example of using this method, and the required class.

remove_callable($class)

The remove_callable method removes a callable from the callables array.

Static No
Parameters
Param Type Default Description
$class string|Object 
None
 Name of the class as string, or object name
Returns Validation instance
Example 
$val->remove_callable('myvalidation');

callables()

The callables method fetches the objects for which you don't need to add a full callback but just the method name

Static No
Parameters None
Returns array

run($input = null, $allow_partial = false, $temp_callables = array())

Runs the defined validation rules against the input passed, or Input::post() if nothing was passed.

Static No
Parameters
Param Type Default Description
$input array 
null
 Assoc array of input fields and values
$allow_partial bool 
false
 If false, all fields that have validation rules defined MUST be present in the input
$temp_callables array 
array()
 Any additional callables required to run all defined validation rules
Returns Boolean, true if the input validated, false if it failed
Example 
$val = Validation::forge('article');
$val->add_field('title', 'Title', 'required');

if ( ! $val->run())
{
    foreach ($val->error() as $field => $error)
    {
        echo $error->get_message();
        // The field Title is required and must contain a value.
    }
}

input($key = null, $default = null)

Returns one or all input values, or the default value if the requested key is not present in the input.

Static No
Parameters
Param Type Default Description
$key string 
null
 Name of the input field, or null to return all input
$default mixed 
null
 Value to return if the key is not present in the input
Returns Mixed, the input value or the value specified as $default
Example 
$val = Validation::forge('article');
$val->add_field('title', 'Title', 'required');

if ($val->run())
{
    // if something was posted, echo it
    echo $val->input('title');
}

Input is only available after the validation rules have run. By default, input() will fall back to Input::param() when no rules have run. This behaviour can be controlled through the validation config file.

validated($field = null, $default = false)

Returns one or all validated input values, or the default value if the requested key is not present in the validated input.

Static No
Parameters
Param Type Default Description
$field string 
null
 Name of the input field, or null to return all input
$default mixed 
null
 Value to return if the key is not present in the input
Returns Mixed, the validated input value or the value specified as $default
Example 
$val = Validation::forge('article');
$val->add_field('title', 'Title', 'required');

if ($val->run())
{
    // if something was posted, echo it
    echo $val->validated('title');
}

Where input() returns the raw input value, validated() will return the validated value, which might be different than the input because some validation rules alter the input (for example a rule like strtoupper).

error($field = null, $default = false)

The error method returns specific error or all errors that occur during validation.

Static No
Parameters
Param Type Default Description
$field string 
null
 The fieldname of the Validation_Error instance you want to return. If you don't specify the fieldname, then returns all error objects.
$default mixed 
false
 If an error of the specified field does not exist, returns this value.
Returns Validation_Error instance
or array if you don't specify the fieldname
Example 
$val = Validation::forge('article');
$val->add_field('title', 'Title', 'required');

if ( ! $val->run(array()))
{
    foreach ($val->error() as $field => $error)
    {
        echo $error->get_message();
        // The field Title is required and must contain a value.
    }
}

error_message($field = null, $default = false)

The error_message method returns specific error message or all error messages that occur during validation.

Static No
Parameters
Param Type Default Description
$field string 
null
 The fieldname of the error message you want to return. If you don't specify the fieldname, then returns all error messages.
$default string 
false
 If an error of the specified field does not exist, returns this value.
Returns string
or array if you don't specify the fieldname
Example 
$val = Validation::forge('article');
$val->add_field('title', 'Title', 'required');

if ( ! $val->run(array()))
{
    foreach ($val->error_message() as $field => $message)
    {
        echo $message;
        // The field Title is required and must contain a value.
    }
}

show_errors($options = array())

The show_errors returns the list of validation errors rendered in HTML according to the defined template.

Static No
Parameters
Param Type Default Description
$options array 
array()
 Options for the HTML template, to override the defaults from the validation config file
Returns string, the rendered HTML
Example 
$val = Validation::forge('article');
$val->add_field('title', 'Title', 'required');

if ( ! $val->run(array()))
{
    echo $val->show_errors();
}

The following options can be passed: 'open_list', 'close_list', 'open_error', 'close_error' and 'no_errors'. By default an unordered list is generated, and an empty string is returned if no validation errors were found.